@rubytech/create-maxy-code 0.1.35 → 0.1.37

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

@@ -3,7 +3,7 @@
 // here via fetch.
 //
 // Routes:
-//   POST   /spawn               { senderId, role, channel } -> Session
+//   POST   /spawn               { senderId, role, channel, tunnelUrl? } -> Session
 //   GET    /list?senderId=...   -> Session[]
 //   POST   /resume              { senderId, role, channel, claudeSessionId } -> Session
 //   DELETE /:sessionId          -> 204
@@ -14,15 +14,22 @@
 //   GET    /:sessionId/meta     -> SessionMeta payload
 //   PATCH  /:sessionId          { displayName } -> 204 (writes sidecar)
 //
-// The `/log` route returns the path of claude's per-session JSONL transcript
-// (not a manager-written .pty file — that's gone). On a streaming request
-// (?follow=1) the manager opens the file, streams the current bytes, then
-// watches for appends and pushes them as they arrive. On client disconnect
-// the watcher is cleared.
+// `/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.
 //
-// sidecar `<id>.meta.json` next to the JSONL holds operator-
-// owned fields (displayName). PATCH writes it; /meta reads it via the
-// enumerator helpers. Sidecar never touches the claude-owned JSONL.
+// 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.
 import { Hono } from 'hono';
 import { stream } from 'hono/streaming';
 import { existsSync, statSync, createReadStream, watchFile, unwatchFile, rmSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
@@ -32,10 +39,6 @@ import { claudeStateRoot, projectSlugForCwd } from './jsonl-path.js';
 import { basename, join } from 'node:path';
 const ROLES = ['admin', 'public'];
 const CHANNELS = ['browser', 'whatsapp', 'telegram', 'webchat', 'email'];
-/** Parse the optional `aboutOwner` field from a /spawn or /resume POST body.
- *  Accepts either `{ ok:true, body:string }` or `{ ok:false, reason:string }`.
- *  Returns undefined for missing / malformed shapes so a stale UI never blocks
- *  the spawn — the composer simply omits the `<about-owner>` sentinel. */
 function parseAboutOwner(raw) {
     if (!raw || typeof raw !== 'object')
         return undefined;
@@ -48,9 +51,6 @@ function parseAboutOwner(raw) {
     }
     return undefined;
 }
-/** Parse the optional `dormantPlugins` array. Each entry must be
- *  `{ name:string, description:string }`. Malformed entries are dropped
- *  silently — the composer suppresses the sentinel if the array ends up empty. */
 function parseDormantPlugins(raw) {
     if (!Array.isArray(raw))
         return undefined;
@@ -67,40 +67,36 @@ function parseDormantPlugins(raw) {
     }
     return out.length > 0 ? out : undefined;
 }
-// Path-traversal guard. — every sessionId reaching the manager
-// (alive rows + dehydrated rows) is now the intrinsic claude session id
-// Claude Code wrote as the JSONL basename (`session_<id>` or a bare UUID,
-// per claude's writer). Reject anything with `/`, `..`, or out-of-range
-// chars before touching the filesystem.
+// Path-traversal guard. Bridge suffixes and intrinsic JSONL basenames both
+// match this character class.
 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 unifies live and
- *  dehydrated rows under the intrinsic claude session id, so the lookup
- *  is one map probe plus a filesystem fallback for ended rows. */
+/** 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) {
+    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;
+    }
     const slug = projectSlugForCwd(deps.spawnCwd);
     const path = join(claudeStateRoot(), 'projects', slug, `${sessionId}.jsonl`);
     if (existsSync(path))
         return { path, claudeSessionId: sessionId };
     return null;
 }
-/** attach the audit watcher for a public session's JSONL.
- *  the attach is gated on `onJsonlObserved`, which fires only
- *  after the observer has bound the JSONL, so jsonlPath and claudeSessionId
- *  are always set by the time this runs. Race-safe: if the PTY exited
- *  between observer fire and this call, detach immediately so the watcher
- *  does not leak. */
 function attachPublicAudit(deps, session) {
     if (session.role !== 'public')
         return;
+    if (session.claudeSessionId === null || session.jsonlPath === null)
+        return;
     const claudeSessionId = session.claudeSessionId;
     deps.publicToolAudit.attach(claudeSessionId, session.jsonlPath);
     if (session.exited) {
@@ -113,27 +109,24 @@ function attachPublicAudit(deps, session) {
 }
 export function buildHttpApp(deps) {
     const app = new Hono();
-    // display-name resolution for alive rows shares the same
-    // three-tier chain as ended rows: sidecar → ai-title → 8-char slice.
-    // The ai-title tier comes from the JSONL tail; we read it via the
-    // enumerator's cached parse so /list polls remain cheap once warm.
-    // every live row in the store carries the intrinsic
-    // `claudeSessionId` (the spawn promise blocks on observation, so a row
-    // never appears in the store without it).
     function liveDisplayName(s, sidecarName) {
         if (sidecarName && sidecarName.trim())
             return sidecarName.trim();
-        if (existsSync(s.jsonlPath)) {
+        if (s.jsonlPath && s.claudeSessionId && existsSync(s.jsonlPath)) {
             const enriched = readJsonlSession(deps.spawnCwd, s.claudeSessionId, LIST_TAIL_BYTES, deps.logger);
             if (enriched?.aiTitle?.trim())
                 return enriched.aiTitle.trim();
         }
-        return s.claudeSessionId.slice(0, 8);
+        // 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);
     }
     function toLivePayload(s) {
-        const sidecar = readSidecar(s.jsonlPath);
+        const sidecar = s.jsonlPath ? readSidecar(s.jsonlPath) : null;
+        const hasJsonl = s.jsonlPath !== null && existsSync(s.jsonlPath);
         return {
-            sessionId: s.claudeSessionId,
+            sessionId: s.bridgeSuffix,
+            claudeSessionId: s.claudeSessionId,
             pid: s.pid,
             url: s.url,
             startedAt: s.startedAt,
@@ -143,12 +136,12 @@ export function buildHttpApp(deps) {
             jsonlPath: s.jsonlPath,
             status: 'alive',
             displayName: liveDisplayName(s, sidecar?.displayName),
-            // Pane-grade fields for alive rows are filled lazily on /meta to keep
-            // /list polls cheap; /list payload carries null/0 placeholders.
             lastMessageAt: null,
             turnCount: 0,
             capped: false,
-            sizeBytes: existsSync(s.jsonlPath) ? statSync(s.jsonlPath).size : null,
+            sizeBytes: hasJsonl && s.jsonlPath ? statSync(s.jsonlPath).size : null,
+            hidden: s.hidden,
+            specialist: s.specialist,
         };
     }
     app.post('/spawn', async (c) => {
@@ -165,21 +158,20 @@ export function buildHttpApp(deps) {
         const senderId = typeof body.senderId === 'string' ? body.senderId : '';
         const role = typeof body.role === 'string' ? body.role : '';
         const channel = typeof body.channel === 'string' ? body.channel : '';
-        // log every spawn request entry so the per-spawn timeline starts
-        // with a row in server.log even when the spawn fails before any
-        // downstream emitter (composer, PTY, observer) had a chance to log.
+        const hidden = body.hidden === true;
+        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})`
             : body.dormantPlugins == null ? 'absent' : typeof body.dormantPlugins;
-        deps.logger(`spawn-request senderId=${senderId || 'missing'} role=${role || 'missing'} channel=${channel || 'missing'} permissionMode=${typeof body.permissionMode === 'string' ? body.permissionMode : 'default'} channels=${Array.isArray(body.channels) ? body.channels.length : 0} attachmentDir=${typeof body.attachmentDir === 'string' ? 'set' : 'absent'} aboutOwner=${aboutOwnerShape} dormantPlugins=${dormantPluginsShape}`);
+        deps.logger(`spawn-request senderId=${senderId || 'missing'} role=${role || 'missing'} channel=${channel || 'missing'} permissionMode=${typeof body.permissionMode === 'string' ? body.permissionMode : 'default'} channels=${Array.isArray(body.channels) ? body.channels.length : 0} attachmentDir=${typeof body.attachmentDir === 'string' ? 'set' : 'absent'} aboutOwner=${aboutOwnerShape} dormantPlugins=${dormantPluginsShape} tunnelUrl=${typeof body.tunnelUrl === 'string' ? 'set' : (body.tunnelUrl === null ? 'null' : 'absent')}`);
         if (!senderId || !ROLES.includes(role) || !CHANNELS.includes(channel)) {
             timed(deps.logger, 'POST', '/spawn', 400, Date.now() - start);
             return c.json({ error: 'invalid-arguments', detail: { senderId: !!senderId, role, channel } }, 400);
         }
-        // gate `role=public` spawns on the in-memory token buckets.
-        // Admin spawns are unthrottled. Rejection carries the bucket that tripped
-        // so the caller can distinguish channel-level abuse from cross-channel.
         if (role === 'public') {
             const decision = deps.publicSpawnLimiter.admit(senderId, channel);
             if (!decision.admitted) {
@@ -191,29 +183,27 @@ export function buildHttpApp(deps) {
                 }, 429);
             }
         }
-        // `channels` is an optional string[]; non-string entries are
-        // dropped silently. Empty / absent leaves the spawn argv unchanged.
         const channels = Array.isArray(body.channels)
             ? body.channels.filter((c) => typeof c === 'string' && c.length > 0)
             : undefined;
-        // optional permission-mode passthrough. Unknown values are
-        // dropped silently (spawn proceeds in `default` Ask-permissions mode)
-        // so a stale UI never blocks a spawn over a typo'd mode string.
         const permissionMode = typeof body.permissionMode === 'string' && PERMISSION_MODES.includes(body.permissionMode)
             ? body.permissionMode
             : undefined;
-        // optional public-chat attachment dir. Absolute path required;
-        // non-absolute or non-string values are dropped silently so a malformed
-        // bridge payload never blocks a spawn.
         const attachmentDir = typeof body.attachmentDir === 'string' && body.attachmentDir.startsWith('/')
             ? body.attachmentDir
             : undefined;
-        // Pre-resolved owner profile + dormant-plugins set, computed UI-side by
-        // the caller that holds Neo4j credentials. Missing / malformed shapes
-        // suppress the corresponding sentinel rather than blocking the spawn.
         const aboutOwner = parseAboutOwner(body.aboutOwner);
         const dormantPlugins = parseDormantPlugins(body.dormantPlugins);
-        const result = await spawnClaudeSession({ ...deps, store: deps.store, onJsonlObserved: (s) => attachPublicAudit(deps, s) }, {
+        // 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 }, {
             senderId,
             role: role,
             channel: channel,
@@ -222,46 +212,45 @@ export function buildHttpApp(deps) {
             attachmentDir,
             aboutOwner,
             dormantPlugins,
+            hidden,
+            specialist,
+            stdinPayload,
         });
         if (!result.ok) {
-            // observe-timeout is the loud-fail upper bound on the
-            // bridge-binding race; surface as 504 so the UI can distinguish it
-            // from a generic spawn failure. Everything else stays 500.
-            // stderrTail carries the captured PTY stdout (welcome banner, error
-            // text, exit prompt) so the UI can show why the spawn failed
-            // instead of an opaque `spawn-failed` label.
-            const status = result.reason === 'observe-timeout' ? 504 : 500;
-            timed(deps.logger, 'POST', '/spawn', status, Date.now() - start);
-            return c.json({ error: 'spawn-failed', reason: result.reason, stderrTail: result.stderrTail }, status);
-        }
-        // public-tool audit attaches inside the
-        // `onJsonlObserved` callback once the observer has matched Claude
-        // Code's JSONL on disk. — by the time the spawn promise
-        // resolves, that callback has fired and the audit is attached.
+            // 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.
+            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);
     });
     app.get('/list', (c) => {
         const start = Date.now();
         const senderId = c.req.query('senderId') ?? '';
+        const includeHidden = c.req.query('includeHidden') === '1';
         if (!senderId) {
             timed(deps.logger, 'GET', '/list', 400, Date.now() - start);
             return c.json({ error: 'senderId-required' }, 400);
         }
-        // live rows and dehydrated rows share the same surface id
-        // (Claude Code's intrinsic claudeSessionId), so dedup is a simple
-        // set-membership check. Live entries take precedence on a collision
-        // (the PTY is still attached; the dehydrated row would be a stale
-        // snapshot of the same JSONL).
-        const liveStored = deps.store.listBySender(senderId);
+        const liveStored = deps.store.listBySender(senderId, { includeHidden });
         const live = liveStored.map(toLivePayload);
-        const liveIds = new Set(liveStored.map((s) => s.claudeSessionId));
+        // 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 dehydrated = [];
         for (const j of listJsonlSessions(deps.spawnCwd, LIST_TAIL_BYTES, deps.logger)) {
-            if (liveIds.has(j.claudeSessionId))
+            if (liveIntrinsicIds.has(j.claudeSessionId))
                 continue;
             dehydrated.push({
                 sessionId: j.claudeSessionId,
+                claudeSessionId: j.claudeSessionId,
                 pid: null,
                 url: null,
                 startedAt: j.startedAt,
@@ -275,6 +264,8 @@ export function buildHttpApp(deps) {
                 turnCount: j.turnCount,
                 capped: j.capped,
                 sizeBytes: j.sizeBytes,
+                hidden: false,
+                specialist: null,
             });
         }
         deps.logger(`list-source live=${live.length} jsonl=${dehydrated.length}`);
@@ -301,15 +292,17 @@ export function buildHttpApp(deps) {
             timed(deps.logger, 'POST', '/resume', 400, Date.now() - start);
             return c.json({ error: 'invalid-arguments' }, 400);
         }
-        // same `channels` passthrough as /spawn so resumed sessions
-        // re-attach to the brand's channel plugins. Absent/empty preserves
-        // today's argv shape.
         const channels = Array.isArray(body.channels)
             ? body.channels.filter((c) => typeof c === 'string' && c.length > 0)
             : undefined;
         const aboutOwner = parseAboutOwner(body.aboutOwner);
         const dormantPlugins = parseDormantPlugins(body.dormantPlugins);
-        const result = await spawnClaudeSession({ ...deps, store: deps.store, onJsonlObserved: (s) => attachPublicAudit(deps, s) }, {
+        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 }, {
             senderId,
             role: role,
             channel: channel,
@@ -320,18 +313,13 @@ export function buildHttpApp(deps) {
         });
         if (!result.ok) {
             deps.logger(`resume-failed reason=${result.reason} resumeFrom=${claudeSessionId}`);
-            const status = result.reason === 'observe-timeout' ? 504 : 500;
-            timed(deps.logger, 'POST', '/resume', status, Date.now() - start);
-            return c.json({ error: 'resume-failed', reason: result.reason }, status);
+            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}`);
-        // audit watcher attaches via onJsonlObserved.
         timed(deps.logger, 'POST', '/resume', 200, Date.now() - start);
         return c.json(toLivePayload(result.session), 200);
     });
-    // sessionId metadata for the pane. Merges live store, dehydrated
-    // enumeration, and sidecar into one payload. Alive rows get a fresh tail
-    // parse with the full jsonlReadMaxBytes; ended rows likewise (cached).
     app.get('/:sessionId/meta', (c) => {
         const start = Date.now();
         const sessionId = c.req.param('sessionId');
@@ -343,15 +331,12 @@ export function buildHttpApp(deps) {
         let payload;
         if (live) {
             const base = toLivePayload(live);
-            // claudeSessionId is the row's only id; the manager-mint
-            // is gone.
-            const claudeSessionId = live.claudeSessionId;
             let lastMessageAt = null;
             let turnCount = 0;
             let capped = false;
             let sizeBytes = base.sizeBytes;
-            if (existsSync(live.jsonlPath)) {
-                const enriched = readJsonlSession(deps.spawnCwd, claudeSessionId, deps.jsonlReadMaxBytes, deps.logger);
+            if (live.claudeSessionId && live.jsonlPath && existsSync(live.jsonlPath)) {
+                const enriched = readJsonlSession(deps.spawnCwd, live.claudeSessionId, deps.jsonlReadMaxBytes, deps.logger);
                 if (enriched) {
                     lastMessageAt = enriched.lastMessageAt;
                     turnCount = enriched.turnCount;
@@ -365,7 +350,6 @@ export function buildHttpApp(deps) {
                 turnCount,
                 capped,
                 sizeBytes,
-                claudeSessionId,
             };
         }
         else {
@@ -376,6 +360,7 @@ export function buildHttpApp(deps) {
             }
             payload = {
                 sessionId: enriched.claudeSessionId,
+                claudeSessionId: enriched.claudeSessionId,
                 pid: null,
                 url: null,
                 startedAt: enriched.startedAt,
@@ -389,7 +374,8 @@ export function buildHttpApp(deps) {
                 turnCount: enriched.turnCount,
                 capped: enriched.capped,
                 sizeBytes: enriched.sizeBytes,
-                claudeSessionId: enriched.claudeSessionId,
+                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}`);
         }
@@ -397,8 +383,6 @@ export function buildHttpApp(deps) {
         timed(deps.logger, 'GET', `/${sessionId}/meta`, 200, Date.now() - start);
         return c.json(payload, 200);
     });
-    // operator-owned displayName. Writes sidecar JSON next to the
-    // JSONL. Sidecar never touches the claude-owned transcript.
     app.patch('/:sessionId', async (c) => {
         const start = Date.now();
         const sessionId = c.req.param('sessionId');
@@ -438,12 +422,6 @@ export function buildHttpApp(deps) {
         timed(deps.logger, 'PATCH', `/${sessionId}`, 200, Date.now() - start);
         return c.json({ ok: true, displayName: body.displayName }, 200);
     });
-    // archive / unarchive. Moves <id>.jsonl + sidecar between the
-    // project dir and a sibling `archive/` subdir at
-    // ${claudeStateRoot()}/projects/<slug>/archive/. Archived JSONLs no longer
-    // appear in /list because the enumerator only reads files at the top of the
-    // slug dir, not subdirs. Refuses with 409 pty-still-alive when any live PTY
-    // maps to this claudeSessionId — same guard as the purge route.
     app.post('/:sessionId/archive', async (c) => {
         const start = Date.now();
         const sessionId = c.req.param('sessionId');
@@ -464,9 +442,6 @@ export function buildHttpApp(deps) {
             timed(deps.logger, 'POST', `/${sessionId}/archive`, 400, Date.now() - start);
             return c.json({ error: 'invalid-mode', detail: { expected: ['archive', 'unarchive'] } }, 400);
         }
-        // live and dehydrated rows share the intrinsic id, so a
-        // single store probe answers "is the PTY still alive?". The compensating
-        // findLiveByClaudeId lookup is gone.
         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);
@@ -502,9 +477,6 @@ export function buildHttpApp(deps) {
         timed(deps.logger, 'POST', `/${sessionId}/archive`, 200, Date.now() - start);
         return c.json({ ok: true, mode }, 200);
     });
-    // DELETE branches on `?purge=1`. Bare DELETE is the existing
-    // "end session" path (kills the PTY, leaves the JSONL). Purge hard-removes
-    // the JSONL + sidecar + any `<sessionId>/` subdir claude wrote.
     app.delete('/:sessionId', async (c) => {
         const start = Date.now();
         const sessionId = c.req.param('sessionId');
@@ -518,8 +490,6 @@ export function buildHttpApp(deps) {
             timed(deps.logger, 'DELETE', `/${sessionId}`, 204, Date.now() - start);
             return c.body(null, 204);
         }
-        // Purge path. — live rows are keyed on the intrinsic id, so a
-        // single store probe is the alive-PTY check.
         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);
@@ -603,26 +573,27 @@ export function buildHttpApp(deps) {
             timed(deps.logger, 'GET', `/${sessionId}/log`, 404, Date.now() - start);
             return c.json({ error: 'session-not-found' }, 404);
         }
-        // every promoted live session carries a non-null jsonlPath
-        // (the spawn promise blocked on observation), so the jsonl-path-not-
-        // derived 422 branch the predecessor needed is gone.
+        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);
+            return c.json({ jsonlPath: null, exists: false, sizeBytes: 0, pending: true }, 202);
+        }
+        const jsonlPath = s.jsonlPath;
         const follow = c.req.query('follow') === '1';
         if (!follow) {
-            const exists = existsSync(s.jsonlPath);
-            const sizeBytes = exists ? statSync(s.jsonlPath).size : 0;
+            const exists = existsSync(jsonlPath);
+            const sizeBytes = exists ? statSync(jsonlPath).size : 0;
             timed(deps.logger, 'GET', `/${sessionId}/log`, 200, Date.now() - start);
-            return c.json({ jsonlPath: s.jsonlPath, exists, sizeBytes }, 200);
+            return c.json({ jsonlPath, exists, sizeBytes }, 200);
         }
-        // Streaming follow. Stream the current file content, then watch for
-        // appends and push new bytes as they arrive. On client disconnect
-        // (controller.cancel via Hono's onAbort) unwatch.
-        const path = s.jsonlPath;
         timed(deps.logger, 'GET', `/${sessionId}/log?follow=1`, 200, Date.now() - start);
         return stream(c, async (out) => {
             let position = 0;
-            if (existsSync(path)) {
-                const initialSize = statSync(path).size;
-                const head = createReadStream(path, { start: 0, end: Math.max(0, initialSize - 1) });
+            if (existsSync(jsonlPath)) {
+                const initialSize = statSync(jsonlPath).size;
+                const head = createReadStream(jsonlPath, { start: 0, end: Math.max(0, initialSize - 1) });
                 for await (const chunk of head) {
                     await out.write(chunk);
                 }
@@ -631,25 +602,24 @@ export function buildHttpApp(deps) {
             let active = true;
             out.onAbort(() => {
                 active = false;
-                unwatchFile(path);
+                unwatchFile(jsonlPath);
             });
             const listener = () => {
                 if (!active)
                     return;
-                if (!existsSync(path))
+                if (!existsSync(jsonlPath))
                     return;
-                const newSize = statSync(path).size;
+                const newSize = statSync(jsonlPath).size;
                 if (newSize <= position)
                     return;
-                const tail = createReadStream(path, { start: position, end: newSize - 1 });
+                const tail = createReadStream(jsonlPath, { start: position, end: newSize - 1 });
                 position = newSize;
                 tail.on('data', (chunk) => {
                     if (active)
                         void out.write(chunk);
                 });
             };
-            watchFile(path, { interval: 250 }, listener);
-            // Keep the stream open until the client aborts.
+            watchFile(jsonlPath, { interval: 250 }, listener);
             while (active) {
                 await new Promise((resolve) => setTimeout(resolve, 1_000));
             }