@spexcode/spec-cli 0.6.7 → 0.6.8

package/dist/reviews.js

@@ -86,7 +86,9 @@ export async function issuesReview(query, requestedPage) {
         }),
     };
 }
-const byNewest = (a, b) => Number(b.filterKind === EVAL_FILTER_KIND.RESULT) - Number(a.filterKind === EVAL_FILTER_KIND.RESULT)
+const orderableEval = (item) => item.filterKind === EVAL_FILTER_KIND.RESULT
+    || item.filterKind === EVAL_FILTER_KIND.DEFERRED;
+const byNewest = (a, b) => Number(orderableEval(b)) - Number(orderableEval(a))
     || String(b.ts ?? '').localeCompare(String(a.ts ?? ''))
     || String(a.node ?? '').localeCompare(String(b.node ?? ''))
     || String(a.scenario ?? '').localeCompare(String(b.scenario ?? ''));
@@ -114,10 +116,11 @@ export function trunkEvalReviewItems(nodes) {
                 ...reading,
                 expected: scenario.expected ?? reading.expected,
                 tags: scenario.tags,
-                state: evalReviewState(reading),
+                ...(reading.freshnessDeferred
+                    ? { state: 'deferred', filterKind: EVAL_FILTER_KIND.DEFERRED }
+                    : { state: evalReviewState(reading), filterKind: EVAL_FILTER_KIND.RESULT }),
                 node: node.id,
                 hue: node.hue,
-                filterKind: EVAL_FILTER_KIND.RESULT,
             });
         }
     }
@@ -149,10 +152,11 @@ export function scopedEvalReviewItems(model) {
                 expected: scenario.expected ?? reading.expected,
                 tags: scenario.tags,
                 impact: scenario.impact,
-                state: evalReviewState(reading),
+                ...(reading.freshnessDeferred
+                    ? { state: 'deferred', filterKind: EVAL_FILTER_KIND.DEFERRED }
+                    : { state: evalReviewState(reading), filterKind: EVAL_FILTER_KIND.RESULT }),
                 node: node.id,
                 hue: node.hue,
-                filterKind: EVAL_FILTER_KIND.RESULT,
             };
             items.push(item);
         }
