@playola-radio/slipstream 0.1.0 → 0.3.0

package/dist/engine.js

@@ -1,5 +1,27 @@
 import { sep } from 'node:path';
 import { snapshotsEqual } from "./snapshot.js";
+/** Whether `path` equals or sits under one of `scopes` (`''` covers every path).
+ * Walks the path's ancestors, so the cost is its depth, not the scope count. */
+export function isUnderUnknownScope(path, scopes) {
+    if (scopes.has(''))
+        return true;
+    for (let p = path;;) {
+        if (scopes.has(p))
+            return true;
+        const i = p.lastIndexOf(sep);
+        if (i < 0)
+            return false;
+        p = p.slice(0, i);
+    }
+}
+/** Add an unknown scope unless an existing one already covers it. Descendants
+ * added earlier are kept: pruning them costs a scan of every scope per add. */
+export function addUnknownScope(scope, scopes) {
+    if (isUnderUnknownScope(scope, scopes))
+        return false;
+    scopes.add(scope);
+    return true;
+}
 /**
  * Per-path serialized capture. Each path compares the freshly-read snapshot
  * against the *last committed* snapshot — never against whatever is on disk
@@ -18,19 +40,13 @@ export function createEngine({ reader, log, now = Date.now }) {
         committed.set(path, snapshot);
     };
     const markBaselineUnknown = (relDir) => {
-        baselineUnknown.add(relDir);
+        addUnknownScope(relDir, baselineUnknown);
     };
+    const isRecorded = (path) => committed.has(path);
     // The prior state of a path we never baselined is honestly unknown when its
     // directory could not be scanned; elsewhere, no baseline means it did not
     // exist yet.
-    const priorFor = (path) => {
-        for (const prefix of baselineUnknown) {
-            if (prefix === '' || path === prefix || path.startsWith(prefix + sep)) {
-                return { kind: 'unavailable', reason: 'baseline-unknown' };
-            }
-        }
-        return { kind: 'absent' };
-    };
+    const priorFor = (path) => isUnderUnknownScope(path, baselineUnknown) ? { kind: 'unavailable', reason: 'baseline-unknown' } : { kind: 'absent' };
     const notify = (path, observedAtMs) => {
         const prior = pending.get(path);
         pending.set(path, prior === undefined ? observedAtMs : Math.min(prior, observedAtMs));
@@ -108,5 +124,5 @@ export function createEngine({ reader, log, now = Date.now }) {
         pending.clear();
         coalesced.clear();
     };
-    return { setBaseline, markBaselineUnknown, notify, drain, resetNotifications };
+    return { setBaseline, markBaselineUnknown, isRecorded, notify, drain, resetNotifications };
 }

package/dist/ensure-daemon.js

@@ -0,0 +1,30 @@
+/**
+ * Make sure a daemon serves a store, starting one if none answers. Shared by
+ * chat attach and the Conductor setup script. A live daemon is always kept,
+ * whatever configuration it was started with.
+ */
+export class DaemonUnavailableError extends Error {
+}
+const DAEMON_START_MS = 10_000;
+export async function ensureDaemon(store, deps) {
+    const verdict = await deps.probe();
+    if (verdict === 'live')
+        return;
+    if (verdict === 'ambiguous') {
+        throw new DaemonUnavailableError(`the daemon for ${store} is not answering; run \`slipstream status --store ${store}\`. `
+            + 'Nothing was recorded.');
+    }
+    const child = deps.startDaemon();
+    let exited;
+    void child.exited.then((code) => { exited = code; });
+    const deadline = Date.now() + DAEMON_START_MS;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, deps.pollIntervalMs ?? 100));
+        if (await deps.probe() === 'live')
+            return;
+        if (exited !== undefined)
+            break;
+    }
+    const why = deps.logPath ? `See ${deps.logPath} for why` : `Run \`slipstream start --store ${store}\` in a terminal to see why`;
+    throw new DaemonUnavailableError(`the Slipstream daemon did not start. ${why}. Nothing was recorded.`);
+}

