@hienlh/ppm 0.23.5 → 0.23.7

package/src/server/routes/resources.ts

@@ -1,19 +1,27 @@
 /**
  * Whole-machine metrics routes, mounted under `/api/system` behind auth.
  *
+ *   GET    /hardware                         static device inventory (drives, NICs, GPUs)
  *   GET    /resources?processes=0|1          latest snapshot for that tier (or null)
  *   GET    /resources/stream?processes=0|1   SSE: `session` frame, then `snapshot` frames
  *   POST   /resources/stream/:sid/ping       renew the subscriber lease
  *   DELETE /resources/stream/:sid            drop the subscriber
  *   POST   /resources/kill                   guarded kill (JSON + X-PPM-Request header)
+ *   POST   /resources/signal                 guarded signal, same guard as a kill
+ *   GET    /resources/process/:pid           on-demand facts for the Details dialog
  */
 import { Hono } from "hono";
 import type { MetricsSnapshot, MetricsTier } from "../../types/system-metrics.ts";
+import type { HardwareInventory } from "../../types/system-hardware.ts";
 import { ok, err } from "../../types/api.ts";
 import {
   systemMetricsService, MAX_STREAM_SUBSCRIBERS, type SystemMetricsService,
 } from "../../services/system-metrics/system-metrics.service.ts";
 import { isValidSid } from "../../services/system-metrics/metrics-subscriber-registry.ts";
