passalong 0.13.1 → 0.15.0

package/README.md

@@ -5,13 +5,14 @@ Hand work to your AI coding agents, and get back what they did and how they chec
 Write a task, a bug or a finished change once. The agent that takes it starts knowing what done
 looks like and what was already decided, reports as it goes, and hands back a write-up with the
 evidence for each thing you asked for, which you approve or send back. One agent per job, and
-everyone can see who has what. Works with Claude Code, Cursor, Gemini, ChatGPT, or anything that
+everyone can see who has what. Works with Claude Code, Codex, ChatGPT, Claude, or anything that
 speaks MCP or HTTP. See [passalong.dev](https://passalong.dev).
 
 ```sh
 npm i -g passalong
 passalong setup      # installs the Claude Code capture skill + registers the MCP server
 passalong login      # optional: sync guides across machines and get share links
+codex mcp add passalong -- passalong mcp   # Codex: the same MCP server
 ```
 
 ## The loop
@@ -41,7 +42,11 @@ passalong archive <id>        off your board and out of the free tier's count (w
 passalong promote <id>        deprecated: mark promoted
 passalong rm <id>             delete a guide locally and from sync
 passalong export [dir]        dump every guide as plain markdown
-passalong login [token]       sign in with your email and password, or attach this machine with a token
+passalong login [token]       sign in from the browser, or attach this machine with a token
+passalong login --new         add another account to this machine
+passalong accounts            the accounts signed in here, and which is the default
+passalong use <name>          make one of them the default
+passalong logout <name>       forget one of them
 passalong me [--handle H] [--name N] [--email E]   who you are to teammates
 passalong team                current team and its members
 passalong team create <name>  start a team (you become its owner)
@@ -103,3 +108,15 @@ Plain markdown with frontmatter in `~/.passalong/guides`. Yours to edit, grep, a
 `passalong export` dumps everything. Works with no account; `passalong login` adds sync and share links.
 
 Point at a self-hosted server with `PASSALONG_API=https://your-host` before `passalong login`.
+
+## More than one account
+
+A machine can be signed in to several accounts, say a work one and a personal one.
+`passalong login --new` adds another beside the first, `passalong accounts` lists them, and
+`passalong use <name>` picks the default a person at a terminal gets.
+
+An agent has no terminal to be asked at, so with two or more accounts and nothing saying which, it
+is refused and told to ask you. It puts the question to you in plain words, you answer, and it calls
+`use_account` with the name. That lasts for the session and moves nothing on disk. From a shell,
+`--as <name>` or `PASSALONG_ACCOUNT=<name>` says the same for one command. The team you work in
+(`passalong team use`) belongs to the account, not the machine.

package/bin/passalong

@@ -39,7 +39,11 @@
 //   passalong archive <id>        off your board and out of the free tier's count (was `done`)
 //   passalong rm <id>             delete a guide locally and from sync
 //   passalong export [dir]        dump every guide as plain markdown (default ./passalong-export)
-//   passalong login [token]       sign in with your email and password, or attach this machine with a token
+//   passalong login [token]       sign in from the browser, or attach this machine with a token
+//   passalong login --new         add another account to this machine
+//   passalong accounts            the accounts signed in here, and which is the default
+//   passalong use <name>          make one of them the default
+//   passalong logout <name>       forget one of them
 //   passalong me [--handle H] [--name N] [--email E]   who you are to teammates
 //   passalong team                current team and its members
 //   passalong team create <name>  start a team (you become its owner)
@@ -51,7 +55,7 @@
 //   passalong mcp                 run the MCP server over stdio
 //   passalong version             print the installed version (also -v, --version)
 import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -94,6 +98,118 @@ const tty = process.stdout.isTTY && process.stdin.isTTY;
  * Written against readline rather than a dependency because this package has none beyond the MCP
  * SDK and zod, and asking for a line of text is not where that changes.
  */
+/** Open a page in the default browser, and say nothing if there is none to open. */
+function openPage(url) {
+  const [cmd, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { detached: true, stdio: "ignore" }).on("error", () => {}).unref();
+  } catch {}
+}
+
+/**
+ * Keep a login under a name, and say what that did. The first one on a machine is the default; one
+ * added beside it is not, because a default that changes by itself is how an agent ends up acting
+ * as the wrong person. A machine that has only the older single login gets that one named first,
+ * so adding a second does not lose it.
+ */
+async function keepLogin(token, base = api.baseUrl()) {
+  const who = await api.meWith(token, base).catch((e) => die(`token rejected: ${e.message}`));
+  const cfg = store.readConfig();
+  if (cfg.token && !cfg.accounts && cfg.token !== token) {
+    const old = await api.meWith(cfg.token, cfg.api || base).catch(() => null);
+    store.saveAccount(
+      { token: cfg.token, api: cfg.api || base, account: old?.account || "", handle: old?.handle || "", email: old?.email || "", team: cfg.team || "" },
+      { activate: true },
+    );
+  }
+  const before = Object.keys(store.readAccounts()).length;
+  const name = store.saveAccount(
+    { token, api: base, account: who.account, handle: who.handle || "", email: who.email || "" },
+    { activate: before === 0 },
+  );
+  if (!api.currentTeam() && who.teams?.length === 1) store.saveTeam(name, who.teams[0].slug);
+  const now = store.readConfig();
+  const count = Object.keys(store.readAccounts(now)).length;
+  console.error(`signed in as ${name} (account ${who.account}) on ${base}. Sync is on.`);
+  if (count > 1)
+    console.error(
+      `${count} accounts are signed in here; the default is ${now.active}. ` +
+        (now.active === name ? "" : `Switch it with \`passalong use ${name}\`. `) +
+        "Agents are asked which to use each session.",
+    );
+  return { name, who };
+}
+
+/**
+ * Sign in by approving in the browser: show a code, wait, and be handed a token. No password is
+ * typed here and no token is pasted between windows. Needs no terminal to ask on, so an agent can
+ * run it and tell the person which page to open.
+ */
+async function browserLogin() {
+  const verifier = randomBytes(32).toString("hex");
+  const challenge = createHash("sha256").update(verifier).digest("hex");
+  const start = await api.deviceStart(challenge, `${hostname()} cli`).catch((e) => die(e.message));
+  console.error(`Open ${start.url}`);
+  console.error(`and check the page shows the code ${start.code}, then press Approve.`);
+  if (tty) openPage(start.url);
+  console.error("Waiting for you to approve it here… (Ctrl-C to stop)");
+  const until = Date.now() + start.expires_in * 1000;
+  while (Date.now() < until) {
+    await new Promise((r) => setTimeout(r, start.interval * 1000));
+    const got = await api.devicePoll(start.id, verifier).catch((e) => die(e.message));
+    if (!got) continue;
+    await keepLogin(got.token);
+    console.error("Attach other machines with:");
+    console.error(`  passalong login ${got.token}`);
+    console.error("(keep it private — it is a credential, not a password)");
+    console.error("Give teammates a name to address you by: passalong me --handle <you>");
+    return;
+  }
+  die("nobody approved it in time. Run `passalong login` again.");
+}
+
+/** The old way, kept for anyone who asks for it with `--email`: an email and a password, typed here. */
+async function passwordLogin(f) {
+// An account you cannot sign in to is one that dies with this file. This used to mint one
+  // silently and then suggest adding a password afterwards; it asks up front instead.
+  if (!tty)
+    die(
+      "no terminal to ask on. Sign in at " +
+        `${api.baseUrl()}/hub, then attach this machine with \`passalong login <token>\``,
+    );
+
+  const email = f.email || (await ask("Email: "));
+  if (!email) die("an email is needed to sign in");
+  const password = await ask("Password: ", { hidden: true });
+  if (!password) die("a password is needed to sign in");
+
+  const label = `${hostname()} cli`;
+  let who = await api.signIn(email, password, { label }).catch((e) => e);
+  if (who instanceof Error) {
+    // 401 is "no such account, or the wrong password", said the same way on purpose so the API
+    // does not confirm which addresses exist. The CLI has to ask rather than guess, because
+    // creating an account for a mistyped address is worse than being told to try again.
+    if (who.status !== 401) die(who.message);
+    const yes = (await ask(`No account signed in as ${email}. Create one? [y/N] `)).toLowerCase();
+    if (yes !== "y" && yes !== "yes")
+      die("not signed in. If the password was wrong, try again, or reset it at " + `${api.baseUrl()}/hub`);
+    const again = await ask("Choose a password: ", { hidden: true });
+    if (again !== password) die("those did not match");
+    who = await api.signIn(email, password, { make: true, label }).catch((e) => die(e.message));
+  }
+
+  await keepLogin(who.token);
+  console.error("Attach other machines with:");
+  console.error(`  passalong login ${who.token}`);
+  console.error("(keep it private — it is a credential, not a password)");
+  console.error("Give teammates a name to address you by: passalong me --handle <you>");
+}
+
 async function ask(question, { hidden = false } = {}) {
   const { createInterface } = await import("node:readline");
   const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
@@ -276,6 +392,7 @@ const commands = {
     console.log(id);
     const target = guide.meta.target_context;
     console.error(`task "${guide.meta.title}" is in Draft${target ? ` for ${target}` : " (no repo)"}`);
+    if (guide.meta.team) console.error(`handed to ${guide.meta.team} (team inbox)`);
     console.error(`when an agent may take it: passalong ready ${id}`);
     if (!synced) console.error("not synced (run `passalong login` — agents elsewhere cannot see it)");
   },
@@ -685,9 +802,7 @@ const commands = {
   async login(f) {
     const given = f._[0];
     if (given) {
-      store.writeConfig({ token: given, api: api.baseUrl() });
-      const who = await api.me().catch((e) => die(`token rejected: ${e.message}`));
-      console.error(`logged in (account ${who.account}) — ${api.baseUrl()}`);
+      await keepLogin(given);
       return;
     }
     if (api.loggedIn() && !f.new) {
@@ -695,43 +810,58 @@ const commands = {
       if (who) {
         console.error(`already logged in (account ${who.account}). Attach another machine with:`);
         console.error(`  passalong login ${api.token()}`);
+        console.error("Add another account to this machine with `passalong login --new`.");
         return;
       }
     }
-    // An account you cannot sign in to is one that dies with this file. This used to mint one
-    // silently and then suggest adding a password afterwards; it asks up front instead.
-    if (!tty)
-      die(
-        "no terminal to ask on. Sign in at " +
-          `${api.baseUrl()}/hub, then attach this machine with \`passalong login <token>\``,
-      );
+    // Passwords are for someone who asks: `--email` keeps the prompts. Everyone else is sent to the
+    // browser, which works with no terminal at all — an agent can start it, and the person it is
+    // working for clicks once.
+    if (f.email || f.password) return passwordLogin(f);
+    return browserLogin();
+  },
 
-    const email = f.email || (await ask("Email: "));
-    if (!email) die("an email is needed to sign in");
-    const password = await ask("Password: ", { hidden: true });
-    if (!password) die("a password is needed to sign in");
-
-    const label = `${hostname()} cli`;
-    let who = await api.signIn(email, password, { label }).catch((e) => e);
-    if (who instanceof Error) {
-      // 401 is "no such account, or the wrong password", said the same way on purpose so the API
-      // does not confirm which addresses exist. The CLI has to ask rather than guess, because
-      // creating an account for a mistyped address is worse than being told to try again.
-      if (who.status !== 401) die(who.message);
-      const yes = (await ask(`No account signed in as ${email}. Create one? [y/N] `)).toLowerCase();
-      if (yes !== "y" && yes !== "yes")
-        die("not signed in. If the password was wrong, try again, or reset it at " + `${api.baseUrl()}/hub`);
-      const again = await ask("Choose a password: ", { hidden: true });
-      if (again !== password) die("those did not match");
-      who = await api.signIn(email, password, { make: true, label }).catch((e) => die(e.message));
+  /** The accounts signed in here, with the default marked. */
+  async accounts() {
+    const cfg = store.readConfig();
+    const all = store.readAccounts(cfg);
+    const names = Object.keys(all);
+    if (!names.length) {
+      console.log(
+        cfg.token
+          ? "one account is signed in here (a login from before accounts had names). `passalong login --new` adds another."
+          : "no account is signed in here — passalong login",
+      );
+      return;
+    }
+    for (const n of names) {
+      const a = all[n];
+      const who = [a.handle ? `@${a.handle}` : "", a.email].filter(Boolean).join("  ");
+      console.log(`${n === cfg.active ? "*" : " "} ${n}${who ? `  ${who}` : ""}  ${a.api}`);
     }
+    if (names.length > 1)
+      console.log("\n* is the default for a person at a terminal. Agents are asked which to use each session.");
+  },
 
-    store.writeConfig({ token: who.token, api: api.baseUrl() });
-    console.error(`signed in as ${email} (account ${who.account}) on ${api.baseUrl()}. Sync is on.`);
-    console.error("Attach other machines with:");
-    console.error(`  passalong login ${who.token}`);
-    console.error("(keep it private — it is a credential, not a password)");
-    console.error("Give teammates a name to address you by: passalong me --handle <you>");
+  /** Make one of them the default. This changes what a terminal gets, never what a session of an agent is told. */
+  async use(f) {
+    const name = f._[0] || die("usage: passalong use <name> (see `passalong accounts`)");
+    if (!store.readAccounts()[name])
+      die(`no account called "${name}" here. Signed in: ${Object.keys(store.readAccounts()).join(", ") || "none"}`);
+    store.setActive(name);
+    console.error(`the default account is now ${name}`);
+  },
+
+  /** Forget one of them on this machine. The account itself is untouched: only its token here goes. */
+  async logout(f) {
+    const name = f._[0] || die("usage: passalong logout <name> (see `passalong accounts`)");
+    const r = store.removeAccount(name);
+    if (!r.removed) die(`no account called "${name}" here`);
+    console.error(
+      r.active
+        ? `signed out of ${name}; the default is now ${r.active}`
+        : `signed out of ${name}; no account is signed in here now`,
+    );
   },
 
   async me(f) {
@@ -753,7 +883,7 @@ const commands = {
           ? " (no plan — nothing is syncing)"
           : " (no limit on your plan)";
     console.log(`guides   ${who.guides} synced${ceiling}`);
-    const current = store.readConfig().team;
+    const current = api.currentTeam();
     console.log(
       `teams    ${who.teams.length ? who.teams.map((t) => `${t.slug}${t.slug === current ? "*" : ""} (${t.role})`).join(", ") : "(none — passalong team create <name>)"}`,
     );
@@ -761,7 +891,7 @@ const commands = {
 
   async team(f) {
     const [sub, ...rest] = f._;
-    const cfg = store.readConfig();
+    const cfg = { team: api.currentTeam() };
     if (!sub) {
       if (!cfg.team) {
         const { teams } = await api.teams().catch((e) => die(e.message));
@@ -777,7 +907,7 @@ const commands = {
     if (sub === "create") {
       const name = rest.join(" ") || die("usage: passalong team create <name>");
       const t = await api.createTeam(name).catch((e) => die(e.message));
-      store.writeConfig({ team: t.slug });
+      api.setTeam(t.slug);
       console.error(`team ${t.name} created as "${t.slug}" — now current. Invite people: passalong team invite [email]`);
       return;
     }
@@ -798,7 +928,7 @@ const commands = {
       const ref = rest[0] || die("usage: passalong team join <link|code>");
       const code = ref.includes("/") ? ref.split("/").filter(Boolean).pop() : ref;
       const r = await api.join(code).catch((e) => die(e.message));
-      store.writeConfig({ team: r.slug });
+      api.setTeam(r.slug);
       console.error(`${r.joined ? "joined" : "already in"} ${r.name} (${r.slug}) — now current`);
       const who = await api.me().catch(() => null);
       if (who && !who.handle) console.error("teammates address you by handle: passalong me --handle <you>");
@@ -807,7 +937,7 @@ const commands = {
     if (sub === "use") {
       const slug = rest[0] || die("usage: passalong team use <slug>");
       await api.team(slug).catch((e) => die(e.message));
-      store.writeConfig({ team: slug });
+      api.setTeam(slug);
       console.error(`current team: ${slug}`);
       return;
     }
@@ -889,6 +1019,19 @@ const commands = {
         input = JSON.parse(raw || "{}");
       }
       if (!api.loggedIn()) return;
+      // Two or more accounts and nothing saying which: the one thing worth telling the agent at the
+      // start of a session, because every call after it would be refused until somebody chooses.
+      if (f.hook === "session" && api.needsChoice()) {
+        console.log(
+          JSON.stringify({
+            hookSpecificOutput: {
+              hookEventName: "SessionStart",
+              additionalContext: `Passalong: ${api.choiceMessage()}`,
+            },
+          }),
+        );
+        return;
+      }
       // The timeout is cleared as soon as the answer is in. Left running it holds the process open
       // for the full five seconds after the hook has printed, and a session start or a stop that
       // waits five seconds for nothing is the hook getting in the way, which it must never do.
@@ -938,6 +1081,15 @@ const commands = {
 
 const argv = flags(process.argv.slice(2));
 const cmd = argv._.shift() || "help";
+// `--as <name>` says which of the accounts on this machine this one command is for. It exists for an
+// agent that was told which by the person, since it has no terminal to be asked at.
+if (typeof argv.as === "string") {
+  try {
+    api.chooseAccount(argv.as);
+  } catch (e) {
+    die(e.message);
+  }
+}
 // The first thing anyone runs when something is off, and until now it printed the help page. The
 // parser only knows `--x`, so `--version` arrives as a flag on an empty command and `-v` as a word;
 // both are caught here, with `version`, before dispatch. Only the number goes to stdout, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Hand tasks, bugs and finished work to AI coding agents, and get back a write-up with evidence.",
   "mcpName": "io.github.codellyson/passalong",
   "keywords": [
@@ -14,7 +14,7 @@
     "mcp-server",
     "coding-agents",
     "task-management",
-    "cursor"
+    "codex"
   ],
   "homepage": "https://passalong.dev",
   "repository": {

package/src/api.js

@@ -1,7 +1,7 @@
 // Client for the hosted sync API (apps/api). Everything here is optional: with no token the
 // CLI is a purely local tool, and every function throws an ApiError the CLI turns into a hint.
 import { readFileSync } from "node:fs";
-import { readConfig } from "./store.js";
+import { nameFor, readAccounts, readConfig, saveTeam } from "./store.js";
 
 /**
  * This build's version, sent on every authenticated call as `x-passalong-version`. The server
@@ -22,21 +22,133 @@ export class ApiError extends Error {
   }
 }
 
+// ---- which account -----------------------------------------------------------------------------
+//
+// A machine may be signed in to several (store.js). Who a call is made as comes from, in order:
+// PASSALONG_TOKEN, an account named by PASSALONG_ACCOUNT, `--as` or `use_account` (this process
+// only), then the machine's default. With two or more logins and nobody having said which, a
+// person at a terminal gets the default and an agent — a process with no terminal to ask on — is
+// refused with the names, so it asks the person rather than choosing. That refusal is the prompt:
+// an agent cannot be asked a question, but it can be told to put one to somebody.
+
+let chosen = "";
+
+const interactive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+/** Names of the logins on this machine, each with what tells them apart. */
+export function accountList() {
+  return Object.entries(readAccounts()).map(([name, a]) => ({
+    name,
+    handle: a.handle || "",
+    email: a.email || "",
+    api: a.api || "",
+  }));
+}
+
+/** Name an account for this process only, the way a person confirming one for a session does. */
+export function chooseAccount(name) {
+  const all = readAccounts();
+  if (!all[name]) {
+    const names = Object.keys(all).join(", ");
+    throw new ApiError(
+      0,
+      `no account called "${name}" on this machine${names ? `. Signed in: ${names}` : ""}`,
+    );
+  }
+  chosen = name;
+  return { name, ...all[name] };
+}
+
+/** Take back a choice made with chooseAccount: the session is undecided again. */
+export function forgetChoice() {
+  chosen = "";
+}
+
+/** The account this process was told to use, or null when nobody said. */
+function picked() {
+  const want = chosen || process.env.PASSALONG_ACCOUNT || "";
+  if (!want) return null;
+  const a = readAccounts()[want];
+  if (!a) {
+    const names = Object.keys(readAccounts()).join(", ");
+    throw new ApiError(0, `no account called "${want}" on this machine. Signed in: ${names}`);
+  }
+  return { name: want, ...a };
+}
+
+/** The name of the account in use, if there is one: for saying who a command is about to act as. */
+export function accountInUse() {
+  if (process.env.PASSALONG_TOKEN) return "";
+  const p = picked();
+  if (p) return p.name;
+  return readConfig().active || "";
+}
+
+/** True when a call would have to guess which of several accounts is meant. */
+export function needsChoice() {
+  if (process.env.PASSALONG_TOKEN || chosen || process.env.PASSALONG_ACCOUNT) return false;
+  return Object.keys(readAccounts()).length >= 2 && !interactive();
+}
+
+/** What an agent is told when it would have to guess. It is written to be passed on to a person. */
+export function choiceMessage() {
+  const list = accountList()
+    .map((a) => {
+      const who = a.email || (a.handle ? `@${a.handle}` : "");
+      return who && who !== a.name ? `${a.name} (${who})` : a.name;
+    })
+    .join(", ");
+  return (
+    `More than one Passalong account is signed in on this machine (${list}) and nothing says which ` +
+    "this session is for. Ask the person which one to use, then call use_account with its name " +
+    "(or run the command with --as <name>). Do not choose one yourself."
+  );
+}
+
 export function baseUrl() {
-  return (process.env.PASSALONG_API || readConfig().api || DEFAULT_API).replace(/\/$/, "");
+  const base = process.env.PASSALONG_API || picked()?.api || readConfig().api || DEFAULT_API;
+  return base.replace(/\/$/, "");
 }
 
 export function token() {
-  return process.env.PASSALONG_TOKEN || readConfig().token || null;
+  return process.env.PASSALONG_TOKEN || picked()?.token || readConfig().token || null;
 }
 
 export function loggedIn() {
   return Boolean(token());
 }
 
+/** The team this account works in. It belongs to the account, not the machine. */
+export function currentTeam() {
+  const p = picked();
+  return (p ? p.team : readConfig().team) || "";
+}
+
+export function setTeam(slug) {
+  saveTeam(picked()?.name || readConfig().active || "", slug);
+}
+
+/** Who a token is, without it being the one this process uses: how a login is named before it is kept. */
+export async function meWith(tokenValue, base = baseUrl()) {
+  let res;
+  try {
+    res = await fetch(`${base}/v1/me`, {
+      headers: { ...CLIENT, authorization: `Bearer ${tokenValue}` },
+    });
+  } catch (err) {
+    throw new ApiError(0, `could not reach ${base} (${err.message})`);
+  }
+  const said = await res.json().catch(() => ({}));
+  if (!res.ok) throw new ApiError(res.status, said.message || res.statusText);
+  return said;
+}
+
+export { nameFor };
+
 async function call(path, { method = "GET", body, auth = true, raw = false } = {}) {
   const headers = { ...CLIENT };
   if (auth) {
+    if (needsChoice()) throw new ApiError(409, choiceMessage());
     const t = token();
     if (!t) throw new ApiError(401, "not logged in — run `passalong login` to enable sync");
     headers.authorization = `Bearer ${t}`;
@@ -126,6 +238,32 @@ export async function signIn(email, password, { make = false, label = "" } = {})
  * still live and still right for the invite page, which mints before it claims, and because
  * removing a published export is a breaking change for anyone who imported it.
  */
+/**
+ * Sign this machine in from the browser. `challenge` is the sha256, in hex, of a secret kept here;
+ * what comes back is a short code to show, the page to open, and how often to ask whether it was
+ * approved. Nothing in the answer is a credential.
+ */
+export const deviceStart = (challenge, label) =>
+  call("/v1/device/start", { method: "POST", auth: false, body: { challenge, label } });
+
+/** `null` while nobody has said yes; the account and its token once somebody has. */
+export async function devicePoll(id, verifier) {
+  let res;
+  try {
+    res = await fetch(`${baseUrl()}/v1/device/poll`, {
+      method: "POST",
+      headers: { ...CLIENT, "content-type": "application/json" },
+      body: JSON.stringify({ id, verifier }),
+    });
+  } catch (err) {
+    throw new ApiError(0, `could not reach ${baseUrl()} (${err.message})`);
+  }
+  if (res.status === 202) return null;
+  const said = await res.json().catch(() => ({}));
+  if (!res.ok) throw new ApiError(res.status, said.message || res.statusText);
+  return said;
+}
+
 export const createAccount = () => call("/v1/accounts", { method: "POST", auth: false });
 export const me = () => call("/v1/me");
 export const updateMe = (patch) => call("/v1/me", { method: "PATCH", body: patch });
@@ -238,6 +376,7 @@ export const ack = (id, taken, note = "") =>
  * percent-encoded because a header cannot hold what a filename can.
  */
 export async function uploadFile(bytes, type, name = "") {
+  if (needsChoice()) throw new ApiError(409, choiceMessage());
   const t = token();
   if (!t) throw new ApiError(401, "not logged in — run `passalong login` to enable sync");
   const headers = {

package/src/guide.js

@@ -709,3 +709,101 @@ function taskTemplate(meta = {}) {
 export function stripPlaceholders(body) {
   return body.replace(/^<!-- passalong:.*?-->\n?/gm, "").trim();
 }
+
+// ---- reading a guide in parts, and how big one may be -----------------------------------------
+// Mirrors apps/api/src/sections.ts — apps/api/test/sections.test.mjs holds the two to the same
+// answers. Most of what is stored is a few very large guides (six of 123 held 72% of the text), and
+// an agent that wants only the Acceptance of a long task should not read the rest first.
+
+/** Over this a guide is large: its readers are offered the outline first, and its author a warning. */
+export const GUIDE_WARN = 20_000;
+/** Over this a new guide is refused by the server. A guide stored before it existed may keep its size. */
+export const GUIDE_MAX = 60_000;
+
+/** Where each heading starts, outside the frontmatter and outside code fences. */
+function headingLines(markdown) {
+  const fm = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/.exec(markdown);
+  const bodyStart = fm ? fm[0].length : 0;
+  const lines = [];
+  let fence = "";
+  let at = bodyStart;
+  for (const raw of markdown.slice(bodyStart).split("\n")) {
+    const mark = /^\s*(```|~~~)/.exec(raw)?.[1];
+    if (mark) fence = fence ? (fence === mark ? "" : fence) : mark;
+    const m = !fence && !mark ? /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(raw) : null;
+    if (m) lines.push({ heading: m[2].trim(), level: m[1].length, start: at });
+    at += raw.length + 1;
+  }
+  return lines;
+}
+
+/** The end of the section that begins at lines[i]: the next heading at its level or above. */
+function sectionEnd(lines, i, total) {
+  for (let j = i + 1; j < lines.length; j++)
+    if (lines[j].level <= lines[i].level) return lines[j].start;
+  return total;
+}
+
+/** Every heading, with the characters in its section (nested ones included). */
+export function outline(markdown) {
+  const lines = headingLines(markdown);
+  return lines.map((l, i) => ({
+    heading: l.heading,
+    level: l.level,
+    chars: sectionEnd(lines, i, markdown.length) - l.start,
+  }));
+}
+
+/** One section by its heading — exact, then by its start, then by what it contains. */
+export function section(markdown, name) {
+  const lines = headingLines(markdown);
+  const want = String(name ?? "")
+    .trim()
+    .toLowerCase();
+  if (!want) return null;
+  const at = (test) => lines.findIndex((l) => test(l.heading.toLowerCase()));
+  const i = [
+    at((h) => h === want),
+    at((h) => h.startsWith(want)),
+    at((h) => h.includes(want)),
+  ].find((n) => n >= 0);
+  if (i === undefined) return null;
+  return {
+    heading: lines[i].heading,
+    text: markdown.slice(lines[i].start, sectionEnd(lines, i, markdown.length)).trimEnd(),
+  };
+}
+
+/** What a guide's author is told when it is on the large side. */
+export function sizeWarning(chars) {
+  return chars > GUIDE_WARN
+    ? `this guide is ${chars.toLocaleString("en")} characters, and over ${GUIDE_WARN.toLocaleString("en")} ` +
+        "it is read by outline first. Put logs, dumps and long output in a file (attach_file) and " +
+        "link it; keep the guide to what the next agent has to act on."
+    : null;
+}
+
+/**
+ * What an agent is shown instead of a large guide: who it is, what it is, and where its parts are.
+ * `path` is where the whole of it was written, for a search rather than a read.
+ */
+export function outlineText(markdown, { id = "", path = "" } = {}) {
+  const { meta } = parse(markdown);
+  const rows = outline(markdown)
+    .filter((h) => h.level <= 3)
+    .map(
+      (h) => `${"  ".repeat(h.level - 1)}- ${h.heading} (${h.chars.toLocaleString("en")} chars)`,
+    );
+  return [
+    `${meta.title || id} — ${meta.kind || "guide"}, ${markdown.length.toLocaleString("en")} characters`,
+    meta.summary ? `Summary: ${meta.summary}` : "",
+    "",
+    "Sections:",
+    ...rows,
+    "",
+    `Read one with get_guide ref=${id} section="<heading>", or the whole thing with full=true.` +
+      (path ? ` The full text is also on disk at ${path}, if you only need to search it.` : ""),
+  ]
+    .filter((l, i, a) => l !== "" || a[i - 1] !== "")
+    .join("\n");
+}

package/src/mcp.js

@@ -9,7 +9,18 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import * as api from "./api.js";
 import { refusal, runChecks } from "./checks.js";
-import { AREAS, BUG_SECTIONS, parse, SECTIONS, TASK_SECTIONS, template } from "./guide.js";
+import {
+  AREAS,
+  BUG_SECTIONS,
+  GUIDE_WARN,
+  outlineText,
+  parse,
+  SECTIONS,
+  section as sectionOf,
+  sizeWarning,
+  TASK_SECTIONS,
+  template,
+} from "./guide.js";
 import * as passalong from "./passalong.js";
 
 /**
@@ -396,7 +407,7 @@ export function buildServer() {
       if (h)
         return fail({
           message:
-            `${err.message}. Somebody else is on it here${h.note ? ` (last said: "${h.note}")` : ""}. ` +
+            `${err.message}. Somebody else is on it here${h.agent ? ` (agent ${h.agent}${h.host ? ` on ${h.host}` : ""})` : ""}${h.note ? ` (last said: "${h.note}")` : ""}. ` +
             "Tell the user before doing this work too; get_guide reads it without taking it.",
         });
       return failWith(err);
@@ -787,36 +798,44 @@ export function buildServer() {
           ),
         checks: z
           .array(
-            z.object({
-              check: z
-                .string()
-                .describe(
-                  "the line this answers, in the guide's own words: an Acceptance line on a task, " +
-                    "a Verification line on a handoff or a bug",
-                ),
-              says: z
-                .string()
-                .optional()
-                .describe(
-                  'what happened, in one plain sentence for a PERSON: "Swagger lists all six ' +
-                    'endpoints, each with request and response schemas." It is the row they read ' +
-                    "in the review table; the evidence stays folded behind it. Strongly " +
-                    "recommended: a check without one shows only the line it answers",
-                ),
-              ran: z
-                .string()
-                .optional()
-                .describe("what you ran for it, and what came back; not needed when `cmd` is set"),
-              cmd: z
-                .string()
-                .optional()
-                .describe(
-                  "the shell command that proves this line, run here before the hand-in lands — " +
-                    "its exit code decides the check and its output is recorded as the evidence. " +
-                    "Non-zero refuses the hand-in. Leave it out for a check nobody can run, like " +
-                    '"the badge reads 3" — then SHOW it with attach_screenshot and put the line it returns in `ran`; a check is run or shown, and describing what you saw is refused',
-                ),
-            }),
+            // A bare string is a check line with nothing behind it. Let it through to the server's
+            // refusal, which says what to send, rather than a schema error that says only "expected
+            // object".
+            z.preprocess(
+              (v) => (typeof v === "string" ? { check: v } : v),
+              z.object({
+                check: z
+                  .string()
+                  .describe(
+                    "the line this answers, in the guide's own words: an Acceptance line on a task, " +
+                      "a Verification line on a handoff or a bug",
+                  ),
+                says: z
+                  .string()
+                  .optional()
+                  .describe(
+                    'what happened, in one plain sentence for a PERSON: "Swagger lists all six ' +
+                      'endpoints, each with request and response schemas." It is the row they read ' +
+                      "in the review table; the evidence stays folded behind it. Strongly " +
+                      "recommended: a check without one shows only the line it answers",
+                  ),
+                ran: z
+                  .string()
+                  .optional()
+                  .describe(
+                    "what you ran for it, and what came back; not needed when `cmd` is set",
+                  ),
+                cmd: z
+                  .string()
+                  .optional()
+                  .describe(
+                    "the shell command that proves this line, run here before the hand-in lands — " +
+                      "its exit code decides the check and its output is recorded as the evidence. " +
+                      "Non-zero refuses the hand-in. Leave it out for a check nobody can run, like " +
+                      '"the badge reads 3" — then SHOW it with attach_screenshot and put the line it returns in `ran`; a check is run or shown, and describing what you saw is refused',
+                  ),
+              }),
+            ),
           )
           .optional()
           .describe(
@@ -928,7 +947,9 @@ export function buildServer() {
       title: "Get guide",
       annotations: READS,
       description:
-        "READ a transfer guide by passalong id or share link and return its full markdown. Also " +
+        "READ a transfer guide by passalong id or share link and return its markdown. A guide over " +
+        "20,000 characters comes back as an outline (its headings and their sizes) unless you ask " +
+        "for `section`, for one part, or `full`, for all of it. Also " +
         "writes it to .passalong/<id>.md in the working directory so it survives the session. " +
         "Pulling a teammate's guide tells them the transfer landed. Use this to look at a guide " +
         "you have not committed to. If you are about to DO the work, call take instead: " +
@@ -940,12 +961,38 @@ export function buildServer() {
           .string()
           .optional()
           .describe("directory to write .passalong/<id>.md into; default is the server's cwd"),
+        section: z
+          .string()
+          .optional()
+          .describe("read only the part under this heading, e.g. Acceptance; see the outline"),
+        outline: z
+          .boolean()
+          .optional()
+          .describe("just the headings and their sizes, whatever the guide's length"),
+        full: z
+          .boolean()
+          .optional()
+          .describe("the whole document, even one over 20,000 characters"),
       },
     },
-    async ({ ref, cwd }) => {
+    async ({ ref, cwd, section, outline, full }) => {
       try {
         const { markdown, path, from } = await passalong.pull(ref, { cwd: cwd || process.cwd() });
         const meta = parse(markdown).meta;
+        if (section) {
+          const part = sectionOf(markdown, section);
+          if (!part)
+            return text(
+              `No heading matching "${section}".\n\n${outlineText(markdown, { id: meta.id || ref, path })}`,
+            );
+          return text(
+            `${part.text}\n\n<!-- passalong: ${meta.id || ref}, "${part.heading}" only; the whole guide is at ${path} -->`,
+          );
+        }
+        if (outline || (!full && markdown.length > GUIDE_WARN))
+          return text(
+            `${outlineText(markdown, { id: meta.id || ref, path })}\n\n<!-- passalong: ${from}; written to ${path} -->`,
+          );
         const lead = leadFor(meta);
         const siblings = await related(meta);
         // Follow-ups are more context for this guide, so they come with it — after the document,
@@ -1144,6 +1191,7 @@ export function buildServer() {
           parent: guide.meta.parent || "",
           notified,
           path,
+          ...(sizeWarning(markdown.length) ? { warning: sizeWarning(markdown.length) } : {}),
           // A task does not go live on publish, and an agent that reports "queued it" has told
           // the user something untrue. Said in the result so it is said to them.
           ...(guide.meta.kind === "task" && guide.meta.status === "draft"
@@ -1274,6 +1322,59 @@ export function buildServer() {
     async ({ kind }) => text(template(kind ? { kind } : {})),
   );
 
+  server.registerTool(
+    "accounts",
+    {
+      title: "Accounts on this machine",
+      annotations: READS,
+      description:
+        "The Passalong accounts signed in on this machine, which one this session is using, and " +
+        "whether it still has to be chosen. With two or more and nothing chosen, every call that " +
+        "needs an account is refused until use_account says which. Read-only.",
+      inputSchema: {},
+    },
+    async () => {
+      const list = api.accountList();
+      return json({
+        accounts: list,
+        in_use: api.accountInUse(),
+        must_choose: api.needsChoice(),
+        ...(api.needsChoice() ? { next: api.choiceMessage() } : {}),
+      });
+    },
+  );
+
+  server.registerTool(
+    "use_account",
+    {
+      title: "Use an account for this session",
+      annotations: { ...ADDS, idempotentHint: true },
+      description:
+        "Say which signed-in account this session acts as. Call it only with a name the PERSON " +
+        "gave you: when a machine has more than one account and none is chosen, ask them which, " +
+        "in plain words, then pass their answer. It lasts until this session ends and changes " +
+        "nothing on disk, so it never moves the machine's default.",
+      inputSchema: {
+        name: z.string().describe("an account name from the accounts tool, as the person said it"),
+      },
+    },
+    async ({ name }) => {
+      try {
+        api.chooseAccount(name);
+        const who = await api.me();
+        return json({
+          using: name,
+          account: who.account,
+          handle: who.handle || "",
+          email: who.email || "",
+          teams: (who.teams || []).map((t) => t.slug),
+        });
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
   server.registerTool(
     "set_guide_status",
     {

package/src/passalong.js

@@ -55,6 +55,14 @@ export async function share(markdown, { cwd = process.cwd(), to, follows } = {})
   const target = parseTarget(to);
   if (target.team) guide.meta.team = target.team;
   if (target.to) guide.meta.to = target.to;
+  if (
+    !guide.meta.team &&
+    (guide.meta.kind === "bug" || guide.meta.kind === "task") &&
+    api.loggedIn()
+  ) {
+    const team = api.currentTeam();
+    if (team) guide.meta.team = team;
+  }
   // `follows` names the guide this one came out of: an id, a share link, or a pulled .md file. An id
   // is used as it is; a link or a file is read for the id in its own frontmatter. `validate()` below
   // is what refuses a guide that names itself.
@@ -111,10 +119,11 @@ export async function fileBugs(
   if (!api.loggedIn())
     throw new PassalongError("filing a report needs sync — run `passalong login` first");
   const target = parseTarget(to);
+  const team = target.team || api.currentTeam();
   const { report } = await api.createReport({
     title,
     environment,
-    team: target.team || "",
+    team,
     to: target.to || "",
   });
 
@@ -139,7 +148,7 @@ export async function fileBugs(
         .join(", ")}) before failing: ${err.message}`,
     );
   }
-  return { report: { id: report.id, title, environment }, issues: filed };
+  return { report: { id: report.id, title, environment, team }, issues: filed };
 }
 
 /** Resolve a reference (id, share URL, or local file path) to a guide. */

package/src/store.js

@@ -44,6 +44,102 @@ export function writeConfig(patch) {
   return next;
 }
 
+// ---- accounts on this machine -----------------------------------------------------------------
+//
+// One machine used to hold one login: a single `token` and `api` in the config, so every repo and
+// every agent acted as whoever signed in last, and a second `login` overwrote the first. They are
+// now kept by name under `accounts`, with `active` naming the one a person at a terminal gets by
+// default. `token`, `api` and `team` stay at the top of the file as a copy of the active account,
+// because that is where every older reader — and every older CLI sharing this directory — looks.
+
+/** Every login on this machine by name. Empty on a config from before there were several. */
+export function readAccounts(cfg = readConfig()) {
+  return cfg.accounts && typeof cfg.accounts === "object" ? cfg.accounts : {};
+}
+
+const slug = (s) =>
+  String(s ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32);
+
+/** What a login is called when its owner has not said: their @handle, else the start of their email. */
+export function nameFor({ handle, email, account }) {
+  return slug(handle) || slug(String(email ?? "").split("@")[0]) || slug(account) || "account";
+}
+
+/** Make `name` the default: what a person at a terminal gets, and what older readers see. */
+export function setActive(name) {
+  const entry = readAccounts()[name];
+  if (!entry) throw new Error(`no account called "${name}" on this machine`);
+  return writeConfig({
+    active: name,
+    token: entry.token,
+    api: entry.api,
+    team: entry.team || "",
+  });
+}
+
+/**
+ * Keep a login under a name. A login of an account already here is updated in place rather than
+ * added twice; a new one takes `nameFor`, with a number on the end if that is taken. The first
+ * login on a machine becomes the default, and so does any that `activate` asks for.
+ */
+export function saveAccount(entry, { activate = false } = {}) {
+  const cfg = readConfig();
+  const all = { ...readAccounts(cfg) };
+  const same = Object.entries(all).find(
+    ([, a]) => entry.account && a.account === entry.account && a.api === entry.api,
+  );
+  let name = same?.[0];
+  if (!name) {
+    const base = nameFor(entry);
+    name = base;
+    for (let i = 2; all[name]; i++) name = `${base}-${i}`;
+  }
+  all[name] = { ...(same?.[1] ?? {}), ...entry };
+  writeConfig({ accounts: all });
+  if (activate || !cfg.active || !readAccounts(cfg)[cfg.active]) setActive(name);
+  else if (cfg.active === name) setActive(name);
+  return name;
+}
+
+/** Set the team an account works in, and mirror it when that account is the default. */
+export function saveTeam(name, team) {
+  const cfg = readConfig();
+  const all = readAccounts(cfg);
+  if (name && all[name]) {
+    writeConfig({ accounts: { ...all, [name]: { ...all[name], team } } });
+    if (cfg.active === name) writeConfig({ team });
+  } else writeConfig({ team });
+}
+
+/**
+ * Forget a login. If it was the default, the first one left takes over — said to the person by the
+ * caller, because a default that changes silently is the thing this exists to stop.
+ */
+export function removeAccount(name) {
+  const cfg = readConfig();
+  const all = { ...readAccounts(cfg) };
+  if (!all[name]) return { removed: false, active: cfg.active || "" };
+  delete all[name];
+  writeConfig({ accounts: all });
+  if (cfg.active !== name) return { removed: true, active: cfg.active || "" };
+  const next = Object.keys(all)[0];
+  if (next) {
+    setActive(next);
+    return { removed: true, active: next };
+  }
+  const bare = readConfig();
+  delete bare.active;
+  delete bare.token;
+  delete bare.team;
+  delete bare.accounts;
+  writeFileSync(CONFIG, `${JSON.stringify(bare, null, 2)}\n`, { mode: 0o600 });
+  return { removed: true, active: "" };
+}
+
 export function guidePath(id) {
   return join(GUIDES, `${id}.md`);
 }