package/dist/http-reader.js

@@ -7,8 +7,8 @@ import { parseCursor, openLogCursor, LogCorruptError } from "./log-reader.js";
 import { parseClipSnapshot } from "./clip-blob-reader.js";
 import { createClipProjectionService } from "./clip-projection-service.js";
 import { languageForPath } from "./clip-language.js";
-import { liveBoundary, staticBoundary } from "./reader-runtime.js";
-import { createBoundaryRegistry } from "./boundary-registry.js";
+import { liveBoundary } from "./reader-runtime.js";
+import { createBoundaryRegistry, resolveBoundary } from "./boundary-registry.js";
 import { DISPLAY_FOLD_CONTRACT } from "./display-fold.js";
 import { createProjectionAdmission, PROVISIONAL_SHARED_ADMISSION } from "./projection-admission.js";
 import { createInterfaceService } from "./interface-service.js";
@@ -60,9 +60,11 @@ export async function startReaderServer(opts) {
     // One resolution path for boundaries. In standalone `serve` mode the caller's
     // `active` session becomes a one-entry registry with a live boundary, so the
     // rest of the server never special-cases it. The daemon passes its own registry.
+    // `serve` never binds an agent chat, so its live capture reports no agent.
     const registry = opts.registry ?? createBoundaryRegistry();
     if (opts.active && !opts.registry) {
         registry.installIfAbsent(opts.active.id, liveBoundary(opts.active.health));
+        registry.setAgentConnection(opts.active.id, 'none');
     }
     // The clip projection is computed on demand from the immutable blobs and cached
     // disposably (no log, no persistence). The service owns the worker pool + bounded
@@ -127,6 +129,14 @@ export async function startReaderServer(opts) {
             return;
         }
         const { pathname, searchParams } = new URL(req.url ?? '/', url);
+        if (pathname === '/v1/captures') {
+            if (!opts.captures) {
+                send(res, 404, 'not found');
+                return;
+            }
+            sendJson(res, 200, await opts.captures());
+            return;
+        }
         if (pathname === '/v1/sessions') {
             const sessions = await listSessions(opts.storeDir);
             // A registry-known session's authoritative durable high-water is its
@@ -140,7 +150,12 @@ export async function startReaderServer(opts) {
                 // disk for every session it knows (see the reserved/active-window note).
                 const runtime = registry.get(s.id);
                 const durableSeq = s.removed ? 0n : (runtime ? runtime.boundary.current() : s.durableSeq);
-                return { id: s.id, durable_seq: durableSeq.toString(), removed: s.removed };
+                // Readiness is a property of a live capture only: a retained or removed
+                // session has no agent connection, whatever its log last recorded.
+                const agent = s.removed ? undefined : runtime?.agentConnection;
+                const agentConnection = agent === undefined ? { state: 'disconnected', reason: 'capture_not_live' }
+                    : agent === 'none' ? { state: 'disconnected', reason: 'no_agent' } : { state: agent };
+                return { id: s.id, durable_seq: durableSeq.toString(), removed: s.removed, agent_connection: agentConnection };
             }));
             return;
         }
@@ -241,7 +256,7 @@ export async function startReaderServer(opts) {
                 send(res, 400, 'invalid type');
                 return;
             }
