@rubytech/create-maxy-code 0.1.40 → 0.1.41

package/payload/platform/services/claude-session-manager/dist/http-server.js

@@ -6,35 +6,27 @@
 //   POST   /spawn               { senderId, role, channel, tunnelUrl? } -> Session
 //   GET    /list?senderId=...   -> Session[]
 //   POST   /resume              { senderId, role, channel, claudeSessionId } -> Session
-//   DELETE /:sessionId          -> 204
-//   DELETE /:sessionId?purge=1  -> 204 (hard-removes JSONL + sidecar); 409 if PTY alive
-//   POST   /:sessionId/input    { text }
-//   GET    /:sessionId/log      -> { jsonlPath, sizeBytes, exists }
-//   GET    /:sessionId/log?follow=1 -> streamed file content (current + new)
-//   GET    /:sessionId/meta     -> SessionMeta payload
-//   PATCH  /:sessionId          { displayName } -> 204 (writes sidecar)
+//   POST   /:id/stop            -> 204 (kill PTY; idempotent on already-dead row)
+//                                 404 if no row matches any of the 4 keys
+//   DELETE /:id                 -> 204 (rmSync JSONL + sidecar + subdir)
+//                                 409 if PTY still alive
+//                                 404 if no transcript on disk
+//   POST   /:id/input           { text }
+//   GET    /:id/log             -> { jsonlPath, sizeBytes, exists }
+//   GET    /:id/log?follow=1    -> streamed file content (current + new)
+//   GET    /:id/meta            -> SessionMeta payload
+//   PATCH  /:id                 { displayName } -> 204 (writes sidecar)
+//   POST   /:id/archive         { mode }
 //
