@rubytech/create-maxy-code 0.1.91 → 0.1.93

package/payload/platform/services/claude-session-manager/dist/fs-watcher.js

@@ -1,23 +1,28 @@
-// Filesystem watcher — single source of truth for the manager's row index.
+// Filesystem watcher — disk is the source of truth (Task 258).
 //
 // Two directories are watched continuously:
 //
 //   ${CLAUDE_CONFIG_DIR}/sessions/<pid>.json   — written by Claude Code at PTY
-//     launch for entrypoint=cli. Carries sessionId, bridgeSessionId, agent,
-//     status, cwd, updatedAt directly. Created at process init, refreshed on
-//     status/agent change, deleted when the process exits cleanly.
+//     launch. Carries sessionId, bridgeSessionId, agent, status, cwd,
+//     updatedAt directly. Created at process init, refreshed on status/agent
+//     change, deleted when the process exits cleanly.
 //
 //   ${CLAUDE_CONFIG_DIR}/projects/<slug>/<sessionId>.jsonl — written on the
 //     first operator turn; persists after process exit as the audit
 //     transcript.
 //
-// The watcher unifies the two surfaces into one row indexed by the intrinsic
-// `sessionId` (the UUID Claude Code mints, identical to the JSONL basename).
-// PID-file events drive the live half of the lifecycle; JSONL events drive
-// the archived half. A row exists whenever EITHER file exists.
+// Row identity rule:
+//   - A top-level JSONL file at `<projectsDir>/<sid>.jsonl` is a row whose
+//     `sessionId` IS the basename. Always.
+//   - A PID file at `<sessionsDir>/<pid>.json` decorates a row: the row
+//     becomes 'live' when the PID file's `sessionId` field matches a
+//     top-level JSONL basename, OR when the PID file's `sessionId` field
+//     has no matching JSONL yet (fresh /spawn pre-first-turn).
+//   - The fs-watcher carries no path-anchored maps and no merge state
+//     machine. After Task 258, paths are derived; the watcher reads disk.
 //
 // Boot sequence is sync-then-arm: bootSeed() reads both directories
-// synchronously and rebuilds the in-memory index before arm() turns on the
+// synchronously and rebuilds the in-memory cache before arm() turns on the
 // fs.watch handlers. Without this ordering, watch events fire before the
 // seed completes and either land before any subscriber attaches (silent
 // drop) or race with seed inserts (double-emit). The deterministic order
@@ -28,18 +33,10 @@
 // emits when the PID file is rewritten (write-temp-rename is two events
 // from fs.watch's perspective on macOS, more on Linux), and folds the
 // CREATE→MODIFY pair an editor-style writer can emit.
-//
-// Identifiers carried on every row:
-//   - sessionId           (canonical, never null)
-//   - bridgeSessionId     ("session_<suffix>" form, null for entrypoint=cli
-//                          rows that have not yet written URL-bound state)
-//   - bridgeSuffix        ("<suffix>" — derived; bridgeSessionId minus the
-//                          "session_" prefix)
-//   - pid                 (null on archived JSONL-only rows)
-// The store/HTTP layer resolves an inbound id against all four keys so a
-// caller holding any one of them resolves to the same row.
 import { existsSync, mkdirSync, openSync, closeSync, readSync, readFileSync, readdirSync, statSync, watch } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { readSidecar } from './session-sidecar.js';
+import { defaultSystemctlRunner, getScopeMainPid, listSurvivingScopes, stopScopeUnit, } from './systemd-scope.js';
 const DEBOUNCE_MS = 200;
 // First `agent-setting` record sits near the JSONL head (Claude Code writes
 // it after env+meta, before the first user turn). 32 KiB is enough to cover
