spexcode 0.6.1 → 0.6.5

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

@@ -0,0 +1,14 @@
+import type { TimelineEvent } from './session-timeline.js';
+export type Cursors = {
+    version: 1;
+    follows: Record<string, number>;
+};
+export declare function readCursors(id: string): Cursors;
+export declare const followCursor: (id: string, target: string) => number | null;
+export declare function advanceFollow(id: string, target: string, to: number): void;
+export declare const followedSessions: (id: string) => string[];
+export declare function unreadSince(events: TimelineEvent[], from: number): {
+    events: TimelineEvent[];
+    at: number[];
+    next: number;
+};

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

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sessionArtifactPath, sessionStoreDir } from '@spexcode/spec-core';
+const cursorsPath = (id) => sessionArtifactPath(id, 'cursors.json');
+const at = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0);
+// Never throws: a missing, empty, or unparseable file reads as "nothing consumed", because re-showing a
+// message is the honest recovery for a lost position and skipping one is not. Followed entries whose target
+// store dir is gone are dropped here — expiry is this read, and the next write persists it.
+export function readCursors(id) {
+    let raw = null;
+    try {
+        raw = JSON.parse(readFileSync(cursorsPath(id), 'utf8'));
+    }
+    catch { /* no cursors yet */ }
+    const follows = {};
+    const stored = raw?.follows;
+    if (stored && typeof stored === 'object') {
+        for (const [target, pos] of Object.entries(stored)) {
+            if (!target || !existsSync(sessionStoreDir(target)))
+                continue;
+            follows[target] = at(pos);
+        }
+    }
+    return { version: 1, follows };
+}
+// Written whole and atomically, one field per line — the same shape as the session record, so a position stays
+// readable by an exact whole-line match where a value regex would not be.
+function writeCursors(id, cursors) {
+    const dir = sessionStoreDir(id);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.cursors.json.${process.pid}.tmp`);
+    writeFileSync(tmp, JSON.stringify(cursors, null, 2) + '\n');
+    renameSync(tmp, cursorsPath(id));
+}
+export const followCursor = (id, target) => {
+    const stored = readCursors(id).follows[target];
+    return stored === undefined ? null : stored;
+};
+// Start or advance a follow. Following IS this entry existing, so the first call registers the relationship.
+// Monotonic: a stale read can leave a position too low (an event read twice), never too high (one lost).
+export function advanceFollow(id, target, to) {
+    const cursors = readCursors(id);
+    const stored = cursors.follows[target];
+    if (stored !== undefined && to <= stored)
+        return;
+    writeCursors(id, { ...cursors, follows: { ...cursors.follows, [target]: Math.max(0, Math.floor(to)) } });
+}
+export const followedSessions = (id) => Object.keys(readCursors(id).follows);
+const sameStatus = (a, b) => a.kind === 'status' && b.kind === 'status' && a.status === b.status
+    && (a.proposal ?? null) === (b.proposal ?? null) && (a.note ?? null) === (b.note ?? null);
+// @@@ edges, not lines - what a reader has not yet seen, with repeated status lines dropped. X→X IS NOT A
+// TRANSITION: the log is append-only and already holds runs of identical status lines from before the
+// timeline observer was deleted (every stray `spex serve` process ran an fs.watch over the same store and
+// re-recorded each real move, so ONE transition landed as up to 6 lines within ~200ms). Those bytes are
+// history and stay. Any consumer that decides "did it move?" must therefore compare VALUES, never adjacency,
+// and must compare against the last status the reader ALREADY saw — otherwise a duplicate straddling the
+// cursor boundary reads as a fresh move on the very next tick. `next` is where the cursor goes after consuming
+// the WHOLE slice: the full length, because a dropped duplicate is still consumed. `at[i]` is the absolute
+// index of `events[i]`, which is what lets a reader that STOPS on one event ([[session-follow]]'s take-one
+// wait) advance to exactly `at[i] + 1` and leave the lines behind it unread for the next reader.
+export function unreadSince(events, from) {
+    const start = Math.min(Math.max(0, Math.floor(from)), events.length);
+    let prev = null;
+    for (let i = start - 1; i >= 0; i--)
+        if (events[i].kind === 'status') {
+            prev = events[i];
+            break;
+        }
+    const out = [];
+    const at = [];
+    for (let i = start; i < events.length; i++) {
+        const e = events[i];
+        if (e.kind === 'status') {
+            if (prev && sameStatus(prev, e))
+                continue;
+            prev = e;
+        }
+        out.push(e);
+        at.push(i);
+    }
+    return { events: out, at, next: events.length };
+}

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>;