+import { readHardwareInventory } from "../../services/system-metrics/hardware-inventory.ts";
+import { createAppIconService, type AppIconService } from "../../services/system-services/app-icon-service.ts";
+import { iconMimeType } from "../../services/system-services/app-icons-linux.ts";
+import { crossOriginRefusal } from "./cross-origin-guard.ts";
 
 /** Frames a stalled client failed to take before the stream is closed. Metrics
  *  are lossy by nature; `ReadableStream`'s queue is not, and 30-60 KB every 2 s
@@ -22,9 +30,34 @@ export const MAX_DROPPED_FRAMES = 10;
 
 const tierOf = (raw: string | undefined): MetricsTier => (raw === "1" || raw === "true" ? "full" : "light");
 
-export function createResourceRoutes(service: SystemMetricsService = systemMetricsService): Hono {
+
+export function createResourceRoutes(
+  service: SystemMetricsService = systemMetricsService,
+  hardware: () => Promise<HardwareInventory> = readHardwareInventory,
+  appIcons: AppIconService = createAppIconService(),
+): Hono {
   const routes = new Hono();
 
+  // Static facts, fetched once per window and again whenever a snapshot names a
+  // device id the client does not know yet — never on the 2 s tick.
+  routes.get("/hardware", async (c) => c.json(ok(await hardware())));
+
+  // The request names an APP, never a path: the only file this can serve is one
+  // this host's own desktop entry pointed at, resolved server-side.
+  routes.get("/app-icon/:id", async (c) => {
+    const iconPath = appIcons.path(c.req.param("id") ?? "");
+    if (!iconPath) return c.json(err("No icon for that app"), 404);
+    const file = Bun.file(iconPath);
+    if (!(await file.exists())) return c.json(err("No icon for that app"), 404);
+    return new Response(file, {
+      headers: {
+        "Content-Type": iconMimeType(iconPath),
+        // Icons change only when a package is reinstalled.
+        "Cache-Control": "public, max-age=86400",
+      },
+    });
+  });
+
   routes.get("/resources", (c) => c.json(ok(service.getLatest(tierOf(c.req.query("processes"))))));
 
   routes.get("/resources/stream", (c) => {
@@ -102,15 +135,45 @@ export function createResourceRoutes(service: SystemMetricsService = systemMetri
     return c.json(ok({ stopped }));
   });
 
-  routes.post("/resources/kill", async (c) => {
-    // CSRF hardening for the auth-disabled configuration: a cross-origin HTML
-    // form can set neither a JSON content type nor a custom header, so both
-    // force a preflight that the browser will refuse.
-    const contentType = c.req.header("content-type") ?? "";
-    if (!contentType.toLowerCase().startsWith("application/json")) {
-      return c.json(err("Content-Type must be application/json"), 400);
+  // Every field here is already in the process table this caller can stream,
+  // except exe/cwd/cgroup — the same trust level, behind the same auth.
+  routes.get("/resources/process/:pid", async (c) => {
+    const raw = c.req.param("pid") ?? "";
+    const pid = Number(raw);
+    if (!/^\d+$/.test(raw) || !Number.isInteger(pid) || pid <= 0) {
+      return c.json(err("PID must be a positive integer"), 400);
+    }
+    // Two different claims, and for a while they shared one sentence: a host with
+    // no reader answered "no longer running" about processes that were running.
+    if (!service.supportsProcessDetails()) {
+      return c.json(err("PPM cannot read process details on this host yet"), 501);
     }
-    if (c.req.header("x-ppm-request") !== "1") return c.json(err("Missing X-PPM-Request header"), 400);
+    const details = await service.processDetails(pid);
+    if (!details) return c.json(err(`PID ${pid} is no longer running`), 404);
+    return c.json(ok(details));
+  });
+
+  routes.post("/resources/signal", async (c) => {
+    const refusal = crossOriginRefusal(c);
+    if (refusal) return c.json(err(refusal), 400);
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json(err("Invalid JSON body"), 400);
+    }
+    try {
+      const outcome = await service.signal(body);
+      return c.json(outcome.body, outcome.status);
+    } catch (e) {
+      console.error("[SystemMetrics] signal re-query failed:", (e as Error)?.message ?? e);
+      return c.json(err("Could not verify the process — try again"), 500);
+    }
+  });
+
+  routes.post("/resources/kill", async (c) => {
+    const refusal = crossOriginRefusal(c);
+    if (refusal) return c.json(err(refusal), 400);
     let body: unknown;
     try {
       body = await c.req.json();

package/src/server/routes/settings.ts

@@ -15,7 +15,7 @@ import {
 import { ok, err } from "../../types/api.ts";
 import { proxyService } from "../../services/proxy.service.ts";
 import { clearIndexCache } from "../../services/file-list-index.service.ts";
-import { providerRegistry } from "../../providers/registry.ts";
+import { providerRegistry, providerProbeStatuses, retryProviderProbe } from "../../providers/registry.ts";
 
 export const settingsRoutes = new Hono();
 
@@ -264,6 +264,24 @@ settingsRoutes.put("/ai", async (c) => {
   }
 });
 
+/**
+ * GET /settings/ai/providers/status — which CLI providers registered, and why one did not.
+ *
+ * Settings builds its provider tabs from config, which keeps a codex entry
+ * forever once it has been written — so the tab is there while chat offers no
+ * Codex at all. This is what lets that tab say which of the two it is.
+ */
+settingsRoutes.get("/ai/providers/status", (c) => c.json(ok(providerProbeStatuses())));
+
+/** POST /settings/ai/providers/:id/probe — probe now, ahead of the backoff */
+settingsRoutes.post("/ai/providers/:id/probe", async (c) => {
+  try {
+    return c.json(ok(await retryProviderProbe(c.req.param("id"))));
+  } catch (e) {
+    return c.json(err((e as Error).message), 400);
+  }
+});
+
 /** GET /settings/ai/providers/:id/models — list models for a provider (global, no project context needed) */
 settingsRoutes.get("/ai/providers/:id/models", async (c) => {
   try {

package/src/server/routes/speech.ts

@@ -0,0 +1,66 @@
+/**
+ * Speech-to-text on the host: install status, the install/uninstall buttons in
+ * Settings, and the transcribe door the chat mic posts a WAV to.
+ *
+ * Mounted under `/api`, so every route here is already behind `authMiddleware`.
+ */
+import { Hono } from "hono";
+import { err, ok } from "../../types/api.ts";
+import {
+  getWhisperStatus,
+  startWhisperInstall,
+  uninstallWhisper,
+} from "../../services/speech-to-text/whisper-install.service.ts";
+import { transcribeWav } from "../../services/speech-to-text/whisper-transcribe.service.ts";
+
+export const speechRoutes = new Hono();
+
+/** 16 kHz mono 16-bit is 32 KB/s, so this is about 13 minutes of speech. */
+const MAX_AUDIO_BYTES = 25 * 1024 * 1024;
+
+const message = (e: unknown) => (e instanceof Error ? e.message : String(e));
+
+speechRoutes.get("/status", (c) => c.json(ok(getWhisperStatus())));
+
+speechRoutes.post("/install", async (c) => {
+  const body = (await c.req.json().catch(() => ({}))) as { model?: string };
+  try {
+    return c.json(ok(startWhisperInstall(body.model)));
+  } catch (e) {
+    return c.json(err(message(e)), 409);
+  }
+});
+
+speechRoutes.post("/uninstall", (c) => {
+  try {
+    uninstallWhisper();
+    return c.json(ok(getWhisperStatus()));
+  } catch (e) {
+    return c.json(err(message(e)), 409);
+  }
+});
+
+/**
+ * POST /api/speech/transcribe?lang=vi — body is the raw WAV the browser recorded.
+ *
+ * WAV rather than the browser's native webm/opus: whisper.cpp reads wav, flac,
+ * mp3 and Vorbis-ogg only, and converting Opus on the host would mean depending
+ * on ffmpeg being installed as well.
+ */
+speechRoutes.post("/transcribe", async (c) => {
+  const lang = c.req.query("lang") ?? "vi";
+  if (!/^(auto|[a-z]{2})$/.test(lang)) return c.json(err("invalid lang"), 400);
+
+  const body = new Uint8Array(await c.req.arrayBuffer());
+  if (body.byteLength === 0) return c.json(err("empty audio"), 400);
+  if (body.byteLength > MAX_AUDIO_BYTES) return c.json(err("audio too long"), 413);
+
+  const status = getWhisperStatus();
+  if (!status.ready) return c.json(err("Whisper is not installed on this host"), 409);
+
+  try {
+    return c.json(ok(await transcribeWav(body, lang)));
+  } catch (e) {
+    return c.json(err(message(e)), 500);
+  }
+});

package/src/server/routes/system-services.ts

@@ -0,0 +1,76 @@
+/**
+ * Services page routes, mounted under /api/system behind auth.
+ *
+ *   GET  /services                        both scopes in one snapshot
+ *   GET  /services/:scope/:unit           details plus this boot's journal
+ *   POST /services/:scope/:unit/:action   guarded start/stop/restart/enable/disable
+ *
+ * The action route is the only one that changes anything, and it is guarded
+ * twice: the cross-origin header pair, then PPM's own refusals (which is the
+ * SAME function that produced each row's `refused` map, so a greyed-out button
+ * and a 403 always agree).
+ */
+import { Hono } from "hono";
+import { ok, err } from "../../types/api.ts";
+import type { ServiceAction, ServiceScope } from "../../types/system-services.ts";
+import { SERVICE_ACTIONS } from "../../types/system-services.ts";
+import {
+  collectServices, createSystemdServices, runServiceAction, serviceDetails,
+  ServiceActionRefused, type SystemdDeps,
+} from "../../services/system-services/systemd-collector.ts";
+import { isPlausibleUnitName } from "../../services/system-services/service-guard.ts";
+import { crossOriginRefusal } from "./cross-origin-guard.ts";
+
+const SCOPES: readonly string[] = ["system", "user"];
+const isScope = (value: string): value is ServiceScope => SCOPES.includes(value);
+
+export function createSystemServiceRoutes(deps: SystemdDeps = createSystemdServices()): Hono {
+  const routes = new Hono();
+
+  routes.get("/services", async (c) => c.json(ok(await collectServices(deps))));
+
+  routes.get("/services/:scope/:unit", async (c) => {
+    const scope = c.req.param("scope") ?? "";
+    const unit = c.req.param("unit") ?? "";
+    if (!isScope(scope)) return c.json(err("Scope must be system or user"), 400);
+    if (!isPlausibleUnitName(unit)) return c.json(err("Not a unit name"), 400);
+    const details = await serviceDetails(unit, scope, deps);
+    if (!details) return c.json(err(`No unit named ${unit}`), 404);
+    return c.json(ok(details));
+  });
+
+  routes.post("/services/:scope/:unit/:action", async (c) => {
+    const refusal = crossOriginRefusal(c);
+    if (refusal) return c.json(err(refusal), 400);
+
+    const scope = c.req.param("scope") ?? "";
+    const unit = c.req.param("unit") ?? "";
+    const action = c.req.param("action") ?? "";
+    if (!isScope(scope)) return c.json(err("Scope must be system or user"), 400);
+    if (!isPlausibleUnitName(unit)) return c.json(err("Not a unit name"), 400);
+    if (!SERVICE_ACTIONS.includes(action as ServiceAction)) {
+      return c.json(err(`Action must be one of ${SERVICE_ACTIONS.join("|")}`), 400);
+    }
+
+    // Audit line: unit, scope, action and outcome only. No command lines and no
+    // journal text — the tail of ~/.ppm/ppm.log is served unauthenticated.
+    const prefix = `[SystemServices] ${action} ${scope}/${unit}`;
+    try {
+      const result = await runServiceAction(unit, scope, action as ServiceAction, deps);
+      console.log(`${prefix} -> done`);
+      return c.json(ok(result));
+    } catch (e) {
+      if (e instanceof ServiceActionRefused) {
+        console.log(`${prefix} -> refused: ${e.message}`);
+        return c.json(err(e.message), 403);
+      }
+      const message = (e as Error)?.message ?? "Action failed";
+      console.log(`${prefix} -> failed: ${message}`);
+      return c.json(err(message), 500);
+    }
+  });
+
+  return routes;
+}
+
+export const systemServiceRoutes = createSystemServiceRoutes();

package/src/server/routes/tunnel.ts

@@ -5,6 +5,7 @@ import { getLocalIp } from "../../lib/network-utils.ts";
 import { ok, err } from "../../types/api.ts";
 import { getConfigValue } from "../../services/db.service.ts";
 import { resolveTunnelConfig } from "../../services/named-tunnel/named-tunnel-config.ts";
+import { requestTunnelReload } from "../../services/supervisor-state.ts";
 
 export const tunnelRoutes = new Hono();
 
@@ -14,7 +15,31 @@ tunnelRoutes.get("/", (c) => {
   const port = configService.get("port") ?? 8080;
   const localIp = getLocalIp();
   const localUrl = localIp ? `http://${localIp}:${port}` : null;
-  return c.json(ok({ active: !!url, url, localUrl }));
+  // `enabled` is what the user asked for; `active` is what is actually serving.
+  // They disagree for the seconds between a toggle and the supervisor acting on
+  // it, and whenever a tunnel the switch permits has failed to come up.
+  const enabled = resolveTunnelConfig(getConfigValue("tunnel")).enabled;
+  return c.json(ok({ active: !!url, url, localUrl, enabled }));
+});
+
+/**
+ * POST /api/tunnel/enabled — the master switch.
+ *
+ * Writing the config is only half of it: the supervisor owns the cloudflared
+ * process and lives in another process with its own config cache, so the change
+ * reaches it as a `retunnel`, which it already knows how to claim atomically.
+ * `no-supervisor` is not an error — a dev server started without one still
+ * persists the choice for the next real start.
+ */
+tunnelRoutes.post("/enabled", async (c) => {
+  const body = await c.req.json().catch(() => null) as { enabled?: unknown } | null;
+  if (typeof body?.enabled !== "boolean") {
+    return c.json(err("`enabled` must be a boolean"), 400);
+  }
+  const current = configService.get("tunnel");
+  configService.set("tunnel", { ...current, enabled: body.enabled });
+  const reload = requestTunnelReload();
+  return c.json(ok({ enabled: body.enabled, reload }));
 });
 
 /** POST /api/tunnel/start — start tunnel if not already running */
@@ -26,6 +51,13 @@ tunnelRoutes.post("/start", async (c) => {
   // round-robins between the two, so ~half of requests hit whichever origin the
   // stale connector still points at.
   const cfg = resolveTunnelConfig(getConfigValue("tunnel"));
+  // The master switch has to hold here too, or it is not one. This route spawns
+  // cloudflared from the *server* process, which the supervisor never learns a pid
+  // for — so a public URL raised past a switched-off tunnel is also one nothing
+  // will reap except the next restart's orphan sweep.
+  if (!cfg.enabled) {
+    return c.json(err("public tunnel is switched off"), 409);
+  }
   if (cfg.mode === "named") {
     return c.json(err("named tunnel is supervisor-managed"), 409);
   }

package/src/server/ws/chat.ts

@@ -3,7 +3,7 @@ import { providerRegistry } from "../../providers/registry.ts";
 import { resolveProjectPath } from "../helpers/resolve-project.ts";
 import { logSessionEvent } from "../../services/session-log.service.ts";
 import { listSessions as sdkListSessions } from "@anthropic-ai/claude-agent-sdk";
-import { getSessionTitle, incrementSessionUnread, clearSessionUnread, getSessionModel, setSessionModel, getSessionProvider, getSessionEffort, setSessionEffort, getSessionThinking, setSessionThinking, setSessionMigratedTo, getSessionDesignSlug, setSessionPermissionMode } from "../../services/db.service.ts";
+import { getSessionTitle, incrementSessionUnread, clearSessionUnread, getSessionModel, setSessionModel, getSessionProvider, getSessionEffort, setSessionEffort, getSessionThinking, setSessionThinking, setSessionMigratedTo, getSessionDesignSlug, setSessionPermissionMode, getLastTurnCacheState } from "../../services/db.service.ts";
 import { VALID_PERMISSION_MODES } from "../../types/config.ts";
 import { VALID_EFFORT_VALUES, THINKING_ADAPTIVE, isThinkingEnabled } from "../../providers/claude-agent-sdk-query-options.ts";
 import type { ChatWsClientMessage, SessionPhase } from "../../types/api.ts";
@@ -16,7 +16,8 @@ import { resolveSessionDir } from "../../services/subagent-transcript-merger.ts"
 import { backgroundShellRegistry } from "../../services/background-shell-registry.ts";
 import { basename } from "node:path";
 import { configService } from "../../services/config.service.ts";
-import { formatTurnUsageLog } from "../../shared/turn-usage.ts";
+import { formatTurnUsageLog, prefixTokens } from "../../shared/turn-usage.ts";
+import type { PromptCacheState } from "../../shared/prompt-cache-idle.ts";
 import { isAsyncAgentLaunchAck, isTerminalAgentStatus } from "../../shared/background-agent-status.ts";
 import { cacheReleaseDelayMs, selectWarmIdleEvictions } from "../../services/subprocess-retention.ts";
 import { needsAuthServerNames } from "../../services/mcp-oauth/mcp-oauth-redirect.ts";
@@ -131,6 +132,14 @@ interface SessionEntry {
   idleSince?: number;
   /** When the last turn completed — the moment this session's prompt cache was last written */
   lastTurnEndedAt?: number;
+  /** Transcript replayed to the API on that turn — what re-caching it would cost again */
+  lastTurnPrefixTokens?: number;
+  /** Context that turn actually held, measured per API call rather than summed */
+  lastTurnContextTokens?: number;
+  /** Cache window the API reported on that turn, outranking the credential-shaped guess */
+  lastTurnCacheTtlMs?: number;
+  /** A compaction the last turn ended on, which leaves the cached prefix inapplicable */
+  lastTurnCompactedAt?: number;
   /**
    * When the message that opened the current turn reached the server — what "time to first
    * event" is measured from. The consumer loop outlives turns, so its own clock would count
@@ -235,7 +244,12 @@ function scheduleSubprocessRelease(sessionId: string): void {
   const note = "Subprocess released: its prompt cache has expired, so keeping it warm saves nothing";
   // The window is the provider's to state: an API-key install's cache dies at five minutes,
   // so holding the subprocess for an hour there guards nothing and costs ~350MB.
-  const ttlMs = provider.promptCacheTtlMs?.(sessionId);
+  // The API's own answer where the turn gave one, the provider's inference otherwise: an
+  // install wrongly read as API-key would drop a subprocess at minute five and pay to rebuild
+  // a prefix whose cache had fifty-five minutes left. Entry-only, with no DB lookup — a
+  // session with no turn in this process has no `lastTurnEndedAt` either, so the delay is 0
+  // regardless of the window.
+  const ttlMs = entry.lastTurnCacheTtlMs ?? provider.promptCacheTtlMs?.(sessionId);
   const delay = cacheReleaseDelayMs(entry.lastTurnEndedAt, Date.now(), ttlMs);
   if (delay === 0) {
     releaseSubprocess(sessionId, "cache_expired", note);
@@ -248,6 +262,54 @@ function scheduleSubprocessRelease(sessionId: string): void {
   }, delay);
 }
 
+/**
+ * What a reconnecting client needs to say whether this session's prompt cache is still warm.
+ *
+ * The three facts are only known here: when the cache was last written, how long this
+ * install's caches live, and how much transcript would have to be re-sent. The browser has
+ * none of them after a reload — `ChatMessage.usage` is attached from the live `done` event
+ * and is not in the transcript — so a tab reopened the next morning would otherwise have no
+ * way to warn that the first message of the day is the expensive one.
+ *
+ * Null until a turn has both completed and reported its usage: with nothing cached there is
+ * nothing to lose, and a size PPM cannot measure must not be guessed at.
+ */
+function promptCacheSnapshot(sessionId: string, entry: SessionEntry): PromptCacheState | null {
+  const provider = providerRegistry.get(entry.providerId);
+  const declaredTtlMs = provider?.promptCacheTtlMs?.(sessionId);
+  // A provider with no opinion has no Anthropic prompt cache to warn about. Asked before the
+  // measured window is consulted, because this gate is about whether there is a cache at all.
+  if (declaredTtlMs == null) return null;
+
+  // The entry is memory, and memory is the short-lived half of this. `CLEANUP_TIMEOUT_MS`
+  // drops it five minutes after the last tab leaves, and a restart drops it at once — both
+  // well inside the hour the cache it describes actually lives. So a session reopened later
+  // has to answer from `turn_usage`, which recorded the same three facts on every turn.
+  // Memory still wins when it has them: it is this process's own turn, with no clock
+  // conversion between here and SQLite's UTC text.
+  const persisted = entry.lastTurnEndedAt == null ? getLastTurnCacheState(sessionId) : null;
+  const lastTurnEndedAt = entry.lastTurnEndedAt ?? persisted?.endedAtMs;
+  const billedPrefixTokens = entry.lastTurnPrefixTokens ?? persisted?.prefixTokens;
+  const contextTokens = entry.lastTurnContextTokens ?? persisted?.contextTokens;
+  // `usage.cache_creation` beats the guess `promptCacheTtlMs` makes from the credential's
+  // shape, which is wrong for a proxy, a custom base_url, or a subscription past its limits.
+  const ttlMs = entry.lastTurnCacheTtlMs ?? persisted?.cacheTtlMs ?? declaredTtlMs;
+  // Memory first again, and here that matters in the other direction: a live entry that has
+  // re-cached since holds `undefined`, which must beat the stale compaction still on the
+  // row this session's last turn wrote.
+  const compactedAt = entry.lastTurnEndedAt != null ? entry.lastTurnCompactedAt : persisted?.compactedAt;
+
+  return {
+    ttlMs,
+    // Sent even before a turn has completed: the window is the install's, and a tab that
+    // stays connected all day needs it to arm the notice from its own turns.
+    ...(lastTurnEndedAt != null && { lastTurnEndedAt }),
+    ...(billedPrefixTokens != null && { billedPrefixTokens }),
+    ...(contextTokens != null && { contextTokens }),
+    ...(compactedAt != null && { compactedAt }),
+  };
+}
+
 /** Push the current background-shell registry snapshot to a session's clients. */
 function broadcastBackgroundRegistry(sessionId: string): void {
   broadcast(sessionId, {
@@ -850,6 +912,13 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
         // release pending from the disconnect was timed against the previous turn — re-time it
         // or it fires while the cache it was protecting is still fresh.
         entry.lastTurnEndedAt = Date.now();
+        if (ev.usage) entry.lastTurnPrefixTokens = prefixTokens(ev.usage);
+        if (ev.usage?.contextTokens != null) entry.lastTurnContextTokens = ev.usage.contextTokens;
+        if (ev.usage?.cacheTtlMs != null) entry.lastTurnCacheTtlMs = ev.usage.cacheTtlMs;
+        // Assigned rather than only-when-present: the provider clears this the moment an API
+        // call re-caches, and that clearing is the signal the cache is usable again. Skipping
+        // the undefined case would leave a session cold for the rest of its life.
+        if (ev.usage) entry.lastTurnCompactedAt = ev.usage.compactedAt;
         if (entry.clients.size === 0) scheduleSubprocessRelease(sessionId);
 
         // Fire-and-forget: fetch updated session title (DB title takes priority) + notification
@@ -1060,6 +1129,7 @@ export const chatWebSocket = {
         model: resolveSessionModel(sessionId),
         effort: resolveSessionEffort(sessionId),
         thinking: resolveSessionThinkingEnabled(sessionId),
+        promptCache: promptCacheSnapshot(sessionId, existing),
       }));
 
       // If actively streaming, send buffered turn events for reconnect sync
@@ -1194,6 +1264,7 @@ export const chatWebSocket = {
         model: resolveSessionModel(sessionId),
         effort: resolveSessionEffort(sessionId),
         thinking: resolveSessionThinkingEnabled(sessionId),
+        promptCache: promptCacheSnapshot(sessionId, entry),
       }));
       if (entry.phase !== "idle") {
         sendTurnEvents(sessionId, ws);

package/src/services/codex-account-login.ts

@@ -88,6 +88,8 @@ interface ChatGptLogin {
   /** True from the completion notification until the account is written. The
    * home must survive this window even if the browser walks away. */
   finalizing: boolean;
+  /** Settles on the app-server's account/updated — see finalizeLogin for why it matters. */
+  authReloaded: Promise<void>;
 }
 const pendingLogins = new Map<string, ChatGptLogin>();
 
@@ -142,6 +144,14 @@ function settle(id: string, status: Exclude<DeviceLoginStatus, { state: "pending
   p.timer = unref(setTimeout(() => { pendingLogins.delete(id); }, RESULT_GRACE_MS));
 }
 
+/** Bounded: an app-server that never announces the reload still gets its second read. */
+function waitForAuthReload(p: ChatGptLogin): Promise<void> {
+  return new Promise((resolve) => {
+    const t = unref(setTimeout(resolve, CONTROL_REQUEST_TIMEOUT_MS));
+    void p.authReloaded.then(() => { clearTimeout(t); resolve(); });
+  });
+}
+
 /** Turn the app-server's completion notification into a persisted account. */
 async function finalizeLogin(id: string, notif: CompletionNotification): Promise<void> {
   const p = pendingLogins.get(id);
@@ -151,7 +161,15 @@ async function finalizeLogin(id: string, notif: CompletionNotification): Promise
   // Authorization has completed; account/read has its own bounded timeout.
   clearTimeout(p.timer);
   try {
-    const read = await p.client.request<AccountRead>("account/read", {}, CONTROL_REQUEST_TIMEOUT_MS);
+    let read = await p.client.request<AccountRead>("account/read", {}, CONTROL_REQUEST_TIMEOUT_MS);
+    if (!read?.account) {
+      // codex sends account/login/completed BEFORE it reloads the auth the login just wrote,
+      // and announces the reload with account/updated (send_chatgpt_login_completion_notifications,
+      // rust-v0.154.0). A read that lands in between finds no account, although the sign-in
+      // succeeded — so an empty answer waits for the reload and asks once more.
+      await waitForAuthReload(p);
+      read = await p.client.request<AccountRead>("account/read", {}, CONTROL_REQUEST_TIMEOUT_MS);
+    }
     if (!read?.account) throw new Error("login completed but account is empty");
     if (p.status.state !== "pending") return;
     if (p.reloginId) {
@@ -200,15 +218,21 @@ async function startChatGptLogin(
   const home = target ? target.home : codexAccountHome(id);
   mkdirSync(home, { recursive: true, mode: 0o700 });
   const client = makeClient();
+  // Registered with the completion handler, not after it: the reload can be announced
+  // before the first account/read has even answered.
+  let markAuthReloaded!: () => void;
+  const authReloaded = new Promise<void>((resolve) => { markAuthReloaded = resolve; });
   client.onNotification((n) => {
     if (n.method === "account/login/completed") {
       void finalizeLogin(id, (n.params ?? {}) as CompletionNotification);
+    } else if (n.method === "account/updated") {
+      markAuthReloaded();
     }
   });
   client.onClose(() => settle(id, { state: "error", error: "login process exited" }));
   const timer = unref(setTimeout(() => settle(id, { state: "error", error: "timed out" }), method === "browser" ? BROWSER_LOGIN_TTL : DEVICE_LOGIN_TTL));
   const pending: ChatGptLogin = {
-    method, client, home, label, status: { state: "pending" }, timer, finalizing: false,
+    method, client, home, label, status: { state: "pending" }, timer, finalizing: false, authReloaded,
     ...(target ? { reloginId: target.id } : {}),
   };
   pendingLogins.set(id, pending);

package/src/services/codex-reset-credit.service.ts

@@ -0,0 +1,83 @@
+/**
+ * "Use reset" for a Codex account: spend one free rate-limit reset — but only once a limit has
+ * actually been reached.
+ *
+ * The gate lives on the server, not just on the button. A reset is one-use, it moves the
+ * weekly reset date (OpenAI: the next weekly reset is counted from when you continue, and the
+ * original one is not also granted), and spending it early throws away whatever was left of
+ * the window. So the decision is made against a *live* quota read taken right here, never
+ * against whatever the card was last shown.
+ */
+import { randomUUID } from "node:crypto";
+import { getCodexAccount } from "./codex-account.service.ts";
+import { clearCodexAccountUsageLimit, isCodexAccountUsageLimited } from "./codex-account-cooldown.ts";
+import { refreshUsage } from "./provider-usage/usage-registry.ts";
+import { fetchCodexUsageLive } from "../providers/codex-app-server/codex-usage-fetch.ts";
+import { consumeCodexResetCredit, type ResetCreditOutcome } from "../providers/codex-app-server/codex-reset-credit.ts";
+import { usageLimitReached } from "../shared/usage-extra.ts";
+import type { UsageInfo } from "../types/chat.ts";
+
+/** A refusal the caller should show as-is, with the HTTP status that fits it. */
+export class ResetCreditRefusedError extends Error {
+  constructor(message: string, readonly status: 404 | 409 | 502) { super(message); }
+}
+
+/** Accounts with a reset in flight — a double click must not become two attempts. */
+const inFlight = new Set<string>();
+
+export interface ResetCreditResult {
+  outcome: ResetCreditOutcome;
+  /** The account's quota after the attempt, freshly read. */
+  usage: UsageInfo;
+}
+
+/**
+ * The ways out to Codex, replaceable so a test can stand in for the app-server.
+ *
+ * All three of them. `refresh` was reached directly for a while, which left one door open in
+ * a seam whose whole point is that there are none: a test that faked the other two still made
+ * a real usage read on the way out, and the only sign of it was the call taking whatever the
+ * network took — five seconds and a timeout when something earlier in the process had left a
+ * connection to wait on.
+ */
+export interface ResetCreditCodexPorts {
+  readUsage: (codexHome: string) => Promise<UsageInfo>;
+  consume: (codexHome: string, idempotencyKey: string, creditId?: string) => Promise<ResetCreditOutcome>;
+  refresh: (accountId: string) => Promise<UsageInfo>;
+}
+
+const LIVE_PORTS: ResetCreditCodexPorts = {
+  readUsage: fetchCodexUsageLive,
+  consume: consumeCodexResetCredit,
+  refresh: (accountId) => refreshUsage("codex", accountId),
+};
+
+export async function spendCodexResetCredit(accountId: string, ports: ResetCreditCodexPorts = LIVE_PORTS): Promise<ResetCreditResult> {
+  const account = getCodexAccount(accountId);
+  if (!account) throw new ResetCreditRefusedError("Account not found", 404);
+  if (inFlight.has(accountId)) throw new ResetCreditRefusedError("A reset for this account is already in progress.", 409);
+  inFlight.add(accountId);
+  try {
+    let live: UsageInfo;
+    try {
+      live = await ports.readUsage(account.home);
+    } catch (e) {
+      // Refuse rather than guess: the only safe answer to "is the limit reached?" is a fresh one.
+      throw new ResetCreditRefusedError(`Could not read ${account.label}'s current usage, so no reset was used: ${(e as Error).message}`, 502);
+    }
+    // Codex refusing a turn for quota is also a reached limit, even if the figures lag it.
+    if (!usageLimitReached(live) && !isCodexAccountUsageLimited(accountId)) {
+      throw new ResetCreditRefusedError(`${account.label} has not reached a limit yet, so a reset would waste the usage left and move the weekly reset date. It is kept for when you hit the limit.`, 409);
+    }
+    if ((live.resetCredits?.available ?? 0) === 0) {
+      throw new ResetCreditRefusedError(`${account.label} has no free reset left.`, 409);
+    }
+    // The soonest-expiring credit first: the others outlive it.
+    const outcome = await ports.consume(account.home, randomUUID(), live.resetCredits?.nextCreditId);
+    if (outcome === "reset") clearCodexAccountUsageLimit(accountId);
+    console.log(`[codex] account ${accountId} reset credit → ${outcome}`);
+    return { outcome, usage: await ports.refresh(accountId) };
+  } finally {
+    inFlight.delete(accountId);
+  }
+}