-// `/spawn` returns 200 the instant Claude Code emits its `/remote-control`
-// URL — the operator gets a usable session inside ~2 s even when they never
-// type. The wire shape is `{sessionId: <bridge-suffix>, claudeSessionId: null,
-// jsonlPath: null, ...LivePayload}`. The jsonl-observer fires on the first
-// operator turn (claude does not write the JSONL until then, verified Pi
-// 2.1.143 and Mac 2.1.128) and promotes the row to the intrinsic
-// claudeSessionId in the background — no second client call needed.
-//
-// Every GET route resolves either the bridge suffix or the intrinsic id to
-// the same row, so a UI that mounted on the bridge suffix at t=0 keeps
-// routing correctly after promotion without flipping the row's visible
-// position. The intrinsic id is the right field to use for routing once
-// known (UI reads `claudeSessionId ?? sessionId`).
-//
-// sidecar `<id>.meta.json` next to the JSONL holds operator-owned fields
-// (displayName). PATCH writes it; /meta reads it via the enumerator helpers.
+// Any of the four ids — intrinsic sessionId, bridgeSessionId, bridgeSuffix,
+// or pid (numeric) — resolves to the same row via the fs-watcher index.
+// Unknown ids return 404; nothing returns a silent 204 against an id the
+// manager does not know.
 import { Hono } from 'hono';
 import { stream } from 'hono/streaming';
 import { existsSync, statSync, createReadStream, watchFile, unwatchFile, rmSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
-import { spawnClaudeSession, deleteSession, PERMISSION_MODES } from './pty-spawner.js';
-import { listJsonlSessions, readJsonlSession, readSidecar, sidecarPathFor } from './jsonl-enumerator.js';
+import { spawnClaudeSession, stopSession, PERMISSION_MODES } from './pty-spawner.js';
+import { readJsonlSession, readSidecar, sidecarPathFor } from './jsonl-enumerator.js';
 import { claudeStateRoot, projectSlugForCwd } from './jsonl-path.js';
 import { basename, join } from 'node:path';
 const ROLES = ['admin', 'public'];
@@ -43,12 +35,10 @@ function parseAboutOwner(raw) {
     if (!raw || typeof raw !== 'object')
         return undefined;
     const r = raw;
-    if (r.ok === true && typeof r.body === 'string') {
+    if (r.ok === true && typeof r.body === 'string')
         return { ok: true, body: r.body };
-    }
-    if (r.ok === false && typeof r.reason === 'string' && r.reason.length > 0) {
+    if (r.ok === false && typeof r.reason === 'string' && r.reason.length > 0)
         return { ok: false, reason: r.reason };
-    }
     return undefined;
 }
 function parseDormantPlugins(raw) {
@@ -121,37 +111,40 @@ function parseSpecialistDomains(raw) {
     }
     return out.length > 0 ? out : undefined;
 }
-// Path-traversal guard. Bridge suffixes and intrinsic JSONL basenames both
-// match this character class.
+// `<id>` may be: intrinsic UUID, bridgeSessionId ("session_<suffix>"),
+// bridgeSuffix, or pid (numeric). All resolve to a sessionId via watcher.
 const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
 const LIST_TAIL_BYTES = 64 * 1024;
 const DISPLAY_NAME_MAX = 256;
 function timed(logger, method, path, status, ms) {
     logger(`api method=${method} path=${path} outcome=${status} ms=${ms}`);
 }
-/** Locate the JSONL path for any sessionId. For alive rows, returns null
- *  when the row has not yet promoted (no JSONL on disk yet). */
-function resolveJsonlPath(deps, sessionId) {
-    const live = deps.store.get(sessionId);
-    if (live && live.claudeSessionId !== null && live.jsonlPath !== null) {
-        return { path: live.jsonlPath, claudeSessionId: live.claudeSessionId };
-    }
-    if (live && live.claudeSessionId === null) {
-        // Row is alive but pre-promotion: no JSONL exists yet.
-        return null;
+/** Resolve any of the 4 keys to the canonical (sessionId, row) pair.
+ *  Tries: intrinsic sessionId, bridgeSessionId, bridgeSuffix, numeric pid.
+ *  Returns undefined when nothing matches. */
+function resolveRow(watcher, id) {
+    const direct = watcher.getBySessionId(id);
+    if (direct)
+        return direct;
+    const byBridge = watcher.getByBridgeSessionId(id);
+    if (byBridge)
+        return byBridge;
+    const bySuffix = watcher.getByBridgeSuffix(id);
+    if (bySuffix)
+        return bySuffix;
+    if (/^\d+$/.test(id)) {
+        const byPid = watcher.getByPid(Number(id));
+        if (byPid)
+            return byPid;
     }
-    const slug = projectSlugForCwd(deps.spawnCwd);
-    const path = join(claudeStateRoot(), 'projects', slug, `${sessionId}.jsonl`);
-    if (existsSync(path))
-        return { path, claudeSessionId: sessionId };
-    return null;
+    return undefined;
 }
 function attachPublicAudit(deps, session) {
     if (session.role !== 'public')
         return;
-    if (session.claudeSessionId === null || session.jsonlPath === null)
+    if (session.jsonlPath === null)
         return;
-    const claudeSessionId = session.claudeSessionId;
+    const claudeSessionId = session.sessionId;
     deps.publicToolAudit.attach(claudeSessionId, session.jsonlPath);
     if (session.exited) {
         deps.publicToolAudit.detach(claudeSessionId);
@@ -163,24 +156,41 @@ function attachPublicAudit(deps, session) {
 }
 export function buildHttpApp(deps) {
     const app = new Hono();
+    // Watcher subscriber: when JSONL CREATE fires for a live session,
+    // patch jsonlPath onto the StoredSession and attach the audit watcher.
+    deps.watcher.subscribe((event) => {
+        if (event.source !== 'jsonl')
+            return;
+        if (event.kind !== 'create' && event.kind !== 'modify')
+            return;
+        if (!event.row || !event.row.jsonlPath)
+            return;
+        const live = deps.store.get(event.sessionId);
+        if (!live)
+            return;
+        if (live.jsonlPath !== null)
+            return;
+        live.jsonlPath = event.row.jsonlPath;
+        deps.logger(`[fs-watcher] live-row-jsonl-attached sessionId=${event.sessionId} path=${event.row.jsonlPath}`);
+        attachPublicAudit(deps, live);
+    });
     function liveDisplayName(s, sidecarName) {
         if (sidecarName && sidecarName.trim())
             return sidecarName.trim();
-        if (s.jsonlPath && s.claudeSessionId && existsSync(s.jsonlPath)) {
-            const enriched = readJsonlSession(deps.spawnCwd, s.claudeSessionId, LIST_TAIL_BYTES, deps.logger);
+        if (s.jsonlPath && existsSync(s.jsonlPath)) {
+            const enriched = readJsonlSession(deps.spawnCwd, s.sessionId, LIST_TAIL_BYTES, deps.logger);
             if (enriched?.aiTitle?.trim())
                 return enriched.aiTitle.trim();
         }
-        // pre-promotion → 8 chars of the bridge suffix; post-promotion → 8
-        // chars of the intrinsic id (which the operator may copy into resume).
-        return (s.claudeSessionId ?? s.bridgeSuffix).slice(0, 8);
+        return s.sessionId.slice(0, 8);
     }
     function toLivePayload(s) {
         const sidecar = s.jsonlPath ? readSidecar(s.jsonlPath) : null;
         const hasJsonl = s.jsonlPath !== null && existsSync(s.jsonlPath);
         return {
-            sessionId: s.bridgeSuffix,
-            claudeSessionId: s.claudeSessionId,
+            sessionId: s.sessionId,
+            claudeSessionId: s.sessionId,
+            bridgeSessionId: s.bridgeSessionId,
             pid: s.pid,
             url: s.url,
             startedAt: s.startedAt,
@@ -198,6 +208,45 @@ export function buildHttpApp(deps) {
             specialist: s.specialist,
         };
     }
+    function toArchivedPayload(row, senderId) {
+        let displayName = row.sessionId.slice(0, 8);
+        let lastMessageAt = null;
+        let turnCount = 0;
+        let capped = false;
+        let sizeBytes = null;
+        let startedAt = new Date(row.updatedAt || 0).toISOString();
+        if (row.jsonlPath && existsSync(row.jsonlPath)) {
+            const enriched = readJsonlSession(deps.spawnCwd, row.sessionId, LIST_TAIL_BYTES, deps.logger);
+            if (enriched) {
+                displayName = enriched.displayName;
+                lastMessageAt = enriched.lastMessageAt;
+                turnCount = enriched.turnCount;
+                capped = enriched.capped;
+                sizeBytes = enriched.sizeBytes;
+                startedAt = enriched.startedAt;
+            }
+        }
+        return {
+            sessionId: row.sessionId,
+            claudeSessionId: row.sessionId,
+            bridgeSessionId: row.bridgeSessionId,
+            pid: null,
+            url: null,
+            startedAt,
+            senderId,
+            role: null,
+            channel: null,
+            jsonlPath: row.jsonlPath,
+            status: 'ended',
+            displayName,
+            lastMessageAt,
+            turnCount,
+            capped,
+            sizeBytes,
+            hidden: false,
+            specialist: row.agent,
+        };
+    }
     app.post('/spawn', async (c) => {
         const start = Date.now();
         let body;
@@ -216,7 +265,6 @@ export function buildHttpApp(deps) {
         const specialist = typeof body.specialist === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(body.specialist)
             ? body.specialist
             : undefined;
-        const stdinPayload = typeof body.stdinPayload === 'string' ? body.stdinPayload : undefined;
         const aboutOwnerShape = body.aboutOwner == null ? 'absent' : (typeof body.aboutOwner === 'object' ? 'object' : typeof body.aboutOwner);
         const dormantPluginsShape = Array.isArray(body.dormantPlugins)
             ? `array(${body.dormantPlugins.length})`
@@ -250,16 +298,12 @@ export function buildHttpApp(deps) {
         const dormantPlugins = parseDormantPlugins(body.dormantPlugins);
         const activePlugins = parseActivePlugins(body.activePlugins);
         const specialistDomains = parseSpecialistDomains(body.specialistDomains);
-        // tunnelUrl override resolved upstream by the UI process from the
-        // brand's tunnel.state on disk (the manager has no Neo4j credentials).
-        // string → render; null → render `tunnel-url: none`; undefined → fall
-        // back to deps.host.tunnelUrl (whatever boot resolved).
         const tunnelUrlOverride = typeof body.tunnelUrl === 'string'
             ? body.tunnelUrl
             : body.tunnelUrl === null
                 ? null
                 : undefined;
-        const result = await spawnClaudeSession({ ...deps, store: deps.store, onJsonlObserved: (s) => attachPublicAudit(deps, s), tunnelUrlOverride }, {
+        const result = await spawnClaudeSession({ ...deps, store: deps.store, watcher: deps.watcher, onSessionReady: (s) => attachPublicAudit(deps, s), tunnelUrlOverride }, {
             senderId,
             role: role,
             channel: channel,
@@ -272,19 +316,147 @@ export function buildHttpApp(deps) {
             specialistDomains,
             hidden,
             specialist,
-            stdinPayload,
         });
         if (!result.ok) {
-            // Every remaining spawn-failure surface is 500: which-claude-not-found,
-            // pty-spawn-failed, url-capture-timeout, bridge-suffix-unparseable,
-            // host-context-unresolved, identity-unresolved. The observe-timeout 504
-            // is gone — /spawn never blocks on observation.
+            if ('rejected' in result) {
+                timed(deps.logger, 'POST', '/spawn', 503, Date.now() - start);
+                if (result.rejected.kind === 'specialist-cap-reached') {
+                    return c.json({ error: 'specialist-cap-reached', currentCount: result.rejected.currentCount, cap: result.rejected.cap }, 503);
+                }
+                return c.json({ error: 'operator-slots-reserved', total: result.rejected.total, reserve: result.rejected.reserve, totalCap: result.rejected.totalCap }, 503);
+            }
             timed(deps.logger, 'POST', '/spawn', 500, Date.now() - start);
             return c.json({ error: 'spawn-failed', reason: result.reason, stderrTail: result.stderrTail }, 500);
         }
         timed(deps.logger, 'POST', '/spawn', 200, Date.now() - start);
         return c.json(toLivePayload(result.session), 200);
     });
+    // SSE feed of row deltas. One channel per client; manager fans out from
+    // a single watcher subscription. On connect: replay current rows as
+    // `row-created`, then stream subsequent watcher events as
+    // `row-<created|updated|archived|removed>`.
+    //
+    // Payload shape per event (`data: <json>`):
+    //   { sessionId, live, status, agentLabel, bridgeSessionId, cwd,
+    //     firstPrompt, updatedAt }
+    //
+    // `live` mirrors the watcher's `state === 'live'`. `status` is the
+    // watcher's `idle | busy | gone`. `agentLabel` is the resolution
+    // `agent ?? cachedAgentSetting`; the UI maps null → "admin",
+    // non-null → the specialist name. `firstPrompt` is the resolved
+    // displayName (sidecar → ai-title → 8-char slice) so the row title is
+    // computed once on the server, not by every browser tab.
+    app.get('/events', (c) => {
+        const start = Date.now();
+        const clientIp = c.req.header('x-forwarded-for') ?? 'loopback';
+        const replayRows = deps.watcher.all();
+        deps.logger(`[admin-events] client-connected ip=${clientIp} seeded-rows=${replayRows.length}`);
+        function rowToPayload(row) {
+            const agentLabel = row.agent ?? row.cachedAgentSetting ?? null;
+            let firstPrompt = null;
+            if (row.jsonlPath && existsSync(row.jsonlPath)) {
+                const enriched = readJsonlSession(deps.spawnCwd, row.sessionId, LIST_TAIL_BYTES, deps.logger);
+                if (enriched)
+                    firstPrompt = enriched.displayName;
+            }
+            if (!firstPrompt) {
+                const sidecar = row.jsonlPath ? readSidecar(row.jsonlPath) : null;
+                firstPrompt = sidecar?.displayName ?? row.sessionId.slice(0, 8);
+            }
+            return {
+                sessionId: row.sessionId,
+                live: row.state === 'live',
+                status: row.status,
+                agentLabel,
+                bridgeSessionId: row.bridgeSessionId,
+                cwd: row.cwd,
+                firstPrompt,
+                updatedAt: row.updatedAt,
+            };
+        }
+        timed(deps.logger, 'GET', '/events', 200, Date.now() - start);
+        return stream(c, async (out) => {
+            // SSE response headers — Hono's stream() helper sets text/event-stream
+            // automatically, but we explicitly disable proxy buffering so the
+            // first replay batch arrives before any keep-alive.
+            c.header('Content-Type', 'text/event-stream');
+            c.header('Cache-Control', 'no-cache, no-transform');
+            c.header('X-Accel-Buffering', 'no');
+            c.header('Connection', 'keep-alive');
+            const connectStart = Date.now();
+            let active = true;
+            let subscribersCount = 0;
+            // Replay phase. Emit a `row-created` for every row in the index so
+            // a freshly-connected tab catches up to the manager's view before
+            // any subsequent delta arrives.
+            for (const row of replayRows) {
+                if (!active)
+                    break;
+                const payload = rowToPayload(row);
+                await out.write(`event: row-created\ndata: ${JSON.stringify(payload)}\n\n`);
+            }
+            // Delta phase. Subscribe to the watcher and map watcher events to
+            // the four SSE event kinds. Mapping:
+            //   create  → row-created
+            //   modify  → row-updated   (state may have flipped — see archive)
+            //   delete  → row-removed when the row is fully gone, row-archived
+            //             when the PID file went away but the JSONL survives.
+            const unsubscribe = deps.watcher.subscribe((event) => {
+                if (!active)
+                    return;
+                // The watcher emits a synthetic `kind=modify source=jsonl` pair
+                // immediately after `kind=delete source=pid` when a row demotes
+                // from live → archived. Treat that pair as one `row-archived`
+                // event so the UI sees a single transition rather than a delete
+                // followed by an unrelated update.
+                if (event.kind === 'delete' && event.source === 'pid' && event.row) {
+                    const payload = rowToPayload(event.row);
+                    subscribersCount += 1;
+                    deps.logger(`[admin-events] emit event=row-archived sessionId=${event.sessionId} subscribers=1`);
+                    void out.write(`event: row-archived\ndata: ${JSON.stringify(payload)}\n\n`);
+                    return;
+                }
+                if (event.kind === 'delete' && event.source === 'jsonl' && !event.row) {
+                    subscribersCount += 1;
+                    deps.logger(`[admin-events] emit event=row-removed sessionId=${event.sessionId} subscribers=1`);
+                    void out.write(`event: row-removed\ndata: ${JSON.stringify({ sessionId: event.sessionId })}\n\n`);
+                    return;
+                }
+                // Skip the synthetic `modify jsonl` half of the demote pair —
+                // it carries the same row state already emitted as row-archived.
+                if (event.kind === 'modify' && event.source === 'jsonl' && event.row && event.row.state === 'archived' && event.row.pidFilePath === null) {
+                    return;
+                }
+                if (!event.row)
+                    return;
+                const sseEvent = event.kind === 'create' ? 'row-created' : 'row-updated';
+                const payload = rowToPayload(event.row);
+                subscribersCount += 1;
+                deps.logger(`[admin-events] emit event=${sseEvent} sessionId=${event.sessionId} subscribers=1`);
+                void out.write(`event: ${sseEvent}\ndata: ${JSON.stringify(payload)}\n\n`);
+            });
+            // Keep-alive comment every 25 s. Proxies aggressively close idle
+            // text/event-stream connections at 30–60 s; a comment line is
+            // ignored by EventSource consumers but resets the proxy clock.
+            const keepAlive = setInterval(() => {
+                if (!active)
+                    return;
+                void out.write(`: keep-alive ${Date.now()}\n\n`);
+            }, 25_000);
+            out.onAbort(() => {
+                active = false;
+                clearInterval(keepAlive);
+                unsubscribe();
+                const durationMs = Date.now() - connectStart;
+                deps.logger(`[admin-events] client-disconnected ip=${clientIp} duration-ms=${durationMs} emits=${subscribersCount}`);
+            });
+            // Park the stream open until the client aborts. Without this the
+            // handler returns and Hono closes the response.
+            while (active) {
+                await new Promise((resolve) => setTimeout(resolve, 1_000));
+            }
+        });
+    });
     app.get('/list', (c) => {
         const start = Date.now();
         const senderId = c.req.query('senderId') ?? '';
@@ -295,36 +467,22 @@ export function buildHttpApp(deps) {
         }
         const liveStored = deps.store.listBySender(senderId, { includeHidden });
         const live = liveStored.map(toLivePayload);
-        // Live rows dedup against dehydrated by intrinsic id when promoted;
-        // un-promoted rows have no intrinsic id and cannot collide with disk.
-        const liveIntrinsicIds = new Set();
-        for (const s of liveStored) {
-            if (s.claudeSessionId !== null)
-                liveIntrinsicIds.add(s.claudeSessionId);
-        }
+        const liveSessionIds = new Set();
+        for (const s of liveStored)
+            liveSessionIds.add(s.sessionId);
+        // Archived rows come from the watcher's JSONL index (rows whose
+        // state === 'archived'). The watcher's boot-seed already paired
+        // PID files with JSONLs on disk, so archived rows here are exactly
+        // the sessions whose PTY has exited but transcript persists.
         const dehydrated = [];
-        for (const j of listJsonlSessions(deps.spawnCwd, LIST_TAIL_BYTES, deps.logger)) {
-            if (liveIntrinsicIds.has(j.claudeSessionId))
+        for (const row of deps.watcher.all()) {
+            if (row.state !== 'archived')
                 continue;
-            dehydrated.push({
-                sessionId: j.claudeSessionId,
-                claudeSessionId: j.claudeSessionId,
-                pid: null,
-                url: null,
-                startedAt: j.startedAt,
-                senderId,
-                role: null,
-                channel: null,
-                jsonlPath: j.jsonlPath,
-                status: 'ended',
-                displayName: j.displayName,
-                lastMessageAt: j.lastMessageAt,
-                turnCount: j.turnCount,
-                capped: j.capped,
-                sizeBytes: j.sizeBytes,
-                hidden: false,
-                specialist: null,
-            });
+            if (liveSessionIds.has(row.sessionId))
+                continue;
+            if (!row.jsonlPath)
+                continue;
+            dehydrated.push(toArchivedPayload(row, senderId));
         }
         deps.logger(`list-source live=${live.length} jsonl=${dehydrated.length}`);
         const merged = [...live, ...dehydrated];
@@ -362,7 +520,7 @@ export function buildHttpApp(deps) {
             : body.tunnelUrl === null
                 ? null
                 : undefined;
-        const result = await spawnClaudeSession({ ...deps, store: deps.store, onJsonlObserved: (s) => attachPublicAudit(deps, s), tunnelUrlOverride }, {
+        const result = await spawnClaudeSession({ ...deps, store: deps.store, watcher: deps.watcher, onSessionReady: (s) => attachPublicAudit(deps, s), tunnelUrlOverride }, {
             senderId,
             role: role,
             channel: channel,
@@ -374,22 +532,34 @@ export function buildHttpApp(deps) {
             specialistDomains,
         });
         if (!result.ok) {
+            if ('rejected' in result) {
+                timed(deps.logger, 'POST', '/resume', 503, Date.now() - start);
+                if (result.rejected.kind === 'specialist-cap-reached') {
+                    return c.json({ error: 'specialist-cap-reached', currentCount: result.rejected.currentCount, cap: result.rejected.cap }, 503);
+                }
+                return c.json({ error: 'operator-slots-reserved', total: result.rejected.total, reserve: result.rejected.reserve, totalCap: result.rejected.totalCap }, 503);
+            }
             deps.logger(`resume-failed reason=${result.reason} resumeFrom=${claudeSessionId}`);
             timed(deps.logger, 'POST', '/resume', 500, Date.now() - start);
             return c.json({ error: 'resume-failed', reason: result.reason }, 500);
         }
-        deps.logger(`resume pid=${result.session.pid} sessionUrl=${result.session.url} resumeFrom=${claudeSessionId} latency-ms=${Date.now() - start}`);
+        deps.logger(`resume pid=${result.session.pid} sessionId=${result.session.sessionId} resumeFrom=${claudeSessionId} latency-ms=${Date.now() - start}`);
         timed(deps.logger, 'POST', '/resume', 200, Date.now() - start);
         return c.json(toLivePayload(result.session), 200);
     });
     app.get('/:sessionId/meta', (c) => {
         const start = Date.now();
-        const sessionId = c.req.param('sessionId');
-        if (!SESSION_ID_PATTERN.test(sessionId)) {
-            timed(deps.logger, 'GET', `/${sessionId}/meta`, 400, Date.now() - start);
+        const id = c.req.param('sessionId');
+        if (!SESSION_ID_PATTERN.test(id)) {
+            timed(deps.logger, 'GET', `/${id}/meta`, 400, Date.now() - start);
             return c.json({ error: 'invalid-session-id' }, 400);
         }
-        const live = deps.store.get(sessionId);
+        const row = resolveRow(deps.watcher, id);
+        if (!row) {
+            timed(deps.logger, 'GET', `/${id}/meta`, 404, Date.now() - start);
+            return c.json({ error: 'session-not-found' }, 404);
+        }
+        const live = deps.store.get(row.sessionId);
         let payload;
         if (live) {
             const base = toLivePayload(live);
@@ -397,8 +567,8 @@ export function buildHttpApp(deps) {
             let turnCount = 0;
             let capped = false;
             let sizeBytes = base.sizeBytes;
-            if (live.claudeSessionId && live.jsonlPath && existsSync(live.jsonlPath)) {
-                const enriched = readJsonlSession(deps.spawnCwd, live.claudeSessionId, deps.jsonlReadMaxBytes, deps.logger);
+            if (live.jsonlPath && existsSync(live.jsonlPath)) {
+                const enriched = readJsonlSession(deps.spawnCwd, live.sessionId, deps.jsonlReadMaxBytes, deps.logger);
                 if (enriched) {
                     lastMessageAt = enriched.lastMessageAt;
                     turnCount = enriched.turnCount;
@@ -406,50 +576,20 @@ export function buildHttpApp(deps) {
                     sizeBytes = enriched.sizeBytes;
                 }
             }
-            payload = {
-                ...base,
-                lastMessageAt,
-                turnCount,
-                capped,
-                sizeBytes,
-            };
+            payload = { ...base, lastMessageAt, turnCount, capped, sizeBytes };
         }
         else {
-            const enriched = readJsonlSession(deps.spawnCwd, sessionId, deps.jsonlReadMaxBytes, deps.logger);
-            if (!enriched) {
-                timed(deps.logger, 'GET', `/${sessionId}/meta`, 404, Date.now() - start);
-                return c.json({ error: 'session-not-found' }, 404);
-            }
-            payload = {
-                sessionId: enriched.claudeSessionId,
-                claudeSessionId: enriched.claudeSessionId,
-                pid: null,
-                url: null,
-                startedAt: enriched.startedAt,
-                senderId: '',
-                role: null,
-                channel: null,
-                jsonlPath: enriched.jsonlPath,
-                status: 'ended',
-                displayName: enriched.displayName,
-                lastMessageAt: enriched.lastMessageAt,
-                turnCount: enriched.turnCount,
-                capped: enriched.capped,
-                sizeBytes: enriched.sizeBytes,
-                hidden: false,
-                specialist: null,
-            };
-            deps.logger(`meta-jsonl-tail-bytes sessionId=${sessionId.slice(0, 8)} read=${Math.min(enriched.sizeBytes, deps.jsonlReadMaxBytes)} capped=${enriched.capped}`);
+            payload = toArchivedPayload(row, '');
         }
-        deps.logger(`meta sessionId=${sessionId.slice(0, 8)} fields=${Object.keys(payload).length} ms=${Date.now() - start}`);
-        timed(deps.logger, 'GET', `/${sessionId}/meta`, 200, Date.now() - start);
+        deps.logger(`meta sessionId=${row.sessionId.slice(0, 8)} fields=${Object.keys(payload).length} ms=${Date.now() - start}`);
+        timed(deps.logger, 'GET', `/${id}/meta`, 200, Date.now() - start);
         return c.json(payload, 200);
     });
     app.patch('/:sessionId', async (c) => {
         const start = Date.now();
-        const sessionId = c.req.param('sessionId');
-        if (!SESSION_ID_PATTERN.test(sessionId)) {
-            timed(deps.logger, 'PATCH', `/${sessionId}`, 400, Date.now() - start);
+        const id = c.req.param('sessionId');
+        if (!SESSION_ID_PATTERN.test(id)) {
+            timed(deps.logger, 'PATCH', `/${id}`, 400, Date.now() - start);
             return c.json({ error: 'invalid-session-id' }, 400);
         }
         let body;
@@ -457,38 +597,38 @@ export function buildHttpApp(deps) {
             body = await c.req.json();
         }
         catch {
-            timed(deps.logger, 'PATCH', `/${sessionId}`, 400, Date.now() - start);
+            timed(deps.logger, 'PATCH', `/${id}`, 400, Date.now() - start);
             return c.json({ error: 'body-not-json' }, 400);
         }
         if (typeof body.displayName !== 'string' || body.displayName.length === 0 || body.displayName.length > DISPLAY_NAME_MAX) {
-            timed(deps.logger, 'PATCH', `/${sessionId}`, 400, Date.now() - start);
+            timed(deps.logger, 'PATCH', `/${id}`, 400, Date.now() - start);
             return c.json({ error: 'invalid-displayName', detail: { maxLen: DISPLAY_NAME_MAX } }, 400);
         }
-        const resolved = resolveJsonlPath(deps, sessionId);
-        if (!resolved) {
-            timed(deps.logger, 'PATCH', `/${sessionId}`, 404, Date.now() - start);
+        const row = resolveRow(deps.watcher, id);
+        if (!row || !row.jsonlPath) {
+            timed(deps.logger, 'PATCH', `/${id}`, 404, Date.now() - start);
             return c.json({ error: 'session-not-found' }, 404);
         }
-        const sidecarPath = sidecarPathFor(resolved.path);
-        const prior = readSidecar(resolved.path)?.displayName ?? null;
+        const sidecarPath = sidecarPathFor(row.jsonlPath);
+        const prior = readSidecar(row.jsonlPath)?.displayName ?? null;
         try {
             writeFileSync(sidecarPath, JSON.stringify({ displayName: body.displayName }, null, 2) + '\n', 'utf8');
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            deps.logger(`rename-failed sessionId=${sessionId.slice(0, 8)} message=${msg}`);
-            timed(deps.logger, 'PATCH', `/${sessionId}`, 500, Date.now() - start);
+            deps.logger(`rename-failed sessionId=${row.sessionId.slice(0, 8)} message=${msg}`);
+            timed(deps.logger, 'PATCH', `/${id}`, 500, Date.now() - start);
             return c.json({ error: 'sidecar-write-failed', detail: msg }, 500);
         }
-        deps.logger(`rename sessionId=${sessionId.slice(0, 8)} from=${prior ?? ''} to=${body.displayName}`);
-        timed(deps.logger, 'PATCH', `/${sessionId}`, 200, Date.now() - start);
+        deps.logger(`rename sessionId=${row.sessionId.slice(0, 8)} from=${prior ?? ''} to=${body.displayName}`);
+        timed(deps.logger, 'PATCH', `/${id}`, 200, Date.now() - start);
         return c.json({ ok: true, displayName: body.displayName }, 200);
     });
     app.post('/:sessionId/archive', async (c) => {
         const start = Date.now();
-        const sessionId = c.req.param('sessionId');
-        if (!SESSION_ID_PATTERN.test(sessionId)) {
-            timed(deps.logger, 'POST', `/${sessionId}/archive`, 400, Date.now() - start);
+        const id = c.req.param('sessionId');
+        if (!SESSION_ID_PATTERN.test(id)) {
+            timed(deps.logger, 'POST', `/${id}/archive`, 400, Date.now() - start);
             return c.json({ error: 'invalid-session-id' }, 400);
         }
         let body;
@@ -496,30 +636,35 @@ export function buildHttpApp(deps) {
             body = await c.req.json();
         }
         catch {
-            timed(deps.logger, 'POST', `/${sessionId}/archive`, 400, Date.now() - start);
+            timed(deps.logger, 'POST', `/${id}/archive`, 400, Date.now() - start);
             return c.json({ error: 'body-not-json' }, 400);
         }
         const mode = body.mode;
         if (mode !== 'archive' && mode !== 'unarchive') {
-            timed(deps.logger, 'POST', `/${sessionId}/archive`, 400, Date.now() - start);
+            timed(deps.logger, 'POST', `/${id}/archive`, 400, Date.now() - start);
             return c.json({ error: 'invalid-mode', detail: { expected: ['archive', 'unarchive'] } }, 400);
         }
-        if (deps.store.get(sessionId)) {
-            deps.logger(`archive-rejected sessionId=${sessionId.slice(0, 8)} reason=pty-still-alive`);
-            timed(deps.logger, 'POST', `/${sessionId}/archive`, 409, Date.now() - start);
+        const row = resolveRow(deps.watcher, id);
+        if (!row) {
+            timed(deps.logger, 'POST', `/${id}/archive`, 404, Date.now() - start);
+            return c.json({ error: 'session-not-found' }, 404);
+        }
+        if (deps.store.get(row.sessionId)) {
+            deps.logger(`archive-rejected sessionId=${row.sessionId.slice(0, 8)} reason=pty-still-alive`);
+            timed(deps.logger, 'POST', `/${id}/archive`, 409, Date.now() - start);
             return c.json({ error: 'pty-still-alive', detail: 'end the session before archiving' }, 409);
         }
         const slug = projectSlugForCwd(deps.spawnCwd);
         const slugDir = join(claudeStateRoot(), 'projects', slug);
         const archiveDir = join(slugDir, 'archive');
-        const fileName = `${sessionId}.jsonl`;
-        const sidecarName = `${sessionId}.meta.json`;
+        const fileName = `${row.sessionId}.jsonl`;
+        const sidecarName = `${row.sessionId}.meta.json`;
         const fromJsonl = mode === 'archive' ? join(slugDir, fileName) : join(archiveDir, fileName);
         const toJsonl = mode === 'archive' ? join(archiveDir, fileName) : join(slugDir, fileName);
         const fromSidecar = mode === 'archive' ? join(slugDir, sidecarName) : join(archiveDir, sidecarName);
         const toSidecar = mode === 'archive' ? join(archiveDir, sidecarName) : join(slugDir, sidecarName);
         if (!existsSync(fromJsonl)) {
-            timed(deps.logger, 'POST', `/${sessionId}/archive`, 404, Date.now() - start);
+            timed(deps.logger, 'POST', `/${id}/archive`, 404, Date.now() - start);
             return c.json({ error: 'session-not-found' }, 404);
         }
         try {
@@ -531,49 +676,63 @@ export function buildHttpApp(deps) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            deps.logger(`archive-failed sessionId=${sessionId.slice(0, 8)} mode=${mode} message=${msg}`);
-            timed(deps.logger, 'POST', `/${sessionId}/archive`, 500, Date.now() - start);
+            deps.logger(`archive-failed sessionId=${row.sessionId.slice(0, 8)} mode=${mode} message=${msg}`);
+            timed(deps.logger, 'POST', `/${id}/archive`, 500, Date.now() - start);
             return c.json({ error: 'archive-failed', detail: msg }, 500);
         }
-        deps.logger(`archive sessionId=${sessionId.slice(0, 8)} from=${basename(fromJsonl)} to=${join(mode === 'archive' ? 'archive' : '.', basename(toJsonl))}`);
-        timed(deps.logger, 'POST', `/${sessionId}/archive`, 200, Date.now() - start);
+        deps.logger(`archive sessionId=${row.sessionId.slice(0, 8)} from=${basename(fromJsonl)} to=${join(mode === 'archive' ? 'archive' : '.', basename(toJsonl))}`);
+        timed(deps.logger, 'POST', `/${id}/archive`, 200, Date.now() - start);
         return c.json({ ok: true, mode }, 200);
     });
-    app.delete('/:sessionId', async (c) => {
+    // SIGTERM-only stop. Idempotent on already-dead PTYs. JSONL untouched.
+    app.post('/:sessionId/stop', async (c) => {
         const start = Date.now();
-        const sessionId = c.req.param('sessionId');
-        const purge = c.req.query('purge') === '1';
-        if (!SESSION_ID_PATTERN.test(sessionId)) {
-            timed(deps.logger, 'DELETE', `/${sessionId}`, 400, Date.now() - start);
+        const id = c.req.param('sessionId');
+        if (!SESSION_ID_PATTERN.test(id) && !/^\d+$/.test(id)) {
+            timed(deps.logger, 'POST', `/${id}/stop`, 400, Date.now() - start);
             return c.json({ error: 'invalid-session-id' }, 400);
         }
-        if (!purge) {
-            await deleteSession({ store: deps.store, killGraceMs: deps.killGraceMs, logger: deps.logger }, sessionId);
-            timed(deps.logger, 'DELETE', `/${sessionId}`, 204, Date.now() - start);
-            return c.body(null, 204);
+        const row = resolveRow(deps.watcher, id);
+        if (!row && !deps.store.get(id)) {
+            timed(deps.logger, 'POST', `/${id}/stop`, 404, Date.now() - start);
+            return c.json({ error: 'session-not-found' }, 404);
+        }
+        const sessionId = row?.sessionId ?? id;
+        await stopSession({ store: deps.store, killGraceMs: deps.killGraceMs, logger: deps.logger }, sessionId);
+        timed(deps.logger, 'POST', `/${sessionId}/stop`, 204, Date.now() - start);
+        return c.body(null, 204);
+    });
+    // Hard-remove transcript. 409 if PTY is still alive (stop first).
+    app.delete('/:sessionId', async (c) => {
+        const start = Date.now();
+        const id = c.req.param('sessionId');
+        if (!SESSION_ID_PATTERN.test(id) && !/^\d+$/.test(id)) {
+            timed(deps.logger, 'DELETE', `/${id}`, 400, Date.now() - start);
+            return c.json({ error: 'invalid-session-id' }, 400);
         }
+        const row = resolveRow(deps.watcher, id);
+        const sessionId = row?.sessionId ?? id;
         if (deps.store.get(sessionId)) {
-            deps.logger(`purge-rejected sessionId=${sessionId.slice(0, 8)} reason=pty-still-alive`);
-            timed(deps.logger, 'DELETE', `/${sessionId}?purge=1`, 409, Date.now() - start);
-            return c.json({ error: 'pty-still-alive', detail: 'end the session before purging' }, 409);
+            deps.logger(`delete-rejected sessionId=${sessionId.slice(0, 8)} reason=pty-still-alive`);
+            timed(deps.logger, 'DELETE', `/${id}`, 409, Date.now() - start);
+            return c.json({ error: 'pty-still-alive', detail: 'stop the session before deleting' }, 409);
         }
-        const resolved = resolveJsonlPath(deps, sessionId);
-        if (!resolved) {
-            timed(deps.logger, 'DELETE', `/${sessionId}?purge=1`, 404, Date.now() - start);
+        if (!row || !row.jsonlPath) {
+            timed(deps.logger, 'DELETE', `/${id}`, 404, Date.now() - start);
             return c.json({ error: 'session-not-found' }, 404);
         }
-        const sidecarPath = sidecarPathFor(resolved.path);
+        const sidecarPath = sidecarPathFor(row.jsonlPath);
         const subdir = join(claudeStateRoot(), 'projects', projectSlugForCwd(deps.spawnCwd), sessionId);
         let bytes = 0;
         try {
-            bytes = existsSync(resolved.path) ? statSync(resolved.path).size : 0;
+            bytes = existsSync(row.jsonlPath) ? statSync(row.jsonlPath).size : 0;
         }
         catch {
-            // ignore — size is informational
+            // size is informational
         }
         try {
-            if (existsSync(resolved.path))
-                rmSync(resolved.path);
+            if (existsSync(row.jsonlPath))
+                rmSync(row.jsonlPath);
             if (existsSync(sidecarPath))
                 rmSync(sidecarPath);
             if (existsSync(subdir))
@@ -581,24 +740,26 @@ export function buildHttpApp(deps) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            deps.logger(`purge-failed sessionId=${sessionId.slice(0, 8)} message=${msg}`);
-            timed(deps.logger, 'DELETE', `/${sessionId}?purge=1`, 500, Date.now() - start);
-            return c.json({ error: 'purge-failed', detail: msg }, 500);
+            deps.logger(`delete-failed sessionId=${sessionId.slice(0, 8)} message=${msg}`);
+            timed(deps.logger, 'DELETE', `/${id}`, 500, Date.now() - start);
+            return c.json({ error: 'delete-failed', detail: msg }, 500);
         }
         deps.logger(`purge sessionId=${sessionId.slice(0, 8)} bytes=${bytes}`);
-        timed(deps.logger, 'DELETE', `/${sessionId}?purge=1`, 204, Date.now() - start);
+        timed(deps.logger, 'DELETE', `/${id}`, 204, Date.now() - start);
         return c.body(null, 204);
     });
     app.post('/:sessionId/input', async (c) => {
         const start = Date.now();
-        const sessionId = c.req.param('sessionId');
+        const id = c.req.param('sessionId');
+        const row = resolveRow(deps.watcher, id);
+        const sessionId = row?.sessionId ?? id;
         const s = deps.store.get(sessionId);
         if (!s) {
-            timed(deps.logger, 'POST', `/${sessionId}/input`, 404, Date.now() - start);
+            timed(deps.logger, 'POST', `/${id}/input`, 404, Date.now() - start);
             return c.json({ error: 'session-not-found' }, 404);
         }
         if (s.exited) {
-            timed(deps.logger, 'POST', `/${sessionId}/input`, 410, Date.now() - start);
+            timed(deps.logger, 'POST', `/${id}/input`, 410, Date.now() - start);
             return c.json({ error: 'session-exited' }, 410);
         }
         let body;
@@ -606,11 +767,11 @@ export function buildHttpApp(deps) {
             body = await c.req.json();
         }
         catch {
-            timed(deps.logger, 'POST', `/${sessionId}/input`, 400, Date.now() - start);
+            timed(deps.logger, 'POST', `/${id}/input`, 400, Date.now() - start);
             return c.json({ error: 'body-not-json' }, 400);
         }
         if (typeof body.text !== 'string') {
-            timed(deps.logger, 'POST', `/${sessionId}/input`, 400, Date.now() - start);
+            timed(deps.logger, 'POST', `/${id}/input`, 400, Date.now() - start);
             return c.json({ error: 'text-required' }, 400);
         }
         const bytes = Buffer.byteLength(body.text, 'utf8');
@@ -620,26 +781,25 @@ export function buildHttpApp(deps) {
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             deps.logger(`input-failed pid=${s.pid} sessionId=${sessionId} message=${msg}`);
-            timed(deps.logger, 'POST', `/${sessionId}/input`, 500, Date.now() - start);
+            timed(deps.logger, 'POST', `/${id}/input`, 500, Date.now() - start);
             return c.json({ error: 'pty-write-failed', detail: msg }, 500);
         }
         deps.logger(`input pid=${s.pid} sessionId=${sessionId} bytes=${bytes} channel=${s.channel}`);
-        timed(deps.logger, 'POST', `/${sessionId}/input`, 200, Date.now() - start);
+        timed(deps.logger, 'POST', `/${id}/input`, 200, Date.now() - start);
         return c.json({ ok: true, bytes }, 200);
     });
     app.get('/:sessionId/log', (c) => {
         const start = Date.now();
-        const sessionId = c.req.param('sessionId');
+        const id = c.req.param('sessionId');
+        const row = resolveRow(deps.watcher, id);
+        const sessionId = row?.sessionId ?? id;
         const s = deps.store.get(sessionId);
         if (!s) {
-            timed(deps.logger, 'GET', `/${sessionId}/log`, 404, Date.now() - start);
+            timed(deps.logger, 'GET', `/${id}/log`, 404, Date.now() - start);
             return c.json({ error: 'session-not-found' }, 404);
         }
         if (s.jsonlPath === null) {
-            // alive but pre-promotion: the first operator turn has not landed,
-            // so claude has not written a JSONL yet. Loud-fail with 202 so the
-            // UI can re-poll once `claudeSessionId` flips on a subsequent /list.
-            timed(deps.logger, 'GET', `/${sessionId}/log`, 202, Date.now() - start);
+            timed(deps.logger, 'GET', `/${id}/log`, 202, Date.now() - start);
             return c.json({ jsonlPath: null, exists: false, sizeBytes: 0, pending: true }, 202);
         }
         const jsonlPath = s.jsonlPath;
@@ -647,10 +807,10 @@ export function buildHttpApp(deps) {
         if (!follow) {
             const exists = existsSync(jsonlPath);
             const sizeBytes = exists ? statSync(jsonlPath).size : 0;
-            timed(deps.logger, 'GET', `/${sessionId}/log`, 200, Date.now() - start);
+            timed(deps.logger, 'GET', `/${id}/log`, 200, Date.now() - start);
             return c.json({ jsonlPath, exists, sizeBytes }, 200);
         }
-        timed(deps.logger, 'GET', `/${sessionId}/log?follow=1`, 200, Date.now() - start);
+        timed(deps.logger, 'GET', `/${id}/log?follow=1`, 200, Date.now() - start);
         return stream(c, async (out) => {
             let position = 0;
             if (existsSync(jsonlPath)) {