@symbols-cli/cli 0.0.1

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2025 Symbols LLC. All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, modification, or use of this software, via any medium, is
+strictly prohibited.
+
+No license, express or implied, is granted except by a written agreement
+signed by Symbols LLC.

package/README.md

@@ -0,0 +1,103 @@
+# Symbols CLI
+
+Run the Symbols agent on your own machine.
+
+```bash
+npm i -g @symbols-cli/cli    # requires Node >= 20
+symbols login
+symbols up
+cd ~/Symbols/<your project>
+claude
+```
+
+## Why this exists
+
+Odin Code runs the agent in a per-user container capped at **1536 MB and 1 vCPU**.
+`claude` alone holds ~675 MB, so a genuinely large task — "make a report for 100
+stocks" — gets OOM-killed. Your laptop has 16–64 GB and 8–16 cores, dedicated to
+one person. Same agent, same skills, same data; no ceiling.
+
+Typing is also local. Today every keystroke crosses the network twice
+(browser → websocket → server → `docker exec` → tmux → claude, and back) at a
+measured ~256 ms round trip. Here there is no network in the loop.
+
+## What runs where
+
+| | |
+|---|---|
+| The agent (`claude`), your files, your editor | **Your machine** |
+| Market data, backtests, notebook cell execution, LEAN | **Symbols servers** |
+
+Market data always comes through the API — no Databento, Unusual Whales or R2
+credentials are ever placed on your machine. Backtests POST and poll; LEAN never
+runs locally.
+
+## Read this before you install
+
+**The agent runs as you, in your home directory.** That is the entire point — it is
+what removes the memory ceiling — and it is also the thing to understand before
+installing.
+
+Inside a container, a prompt-injection attack (a hostile string in a fetched web
+page, an imported notebook, a forked community strategy) was bounded by the
+sandbox. On your laptop the boundary is different: it is Claude Code's own
+permission model plus your OS's file protections. An agent session that goes wrong
+can reach what you can reach — your SSH keys, your browser profile, your other
+repositories.
+
+Symbols' commitment is to add **no attack surface beyond what vanilla Claude Code
+already has**:
+
+- Skills are **signed**; an unsigned or wrong-key bundle is refused, and so is a
+  rollback to an older version.
+- File sync **never writes server content into config-bearing paths** — not
+  `.claude/**`, not `.mcp.json`, not `CLAUDE.md` outside its managed markers, not
+  `.git/**`. Those are files a tool *executes*, and a compromised server must not
+  be able to place one in your project.
+- `symbols` writes inside `~/Symbols/**` and its own `~/.symbols/` state directory.
+  It never touches `~/.claude/`, `~/.claude.json`, or your shell rc.
+
+## Your credential
+
+`symbols login` opens your browser. You authenticate with Clerk there; the CLI
+never sees a password.
+
+What comes back is a device credential, stored in the **macOS keychain** (or
+`~/.symbols/credentials` at `0600` elsewhere — `symbols whoami` tells you which,
+rather than assuming). It is:
+
+- **read-and-notebook scoped.** It cannot place an order. `symbols whoami` prints
+  the live scope list so you can check that yourself.
+- **short-lived in use.** Access tokens last 15 minutes and are held in memory
+  only.
+- **revocable, durably.** `symbols logout`, or revoke the device from the app. A
+  revoked device stops refreshing immediately; an access token already minted
+  stays valid until it expires, at most 15 minutes.
+
+Placing live orders is deliberately **not** something this credential can do. The
+CLI proposes an order; you approve it in the app. That keeps a human at the point
+where money moves, which a timer on a laptop cannot substitute for.
+
+## Commands
+
+| | |
+|---|---|
+| `symbols login` / `logout` / `whoami` | device credential |
+| `symbols up` | create `~/Symbols` and wire the project |
+| `symbols update` | fetch + verify the signed skills bundle |
+| `symbols sync` / `watch` / `status` | file sync |
+| `symbols project new \| ls \| rm` | projects |
+| `symbols curl <path>` | call the API by path, authenticated |
+| `symbols doctor` | check the install; exits non-zero on any problem |
+
+## Development
+
+```bash
+bun install
+bun run --cwd apps/cli build
+node --test apps/cli/test/*.test.mjs
+
+# Point at a local server (the API origin is otherwise allowlisted)
+SYMBOLS_ALLOW_INSECURE_ORIGIN=1 SYMBOLS_API_URL=http://127.0.0.1:8000 \
+  node apps/cli/dist/index.js whoami
+```

