@oar-sh/oar 0.9.10 → 0.9.11

package/server/services/background-work-view.mjs

@@ -0,0 +1,228 @@
+'use strict';
+
+/**
+ * What the relay can say about background work whose details it may not
+ * hold, because its task store and activity tracker live in memory and
+ * start empty at every runtime start while the workers keep running:
+ *
+ *  - the placeholder: a live worker that says it has background work (the
+ *    Claude worker's `autoCompactWindow.backgroundWork` on its heartbeat)
+ *    while this runtime was never told its task set. Workers that answer a
+ *    resync request fill the real set in within one heartbeat; this is for
+ *    the ones still running older code. It is read, never stored: it goes
+ *    when the set arrives, when the flag goes false and when the worker is
+ *    gone, and it raises no start or end event.
+ *  - the suspend blockers for background work, from the store and from the
+ *    activity tracker (which also reads running sub-agent runs from the
+ *    database), and the blocker for a runtime that only just started.
+ */
+
+import {
+  UNREPORTED_BACKGROUND_TASK_DESCRIPTION,
+  UNREPORTED_BACKGROUND_TASK_ID,
+} from './session-activity-tracker.mjs';
+
+// Providers whose worker lists every running background sub-agent in its
+// task set, by the run's id. Others may run background agents no set lists
+// (their run rows are their only trace), so a set says nothing about a row.
+const RUN_LISTING_PROVIDERS = new Set(['claude']);
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+/** The placeholder as a row of the task panel: no details, no Stop button. */
+export function unreportedBackgroundTaskCard() {
+  return {
+    taskId: UNREPORTED_BACKGROUND_TASK_ID,
+    taskType: 'unreported',
+    description: UNREPORTED_BACKGROUND_TASK_DESCRIPTION,
+    startedAt: null,
+    stoppable: false,
+    placeholder: true,
+  };
+}
+
+export function createBackgroundWorkView({
+  store,
+  db = null,
+  getRegistry = () => null,
+  getTracker = () => null,
+  isWorkerAlive = () => false,
+  // A conversation's id and its worker's session id are two ids, usually
+  // equal and not always. The tracker and the database speak of
+  // conversations; the registry, the store and the workers' own headers of
+  // sessions. These two map between them through the runtime session.
+  sessionIdOf = () => '',
+  conversationIdOf = () => '',
+  // conversationId → its provider ('claude', 'github', …).
+  providerOf = () => '',
+  titleOf = (conversationId) => toText(conversationId).slice(0, 8),
+} = {}) {
+  let listRunningRuns = null;
+  if (db) {
+    try {
+      listRunningRuns = db.prepare(`
+        SELECT DISTINCT conversation_id FROM subagent_runs
+        WHERE status = 'running' AND background = 1 AND parent_subagent_id IS NULL
+      `);
+    } catch {}
+  }
+
+  function mapped(resolve, id) {
+    try { return toText(resolve(id)); } catch { return ''; }
+  }
+
+  /** The worker of a session id or of a conversation id. */
+  function workerOf(key) {
+    const registry = getRegistry();
+    const id = toText(key);
+    if (!registry || !id) return null;
+    // The registry's own indexes first; the mapping is a database read.
+    const direct = registry.getWorker?.(id) || registry.getWorkerByConversationId?.(id) || null;
+    if (direct) return direct;
+    const sessionId = mapped(sessionIdOf, id);
+    return (sessionId && sessionId !== id && registry.getWorker?.(sessionId)) || null;
+  }
+
+  /** The conversation a worker serves; the registry's own field may hold its session id. */
+  function conversationOf(worker, fallback = '') {
+    return mapped(conversationIdOf, worker?.sdkSessionId) || toText(worker?.conversationId) || toText(fallback);
+  }
+
+  function workerAlive(key) {
+    const worker = workerOf(key);
+    return !!worker && isWorkerAlive(worker.sdkSessionId) === true;
+  }
+
+  /** Whether the placeholder stands for this worker (by session or conversation id). */
+  function hasUnreportedWork(key) {
+    const worker = workerOf(key);
+    if (!worker || worker.steering?.autoCompactWindow?.backgroundWork !== true) return false;
+    const keys = [worker.sdkSessionId, worker.conversationId, conversationOf(worker), key];
+    if (store.hasReport(...keys)) return false;
+    if (keys.some((entry) => store.get(entry).length > 0)) return false;
+    return isWorkerAlive(worker.sdkSessionId) === true;
+  }
+
+  function listUnreportedConversationIds() {
+    const workers = getRegistry()?.listWorkers?.() || [];
+    return workers
+      .filter((worker) => worker?.steering?.autoCompactWindow?.backgroundWork === true && hasUnreportedWork(worker.sdkSessionId))
+      .map((worker) => conversationOf(worker, worker.sdkSessionId))
+      .filter(Boolean);
+  }
+
+  /**
+   * Whether the task set of a conversation's worker lists a sub-agent run
+   * (by the run's id or its task id): true or false, and null where the set
+   * cannot answer, because the worker has reported none in this runtime
+   * or its provider's sets do not list every background run. The tracker
+   * drops a `running` row that is not listed and has long been quiet.
+   */
+  function runListed(conversationId, row) {
+    const conversation = toText(conversationId);
+    if (!RUN_LISTING_PROVIDERS.has(mapped(providerOf, conversation).toLowerCase())) return null;
+    const keys = [...new Set([conversation, mapped(sessionIdOf, conversation), toText(workerOf(conversation)?.sdkSessionId)].filter(Boolean))];
+    if (!store.hasReport(...keys)) return null;
+    const runId = toText(row?.id);
+    const taskId = toText(row?.task_id);
+    return keys.some((key) => store.get(key).some((task) => (runId && toText(task?.toolUseId) === runId)
+      || (taskId && toText(task?.taskId) === taskId)));
+  }
+
+  /** The task panel's rows for a conversation: its set, else the placeholder. */
+  function panelTasks(...keys) {
+    for (const key of keys) {
+      const tasks = store.get(key);
+      if (tasks.length) return tasks;
+    }
+    return keys.some((key) => toText(key) && hasUnreportedWork(key)) ? [unreportedBackgroundTaskCard()] : [];
+  }
+
+  /**
+   * One `background` blocker per conversation with running background work
+   * of a live worker: the tasks of its published set, the running tasks the
+   * tracker knows (a background sub-agent run in the database, the
+   * placeholder), each task once.
+   */
+  function backgroundBlockers() {
+    const byConversation = new Map();
+    const add = (conversationId, id, description) => {
+      const conversation = toText(conversationId);
+      if (!conversation) return;
+      let tasks = byConversation.get(conversation);
+      if (!tasks) byConversation.set(conversation, tasks = new Map());
+      const taskId = toText(id) || `task-${tasks.size + 1}`;
+      if (!tasks.has(taskId)) tasks.set(taskId, toText(description) || 'task');
+    };
+    for (const [key, entry] of store.sets) {
+      const tasks = Array.isArray(entry?.tasks) ? entry.tasks : [];
+      if (!tasks.length || !workerAlive(key)) continue;
+      const conversationId = conversationOf(workerOf(key), mapped(conversationIdOf, key) || key);
+      for (const task of tasks) add(conversationId, task?.taskId, task?.description || task?.taskType);
+    }
+    const tracker = getTracker();
+    if (tracker) {
+      const candidates = new Set();
+      try { for (const id of tracker.knownConversationIds?.() || []) candidates.add(toText(id)); } catch {}
+      try { for (const row of listRunningRuns?.all() || []) candidates.add(toText(row.conversation_id)); } catch {}
+      for (const conversationId of candidates) {
+        if (!conversationId || !workerAlive(conversationId)) continue;
+        let view = null;
+        try { view = tracker.describe(conversationId); } catch {}
+        for (const task of view?.tasks || []) {
+          // A run inside a turn is the turn's work; the turn is the blocker.
+          if (task.status !== 'running' || task.inTurn) continue;
+          add(conversationId, task.id, task.description || task.type);
+        }
+      }
+    }
+    return [...byConversation].map(([conversationId, tasks]) => {
+      // The placeholder's text names the way out; it is not cut short.
+      const what = [...tasks].slice(0, 3)
+        .map(([id, text]) => (id === UNREPORTED_BACKGROUND_TASK_ID ? text : text.slice(0, 80)))
+        .join('; ');
+      return {
+        kind: 'background',
+        conversationId,
+        title: titleOf(conversationId),
+        count: tasks.size,
+        detail: `${tasks.size} background agent${tasks.size === 1 ? '' : 's'}: ${what}`,
+      };
+    });
+  }
+
+  /**
+   * The blocker of a runtime that only just started: workers that outlived
+   * the one before it may not have reported their background work yet, so
+   * "nothing runs" is not known. Null once the window is over. Its text
+   * does not change while it stands: every change of a blocker goes out to
+   * every page.
+   */
+  function bootBlocker() {
+    let boot = null;
+    try { boot = getTracker()?.bootReporting?.() || null; } catch {}
+    if (!boot?.active) return null;
+    return {
+      kind: 'boot',
+      detail: 'the relay just started, sessions are still reporting',
+    };
+  }
+
+  /** What holds a host suspend back for background work: the two above. */
+  function blockers() {
+    const boot = bootBlocker();
+    return [...backgroundBlockers(), ...(boot ? [boot] : [])];
+  }
+
+  return {
+    hasUnreportedWork,
+    listUnreportedConversationIds,
+    runListed,
+    panelTasks,
+    backgroundBlockers,
+    bootBlocker,
+    blockers,
+  };
+}