@@ -119,49 +116,28 @@ function parsePidFile(path) {
         : typeof parsed.startedAt === 'number'
             ? parsed.startedAt
             : 0;
-    return {
-        sessionId,
-        bridgeSessionId,
-        bridgeSuffix,
-        agent,
-        cachedAgentSetting: null,
-        cwd,
-        pid,
-        jsonlPath: null,
-        pidFilePath: path,
-        state: 'live',
-        status,
-        updatedAt,
-    };
+    return { sessionId, pid, bridgeSessionId, bridgeSuffix, agent, cwd, status, updatedAt, pidFilePath: path };
 }
 export function createFsWatcher(opts) {
     const { sessionsDir, projectsDir, logger } = opts;
-    // Canonical store keyed on sessionId. Secondary maps re-derived from the
-    // canonical row so a removeRow drops every key in one shot.
+    const runSystemctl = opts.runSystemctl ?? defaultSystemctlRunner;
+    // Transient row cache, keyed on sessionId. Built by bootSeed and kept
+    // in sync by fs event reconciliation. Not the source of truth — disk is.
     const rowsBySessionId = new Map();
+    // Reverse indexes derived from row content. Rebuilt on indexRow/unindexRow.
     const sessionIdByPid = new Map();
     const sessionIdByBridgeSuffix = new Map();
-    const sessionIdByPidFilePath = new Map();
-    // Task 190 — jsonl-path-anchored prior-row lookup. Closes the symmetric
-    // gap to Task 186's pid-file swap: when `claude --resume` rewrites the
-    // pid file, the fork sid stays canonical, but Claude continues writing
-    // turns to `<source>.jsonl`. The admin server archives the source jsonl
-    // during resume, so the first post-resume turn re-creates the file at
-    // the projects-dir path. Without this map, that create event lands as
-    // a stray archived row. The pid-file swap branch pre-seeds this map
-    // with `jsonlPathFor(parsed.sessionId) → priorSessionIdAtPath` so the
-    // jsonl event redirects onto the fork row.
-    const sessionIdByJsonlPath = new Map();
     const subscribers = new Set();
     const pidWaiters = new Map();
     const debounceTimers = new Map();
     let pidWatcher = null;
     let jsonlWatcher = null;
+    let archiveWatcher = null;
     let armed = false;
     let seeded = false;
     function emit(event) {
         logger(`[fs-watcher] event=${event.kind} kind=${event.source} sessionId=${event.sessionId} agent=${event.row?.agent ?? 'none'} ` +
-            `status=${event.row?.status ?? 'gone'} path=${event.row?.[event.source === 'pid' ? 'pidFilePath' : 'jsonlPath'] ?? 'none'}`);
+            `status=${event.row?.status ?? 'gone'} path=${event.row?.pidFilePath ?? 'derived'}`);
         for (const sub of subscribers) {
             try {
                 sub(event);
@@ -186,10 +162,6 @@ export function createFsWatcher(opts) {
             sessionIdByPid.set(row.pid, row.sessionId);
         if (row.bridgeSuffix)
             sessionIdByBridgeSuffix.set(row.bridgeSuffix, row.sessionId);
-        if (row.pidFilePath)
-            sessionIdByPidFilePath.set(row.pidFilePath, row.sessionId);
-        if (row.jsonlPath)
-            sessionIdByJsonlPath.set(row.jsonlPath, row.sessionId);
     }
     function unindexRow(row) {
         rowsBySessionId.delete(row.sessionId);
@@ -197,47 +169,188 @@ export function createFsWatcher(opts) {
             sessionIdByPid.delete(row.pid);
         if (row.bridgeSuffix)
             sessionIdByBridgeSuffix.delete(row.bridgeSuffix);
-        if (row.pidFilePath)
-            sessionIdByPidFilePath.delete(row.pidFilePath);
-        if (row.jsonlPath)
-            sessionIdByJsonlPath.delete(row.jsonlPath);
     }
+    const archiveDir = join(projectsDir, 'archive');
     function jsonlPathFor(sessionId) {
         return join(projectsDir, `${sessionId}.jsonl`);
     }
+    function archiveJsonlPathFor(sessionId) {
+        return join(archiveDir, `${sessionId}.jsonl`);
+    }
+    function sidecarPathForLocation(sessionId, location) {
+        return location === 'archive'
+            ? join(archiveDir, `${sessionId}.meta.json`)
+            : join(projectsDir, `${sessionId}.meta.json`);
+    }
+    /** Read the sidecar that should live next to `<sessionId>.jsonl` for
+     *  the given location. Missing or malformed sidecars yield a record
+     *  with seven null fields and `hidden: false` — the row is still
+     *  indexed; the operator-facing /list filter hides it unless
+     *  `includeHidden=1`. The watcher logs every read via `readSidecar`'s
+     *  own log lines. */
+    function readSidecarForLocation(sessionId, location) {
+        const path = sidecarPathForLocation(sessionId, location);
+        const result = readSidecar(path, logger);
+        return { sidecar: result.sidecar, present: result.outcome === 'ok' };
+    }
+    function applySidecarToRow(row, sidecar) {
+        if (!sidecar) {
+            return {
+                ...row,
+                senderId: null,
+                role: null,
+                channel: null,
+                url: null,
+                startedAt: null,
+                permissionMode: null,
+                hidden: false,
+                sidecarSpecialist: null,
+            };
+        }
+        return {
+            ...row,
+            senderId: sidecar.senderId,
+            role: sidecar.role,
+            channel: sidecar.channel,
+            url: sidecar.url,
+            startedAt: sidecar.startedAt,
+            permissionMode: sidecar.permissionMode,
+            hidden: sidecar.hidden,
+            sidecarSpecialist: sidecar.specialist,
+        };
+    }
+    /** Find the pid file (if any) whose content names `sessionId`. Used at
+     *  bootSeed to correlate jsonls with their live pid files, and on jsonl
+     *  events to detect a freshly-created jsonl whose sessionId matches a
+     *  pre-first-turn live row. */
+    function findPidFileForSessionId(sessionId) {
+        try {
+            for (const entry of readdirSync(sessionsDir, { withFileTypes: true })) {
+                if (!entry.isFile() || !entry.name.endsWith('.json'))
+                    continue;
+                const parsed = parsePidFile(join(sessionsDir, entry.name));
+                if (parsed && parsed.sessionId === sessionId)
+                    return parsed;
+            }
+        }
+        catch {
+            // sessionsDir absent — fine.
+        }
+        return null;
+    }
+    function buildLiveRow(pidContent) {
+        const base = {
+            sessionId: pidContent.sessionId,
+            bridgeSessionId: pidContent.bridgeSessionId,
+            bridgeSuffix: pidContent.bridgeSuffix,
+            agent: pidContent.agent,
+            cachedAgentSetting: null,
+            cwd: pidContent.cwd,
+            pid: pidContent.pid,
+            pidFilePath: pidContent.pidFilePath,
+            state: 'live',
+            status: pidContent.status,
+            updatedAt: pidContent.updatedAt,
+            scopeUnitToken: null,
+            senderId: null,
+            role: null,
+            channel: null,
+            url: null,
+            startedAt: null,
+            permissionMode: null,
+            hidden: false,
+            sidecarSpecialist: null,
+        };
+        // Live rows always read the sidecar from the top-level projects dir
+        // (the JSONL hasn't been archived yet). A pre-first-turn live spawn
+        // without a sidecar should never happen post-Task-260 because the
+        // pty-spawner writes the sidecar BEFORE the PID-file event resolves
+        // — but if it does, the row indexes with null spawn fields and the
+        // /list filter hides it unless includeHidden=1.
+        const { sidecar } = readSidecarForLocation(pidContent.sessionId, 'top');
+        return applySidecarToRow(base, sidecar);
+    }
+    function buildArchivedRow(sessionId, jsonlPath) {
+        // Locate the sidecar that belongs next to this JSONL. The path the
+        // caller passed names the JSONL's directory; the sidecar shares
+        // that directory by construction.
+        const location = dirname(jsonlPath) === archiveDir ? 'archive' : 'top';
+        const base = {
+            sessionId,
+            bridgeSessionId: null,
+            bridgeSuffix: null,
+            agent: null,
+            cachedAgentSetting: readAgentSettingFromJsonl(jsonlPath),
+            cwd: null,
+            pid: null,
+            pidFilePath: null,
+            state: location === 'archive' ? 'archived' : 'archived',
+            status: 'gone',
+            updatedAt: (() => {
+                try {
+                    return statSync(jsonlPath).mtimeMs;
+                }
+                catch {
+                    return 0;
+                }
+            })(),
+            scopeUnitToken: null,
+            senderId: null,
+            role: null,
+            channel: null,
+            url: null,
+            startedAt: null,
+            permissionMode: null,
+            hidden: false,
+            sidecarSpecialist: null,
+        };
+        const { sidecar } = readSidecarForLocation(sessionId, location);
+        return applySidecarToRow(base, sidecar);
+    }
     /** Apply the current on-disk state for one PID-file path to the index.
-     *  Reads the file if present, merges with any existing row (by sessionId),
-     *  or removes the row when the file is gone. Emits create/modify/delete. */
+     *  Reads the file if present; on delete, finds the row via pid (from the
+     *  filename) since we no longer carry a path-keyed index. */
     function reconcilePidFile(path) {
         const onDisk = existsSync(path);
-        const priorSessionId = sessionIdByPidFilePath.get(path);
         if (!onDisk) {
+            // pid is encoded in the filename. Look up by pid → sessionId.
+            const fileName = path.slice(path.lastIndexOf('/') + 1);
+            const pidStr = fileName.replace(/\.json$/, '');
+            const pid = /^\d+$/.test(pidStr) ? Number(pidStr) : null;
+            if (pid === null)
+                return;
+            const priorSessionId = sessionIdByPid.get(pid);
             if (!priorSessionId)
                 return;
             const prior = rowsBySessionId.get(priorSessionId);
-            if (!prior) {
-                sessionIdByPidFilePath.delete(path);
+            if (!prior)
                 return;
-            }
-            // PID file gone. If JSONL still exists, demote row to archived;
-            // else drop it entirely.
-            const jsonlPath = prior.jsonlPath ?? jsonlPathFor(prior.sessionId);
-            if (existsSync(jsonlPath)) {
+            // Task 260 — the JSONL may have already moved to archive/ if the
+            // operator pressed Archive concurrently with the PTY exit. Check
+            // both locations; the demotion row stays a single entry, with the
+            // sidecar re-read from whichever directory currently holds it.
+            const topJsonl = jsonlPathFor(prior.sessionId);
+            const archivedJsonl = archiveJsonlPathFor(prior.sessionId);
+            const hasTop = existsSync(topJsonl);
+            const hasArchived = existsSync(archivedJsonl);
+            if (hasTop || hasArchived) {
                 // Cache agent identity from JSONL head before the PID file is
-                // forgotten. `agent` on a live row comes from the PID file
-                // (`--agent <name>`); after demote it's null, so without this
-                // cache the UI would lose the specialist label.
+                // forgotten. `agent` on a live row comes from the PID file; after
+                // demote it's null, so without this cache the UI would lose the
+                // specialist label.
+                const presentJsonl = hasTop ? topJsonl : archivedJsonl;
+                const sidecarLocation = hasTop ? 'top' : 'archive';
                 const cachedAgentSetting = prior.cachedAgentSetting
-                    ?? readAgentSettingFromJsonl(jsonlPath);
-                const updated = {
+                    ?? readAgentSettingFromJsonl(presentJsonl);
+                const { sidecar } = readSidecarForLocation(prior.sessionId, sidecarLocation);
+                const updated = applySidecarToRow({
                     ...prior,
                     pid: null,
                     pidFilePath: null,
                     state: 'archived',
                     status: 'gone',
                     cachedAgentSetting,
-                    jsonlPath,
-                };
+                }, sidecar);
                 unindexRow(prior);
                 indexRow(updated);
                 emit({ kind: 'delete', source: 'pid', row: updated, sessionId: updated.sessionId });
@@ -251,138 +364,124 @@ export function createFsWatcher(opts) {
         const parsed = parsePidFile(path);
         if (!parsed)
             return;
-        const jsonlPath = jsonlPathFor(parsed.sessionId);
-        if (existsSync(jsonlPath))
-            parsed.jsonlPath = jsonlPath;
-        // Task 186 — `claude --resume` rewrites the pid file's sessionId field
-        // to the resumed source id at the same path. Hold the prior sessionId
-        // as canonical: it matches `SessionStore.add(...)` from `/spawn` (and
-        // the `/resume` response payload echoed to the client URL). Merge the
-        // rewritten content's mutable fields (agent, status, updatedAt) into
-        // the prior row; do NOT index a second row.
-        const priorSessionIdAtPath = sessionIdByPidFilePath.get(path);
-        if (priorSessionIdAtPath && priorSessionIdAtPath !== parsed.sessionId) {
-            const priorAtPath = rowsBySessionId.get(priorSessionIdAtPath);
-            if (priorAtPath) {
-                logger(`[fs-watcher] pid-file-sessionId-changed path=${path} prior=${priorSessionIdAtPath} next=${parsed.sessionId}`);
-                // Task 190 — pre-register the resumed source jsonl path against
-                // the prior canonical sid so the eventual jsonl create event
-                // (Claude writes turns to `<parsed.sessionId>.jsonl`) routes back
-                // to this row instead of indexing a stray archived row.
-                sessionIdByJsonlPath.set(jsonlPathFor(parsed.sessionId), priorSessionIdAtPath);
-                const merged = {
-                    ...priorAtPath,
-                    agent: parsed.agent,
-                    status: parsed.status,
-                    updatedAt: parsed.updatedAt,
-                };
-                rowsBySessionId.set(priorSessionIdAtPath, merged);
-                emit({ kind: 'modify', source: 'pid', row: merged, sessionId: priorSessionIdAtPath });
-                return;
+        // If this pid was already mapped to a different sessionId (claude
+        // rewrote the file's sessionId mid-life, e.g. Task 186 resume
+        // convergence), drop the stale row first. The new content is the
+        // authoritative state.
+        const stalePriorByPid = sessionIdByPid.get(parsed.pid);
+        if (stalePriorByPid && stalePriorByPid !== parsed.sessionId) {
+            const stale = rowsBySessionId.get(stalePriorByPid);
+            if (stale) {
+                unindexRow(stale);
+                emit({ kind: 'delete', source: 'pid', row: null, sessionId: stalePriorByPid });
             }
-            // Prior row was unindexed (e.g. by the reaper) between events. Drop
-            // the stale path mapping and fall through to the standard new-row
-            // path so the rewritten content lands as a fresh row rather than
-            // permanently leaking the swap log line.
-            logger(`[fs-watcher] pid-file-sessionId-changed path=${path} prior=${priorSessionIdAtPath} next=${parsed.sessionId} prior-row=gone`);
-            sessionIdByPidFilePath.delete(path);
         }
         const prior = rowsBySessionId.get(parsed.sessionId);
-        if (!prior) {
-            indexRow(parsed);
-            emit({ kind: 'create', source: 'pid', row: parsed, sessionId: parsed.sessionId });
+        const merged = buildLiveRow(parsed);
+        if (prior) {
+            // Preserve cachedAgentSetting from the prior row (read once at
+            // archive transition or boot-seed; pid file rewrites don't carry it).
+            merged.cachedAgentSetting = prior.cachedAgentSetting ?? merged.cachedAgentSetting;
+            unindexRow(prior);
+            indexRow(merged);
+            emit({ kind: 'modify', source: 'pid', row: merged, sessionId: merged.sessionId });
             return;
         }
-        // Merge: keep jsonlPath from prior if file existed; otherwise from
-        // parsed (which already checked disk above).
-        const merged = {
-            ...prior,
-            ...parsed,
-            jsonlPath: parsed.jsonlPath ?? prior.jsonlPath,
-        };
-        unindexRow(prior);
         indexRow(merged);
-        emit({ kind: 'modify', source: 'pid', row: merged, sessionId: merged.sessionId });
+        emit({ kind: 'create', source: 'pid', row: merged, sessionId: merged.sessionId });
     }
+    // Task 260 — reconciliation is now path-aware: the same sessionId can
+    // surface at `<projectsDir>/<sid>.jsonl` (live or ended-but-not-archived)
+    // or at `<projectsDir>/archive/<sid>.jsonl` (archived). Row identity is
+    // the sessionId; the row's `state` reflects which directory holds the
+    // JSONL right now.
+    //
+    // The load-bearing event in this path is the top↔archive RENAME, which
+    // fs.watch emits as a (delete on source, create on destination) pair in
+    // either order. Coalescing that pair into ONE `row-updated` event keyed
+    // on sessionId is the contract Task 260 promises the UI: an archive
+    // never produces a `row-removed` followed by a `row-created` — it
+    // produces a single `row-updated` with the new state flag.
+    //
+    // Implementation: on a delete event for one location, check whether the
+    // sibling location still holds the JSONL for the same sessionId. If
+    // yes, mutate the row's state (and re-read its sidecar from the new
+    // location) and emit a single `modify`. If no, the JSONL really left
+    // disk — unindex and emit delete. On a create event, if the row
+    // already exists with the matching state, no-op (we already emitted
+    // the modify above); otherwise treat as a fresh row.
     function reconcileJsonlFile(path) {
-        const onDisk = existsSync(path);
         const fileName = path.slice(path.lastIndexOf('/') + 1);
         if (!fileName.endsWith('.jsonl'))
             return;
         const sessionId = fileName.slice(0, -'.jsonl'.length);
+        const location = dirname(path) === archiveDir ? 'archive' : 'top';
+        const onDisk = existsSync(path);
         const prior = rowsBySessionId.get(sessionId);
+        const siblingPath = location === 'top' ? archiveJsonlPathFor(sessionId) : jsonlPathFor(sessionId);
+        const siblingOnDisk = existsSync(siblingPath);
         if (!onDisk) {
+            // Event is a delete for THIS location.
             if (!prior)
                 return;
-            // JSONL gone. If PID file still present, row stays live but loses
-            // transcript; else drop row entirely.
+            if (siblingOnDisk) {
+                // top↔archive rename — coalesce into ONE modify with the new
+                // state. The new location reflects where the JSONL lives now.
+                const newLocation = location === 'top' ? 'archive' : 'top';
+                const newState = newLocation === 'top' ? 'live' : 'archived';
+                const { sidecar } = readSidecarForLocation(sessionId, newLocation);
+                const updated = applySidecarToRow({ ...prior, state: newState }, sidecar);
+                unindexRow(prior);
+                indexRow(updated);
+                emit({ kind: 'modify', source: 'jsonl', row: updated, sessionId });
+                logger(`[fs-watcher] archive-rename sessionId=${sessionId.slice(0, 8)} direction=${location}->${newLocation}`);
+                return;
+            }
+            // True delete. If PID file still present at the prior location,
+            // row stays live (transient — live PTY may write a new jsonl on
+            // the next turn); else drop the row entirely.
             if (prior.pidFilePath && existsSync(prior.pidFilePath)) {
-                const updated = { ...prior, jsonlPath: null };
-                rowsBySessionId.set(updated.sessionId, updated);
-                emit({ kind: 'delete', source: 'jsonl', row: updated, sessionId });
+                emit({ kind: 'delete', source: 'jsonl', row: prior, sessionId });
                 return;
             }
             unindexRow(prior);
             emit({ kind: 'delete', source: 'jsonl', row: null, sessionId });
             return;
         }
+        // Event is a create or modify on THIS location.
+        const desiredState = location === 'top' ? 'live' : 'archived';
         if (prior) {
-            if (prior.jsonlPath === path) {
-                emit({ kind: 'modify', source: 'jsonl', row: prior, sessionId });
-                return;
-            }
-            const updated = { ...prior, jsonlPath: path };
+            // Row already exists. If the state matches (or the row is live
+            // because a PID file is present), this is a content modify or
+            // the second event of a rename whose first half already mutated
+            // the row to the new state — both cases emit a single modify and
+            // refresh the sidecar.
+            const { sidecar } = readSidecarForLocation(sessionId, location);
+            const nextState = prior.pidFilePath && existsSync(prior.pidFilePath) && location === 'top'
+                ? 'live'
+                : desiredState;
+            const updated = applySidecarToRow({ ...prior, state: nextState }, sidecar);
+            // Only unindex+reindex when something changed; otherwise we just
+            // re-emit modify so subscribers re-render.
             unindexRow(prior);
             indexRow(updated);
             emit({ kind: 'modify', source: 'jsonl', row: updated, sessionId });
             return;
         }
-        // Task 190 — before falling into the archived-row fallback, consult
-        // the jsonl-path map. A prior canonical sid may have pre-registered
-        // this path via the Task 186 pid-file swap branch (the resume case)
-        // or a row indexed earlier may name this path. Either way: redirect
-        // the event onto the prior canonical sid rather than indexing a
-        // second row at the basename-derived sid.
-        const priorCanonicalSid = sessionIdByJsonlPath.get(path);
-        if (priorCanonicalSid && priorCanonicalSid !== sessionId) {
-            const priorCanonical = rowsBySessionId.get(priorCanonicalSid);
-            if (priorCanonical) {
-                logger(`[fs-watcher] jsonl-path-sessionId-changed path=${path} prior=${priorCanonicalSid} next=${sessionId}`);
-                const updated = { ...priorCanonical, jsonlPath: path };
-                unindexRow(priorCanonical);
-                indexRow(updated);
-                emit({ kind: 'modify', source: 'jsonl', row: updated, sessionId: updated.sessionId });
-                return;
-            }
-            // Prior canonical row vanished between the swap pre-seed and the
-            // jsonl event (e.g. pid file deleted, reaper). Drop the stale map
-            // entry and fall through to the standard archived-row path so the
-            // file lands as an ordinary archived row at the basename sid.
-            logger(`[fs-watcher] jsonl-path-sessionId-changed path=${path} prior=${priorCanonicalSid} next=${sessionId} prior-row=gone`);
-            sessionIdByJsonlPath.delete(path);
-        }
-        // JSONL appeared without a corresponding PID file → archived row.
-        const row = {
-            sessionId,
-            bridgeSessionId: null,
-            bridgeSuffix: null,
-            agent: null,
-            cachedAgentSetting: readAgentSettingFromJsonl(path),
-            cwd: null,
-            pid: null,
-            jsonlPath: path,
-            pidFilePath: null,
-            state: 'archived',
-            status: 'gone',
-            updatedAt: (() => {
-                try {
-                    return statSync(path).mtimeMs;
-                }
-                catch {
-                    return 0;
-                }
-            })(),
-        };
+        // Fresh jsonl at this sessionId. If a pid file already exists with
+        // this sessionId (rare but possible — claude wrote its first turn
+        // before the pid-file create event was observed), build a live row.
+        // Otherwise the row reflects the location: top → live (manager
+        // probably just spawned but the PID file hasn't been observed yet,
+        // or a manually-restored archive) / archive → archived.
+        const matchingPid = findPidFileForSessionId(sessionId);
+        if (matchingPid && location === 'top') {
+            const row = buildLiveRow(matchingPid);
+            indexRow(row);
+            emit({ kind: 'create', source: 'jsonl', row, sessionId });
+            return;
+        }
+        const row = buildArchivedRow(sessionId, path);
         indexRow(row);
         emit({ kind: 'create', source: 'jsonl', row, sessionId });
     }
@@ -404,71 +503,165 @@ export function createFsWatcher(opts) {
     function bootSeed() {
         if (seeded)
             return;
+        // Task 260 — walk the projects dir AND its archive subdir so archived
+        // rows are first-class members of the row index. Then walk the
+        // sessions dir; each pid file's sessionId either matches an
+        // already-seeded jsonl row (promote to live) or has no jsonl yet (a
+        // pre-first-turn live row, no transcript).
+        let topJsonlCount = 0;
+        let archiveJsonlCount = 0;
+        let sidecarCount = 0;
         let pidCount = 0;
-        let jsonlCount = 0;
         try {
-            for (const entry of readdirSync(sessionsDir, { withFileTypes: true })) {
-                if (!entry.isFile() || !entry.name.endsWith('.json'))
+            for (const entry of readdirSync(projectsDir, { withFileTypes: true })) {
+                if (!entry.isFile() || !entry.name.endsWith('.jsonl'))
                     continue;
-                const path = join(sessionsDir, entry.name);
-                const row = parsePidFile(path);
-                if (!row)
+                const sessionId = entry.name.slice(0, -'.jsonl'.length);
+                if (!sessionId)
                     continue;
-                const jsonlPath = jsonlPathFor(row.sessionId);
-                if (existsSync(jsonlPath))
-                    row.jsonlPath = jsonlPath;
-                indexRow(row);
-                pidCount += 1;
+                const jsonlPath = join(projectsDir, entry.name);
+                if (!rowsBySessionId.has(sessionId)) {
+                    indexRow(buildArchivedRow(sessionId, jsonlPath));
+                }
+                topJsonlCount += 1;
             }
         }
         catch {
-            // sessionsDir absent — fine. Watcher creates it via mkdir at arm time.
+            // projectsDir absent on first boot — Claude Code creates it on first
+            // transcript write. Watcher's mkdirSync at arm() avoids fs.watch ENOENT.
         }
         try {
-            for (const entry of readdirSync(projectsDir, { withFileTypes: true })) {
+            for (const entry of readdirSync(archiveDir, { withFileTypes: true })) {
                 if (!entry.isFile() || !entry.name.endsWith('.jsonl'))
                     continue;
                 const sessionId = entry.name.slice(0, -'.jsonl'.length);
-                const path = join(projectsDir, entry.name);
-                const prior = rowsBySessionId.get(sessionId);
-                if (prior) {
-                    if (prior.jsonlPath !== path) {
-                        rowsBySessionId.set(sessionId, { ...prior, jsonlPath: path });
-                    }
+                if (!sessionId)
+                    continue;
+                const jsonlPath = join(archiveDir, entry.name);
+                if (!rowsBySessionId.has(sessionId)) {
+                    indexRow(buildArchivedRow(sessionId, jsonlPath));
                 }
-                else {
-                    const row = {
-                        sessionId,
-                        bridgeSessionId: null,
-                        bridgeSuffix: null,
-                        agent: null,
-                        cachedAgentSetting: readAgentSettingFromJsonl(path),
-                        cwd: null,
-                        pid: null,
-                        jsonlPath: path,
-                        pidFilePath: null,
-                        state: 'archived',
-                        status: 'gone',
-                        updatedAt: (() => {
-                            try {
-                                return statSync(path).mtimeMs;
-                            }
-                            catch {
-                                return 0;
-                            }
-                        })(),
-                    };
-                    indexRow(row);
+                archiveJsonlCount += 1;
+            }
+        }
+        catch {
+            // archive subdir absent — fine. Watcher mkdirs it at arm time.
+        }
+        try {
+            for (const entry of readdirSync(sessionsDir, { withFileTypes: true })) {
+                if (!entry.isFile() || !entry.name.endsWith('.json'))
+                    continue;
+                const path = join(sessionsDir, entry.name);
+                const parsed = parsePidFile(path);
+                if (!parsed)
+                    continue;
+                const prior = rowsBySessionId.get(parsed.sessionId);
+                const row = buildLiveRow(parsed);
+                if (prior) {
+                    // Preserve cached agent setting we already read from the jsonl head.
+                    row.cachedAgentSetting = prior.cachedAgentSetting ?? row.cachedAgentSetting;
+                    unindexRow(prior);
                 }
-                jsonlCount += 1;
+                indexRow(row);
+                pidCount += 1;
             }
         }
         catch {
-            // projectsDir absent on first boot — Claude Code creates it on first
-            // transcript write. Watcher's mkdirSync at arm() avoids fs.watch ENOENT.
+            // sessionsDir absent — fine. Watcher creates it via mkdir at arm time.
+        }
+        // Count rows whose sidecar populated `senderId` — the load-bearing
+        // signal that a row is fully addressable in /list. `sidecarCount <
+        // topJsonlCount + archiveJsonlCount` flags pre-Task-260 JSONLs that
+        // landed before the sidecar writer existed: they index normally but
+        // /list filters them out unless includeHidden=1.
+        for (const row of rowsBySessionId.values()) {
+            if (row.senderId !== null)
+                sidecarCount += 1;
         }
         seeded = true;
-        logger(`[fs-watcher] boot-seed sessions-dir=${pidCount} projects-dir=${jsonlCount} rows=${rowsBySessionId.size}`);
+        const totalJsonl = topJsonlCount + archiveJsonlCount;
+        logger(`[fs-watcher] boot-seed sessions-dir=${pidCount} projects-dir-top=${topJsonlCount} projects-dir-archive=${archiveJsonlCount} sidecars=${sidecarCount} rows=${rowsBySessionId.size} jsonl-total=${totalJsonl}`);
+        // Task 250 — second pass: reconcile surviving `claude-session-*.scope`
+        // units with the rows just built. A surviving scope without a row is
+        // an orphan; a surviving scope with a row reattaches as `detached`.
+        reconcileSurvivingScopes();
+    }
+    /** Task 250 — boot-seed extension. Lists `claude-session-*.scope` units
+     *  owned by the user manager; for each, queries MainPID and looks up the
+     *  matching PID file in sessionsDir. The PID file's `sessionId` field is
+     *  the row key. Outcomes per scope:
+     *
+     *    - reattached: surviving scope whose MainPID points to a parsed PID
+     *      file whose sessionId is in `rowsBySessionId`. The row's
+     *      `scopeUnitToken` is set and `status` flipped to `detached`. The
+     *      manager has lost the PTY master fd; the row is observation-only
+     *      until the operator clicks End (handled separately via the row's
+     *      unit token).
+     *    - orphaned: surviving scope whose MainPID either (a) doesn't
+     *      resolve, (b) has no PID file, or (c) the PID file's sessionId is
+     *      unknown. The manager cannot reconstruct what claude is doing; per
+     *      the eng-review decision, it issues `systemctl --user stop` on the
+     *      orphan rather than leaving the cgroup alive.
+     *
+     *  Emits `[boot-seed] survived-scopes=N reattached=N orphaned=N
+     *  orphaned-stopped=N` even when every count is zero so the operator
+     *  can confirm the reconciliation ran. */
+    function reconcileSurvivingScopes() {
+        const { scopes, result } = listSurvivingScopes(runSystemctl);
+        if (result.exitCode !== 0) {
+            logger(`[boot-seed] systemctl-list-units-failed exit-code=${result.exitCode} stderr=${JSON.stringify(result.stderr.slice(-200))} survived-scopes=0 reattached=0 orphaned=0 orphaned-stopped=0`);
+            return;
+        }
+        let reattached = 0;
+        let orphaned = 0;
+        let orphanedStopped = 0;
+        for (const scope of scopes) {
+            const decision = reattachOrOrphan(scope);
+            if (decision === 'reattached') {
+                reattached += 1;
+            }
+            else {
+                orphaned += 1;
+                try {
+                    const stop = stopScopeUnit(runSystemctl, scope.unitToken);
+                    if (stop.outcome === 'ok' || stop.outcome === 'already-gone') {
+                        orphanedStopped += 1;
+                    }
+                    logger(`[boot-seed] orphan-stop unit=${scope.unitName} outcome=${stop.outcome} exit-code=${stop.exitCode}`);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    logger(`[boot-seed] orphan-stop-threw unit=${scope.unitName} err=${JSON.stringify(msg)}`);
+                }
+            }
+        }
+        logger(`[boot-seed] survived-scopes=${scopes.length} reattached=${reattached} orphaned=${orphaned} orphaned-stopped=${orphanedStopped}`);
+    }
+    function reattachOrOrphan(scope) {
+        const mainPid = getScopeMainPid(runSystemctl, scope.unitToken);
+        if (mainPid === null)
+            return 'orphan';
+        // Look up PID file at `<sessionsDir>/<mainPid>.json`. Claude Code's
+        // own session-init writes this file with `pid` + `sessionId` fields.
+        const pidPath = join(sessionsDir, `${mainPid}.json`);
+        const parsed = parsePidFile(pidPath);
+        if (!parsed)
+            return 'orphan';
+        if (parsed.pid !== mainPid)
+            return 'orphan';
+        const row = rowsBySessionId.get(parsed.sessionId);
+        if (!row)
+            return 'orphan';
+        // Found a matching row — mark it detached and stamp the scope token.
+        // Use unindexRow/indexRow to keep the reverse indexes consistent (we
+        // are not changing the sessionId or pid keys, only mutable fields, so
+        // re-indexing is defensive).
+        unindexRow(row);
+        row.status = 'detached';
+        row.scopeUnitToken = scope.unitToken;
+        indexRow(row);
+        logger(`[boot-seed] reattached sessionId=${parsed.sessionId} unit=${scope.unitName} pid=${mainPid}`);
+        return 'reattached';
     }
     function arm() {
         if (armed)
@@ -483,6 +676,13 @@ export function createFsWatcher(opts) {
             mkdirSync(projectsDir, { recursive: true });
         }
         catch { /* best effort */ }
+        // Task 260 — archive subdir must exist before fs.watch attaches;
+        // otherwise the watch handle fails ENOENT and we miss the first
+        // archive event of the session.
+        try {
+            mkdirSync(archiveDir, { recursive: true });
+        }
+        catch { /* best effort */ }
         try {
             pidWatcher = watch(sessionsDir, { persistent: false }, (_event, filename) => {
                 if (!filename || !filename.endsWith('.json'))
@@ -511,8 +711,27 @@ export function createFsWatcher(opts) {
         catch (err) {
             logger(`[fs-watcher] watch-init-failed dir=${projectsDir} message=${err instanceof Error ? err.message : String(err)}`);
         }
+        // Task 260 — second fs.watch on archive/. Without this the archive
+        // route's rename emits a delete on top (handled by jsonlWatcher) but
+        // the create on archive is silent, breaking the rename-coalesce that
+        // turns the pair into one row-updated event. The watcher's
+        // reconcileJsonlFile handles archive paths symmetric to top paths.
+        try {
+            archiveWatcher = watch(archiveDir, { persistent: false }, (_event, filename) => {
+                if (!filename || !filename.endsWith('.jsonl'))
+                    return;
+                const path = join(archiveDir, filename);
+                schedule(path, reconcileJsonlFile);
+            });
+            archiveWatcher.on('error', (err) => {
+                logger(`[fs-watcher] watch-error dir=${archiveDir} message=${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+        catch (err) {
+            logger(`[fs-watcher] watch-init-failed dir=${archiveDir} message=${err instanceof Error ? err.message : String(err)}`);
+        }
         armed = true;
-        logger(`[fs-watcher] armed sessions-dir=${sessionsDir} projects-dir=${projectsDir}`);
+        logger(`[fs-watcher] armed sessions-dir=${sessionsDir} projects-dir=${projectsDir} archive-dir=${archiveDir}`);
     }
     function subscribe(sub) {
         subscribers.add(sub);
@@ -549,6 +768,27 @@ export function createFsWatcher(opts) {
             pidWaiters.set(pid, { resolve, reject, timer });
         });
     }
+    function refreshSidecar(sessionId) {
+        const prior = rowsBySessionId.get(sessionId);
+        if (!prior)
+            return false;
+        // Task 260 — find the sidecar wherever it actually lives on disk
+        // (top or archive). Row state alone doesn't say: an `archived`
+        // state means "no live PTY", but the JSONL/sidecar pair may still
+        // be at the top level (e.g. a pre-Task-260 JSONL that has never
+        // been archived through the route).
+        const topSidecar = sidecarPathForLocation(sessionId, 'top');
+        const archiveSidecar = sidecarPathForLocation(sessionId, 'archive');
+        const location = existsSync(topSidecar)
+            ? 'top'
+            : existsSync(archiveSidecar) ? 'archive' : (prior.state === 'archived' ? 'archive' : 'top');
+        const { sidecar } = readSidecarForLocation(sessionId, location);
+        const updated = applySidecarToRow(prior, sidecar);
+        unindexRow(prior);
+        indexRow(updated);
+        emit({ kind: 'modify', source: 'jsonl', row: updated, sessionId });
+        return true;
+    }
     function close() {
         if (pidWatcher) {
             pidWatcher.close();
@@ -558,6 +798,10 @@ export function createFsWatcher(opts) {
             jsonlWatcher.close();
             jsonlWatcher = null;
         }
+        if (archiveWatcher) {
+            archiveWatcher.close();
+            archiveWatcher = null;
+        }
         for (const t of debounceTimers.values())
             clearTimeout(t);
         debounceTimers.clear();
@@ -578,6 +822,7 @@ export function createFsWatcher(opts) {
         getByPid,
         all,
         waitForPid,
+        refreshSidecar,
         close,
         __internal: { reconcilePidFile, reconcileJsonlFile },
     };