@@ -278,9 +282,10 @@ export function timelineEvalReviewItems(timeline, node) {
         })),
         ...[...latest.values()].map((reading) => ({
             ...reading,
-            state: evalReviewState(reading),
+            ...(reading.freshnessDeferred
+                ? { state: 'deferred', filterKind: EVAL_FILTER_KIND.DEFERRED }
+                : { state: evalReviewState(reading), filterKind: EVAL_FILTER_KIND.RESULT }),
             node,
-            filterKind: EVAL_FILTER_KIND.RESULT,
             filterKey: `${EVAL_FILTER_KIND.RESULT}:${reading.scenario}`,
         })),
         ...(timeline.dangling ?? []).map((track) => ({

package/dist/runtime-ownership.d.ts

@@ -10,6 +10,16 @@ export type BackendInstanceRecord = {
 export declare function readBackendInstanceRecords(root?: string): BackendInstanceRecord[];
 export declare function registerBackendInstance(instanceId: string, pid?: number, root?: string): BackendInstanceRecord;
 export declare function unregisterBackendInstance(instanceId: string, pid?: number): void;
+type ProcBackendCandidate = BackendInstanceRecord & {
+    candidatePid: number;
+    command: string;
+};
+/**
+ * Reap only backend children whose supervisor identity is provably stale. A dead registry PID alone is not
+ * enough: the live process must carry the exact instance id and project root, run the backend entrypoint, and
+ * have been orphaned to PID 1. Ordinary launchers, shells, and app-server generations do not match.
+ */
+export declare function reapOrphanBackendInstances(root?: string): ProcBackendCandidate[];
 export declare function spawnDetachedRuntime(opts: {
     cwd: string;
     logFile: string;
@@ -19,3 +29,4 @@ export declare function spawnDetachedRuntime(opts: {
     args: string[];
     env?: NodeJS.ProcessEnv;
 }): ProcessIdentity;
+export {};

package/dist/runtime-ownership.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { closeSync, mkdirSync, openSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { closeSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { repoRoot } from '@spexcode/spec-core';
 import { readJsonConfig, runtimeRoot } from '@spexcode/spec-core';
@@ -47,6 +47,84 @@ export function unregisterBackendInstance(instanceId, pid = process.pid) {
     }
     catch { /* not ours / already removed */ }
 }
+const procRows = () => {
+    try {
+        return readdirSync('/proc').filter((name) => /^\d+$/.test(name)).map(Number);
+    }
+    catch {
+        return [];
+    }
+};
+const procEnv = (pid) => {
+    try {
+        return Object.fromEntries(readFileSync(`/proc/${pid}/environ`, 'utf8').split('\0').flatMap((entry) => {
+            const split = entry.indexOf('=');
+            return split > 0 ? [[entry.slice(0, split), entry.slice(split + 1)]] : [];
+        }));
+    }
+    catch {
+        return {};
+    }
+};
+const procCommand = (pid) => {
+    try {
+        return readFileSync(`/proc/${pid}/cmdline`, 'utf8').replaceAll('\0', ' ').trim();
+    }
+    catch {
+        return '';
+    }
+};
+const procParent = (pid) => {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        const close = stat.lastIndexOf(')');
+        const fields = stat.slice(close + 2).split(' ');
+        return Number(fields[1]) || null;
+    }
+    catch {
+        return null;
+    }
+};
+const isBackendCommand = (command) => /(?:^|\/)spec-cli\/(?:src\/index\.ts|dist\/index\.js)(?:\s|$)/.test(command);
+/**
+ * Reap only backend children whose supervisor identity is provably stale. A dead registry PID alone is not
+ * enough: the live process must carry the exact instance id and project root, run the backend entrypoint, and
+ * have been orphaned to PID 1. Ordinary launchers, shells, and app-server generations do not match.
+ */
+export function reapOrphanBackendInstances(root = repoRoot()) {
+    const records = readBackendInstanceRecords(root);
+    const liveCurrent = records.filter((record) => processStartToken(record.pid) === record.startToken);
+    const currentIds = new Set(liveCurrent.map((record) => record.instanceId));
+    const candidates = [];
+    for (const record of records) {
+        if (currentIds.has(record.instanceId))
+            continue;
+        if (processStartToken(record.pid) === record.startToken)
+            continue;
+        for (const pid of procRows()) {
+            const env = procEnv(pid);
+            if (env.SPEXCODE_INSTANCE_ID !== record.instanceId || env.SPEXCODE_PROJECT_ROOT !== root)
+                continue;
+            if (procParent(pid) !== 1)
+                continue;
+            const command = procCommand(pid);
+            if (!isBackendCommand(command))
+                continue;
+            candidates.push({ ...record, candidatePid: pid, command });
+        }
+    }
+    for (const candidate of candidates) {
+        try {
+            process.kill(candidate.candidatePid, 'SIGTERM');
+        }
+        catch { /* exact process already exited */ }
+        try {
+            rmSync(backendInstancePath(candidate.instanceId), { force: true });
+        }
+        catch { /* stale record is advisory */ }
+    }
+    return candidates;
+}
 export function spawnDetachedRuntime(opts) {
     mkdirSync(dirname(opts.logFile), { recursive: true });
     mkdirSync(dirname(opts.pidFile), { recursive: true });

package/dist/session-application.d.ts

@@ -0,0 +1,23 @@
+import { type CommittedSessionChange, type ProductionSessionApplication } from '@spexcode/session-application';
+type SessionApplicationCommitWake = (recipients: readonly string[]) => void;
+/** The application owns commit ordering; Spex supplies the adopter transport wake. */
+export declare function setSessionApplicationCommitWake(wake: SessionApplicationCommitWake): void;
+/** Allow the adopter to refresh its board stream after the canonical transaction commits. */
+export declare function setSessionApplicationCommitObserver(observer: (change: Pick<CommittedSessionChange, 'recipients'>) => void): void;
+/** The backend's sole session application composition. Path selection is shared with self-launch. */
+export declare function configuredSessionApplication(): ProductionSessionApplication;
+export type SessionApplicationCutoverState = 'ready' | 'residue' | 'fresh' | 'migration-required' | 'fenced' | 'ambiguous';
+/** Inspect cutover state without initializing a fresh database as a side effect of a rejected request. */
+export declare function sessionApplicationCutoverState(): SessionApplicationCutoverState;
+/** Resolve the canonical application. A legacy tree is cut over at its first canonical access; runtime code
+ * never gets to choose between JSON and SQLite based on the caller or request path. */
+export declare function configuredSessionApplicationIfCutover(): ProductionSessionApplication | undefined;
+/** Initialize a fresh canonical store only after an accepted create has crossed its no-side-effect boundary. */
+export declare function initializeFreshSessionApplication(): ProductionSessionApplication;
+export declare function acquireFreshSessionApplicationForCreate(): {
+    application: ProductionSessionApplication;
+    owned: boolean;
+};
+export declare function releaseFreshSessionApplicationForCreate(owned: boolean, committed: boolean): void;
+export declare function resetConfiguredSessionApplicationForTest(): void;
+export {};

package/dist/session-application.js

@@ -0,0 +1,189 @@
+import { existsSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { openProjectSessionApplication, legacyResidueExists, migrateJsonSessionRecords, } from '@spexcode/session-application';
+import { requireLocalDatabasePath, resolveDatabasePath } from '@spexcode/session-selflaunch';
+import { runtimeRoot } from '@spexcode/spec-core';
+import { jsonMigrationFencePath } from '@spexcode/session-application';
+let cached;
+let cachedPath;
+let freshStoreOwned = false;
+let freshStoreCommitted = false;
+let freshStoreLeases = 0;
+let commitWake = () => { };
+let commitObserver;
+/** The application owns commit ordering; Spex supplies the adopter transport wake. */
+export function setSessionApplicationCommitWake(wake) {
+    commitWake = wake;
+}
+/** Allow the adopter to refresh its board stream after the canonical transaction commits. */
+export function setSessionApplicationCommitObserver(observer) {
+    commitObserver = observer;
+}
+/** The backend's sole session application composition. Path selection is shared with self-launch. */
+export function configuredSessionApplication() {
+    const databasePath = resolveDatabasePath();
+    if (cached !== undefined && cachedPath === databasePath)
+        return cached;
+    if (cached !== undefined)
+        cached.close();
+    cached = openProjectSessionApplication({
+        databasePath,
+        locality: path => { requireLocalDatabasePath(path); },
+        onCommitted: result => {
+            commitWake(result.recipients);
+            if (commitObserver)
+                setImmediate(() => commitObserver?.(result));
+        },
+        onRuntimeBound: sessionId => commitWake([sessionId]),
+    });
+    cachedPath = databasePath;
+    return cached;
+}
+// A marked store is `ready` only once its legacy tree holds nothing left to absorb. The scan runs once per process
+// per store: after residue is migrated (or none was found) no legacy writer exists to create more, so later calls
+// answer from memory instead of walking every session directory on the hot path.
+const settledResidueStores = new Set();
+/** Inspect cutover state without initializing a fresh database as a side effect of a rejected request. */
+export function sessionApplicationCutoverState() {
+    const databasePath = resolveDatabasePath();
+    const recordsRoot = join(runtimeRoot(), 'sessions');
+    const storeKey = `${databasePath}\0${recordsRoot}`;
+    if (existsSync(`${databasePath}.json-migration.json`)) {
+        if (settledResidueStores.has(storeKey))
+            return 'ready';
+        if (legacyResidueExists(recordsRoot))
+            return 'residue';
+        settledResidueStores.add(storeKey);
+        return 'ready';
+    }
+    if (existsSync(jsonMigrationFencePath(recordsRoot)))
+        return 'fenced';
+    if (existsSync(recordsRoot) && readdirSync(recordsRoot, { withFileTypes: true }).some(entry => entry.isDirectory()))
+        return 'migration-required';
+    if (existsSync(databasePath))
+        return 'ambiguous';
+    return 'fresh';
+}
+/** Resolve the canonical application. A legacy tree is cut over at its first canonical access; runtime code
+ * never gets to choose between JSON and SQLite based on the caller or request path. */
+export function configuredSessionApplicationIfCutover() {
+    const state = sessionApplicationCutoverState();
+    if (state === 'ready')
+        return configuredSessionApplication();
+    if (state === 'migration-required' || state === 'residue')
+        return initializeMigratedSessionApplication(state);
+    if (state === 'fresh')
+        return initializeFreshSessionApplication();
+    if (state === 'fenced' || state === 'ambiguous') {
+        throw new Error(`session application cutover is ${state}; refusing a legacy/runtime split`);
+    }
+    return undefined;
+}
+// One importer for both shapes of legacy tree. Before the marker it installs the canonical store; after the
+// marker it absorbs whatever residue the tree still holds into the store this process already owns, then
+// retires the tree. Either way the tree is gone when this returns, so the cutover state settles to `ready`.
+function initializeMigratedSessionApplication(state) {
+    const databasePath = resolveDatabasePath();
+    const recordsRoot = join(runtimeRoot(), 'sessions');
+    const locality = (path) => { requireLocalDatabasePath(path); };
+    if (state === 'migration-required') {
+        migrateJsonSessionRecords({ databasePath, recordsRoot, locality });
+        return configuredSessionApplication();
+    }
+    const application = configuredSessionApplication();
+    const report = migrateJsonSessionRecords({ databasePath, recordsRoot, locality, application });
+    settledResidueStores.add(`${databasePath}\0${recordsRoot}`);
+    const residue = report.residue;
+    if (residue) {
+        console.log(`[session-application] migrated legacy residue from ${recordsRoot}: ${residue.records} record(s), ${residue.events} event(s), ${residue.parentEdges} parent edge(s), ${residue.watchEdges} watch edge(s), ${residue.pending} pending; ${residue.unclaimed.length} unclaimed dir(s)${residue.unclaimed.length ? ` (${residue.unclaimed.join(', ')})` : ''}; backup ${residue.backupRoot}`);
+    }
+    return application;
+}
+/** Initialize a fresh canonical store only after an accepted create has crossed its no-side-effect boundary. */
+export function initializeFreshSessionApplication() {
+    const state = sessionApplicationCutoverState();
+    if (state === 'ready')
+        return configuredSessionApplication();
+    if (state === 'residue')
+        return initializeMigratedSessionApplication(state);
+    if (state !== 'fresh')
+        throw new Error(`cannot initialize a fresh session store from cutover state: ${state}`);
+    const databasePath = resolveDatabasePath();
+    const recordsRoot = join(runtimeRoot(), 'sessions');
+    migrateJsonSessionRecords({ databasePath, recordsRoot, locality: path => { requireLocalDatabasePath(path); } });
+    return configuredSessionApplication();
+}
+export function acquireFreshSessionApplicationForCreate() {
+    const state = sessionApplicationCutoverState();
+    if (state === 'fresh') {
+        const application = initializeFreshSessionApplication();
+        freshStoreOwned = true;
+        freshStoreCommitted = false;
+        freshStoreLeases++;
+        return { application, owned: true };
+    }
+    if (state === 'ready' && freshStoreOwned && !freshStoreCommitted) {
+        freshStoreLeases++;
+        return { application: configuredSessionApplication(), owned: true };
+    }
+    if (state === 'residue')
+        return { application: initializeMigratedSessionApplication(state), owned: false };
+    if (state !== 'ready')
+        throw new Error(`cannot initialize a session store from cutover state: ${state}`);
+    return { application: configuredSessionApplication(), owned: false };
+}
+export function releaseFreshSessionApplicationForCreate(owned, committed) {
+    if (!owned)
+        return;
+    if (committed)
+        freshStoreCommitted = true;
+    freshStoreLeases = Math.max(0, freshStoreLeases - 1);
+    if (freshStoreLeases !== 0)
+        return;
+    if (freshStoreCommitted) {
+        try {
+            unlinkSync(jsonMigrationFencePath(join(runtimeRoot(), 'sessions')));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        return;
+    }
+    const application = cached;
+    const rows = application?.protocol.withTransaction(tx => Number(tx.query('SELECT COUNT(*) AS count FROM session_application_state')[0]?.count ?? 0)) ?? 0;
+    if (rows !== 0) {
+        freshStoreCommitted = true;
+        try {
+            unlinkSync(jsonMigrationFencePath(join(runtimeRoot(), 'sessions')));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        return;
+    }
+    application?.close();
+    cached = undefined;
+    const databasePath = resolveDatabasePath();
+    const recordsRoot = join(runtimeRoot(), 'sessions');
+    for (const path of [databasePath, `${databasePath}.json-migration.json`, jsonMigrationFencePath(recordsRoot)]) {
+        try {
+            unlinkSync(path);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    rmSync(`${databasePath}.json-migration-backup`, { recursive: true, force: true });
+    freshStoreOwned = false;
+}
+export function resetConfiguredSessionApplicationForTest() {
+    cached?.close();
+    cached = undefined;
+    settledResidueStores.clear();
+    freshStoreOwned = false;
+    freshStoreCommitted = false;
+    freshStoreLeases = 0;
+}

package/dist/session-declarations.js

@@ -27,7 +27,11 @@ export async function sessionStateKit(sessionId) {
     // 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;
+    // Hook payloads from Codex carry the native thread id, while the canonical
+    // application is keyed by the Spex session id. Resolve that alias once at
+    // the state-writer boundary; shell hooks stay transport-only and every
+    // lifecycle producer writes the same canonical record.
+    const sess = sessionId ? (l.readAliasedRawRecord(sessionId)?.session_id ?? sessionId) : undefined;
     // @@@ 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
@@ -99,6 +103,14 @@ export async function runSessionDeclaration(verb, argv = process.argv) {
         if (proposal === 'nothing')
             nothingProposalTrap();
         const { s, sess, mark, noRecord, noteEcho } = await sessionStateKit(sessionId);
+        if (proposal === 'merge') {
+            const readiness = s.mergeReadiness('merge');
+            if (!readiness.ready) {
+                console.error(`review declaration refused: ${readiness.reason}`);
+                process.exitCode = 1;
+                return;
+            }
+        }
         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.

package/dist/session-files.d.ts

@@ -6,6 +6,12 @@ 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 type SessionFileStatus = {
+    path: string;
+    valid: boolean;
+    reason?: string;
+};
+export declare function inspectSessionFiles(id: string): SessionFileStatus[];
 export declare function readSessionFiles(id: string): string[];
 export declare function addSessionFile(id: string, input: string, lock: SessionFileLock, cwd?: string): {
     path: string;

package/dist/session-files.js

@@ -71,7 +71,19 @@ 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
+export function inspectSessionFiles(id) {
+    requireSession(id);
+    return readFiles(id).map((path) => {
+        try {
+            currentFile(path);
+            return { path, valid: true };
+        }
+        catch (error) {
+            return { path, valid: false, reason: error instanceof Error ? error.message : String(error) };
+        }
+    });
+}
+// Session projections already hold a parsed runtime envelope; re-checking it 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);

package/dist/session-follow.js

@@ -1,13 +1,9 @@
-import { existsSync } from 'node:fs';
-import { sessionStoreDir } from '@spexcode/spec-core';
-import { advanceFollow, followCursor, unreadSince } from '@spexcode/session-core';
+import { configuredSessionApplicationIfCutover } from './session-application.js';
 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.
+// @@@ session-follow - supervision follows canonical SQLite events past an application-owned cursor, never a
+// derived board. The bounded observation tick reads the event sequence and cursor only; it never opens a backend,
+// rendezvous socket, or tmux. M followers over N sessions therefore cost the control plane zero native probes.
 // 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.
@@ -51,11 +47,19 @@ export async function followSessions(emit, opts) {
                 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 application = configuredSessionApplicationIfCutover();
+    const canonicalSelf = self && application?.readState(self) ? self : null;
+    const readCursor = (id) => {
+        if (!self)
+            return memo.get(id) ?? null;
+        return canonicalSelf ? application.readFollowCursor(canonicalSelf, id) : null;
+    };
+    const writeCursor = (id, to) => {
+        if (!self)
+            memo.set(id, to);
+        else if (canonicalSelf)
+            application.advanceFollowCursor(canonicalSelf, id, to);
+    };
     const line = (id, st, note, first) => {
         const s = row?.(id, st, note);
         if (!s)
@@ -74,7 +78,7 @@ export async function followSessions(emit, opts) {
             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 (!application?.readState(id)) {
                 if (state.delete(id))
                     emit(`${tag}[spex] closed · removed  [id ${id}]`);
                 if (take)
@@ -111,7 +115,12 @@ export async function followSessions(emit, opts) {
                 continue; // THE cheap tick: nothing appended, nothing parsed
             f.stamp = stamp;
             const evs = timelineEvents(id);
-            const slice = unreadSince(evs, f.pos);
+            const unread = evs.slice(f.pos);
+            const slice = {
+                events: unread,
+                at: unread.map((_, index) => f.pos + index),
+                next: evs.length,
+            };
             let hit = null;
             for (let k = 0; k < slice.events.length && !hit; k++) {
                 const e = slice.events[k];
@@ -151,18 +160,26 @@ export async function followSessions(emit, opts) {
             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);
+        // THE FOLLOWER'S OWN LOG — watched exactly like any other target, on its own canonical cursor row. In take
+        // mode the returned message is this wait's consumed result, so advance past it before returning; otherwise
+        // an empty cursor returns the same oldest inbox message forever. A turn-boundary delivery may still present
+        // the message through the adapter, but it does not own this read cursor.
+        if (self && application?.readState(self)) {
+            const ownEvents = timelineEvents(self);
+            const ownStart = readCursor(self) ?? 0;
+            const ownUnread = ownEvents.slice(ownStart);
+            const mine = {
+                events: ownUnread,
+                at: ownUnread.map((_, index) => ownStart + index),
+            };
             for (let k = 0; k < mine.events.length; k++) {
                 const e = mine.events[k];
                 if (e.kind !== 'sent')
                     continue;
-                if (take)
+                if (take) {
+                    writeCursor(self, mine.at[k] + 1);
                     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)

package/dist/session-record-lock.d.ts

@@ -0,0 +1,3 @@
+export declare function withSessionRecordLock<T>(id: string, body: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+export declare function withSessionRecordLockSync<T>(id: string, body: () => T): T;
+export declare function trySessionRecordLockSync(id: string): (() => void) | null;

package/dist/session-record-lock.js

@@ -0,0 +1,94 @@
+import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { runtimeRoot } from '@spexcode/spec-core';
+const root = () => join(runtimeRoot(), '.session-record-locks');
+const pathFor = (id) => join(root(), `${id}.lock`);
+const pause = (signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(Object.assign(new Error('The operation was aborted'), { name: 'AbortError', code: 'ABORT_ERR' }));
+        return;
+    }
+    const timer = setTimeout(resolve, 10);
+    if (signal)
+        signal.addEventListener('abort', () => { clearTimeout(timer); reject(Object.assign(new Error('The operation was aborted'), { name: 'AbortError', code: 'ABORT_ERR' })); }, { once: true });
+});
+async function acquire(id, timeoutMs = 30_000, signal) {
+    mkdirSync(root(), { recursive: true });
+    const path = pathFor(id), deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (signal?.aborted)
+            throw Object.assign(new Error('The operation was aborted'), { name: 'AbortError', code: 'ABORT_ERR' });
+        try {
+            const fd = openSync(path, 'wx');
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => { try {
+                unlinkSync(path);
+            }
+            catch { /* dead-owner recovery may have removed it */ } };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let owner = 0;
+            try {
+                owner = Number(readFileSync(path, 'utf8').trim()) || 0;
+            }
+            catch { /* creator/releaser race */ }
+            if (owner && owner !== process.pid) {
+                try {
+                    process.kill(owner, 0);
+                }
+                catch {
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch { /* race */ }
+                    ;
+                    continue;
+                }
+            }
+            if (Date.now() >= deadline)
+                throw new Error(`session record ${id}: timed out waiting for transaction lock`);
+            await pause(signal);
+        }
+    }
+}
+export async function withSessionRecordLock(id, body, signal) {
+    const release = await acquire(id, 30_000, signal);
+    try {
+        return await body();
+    }
+    finally {
+        release();
+    }
+}
+export function withSessionRecordLockSync(id, body) {
+    const release = trySessionRecordLockSync(id);
+    if (!release)
+        throw new Error(`session record ${id}: transaction lock is busy`);
+    try {
+        return body();
+    }
+    finally {
+        release();
+    }
+}
+export function trySessionRecordLockSync(id) {
+    mkdirSync(root(), { recursive: true });
+    const path = pathFor(id);
+    try {
+        const fd = openSync(path, 'wx');
+        writeSync(fd, String(process.pid));
+        closeSync(fd);
+        return () => { try {
+            unlinkSync(path);
+        }
+        catch { /* dead-owner recovery may have removed it */ } };
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return null;
+        throw error;
+    }
+}