@playola-radio/slipstream 0.1.0 → 0.3.0

package/dist/boundary-registry.js

@@ -28,6 +28,12 @@ export function createBoundaryRegistry() {
         },
         freeze(id, seq) {
             transition(id, staticBoundary(seq));
+            delete entries.get(id).agentConnection;
+        },
+        setAgentConnection(id, state) {
+            const entry = entries.get(id);
+            if (entry)
+                entry.agentConnection = state;
         },
         get(id) {
             return entries.get(id);
@@ -45,3 +51,22 @@ export function createBoundaryRegistry() {
         },
     };
 }
+/** A session's boundary: the registry's if it knows the id, else the disk
+ * high-water. The registry is re-checked after the async disk read (and on its
+ * failure), so a boundary pinned meanwhile is never replaced by a stale read. */
+export async function resolveBoundary(registry, id, readDisk) {
+    const known = registry.get(id);
+    if (known)
+        return known.boundary;
+    let seq;
+    try {
+        seq = await readDisk();
+    }
+    catch (err) {
+        const late = registry.get(id);
+        if (late)
+            return late.boundary;
+        throw err;
+    }
+    return registry.get(id)?.boundary ?? staticBoundary(seq);
+}

package/dist/capture-intent.js

@@ -0,0 +1,70 @@
+/**
+ * The daemon's capture and binding intent, in the shape of the durable intent
+ * record (docs/autocapture/contracts.md §8), persisted by `intent-store.ts`.
+ * Every function here is a synchronous mutation, so a caller holding no await
+ * between its checks and the call gets the mutual exclusion the contract's
+ * mutex asks for; the caller then persists before it acknowledges.
+ */
+/** Capture slots (spec D10). A slot is any `running` intent, whatever its state. */
+export const MAX_CAPTURES = 32;
+/** Linked chats store-wide. */
+export const MAX_BINDINGS = 10;
+export function emptyIntent() {
+    return { version: 1, next_binding_generation: '1', captures: [], bindings: [] };
+}
+export function runningCount(record) {
+    return record.captures.filter((c) => c.intent === 'running').length;
+}
+export function linkedCount(record) {
+    return record.bindings.filter((b) => b.intent === 'linked').length;
+}
+export function findCapture(record, sessionId) {
+    return record.captures.find((c) => c.session_id === sessionId);
+}
+/** Admit a capture as `running`. The caller checks `runningCount < MAX_CAPTURES`
+ * with no await before this call. A prior entry for the same session (a
+ * re-attach after detach) is replaced. */
+export function admitCapture(record, entry) {
+    record.captures = record.captures.filter((c) => c.session_id !== entry.session_id);
+    const admitted = {
+        ...entry,
+        intent: 'running',
+        withdrawn_reason: null,
+        capture_mode: 'watch-only',
+        last_failure: null,
+    };
+    record.captures.push(admitted);
+    return admitted;
+}
+export function withdrawCapture(record, sessionId, reason) {
+    const entry = findCapture(record, sessionId);
+    if (!entry || entry.intent === 'withdrawn')
+        return;
+    entry.intent = 'withdrawn';
+    entry.withdrawn_reason = reason;
+}
+export function findLinked(record, harness, harnessSessionId) {
+    return record.bindings.find((b) => b.intent === 'linked' && b.harness === harness && b.harness_session_id === harnessSessionId);
+}
+export function linkedFor(record, sessionId) {
+    return record.bindings.find((b) => b.intent === 'linked' && b.session_id === sessionId);
+}
+/** Link a chat under a freshly allocated, never-reused generation. */
+export function linkBinding(record, entry) {
+    const generation = record.next_binding_generation;
+    record.next_binding_generation = (BigInt(generation) + 1n).toString();
+    const linked = { ...entry, binding_generation: generation, intent: 'linked', unavailable: null };
+    record.bindings.push(linked);
+    return linked;
+}
+export function revokeBinding(record, sessionId) {
+    const linked = linkedFor(record, sessionId);
+    if (linked)
+        linked.intent = 'revoked';
+    return linked;
+}
+/** Forget a deleted session's capture and binding entries. */
+export function forgetSession(record, sessionId) {
+    record.captures = record.captures.filter((c) => c.session_id !== sessionId);
+    record.bindings = record.bindings.filter((b) => b.session_id !== sessionId);
+}

package/dist/capture-scope.js

