spexcode 0.6.2 → 0.6.6

package/node_modules/@spexcode/spec-cli/dist/search.js

@@ -0,0 +1,61 @@
+import { loadSpecsLite } from '@spexcode/spec-core';
+import { rankDocs } from './ranker.js';
+// zero-result fallback: nearest node titles by per-word edit distance over title+id — the lightweight
+// string distance that routes a typo'd query to a next step. Each query word takes its best normalised
+// Levenshtein similarity against any title/id word (≥0.5, so unrelated words don't accumulate), then the
+// words sum. Same loadSpecsLite read as the ranker; deliberately NOT part of rankDocs scoring (this
+// tolerates typos, the ranker must not).
+export function nearestTitles(query, n = 3) {
+    const words = (s) => s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 1);
+    const lev = (a, b) => {
+        const dp = Array.from({ length: b.length + 1 }, (_, i) => i);
+        for (let i = 1; i <= a.length; i++) {
+            let prev = dp[0];
+            dp[0] = i;
+            for (let j = 1; j <= b.length; j++) {
+                const cur = dp[j];
+                dp[j] = Math.min(dp[j] + 1, dp[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+                prev = cur;
+            }
+        }
+        return dp[b.length];
+    };
+    const qws = words(query);
+    if (!qws.length)
+        return []; // nothing to be "near" (e.g. a pure-CJK query) — the caller still points at spex graph
+    return loadSpecsLite()
+        .map((s) => {
+        const tws = [...new Set(words(`${s.title} ${s.id}`))];
+        let score = 0;
+        for (const q of qws) {
+            let best = 0;
+            for (const t of tws)
+                best = Math.max(best, 1 - lev(q, t) / Math.max(q.length, t.length));
+            if (best >= 0.5)
+                score += best;
+        }
+        return { id: s.id, title: s.title, score };
+    })
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, n)
+        .map(({ id, title }) => ({ id, title }));
+}
+export async function searchSpecs(query, opts = {}) {
+    const t0 = performance.now();
+    // pre-sort by (shorter id, then id): rankDocs sorts stably, so for equal-scored nodes this IS the tiebreak.
+    const nodes = loadSpecsLite()
+        .slice()
+        .sort((a, b) => a.id.length - b.id.length || a.id.localeCompare(b.id));
+    const inputs = nodes.map((s) => ({
+        ref: s, name: `${s.title} ${s.id}`, desc: s.desc, body: s.body,
+    }));
+    const out = rankDocs(query, inputs, { limit: opts.limit }).map((r) => ({
+        id: r.ref.id, title: r.ref.title, path: r.ref.path, score: r.score, snippet: r.snippet,
+    }));
+    if (opts.onStats) {
+        const tokens = inputs.reduce((a, i) => a + `${i.name} ${i.desc} ${i.body}`.split(/[^a-z0-9]+/i).filter(Boolean).length, 0);
+        opts.onStats({ nodes: inputs.length, tokens, ms: performance.now() - t0 });
+    }
+    return out;
+}

package/node_modules/@spexcode/spec-cli/dist/session-declarations.d.ts

@@ -0,0 +1,13 @@
+type DeclarationVerb = 'done' | 'park' | 'ask';
+export declare function sessionStateKit(sessionId?: string): Promise<{
+    s: typeof import("./sessions.js");
+    sess: string | undefined;
+    noRecord: () => string;
+    mark: (fn: () => boolean) => {
+        ok: boolean;
+        reason?: string;
+    };
+    noteEcho: (note?: string) => string;
+}>;
+export declare function runSessionDeclaration(verb: DeclarationVerb, argv?: readonly string[]): Promise<void>;
+export {};

package/node_modules/@spexcode/spec-cli/dist/session-declarations.js

