@botiverse/hands-cli 0.5.15 → 0.5.16

package/dist/lib/agent_env.d.ts

@@ -0,0 +1,33 @@
+export declare const HANDS_SERVICE = "hands-4cc7a2";
+export interface AgentEnv {
+    transportDir: string;
+    slockHome: string;
+    agentId: string;
+    raftBin: string;
+}
+export type Admission = {
+    kind: "human";
+} | {
+    kind: "agent";
+    env: AgentEnv;
+} | {
+    kind: "fail_closed";
+    reason: string;
+};
+/**
+ * Decide human vs agent vs fail-closed. Once ANY agent marker is present we never
+ * return `human` — a partial/invalid environment fails closed rather than silently
+ * using ambient human credentials.
+ */
+export declare function admitAgent(env?: NodeJS.ProcessEnv): Admission;
+/** Canonical per-agent store path, with slug validation + root containment. */
+export declare function agentAuthPath(a: AgentEnv, service?: string): string;
+/**
+ * Read the stored Hands access token for this agent, or null if absent/unreadable.
+ * Dependency-free (fs + path only) so `config.ts` can call it without an import cycle
+ * through the api client. Auto-refresh-on-expiry lands in CP3 checkpoint-2.
+ */
+export declare function readAgentAccessToken(a: AgentEnv, service?: string): string | null;
+/** Read the api base recorded in the agent store (so the resolver never reads the
+ *  human config in agent mode), or null. */
+export declare function readAgentApiBase(a: AgentEnv, service?: string): string | null;

package/dist/lib/agent_env.js

