@playola-radio/slipstream 0.1.0 → 0.3.0

package/dist/session.js

@@ -1,25 +1,26 @@
-import { access, readdir, realpath } from 'node:fs/promises';
+import { access, lstat, mkdtemp, readdir, readFile, realpath, rm, stat, truncate, writeFile } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
 import { isAbsolute, join, relative, sep } from 'node:path';
 import { createCas } from "./cas.js";
 import { createReader, DEFAULT_MAX_BYTES } from "./reader.js";
 import { createLog } from "./log.js";
-import { createEngine } from "./engine.js";
+import { addUnknownScope, createEngine, isUnderUnknownScope } from "./engine.js";
+import { detectCaptureScope } from "./capture-scope.js";
 import { createHealth } from "./health.js";
 import { acquireSessionLock } from "./lock.js";
 import { recoverSession } from "./recovery.js";
 import { StorageError, assertOwnerOnly, mkdirpDurable } from "./storage.js";
 import { snapshotsEqual } from "./snapshot.js";
-import { isValidSessionId } from "./store-reader.js";
+import { finalRecord, isValidSessionId } from "./store-reader.js";
 import { createPlatform } from "./platform.js";
 import { createAttributionProducer, DEFAULT_ENRICHMENT_POLICY, } from "./attribution-producer.js";
-import { normalizeAsk, questionBody, questionResult, readQuestionContext, QuestionError, QUESTION_TTL_MS, QUESTION_LIMIT, assertAnswerText, answerResult } from "./questions.js";
-import { createCoverageRunner } from "./transcript/runner.js";
-import { nodeDiscoveryIO, nodeTranscriptFileIO } from "./transcript/fs-io.js";
-/** How often the transcript watcher re-runs discovery and reads new records. */
-export const DEFAULT_TRANSCRIPT_POLL_MS = 2000;
+import { EVENT_TYPES } from "./event.js";
+import { normalizeAsk, questionBody, questionResult, readQuestionContext, QuestionError, QUESTION_TTL_MS, QUESTION_LIMIT, assertAnswerText, answerResult, normalizeExchange, exchangeBody, exchangeResult, sameSourceContext, normalizeRelayUpdate, relayUpdateBody, relayUpdateResult } from "./questions.js";
 /** A `request_id` was reused with a different title — a caller mistake, not a
  * retry, so it never commits a second declaration. */