@@ -0,0 +1,126 @@
+// @@@ worker declarations ([[cli-surface]] / [[state]]) - these are the three porcelain writes an
+// agent performs from its own worktree. Keep their session resolution, no-record diagnosis, durable note
+// receipt, and state write together so the CLI hub only selects the verb and never becomes a second owner.
+const DECLARED = ' — recorded; the human sees it in the dashboard. This declaration remains in the session timeline; your next tool call flips only the current graph state back to active (the mark-active hook, by design).';
+// appended ONLY to a propose-close declaration: a worktree about to be discarded may still own ephemeral things the agent started to test this change; nudge (not gate) it to reclaim them before the worktree goes, keyed on whether the thing should outlive the task — never on who started it (a deliberately long-running service / a production build is started-by-you yet must be left alone). Project-agnostic on purpose.
+// @@@ the sweep never includes THIS session - the nudge names sessions as sweepable, and it is read at the one moment a session is thinking about closing. Said loosely it reads as permission to close yourself, which deletes the worktree the reading agent is running in. So the target is scoped to sessions the agent spawned, and the exclusion is stated rather than implied.
+const CLOSE_CLEANUP = '\n\nBefore this worktree closes, check whether you left anything running that you started to test this change — a background process, a dev or preview server, a bound port, a throwaway session you spawned. If nothing depends on it anymore, shut it down, or it keeps running as an orphan. Leave anything meant to keep running: a service you deliberately stood up, a production build, anything other work relies on. What matters is whether it still needs to exist after this task, not whether you started it. If unsure, leave it. This sweep never includes THIS session: you have PROPOSED that the human close it, and closing your own session would delete the worktree you are running in. This is a reminder to check, not a required step.';
+const flag = (argv, name) => {
+    const i = argv.indexOf(`--${name}`);
+    return i >= 0 ? argv[i + 1] : undefined;
+};
+function nothingProposalTrap() {
+    console.error('`spex session done --propose nothing` is an intended trap: no state was recorded.');
+    console.error('Choose the true destination:');
+    console.error('  `merge` - committed spec and code have not landed in `main`.');
+    console.error('  `close` - work is complete: it has landed (or had nothing to land), is verified, and no worktree, human decision/follow-up, or posted artifact needs human inspection.');
+    console.error('  `ask` - a human reply, direction, or decision is needed, including a reported finding/recommendation, handoff, or posted artifact inspection.');
+    console.error('  `park` - a managed delivery or background job will resume a named next action; watching terminal children is not a wake-up.');
+    process.exit(2);
+}
+// Shared with `spex internal session-*`: machine lifecycle producers use the same record-resolution and
+// diagnostic rules, but they do not own any porcelain declaration verb.
+export async function sessionStateKit(sessionId) {
+    const s = await import('./sessions.js');
+    const l = await import('@spexcode/spec-core');
+    const { existsSync, writeFileSync } = await import('node:fs');
+    // the agent-authored state writers resolve WHICH session by id: a `--session <id>` flag (the lifecycle
+    // hooks pass it, parsed from the payload, since they no longer have a cwd `.session`) wins, else the
+    // harness env var (ownSessionId — the agent's own `spex session …` carries the harness session id).
+    const sess = sessionId;
+    // @@@ no-record diagnosis ([[state]]) - the session store resolves from the CURRENT directory (runtimeRoot
+    // ← the cwd's git common dir), so the classic declaration failure is a cd OUTSIDE the session's project —
+    // and a bare "no session record" told the author none of that (field-reported). Name the actual cause and
+    // route the fix; each branch is a distinct situation, distinguished by probing the same store the writer used.
+    const noRecord = () => {
+        // cwd probe FIRST: outside a git repo nothing below can resolve — not the store, and not even the env
+        // id (ownSessionId's alias walk reads the store too) — so diagnose the cwd before touching either.
+        let ids;
+        try {
+            ids = l.listSessionIds();
+        }
+        catch {
+            ids = null;
+        }
+        if (ids === null)
+            return `no session record — declarations resolve the session store from the CURRENT directory, and ${process.cwd()} is not inside a git repository. cd back into the session's worktree and re-declare.`;
+        const wid = sess || s.ownSessionId(); // safe now: the store just resolved, so the alias walk cannot throw
+        if (!wid)
+            return 'no session record — no session id to write: this shell carries no harness session env (SPEXCODE_SESSION_ID / CLAUDE_CODE_SESSION_ID) and no --session was given. Pass --session <id> (spex session ls lists ids).';
+        if (ids.length === 0)
+            return `no session record for ${wid.slice(0, 8)} — declarations resolve the session store from the CURRENT directory, and the project at ${process.cwd()} has no sessions at all: you are in a different project's checkout. cd back into the session's worktree and re-declare.`;
+        return `no session record for ${wid.slice(0, 8)} — this project's store (resolved from ${process.cwd()}) holds ${ids.length} session(s) but not this one: a wrong --session id, or you are declaring from a different project's checkout. cd back into the session's worktree and re-declare, or pass a valid --session <id> (spex session ls).`;
+    };
+    // a state writer from a non-repo cwd throws git's not-a-repo before it can return false — map exactly
+    // that throw to the no-record path (noRecord re-probes and names the cwd); anything else stays loud.
+    // A record that exists but CANNOT carry state (unreadable bytes, or a worktree that is gone) is its own
+    // answer: the writer refused on purpose and already knows why, so that reason is what the caller prints —
+    // never the no-record diagnosis, which would send the author chasing a wrong cwd ([[sessions-core]]).
+    const mark = (fn) => {
+        try {
+            return { ok: fn() };
+        }
+        catch (e) {
+            if (e instanceof s.SessionRecordUnusable)
+                return { ok: false, reason: e.message };
+            if (/not a git repository/i.test(String(e?.stderr ?? e)))
+                return { ok: false };
+            throw e;
+        }
+    };
+    // Taught once per record: the CLI's explicit NOTE column is the only note display that cuts prose.
+    const noteEcho = (note) => {
+        if (!note)
+            return '';
+        const tableCut = s.displayWidth(note) > s.NOTE_BOARD_LIMIT;
+        if (!tableCut)
+            return '';
+        const wid = sess || s.ownSessionId();
+        const rid = wid ? (l.readAliasedRawRecord(wid)?.session_id ?? wid) : null; // sentinel lives in the RECORD's dir, so an aliased codex id lands on the same file
+        if (rid) {
+            const sentinel = l.sessionArtifactPath(rid, 'note-echo-taught');
+            try {
+                if (existsSync(sentinel))
+                    return '';
+                writeFileSync(sentinel, `${new Date().toISOString()}\n`); // only reached on a successful declaration (the echo rides the success branch)
+            }
+            catch { /* unreadable/unwritable store dir → fall through and teach again; never block the echo */ }
+        }
+        return `\nyour note is ${note.length} chars — the session table's NOTE column shows only the first ${s.NOTE_BOARD_LIMIT} display columns. the full text IS recorded, and readable via spex session review ${(wid || '<your-session>').slice(0, 8)} / spex session ls --json. (said once — later cut notes won't repeat this.)`;
+    };
+    return { s, sess, noRecord, mark, noteEcho };
+}
+export async function runSessionDeclaration(verb, argv = process.argv) {
+    const sessionId = flag(argv, 'session');
+    const note = flag(argv, 'note');
+    if (verb === 'done') {
+        // `merge`/`close` are awaiting declarations; `nothing` is an intentional no-write correction trap.
+        const proposal = flag(argv, 'propose') || 'nothing';
+        if (proposal === 'nothing')
+            nothingProposalTrap();
+        const { s, sess, mark, noRecord, noteEcho } = await sessionStateKit(sessionId);
+        let closeNote = proposal === 'close' ? CLOSE_CLEANUP : '';
+        if (proposal === 'close') {
+            // The closeout nudge is advisory: a declaration must land even if the local issue store fails.
+            try {
+                closeNote += (await import('./localIssues.js')).closeoutNudge(sess ?? s.ownSessionId());
+            }
+            catch (e) {
+                console.error(`issue closeout check failed (declaration unaffected): ${e instanceof Error ? e.message : e}`);
+            }
+        }
+        const done = mark(() => s.markDone(proposal, sess, note));
+        console.log(done.ok ? `done (${proposal})${DECLARED}${noteEcho(note)}${closeNote}` : done.reason ?? noRecord());
+        return;
+    }
+    const { s, sess, mark, noRecord, noteEcho } = await sessionStateKit(sessionId);
+    if (verb === 'park') {
+        // sugar: the agent is waiting on a background task; it will self-resume (NOT idle/awaiting)
+        const parked = mark(() => s.markState('parked', { note, sessionId: sess }));
+        console.log(parked.ok ? `parked${DECLARED}${noteEcho(note)}` : parked.reason ?? noRecord());
+        return;
+    }
+    // The agent deliberately pauses for a human response. This is authored state, not an active-only inference.
+    const asked = mark(() => s.markState('asking', { note, sessionId: sess }));
+    console.log(asked.ok ? `asking${DECLARED}${noteEcho(note)}` : asked.reason ?? noRecord());
+}