package/dist/auth/client.js

@@ -0,0 +1,531 @@
+// 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.
+// The authed fetch every command goes through.
+//
+// It owns four things so that no caller has to think about them:
+//
+//   1. HOST PINNING (S3). Every request resolves its origin through `apiOrigin()`.
+//      Callers pass a PATH, never a URL — the same shape `symbols curl` enforces,
+//      for the same reason.
+//   2. ACCESS-TOKEN LIFECYCLE. A 15-minute access token is minted from the
+//      refresh credential on demand, cached in memory only, and re-minted once on
+//      a 401. It is never written to disk.
+//   3. WRITE-AHEAD ROTATION. This client GENERATES the next refresh token and
+//      PERSISTS it before asking the server to commit its hash, so the credential
+//      exists here before it can exist there. Recovery after a crash is therefore
+//      purely local — try the pending token, fall back to the current one — and
+//      the server never has to hand a credential back to whoever asks for one.
+//      That last property is not a nicety: an earlier design let the server
+//      re-issue on presentation of a superseded token, and it could not tell a
+//      crashed client from an attacker holding a copy. It was a session takeover.
+//   4. VERSION SIGNALLING. `X-Symbols-Cli-Version` on every request, and a `426`
+//      is surfaced as an actionable upgrade message rather than a raw status.
+//
+// ⚠ A 426-driven auto-upgrade MUST NOT be added here before bundle signing (S1)
+// lands. An unsigned self-update path is a remote-code-execution channel into
+// every user's home directory, which is precisely the inversion the plan calls
+// the thing it got most wrong.
+import { promises as fs } from "node:fs";
+import { join, dirname } from "node:path";
+import { apiOrigin } from "./hosts.js";
+import { randomBytes, createHash } from "node:crypto";
+import { load, save, credentialsPath } from "./credentials.js";
+import { CLI_VERSION } from "../util/version.js";
+import { refreshBody } from "./wire.js";
+export class NotLoggedInError extends Error {
+    constructor() {
+        super("not signed in — run `symbols login`");
+        this.name = "NotLoggedInError";
+    }
+}
+export class DeviceRevokedError extends Error {
+    constructor() {
+        super("this device's access was revoked — run `symbols login` to sign in again");
+        this.name = "DeviceRevokedError";
+    }
+}
+/** In memory only, for the life of the process. Never persisted. */
+let cached = null;
+/** Re-mint this long before expiry so an in-flight request cannot straddle it. */
+const EXPIRY_SKEW_MS = 60_000;
+/**
+ * How long a single credential rotation may take before it is abandoned.
+ *
+ * Generous on purpose — see the note at the POST. This exists to bound an
+ * unbounded wait, not to make the refresh fast.
+ */
+const REFRESH_TIMEOUT_MS = 20_000;
+export class ApiError extends Error {
+    status;
+    path;
+    constructor(status, path, message) {
+        super(message);
+        this.status = status;
+        this.path = path;
+        this.name = "ApiError";
+    }
+}
+/** A path, always — `/api/...`. Passing a URL is a programming error, not config. */
+function urlFor(path) {
+    if (!path.startsWith("/")) {
+        throw new Error(`api path must start with '/' (got '${path}')`);
+    }
+    return apiOrigin() + path;
+}
+async function rawFetch(path, init) {
+    const headers = new Headers(init.headers);
+    headers.set("x-symbols-cli-version", CLI_VERSION);
+    headers.set("accept", "application/json");
+    return fetch(urlFor(path), { ...init, headers, redirect: "error" });
+}
+/**
+ * Exchange the stored refresh token for an access token, rotating the refresh
+ * token in the process.
+ *
+ * Persist-before-use: see the S4 note at the top of this file.
+ */
+/** A fresh refresh token for this device. 32 CSPRNG bytes, url-safe. */
+function newRefreshToken(deviceId) {
+    return `${deviceId}.${randomBytes(32).toString("base64url")}`;
+}
+function sha256Hex(s) {
+    return createHash("sha256").update(s).digest("hex");
+}
+/**
+ * Exchange the stored refresh token for an access token, rotating as we go.
+ *
+ * ## WRITE-AHEAD — the ordering is the security property
+ *
+ * We GENERATE the next token, PERSIST it as `pendingToken`, and only then ask
+ * the server to commit its hash. The credential therefore exists on this disk
+ * before it can exist server-side, so no crash window can strand us holding
+ * something the server has superseded.
+ *
+ * That is what lets the server treat any presentation of a superseded token as
+ * a replay and revoke on it. Three earlier designs routed recovery through the
+ * server instead, which forced `refresh` to hand a credential to whoever
+ * presented the previous token — and it cannot tell a crashed client from an
+ * attacker holding a copy. The last of those was a full session takeover.
+ *
+ * Recovery is local and needs no server cooperation:
+ *   * crashed before the POST      -> the server never committed; `pending` is
+ *                                     unknown to it, so fall back to `refreshToken`
+ *   * crashed after the POST       -> the server committed; `pending` IS current,
+ *                                     so it works and we promote it
+ */
+async function mintAccessToken() {
+    const cred = await load();
+    if (!cred)
+        throw new NotLoggedInError();
+    // A credential minted against a different origin must not be sent to this one.
+    const origin = apiOrigin();
+    if (cred.origin !== origin) {
+        throw new Error(`stored credential belongs to ${cred.origin}, not ${origin} — run \`symbols login\``);
+    }
+    // Try the pending token FIRST. If a previous rotation committed server-side
+    // but we died before promoting it, this is the live credential.
+    if (cred.pendingToken) {
+        try {
+            const minted = await rotate(cred, cred.pendingToken);
+            return minted;
+        }
+        catch (err) {
+            if (err instanceof DeviceRevokedError) {
+                // The server does not recognise it, so that rotation never committed.
+                // Drop it before falling back, or every future call pays a wasted round
+                // trip re-presenting a token that will never be accepted.
+                const withoutPending = { ...cred };
+                delete withoutPending.pendingToken;
+                await save(withoutPending);
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    return rotate(cred, cred.refreshToken);
+}
+/** One rotation attempt, presenting `present` and writing ahead the successor. */
+async function rotate(cred, present) {
+    const next = newRefreshToken(cred.deviceId);
+    // ⚠ PERSIST BEFORE THE REQUEST. This is the whole scheme.
+    //
+    // Only `pendingToken` moves. An earlier version also set
+    // `refreshToken: present`, which on the RECOVERY path — where `present` is
+    // itself an unconfirmed pending token — overwrote the last known-good
+    // credential with one the server might never have committed. A crash there
+    // lost the original outright.
+    await save({ ...cred, pendingToken: next });
+    // ⚠ A6 — THE REFRESH NEEDS ITS OWN DEADLINE. It had none, so a stalled
+    // rotation ran until the CALLER's budget expired — measured: a tool with a
+    // nominal 15 s cap returned after 22074 ms, and the error named the API call
+    // rather than the refresh that actually hung.
+    //
+    // Aborting mid-rotation is safe and is NOT a new failure mode: `save()` above
+    // persists `pendingToken` BEFORE this POST, and `mintAccessToken`'s recovery
+    // path already handles the crashed-mid-rotation case. An abort is therefore
+    // equivalent to a crash, and recovers from local state.
+    //
+    // Not set aggressively: this is a multi-statement Postgres transaction on the
+    // far side, not a cheap read, so a tight deadline would convert a slow
+    // rotation into a failed one.
+    const res = await rawFetch("/api/auth/cli/refresh", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(refreshBody({ ...cred, refreshToken: present }, sha256Hex(next))),
+        signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS),
+    });
+    if (res.status === 401 || res.status === 403) {
+        throw new DeviceRevokedError();
+    }
+    if (!res.ok) {
+        throw new ApiError(res.status, "/api/auth/cli/refresh", `refresh failed (${res.status})`);
+    }
+    const body = (await res.json());
+    // Committed. Promote: `next` is the live credential and nothing is pending.
+    //
+    // ⚠ The token just presented is now SUPERSEDED, and the server has it in
+    // history — presenting it again is a proven replay and revokes the device. It
+    // must not survive anywhere in the stored credential.
+    const promoted = { ...cred, refreshToken: next };
+    delete promoted.pendingToken;
+    await save(promoted);
+    const expiresAt = Date.parse(body.expires_at);
+    return {
+        mintedAt: Date.now(),
+        token: body.access_token,
+        // A malformed timestamp must not become an infinitely-valid token.
+        expiresAt: Number.isFinite(expiresAt) ? expiresAt : Date.now() + 15 * 60_000,
+    };
+}
+/**
+ * Cross-process single-flight around the refresh.
+ *
+ * Without it, two `symbols` processes (`watch` in one terminal, `status` in
+ * another) can present the SAME refresh token at the same instant. One rotates;
+ * the other is then holding a token the server has just superseded — and a
+ * superseded token is a PROVEN REPLAY, so the server revokes the device. It is
+ * right to: it cannot tell our second process from an attacker holding a stolen
+ * copy, and guessing in the caller's favour is how an earlier design became a
+ * session takeover.
+ *
+ * ⚠ THAT MAKES THIS LOCK THE ONLY DEFENCE, not an optimisation. The server is
+ * deliberately fail-closed, so every collision this client fails to prevent
+ * signs the user out. Serialising means exactly one process presents a token;
+ * the losers wait, re-read the store, and find the winner's rotated credential
+ * already there.
+ *
+ * The crash-before-persist case a server-side grace used to cover is handled
+ * locally instead: the client writes its successor to disk BEFORE the server can
+ * commit it, so recovery never needs the server's cooperation. See `rotate`.
+ */
+const LOCK_STALE_MS = 30_000;
+function lockPath() {
+    return join(dirname(credentialsPathForLock()), "refresh.lock");
+}
+/** The credentials dir, without importing the path helper's whole surface. */
+function credentialsPathForLock() {
+    // `credentialsPath()` is the authority for where state lives; the lock sits
+    // beside it so a custom SYMBOLS_HOME keeps them together.
+    return credentialsPath();
+}
+async function acquireLock() {
+    const path = lockPath();
+    await fs.mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    try {
+        // `wx` is the atomic create-or-fail; two processes cannot both succeed.
+        const h = await fs.open(path, "wx", 0o600);
+        await h.writeFile(String(process.pid));
+        await h.close();
+        return true;
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+        // A crashed process leaves its lock behind. Break it once it is clearly
+        // stale — a permanently stuck lock is worse than a rare double-refresh,
+        // because it bricks every command rather than costing one rotation.
+        try {
+            const st = await fs.stat(path);
+            if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+                await fs.rm(path, { force: true });
+                return acquireLock();
+            }
+        }
+        catch {
+            // The holder released it between our open and our stat. Fall through.
+        }
+        return false;
+    }
+}
+async function releaseLock() {
+    await fs.rm(lockPath(), { force: true }).catch(() => { });
+}
+/** Refresh under the lock; if another process holds it, wait for its result. */
+async function mintUnderLock() {
+    // ⚠ A3 — there used to be a `const before = await load()` here, costing a
+    // ~17 ms keychain exec on EVERY refresh. Its only consumer was a comparison
+    // whose `continue` was the last statement of the loop body, so taking the
+    // branch was indistinguishable from falling through: the whole thing was a
+    // no-op with a subprocess attached.
+    //
+    // The read the write-ahead scheme actually depends on is the one
+    // `mintAccessToken` performs UNDER the lock, which is untouched. If you want
+    // the original intent back, load AFTER a failed `acquireLock()` — never
+    // before the first attempt.
+    let before = null;
+    for (let attempt = 0; attempt < 40; attempt += 1) {
+        if (await acquireLock()) {
+            try {
+                return await mintAccessToken();
+            }
+            finally {
+                await releaseLock();
+            }
+        }
+        await new Promise((r) => setTimeout(r, 50));
+        // The winner writes the rotated credential before releasing, so a changed
+        // token means its refresh already succeeded.
+        //
+        // ⚠ LOOP BACK — DO NOT PRESENT IT HERE. An earlier version returned
+        // `mintAccessToken()` directly from this branch, outside the lock. With two
+        // processes that is safe, and with three it is not: a third rotation can
+        // supersede the token we just observed between this `load()` and the
+        // presentation, and the server (correctly fail-closed, since it cannot tell
+        // our process from an attacker) revokes the device.
+        //
+        // It is the same mistake as the fallback below, one level subtler — present
+        // a token only under the lock, always. Continuing costs one more 50ms tick
+        // and the next iteration acquires the lock immediately, because the winner
+        // has released it.
+        // Lazily captured on the FIRST contended pass only — by which point we are
+        // already paying a 50 ms tick, so the keychain read is free relative to it.
+        before ??= await load();
+        const now = await load();
+        if (now && before && now.refreshToken !== before.refreshToken) {
+            continue;
+        }
+    }
+    // ⚠ DO NOT PRESENT A TOKEN HERE.
+    //
+    // This used to fall through to `mintAccessToken()` on the grounds that "the
+    // server's grace covers the collision". That grace no longer exists, and under
+    // the current design presenting a token the winning process has already
+    // superseded is a PROVEN REPLAY — the server revokes the device. On a flaky
+    // link, a collision this code caused would sign the user's own laptop out.
+    //
+    // The server cannot help: it genuinely cannot tell our second process from an
+    // attacker, and fail-closed is the right choice for it. That makes this lock
+    // the real defence, so refusing is the correct outcome — a retry costs a
+    // second, a spurious revoke costs the session.
+    throw new Error("another `symbols` process is refreshing this device's credential. Try again in a moment.");
+}
+/**
+ * The mint currently in flight, if any. **A1 — single-flight.**
+ *
+ * ⚠ WITHOUT THIS, ONE PROCESS RACES ITSELF INTO ITS OWN CROSS-PROCESS LOCK.
+ *
+ * The MCP SDK dispatches `tools/call` concurrently. Measured on the shipped
+ * build: 12 parallel tool calls at session start produced **7** refresh POSTs
+ * and **5 hard failures** reading "another `symbols` process is refreshing this
+ * device's credential" — with exactly one process running. Every caller missed
+ * the cache, every caller called `mintUnderLock`, and the losers exhausted the
+ * 40 x 50 ms lock wait and gave up.
+ *
+ * Memoising the in-flight promise takes that to 1 refresh POST, 12/12 calls
+ * succeeding, and the slowest call from 2323 ms to 807 ms. It also cuts six
+ * credential rotations, which moves AWAY from the replay/revoke cliff rather
+ * than toward it.
+ *
+ * Two conditions, both load-bearing:
+ *   * cleared in a `finally`, so a rejected mint is never cached — one
+ *     transient failure would otherwise poison every later call in the session;
+ *   * keyed on `force`, so a caller that needs a genuinely fresh token cannot
+ *     be handed the stale in-flight one.
+ *
+ * The cross-process file lock is untouched. This stops a process racing ITSELF;
+ * that lock still stops two processes racing each other.
+ */
+let inFlight = null;
+async function accessToken(force = false) {
+    if (!force && cached && cached.expiresAt - EXPIRY_SKEW_MS > Date.now()) {
+        return cached.token;
+    }
+    if (inFlight && (inFlight.force || !force)) {
+        return (await inFlight.promise).token;
+    }
+    const promise = mintUnderLock();
+    inFlight = { force, promise };
+    try {
+        cached = await promise;
+        return cached.token;
+    }
+    finally {
+        // ⚠ ALWAYS, INCLUDING ON REJECTION. A cached rejected promise would make
+        // every subsequent call in this process fail with a stale error.
+        if (inFlight?.promise === promise)
+            inFlight = null;
+    }
+}
+/** Drop the cached access token — used by `logout`, and after a 401. */
+export function forgetAccessToken() {
+    cached = null;
+    retriedGeneration = null;
+}
+/**
+ * May a 401 be retried with a freshly minted token?
+ *
+ * ⚠ ONE DECISION, TWO CALLERS. `request()` and `requestBytes()` each grew their
+ * own version and drifted; `requestBytes` ended up retrying unconditionally,
+ * which is the bug `request()` had already been fixed for.
+ *
+ * A forced re-mint is not free: it is a full refresh, so it ROTATES the refresh
+ * chain and writes the credential store. Retrying a 401 that the token cannot
+ * explain — an unscoped route, a revoked device — buys nothing and costs a
+ * rotation.
+ *
+ * ⚠ A5 — THIS IS PER TOKEN GENERATION, NOT PER 5 SECONDS, AND THAT MATTERS.
+ *
+ * The previous rule was "retry if the token is older than 5 s". In a one-shot
+ * command that is nearly always false, so it worked. In `symbols mcp` the token
+ * lives ~14 minutes, so the guard was effectively OFF: every failing tool call
+ * ran GET(401) -> POST /refresh -> GET(401). Measured: 6 failing tool calls
+ * produced 17 HTTP requests and 6 refreshes.
+ *
+ * `auth_cli.rs:192` caps refresh at 60/min per IP. So 60 failing tool calls in
+ * a minute would 429 the refresh endpoint — after which EVERY tool fails with
+ * `refresh failed (429)`. A latency wart on the one-shot path was a
+ * self-inflicted session outage on the agent path.
+ *
+ * One retry per generation preserves the case that is real — the token expired
+ * server-side mid-flight — and refuses the loop.
+ */
+let retriedGeneration = null;
+export function shouldRetryAfter401(status, anonymous) {
+    if (status !== 401 || anonymous || cached === null)
+        return false;
+    return retriedGeneration !== cached.token;
+}
+/**
+ * Mark the token we just force-minted as having spent its retry.
+ *
+ * ⚠ THIS IS THE HALF I GOT WRONG FIRST, and the test caught it. Marking the
+ * OLD token was useless: the retry immediately mints a new one, and the new
+ * token did not match the marker, so the very next 401 retried again. Six
+ * failing calls still burned six rotations — the exact behaviour A5 exists to
+ * stop — and only a behavioural test showed it. A source assertion that the
+ * guard "is generation-based" would have passed.
+ *
+ * Marking the NEW token is what makes a generation finite: it gets one forced
+ * re-mint, and a 401 after that is understood to be about something other than
+ * staleness. A genuinely new token — minted on natural expiry ~15 min later —
+ * starts with its retry unspent.
+ */
+function markRetryConsumed() {
+    retriedGeneration = cached?.token ?? null;
+}
+export async function request(path, opts = {}) {
+    const send = async (bearer) => {
+        const headers = { ...opts.headers };
+        if (bearer)
+            headers["authorization"] = `Bearer ${bearer}`;
+        if (opts.body !== undefined)
+            headers["content-type"] = "application/json";
+        return rawFetch(path, {
+            method: opts.method ?? "GET",
+            headers,
+            ...(opts.body === undefined ? {} : { body: JSON.stringify(opts.body) }),
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        });
+    };
+    let res = await send(opts.anonymous ? null : await accessToken());
+    // Exactly one retry, and only on 401. The access token may have been minted
+    // just before a server-side rotation; a second 401 is a real refusal and
+    // looping on it would hammer the refresh endpoint.
+    // ⚠ RETRY ONLY IF THE TOKEN COULD PLAUSIBLY BE THE PROBLEM.
+    //
+    // A forced re-mint is not free: it is a full refresh, which ROTATES the
+    // refresh chain and writes the credential store. An earlier version retried on
+    // every 401 unconditionally, so each failing call cost TWO rotations — and a
+    // sweep of the 12 MCP tools against a surface that 401s (as it does until
+    // P1's extractor sweep reaches a route) burned ~24 rotations, measurably
+    // against the 60/min per-IP cap SEC-3 added.
+    //
+    // If the access token was minted seconds ago it is not stale, so the 401 is
+    // about something else — an unscoped route, a revoked device — and re-minting
+    // cannot help. Retry only when the token is old enough for expiry or a
+    // server-side rotation to be a credible explanation.
+    if (shouldRetryAfter401(res.status, opts.anonymous === true)) {
+        forgetAccessToken();
+        res = await send(await accessToken(true));
+        markRetryConsumed();
+    }
+    if (res.status === 426) {
+        const body = await res.text().catch(() => "");
+        throw new ApiError(426, path, `this CLI version (${CLI_VERSION}) is no longer supported. ` +
+            `Upgrade with \`npm i -g @symbols-cli/cli\`.${body ? ` ${body}` : ""}`);
+    }
+    const text = await res.text();
+    let parsed = null;
+    if (text) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = text;
+        }
+    }
+    if (!res.ok) {
+        const detail = parsed && typeof parsed === "object" && "detail" in parsed
+            ? String(parsed.detail)
+            : typeof parsed === "string" && parsed
+                ? parsed
+                : res.statusText;
+        throw new ApiError(res.status, path, `${res.status} ${detail}`);
+    }
+    return { status: res.status, body: parsed };
+}
+/**
+ * The same request, returning RAW BYTES.
+ *
+ * Added by P2 for the skills bundle, which is a gzipped tar: `request` calls
+ * `res.text()`, and running a tarball through UTF-8 decoding corrupts it
+ * silently — the sha256 would fail with no hint as to why.
+ *
+ * It goes through `rawFetch` (host pinning) and `accessToken` (the rotation
+ * lock) for the same reason every other call does: a second fetch path would be
+ * a second place for S3 to be forgotten.
+ */
+export async function requestBytes(path, opts = {}) {
+    const send = async (bearer) => {
+        const headers = { ...opts.headers };
+        if (bearer)
+            headers["authorization"] = `Bearer ${bearer}`;
+        return rawFetch(path, {
+            method: opts.method ?? "GET",
+            headers,
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        });
+    };
+    let res = await send(opts.anonymous ? null : await accessToken());
+    // ⚠ A4 — THE SAME HELPER `request()` USES. This path used to retry on EVERY
+    // 401 unconditionally, reintroducing the exact bug `request()` documents and
+    // guards: one 401 here costs TWO full credential rotations, and both callers
+    // (`bundle.ts:424`, `:428`) are on `symbols up` / `symbols update`. Sharing
+    // one decision function is what stops the two paths drifting apart again.
+    if (shouldRetryAfter401(res.status, opts.anonymous === true)) {
+        forgetAccessToken();
+        res = await send(await accessToken(true));
+        markRetryConsumed();
+    }
+    if (!res.ok) {
+        throw new ApiError(res.status, path, `${res.status} ${res.statusText}`);
+    }
+    return { status: res.status, bytes: Buffer.from(await res.arrayBuffer()) };
+}
+/** For `login`, which has no credential yet and authenticates with the code. */
+export async function requestAnonymous(path, opts = {}) {
+    return request(path, { ...opts, anonymous: true });
+}