+export class RootChangedError extends Error {
+}
 export class InvalidTitleError extends Error {
     code = 'INVALID_TITLE';
     constructor(message) {
@@ -27,7 +28,15 @@ export class InvalidTitleError extends Error {
         this.name = 'InvalidTitleError';
     }
 }
-const defaultDependencies = { createLog, platform: createPlatform(), enumerate, readQuestionContext };
+const CORE_EVENT_TYPES = new Set(EVENT_TYPES);
+const isCoreEvent = (event) => CORE_EVENT_TYPES.has(event.type);
+const defaultDependencies = {
+    createLog,
+    platform: createPlatform(),
+    enumerate,
+    readQuestionContext,
+    detectScope: detectCaptureScope,
+};
 /** A relative path escapes its base only via a leading `..` segment (or when it
  * comes back absolute); a filename that merely starts with `..`, like
  * `..notes.ts`, stays inside. */
@@ -37,6 +46,37 @@ function escapesBase(rel) {
 function isUnder(child, parent) {
     return !escapesBase(relative(parent, child));
 }
+/** A frozen copy of the root `.slipstreamignore`, handed to git as its
+ * lowest-precedence excludes file so capture can drop extra paths — including
+ * tracked ones git would merge. Copied once so a mid-capture edit does not
+ * change this capture's scope; a later restart re-reads it, matching how git's
+ * own rule changes take effect. Returns undefined when the file is absent or
+ * empty. A file that exists but cannot be read rejects rather than silently
+ * widening scope to paths the user meant to exclude. Only consulted inside a
+ * git work tree; a non-git root ignores the file. */
+async function freezeSlipstreamIgnore(root) {
+    const path = join(root, '.slipstreamignore');
+    // Stat (which follows symlinks but never blocks) before opening: a named pipe
+    // or other non-regular file would otherwise hang the read and stall startup.
+    let info;
+    try {
+        info = await stat(path);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+    if (!info.isFile())
+        throw new Error(`.slipstreamignore is not a regular file`);
+    const content = await readFile(path, 'utf8');
+    if (content.trim() === '')
+        return undefined;
+    const dir = await mkdtemp(join(tmpdir(), 'slip-ignore-'));
+    const file = join(dir, 'excludes');
+    await writeFile(file, content);
+    return { dir, file };
+}
 export async function startCapture(opts, dependencies = {}) {
     const deps = { ...defaultDependencies, ...dependencies };
     if (opts.sessionId !== undefined) {
@@ -50,13 +90,45 @@ export async function startCapture(opts, dependencies = {}) {
     // The native watcher reports realpaths; resolve symlinks in the root (e.g.
     // macOS /var -> /private/var) so relative-path math against events matches.
     const root = await realpath(opts.root);
+    const rootStat = await stat(root, { bigint: true });
+    const expected = opts.rootIdentity;
+    const replaced = (st) => expected !== undefined
+        && (st?.dev.toString() !== expected.dev || st.ino.toString() !== expected.ino);
+    if (replaced(rootStat)) {
+        throw new RootChangedError(`the workspace root ${root} was replaced; a directory recreated there is captured under a new session`);
+    }
+    // Validate the store before freezing anything, so a bad store directory fails
+    // without leaving a frozen copy of the ignore rules behind.
     await mkdirpDurable(opts.storeDir);
     const storeDir = await realpath(opts.storeDir);
     await assertOwnerOnly(storeDir, 'dir');
     if (isUnder(root, storeDir)) {
         throw new Error('store directory must not equal or contain the watched root');
     }
+    // Decided before anything is written: a git root git cannot read rejects here
+    // rather than silently capturing what git would not merge.
+    const baseScope = await deps.detectScope(root);
+    // Only a git work tree honors .slipstreamignore; a non-git root never reads it
+    // (so an unreadable file there does not block capture). Frozen before
+    // classification so a mid-capture edit does not change this capture's scope;
+    // cleaned up on a failed start, in the catches below, and in stop().
+    let frozenSlip;
+    let scope = baseScope;
+    if (baseScope.policy === 'git') {
+        try {
+            frozenSlip = await freezeSlipstreamIgnore(root);
+            if (frozenSlip)
+                scope = await deps.detectScope(root, frozenSlip.file);
+        }
+        catch (err) {
+            if (frozenSlip)
+                await rm(frozenSlip.dir, { recursive: true, force: true }).catch(() => { });
+            throw err;
+        }
+    }
+    const slipstreamApplied = frozenSlip !== undefined;
     const resuming = opts.resumeSessionId !== undefined;
+    const captureModeField = opts.captureMode ? { capture_mode: opts.captureMode } : {};
     const sessionId = opts.resumeSessionId ?? opts.sessionId ?? randomUUID();
     const blobsDir = join(storeDir, 'blobs');
     const sessionDir = join(storeDir, 'sessions', sessionId);
@@ -64,7 +136,7 @@ export async function startCapture(opts, dependencies = {}) {
     await mkdirpDurable(sessionDir);
     await assertOwnerOnly(sessionDir, 'dir'); // blobsDir perms are checked by createCas
     const logPath = join(sessionDir, 'events.jsonl');
-    const cas = await createCas(blobsDir);
+    const cas = opts.cas ?? await createCas(blobsDir);
     // Durable task boundaries (Stage 3). `currentTaskId` is the latest committed
     // declaration in shared append order — the grouping hint stamped onto changes.
     // The two maps are the idempotency index keyed by `request_id`: `committedTasks`
@@ -74,41 +146,96 @@ export async function startCapture(opts, dependencies = {}) {
     const committedQuestions = new Map();
     const inflightQuestions = new Map();
     const reservedQuestions = new Set();
-    // Questions not yet attempted. Removed once dispatch is attempted (durably
-    // consumed either way) so eligibility counting and claim lookup scan only
-    // outstanding questions, not every question ever queued by a long-lived capture.
-    const unattemptedQuestions = new Map();
+    // Exchanges are a separate namespace: they never queue, expire, count against
+    // QUESTION_LIMIT, or appear in the ask follow-up lookup.
+    const committedExchanges = new Map();
+    const inflightExchanges = new Map();
+    const exchangesById = new Map();
+    // relay_id -> question_id for every committed send. A relay_id is reserved while
+    // its append is in flight, so a concurrent reuse is refused before either lands.
+    const relayQuestions = new Map();
+    const reservedRelays = new Set();
+    const committedRelayUpdates = new Map();
+    const inflightRelayUpdates = new Map();
+    const sourceContext = (context) => ({
+        change_seq: context.change_seq,
+        path: context.path,
+        snapshot_sha256: context.snapshot_sha256,
+        line_start: context.line_start,
+        line_end: context.line_end,
+    });
+    // Questions a chat may claim. Removed once dispatch is attempted (durably
+    // consumed either way) or answered, so eligibility counting and claim lookup
+    // scan only outstanding questions, not every question ever queued by a
+    // long-lived capture. An unlink re-arms the unanswered ones for the next chat.
+    const claimableQuestions = new Map();
     // Kept for the capture's lifetime: a question stays answerable after it
-    // leaves the unattempted queue or passes its claim TTL.
+    // leaves the claimable queue or passes its claim TTL.
     const questionsById = new Map();
-    const attemptSeqs = new Map();
+    // Every chat a question was handed to, in attempt order.
+    const attemptsById = new Map();
+    let latestResumeSeq = 0n;
     const committedAnswers = new Map();
     const inflightAnswers = new Map();
     let currentTaskId;
     const committedTasks = new Map();
     const inflightTasks = new Map();
+    const pruneExpiredClaimableQuestions = () => {
+        const currentTime = now();
+        for (const [id, queued] of claimableQuestions) {
+            if (currentTime >= queued.data.expires_at_ms)
+                claimableQuestions.delete(id);
+        }
+    };
     // The attribution producer, constructed once the append path exists below. Its
     // `noteCommitted` is fed from the log's single in-order commit hook, so every
     // durably-committed change/evidence/policy reaches it exactly once, in order.
     let producer;
+    const noteAttempt = (event) => {
+        const id = event.data.question_id;
+        // An attempt written before attempts recorded their chat went to the queued target.
+        const target = event.data.target ?? questionsById.get(id).data.target;
+        const attempts = attemptsById.get(id) ?? [];
+        attempts.push({ target, seq: event.seq });
+        attemptsById.set(id, attempts);
+    };
     const seedTaskState = (rec) => {
         committedQuestions.clear();
-        unattemptedQuestions.clear();
+        claimableQuestions.clear();
+        questionsById.clear();
+        attemptsById.clear();
+        committedAnswers.clear();
+        latestResumeSeq = rec.resumeSeq;
         for (const event of rec.questions) {
             committedQuestions.set(event.data.request_id, { body: questionBody(event.data), result: questionResult(event) });
-            unattemptedQuestions.set(event.data.question_id, event);
+            questionsById.set(event.data.question_id, event);
+            // Questions queued before the latest resume stay history only (D2).
+            if (BigInt(event.seq) > rec.resumeSeq)
+                claimableQuestions.set(event.data.question_id, event);
         }
-        for (const event of rec.questionAttempts)
-            unattemptedQuestions.delete(event.data.question_id);
-        questionsById.clear();
-        attemptSeqs.clear();
-        committedAnswers.clear();
-        for (const event of rec.questions)
-            questionsById.set(event.data.question_id, event.data);
-        for (const event of rec.questionAttempts)
-            attemptSeqs.set(event.data.question_id, event.seq);
-        for (const event of rec.questionAnswers)
+        for (const event of rec.questionAttempts) {
+            noteAttempt(event);
+            if (BigInt(event.seq) > rec.unlinkSeq)
+                claimableQuestions.delete(event.data.question_id);
+        }
+        for (const event of rec.questionAnswers) {
             committedAnswers.set(event.data.question_id, { text: event.data.text, result: answerResult(event) });
+            claimableQuestions.delete(event.data.question_id);
+        }
+        pruneExpiredClaimableQuestions();
+        committedExchanges.clear();
+        exchangesById.clear();
+        for (const event of rec.questionExchanges) {
+            committedExchanges.set(event.data.request_id, { body: exchangeBody(event.data), result: exchangeResult(event) });
+            exchangesById.set(event.data.question_id, sourceContext(event.data.context));
+        }
+        relayQuestions.clear();
+        for (const [relayId, questionId] of rec.relayQuestions)
+            relayQuestions.set(relayId, questionId);
+        committedRelayUpdates.clear();
+        for (const event of rec.questionRelayUpdates) {
+            committedRelayUpdates.set(event.data.request_id, { body: relayUpdateBody(event.data), result: relayUpdateResult(event) });
+        }
         currentTaskId = rec.currentTaskId;
         committedTasks.clear();
         for (const [requestId, decl] of rec.taskDeclarations) {
@@ -137,22 +264,48 @@ export async function startCapture(opts, dependencies = {}) {
             };
         },
         onCommitted: (event) => {
+            // A resume or an unlinked chat leaves no current task (D1). A resume leaves no
+            // claimable questions (D2); an unlink hands every unanswered question queued
+            // since the latest resume to whichever chat is linked next.
+            if (event.type === 'slipstream.session.resumed.v1') {
+                currentTaskId = undefined;
+                latestResumeSeq = BigInt(event.seq);
+                claimableQuestions.clear();
+            }
+            if (event.type === 'slipstream.agent.unlinked.v1') {
+                currentTaskId = undefined;
+                // Rebuilt in queue order so claims stay oldest first.
+                claimableQuestions.clear();
+                for (const [id, queued] of questionsById) {
+                    if (BigInt(queued.seq) > latestResumeSeq && !committedAnswers.has(id))
+                        claimableQuestions.set(id, queued);
+                }
+                pruneExpiredClaimableQuestions();
+            }
             if (event.type === 'slipstream.task.started.v1')
                 currentTaskId = event.data.task_id;
             // Route every durable commit to attribution in the same total order.
             if (event.type === 'slipstream.question.queued.v1') {
-                unattemptedQuestions.set(event.data.question_id, event);
-                questionsById.set(event.data.question_id, event.data);
+                claimableQuestions.set(event.data.question_id, event);
+                questionsById.set(event.data.question_id, event);
             }
             if (event.type === 'slipstream.question.dispatch_attempted.v1') {
-                unattemptedQuestions.delete(event.data.question_id);
-                attemptSeqs.set(event.data.question_id, event.seq);
+                claimableQuestions.delete(event.data.question_id);
+                noteAttempt(event);
             }
             if (event.type === 'slipstream.question.answered.v1') {
                 committedAnswers.set(event.data.question_id, { text: event.data.text, result: answerResult(event) });
+                claimableQuestions.delete(event.data.question_id);
+            }
+            if (event.type === 'slipstream.question.exchange_recorded.v1') {
+                exchangesById.set(event.data.question_id, sourceContext(event.data.context));
+                if (event.data.relay)
+                    relayQuestions.set(event.data.relay.relay_id, event.data.question_id);
+            }
+            if (event.type === 'slipstream.question.relay_updated.v1' && event.data.update.kind === 'sent') {
+                relayQuestions.set(event.data.relay_id, event.data.question_id);
             }
-            if (event.type !== 'slipstream.question.queued.v1' && event.type !== 'slipstream.question.dispatch_attempted.v1'
-                && event.type !== 'slipstream.question.answered.v1')
+            if (isCoreEvent(event))
                 producer?.noteCommitted(event);
         },
     };
@@ -179,10 +332,22 @@ export async function startCapture(opts, dependencies = {}) {
         // duplicates seqs. Resuming existing history requires resumeSessionId. The
         // check runs while we hold the session lock so a concurrent caller cannot
         // create then release the same id between the check and log creation.
-        const logExists = await access(logPath).then(() => true, () => false);
-        if (logExists) {
+        // A log holding no complete record (a first start that failed before its
+        // `session.started` became durable) recorded nothing, so it starts afresh.
+        try {
+            const logExists = await access(logPath).then(() => true, () => false);
+            const unstarted = logExists && await finalRecord(logPath).then((r) => r === undefined, () => false);
+            if (unstarted)
+                await truncate(logPath, 0);
+            if (logExists && !unstarted) {
+                throw new Error(`cannot start a fresh session ${sessionId}: a log already exists at ${logPath}; use resumeSessionId to continue it`);
+            }
+        }
+        catch (err) {
             await lock.release();
-            throw new Error(`cannot start a fresh session ${sessionId}: a log already exists at ${logPath}; use resumeSessionId to continue it`);
+            if (frozenSlip)
+                await rm(frozenSlip.dir, { recursive: true, force: true }).catch(() => { });
+            throw err;
         }
     }
     let recovered;
@@ -203,6 +368,8 @@ export async function startCapture(opts, dependencies = {}) {
         }
         catch (err) {
             await lock.release(); // a failed resume must not leave the session locked
+            if (frozenSlip)
+                await rm(frozenSlip.dir, { recursive: true, force: true }).catch(() => { });
             throw err;
         }
     }
@@ -221,6 +388,8 @@ export async function startCapture(opts, dependencies = {}) {
     }
     catch (err) {
         await lock.release();
+        if (frozenSlip)
+            await rm(frozenSlip.dir, { recursive: true, force: true }).catch(() => { });
         throw err;
     }
     let stopped = false;
@@ -239,9 +408,12 @@ export async function startCapture(opts, dependencies = {}) {
     const enterFailing = (failure) => {
         if (surrendered)
             return; // ownership lost: do not fight the new owner
+        const newOutage = outageEpisodeId === undefined;
         outageEpisodeId ??= randomUUID();
         const alreadySupervising = supervising;
         health.markFailing(failure);
+        if (newOutage)
+            opts.onStorage?.('failing', failure);
         // Capture the loop's promise only when starting a fresh one, so `stop()` can
         // await the recovery in progress. runSupervisor sets `supervising` in its
         // synchronous prefix, so a concurrent kick sees it and no-ops.
@@ -301,36 +473,191 @@ export async function startCapture(opts, dependencies = {}) {
     const excluded = [storeDir, join(root, '.git')];
     const isExcluded = (abs) => excluded.some((e) => isUnder(abs, e));
     let live = false;
-    const buffer = [];
+    // Raw observations not yet handed to the engine. Under the git policy every
+    // observation waits here until git has classified it; otherwise only those
+    // arriving while capture is not live.
+    let buffer = [];
     const onObservation = (abs, observedAtMs) => {
         if (isExcluded(abs))
             return;
         const rel = relative(root, abs);
-        if (rel === '' || escapesBase(rel))
+        if (rel === '') {
+            void checkRoot();
+            return;
+        }
+        if (escapesBase(rel))
             return;
-        if (live)
+        if (live && scope.policy === 'filesystem') {
             engine.notify(rel, observedAtMs);
-        else
-            buffer.push([rel, observedAtMs]);
+            return;
+        }
+        buffer.push([rel, observedAtMs]);
+        pumpClassifier();
+    };
+    // Paths skipped because git ignores them. Each is also marked prior-unknown in
+    // the engine, so if one later comes into scope it is never reported as newly
+    // created. Only the shallowest skipped path is kept.
+    const ignoredPaths = new Set();
+    const markIgnored = (rel) => {
+        if (!addUnknownScope(rel, ignoredPaths))
+            return;
+        engine.markBaselineUnknown(rel);
+    };
+    // Whether the git filter is working, as last durably disclosed. Flipped only
+    // once the disclosing scope event is committed.
+    let scopeAvailable = true;
+    const scopeEvent = () => ({
+        type: 'slipstream.capture.scope.v1',
+        occurred_at_ms: Date.now(),
+        data: scope.policy === 'git'
+            ? (slipstreamApplied ? { policy: 'git', status: 'active', slipstream_ignore: 'active' } : { policy: 'git', status: 'active' })
+            : { policy: 'filesystem', status: 'active' },
+    });
+    const isRegularFile = (rel) => lstat(join(root, rel)).then((st) => st.isFile(), () => false);
+    // One serial loop asks git about everything buffered so far in a single call;
+    // observations arriving meanwhile go in the next round. It runs only while
+    // live: a round that finishes after capture stopped being live puts its batch
+    // back to be classified afresh when capture is live again.
+    let classifierRunning = false;
+    let classifierDone = Promise.resolve();
+    const pumpClassifier = () => {
+        if (scope.policy !== 'git' || classifierRunning || !live || buffer.length === 0)
+            return;
+        classifierRunning = true;
+        classifierDone = classifyLoop().catch((err) => {
+            console.error(`slipstream: git classification failed: ${err.message}`);
+        });
+    };
+    const classifyLoop = async () => {
+        if (scope.policy !== 'git')
+            return;
+        try {
+            while (live && buffer.length > 0) {
+                const batch = buffer.splice(0);
+                let ignored;
+                try {
+                    ignored = await scope.ignored([...new Set(batch.map(([rel]) => rel))]);
+                }
+                catch (err) {
+                    if (!live) {
+                        buffer = batch.concat(buffer); // no spread: a batch can exceed the argument limit
+                        return;
+                    }
+                    // Fail closed: never capture what might be ignored. The dropped paths'
+                    // prior state is now unknown, and the outage is disclosed once.
+                    console.error(`slipstream: git could not classify ${batch.length} observation(s): ${err.message}`);
+                    for (const [rel] of batch)
+                        engine.markBaselineUnknown(rel);
+                    if (scopeAvailable) {
+                        await appendEvent({
+                            type: 'slipstream.capture.scope.v1',
+                            occurred_at_ms: Date.now(),
+                            data: slipstreamApplied
+                                ? { policy: 'git', status: 'unavailable', slipstream_ignore: 'active' }
+                                : { policy: 'git', status: 'unavailable' },
+                        }).then(() => { scopeAvailable = false; }, () => { });
+                    }
+                    continue;
+                }
+                const forward = [];
+                for (const [rel, ts] of batch) {
+                    if (ignored.has(rel))
+                        markIgnored(rel);
+                    // An ignored directory is out of scope once deleted too, though git no
+                    // longer matches its vanished path. Directories are never captured. A
+                    // file forwarded here, or one captured before, is in scope, so its
+                    // deletion is captured.
+                    else if (!ignoredPaths.has(rel))
+                        forward.push([rel, ts]);
+                    else if (engine.isRecorded(rel) || await isRegularFile(rel)) {
+                        ignoredPaths.delete(rel);
+                        forward.push([rel, ts]);
+                    }
+                }
+                if (live && !scopeAvailable) {
+                    await appendEvent(scopeEvent()).then(() => { scopeAvailable = true; }, () => { });
+                }
+                if (!live || !scopeAvailable) {
+                    buffer = batch.concat(buffer); // no spread: a batch can exceed the argument limit
+                    return;
+                }
+                for (const [rel, ts] of forward)
+                    engine.notify(rel, ts);
+            }
+        }
+        finally {
+            classifierRunning = false;
+        }
+    };
+    // Walk the worktree, skipping what git ignores; skipped paths are marked
+    // prior-unknown. Ignored entries listed up front prune whole directories. A
+    // file created after that listing is caught by asking git about every file
+    // found before any is read.
+    const walk = async (handlers) => {
+        if (scope.policy !== 'git')
+            return deps.enumerate(root, root, isExcluded, handlers);
+        const entries = new Set(await scope.ignoredEntries());
+        for (const rel of entries)
+            markIgnored(rel);
+        const files = [];
+        await deps.enumerate(root, root, (abs) => isExcluded(abs) || entries.has(relative(root, abs)), {
+            onFile: async (rel) => { files.push(rel); },
+            onDirError: handlers.onDirError,
+        });
+        const ignored = await scope.ignored(files);
+        for (const rel of files) {
+            if (ignored.has(rel))
+                markIgnored(rel);
+            else
+                await handlers.onFile(rel);
+        }
     };
     // A native-watcher error means delivery may have lapsed; disclose an honest
     // session-wide coverage gap instead of letting the miss vanish silently.
+    const watcherGap = () => appendEvent({
+        type: 'slipstream.capture.gap.v1',
+        occurred_at_ms: Date.now(),
+        data: { scope: { kind: 'session' }, reason: 'watcher-error' },
+    }).catch(() => { });
     const onError = (err) => {
         console.error(`slipstream: watcher error: ${err.message}`);
-        void appendEvent({
-            type: 'slipstream.capture.gap.v1',
-            occurred_at_ms: Date.now(),
-            data: { scope: { kind: 'session' }, reason: 'watcher-error' },
-        }).catch(() => { });
+        if (terminal)
+            return;
+        void watcherGap();
+        void checkRoot();
     };
-    const priorFor = (path, unknownDirs) => {
-        for (const prefix of unknownDirs) {
-            if (prefix === '' || path === prefix || path.startsWith(prefix + sep)) {
-                return { kind: 'unavailable', reason: 'baseline-unknown' };
-            }
+    // The activation ends, once, when the root it watches is gone or the watcher
+    // can no longer deliver for it.
+    let terminal = false;
+    const end = (reason, message) => {
+        if (terminal || stopped)
+            return;
+        terminal = true;
+        opts.onTerminal?.(reason, message);
+    };
+    const checkRoot = async () => {
+        let now;
+        try {
+            now = await stat(root, { bigint: true });
         }
-        return { kind: 'absent' };
+        catch (err) {
+            const code = err.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                return false;
+        }
+        if (now?.isDirectory() && now.dev === rootStat.dev && now.ino === rootStat.ino)
+            return false;
+        end('root-missing', now ? `the workspace root ${root} was replaced` : `the workspace root ${root} no longer exists`);
+        return true;
     };
+    const onClosed = async (err) => {
+        console.error(`slipstream: watcher subscription closed: ${err.message}`);
+        if (terminal || stopped || await checkRoot())
+            return;
+        await watcherGap();
+        end('watcher-failed', `the watcher stopped delivering changes for ${root}: ${err.message}`);
+    };
+    const priorFor = (path, unknownDirs) => isUnderUnknownScope(path, unknownDirs) ? { kind: 'unavailable', reason: 'baseline-unknown' } : { kind: 'absent' };
     // Re-observe the whole worktree against the last committed snapshots and emit a
     // reconciliation change for every differing endpoint. Enumeration omission is
     // NOT deletion — a known path missing from the scan is actually re-read, so a
@@ -338,13 +665,25 @@ export async function startCapture(opts, dependencies = {}) {
     const reconcile = async (state, gapSeq, append) => {
         const current = new Map();
         const newUnknownDirs = new Set();
-        await deps.enumerate(root, root, isExcluded, {
+        await walk({
             onFile: async (rel) => { current.set(rel, await reader.read(rel)); },
             onDirError: async (relDir) => { newUnknownDirs.add(relDir); },
         });
         const unknownDirs = new Set([...state.baselineUnknownDirs, ...newUnknownDirs]);
+        // Under the git policy a path first seen now may have existed, ignored,
+        // while capture was down: its prior state is unknown, never absent.
+        if (scope.policy === 'git')
+            unknownDirs.add('');
+        // A recorded path the walk did not find is either gone or now ignored. An
+        // ignored one is out of scope: keep its last recorded state, never read it.
+        const unscanned = [...state.committed.keys()].filter((p) => !current.has(p));
+        const ignoredUnscanned = scope.policy === 'git' ? await scope.ignored(unscanned) : new Set();
         const union = new Set([...state.committed.keys(), ...current.keys()]);
         for (const path of union) {
+            if (ignoredUnscanned.has(path)) {
+                engine.setBaseline(path, state.committed.get(path));
+                continue;
+            }
             const after = current.get(path) ?? (await reader.read(path));
             const before = state.committed.get(path) ?? priorFor(path, unknownDirs);
             if (!snapshotsEqual(before, after)) {
@@ -369,7 +708,9 @@ export async function startCapture(opts, dependencies = {}) {
         // Install every unknown directory — recovered as well as newly-failed — so a
         // later live observation of a never-baselined path reports baseline-unknown
         // rather than a fabricated absent prior state.
-        for (const relDir of unknownDirs)
+        for (const relDir of state.baselineUnknownDirs)
+            engine.markBaselineUnknown(relDir);
+        for (const relDir of newUnknownDirs)
             engine.markBaselineUnknown(relDir);
     };
     const goLive = () => {
@@ -379,6 +720,10 @@ export async function startCapture(opts, dependencies = {}) {
         if (stopped)
             return;
         live = true;
+        if (scope.policy === 'git') {
+            pumpClassifier();
+            return;
+        }
         for (const [rel, ts] of buffer)
             engine.notify(rel, ts);
         buffer.length = 0;
@@ -468,6 +813,7 @@ export async function startCapture(opts, dependencies = {}) {
             goLive();
             health.markHealthy();
             outageEpisodeId = undefined; // outage resolved; a later fault opens a new episode
+            opts.onStorage?.('healthy');
             return true;
         }
         catch {
@@ -486,7 +832,14 @@ export async function startCapture(opts, dependencies = {}) {
     // scan is missed; buffered events reconcile against the baseline afterward.
     let subscription;
     try {
-        subscription = await deps.platform.watch({ root, ignore: excluded, onObservation, onError });
+        subscription = await deps.platform.watch({ root, ignore: excluded, onObservation, onError,
+            onClosed: (err) => { void onClosed(err); } });
+        // The root may have been swapped between its first stat and the watcher's
+        // install; nothing is written for a directory this session never watched.
+        const watched = await stat(root, { bigint: true }).catch(() => undefined);
+        if (!watched || watched.dev !== rootStat.dev || watched.ino !== rootStat.ino) {
+            throw new RootChangedError(watched ? `the workspace root ${root} was replaced` : `the workspace root ${root} no longer exists`);
+        }
         if (resuming) {
             // Replay barrier: rebuild the producer's projections and reconstruct
             // outstanding work from the durable log, seeding prior results so a
@@ -499,6 +852,7 @@ export async function startCapture(opts, dependencies = {}) {
                 data: {
                     recovered_through_seq: recovered.recoveredThroughSeq.toString(),
                     discarded_tail_bytes: recovered.discardedTailBytes,
+                    ...captureModeField,
                 },
             });
             const restartGap = await appendEvent({
@@ -506,6 +860,7 @@ export async function startCapture(opts, dependencies = {}) {
                 occurred_at_ms: Date.now(),
                 data: { scope: { kind: 'session' }, reason: 'restart' },
             });
+            await appendEvent(scopeEvent());
             await producer.ensurePolicy(enrichmentPolicy);
             await reconcile({
                 committed: recovered.committed,
@@ -516,10 +871,11 @@ export async function startCapture(opts, dependencies = {}) {
             await appendEvent({
                 type: 'slipstream.session.started.v1',
                 occurred_at_ms: Date.now(),
-                data: { root, max_bytes: maxBytes },
+                data: { root, max_bytes: maxBytes, ...captureModeField },
             });
+            await appendEvent(scopeEvent());
             const unknownScopes = [];
-            await deps.enumerate(root, root, isExcluded, {
+            await walk({
                 onFile: async (rel) => {
                     const snapshot = await reader.read(rel);
                     await appendEvent({
@@ -549,6 +905,8 @@ export async function startCapture(opts, dependencies = {}) {
             producer.start([]);
             await producer.ensurePolicy(enrichmentPolicy);
         }
+        // Every append above resolved durable, so the barrier has passed.
+        await appendEvent({ type: 'slipstream.capture.ready.v1', occurred_at_ms: Date.now(), data: {} });
     }
     catch (err) {
         // A failed startup may already have kicked the recovery supervisor (an append
@@ -562,35 +920,25 @@ export async function startCapture(opts, dependencies = {}) {
         await engine.drain().catch(() => { });
         await underlying.close().catch(() => { });
         await lock.release();
+        if (frozenSlip)
+            await rm(frozenSlip.dir, { recursive: true, force: true }).catch(() => { });
         throw err;
     }
     goLive();
     health.markHealthy();
     const ingestEvidence = (evidence) => producer.ingestEvidence(evidence);
-    // The transcript coverage watcher (A2): reads configured harnesses' transcripts
-    // for this worktree as revisable evidence. It never creates a change and its
-    // evidence flows through the same deduped, append-only producer path, so a
-    // re-read (including a late transcript after a restart) revises without
-    // duplicating. Runs only when a harness is actually configured.
-    let coverageRunner;
-    const tc = opts.transcript;
-    if (tc && tc.harnesses.length > 0) {
-        coverageRunner = createCoverageRunner({
-            harnesses: tc.harnesses,
-            homes: tc.homes,
-            codexScanLimit: tc.codexScanLimit,
-            root,
-            sink: { ingest: ingestEvidence },
-            publish: async (data) => {
-                await appendEvent({ type: 'slipstream.enrichment.coverage.v1', occurred_at_ms: Date.now(), data });
-            },
-            discoveryIO: tc.discoveryIO ?? nodeDiscoveryIO,
-            fileIO: tc.fileIO ?? nodeTranscriptFileIO,
-            intervalMs: tc.pollIntervalMs ?? DEFAULT_TRANSCRIPT_POLL_MS,
-            onError: (err) => console.error(`slipstream: transcript watcher error: ${err.message}`),
-        });
-        coverageRunner.start();
-    }
+    // Transcript reading (A2): configured harnesses' transcripts for this worktree
+    // are read as revisable evidence on the shared scheduler. It never creates a
+    // change and its evidence flows through the same deduped, append-only producer
+    // path, so a re-read (including a late transcript after a restart) revises
+    // without duplicating.
+    const unregisterTranscripts = opts.transcript?.register({
+        root,
+        sink: { ingest: ingestEvidence },
+        publish: async (data) => {
+            await appendEvent({ type: 'slipstream.enrichment.coverage.v1', occurred_at_ms: Date.now(), data });
+        },
+    });
     const beginTask = async ({ title, requestId }) => {
         // Readiness: only a live, healthy, still-owned session may declare a task.
         // Domain error codes (CAPTURE_NOT_READY, STORAGE_UNAVAILABLE, ...) are a later
@@ -684,10 +1032,7 @@ export async function startCapture(opts, dependencies = {}) {
         if (pending)
             return { ...await pending.promise, duplicate: true };
         if (req.reply_to_question_id !== undefined) {
-            const parent = questionsById.get(req.reply_to_question_id)?.context;
-            const c = req.context;
-            if (!parent || parent.change_seq !== c.change_seq || parent.path !== c.path || parent.snapshot_sha256 !== c.snapshot_sha256
-                || parent.line_start !== c.line_start || parent.line_end !== c.line_end) {
+            if (!sameSourceContext(questionsById.get(req.reply_to_question_id)?.data.context, req.context)) {
                 throw new QuestionError('INVALID_CONTEXT', 'a follow-up must reply to a question in this capture about the same source');
             }
         }
@@ -695,11 +1040,11 @@ export async function startCapture(opts, dependencies = {}) {
         // An expired-but-never-attempted entry can never become eligible again, so it
         // is dropped here rather than kept forever awaiting a claim that will not come.
         let eligible = 0;
-        for (const [id, q] of unattemptedQuestions) {
+        for (const [id, q] of claimableQuestions) {
             if (now() < q.data.expires_at_ms)
                 eligible += 1;
             else
-                unattemptedQuestions.delete(id);
+                claimableQuestions.delete(id);
         }
         const reserved = [...inflightQuestions.keys()].filter(id => !committedQuestions.has(id)).length;
         if (eligible + reserved >= QUESTION_LIMIT)
@@ -730,12 +1075,124 @@ export async function startCapture(opts, dependencies = {}) {
             inflightQuestions.delete(req.request_id);
         }
     };
+    // A committed send is registered by onCommitted (or rebuilt by recovery), so a
+    // reservation can be dropped once its append settles either way.
+    const isKnownRelay = (relayId) => relayQuestions.has(relayId) || reservedRelays.has(relayId);
+    const recordQuestionExchange = async (input, assertOwnership = () => { }) => {
+        const req = normalizeExchange(input);
+        if (req.session_id !== sessionId)
+            throw new QuestionError('SESSION_NOT_SELECTED', 'exchange addresses a different capture');
+        assertOwnership();
+        questionReady();
+        const body = exchangeBody(req);
+        const settled = committedExchanges.get(req.request_id);
+        const pending = inflightExchanges.get(req.request_id);
+        const existing = settled ?? pending;
+        if (existing && existing.body !== body)
+            throw new QuestionError('REQUEST_CONFLICT', 'request_id was used for a different exchange or context');
+        if (settled)
+            return { ...settled.result, duplicate: true };
+        if (pending)
+            return { ...await pending.promise, duplicate: true };
+        if (req.reply_to_question_id !== undefined
+            && !sameSourceContext(exchangesById.get(req.reply_to_question_id), req.context)) {
+            throw new QuestionError('INVALID_CONTEXT', 'a follow-up must reply to an exchange in this capture about the same source');
+        }
+        const relayId = req.relay?.relay_id;
+        if (relayId !== undefined && isKnownRelay(relayId))
+            throw new QuestionError('INVALID_RELAY_UPDATE', 'relay_id was already sent in this capture');
+        // Defer starting I/O until the in-flight reservation is installed synchronously.
+        const promise = Promise.resolve().then(async () => {
+            const selected_text = await deps.readQuestionContext({ storeDir, logPath, sessionId,
+                boundary: BigInt(health.snapshot().durable_seq), context: req.context });
+            assertOwnership();
+            questionReady();
+            const recorded_at_ms = now();
+            const event = await appendEvent({ type: 'slipstream.question.exchange_recorded.v1', occurred_at_ms: recorded_at_ms,
+                data: { question_id: randomUUID(), request_id: req.request_id, text: req.text,
+                    context: { ...req.context, selected_text }, answer_text: req.answer_text, recorded_at_ms,
+                    conversation: { ...req.conversation, reported_by: 'client' },
+                    ...(req.reply_to_question_id !== undefined ? { reply_to_question_id: req.reply_to_question_id } : {}),
+                    ...(req.relay !== undefined ? { relay: req.relay } : {}) } });
+            if (surrendered)
+                throw new StorageError('lock', Object.assign(new Error('session ownership lost'), { code: 'ELOCKLOST' }));
+            assertOwnership();
+            const result = exchangeResult(event);
+            committedExchanges.set(req.request_id, { body, result });
+            return result;
+        });
+        inflightExchanges.set(req.request_id, { body, promise });
+        if (relayId !== undefined)
+            reservedRelays.add(relayId);
+        try {
+            return await promise;
+        }
+        finally {
+            inflightExchanges.delete(req.request_id);
+            if (relayId !== undefined)
+                reservedRelays.delete(relayId);
+        }
+    };
+    const recordQuestionRelayUpdate = async (input, assertOwnership = () => { }) => {
+        const req = normalizeRelayUpdate(input);
+        if (req.session_id !== sessionId)
+            throw new QuestionError('SESSION_NOT_SELECTED', 'relay update addresses a different capture');
+        assertOwnership();
+        questionReady();
+        const body = relayUpdateBody(req);
+        const settled = committedRelayUpdates.get(req.request_id);
+        const pending = inflightRelayUpdates.get(req.request_id);
+        const existing = settled ?? pending;
+        if (existing && existing.body !== body)
+            throw new QuestionError('REQUEST_CONFLICT', 'request_id was used for a different relay update');
+        if (settled)
+            return { ...settled.result, duplicate: true };
+        if (pending)
+            return { ...await pending.promise, duplicate: true };
+        if (!exchangesById.has(req.question_id))
+            throw new QuestionError('INVALID_RELAY_UPDATE', 'question_id names no recorded exchange in this capture');
+        const isSend = req.update.kind === 'sent';
+        if (isSend && isKnownRelay(req.relay_id))
+            throw new QuestionError('INVALID_RELAY_UPDATE', 'relay_id was already sent in this capture');
+        if (!isSend) {
+            const owner = relayQuestions.get(req.relay_id);
+            if (owner === undefined)
+                throw new QuestionError('INVALID_RELAY_UPDATE', 'relay_id was never sent in this capture');
+            if (owner !== req.question_id)
+                throw new QuestionError('INVALID_RELAY_UPDATE', 'relay_id belongs to another question');
+        }
+        const promise = Promise.resolve().then(async () => {
+            assertOwnership();
+            questionReady();
+            const recorded_at_ms = now();
+            const event = await appendEvent({ type: 'slipstream.question.relay_updated.v1', occurred_at_ms: recorded_at_ms,
+                data: { question_id: req.question_id, relay_id: req.relay_id, request_id: req.request_id, update: req.update, recorded_at_ms } });
+            if (surrendered)
+                throw new StorageError('lock', Object.assign(new Error('session ownership lost'), { code: 'ELOCKLOST' }));
+            assertOwnership();
+            const result = relayUpdateResult(event);
+            committedRelayUpdates.set(req.request_id, { body, result });
+            return result;
+        });
+        inflightRelayUpdates.set(req.request_id, { body, promise });
+        if (isSend)
+            reservedRelays.add(req.relay_id);
+        try {
+            return await promise;
+        }
+        finally {
+            inflightRelayUpdates.delete(req.request_id);
+            if (isSend)
+                reservedRelays.delete(req.relay_id);
+        }
+    };
     const claimQuestion = async (target, assertOwnership = () => { }) => {
         assertOwnership();
         questionReady();
-        const queued = [...unattemptedQuestions.values()].find(q => q.data.target.harness === target.harness
-            && q.data.target.harness_session_id === target.harness_session_id
-            && q.data.target.worktree === target.worktree
+        pruneExpiredClaimableQuestions();
+        // The control handler admits only the linked chat, so a question queued for an
+        // earlier chat of this worktree is the current chat's to claim.
+        const queued = [...claimableQuestions.values()].find(q => q.data.target.worktree === target.worktree
             && now() < q.data.expires_at_ms
             && !reservedQuestions.has(q.data.question_id));
         if (!queued)
@@ -745,7 +1202,7 @@ export async function startCapture(opts, dependencies = {}) {
         try {
             const attempted_at_ms = now();
             await appendEvent({ type: 'slipstream.question.dispatch_attempted.v1', occurred_at_ms: attempted_at_ms,
-                data: { question_id: id, queued_seq: queued.seq, attempted_at_ms } });
+                data: { question_id: id, queued_seq: queued.seq, attempted_at_ms, target } });
             if (surrendered)
                 throw new StorageError('lock', Object.assign(new Error('session ownership lost'), { code: 'ELOCKLOST' }));
             assertOwnership();
@@ -756,18 +1213,18 @@ export async function startCapture(opts, dependencies = {}) {
         }
     };
     // Order: INVALID_ANSWER, then QUESTION_NOT_FOUND (which also hides questions
-    // dispatched to another harness session), then duplicate or ANSWER_CONFLICT.
+    // never dispatched to this harness session), then duplicate or ANSWER_CONFLICT.
     const answerQuestion = async (input, target, assertOwnership = () => { }) => {
         const { question_id: id, text } = input;
         assertAnswerText(text);
         assertOwnership();
         questionReady();
-        const owner = typeof id === 'string' ? questionsById.get(id)?.target : undefined;
-        const attemptSeq = typeof id === 'string' ? attemptSeqs.get(id) : undefined;
-        if (typeof id !== 'string' || !owner || attemptSeq === undefined || owner.harness !== target.harness
-            || owner.harness_session_id !== target.harness_session_id || owner.worktree !== target.worktree) {
+        const attempt = typeof id === 'string' ? attemptsById.get(id)?.findLast(a => a.target.harness === target.harness
+            && a.target.harness_session_id === target.harness_session_id && a.target.worktree === target.worktree) : undefined;
+        if (typeof id !== 'string' || attempt === undefined) {
             throw new QuestionError('QUESTION_NOT_FOUND', 'no question with that id was dispatched to this harness session');
         }
+        const attemptSeq = attempt.seq;
         const settled = committedAnswers.get(id);
         const pending = inflightAnswers.get(id);
         const existing = settled ?? pending;
@@ -794,22 +1251,40 @@ export async function startCapture(opts, dependencies = {}) {
             inflightAnswers.delete(id);
         }
     };
-    const doStop = async () => {
+    const recordAgent = async (input, assertOwnership = () => { }) => {
+        assertOwnership();
+        questionReady();
+        const event = await appendEvent(input);
+        if (input.type === 'slipstream.agent.binding.v1')
+            recordedBindings.add(input.data.binding_generation);
+        if (surrendered)
+            throw new StorageError('lock', Object.assign(new Error('session ownership lost'), { code: 'ELOCKLOST' }));
+        assertOwnership();
+        return event;
+    };
+    const recordedBindings = new Set(recovered?.bindingGenerations);
+    const doStop = async (opts) => {
         stopped = true;
         // Stop feeding the engine immediately: if the watcher unsubscribe below
         // rejects, late observations buffer instead of appending after the lock is
         // released. Every step is then best-effort so a single failure never skips
-        // closing the log or releasing the lock; the first error is rethrown.
-        live = false;
+        // closing the log or releasing the lock; the first error is rethrown. Under
+        // the git policy capture stays live until git has classified what the
+        // watcher already delivered, so stopping never drops an observed edit.
+        if (scope.policy === 'filesystem')
+            live = false;
         let firstError;
         const record = (err) => {
             if (firstError === undefined)
                 firstError = err;
         };
-        // Stop the coverage watcher before the producer and log close: it appends
+        // Stop transcript reading before the producer and log close: it appends
         // evidence and coverage through both, and an append after close would throw.
-        await coverageRunner?.stop().catch(record);
+        await unregisterTranscripts?.().catch(record);
         await subscription?.close().catch(record);
+        while (classifierRunning)
+            await classifierDone;
+        live = false;
         // Await any in-flight recovery: it may be mid-reopen, and appending after
         // we release the lock would let a second owner's writes interleave. The
         // loop stops starting new attempts once `stopped` is set.
@@ -818,9 +1293,30 @@ export async function startCapture(opts, dependencies = {}) {
         // Fence the attribution generation and flush its in-flight appends before the
         // log closes: a stale evaluation must never append after the log is gone.
         await producer?.stop().catch(record);
-        await Promise.allSettled([...inflightQuestions.values(), ...inflightAnswers.values()].map(q => q.promise));
+        await Promise.allSettled([...inflightQuestions.values(), ...inflightExchanges.values(), ...inflightRelayUpdates.values(), ...inflightAnswers.values()].map(q => q.promise));
+        // Never manufactured: after a lost lock or during a storage outage the stop
+        // stays unrecorded and stop() rejects, so no caller can report it stopped.
+        if (opts && firstError === undefined && (surrendered || health.snapshot().state !== 'healthy')) {
+            record(new Error(`the stop could not be recorded: capture storage is ${surrendered ? 'owned by another process' : health.snapshot().state}`));
+        }
+        else if (opts && firstError === undefined) {
+            try {
+                if (opts.unlinkGeneration !== undefined) {
+                    opts.assertOwnership?.();
+                    await appendEvent({ type: 'slipstream.agent.unlinked.v1', occurred_at_ms: now(),
+                        data: { binding_generation: opts.unlinkGeneration, reason: opts.reason } });
+                }
+                opts.assertOwnership?.();
+                await appendEvent({ type: 'slipstream.capture.stopped.v1', occurred_at_ms: now(), data: { reason: opts.reason } });
+            }
+            catch (err) {
+                record(err);
+            }
+        }
         await underlying.close().catch(record);
         await lock.release().catch(record);
+        if (frozenSlip)
+            await rm(frozenSlip.dir, { recursive: true, force: true }).catch(record);
         if (firstError !== undefined)
             throw firstError;
     };
@@ -835,10 +1331,14 @@ export async function startCapture(opts, dependencies = {}) {
         health,
         beginTask,
         askQuestion,
+        recordQuestionExchange,
+        recordQuestionRelayUpdate,
         claimQuestion,
         answerQuestion,
+        recordAgent,
+        bindingRecorded: (generation) => recordedBindings.has(generation),
         ingestEvidence,
-        stop: () => (stopPromise ??= doStop()),
+        stop: (opts) => (stopPromise ??= doStop(opts)),
     };
 }
 async function enumerate(root, dir, isExcluded, handlers) {