package/node_modules/@spexcode/spec-cli/dist/session-execution.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from 'hono';
+import type { ExecutionStep } from './execution-trace.js';
+export type SessionExecution = Readonly<{
+    revision: string;
+    turnId: string | null;
+    workingNote: string | null;
+    steps: readonly ExecutionStep[];
+}>;
+export declare function readSessionExecution(id: string): SessionExecution | null;
+export declare function sessionExecutionStream(c: Context): Promise<Response>;

package/node_modules/@spexcode/spec-cli/dist/session-execution.js

@@ -0,0 +1,70 @@
+import { streamSSE } from 'hono/streaming';
+import { harnessById } from './harness.js';
+import { readAliasedRawRecord } from '@spexcode/spec-core';
+import { currentHumanTurn } from './session-timeline.js';
+const absentExecution = (turn = null) => ({ revision: `turn:${turn?.token ?? '0'}`, turnId: turn?.token ?? null, workingNote: null, steps: [] });
+// This is deliberately a read projection. Native transcript bytes stay within the adapter, while the API owns
+// only enough information for the frontend's fixed renderer to paint the current execution slice.
+export function readSessionExecution(id) {
+    let record;
+    try {
+        record = readAliasedRawRecord(id);
+    }
+    catch {
+        return null;
+    }
+    if (!record?.governed)
+        return null;
+    const turn = currentHumanTurn(id);
+    const threadId = typeof record.harness_session_id === 'string' ? record.harness_session_id : '';
+    if (!threadId)
+        return absentExecution(turn);
+    try {
+        const trace = harnessById(typeof record.harness === 'string' && record.harness ? record.harness : 'claude')
+            .executionTrace(threadId, turn);
+        return trace || absentExecution(turn);
+    }
+    catch {
+        // A missing/unreadable native source is an absent transient trace, not a synthetic conversation failure.
+        return absentExecution(turn);
+    }
+}
+const TRACE_TICK_MS = 500;
+const HEARTBEAT_TICKS = 20;
+export async function sessionExecutionStream(c) {
+    const id = c.req.param('id') || '';
+    if (!readSessionExecution(id))
+        return c.json({ error: 'no such session' }, 404);
+    return streamSSE(c, async (stream) => {
+        let aborted = false;
+        let lastRevision = '';
+        let ticks = 0;
+        const publish = async () => {
+            const execution = readSessionExecution(id);
+            if (!execution)
+                return false;
+            if (execution.revision === lastRevision)
+                return true;
+            lastRevision = execution.revision;
+            await stream.writeSSE({ event: 'execution', data: JSON.stringify(execution) });
+            return true;
+        };
+        stream.onAbort(() => { aborted = true; });
+        try {
+            if (!await publish())
+                return;
+            while (!aborted) {
+                await stream.sleep(TRACE_TICK_MS);
+                if (aborted)
+                    break;
+                if (!await publish())
+                    break;
+                if (++ticks % HEARTBEAT_TICKS === 0)
+                    await stream.writeSSE({ event: 'ping', data: 'x' });
+            }
+        }
+        catch {
+            // EventSource reconnects a dropped stream. A native trace read must never take down the session server.
+        }
+    });
+}

