@botiverse/hands-cli 0.5.14 → 0.5.16

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}`);

package/dist/lib/api.js.map

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

package/dist/lib/config.d.ts

@@ -1,14 +1,19 @@
 /**
- * Config + auth storage for the quiver CLI.
+ * Config + auth storage for the hands CLI.
  *
  * Resolution order for any setting (first wins):
  *   1. CLI flag (--api, --token, ...)
  *   2. Environment variable (HANDS_API, HANDS_AUTH_TOKEN, ...)
- *   3. File at $XDG_CONFIG_HOME/quiver/auth.json (default ~/.config/quiver/auth.json)
+ *   3. Human config file at $XDG_CONFIG_HOME/hands/auth.json (default ~/.config/hands/auth.json)
  *
- * The config file holds:
- *   - apiBase: the Quiver Worker URL the CLI talks to
+ * Agent mode (managed Raft agent) is ISOLATED: it uses ONLY the per-agent Hands token
+ * under $SLOCK_HOME and never reads/writes the human config or ambient env token. A
+ * broken (partial/invalid) agent environment fails closed rather than falling back.
+ *
+ * The human config file holds:
+ *   - apiBase: the Hands Worker URL the CLI talks to
  *   - authToken: the signed Hands JWT returned after `hands login`
+ * A legacy ~/.config/quiver/auth.json is migrated to the hands path on first use.
  */
 export interface CliConfig {
     apiBase?: string;
@@ -16,6 +21,8 @@ export interface CliConfig {
     /** Legacy field read during migration from cookie-backed sessions. */
     sessionCookie?: string;
 }
+/** Canonical human config path (post-rename). */
+export declare function configPath(): string;
 export declare function getConfig(): CliConfig;
 export declare function saveConfig(patch: Partial<CliConfig>): CliConfig;
 export declare function clearConfig(): void;

package/dist/lib/config.js

@@ -1,37 +1,67 @@
 /**
- * Config + auth storage for the quiver CLI.
+ * Config + auth storage for the hands CLI.
  *
  * Resolution order for any setting (first wins):
  *   1. CLI flag (--api, --token, ...)
  *   2. Environment variable (HANDS_API, HANDS_AUTH_TOKEN, ...)
- *   3. File at $XDG_CONFIG_HOME/quiver/auth.json (default ~/.config/quiver/auth.json)
+ *   3. Human config file at $XDG_CONFIG_HOME/hands/auth.json (default ~/.config/hands/auth.json)
  *
- * The config file holds:
- *   - apiBase: the Quiver Worker URL the CLI talks to
+ * Agent mode (managed Raft agent) is ISOLATED: it uses ONLY the per-agent Hands token
+ * under $SLOCK_HOME and never reads/writes the human config or ambient env token. A
+ * broken (partial/invalid) agent environment fails closed rather than falling back.
+ *
+ * The human config file holds:
+ *   - apiBase: the Hands Worker URL the CLI talks to
  *   - authToken: the signed Hands JWT returned after `hands login`
+ * A legacy ~/.config/quiver/auth.json is migrated to the hands path on first use.
  */
 import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
 import { readEnv } from "./env.js";
+import { admitAgent, readAgentAccessToken, readAgentApiBase, } from "./agent_env.js";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 const DEFAULT_API_BASE = "https://hands.build";
-function configPath() {
+function configDir() {
     const xdg = process.env.XDG_CONFIG_HOME;
-    const dir = xdg && xdg.length > 0 ? xdg : join(homedir(), ".config");
-    return join(dir, "quiver", "auth.json");
+    return xdg && xdg.length > 0 ? xdg : join(homedir(), ".config");
 }
-export function getConfig() {
-    const path = configPath();
+/** Canonical human config path (post-rename). */
+export function configPath() {
+    return join(configDir(), "hands", "auth.json");
+}
+/** Legacy path from before the quiver→hands rename; read once, then migrated. */
+function legacyConfigPath() {
+    return join(configDir(), "quiver", "auth.json");
+}
+function readConfigFile(path) {
     if (!existsSync(path))
-        return {};
+        return null;
     try {
-        const raw = readFileSync(path, "utf8");
-        const parsed = JSON.parse(raw);
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
         return parsed ?? {};
     }
     catch {
+        return null;
+    }
+}
+export function getConfig() {
+    const path = configPath();
+    const current = readConfigFile(path);
+    if (current)
+        return current;
+    // One-time migration from the legacy quiver path. On ANY failure keep the old file
+    // and old credentials (return the legacy config; do not delete or corrupt it).
+    const legacy = readConfigFile(legacyConfigPath());
+    if (!legacy)
         return {};
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(legacy, null, 2) + "\n", { mode: 0o600 });
+    }
+    catch {
+        return legacy; // migration failed → keep using the legacy credentials
     }
+    return legacy;
 }
 export function saveConfig(patch) {
     const current = getConfig();
@@ -56,13 +86,31 @@ export function resolveApiBase() {
     const env = readEnv("API");
     if (env)
         return env;
+    const admission = admitAgent();
+    if (admission.kind === "agent") {
+        // Agent mode: the api base comes from the agent store (recorded at login), never
+        // the human config file.
+        return readAgentApiBase(admission.env) ?? DEFAULT_API_BASE;
+    }
+    if (admission.kind === "fail_closed") {
+        return DEFAULT_API_BASE; // broken agent env: no human config fallback
+    }
     const cfg = getConfig();
     if (cfg.apiBase)
         return cfg.apiBase;
     return DEFAULT_API_BASE;
 }
 export function resolveAuthToken() {
-    // CI mode wins over file config (env vars are explicit).
+    const admission = admitAgent();
+    if (admission.kind === "agent") {
+        // Isolated: ONLY the per-agent store. Missing/bad → require `hands login`; never
+        // fall back to HANDS_AUTH_TOKEN or the human config.
+        return readAgentAccessToken(admission.env) ?? undefined;
+    }
+    if (admission.kind === "fail_closed") {
+        return undefined; // broken agent env → no ambient credentials
+    }
+    // Human / CI (no agent markers): env token wins, then the (migrated) human config.
     const env = readEnv("AUTH_TOKEN") ?? readEnv("BEARER_TOKEN") ?? readEnv("SESSION_COOKIE");
     if (env)
         return env;