package/server/services/cache-rebuild-service.mjs

@@ -62,6 +62,12 @@ export function createCacheRebuildService({
   bootstrapRuntimeSessionBindings,
   collectOrphanedUploadsFromConversation,
   deleteOrphanedUploads,
+  // (conversationId) => void: a hard-deleted conversation takes its preview
+  // links with it, as a delete from the UI does. Archiving keeps them.
+  closeConversationPreviews = null,
+  // Session groups: a purged head leaves its group, and a wipe is followed
+  // by a repair of what the wiped rows headed. Absent in older wiring.
+  conversationGroups = null,
 }) {
   const legacyConversationList = buildLegacyConversationList(db);
   const boundConversationList = buildBoundConversationList(db);
@@ -81,6 +87,7 @@ export function createCacheRebuildService({
     if (!sid) return [];
     const orphanedUploads = collectOrphanedUploadsFromConversation(sid);
     db.transaction(() => {
+      try { conversationGroups?.forgetConversation?.(sid); } catch {}
       db.prepare(`DELETE FROM relay_questions WHERE conversation_id = ?`).run(sid);
       db.prepare(`DELETE FROM relay_boards WHERE conversation_id = ?`).run(sid);
       db.prepare(`DELETE FROM relay_activity WHERE conversation_id = ?`).run(sid);
@@ -91,10 +98,19 @@ export function createCacheRebuildService({
       db.prepare(`DELETE FROM runtime_sessions WHERE conversation_id = ?`).run(sid);
       db.prepare(`DELETE FROM conversations WHERE id = ?`).run(sid);
     })();
+    closePreviews(sid);
     deleteOrphanedUploads(orphanedUploads);
     return orphanedUploads;
   }
 
+  function closePreviews(conversationId) {
+    try {
+      closeConversationPreviews?.(conversationId);
+    } catch (error) {
+      console.warn(`[preview] closing the previews of a purged conversation failed: ${error?.message || error}`);
+    }
+  }
+
   function archiveConversation(conversationId) {
     const sid = normalizeId(conversationId);
     if (!sid) return false;
@@ -112,6 +128,12 @@ export function createCacheRebuildService({
         AND title_source = 'manual'
     `).all().map((row) => normalizeId(row?.id)).filter(Boolean);
     const manualTitleConversationSet = new Set(manualTitleConversations);
+    // The groups headed by a row about to go keep the head's title as their
+    // name, so a group whose hand-titled members survive is not nameless; the
+    // head link stays for a re-import under the same id.
+    try {
+      conversationGroups?.freezeNamesForHeads?.(conversationIds.filter((id) => !manualTitleConversationSet.has(id)), now);
+    } catch {}
     const uploadHashes = [];
     for (const conversationId of conversationIds) {
       for (const hash of collectOrphanedUploadsFromConversation(conversationId)) {
@@ -147,8 +169,16 @@ export function createCacheRebuildService({
       db.prepare(`DELETE FROM sdk_session_imports`).run();
       db.prepare(`DELETE FROM upload_refs`).run();
       db.prepare(`DELETE FROM uploaded_files`).run();
+      // Groups whose rows are all gone go too; one whose head was wiped but
+      // whose hand-titled members stay keeps the frozen name and the head
+      // link (a re-imported head takes it up again).
+      try { conversationGroups?.sweepEmpty?.(); } catch {}
     })();
 
+    for (const conversationId of conversationIds) {
+      if (!manualTitleConversationSet.has(conversationId)) closePreviews(conversationId);
+    }
+
     deleteOrphanedUploads(uploadHashes);
 
     if (uploadsDir && fs?.existsSync?.(uploadsDir)) {

package/server/services/delete-archive-service.mjs

@@ -25,7 +25,7 @@ function createSdkDeleteSessionCaller(sdkClient) {
 
 import { cleanupGeneratedImagesForConversation } from './generated-image-cleanup-service.mjs';
 
-export function createDeleteArchiveService(db, sdkClient, { resolveSessionStateRoot = null } = {}) {
+export function createDeleteArchiveService(db, sdkClient, { resolveSessionStateRoot = null, conversationGroups = null } = {}) {
   const callDeleteSession = createSdkDeleteSessionCaller(sdkClient);
 
   const stmts = {
@@ -87,6 +87,9 @@ export function createDeleteArchiveService(db, sdkClient, { resolveSessionStateR
       messageRows: stmts.listConversationMessages.all(conversationId),
       resolveSessionStateRoot,
     });
+    // A head leaves its session group (title frozen as the name) before its
+    // row goes; a group left empty goes with it.
+    try { conversationGroups?.forgetConversation?.(conversationId); } catch {}
     stmts.hardDeleteConversation(conversationId);
   }
 

package/server/services/detached-worker-watch-service.mjs

@@ -0,0 +1,150 @@
+// ---------------------------------------------------------------------------
+// Detached-worker watch
+//
+// A worker whose process lives on but whose websocket to the relay is gone
+// gets no deliveries, and the relay spawns no replacement while its process
+// is alive: a message for its session would wait for ever. A worker on Node
+// 22 ended up like that after a relay restart, its one reconnect having met a
+// runtime that was not ready yet.
+//
+// The watch looks at the sessions that have a message waiting. One whose
+// worker process is found alive with no socket, no turn running and no
+// background work is replaced once it has been detached for the grace time:
+// the old process is stopped and a new worker spawned, which takes the
+// waiting message at its hello. The grace time counts from the latest of the
+// watch's start (a relay start), the session's last socket end and its last
+// spawn; a worker still booting gets twice as long.
+// ---------------------------------------------------------------------------
+
+export const DETACHED_WORKER_GRACE_MS = 60_000;
+// A replacement that did not help (the new worker cannot connect either)
+// is not repeated at once.
+export const DETACHED_WORKER_REPLACE_COOLDOWN_MS = 5 * 60_000;
+
+function normalizeSessionId(value) {
+  return String(value || '').trim();
+}
+
+export function createDetachedWorkerWatch({
+  graceMs = DETACHED_WORKER_GRACE_MS,
+  replaceCooldownMs = DETACHED_WORKER_REPLACE_COOLDOWN_MS,
+  now = () => Date.now(),
+  // Whether the watch may act at all (routing on, no shutdown under way).
+  isEnabled = () => true,
+  // The session ids that have a message waiting for their worker.
+  listWaitingSessionIds = () => [],
+  hasWorkerSocket = () => true,
+  hasRunningTurn = () => true,
+  hasBackgroundWork = () => true,
+  // A kill just asked for, or a launch in flight: not the watch's business.
+  isLaunchBlocked = () => false,
+  // ({ launchMode, launchAtMs, awaitingHeartbeat }) for the session, or null.
+  getLaunchState = () => null,
+  // Resolves to whether a process of the session's worker is running.
+  isWorkerProcessAlive = async () => false,
+  // Stops the session's worker processes and spawns a new worker; resolves
+  // to { ok, error }.
+  replaceWorker = async () => ({ ok: false, error: 'not-configured' }),
+  log = () => {},
+} = {}) {
+  const startedAtMs = Number(now());
+  const socketEndedAtMs = new Map();
+  const replacedAtMs = new Map();
+  const replacing = new Set();
+  let sweepInFlight = false;
+
+  function nowMs() {
+    const value = Number(now());
+    return Number.isFinite(value) ? value : Date.now();
+  }
+
+  function noteSocketEnded(sessionId) {
+    const sid = normalizeSessionId(sessionId);
+    if (sid) socketEndedAtMs.set(sid, nowMs());
+  }
+
+  function forgetOld(atMs) {
+    const horizon = Math.max(graceMs * 2, replaceCooldownMs);
+    for (const [sid, at] of socketEndedAtMs) {
+      if (atMs - at > horizon) socketEndedAtMs.delete(sid);
+    }
+    for (const [sid, at] of replacedAtMs) {
+      if (atMs - at > horizon) replacedAtMs.delete(sid);
+    }
+  }
+
+  // How long the session's worker has been detached for the watch's
+  // purposes, and the grace it gets.
+  function detachedFor(sid, atMs) {
+    const launch = getLaunchState(sid) || null;
+    const launchAtMs = Number(launch?.launchAtMs || 0);
+    const spawnedAtMs = launch?.launchMode === 'spawned' ? launchAtMs : 0;
+    const anchorMs = Math.max(startedAtMs, Number(socketEndedAtMs.get(sid) || 0), spawnedAtMs);
+    const booting = launch?.launchMode === 'spawned' && launch?.awaitingHeartbeat === true;
+    return { detachedMs: atMs - anchorMs, graceMs: booting ? graceMs * 2 : graceMs };
+  }
+
+  function stillDetached(sid) {
+    return !hasWorkerSocket(sid) && !hasRunningTurn(sid) && !hasBackgroundWork(sid) && !isLaunchBlocked(sid);
+  }
+
+  async function considerSession(sid, atMs) {
+    if (replacing.has(sid)) return false;
+    if (!stillDetached(sid)) return false;
+    const lastReplacedAtMs = replacedAtMs.get(sid);
+    if (lastReplacedAtMs && atMs - lastReplacedAtMs < replaceCooldownMs) return false;
+    const { detachedMs, graceMs: grace } = detachedFor(sid, atMs);
+    if (detachedMs < grace) return false;
+    if (!(await isWorkerProcessAlive(sid))) return false;
+    // The process probe can take a moment (a process list): the worker may
+    // have reconnected or taken a turn meanwhile.
+    if (!isEnabled() || !stillDetached(sid)) return false;
+
+    replacing.add(sid);
+    replacedAtMs.set(sid, atMs);
+    log(`WORKER DETACHED session=${sid.slice(0, 8)} detachedMs=${detachedMs} — no socket while a message waits; replacing the worker`);
+    try {
+      const result = await replaceWorker(sid, { detachedMs });
+      if (result?.ok) {
+        log(`WORKER DETACHED session=${sid.slice(0, 8)} replaced`);
+        return true;
+      }
+      log(`WORKER DETACHED session=${sid.slice(0, 8)} replace failed: ${String(result?.error || 'unknown')}`);
+      return false;
+    } catch (error) {
+      log(`WORKER DETACHED session=${sid.slice(0, 8)} replace failed: ${error?.message || error}`);
+      return false;
+    } finally {
+      replacing.delete(sid);
+    }
+  }
+
+  // One sweep at a time: a slow process list must not pile sweeps up.
+  async function sweep() {
+    if (sweepInFlight) return 0;
+    if (!isEnabled()) return 0;
+    sweepInFlight = true;
+    try {
+      const atMs = nowMs();
+      forgetOld(atMs);
+      const sessionIds = [...new Set((listWaitingSessionIds() || []).map(normalizeSessionId).filter(Boolean))];
+      let replaced = 0;
+      for (const sid of sessionIds) {
+        if (!isEnabled()) break;
+        try {
+          if (await considerSession(sid, atMs)) replaced += 1;
+        } catch (error) {
+          log(`WORKER DETACHED check failed session=${sid.slice(0, 8)} err=${error?.message || error}`);
+        }
+      }
+      return replaced;
+    } finally {
+      sweepInFlight = false;
+    }
+  }
+
+  return {
+    noteSocketEnded,
+    sweep,
+  };
+}

package/server/services/hidden-message-list.mjs

@@ -0,0 +1,21 @@
+'use strict';
+
+// The list of messages a conversation hides from its shared viewers: one
+// short plain-text preview per message, the same shape as the pin list, so
+// the owner's 🙈 list and its count cover messages outside the loaded page.
+// Owner-only: the shared payload never carries it.
+
+import { buildPinPreview, countAttachments } from './message-pin-list.mjs';
+
+export function buildHiddenMessageList(rows) {
+  return (Array.isArray(rows) ? rows : [])
+    .filter((row) => String(row?.id || '').trim())
+    .map((row) => ({
+      messageId: String(row.id).trim(),
+      role: String(row.role || '').trim(),
+      preview: buildPinPreview(row.text, row.mode),
+      timestamp: row.timestamp || null,
+      hiddenAt: row.share_hidden_at || null,
+      attachmentCount: countAttachments(row.attachments),
+    }));
+}

package/server/services/host-suspend-command.mjs

@@ -1,6 +1,7 @@
 'use strict';
 
 import { spawn } from 'node:child_process';
+import { windowsSystemToolPath } from '../../shared/windows-system-tools.mjs';
 
 /**
  * The actual suspend-to-RAM call. Windows only: `SetSuspendState 0,0,0` puts
@@ -25,7 +26,7 @@ export function runHostSuspendToRam({
     return { ok: true, command, dryRun: true };
   }
   try {
-    const child = spawnImpl('rundll32.exe', ['powrprof.dll,SetSuspendState', '0,0,0'], {
+    const child = spawnImpl(windowsSystemToolPath('rundll32.exe'), ['powrprof.dll,SetSuspendState', '0,0,0'], {
       detached: true,
       stdio: 'ignore',
       windowsHide: true,

package/server/services/message-pin-list.mjs

@@ -9,7 +9,7 @@ import { stripRelayPromptContext } from './relay-prompt-sanitizer.mjs';
 export const MESSAGE_PIN_LIMIT = 100;
 export const PIN_PREVIEW_MAX_LENGTH = 160;
 
-function countAttachments(raw) {
+export function countAttachments(raw) {
   if (Array.isArray(raw)) return raw.length;
   if (typeof raw !== 'string' || !raw) return 0;
   try {

package/server/services/preview-health-probe.mjs

@@ -2,7 +2,7 @@
 
 import net from 'net';
 
-// Liveness for preview cards. Previews never auto-close, so the card has to say
+// Liveness for preview cards. Previews never expire, so the card has to say
 // whether the dev server behind it is still up — a TCP connect is enough and,
 // unlike an HTTP request, leaves nothing in the app's request log.
 
@@ -55,6 +55,10 @@ export function createPreviewHealthProbe({
     // A slow sweep must not overlap itself; with the registry capped at 8
     // previews and a 250ms connect budget, one pass is bounded at ~2s anyway.
     if (sweeping) return;
+    // Store writes that failed (a locked database) are retried on this beat,
+    // so the table catches up with memory without a timer of its own, and
+    // rows a restore could not judge get their check again.
+    try { registry.maintain?.(); } catch {}
     const previews = registry.list().filter((entry) => entry.mode !== 'static');
     if (previews.length === 0) return;
     sweeping = true;
@@ -70,6 +74,9 @@ export function createPreviewHealthProbe({
     timer = setIntervalImpl(() => { sweep().catch(() => {}); }, intervalMs);
     // An idle relay should not be held awake by a probe that has nothing to do.
     if (typeof timer?.unref === 'function') timer.unref();
+    // One pass right away: port previews restored at boot start without a
+    // health state, and their cards should not wait a full interval for one.
+    sweep().catch(() => {});
   }
 
   function stop() {

package/server/services/preview-proxy-server.mjs

@@ -2,7 +2,7 @@
 
 import http from 'http';
 
-import { parsePreviewPath } from './preview-registry-service.mjs';
+import { parsePreviewPath, previewLogId } from './preview-registry-service.mjs';
 import { serveStaticPreview } from './preview-static-handler.mjs';
 
 // The preview listener. A bare http.Server on its own loopback port whose
@@ -270,12 +270,16 @@ export function createPreviewProxyServer({
     socket.once('error', forget);
   }
 
-  function logHit(entry, req) {
+  // The token is the capability and the request URL carries it, so the line
+  // names the preview by a hash and logs only the upstream path, without query.
+  function logHit(entry, req, upstreamPath) {
     const now = Date.now();
     const last = lastHitLogAt.get(entry.token) || 0;
     if (now - last < 60_000) return;
     lastHitLogAt.set(entry.token, now);
-    logger?.log?.(`[preview] ${entry.token.slice(0, 8)} → :${entry.targetPort} ${req.method} ${req.url} from ${clientIp(req)}`);
+    const target = entry.mode === 'static' ? 'static' : `:${entry.targetPort}`;
+    const pathOnly = String(upstreamPath || '/').split('?')[0];
+    logger?.log?.(`[preview] ${previewLogId(entry.token)} → ${target} ${req.method} ${pathOnly} from ${clientIp(req)}`);
   }
 
   function resolveRequest(req) {
@@ -309,7 +313,7 @@ export function createPreviewProxyServer({
 
     const { entry, upstreamPath } = resolved;
     registry.recordHit(entry.token);
-    logHit(entry, req);
+    logHit(entry, req, upstreamPath);
 
     // Static previews are answered in-process — no upstream, no forwarding.
     if (entry.mode === 'static') {