package/node_modules/@spexcode/spec-cli/dist/session-files.d.ts

@@ -0,0 +1,28 @@
+export declare class SessionFileError extends Error {
+    readonly status: 400 | 403 | 404 | 500;
+    constructor(status: 400 | 403 | 404 | 500, message: string);
+}
+type SessionFileLock = <T>(id: string, body: () => T) => T;
+export declare const SESSION_FILE_PREVIEW_MAX_BYTES: number;
+export type SessionFilePreviewKind = 'text' | 'image' | 'html';
+export declare function listSessionFiles(id: string): string[];
+export declare function readSessionFiles(id: string): string[];
+export declare function addSessionFile(id: string, input: string, lock: SessionFileLock, cwd?: string): {
+    path: string;
+    added: boolean;
+};
+export declare function retractSessionFile(id: string, input: string, lock: SessionFileLock, cwd?: string): {
+    path: string;
+    removed: boolean;
+};
+export declare function openSessionFile(id: string, path: string): {
+    path: string;
+    name: string;
+    size: number;
+};
+export declare function sessionFilePreviewKind(path: string): {
+    kind: SessionFilePreviewKind;
+    contentType: string;
+} | null;
+export declare const sessionFilesPath: (id: string) => string;
+export {};

package/node_modules/@spexcode/spec-cli/dist/session-files.js