@@ -0,0 +1,112 @@
+/**
+ * Agent runtime admission + credential-store path (RFC 057 agent login, CP3).
+ *
+ * Admission is TRI-STATE (Volta): no markers → normal human/CI; any agent marker but
+ * incomplete/invalid/no-executable-wrapper → FAIL CLOSED (never fall back to human
+ * credentials); complete + valid → agent mode, pinned to the exact `raft` wrapper
+ * inside $SLOCK_CLI_TRANSPORT_DIR (never the PATH `raft`).
+ */
+import { accessSync, constants, existsSync, readFileSync, statSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+// Compiled-fixed exact installed Raft client key. NOT environment-overridable: it is
+// both the invoke target AND part of the on-disk store path, so an override would be a
+// cross-service / path-injection vector. Tests inject a service via function params.
+export const HANDS_SERVICE = "hands-4cc7a2";
+// RFC 057 service slug.
+const SERVICE_SLUG_RE = /^[a-z0-9][a-z0-9._-]{0,79}$/;
+// Daemon-issued agent id: a conservative safe token (no separators/traversal).
+const AGENT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function isExecutableFile(p) {
+    try {
+        if (!statSync(p).isFile())
+            return false;
+        accessSync(p, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decide human vs agent vs fail-closed. Once ANY agent marker is present we never
+ * return `human` — a partial/invalid environment fails closed rather than silently
+ * using ambient human credentials.
+ */
+export function admitAgent(env = process.env) {
+    const transportDir = env.SLOCK_CLI_TRANSPORT_DIR;
+    const slockHome = env.SLOCK_HOME;
+    const agentId = env.SLOCK_AGENT_ID;
+    if (!transportDir && !slockHome && !agentId)
+        return { kind: "human" };
+    if (!transportDir || !slockHome || !agentId) {
+        return { kind: "fail_closed", reason: "incomplete agent markers" };
+    }
+    if (!AGENT_ID_RE.test(agentId)) {
+        return { kind: "fail_closed", reason: "invalid SLOCK_AGENT_ID" };
+    }
+    const raftBin = join(transportDir, "raft");
+    if (!isExecutableFile(raftBin)) {
+        return { kind: "fail_closed", reason: "raft wrapper missing or not executable in transport dir" };
+    }
+    return { kind: "agent", env: { transportDir, slockHome, agentId, raftBin } };
+}
+/** Canonical per-agent store path, with slug validation + root containment. */
+export function agentAuthPath(a, service = HANDS_SERVICE) {
+    if (!SERVICE_SLUG_RE.test(service))
+        throw new Error("invalid service slug");
+    if (!AGENT_ID_RE.test(a.agentId))
+        throw new Error("invalid agent id");
+    const root = resolve(a.slockHome, "agents", a.agentId, "integrations");
+    const path = resolve(root, service, "auth.json");
+    // Belt-and-suspenders containment (agentId/service are already regex-validated).
+    if (path !== join(root, service, "auth.json") || !path.startsWith(root + sep)) {
+        throw new Error("resolved store path escapes the integrations root");
+    }
+    return path;
+}
+/**
+ * Read the stored Hands access token for this agent, or null if absent/unreadable.
+ * Dependency-free (fs + path only) so `config.ts` can call it without an import cycle
+ * through the api client. Auto-refresh-on-expiry lands in CP3 checkpoint-2.
+ */
+export function readAgentAccessToken(a, service = HANDS_SERVICE) {
+    let path;
+    try {
+        path = agentAuthPath(a, service);
+    }
+    catch {
+        return null;
+    }
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return typeof parsed?.access_token === "string" && parsed.access_token.length > 0
+            ? parsed.access_token
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the api base recorded in the agent store (so the resolver never reads the
+ *  human config in agent mode), or null. */
+export function readAgentApiBase(a, service = HANDS_SERVICE) {
+    let path;
+    try {
+        path = agentAuthPath(a, service);
+    }
+    catch {
+        return null;
+    }
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return typeof parsed?.api_base === "string" && parsed.api_base.length > 0 ? parsed.api_base : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=agent_env.js.map

package/dist/lib/agent_env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent_env.js","sourceRoot":"","sources":["../../src/lib/agent_env.ts"],"names":[],"mappings":"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"}

package/dist/lib/agent_refresh.d.ts

@@ -0,0 +1,32 @@
+import { type AgentEnv } from "./agent_env.js";
+export declare const REFRESH_SKEW_MS = 60000;
+export interface RefreshOptions {
+    service?: string;
+    now?: number;
+    fetchImpl?: typeof fetch;
+    /** Injectable sleep for tests (defaults to real setTimeout). */
+    sleepImpl?: (ms: number) => Promise<void>;
+    /** Injectable refresh deadline for tests (defaults to REFRESH_DEADLINE_MS). */
+    deadlineMs?: number;
+}
+/**
+ * Return a valid access token, refreshing (single-flight) if it is within the skew
+ * window. Returns null if there is no stored session (caller must `hands login`).
+ */
+export declare function getFreshAgentAccessToken(a: AgentEnv, opts?: RefreshOptions): Promise<string | null>;
+/**
+ * Force one refresh (used on a 401 even if the token looked unexpired), single-flight.
+ * Returns null if there is no stored session.
+ */
+export declare function forceRefreshAgentToken(a: AgentEnv, opts?: RefreshOptions): Promise<string | null>;
+/** Delete the lock only if it still carries OUR owner id (never a foreign holder's). */
+export declare function releaseOwnLock(lock: string, ownerId: string): void;
+/**
+ * Recover a lock whose owner process is provably dead and acquire it, serialized by an
+ * exclusive reaper fence. Judge-dead → unlink → re-acquire all happen WHILE the fence is
+ * held, so at most one recoverer reaps-and-rebuilds — two concurrent recoverers can never
+ * both re-acquire (→ never double-rotate). A LIVE owner (incl. suspended/stalled — pid
+ * still exists) is never touched. Any uncertainty fails closed. Returns true iff WE now
+ * hold the main lock carrying `ownerId`; false → the caller is a loser.
+ */
+export declare function acquireIfDeadOwner(lock: string, ownerId: string): boolean;

package/dist/lib/agent_refresh.js

@@ -0,0 +1,323 @@
+/**
+ * Agent token auto-refresh + cross-process single-flight (RFC 057, CP3 checkpoint-2).
+ *
+ * The agent access token is short-lived; a long-lived rotating refresh token in the
+ * store renews it. This module:
+ *   - refreshes PROACTIVELY when the access token is within a skew window of expiry,
+ *     and REACTIVELY once after a 401 (driven by api.ts);
+ *   - serializes refresh across concurrent `hands` processes sharing one $SLOCK_HOME
+ *     via an O_EXCL lock. A concurrent loser re-reads the store and returns ONLY the
+ *     strictly-newer session the winner persisted (a changed refresh token vs the one
+ *     it started with); it NEVER rotates in parallel and never re-hands the token it
+ *     came in with (a double-rotate trips the server's refresh-reuse detection and
+ *     chain-revokes the family; re-handing a just-401'd token would 401 again).
+ *
+ * Lock safety:
+ *   - the refresh op (fetch + bounded body read + parse + persist) is hard-aborted at a
+ *     deadline, so a live holder cannot hold the lock forever;
+ *   - a lock is broken ONLY when its owner process is provably DEAD (`process.kill(pid,0)`
+ *     → ESRCH) — never on elapsed time, so a suspended / stalled but live holder is never
+ *     stolen;
+ *   - dead-lock recovery is serialized by an exclusive reaper fence and the main lock is
+ *     re-acquired WHILE the fence is held, so two concurrent recoverers can never both
+ *     reap-and-rebuild (→ never double-rotate);
+ *   - any uncertainty (unparseable owner, non-ENOENT read error, contended/live fence)
+ *     fails closed: the caller becomes a loser rather than risk an unsafe break.
+ *
+ * It does its own fetch (not the api client) to avoid an import cycle, and never echoes
+ * response bodies in errors.
+ */
+import { openSync, closeSync, writeSync, readFileSync, existsSync, unlinkSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { agentAuthPath, HANDS_SERVICE, } from "./agent_env.js";
+import { parseAgentSession, writeAgentSession, readBoundedText, } from "./agent_auth.js";
+// Refresh when the access token expires within this window (or is already expired).
+export const REFRESH_SKEW_MS = 60_000;
+// The whole refresh op (fetch + bounded read + parse + persist) is aborted at this
+// deadline. Breaking a lock is NOT time-based, though — only a provably-dead owner is.
+const REFRESH_DEADLINE_MS = 20_000;
+const LOCK_WAIT_MS = 25_000; // how long a loser waits for the winner's strictly-newer session
+const LOCK_POLL_MS = 100;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function newOwnerId() {
+    return `${process.pid}:${randomBytes(12).toString("hex")}`;
+}
+function readStore(a, service) {
+    let path;
+    try {
+        path = agentAuthPath(a, service);
+    }
+    catch {
+        return null;
+    }
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function accessExpiresWithinSkew(store, now) {
+    const exp = Date.parse(store.access_expires_at);
+    return !Number.isFinite(exp) || exp - now <= REFRESH_SKEW_MS;
+}
+function accessExpired(store, now) {
+    const exp = Date.parse(store.access_expires_at);
+    return !Number.isFinite(exp) || exp <= now;
+}
+function lockPath(a, service) {
+    return join(dirname(agentAuthPath(a, service)), ".auth.refresh.lock");
+}
+/**
+ * POST the refresh token, validate the session, atomically persist it. Own fetch,
+ * hard-aborted at `deadlineMs` across the WHOLE operation (fetch + bounded body read +
+ * parse + persist), never following a redirect (a 307/308 would forward the refresh
+ * token), and never echoing the body.
+ */
+async function rotate(a, service, store, now, fetchImpl, deadlineMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deadlineMs);
+    try {
+        const res = await fetchImpl(new URL("/api/auth/agent/refresh", store.api_base).toString(), {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({ schema: "raft-cli-agent-refresh.v1", refresh_token: store.refresh_token }),
+            signal: controller.signal,
+            redirect: "manual",
+        });
+        if (!res.ok) {
+            // `manual` leaves a 3xx as a non-ok status. Stable reason only; never echo the body.
+            throw new Error(`agent-login: token refresh failed (HTTP ${res.status})`);
+        }
+        const text = await readBoundedText(res, controller);
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new Error("agent-login: refresh response was not JSON");
+        }
+        const session = parseAgentSession(body, now);
+        writeAgentSession(a, service, session, store.api_base, () => new Date(now).toISOString());
+        return session;
+    }
+    finally {
+        // Deadline stays armed across fetch + bounded read + parse + persist.
+        clearTimeout(timer);
+    }
+}
+/**
+ * Return a valid access token, refreshing (single-flight) if it is within the skew
+ * window. Returns null if there is no stored session (caller must `hands login`).
+ */
+export async function getFreshAgentAccessToken(a, opts = {}) {
+    const service = opts.service ?? HANDS_SERVICE;
+    const now = opts.now ?? Date.now();
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleepImpl = opts.sleepImpl ?? sleep;
+    const deadlineMs = opts.deadlineMs ?? REFRESH_DEADLINE_MS;
+    const store = readStore(a, service);
+    if (!store)
+        return null;
+    if (!accessExpiresWithinSkew(store, now))
+        return store.access_token; // still fresh
+    return singleFlightRefresh(a, service, store, now, fetchImpl, sleepImpl, /*force*/ false, deadlineMs);
+}
+/**
+ * Force one refresh (used on a 401 even if the token looked unexpired), single-flight.
+ * Returns null if there is no stored session.
+ */
+export async function forceRefreshAgentToken(a, opts = {}) {
+    const service = opts.service ?? HANDS_SERVICE;
+    const now = opts.now ?? Date.now();
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleepImpl = opts.sleepImpl ?? sleep;
+    const deadlineMs = opts.deadlineMs ?? REFRESH_DEADLINE_MS;
+    const store = readStore(a, service);
+    if (!store)
+        return null;
+    return singleFlightRefresh(a, service, store, now, fetchImpl, sleepImpl, /*force*/ true, deadlineMs);
+}
+async function singleFlightRefresh(a, service, baseline, now, fetchImpl, sleepImpl, force, deadlineMs) {
+    const lock = lockPath(a, service);
+    const ownerId = newOwnerId();
+    let acquired;
+    try {
+        const fd = openSync(lock, "wx"); // fast path: no lock present
+        try {
+            writeSync(fd, ownerId);
+        }
+        finally {
+            try {
+                closeSync(fd);
+            }
+            catch { /* ignore */ }
+        }
+        acquired = true;
+    }
+    catch (e) {
+        if (e?.code !== "EEXIST")
+            throw e;
+        // A lock exists: recover it only if its owner is provably dead, under an exclusive
+        // fence, re-acquiring the main lock while the fence is held. Anything else → loser.
+        acquired = acquireIfDeadOwner(lock, ownerId);
+        if (!acquired)
+            return waitForNewerSession(a, service, baseline, now, force, sleepImpl);
+    }
+    // Winner: we hold `lock` carrying ownerId.
+    try {
+        const fresh = readStore(a, service);
+        if (!fresh)
+            return null;
+        // A prior holder may have refreshed while we blocked; only rotate if still needed.
+        if (!force && !accessExpiresWithinSkew(fresh, now))
+            return fresh.access_token;
+        const session = await rotate(a, service, fresh, now, fetchImpl, deadlineMs);
+        return session.access_token;
+    }
+    finally {
+        releaseOwnLock(lock, ownerId);
+    }
+}
+/** Delete the lock only if it still carries OUR owner id (never a foreign holder's). */
+export function releaseOwnLock(lock, ownerId) {
+    try {
+        if (readFileSync(lock, "utf8") === ownerId)
+            unlinkSync(lock);
+    }
+    catch {
+        // already gone, unreadable, or replaced by another owner — leave it be.
+    }
+}
+/**
+ * Recover a lock whose owner process is provably dead and acquire it, serialized by an
+ * exclusive reaper fence. Judge-dead → unlink → re-acquire all happen WHILE the fence is
+ * held, so at most one recoverer reaps-and-rebuilds — two concurrent recoverers can never
+ * both re-acquire (→ never double-rotate). A LIVE owner (incl. suspended/stalled — pid
+ * still exists) is never touched. Any uncertainty fails closed. Returns true iff WE now
+ * hold the main lock carrying `ownerId`; false → the caller is a loser.
+ */
+export function acquireIfDeadOwner(lock, ownerId) {
+    const ffd = acquireReaperFence(`${lock}.reap`);
+    if (ffd === null)
+        return false; // live/contended/uncertain fence → loser
+    try {
+        let owner = "";
+        try {
+            owner = readFileSync(lock, "utf8");
+        }
+        catch (e) {
+            // Only "already gone" is safe to proceed on; any other error is uncertain → loser.
+            if (e?.code !== "ENOENT")
+                return false;
+        }
+        if (owner) {
+            const pid = ownerPid(owner);
+            if (pid === null || ownerAlive(pid))
+                return false; // live / uncertain owner → loser
+            try {
+                unlinkSync(lock);
+            }
+            catch { /* vanished / already handled */ }
+        }
+        // Re-acquire the main lock while STILL holding the fence, so no other recoverer can
+        // rebuild it underneath us.
+        let fd;
+        try {
+            fd = openSync(lock, "wx");
+        }
+        catch (e) {
+            if (e?.code === "EEXIST")
+                return false; // lost the race → loser
+            throw e;
+        }
+        try {
+            writeSync(fd, ownerId);
+        }
+        finally {
+            try {
+                closeSync(fd);
+            }
+            catch { /* ignore */ }
+        }
+        return true;
+    }
+    finally {
+        try {
+            closeSync(ffd);
+        }
+        catch { /* ignore */ }
+        try {
+            unlinkSync(`${lock}.reap`);
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Acquire the exclusive reaper fence via a single O_EXCL create. On EEXIST — a reaper is
+ * active, OR one crashed and left the fence — we ALWAYS fail closed (return null → loser).
+ * We deliberately do NOT auto-recover a leftover fence: reading its pid and unlinking it
+ * would recurse the very reap race the fence exists to prevent (two recoverers both unlink
+ * + recreate, then each deletes the other's live fence). A crashed reaper — the fence is
+ * held only across synchronous fs calls, never I/O — leaves a diagnosable fence for manual
+ * cleanup, the agreed "prefer fail-closed on reaper residue" over a second grabbable lock.
+ * Kernel O_EXCL is the sole mutual exclusion; nothing here reads-pid-then-unlinks.
+ */
+function acquireReaperFence(fence) {
+    try {
+        const fd = openSync(fence, "wx");
+        try {
+            writeSync(fd, newOwnerId());
+        }
+        catch { /* diagnostic marker only; ignore */ }
+        return fd;
+    }
+    catch {
+        return null; // EEXIST or any error → fail closed (loser); never recover a leftover fence
+    }
+}
+function ownerPid(owner) {
+    const m = /^(\d+):/.exec(owner);
+    if (!m)
+        return null;
+    const pid = Number(m[1]);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+function ownerAlive(pid) {
+    try {
+        process.kill(pid, 0); // signal 0: liveness probe, delivers nothing
+        return true;
+    }
+    catch (e) {
+        if (e?.code === "ESRCH")
+            return false; // no such process → dead
+        return true; // EPERM (exists) or anything unexpected → fail closed = treat as alive
+    }
+}
+/**
+ * Loser path: poll the store for the winner's strictly-newer session, identified by a
+ * refresh token that differs from the one we started with (`baseline`). Never rotates
+ * here. On timeout it FAILS rather than hand back the token we came in with; a proactive
+ * caller may still use a genuinely-unexpired current token, but a forced (post-401)
+ * caller always fails — re-handing a 401'd token would just 401 again.
+ */
+async function waitForNewerSession(a, service, baseline, now, force, sleepImpl) {
+    // Bound by poll count (not wall-clock) so it is deterministic under an injected sleep in
+    // tests, while keeping the same real-time budget in production.
+    const maxPolls = Math.ceil(LOCK_WAIT_MS / LOCK_POLL_MS);
+    for (let i = 0; i < maxPolls; i += 1) {
+        await sleepImpl(LOCK_POLL_MS);
+        const cur = readStore(a, service);
+        if (cur && cur.refresh_token !== baseline.refresh_token) {
+            return cur.access_token; // the winner rotated: a strictly-newer session is persisted
+        }
+    }
+    const cur = readStore(a, service);
+    if (!force && cur && !accessExpired(cur, now))
+        return cur.access_token;
+    throw new Error("agent-login: timed out waiting for a concurrent token refresh");
+}
+//# sourceMappingURL=agent_refresh.js.map

package/dist/lib/agent_refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent_refresh.js","sourceRoot":"","sources":["../../src/lib/agent_refresh.ts"],"names":[],"mappings":"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"}

package/dist/lib/api.d.ts

@@ -7,6 +7,14 @@
  * Endpoints called by the CLI use `requireAppRole("viewer")` or
  * `requireOrgRole("member")` after the user has logged in via `hands login`.
  */
+/**
+ * Run a bearer-parameterized request with agent-aware auth, shared by every CLI HTTP
+ * path (`apiRequest`, `apiUploadFile`, and `hands api`): resolve the bearer (proactive
+ * refresh in agent mode), and on a 401 in agent mode force ONE refresh and retry once.
+ * `doFetch` MUST build a fresh request each call — a request body stream cannot be reused
+ * across attempts, so callers that send a body rebuild it inside the thunk.
+ */
+export declare function agentAwareFetch(doFetch: (bearer: string | undefined) => Promise<Response>): Promise<Response>;
 export declare class QuiverApiError extends Error {
     readonly status: number;
     readonly body: unknown;

package/dist/lib/api.js

@@ -8,10 +8,47 @@
  * `requireOrgRole("member")` after the user has logged in via `hands login`.
  */
 import { resolveApiBase, resolveAuthToken } from "./config.js";
+import { admitAgent } from "./agent_env.js";
+import { getFreshAgentAccessToken, forceRefreshAgentToken } from "./agent_refresh.js";
 import { readEnv } from "./env.js";
 import { Blob } from "node:buffer";
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
+/**
+ * Resolve the bearer for a request. In a managed agent this proactively refreshes the
+ * stored Hands token when it is near expiry (single-flight); a broken agent env yields
+ * no token (fail closed). Human/CI use the ordinary resolver.
+ */
+async function resolveBearer() {
+    const admission = admitAgent();
+    if (admission.kind === "agent") {
+        return (await getFreshAgentAccessToken(admission.env)) ?? undefined;
+    }
+    if (admission.kind === "fail_closed")
+        return undefined;
+    return resolveAuthToken();
+}
+/**
+ * Run a bearer-parameterized request with agent-aware auth, shared by every CLI HTTP
+ * path (`apiRequest`, `apiUploadFile`, and `hands api`): resolve the bearer (proactive
+ * refresh in agent mode), and on a 401 in agent mode force ONE refresh and retry once.
+ * `doFetch` MUST build a fresh request each call — a request body stream cannot be reused
+ * across attempts, so callers that send a body rebuild it inside the thunk.
+ */
+export async function agentAwareFetch(doFetch) {
+    let res = await doFetch(await resolveBearer());
+    // The proactive refresh in resolveBearer covers near-expiry; this covers a token
+    // rejected despite looking unexpired (server-side revocation, clock skew).
+    if (res.status === 401) {
+        const admission = admitAgent();
+        if (admission.kind === "agent") {
+            const refreshed = await forceRefreshAgentToken(admission.env);
+            if (refreshed)
+                res = await doFetch(refreshed);
+        }
+    }
+    return res;
+}
 export class QuiverApiError extends Error {
     status;
     body;
@@ -38,23 +75,26 @@ export async function apiRequest(path, opts = {}) {
             url.searchParams.set(k, String(v));
         }
     }
-    const headers = {
+    const baseHeaders = {
         accept: "application/json",
     };
-    const bearer = resolveAuthToken();
-    if (bearer)
-        headers.authorization = `Bearer ${bearer}`;
     let body;
     if (opts.body !== undefined) {
-        headers["content-type"] = "application/json";
+        baseHeaders["content-type"] = "application/json";
         body = JSON.stringify(opts.body);
     }
-    const res = await fetch(url.toString(), {
-        method: opts.method ?? "GET",
-        headers,
-        ...(body !== undefined ? { body } : {}),
-        ...(opts.signal ? { signal: opts.signal } : {}),
-    });
+    const doFetch = (bearer) => {
+        const headers = { ...baseHeaders };
+        if (bearer)
+            headers.authorization = `Bearer ${bearer}`;
+        return fetch(url.toString(), {
+            method: opts.method ?? "GET",
+            headers,
+            ...(body !== undefined ? { body } : {}),
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        });
+    };
+    const res = await agentAwareFetch(doFetch);
     if (readEnv("VERBOSE") === "1") {
         console.error(`> ${opts.method ?? "GET"} ${url}`);
         console.error(`< ${res.status}`);
@@ -81,19 +121,18 @@ export async function apiRequest(path, opts = {}) {
 }
 export async function apiUploadFile(path, filePath, fieldName = "apk") {
     const url = new URL(path.startsWith("/") ? path : `/${path}`, getApiBase());
-    const form = new FormData();
     const bytes = await readFile(filePath);
-    form.append(fieldName, new Blob([bytes]), basename(filePath));
-    const headers = {
-        accept: "application/json",
-    };
-    const bearer = resolveAuthToken();
-    if (bearer)
-        headers.authorization = `Bearer ${bearer}`;
-    const res = await fetch(url.toString(), {
-        method: "POST",
-        headers,
-        body: form,
+    const name = basename(filePath);
+    // Upload is a primary product path, so it uses the SAME agent-aware request + one-401
+    // as every other call. The multipart body is rebuilt per attempt: a body stream can't
+    // be reused, and agent mode may retry once after a 401.
+    const res = await agentAwareFetch((bearer) => {
+        const form = new FormData();
+        form.append(fieldName, new Blob([bytes]), name);
+        const headers = { accept: "application/json" };
+        if (bearer)
+            headers.authorization = `Bearer ${bearer}`;
+        return fetch(url.toString(), { method: "POST", headers, body: form });
     });
     if (readEnv("VERBOSE") === "1") {
         console.error(`> POST ${url}`);