@rubytech/create-maxy-code 0.1.90 → 0.1.92

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

@@ -26,8 +26,9 @@ import { stream } from 'hono/streaming';
 import { existsSync, statSync, createReadStream, watchFile, unwatchFile, rmSync, mkdirSync, renameSync, readFileSync } from 'node:fs';
 import { spawnClaudeSession, stopSession, PERMISSION_MODES } from './pty-spawner.js';
 import { readJsonlSession } from './jsonl-enumerator.js';
-import { claudeStateRoot, projectSlugForCwd } from './jsonl-path.js';
+import { claudeStateRoot, projectSlugForCwd, jsonlPathForSessionId } from './jsonl-path.js';
 import { basename, join } from 'node:path';
+import { validateUserTitle } from './user-title-store.js';
 const ROLES = ['admin', 'public'];
 const CHANNELS = ['browser', 'whatsapp', 'telegram', 'webchat', 'email'];
 // Task 179 — resume idempotency. Two POSTs 9ms apart with the same
@@ -169,7 +170,8 @@ function attachSpecialistEndTurnAutoArchive(deps, session) {
     if (session.specialist !== AUTO_ARCHIVE_SPECIALIST)
         return;
     let archived = false;
-    function endTurnSeen(jsonlPath) {
+    const jsonlPath = jsonlPathForSessionId(deps.spawnCwd, session.sessionId);
+    function endTurnSeen() {
         try {
             const content = readFileSync(jsonlPath, 'utf8');
             return content.includes(END_TURN_SIGNATURE);
@@ -178,19 +180,18 @@ function attachSpecialistEndTurnAutoArchive(deps, session) {
             return false;
         }
     }
-    function tryArchive(jsonlPath) {
+    function tryArchive() {
         if (archived)
             return;
         if (!existsSync(jsonlPath))
             return;
-        if (!endTurnSeen(jsonlPath))
+        if (!endTurnSeen())
             return;
         archived = true;
         deps.logger(`auto-archive sessionId=${session.sessionId} specialist=${AUTO_ARCHIVE_SPECIALIST} reason=end-turn archivedAt=${new Date().toISOString()}`);
         void stopSession({ store: deps.store, killGraceMs: deps.killGraceMs, logger: deps.logger }, session.sessionId);
     }
-    if (session.jsonlPath)
-        tryArchive(session.jsonlPath);
+    tryArchive();
     const unsubscribe = deps.watcher.subscribe((event) => {
         if (archived)
             return;
@@ -198,20 +199,18 @@ function attachSpecialistEndTurnAutoArchive(deps, session) {
             return;
         if (event.source !== 'jsonl')
             return;
-        const path = event.row?.jsonlPath ?? session.jsonlPath;
-        if (!path)
-            return;
-        tryArchive(path);
+        tryArchive();
     });
     session.pty.onExit(() => unsubscribe());
 }
 function attachPublicAudit(deps, session) {
     if (session.role !== 'public')
         return;
-    if (session.jsonlPath === null)
-        return;
     const claudeSessionId = session.sessionId;
-    deps.publicToolAudit.attach(claudeSessionId, session.jsonlPath);
+    const jsonlPath = jsonlPathForSessionId(deps.spawnCwd, claudeSessionId);
+    if (!existsSync(jsonlPath))
+        return;
+    deps.publicToolAudit.attach(claudeSessionId, jsonlPath);
     if (session.exited) {
         deps.publicToolAudit.detach(claudeSessionId);
         return;
@@ -235,22 +234,29 @@ export function buildHttpApp(deps) {
             listener(sessionId);
     }
     app.__notifyUrlCapturedForTests = notifyUrlCaptured;
-    // Watcher subscriber: when JSONL CREATE fires for a live session,
-    // patch jsonlPath onto the StoredSession and attach the audit watcher.
+    // Task 253 — same fan-out shape for rename. The POST /:sessionId/rename
+    // route writes the user-title store and then calls notifyRename; each
+    // /events handler then re-emits a `row-updated` frame so every browser
+    // tab sees the new label without re-fetching /list.
+    const renameListeners = new Set();
+    function notifyRename(sessionId) {
+        for (const listener of renameListeners)
+            listener(sessionId);
+    }
+    app.__notifyRenameForTests = notifyRename;
+    // Watcher subscriber: when the JSONL CREATE event fires for a live
+    // session, attach the public-audit watcher. The path is derived
+    // (Task 258 — StoredSession no longer carries jsonlPath).
     deps.watcher.subscribe((event) => {
         if (event.source !== 'jsonl')
             return;
         if (event.kind !== 'create' && event.kind !== 'modify')
             return;
-        if (!event.row || !event.row.jsonlPath)
+        if (!event.row)
             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);
     });
     // Task 183 — dispatch jsonl modify/create events into the recorder
@@ -258,7 +264,8 @@ export function buildHttpApp(deps) {
     // database-operator spawns are registered), so operator turns pass
     // through without producing recorder-* lines. The tail's append-only
     // cursor ensures repeated modify events for the same JSONL only read
-    // newly-appended bytes.
+    // newly-appended bytes. Path is derived from sessionId + spawnCwd
+    // (Task 258).
     if (deps.jsonlTail) {
         const tail = deps.jsonlTail;
         deps.watcher.subscribe((event) => {
@@ -266,22 +273,48 @@ export function buildHttpApp(deps) {
                 return;
             if (event.kind !== 'create' && event.kind !== 'modify')
                 return;
-            const path = event.row?.jsonlPath;
-            if (!path)
+            const path = jsonlPathForSessionId(deps.spawnCwd, event.sessionId);
+            if (!existsSync(path))
                 return;
             tail.onJsonlModify(event.sessionId, path);
         });
     }
-    function liveDisplayName(s) {
-        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();
+    /** Task 253 — resolve (displayName, titleSource) for a live PTY.
+     *  Three cases:
+     *  - JSONL exists: read the enumerator's merged result (the enumerator
+     *    consults the user-title store; one resolution site for both layers).
+     *  - JSONL missing but user-title-store has an entry: pre-jsonl rename —
+     *    operator renamed a brand-new row before the first turn flushed.
+     *  - Neither: null + null. */
+    function liveTitleAndSource(s) {
+        const path = jsonlPathForSessionId(deps.spawnCwd, s.sessionId);
+        if (existsSync(path)) {
+            const enriched = readJsonlSession(deps.spawnCwd, s.sessionId, LIST_TAIL_BYTES, deps.logger, deps.userTitleStore);
+            if (enriched)
+                return { displayName: enriched.displayName, titleSource: enriched.titleSource };
         }
-        return null;
+        const userTitle = deps.userTitleStore.get(s.sessionId)?.title;
+        if (userTitle)
+            return { displayName: userTitle, titleSource: 'user' };
+        return { displayName: null, titleSource: null };
+    }
+    /** Task 258/259 — derived: a session is "archived" when its canonical
+     *  top-level jsonl is absent but the archive/ variant exists. After the
+     *  Task 258 refactor the watcher's row index doesn't surface archive/
+     *  rows; the field stays on the wire so the Sidebar/SessionMetadataPane
+     *  Unarchive affordance remains type-stable. A future task that
+     *  enumerates archive/ jsonls into the row index will populate this
+     *  honestly for archived rows. */
+    function isArchivedJsonlPath(sessionId) {
+        const canonical = jsonlPathForSessionId(deps.spawnCwd, sessionId);
+        if (existsSync(canonical))
+            return false;
+        return existsSync(jsonlPathForSessionId(deps.spawnCwd, sessionId, { archived: true }));
     }
     function toLivePayload(s) {
-        const hasJsonl = s.jsonlPath !== null && existsSync(s.jsonlPath);
+        const jsonlPath = jsonlPathForSessionId(deps.spawnCwd, s.sessionId);
+        const hasJsonl = existsSync(jsonlPath);
+        const title = liveTitleAndSource(s);
         return {
             sessionId: s.sessionId,
             pid: s.pid,
@@ -290,13 +323,15 @@ export function buildHttpApp(deps) {
             senderId: s.senderId,
             role: s.role,
             channel: s.channel,
-            jsonlPath: s.jsonlPath,
+            jsonlPath: hasJsonl ? jsonlPath : null,
             status: 'alive',
-            displayName: liveDisplayName(s),
+            archived: false,
+            displayName: title.displayName,
+            titleSource: title.titleSource,
             lastMessageAt: null,
             turnCount: 0,
             capped: false,
-            sizeBytes: hasJsonl && s.jsonlPath ? statSync(s.jsonlPath).size : null,
+            sizeBytes: hasJsonl ? statSync(jsonlPath).size : null,
             hidden: s.hidden,
             specialist: s.specialist,
             model: null,
@@ -304,16 +339,20 @@ export function buildHttpApp(deps) {
     }
     function toArchivedPayload(row, senderId) {
         let displayName = null;
+        let titleSource = null;
         let lastMessageAt = null;
         let turnCount = 0;
         let capped = false;
         let sizeBytes = null;
         let model = 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);
+        const jsonlPath = jsonlPathForSessionId(deps.spawnCwd, row.sessionId);
+        const hasJsonl = existsSync(jsonlPath);
+        if (hasJsonl) {
+            const enriched = readJsonlSession(deps.spawnCwd, row.sessionId, LIST_TAIL_BYTES, deps.logger, deps.userTitleStore);
             if (enriched) {
                 displayName = enriched.displayName;
+                titleSource = enriched.titleSource;
                 lastMessageAt = enriched.lastMessageAt;
                 turnCount = enriched.turnCount;
                 capped = enriched.capped;
@@ -322,6 +361,15 @@ export function buildHttpApp(deps) {
                 model = enriched.model;
             }
         }
+        else {
+            // JSONL gone but user override may still exist (operator renamed the row
+            // before the cascade deleted the file). Surface the user title.
+            const userTitle = deps.userTitleStore.get(row.sessionId)?.title;
+            if (userTitle) {
+                displayName = userTitle;
+                titleSource = 'user';
+            }
+        }
         return {
             sessionId: row.sessionId,
             pid: null,
@@ -330,9 +378,11 @@ export function buildHttpApp(deps) {
             senderId,
             role: null,
             channel: null,
-            jsonlPath: row.jsonlPath,
+            jsonlPath: hasJsonl ? jsonlPath : null,
             status: 'ended',
+            archived: isArchivedJsonlPath(row.sessionId),
             displayName,
+            titleSource,
             lastMessageAt,
             turnCount,
             capped,
@@ -449,7 +499,8 @@ export function buildHttpApp(deps) {
     // `row-<created|updated|archived|removed>`.
     //
     // Payload shape per event (`data: <json>`):
-    //   { sessionId, live, status, agentLabel, cwd, firstPrompt, updatedAt, url }
+    //   { sessionId, live, status, agentLabel, cwd, firstPrompt, titleSource,
+    //     updatedAt, url, archived }
     // Task 141: `sessionId` carries whichever phase is current (bridge
     // suffix preferred, JSONL basename fallback) — same single-id contract
     // as `/meta`.
@@ -474,10 +525,22 @@ export function buildHttpApp(deps) {
         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)
+            let titleSource = null;
+            const jsonlPath = jsonlPathForSessionId(deps.spawnCwd, row.sessionId);
+            if (existsSync(jsonlPath)) {
+                const enriched = readJsonlSession(deps.spawnCwd, row.sessionId, LIST_TAIL_BYTES, deps.logger, deps.userTitleStore);
+                if (enriched) {
                     firstPrompt = enriched.displayName;
+                    titleSource = enriched.titleSource;
+                }
+            }
+            else {
+                // Pre-jsonl / post-purge: only the user-title store can answer.
+                const userTitle = deps.userTitleStore.get(row.sessionId)?.title;
+                if (userTitle) {
+                    firstPrompt = userTitle;
+                    titleSource = 'user';
+                }
             }
             return {
                 sessionId: row.sessionId,
@@ -486,8 +549,12 @@ export function buildHttpApp(deps) {
                 agentLabel,
                 cwd: row.cwd,
                 firstPrompt,
+                titleSource,
                 updatedAt: row.updatedAt,
                 url: deps.store.get(row.sessionId)?.url ?? null,
+                // Task 259 — UI uses this to render Unarchive (vs Resume + Archive)
+                // on rows whose JSONL has been moved to projects/<slug>/archive/.
+                archived: isArchivedJsonlPath(row.sessionId),
             };
         }
         timed(deps.logger, 'GET', '/events', 200, Date.now() - start);
@@ -581,6 +648,24 @@ export function buildHttpApp(deps) {
                 void out.write(`event: row-updated\ndata: ${JSON.stringify(payload)}\n\n`);
             };
             urlUpdateListeners.add(urlListener);
+            // Task 253 — rename re-emit. The POST /:sessionId/rename handler
+            // mutates the user-title store and then calls notifyRename(); each
+            // /events handler re-emits the row so every browser tab sees the new
+            // label without re-fetching /list. The row lookup goes through the
+            // watcher (canonical row index); rowToPayload then re-reads the user
+            // title from `deps.userTitleStore`, picking up the freshly-set value.
+            const renameListener = (sessionId) => {
+                if (!active)
+                    return;
+                const row = deps.watcher.getBySessionId(sessionId);
+                if (!row)
+                    return;
+                const payload = rowToPayload(row);
+                subscribersCount += 1;
+                deps.logger(`[admin-events] emit event=row-updated sessionId=${sessionId} reason=rename subscribers=1`);
+                void out.write(`event: row-updated\ndata: ${JSON.stringify(payload)}\n\n`);
+            };
+            renameListeners.add(renameListener);
             // 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.
@@ -594,6 +679,7 @@ export function buildHttpApp(deps) {
                 clearInterval(keepAlive);
                 unsubscribe();
                 urlUpdateListeners.delete(urlListener);
+                renameListeners.delete(renameListener);
                 const durationMs = Date.now() - connectStart;
                 deps.logger(`[admin-events] client-disconnected ip=${clientIp} duration-ms=${durationMs} emits=${subscribersCount}`);
             });
@@ -627,7 +713,9 @@ export function buildHttpApp(deps) {
                 continue;
             if (liveSessionIds.has(row.sessionId))
                 continue;
-            if (!row.jsonlPath)
+            // Task 258 — confirm the jsonl is actually on disk; row state can lag
+            // behind a delete during boot-seed timing edges.
+            if (!existsSync(jsonlPathForSessionId(deps.spawnCwd, row.sessionId)))
                 continue;
             dehydrated.push(toArchivedPayload(row, senderId));
         }
@@ -701,6 +789,54 @@ export function buildHttpApp(deps) {
             : undefined;
         const sourceRow = resolveRow(deps.watcher, sessionId);
         const specialist = bodySpecialist ?? sourceRow?.agent ?? undefined;
+        // Task 258 — restore the archived jsonl to its canonical top-level path
+        // before claude --resume runs. Claude appends to `<projectsDir>/<sid>.jsonl`;
+        // if the file lives in `archive/`, claude doesn't find it and starts a fresh
+        // empty transcript at the top-level path, silently splitting the conversation.
+        const canonicalJsonl = jsonlPathForSessionId(deps.spawnCwd, sessionId);
+        const archivedJsonl = jsonlPathForSessionId(deps.spawnCwd, sessionId, { archived: true });
+        const canonicalExists = existsSync(canonicalJsonl);
+        const archivedExists = existsSync(archivedJsonl);
+        if (archivedExists && !canonicalExists) {
+            try {
+                renameSync(archivedJsonl, canonicalJsonl);
+                deps.logger(`resume-archive-restored sessionId=${sessionId.slice(0, 8)}`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                deps.logger(`resume-archive-restore-failed sessionId=${sessionId.slice(0, 8)} message=${msg}`);
+                timed(deps.logger, 'POST', '/resume', 500, Date.now() - start);
+                return c.json({ error: 'resume-restore-failed', detail: msg }, 500);
+            }
+        }
+        else if (archivedExists && canonicalExists) {
+            // Both files exist — pre-Task-258 bug already produced two parallel
+            // jsonls for one sessionId. Keep the larger as canonical (more history);
+            // park the smaller at `archive/<sid>.<ts>.jsonl`. No data loss.
+            try {
+                const canonicalSize = statSync(canonicalJsonl).size;
+                const archivedSize = statSync(archivedJsonl).size;
+                const keepArchived = archivedSize > canonicalSize;
+                const ts = Date.now();
+                if (keepArchived) {
+                    const stash = jsonlPathForSessionId(deps.spawnCwd, `${sessionId}.${ts}`, { archived: true });
+                    renameSync(canonicalJsonl, stash);
+                    renameSync(archivedJsonl, canonicalJsonl);
+                    deps.logger(`resume-conflict sessionId=${sessionId.slice(0, 8)} resolution=keep-archived canonical-size=${canonicalSize} archived-size=${archivedSize} stashed=${stash}`);
+                }
+                else {
+                    const stash = jsonlPathForSessionId(deps.spawnCwd, `${sessionId}.${ts}`, { archived: true });
+                    renameSync(archivedJsonl, stash);
+                    deps.logger(`resume-conflict sessionId=${sessionId.slice(0, 8)} resolution=keep-canonical canonical-size=${canonicalSize} archived-size=${archivedSize} stashed=${stash}`);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                deps.logger(`resume-conflict-resolve-failed sessionId=${sessionId.slice(0, 8)} message=${msg}`);
+                timed(deps.logger, 'POST', '/resume', 500, Date.now() - start);
+                return c.json({ error: 'resume-restore-failed', detail: msg }, 500);
+            }
+        }
         const result = await spawnClaudeSession({ ...deps, store: deps.store, watcher: deps.watcher, onSessionReady: (s) => { attachPublicAudit(deps, s); attachSpecialistEndTurnAutoArchive(deps, s); }, onUrlCaptured: notifyUrlCaptured, tunnelUrlOverride }, {
             senderId,
             userId,
@@ -729,8 +865,13 @@ export function buildHttpApp(deps) {
         if (specialist) {
             deps.logger(`resume-specialist-propagated source=${sessionId} specialist=${specialist}`);
         }
-        deps.logger(`resume pid=${result.session.pid} sessionId=${result.session.sessionId} resumeFrom=${sessionId} latency-ms=${Date.now() - start}`);
-        const payload = toLivePayload(result.session);
+        // Task 258 — the archive-restore-before-spawn flow means the operator's
+        // prior canonical sessionId IS the jsonl basename claude appends to.
+        // The pty-spawner's StoredSession.sessionId is set to that same prior
+        // canonical id (resumeClaudeSessionId), so the wire payload echoes it
+        // directly. No mint divergence to log: there's only one sessionId.
+        deps.logger(`resume pid=${result.session.pid} sessionId=${sessionId} resumeFrom=${sessionId} latency-ms=${Date.now() - start}`);
+        const payload = { ...toLivePayload(result.session), sessionId };
         if (idempotencyKey) {
             resumeDedupCache.set(`${senderId}:${idempotencyKey}`, { payload, createdAt: Date.now() });
         }
@@ -758,7 +899,8 @@ export function buildHttpApp(deps) {
             let capped = false;
             let sizeBytes = base.sizeBytes;
             let model = null;
-            if (live.jsonlPath && existsSync(live.jsonlPath)) {
+            const liveJsonlPath = jsonlPathForSessionId(deps.spawnCwd, live.sessionId);
+            if (existsSync(liveJsonlPath)) {
                 const enriched = readJsonlSession(deps.spawnCwd, live.sessionId, deps.jsonlReadMaxBytes, deps.logger);
                 if (enriched) {
                     lastMessageAt = enriched.lastMessageAt;
@@ -802,15 +944,26 @@ export function buildHttpApp(deps) {
             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 = `${row.sessionId}.jsonl`;
+        // Task 258 — refuse archive whenever any alive PTY would append to the
+        // canonical jsonl for this row. After the derived-state refactor the
+        // path is computed from sessionId + spawnCwd: every StoredSession has
+        // exactly one effective path, and the live writer is the StoredSession
+        // whose path equals the candidate.
+        const candidateJsonl = join(slugDir, fileName);
+        const aliveOnPath = deps.store.all().find((s) => {
+            if (s.exited)
+                return false;
+            return jsonlPathForSessionId(deps.spawnCwd, s.sessionId) === candidateJsonl;
+        });
+        if (aliveOnPath) {
+            deps.logger(`archive-refused sessionId=${row.sessionId.slice(0, 8)} reason=pty-alive-jsonl-write store-key=${aliveOnPath.sessionId.slice(0, 8)}`);
+            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 fromJsonl = mode === 'archive' ? join(slugDir, fileName) : join(archiveDir, fileName);
         const toJsonl = mode === 'archive' ? join(archiveDir, fileName) : join(slugDir, fileName);
         if (!existsSync(fromJsonl)) {
@@ -832,6 +985,49 @@ export function buildHttpApp(deps) {
         timed(deps.logger, 'POST', `/${id}/archive`, 200, Date.now() - start);
         return c.json({ ok: true, mode }, 200);
     });
+    // Task 253 — POST /:sessionId/rename { title }
+    //   - 200 + body on accept (carries the persisted title)
+    //   - 400 on validator reject (empty / too-long / control-chars)
+    //   - 404 when no row matches any of the four ids
+    // After accepting, the user-title store persists and notifyRename()
+    // fans a row-updated frame to every connected /events client so the
+    // sidebar refreshes without a /list re-fetch.
+    app.post('/:sessionId/rename', async (c) => {
+        const start = Date.now();
+        const id = c.req.param('sessionId');
+        if (!SESSION_ID_PATTERN.test(id) && !/^\d+$/.test(id)) {
+            timed(deps.logger, 'POST', `/${id}/rename`, 400, Date.now() - start);
+            return c.json({ error: 'invalid-session-id' }, 400);
+        }
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            timed(deps.logger, 'POST', `/${id}/rename`, 400, Date.now() - start);
+            return c.json({ error: 'invalid-json-body' }, 400);
+        }
+        const row = resolveRow(deps.watcher, id);
+        const sessionId = row?.sessionId ?? (deps.store.get(id)?.sessionId);
+        if (!sessionId) {
+            timed(deps.logger, 'POST', `/${id}/rename`, 404, Date.now() - start);
+            return c.json({ error: 'session-not-found' }, 404);
+        }
+        const result = validateUserTitle(body.title);
+        if (!result.ok) {
+            deps.logger(`rename-rejected sessionId=${sessionId.slice(0, 8)} reason=${result.reason}`);
+            timed(deps.logger, 'POST', `/${id}/rename`, 400, Date.now() - start);
+            return c.json({ error: 'invalid-title', reason: result.reason }, 400);
+        }
+        const entry = deps.userTitleStore.set(sessionId, result.title);
+        // Title content is never logged — operator names may contain customer
+        // data. Byte count is enough for forensic recovery of bulk-rename surges.
+        const titleBytes = Buffer.byteLength(entry.title, 'utf-8');
+        deps.logger(`rename sessionId=${sessionId.slice(0, 8)} title-bytes=${titleBytes} source=manager-route`);
+        notifyRename(sessionId);
+        timed(deps.logger, 'POST', `/${id}/rename`, 200, Date.now() - start);
+        return c.json({ ok: true, sessionId, titleSource: 'user', renamedAt: entry.renamedAt }, 200);
+    });
     // SIGTERM-only stop. Idempotent on already-dead PTYs. JSONL untouched.
     app.post('/:sessionId/stop', async (c) => {
         const start = Date.now();
@@ -865,21 +1061,22 @@ export function buildHttpApp(deps) {
             timed(deps.logger, 'DELETE', `/${id}`, 409, Date.now() - start);
             return c.json({ error: 'pty-still-alive', detail: 'stop the session before deleting' }, 409);
         }
-        if (!row || !row.jsonlPath) {
+        const jsonlPath = jsonlPathForSessionId(deps.spawnCwd, sessionId);
+        if (!row || !existsSync(jsonlPath)) {
             timed(deps.logger, 'DELETE', `/${id}`, 404, Date.now() - start);
             return c.json({ error: 'session-not-found' }, 404);
         }
         const subdir = join(claudeStateRoot(), 'projects', projectSlugForCwd(deps.spawnCwd), sessionId);
         let bytes = 0;
         try {
-            bytes = existsSync(row.jsonlPath) ? statSync(row.jsonlPath).size : 0;
+            bytes = existsSync(jsonlPath) ? statSync(jsonlPath).size : 0;
         }
         catch {
             // size is informational
         }
         try {
-            if (existsSync(row.jsonlPath))
-                rmSync(row.jsonlPath);
+            if (existsSync(jsonlPath))
+                rmSync(jsonlPath);
             if (existsSync(subdir))
                 rmSync(subdir, { recursive: true, force: true });
         }
@@ -889,6 +1086,11 @@ export function buildHttpApp(deps) {
             timed(deps.logger, 'DELETE', `/${id}`, 500, Date.now() - start);
             return c.json({ error: 'delete-failed', detail: msg }, 500);
         }
+        // Task 253 — drop the user-title entry for the purged session so the
+        // session-titles.json doesn't accrete orphans. Best-effort; the store
+        // logs its own failure and reads still serve from the in-memory map
+        // until next boot.
+        deps.userTitleStore.remove(sessionId);
         deps.logger(`purge sessionId=${sessionId.slice(0, 8)} bytes=${bytes}`);
         timed(deps.logger, 'DELETE', `/${id}`, 204, Date.now() - start);
         return c.body(null, 204);
@@ -954,26 +1156,19 @@ export function buildHttpApp(deps) {
         const row = resolveRow(deps.watcher, id);
         const sessionId = row?.sessionId ?? id;
         const s = deps.store.get(sessionId);
-        // Task 204 — /log reads the transcript by filesystem-indexed path, not by
-        // PTY runtime presence. The store evicts on natural exit, stop, purge, and
-        // idle, so an ended session whose JSONL still exists on disk and whose
-        // watcher row still carries `jsonlPath` must remain readable here. Mirrors
-        // the existing fallback shape at /meta, /stop, and DELETE /:sessionId.
-        // 404 only when neither the runtime store nor the watcher row can offer a
-        // path to a transcript.
-        if (!s && !row?.jsonlPath) {
+        // Task 258 — /log reads the transcript at the derived canonical path.
+        // 404 when there's no row AND no live session at this id; 202 pending
+        // when a live PTY hasn't flushed its first turn yet (no jsonl on disk).
+        if (!s && !row) {
             timed(deps.logger, 'GET', `/${id}/log`, 404, Date.now() - start);
             return c.json({ error: 'session-not-found' }, 404);
         }
-        // 202 pending fires only when a live session has not yet flushed its JSONL
-        // AND the watcher has not seen the file either. A populated watcher row
-        // proves the file landed, so the read can proceed against disk.
-        if (s && s.jsonlPath === null && !row?.jsonlPath) {
+        const jsonlPath = jsonlPathForSessionId(deps.spawnCwd, sessionId);
+        if (s && !existsSync(jsonlPath)) {
             timed(deps.logger, 'GET', `/${id}/log`, 202, Date.now() - start);
             return c.json({ jsonlPath: null, exists: false, sizeBytes: 0, pending: true }, 202);
         }
-        const jsonlPath = row?.jsonlPath ?? s?.jsonlPath;
-        if (!jsonlPath) {
+        if (!existsSync(jsonlPath)) {
             timed(deps.logger, 'GET', `/${id}/log`, 404, Date.now() - start);
             return c.json({ error: 'session-not-found' }, 404);
         }