@@ -0,0 +1,130 @@
+import { accessSync, constants, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, isAbsolute, resolve } from 'node:path';
+import { readRecordEntry, sessionArtifactPath } from '@spexcode/spec-core';
+export class SessionFileError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'SessionFileError';
+    }
+}
+export const SESSION_FILE_PREVIEW_MAX_BYTES = 2 * 1024 * 1024;
+const HTML_EXTENSIONS = new Set(['.html', '.htm']);
+const TEXT_EXTENSIONS = new Set(['.txt', '.md', '.markdown', '.json', '.yaml', '.yml', '.toml', '.ini', '.log', '.csv', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.css', '.xml', '.py', '.go', '.rs', '.java', '.sh', '.sql']);
+const IMAGE_TYPES = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp',
+};
+const filesPath = (id) => sessionArtifactPath(id, 'files.json');
+function requireSession(id) {
+    const record = readRecordEntry(id);
+    if (record.kind === 'absent')
+        throw new SessionFileError(404, `session ${id} does not exist`);
+    if (record.kind === 'corrupt')
+        throw new SessionFileError(500, `session ${id} has an unreadable record: ${record.error}`);
+}
+function readFiles(id) {
+    const path = filesPath(id);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw new SessionFileError(500, `session file list is unreadable: ${path} — ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!Array.isArray(parsed) || parsed.some((value) => typeof value !== 'string' || !isAbsolute(value)))
+        throw new SessionFileError(500, `session file list is invalid: ${path}`);
+    return [...new Set(parsed)];
+}
+function writeFiles(id, files) {
+    const path = filesPath(id);
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, `${JSON.stringify(files, null, 2)}\n`);
+        renameSync(tmp, path);
+    }
+    finally {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* rename already consumed the temporary file */ }
+    }
+}
+function currentFile(path) {
+    try {
+        if (!statSync(path).isFile())
+            throw new SessionFileError(400, `not a regular file: ${path}`);
+        accessSync(path, constants.R_OK);
+    }
+    catch (error) {
+        if (error instanceof SessionFileError)
+            throw error;
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            throw new SessionFileError(404, `file does not exist: ${path}`);
+        throw new SessionFileError(403, `file is not readable: ${path}`);
+    }
+}
+export function listSessionFiles(id) {
+    requireSession(id);
+    return readSessionFiles(id);
+}
+// Session projections already hold a parsed record; re-checking session.json here would make an in-memory
+// projection depend on the public route's existence guard. The route-facing list keeps that guard above.
+export function readSessionFiles(id) {
+    return readFiles(id);
+}
+export function addSessionFile(id, input, lock, cwd = process.cwd()) {
+    const path = resolve(cwd, input);
+    currentFile(path);
+    return lock(id, () => {
+        requireSession(id);
+        const files = readFiles(id);
+        if (files.includes(path))
+            return { path, added: false };
+        writeFiles(id, [...files, path]);
+        return { path, added: true };
+    });
+}
+export function retractSessionFile(id, input, lock, cwd = process.cwd()) {
+    const path = resolve(cwd, input);
+    return lock(id, () => {
+        requireSession(id);
+        const files = readFiles(id);
+        if (!files.includes(path))
+            return { path, removed: false };
+        writeFiles(id, files.filter((file) => file !== path));
+        return { path, removed: true };
+    });
+}
+export function openSessionFile(id, path) {
+    requireSession(id);
+    if (!readFiles(id).includes(path))
+        throw new SessionFileError(403, 'that path was not posted by this session');
+    try {
+        const stat = statSync(path);
+        if (!stat.isFile())
+            throw new SessionFileError(404, `file no longer exists: ${path}`);
+        accessSync(path, constants.R_OK);
+        return { path, name: basename(path) || 'download', size: stat.size };
+    }
+    catch (error) {
+        if (error instanceof SessionFileError)
+            throw error;
+        throw new SessionFileError(404, `file no longer exists: ${path}`);
+    }
+}
+export function sessionFilePreviewKind(path) {
+    const extension = basename(path).toLowerCase().match(/\.[^.]+$/)?.[0];
+    if (!extension)
+        return null;
+    if (HTML_EXTENSIONS.has(extension))
+        return { kind: 'html', contentType: 'text/html; charset=utf-8' };
+    if (TEXT_EXTENSIONS.has(extension))
+        return { kind: 'text', contentType: 'text/plain; charset=utf-8' };
+    const contentType = IMAGE_TYPES[extension];
+    return contentType ? { kind: 'image', contentType } : null;
+}
+export const sessionFilesPath = (id) => filesPath(id);

package/node_modules/@spexcode/spec-cli/dist/session-follow.d.ts

@@ -0,0 +1,31 @@
+import { type DisplayStatus, type Session } from './sessions.js';
+export declare function sessionEvent(s: Session): string;
+export declare function launchEvent(s: Session): string;
+export type FollowOpts = {
+    targets: () => string[];
+    self?: string | null;
+    statuses?: string[];
+    includeIdle?: boolean;
+    intervalMs?: number;
+    as?: string;
+    take?: boolean;
+    timeoutMs?: number;
+    onObserved?: (id: string, status: DisplayStatus, previous: DisplayStatus | null) => void;
+    row?: (id: string, status: DisplayStatus, note: string | null) => Session | null;
+};
+export type FollowOutcome = {
+    reached: DisplayStatus;
+    id: string;
+    path: DisplayStatus[];
+} | {
+    mail: {
+        from: string | null;
+        text: string;
+    };
+} | {
+    timedOut: true;
+    path: DisplayStatus[];
+} | {
+    gone: string;
+};
+export declare function followSessions(emit: (line: string) => void, opts: FollowOpts): Promise<FollowOutcome>;

package/node_modules/@spexcode/spec-cli/dist/session-follow.js

@@ -0,0 +1,179 @@
+import { existsSync } from 'node:fs';
+import { sessionStoreDir } from '@spexcode/spec-core';
+import { advanceFollow, followCursor, unreadSince } from '@spexcode/session-core';
+import { timelineDisplay, timelineEvents, timelineStamp } from './session-timeline.js';
+import { sessionTitle } from './sessions.js';
+// @@@ session-follow - supervision is FOLLOWING a log past a cursor, never polling a derived board. One tick
+// costs ONE stat per target: if timeline.ndjson has not grown, nothing is opened and nothing is parsed. No
+// call here reaches the backend, a rendezvous socket, or tmux, which is the whole point — M followers over N
+// sessions cost the control plane zero, where the old poll cost one board build (a connect + a tmux spawn per
+// live session) per follower per interval.
+// Actionable = a state whose arrival means "a human/supervisor must now act". `offline` is deliberately ABSENT
+// where the old poll had it: liveness is a present-tense probe derivation, never authored, so it can never
+// appear on a log ([[state]]). A follower learns what a session DECLARED and never that it died.
+const ACTIONABLE = new Set(['review', 'done', 'close-pending', 'error', 'asking']);
+const NEXT = {
+    review: 'merge | close',
+    done: 'merge | close',
+    'close-pending': 'close',
+    error: 'resume (relaunch & retry) | show --capture | close',
+    asking: 'send "<msg>" | show --capture',
+    idle: 'send "<msg>" | show --capture',
+    queued: 'waiting for a free slot — starts automatically | close',
+};
+const trunc = (s, n) => (s.length <= n ? s : `${s.slice(0, n - 1)}…`);
+export function sessionEvent(s) {
+    const note = s.note ? ` — note: ${s.note}` : '';
+    const asked = s.promptPreview ? ` · asked: ${s.promptPreview}` : '';
+    return `[spex] ${s.status} · ${sessionTitle(s)} — act: ${NEXT[s.status] || '—'}${note}${asked}  [id ${s.id}]`;
+}
+// @@@ launchEvent - a session's FIRST sighting, emitted once per id whatever its status, so the stream is a
+// complete lifecycle feed: launched → [transitions] → closed. A launch's own first line is `active` (not
+// actionable), so without this the feed would be blind to new sessions starting.
+export function launchEvent(s) {
+    const note = s.note ? ` — note: ${s.note}` : '';
+    const asked = s.promptPreview ? ` · asked: ${s.promptPreview}` : '';
+    return `[spex] launched · ${sessionTitle(s)} — act: capture | send "<msg>"${note}${asked}  [id ${s.id}]`;
+}
+export async function followSessions(emit, opts) {
+    const { targets, self = null, statuses, includeIdle = false, intervalMs = 1000, as, take = false, timeoutMs = 1_200_000, onObserved, row } = opts;
+    const tag = as ? `[${as}] ` : '';
+    const state = new Map();
+    const memo = new Map(); // cursors for a follower that has no record of its own to store them in
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    // the no-hang wall: a fixed deadline computed ONCE, checked before EVERY sleep below.
+    const deadline = take ? Date.now() + Math.max(1000, timeoutMs) : 0;
+    const isActionable = (st) => ACTIONABLE.has(st) || (includeIdle && st === 'idle');
+    const passes = (st) => !statuses?.length || statuses.includes(st);
+    const anyPath = () => {
+        for (const f of state.values())
+            if (f.path.length)
+                return f.path;
+        return [];
+    };
+    const readCursor = (id) => (self ? followCursor(self, id) : memo.get(id) ?? null);
+    const writeCursor = (id, to) => { if (self)
+        advanceFollow(self, id, to);
+    else
+        memo.set(id, to); };
+    const line = (id, st, note, first) => {
+        const s = row?.(id, st, note);
+        if (!s)
+            return;
+        if (first)
+            emit(tag + launchEvent(s));
+        else if (passes(st) && isActionable(st))
+            emit(tag + sessionEvent(s));
+    };
+    let first = true;
+    let shown = -1; // stream mode: the last inbox line this process printed (see the INBOX read below)
+    for (;;) {
+        const ids = targets();
+        const seen = new Set();
+        for (const id of ids) {
+            if (id === self)
+                continue; // the follower's own log is its INBOX, followed below on its own cursor rule
+            seen.add(id);
+            if (!existsSync(sessionStoreDir(id))) {
+                if (state.delete(id))
+                    emit(`${tag}[spex] closed · removed  [id ${id}]`);
+                if (take)
+                    return { gone: id };
+                continue;
+            }
+            let f = state.get(id);
+            if (!f) {
+                const evs = timelineEvents(id);
+                // A stored cursor always wins — that IS the resume, losing nothing across a follower's death. With
+                // none: a target already present when the follow started predates it, so we begin at the log's END
+                // (its history is not news); a target that appears on a LATER tick genuinely just launched, so its
+                // whole log is read from 0 and its `launched` line reaches the feed.
+                const pos = readCursor(id) ?? (first ? evs.length : 0);
+                // The ARRIVAL state is the last status line BEFORE the cursor — a fact on the log, not whatever a poll
+                // happened to catch. With no such line the first status we read is the arrival instead.
+                let prev = null;
+                for (let i = Math.min(pos, evs.length) - 1; i >= 0; i--) {
+                    const e = evs[i];
+                    if (e.kind === 'status') {
+                        prev = timelineDisplay(e);
+                        break;
+                    }
+                }
+                f = { pos, prev, path: prev ? [prev] : [], stamp: null };
+                state.set(id, f);
+                if (prev) {
+                    onObserved?.(id, prev, null);
+                    line(id, prev, null, true);
+                }
+            }
+            const stamp = timelineStamp(id);
+            if (stamp !== null && stamp === f.stamp)
+                continue; // THE cheap tick: nothing appended, nothing parsed
+            f.stamp = stamp;
+            const evs = timelineEvents(id);
+            const slice = unreadSince(evs, f.pos);
+            let hit = null;
+            for (let k = 0; k < slice.events.length && !hit; k++) {
+                const e = slice.events[k];
+                if (e.kind === 'sent') {
+                    const s = row?.(id, f.prev ?? 'unknown', null);
+                    if (s)
+                        emit(`${tag}[spex] message · ${sessionTitle(s)} — from ${e.from ?? 'human'}: ${trunc(e.text, 120)}  [id ${id}]`);
+                    continue;
+                }
+                const st = timelineDisplay(e);
+                const was = f.prev;
+                f.prev = st;
+                f.path.push(st);
+                onObserved?.(id, st, was);
+                line(id, st, e.note, was === null);
+                // THE edge: a previously-observed NON-actionable status moving INTO an actionable one. An actionable
+                // ARRIVAL (was === null) is not an edge — that standing level is what a level-triggered wait falsely
+                // returned on; nor is an actionable→actionable hop (review→done). The rise OUT of non-actionable is the
+                // one signal that means "the target needs you AGAIN". The previous state is the previous LINE, so two
+                // moves inside one tick are two edges rather than one collapsed sample.
+                if (take && was !== null && !isActionable(was) && isActionable(st))
+                    hit = { reached: st, id, path: f.path };
+                // Consume exactly up to the event we stopped on, so the lines behind it stay unread for the next wait.
+                if (hit) {
+                    f.pos = slice.at[k] + 1;
+                    writeCursor(id, f.pos);
+                }
+            }
+            if (hit)
+                return hit;
+            f.pos = slice.next;
+            writeCursor(id, f.pos);
+        }
+        for (const id of [...state.keys()]) {
+            if (seen.has(id))
+                continue;
+            state.delete(id);
+            emit(`${tag}[spex] closed · removed  [id ${id}]`);
+        }
+        // THE FOLLOWER'S OWN LOG — watched exactly like any other target, on its own entry in `cursors.json`. It is
+        // a WATCH, not a delivery: a message reaches the agent as a prompt through the adapter ([[delivery-queue]]),
+        // so this position only decides what THIS process has already reported and can never make an agent miss
+        // mail. Never advanced here in take mode — the waiter stops on the event and the next wait resumes on it.
+        if (self && existsSync(sessionStoreDir(self))) {
+            const mine = unreadSince(timelineEvents(self), followCursor(self, self) ?? 0);
+            for (let k = 0; k < mine.events.length; k++) {
+                const e = mine.events[k];
+                if (e.kind !== 'sent')
+                    continue;
+                if (take)
+                    return { mail: { from: e.from, text: e.text } };
+                // a stream has no turn boundary to advance that cursor, so its own high-water mark — process-local,
+                // never written — is what keeps an unread line from being re-printed on every tick.
+                if (mine.at[k] <= shown)
+                    continue;
+                shown = mine.at[k];
+                emit(`${tag}[spex] message · you — from ${e.from ?? 'human'}: ${trunc(e.text, 120)}  [id ${self}]`);
+            }
+        }
+        first = false;
+        if (take && Date.now() >= deadline)
+            return { timedOut: true, path: anyPath() };
+        await sleep(intervalMs);
+    }
+}