-            if (!/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/.test(type)) {
+            if (!/^[a-z][a-z0-9_]*(?:[.-][a-z0-9_]+)*$/.test(type)) {
                 send(res, 400, 'invalid type');
                 return;
             }
@@ -259,10 +274,7 @@ export async function startReaderServer(opts) {
         // The registry is authoritative for every session the daemon has touched
         // this run. Disk high-water is the fallback ONLY for daemon-unknown sessions
         // (retained from a prior run, immutable now) — never for one mid-write.
-        const runtime = registry.get(id);
-        if (runtime)
-            return runtime.boundary;
-        return staticBoundary(await onDiskHighWater(sessionLogPath(opts.storeDir, id)));
+        return resolveBoundary(registry, id, () => onDiskHighWater(sessionLogPath(opts.storeDir, id)));
     }
     async function handleClips(res, id, seqStr, traceRouteKey) {
         if (!isValidSessionId(id)) {

package/dist/intent-store.js

@@ -0,0 +1,196 @@
+import { randomUUID } from 'node:crypto';
+import { open, readFile, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { acquireSessionLock } from "./lock.js";
+import { emptyIntent, revokeBinding, withdrawCapture, } from "./capture-intent.js";
+import { FILE_MODE, StorageError, assertOwnerOnly, fsyncDir, mkdirpDurable, writeAll } from "./storage.js";
+/**
+ * The durable intent record, `<store>/control/intent.json` (contracts.md §8). It
+ * is control intent, never evidence that capture happened. Every write is
+ * write-temp, fsync, rename, fsync directory, and completes before the
+ * acknowledgement it backs.
+ */
+export function intentPath(storeDir) {
+    return join(storeDir, 'control', 'intent.json');
+}
+/** The record exists but is not a version-1 intent record. The daemon refuses to
+ * start rather than reset it: a reset would silently forget withdrawals. */
+/** Nothing is recorded for a withdrawal's target. */
+export class NoCaptureError extends Error {
+}
+export class IntentCorruptError extends Error {
+    constructor(path, detail) {
+        super(`the capture intent record ${path} is unreadable (${detail}). Slipstream will not guess what to resume; `
+            + 'move the file aside to start with no recorded captures.');
+        this.name = 'IntentCorruptError';
+    }
+}
+export async function loadIntent(storeDir) {
+    const path = intentPath(storeDir);
+    let text;
+    try {
+        await assertOwnerOnly(path, 'file');
+        text = await readFile(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return emptyIntent();
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new IntentCorruptError(path, 'not JSON');
+    }
+    readLegacyWaitingAsPaused(parsed);
+    const problem = intentProblem(parsed);
+    if (problem)
+        throw new IntentCorruptError(path, problem);
+    return parsed;
+}
+/** An older daemon queued captures as `waiting`; they load as paused. Nothing is
+ * written here; the next ordinary save persists the new form. */
+function readLegacyWaitingAsPaused(parsed) {
+    if (!isObject(parsed) || !Array.isArray(parsed.captures))
+        return;
+    for (const c of parsed.captures) {
+        if (isObject(c) && c.intent === 'waiting')
+            Object.assign(c, { intent: 'withdrawn', withdrawn_reason: 'detached', last_failure: null });
+    }
+}
+export async function saveIntent(storeDir, record) {
+    const dir = join(storeDir, 'control');
+    const path = intentPath(storeDir);
+    const tmp = `${path}.${randomUUID()}.tmp`;
+    await mkdirpDurable(dir);
+    try {
+        const handle = await open(tmp, 'wx', FILE_MODE);
+        try {
+            await writeAll(handle, Buffer.from(JSON.stringify(record, null, 2) + '\n', 'utf8'));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(tmp, path);
+    }
+    catch (err) {
+        await unlink(tmp).catch(() => { });
+        throw err instanceof StorageError ? err : new StorageError(`write(${path})`, err);
+    }
+    await fsyncDir(dir);
+}
+/**
+ * Withdraw capture intent while no daemon runs (contracts.md §8): under the store
+ * lock, so a daemon starting concurrently either sees this write or holds the
+ * lock first and refuses it (`SessionOwnedError`). `target` is a session id or a
+ * canonical root; a root withdraws every entry recorded at it. No session log is
+ * touched: the capture is not running, so nothing is stopped and no
+ * `capture.stopped` is written or backfilled.
+ */
+export async function withdrawOffline(storeDir, target, reason) {
+    const lock = await acquireSessionLock(storeDir);
+    try {
+        const record = await loadIntent(storeDir);
+        const entries = 'sessionId' in target
+            ? record.captures.filter((c) => c.session_id === target.sessionId)
+            : record.captures.filter((c) => c.root === target.root);
+        const result = { withdrawn: [] };
+        for (const entry of entries) {
+            if (entry.intent === 'withdrawn')
+                continue;
+            withdrawCapture(record, entry.session_id, reason);
+            revokeBinding(record, entry.session_id);
+            result.withdrawn.push(entry.session_id);
+        }
+        if (entries.length === 0) {
+            throw new NoCaptureError(`no capture is recorded for ${'sessionId' in target ? target.sessionId : target.root}`);
+        }
+        if (result.withdrawn.length > 0)
+            await saveIntent(storeDir, record);
+        return result;
+    }
+    finally {
+        await lock.release();
+    }
+}
+/** Revoke a capture's linked binding while no daemon runs; false when none is linked. */
+export async function unlinkOffline(storeDir, sessionId) {
+    const lock = await acquireSessionLock(storeDir);
+    try {
+        const record = await loadIntent(storeDir);
+        if (!revokeBinding(record, sessionId))
+            return false;
+        await saveIntent(storeDir, record);
+        return true;
+    }
+    finally {
+        await lock.release();
+    }
+}
+const isString = (v) => typeof v === 'string';
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isDecimal = (v) => isString(v) && /^(0|[1-9][0-9]*)$/.test(v);
+function captureProblem(c, i) {
+    if (!isObject(c))
+        return `captures[${i}] is not an object`;
+    const e = c;
+    if (!isString(e.session_id) || !isString(e.root))
+        return `captures[${i}] lacks a session id or root`;
+    if (e.root_identity !== null && !(isObject(e.root_identity) && isDecimal(e.root_identity.dev) && isDecimal(e.root_identity.ino))) {
+        return `captures[${i}].root_identity is malformed`;
+    }
+    if (!['running', 'withdrawn'].includes(e.intent))
+        return `captures[${i}].intent is unknown`;
+    if (![null, 'detached', 'archived'].includes(e.withdrawn_reason))
+        return `captures[${i}].withdrawn_reason is unknown`;
+    if (e.capture_mode !== 'watch-only')
+        return `captures[${i}].capture_mode is unknown`;
+    const f = e.last_failure;
+    if (f !== null && !(isObject(f) && isString(f.reason) && isString(f.message) && typeof f.at_ms === 'number'
+        && (f.next_attempt_at_ms === null || typeof f.next_attempt_at_ms === 'number'))) {
+        return `captures[${i}].last_failure is malformed`;
+    }
+    return null;
+}
+function bindingProblem(b, i) {
+    if (!isObject(b))
+        return `bindings[${i}] is not an object`;
+    const e = b;
+    if (![e.session_id, e.harness_session_id, e.canonical_worktree, e.verified_transcript_path].every(isString)) {
+        return `bindings[${i}] lacks an identity field`;
+    }
+    if (e.harness !== 'claude-code' && e.harness !== 'codex')
+        return `bindings[${i}].harness is unknown`;
+    if (!isDecimal(e.binding_generation))
+        return `bindings[${i}].binding_generation is malformed`;
+    if (e.intent !== 'linked' && e.intent !== 'revoked')
+        return `bindings[${i}].intent is unknown`;
+    const u = e.unavailable;
+    if (u !== null && !(isObject(u) && isString(u.reason) && isString(u.message)))
+        return `bindings[${i}].unavailable is malformed`;
+    return null;
+}
+function intentProblem(v) {
+    if (!isObject(v))
+        return 'not an object';
+    if (v.version !== 1)
+        return `unsupported version ${JSON.stringify(v.version)}`;
+    if (!isDecimal(v.next_binding_generation))
+        return 'next_binding_generation is malformed';
+    if (!Array.isArray(v.captures) || !Array.isArray(v.bindings))
+        return 'captures or bindings is not a list';
+    for (const [i, c] of v.captures.entries()) {
+        const problem = captureProblem(c, i);
+        if (problem)
+            return problem;
+    }
+    for (const [i, b] of v.bindings.entries()) {
+        const problem = bindingProblem(b, i);
+        if (problem)
+            return problem;
+    }
+    return null;
+}

package/dist/interface-range-resolver.js

@@ -7,6 +7,7 @@ const BASELINED = 'slipstream.file.baselined.v1';
 const CHANGED = 'slipstream.file.changed.v1';
 const COMPLETED = 'slipstream.capture.baseline.completed.v1';
 const GAP = 'slipstream.capture.gap.v1';
+const SCOPE = 'slipstream.capture.scope.v1';
 const SHA = /^[0-9a-f]{64}$/;
 const SEQ = /^[1-9][0-9]*$/;
 const POLICY_EXCLUSIONS = ['store-directory', '.git', 'symlinks'];
@@ -113,6 +114,8 @@ export async function resolveRecordedRange(options) {
     const gaps = [];
     let baselineCompletedSeq = null;
     let unknownScopes = [];
+    let gitScoped = false;
+    let slipstreamScoped = false;
     let lastSeq = 0n;
     const cursor = await openLogCursor(logPath, 0n);
     try {
@@ -209,6 +212,25 @@ export async function resolveRecordedRange(options) {
         else if (record.type === GAP) {
             gaps.push(checkGap(data, seq));
         }
+        else if (record.type === SCOPE) {
+            const valid = (data.policy === 'git' && (data.status === 'active' || data.status === 'unavailable'))
+                || (data.policy === 'filesystem' && data.status === 'active');
+            // Under the git policy the event schema pins slipstream_ignore to the
+            // literal "active", so reject any other present value here too — otherwise
+            // this reader would silently drop the disclosure for history the schema
+            // and recovery reader reject. Other policies tolerate unknown fields, as
+            // the schema does for forward compatibility.
+            const slipOk = data.policy !== 'git'
+                || data.slipstream_ignore === undefined || data.slipstream_ignore === 'active';
+            if (!valid || !slipOk)
+                corrupt(`bad capture scope at ${seq}`);
+            if (data.policy === 'git')
+                gitScoped = true;
+            if (data.policy === 'git' && data.slipstream_ignore === 'active')
+                slipstreamScoped = true;
+            if (data.status === 'unavailable')
+                gaps.push({ seq, reason: 'capture-scope-unavailable', scope: { kind: 'session' } });
+        }
     }
     const files = [];
     for (const [path, state] of states) {
@@ -225,6 +247,11 @@ export async function resolveRecordedRange(options) {
         files.push({ path, before, after, endpointsEqual: endpointsEqual(before, after) });
     }
     files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const policyExclusions = [...POLICY_EXCLUSIONS];
+    if (gitScoped)
+        policyExclusions.push('git-ignored');
+    if (slipstreamScoped)
+        policyExclusions.push('slipstream-ignored');
     return { kind: 'resolved', inventory: { scope: 'observed', baselineCompletedSeq, unknownScopes,
-            policyExclusions: POLICY_EXCLUSIONS }, gaps, files, scan: scan() };
+            policyExclusions }, gaps, files, scan: scan() };
 }

package/dist/launch-agent.js

@@ -0,0 +1,179 @@
+/**
+ * The managed install: a user LaunchAgent that restarts the daemon after a crash
+ * or a login, plus a record of the absolute Node and `slipstream` entry paths it
+ * and the Conductor scripts use. Nothing here sources nvm or depends on an
+ * interactive shell; re-running the install after a Node or package upgrade
+ * rewrites every recorded path together.
+ */
+import { mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { assertOwnerOnly, mkdirpDurable } from "./storage.js";
+import { acquireSessionLock, SessionOwnedError } from "./lock.js";
+export const LAUNCH_AGENT_LABEL = 'radio.playola.slipstream';
+/** git is on it, for the daemon's ignore-rule checks. */
+export const DAEMON_PATH = '/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin:/usr/local/bin';
+const SHUTDOWN_WAIT_MS = 2_000;
+const SHUTDOWN_POLL_MS = 50;
+export class InstallError extends Error {
+}
+/** The running Node and `slipstream` entry, validated for recording. */
+export async function entryPaths(execPath, nodeVersion, cliPath) {
+    const major = Number(nodeVersion.split('.')[0]);
+    if (!isAbsolute(execPath))
+        throw new InstallError(`Node's path ${execPath} is not absolute`);
+    if (!(major >= 24))
+        throw new InstallError(`Slipstream needs Node 24 or later; this is Node ${nodeVersion} at ${execPath}`);
+    if (!isAbsolute(cliPath) || !(await stat(cliPath).catch(() => null))?.isFile()) {
+        throw new InstallError(`the slipstream entry ${cliPath} is not a file`);
+    }
+    return { node: execPath, cli: cliPath };
+}
+export function plistPath(home) {
+    return join(home, 'Library', 'LaunchAgents', `${LAUNCH_AGENT_LABEL}.plist`);
+}
+export function daemonLogPath(home) {
+    return join(home, 'Library', 'Logs', 'slipstream', 'daemon.log');
+}
+export function manifestPath(store) {
+    return join(store, 'control', 'install.json');
+}
+function xml(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+export function renderPlist(o) {
+    const args = [o.node, o.cli, 'start', '--store', o.store].map((a) => `    <string>${xml(a)}</string>`).join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCH_AGENT_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${DAEMON_PATH}</string>
+  </dict>
+  <key>WorkingDirectory</key>
+  <string>${xml(o.home)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${xml(o.log)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(o.log)}</string>
+</dict>
+</plist>
+`;
+}
+async function writeAtomic(path, text, mode) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(tmp, text, { mode, flag: 'wx' });
+        await rename(tmp, path);
+    }
+    catch (err) {
+        await unlink(tmp).catch(() => { });
+        throw err;
+    }
+}
+export async function readManagedInstall(store) {
+    let text;
+    try {
+        text = await readFile(manifestPath(store), 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    const parsed = JSON.parse(text);
+    if (parsed?.version !== 1 || !Array.isArray(parsed.repos))
+        throw new InstallError(`${manifestPath(store)} is not a Slipstream install record`);
+    return parsed;
+}
+export async function writeManagedInstall(store, install) {
+    const control = dirname(manifestPath(store));
+    await mkdirpDurable(control);
+    await assertOwnerOnly(store, 'dir');
+    await assertOwnerOnly(control, 'dir');
+    await writeAtomic(manifestPath(store), JSON.stringify(install, null, 2) + '\n', 0o600);
+}
+/** Write the LaunchAgent for these paths and make sure launchd runs it. A plist
+ * whose paths changed is reloaded, which restarts the daemon on the new ones;
+ * an unchanged, loaded one is left alone unless `restart` asks for the daemon to
+ * be restarted on new code at the same paths. */
+export async function installLaunchAgent(o, run) {
+    const plist = plistPath(o.home);
+    const log = daemonLogPath(o.home);
+    const text = renderPlist({ ...o, log });
+    const current = await readFile(plist, 'utf8').catch(() => null);
+    if (current !== null && current !== text) {
+        const store = current.match(/<string>--store<\/string>\s*<string>([^<]+)<\/string>/)?.[1];
+        if (store !== undefined && store !== xml(o.store)) {
+            throw new InstallError('a managed Slipstream daemon already belongs to another store; stop and remove that install before choosing a different store');
+        }
+    }
+    const domain = `gui/${o.uid}`;
+    await mkdir(dirname(log), { recursive: true });
+    if (current === text && (await run('launchctl', ['print', `${domain}/${LAUNCH_AGENT_LABEL}`])).code === 0) {
+        if (!o.restart)
+            return { plist, log, reloaded: false };
+        const restarted = await run('launchctl', ['kickstart', '-k', `${domain}/${LAUNCH_AGENT_LABEL}`]);
+        if (restarted.code !== 0) {
+            throw new InstallError(`launchctl could not restart the daemon (exit ${restarted.code}): ${restarted.output.trim()}`);
+        }
+        return { plist, log, reloaded: true };
+    }
+    if (current !== text)
+        await writeAtomic(plist, text, 0o644);
+    await run('launchctl', ['bootout', `${domain}/${LAUNCH_AGENT_LABEL}`]);
+    // launchd can stop only the process it owns. Prove no manual or legacy daemon
+    // still owns this shared store before saying the managed one was installed.
+    await mkdirpDurable(o.store);
+    const shutdownDeadline = Date.now() + SHUTDOWN_WAIT_MS;
+    for (;;) {
+        try {
+            const ownership = await acquireSessionLock(o.store);
+            await ownership.release();
+            break;
+        }
+        catch (err) {
+            if (!(err instanceof SessionOwnedError))
+                throw err;
+            if (Date.now() >= shutdownDeadline) {
+                throw new InstallError(`another daemon still owns ${o.store}; stop it before installing the managed daemon`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, SHUTDOWN_POLL_MS));
+        }
+    }
+    // launchd finishes a bootout asynchronously; a bootstrap right behind it can
+    // fail until the old instance is gone.
+    let loaded = await run('launchctl', ['bootstrap', domain, plist]);
+    for (let i = 0; loaded.code !== 0 && i < 10; i++) {
+        await new Promise((r) => setTimeout(r, 200));
+        loaded = await run('launchctl', ['bootstrap', domain, plist]);
+    }
+    if (loaded.code !== 0) {
+        throw new InstallError(`launchctl could not load ${plist} (exit ${loaded.code}): ${loaded.output.trim()}`);
+    }
+    return { plist, log, reloaded: true };
+}
+/** Ask launchd to start the managed daemon now. `exited` settles only when
+ * launchd refuses, so a slow start is waited out rather than abandoned. */
+export function kickstartLaunchAgent(uid, run) {
+    return {
+        exited: run('launchctl', ['kickstart', `gui/${uid}/${LAUNCH_AGENT_LABEL}`])
+            .then((r) => r.code === 0 ? new Promise(() => { }) : r.code),
+    };
+}

package/dist/lock.js

@@ -70,7 +70,7 @@ const HEARTBEAT_MS = 2_000;
  * live owner from being declared stale by a GC/scheduling pause, while still
  * reclaiming a hung owner promptly enough for a supervisor restart.
  */
-const STALE_MS = 12_000;
+export const STALE_MS = 12_000;
 const MAX_ACQUIRE_ATTEMPTS = 8;
 export async function acquireSessionLock(sessionDir, options = {}) {
     const lockPath = join(sessionDir, 'owner.lock');

package/dist/public-events.js

@@ -1,10 +1,22 @@
 /** Additive public events outside the byte-frozen display-fold.v1 dependencies. */
 import { EVENT_TYPES, buildEnvelope, sourceFor, SPEC_VERSION, DATA_CONTENT_TYPE } from "./event.js";
 export const PUBLIC_EVENT_TYPES = [...EVENT_TYPES, 'slipstream.question.queued.v1', 'slipstream.question.dispatch_attempted.v1',
-    'slipstream.question.answered.v1'];
+    'slipstream.question.answered.v1', 'slipstream.question.exchange_recorded.v1', 'slipstream.question.relay_updated.v1', 'slipstream.capture.scope.v1', 'slipstream.agent.connection.v1',
+    'slipstream.capture.ready.v1', 'slipstream.capture.stopped.v1', 'slipstream.agent.binding.v1',
+    'slipstream.agent.unlinked.v1'];
+const LIFECYCLE_TYPES = new Set(['slipstream.capture.scope.v1', 'slipstream.agent.connection.v1', 'slipstream.capture.ready.v1',
+    'slipstream.capture.stopped.v1', 'slipstream.agent.binding.v1', 'slipstream.agent.unlinked.v1']);
+const isLifecycleInput = (input) => LIFECYCLE_TYPES.has(input.type);
 export function buildPublicEnvelope(input, seq, sessionId) {
+    if (isLifecycleInput(input))
+        return {
+            specversion: SPEC_VERSION, id: seq.toString(), source: sourceFor(sessionId), type: input.type,
+            datacontenttype: DATA_CONTENT_TYPE, seq: seq.toString(), time: new Date(input.occurred_at_ms).toISOString(),
+            data: { ...input.data, session_id: sessionId },
+        };
     if (input.type !== 'slipstream.question.queued.v1' && input.type !== 'slipstream.question.dispatch_attempted.v1'
-        && input.type !== 'slipstream.question.answered.v1')
+        && input.type !== 'slipstream.question.answered.v1' && input.type !== 'slipstream.question.exchange_recorded.v1'
+        && input.type !== 'slipstream.question.relay_updated.v1')
         return buildEnvelope(input, seq, sessionId);
     if (input.type === 'slipstream.question.dispatch_attempted.v1')
         return {
@@ -18,6 +30,18 @@ export function buildPublicEnvelope(input, seq, sessionId) {
             datacontenttype: DATA_CONTENT_TYPE, seq: seq.toString(), time: new Date(input.occurred_at_ms).toISOString(),
             subject: `question/${input.data.question_id}`, data: { ...input.data, session_id: sessionId },
         };
+    if (input.type === 'slipstream.question.exchange_recorded.v1')
+        return {
+            specversion: SPEC_VERSION, id: seq.toString(), source: sourceFor(sessionId), type: input.type,
+            datacontenttype: DATA_CONTENT_TYPE, seq: seq.toString(), time: new Date(input.occurred_at_ms).toISOString(),
+            subject: `question/${input.data.question_id}`, data: { ...input.data, session_id: sessionId },
+        };
+    if (input.type === 'slipstream.question.relay_updated.v1')
+        return {
+            specversion: SPEC_VERSION, id: seq.toString(), source: sourceFor(sessionId), type: input.type,
+            datacontenttype: DATA_CONTENT_TYPE, seq: seq.toString(), time: new Date(input.occurred_at_ms).toISOString(),
+            subject: `question/${input.data.question_id}`, data: { ...input.data, session_id: sessionId },
+        };
     return {
         specversion: SPEC_VERSION, id: seq.toString(), source: sourceFor(sessionId),
         type: input.type, datacontenttype: DATA_CONTENT_TYPE, seq: seq.toString(),

package/dist/question-hook.js

@@ -22,8 +22,18 @@ async function postToolUse(harness, input, storeDir, deadlineAtMs) {
             request: { v: 1, verb: 'claim_question', harness, harness_session_id: event.session_id,
                 worktree: event.cwd, transcript_path: event.transcript_path },
             connectTimeoutMs: 300, responseTimeoutMs: 700, deadlineAtMs });
-        if (!reply.ok || reply.question === null)
+        if (!reply.ok)
             return null;
+        if (reply.question === null) {
+            const check = object(reply.setup_check);
+            if (!check || typeof check.check_id !== 'string' || !UUID.test(check.check_id))
+                return null;
+            return JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: [
+                        `Slipstream setup check ${check.check_id}. Slipstream needs one confirmation that this chat can answer questions from the Slipstream app.`,
+                        `Call the slipstream_answer_question tool with question_id ${check.check_id} and text "connected" now, then continue your original work.`,
+                        'If that tool is not available in this chat, tell the user that Slipstream agent setup is still pending and repeat the reload step slipstream attach printed.',
+                    ].join('\n') } });
+        }
         const q = object(reply.question);
         const context = object(q?.context);
         if (!q || !context || !nonempty(q.question_id) || !nonempty(q.text, 8192)