@@ -0,0 +1,135 @@
+import { spawn } from 'node:child_process';
+/** How long one git invocation may run before it counts as a failure. */
+export const GIT_TIMEOUT_MS = 10_000;
+export class GitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GitError';
+    }
+}
+function runGit(root, args, input, timeoutMs = GIT_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        // Its own process group, so a timeout also kills any helpers git starts
+        // that would otherwise hold the pipes open past the deadline.
+        const child = spawn('git', ['-c', 'core.fsmonitor=false', '-C', root, ...args], { stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        // Not spawn's own `timeout`: its timer outlives a failed spawn.
+        const timer = setTimeout(() => {
+            settle(() => reject(new GitError(`git ${args[0]} timed out after ${timeoutMs}ms`)));
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                child.kill('SIGKILL');
+            }
+            child.stdout.destroy();
+            child.stderr.destroy();
+        }, timeoutMs);
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (b) => out.push(b));
+        child.stderr.on('data', (b) => err.push(b));
+        child.stdin.on('error', () => { }); // a git that exits early closes stdin; the exit code reports it
+        child.on('error', (e) => {
+            settle(() => reject(new GitError(`git ${args[0]} could not run: ${e.message}`)));
+        });
+        child.on('close', (code, signal) => {
+            const stderr = Buffer.concat(err).toString('utf8').trim();
+            if (code === null) {
+                settle(() => reject(new GitError(`git ${args[0]} was killed (${signal ?? 'unknown signal'})${stderr ? `: ${stderr}` : ''}`)));
+                return;
+            }
+            settle(() => resolve({ code, stdout: Buffer.concat(out).toString('utf8'), stderr }));
+        });
+        child.stdin.end(input ?? '');
+    });
+}
+const splitNul = (s) => s.split('\0').filter((p) => p.length > 0);
+/** Git reports an ignore file it could not read only as a warning and still
+ * exits successfully, so its answer may be missing rules. Never trust it. */
+function rejectWarnings(command, r) {
+    if (r.stderr)
+        throw new GitError(`git ${command} warned: ${r.stderr}`);
+}
+/**
+ * The root-relative subset of `paths` the slipstream excludes file matches, and
+ * only those: git is asked with that file as its lowest-precedence excludes
+ * source, and `--verbose` lets us keep the paths whose winning rule is the file
+ * itself — never a path a higher-precedence git rule already ignores or keeps.
+ * `--no-index` so the file may exclude tracked paths too, which git never would.
+ */
+async function slipstreamMatched(root, slipExcludesFile, paths, timeoutMs) {
+    const r = await runGit(root, ['-c', `core.excludesFile=${slipExcludesFile}`, 'check-ignore', '--no-index', '-z', '--verbose', '--stdin'], paths.map((p) => `${p}\0`).join(''), timeoutMs);
+    if (r.code !== 0 && r.code !== 1)
+        throw new GitError(`git check-ignore exited ${r.code}: ${r.stderr}`);
+    rejectWarnings('check-ignore', r);
+    // -z --verbose emits repeating NUL-separated groups of (source, linenum,
+    // pattern, pathname), only for paths that match. Keep those whose source is
+    // the slipstream file, so a git rule's match is never miscredited to it. A
+    // negated pattern (`!keep.txt`) is listed as the winning match but un-ignores
+    // the path, so it must not be treated as an exclusion.
+    const fields = r.stdout.split('\0');
+    if (fields.at(-1) === '')
+        fields.pop();
+    const matched = [];
+    for (let i = 0; i + 3 < fields.length; i += 4) {
+        const pattern = fields[i + 2];
+        const path = fields[i + 3];
+        if (path !== undefined && fields[i] === slipExcludesFile && pattern !== undefined && !pattern.startsWith('!')) {
+            matched.push(path);
+        }
+    }
+    return matched;
+}
+export function gitCaptureScope(root, timeoutMs = GIT_TIMEOUT_MS, slipExcludesFile) {
+    return {
+        policy: 'git',
+        ignored: async (paths) => {
+            if (paths.length === 0)
+                return new Set();
+            const r = await runGit(root, ['check-ignore', '-z', '--stdin'], paths.map((p) => `${p}\0`).join(''), timeoutMs);
+            // 0: some paths ignored, 1: none ignored. Anything else is a failure, and
+            // partial output from a failed run is never trusted.
+            if (r.code !== 0 && r.code !== 1)
+                throw new GitError(`git check-ignore exited ${r.code}: ${r.stderr}`);
+            rejectWarnings('check-ignore', r);
+            const result = new Set(splitNul(r.stdout));
+            if (slipExcludesFile)
+                for (const p of await slipstreamMatched(root, slipExcludesFile, paths, timeoutMs))
+                    result.add(p);
+            return result;
+        },
+        ignoredEntries: async () => {
+            const r = await runGit(root, ['ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--directory'], undefined, timeoutMs);
+            if (r.code !== 0)
+                throw new GitError(`git ls-files exited ${r.code}: ${r.stderr}`);
+            rejectWarnings('ls-files', r);
+            return splitNul(r.stdout).map((p) => (p.endsWith('/') ? p.slice(0, -1) : p));
+        },
+    };
+}
+/**
+ * A root outside any git work tree captures everything (the pre-git behavior).
+ * A root inside one is filtered by git. Any other git failure — git missing,
+ * a repository git refuses to read — rejects: capture never silently widens
+ * to ignored files because git could not be asked.
+ */
+export async function detectCaptureScope(root, slipExcludesFile) {
+    const r = await runGit(root, ['rev-parse', '--is-inside-work-tree']);
+    if (r.code === 0 && r.stdout.trim() === 'true')
+        return gitCaptureScope(root, GIT_TIMEOUT_MS, slipExcludesFile);
+    if (r.code === 0 && r.stdout.trim() === 'false')
+        return { policy: 'filesystem' };
+    // Only git's search-found-nothing message. `not a git repository: '<dir>'`
+    // means an explicit GIT_DIR git cannot open, which is a failure.
+    if (r.code === 128 && /not a git repository \(or any/i.test(r.stderr))
+        return { policy: 'filesystem' };
+    throw new GitError(`cannot tell whether ${root} is a git work tree: git rev-parse exited ${r.code}: ${r.stderr}`);
+}

package/dist/cas.js

@@ -1,7 +1,17 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { access, open, mkdir, readFile, rename, unlink } from 'node:fs/promises';
+import { access, lstat, open, mkdir, readFile, rename, unlink } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { DIR_MODE, FILE_MODE, StorageError, assertOwnerOnly, fsyncDir, mkdirpDurable, writeAll, } from "./storage.js";
+/**
+ * When an on-disk blob can be trusted without rewriting it: the only way a file
+ * reaches its content address is a fully written, fsynced temp file renamed into
+ * place. Existing bytes are hash-checked once before reuse to detect damage. Only
+ * its directory entry might not be durable yet — so the shard (and base) are
+ * fsynced once by this instance, after the blob was seen, before it is trusted.
+ * That relies on one instance per store per process (the daemon shares one), and
+ * no other process writing the store concurrently (the daemon's store lock;
+ * standalone capture refuses a daemon-owned store).
+ */
 export async function createCas(rootDir) {
     const base = join(rootDir, 'sha256');
     await mkdirpDurable(base);
@@ -13,6 +23,9 @@ export async function createCas(rootDir) {
     const durableShards = new Set();
     /** In-flight publishes, keyed by sha, so concurrent same-hash puts share one write. */
     const inFlight = new Map();
+    /** shard dirs fsynced by this instance (with `base` before them), covering every entry present then. */
+    const syncedShards = new Map();
+    let baseSynced;
     const pathFor = (sha256) => join(base, sha256.slice(0, 2), sha256);
     const has = async (sha256) => {
         try {
@@ -23,6 +36,34 @@ export async function createCas(rootDir) {
             return false;
         }
     };
+    const syncShardOnce = (shard) => {
+        let pending = syncedShards.get(shard);
+        if (!pending) {
+            pending = (async () => {
+                baseSynced ??= fsyncDir(base);
+                await baseSynced;
+                await fsyncDir(shard);
+            })();
+            pending.catch(() => {
+                syncedShards.delete(shard);
+                baseSynced = undefined;
+            });
+            syncedShards.set(shard, pending);
+        }
+        return pending;
+    };
+    /** Size of the regular file at the blob's address, or undefined if there is none. */
+    const storedSize = async (sha256) => {
+        try {
+            const st = await lstat(pathFor(sha256));
+            return st.isFile() ? st.size : undefined;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return undefined;
+            throw new StorageError('stat-blob', err);
+        }
+    };
     const publish = async (sha256, bytes) => {
         const dest = pathFor(sha256);
         const shard = dirname(dest);
@@ -58,6 +99,11 @@ export async function createCas(rootDir) {
             }
             await fsyncDir(shard); // persist the rename into the shard directory
         }
+        catch (err) {
+            // An earlier sync of this shard no longer covers the entry that may have landed.
+            syncedShards.delete(shard);
+            throw err;
+        }
         finally {
             await unlink(tmp).catch(() => { });
         }
@@ -71,7 +117,17 @@ export async function createCas(rootDir) {
         const existing = inFlight.get(sha256);
         if (existing)
             return existing;
-        const pending = publish(sha256, bytes).finally(() => inFlight.delete(sha256));
+        const pending = (async () => {
+            if ((await storedSize(sha256)) === bytes.length
+                && createHash('sha256').update(await readFile(pathFor(sha256)).catch((err) => {
+                    throw new StorageError('read-blob', err);
+                })).digest('hex') === sha256) {
+                await syncShardOnce(dirname(pathFor(sha256)));
+                durable.add(sha256);
+                return { sha256, size: bytes.length };
+            }
+            return publish(sha256, bytes);
+        })().finally(() => inFlight.delete(sha256));
         inFlight.set(sha256, pending);
         return pending;
     };
@@ -79,19 +135,10 @@ export async function createCas(rootDir) {
     const ensureDurable = async (sha256) => {
         if (durable.has(sha256))
             return;
-        const dest = pathFor(sha256);
-        let handle;
-        try {
-            handle = await open(dest, 'r');
-            await handle.sync();
-        }
-        catch (err) {
-            throw new StorageError('fsync-blob', err);
-        }
-        finally {
-            await handle?.close();
+        if ((await storedSize(sha256)) === undefined) {
+            throw new StorageError('fsync-blob', Object.assign(new Error(`blob ${sha256} is missing`), { code: 'ENOENT' }));
         }
-        await fsyncDir(dirname(dest)); // persist the blob's shard entry
+        await syncShardOnce(dirname(pathFor(sha256)));
         durable.add(sha256);
     };
     return { put, read, has, ensureDurable, pathFor };

package/dist/claude-root-transcript.js

@@ -1,10 +1,7 @@
 import { constants } from 'node:fs';
 import { open, realpath } from 'node:fs/promises';
+import { isWithinRoot } from "./transcript/discovery.js";
 import { HEAD_LINE_CAP, HEAD_SCAN_BYTES, HEAD_SCAN_LINES } from "./transcript/fs-io.js";
-const RUNTIMES = new Map([
-    ['2.1.280', 'sdk-ts'], // Conductor's observed Claude Code launch
-    ['2.1.283', 'sdk-cli'], // Terminal's observed Claude Code launch
-]);
 const FATAL_UTF8 = new TextDecoder('utf8', { fatal: true });
 function record(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value)
@@ -16,6 +13,7 @@ function record(value) {
  * record, and may still be writing the last line while attach reads. Every
  * complete bounded line is parsed; the first identity record fixes the root
  * cwd and identity, while later records must not conflict with the binding.
+ * A later cwd may move inside the root (the chat ran `cd`) but not out of it.
  */
 export async function verifyClaudeRootTranscript(path, sessionId, worktree) {
     let handle;
@@ -62,15 +60,10 @@ export async function verifyClaudeRootTranscript(path, sessionId, worktree) {
             if (version === undefined) {
                 if (parsed.sessionId !== sessionId || typeof parsed.cwd !== 'string' || parsed.cwd.length === 0
                     || typeof parsed.version !== 'string' || parsed.version.length === 0
-                    || typeof parsed.entrypoint !== 'string' || parsed.userType !== 'external'
+                    || typeof parsed.entrypoint !== 'string' || parsed.entrypoint.length === 0 || parsed.userType !== 'external'
                     || parsed.isSidechain !== false || (parsed.type !== 'user' && parsed.type !== 'attachment')) {
                     return { ok: false, reason: 'mismatch' };
                 }
-                const allowedEntrypoint = RUNTIMES.get(parsed.version);
-                if (allowedEntrypoint === undefined)
-                    return { ok: false, reason: 'unsupported-version' };
-                if (parsed.entrypoint !== allowedEntrypoint)
-                    return { ok: false, reason: 'mismatch' };
                 try {
                     if (await realpath(parsed.cwd) !== worktree)
                         return { ok: false, reason: 'mismatch' };
@@ -84,11 +77,25 @@ export async function verifyClaudeRootTranscript(path, sessionId, worktree) {
             }
             else if ((Object.hasOwn(parsed, 'version') && parsed.version !== version)
                 || (Object.hasOwn(parsed, 'entrypoint') && parsed.entrypoint !== entrypoint)
-                || (Object.hasOwn(parsed, 'cwd') && parsed.cwd !== rootCwd)
                 || (Object.hasOwn(parsed, 'userType') && parsed.userType !== 'external')
                 || (Object.hasOwn(parsed, 'isSidechain') && parsed.isSidechain !== false)) {
                 return { ok: false, reason: 'mismatch' };
             }
+            else if (Object.hasOwn(parsed, 'cwd')) {
+                if (typeof parsed.cwd !== 'string')
+                    return { ok: false, reason: 'mismatch' };
+                if (parsed.cwd !== rootCwd) {
+                    let cwd;
+                    try {
+                        cwd = await realpath(parsed.cwd);
+                    }
+                    catch {
+                        return { ok: false, reason: 'mismatch' };
+                    }
+                    if (!isWithinRoot(worktree, cwd))
+                        return { ok: false, reason: 'mismatch' };
+                }
+            }
         }
         if (lines < HEAD_SCAN_LINES && total > HEAD_SCAN_BYTES)
             return { ok: false, reason: 'gap' };