@playola-radio/slipstream 0.1.0

package/dist/log-reader.js

@@ -0,0 +1,148 @@
+// src/log-reader.ts
+import { open } from 'node:fs/promises';
+export class LogCorruptError extends Error {
+}
+/** Optional bounded scans can stop before materializing an oversized record. */
+export class LogReadLimitError extends Error {
+}
+export class LogReadAbortedError extends Error {
+}
+const CURSOR_RE = /^(0|[1-9][0-9]*)$/;
+const SEQ_RE = /^[1-9][0-9]*$/;
+export function parseCursor(raw) {
+    if (raw === undefined)
+        return 0n;
+    if (!CURSOR_RE.test(raw))
+        return null;
+    return BigInt(raw);
+}
+export function parseLine(line) {
+    let obj;
+    try {
+        obj = JSON.parse(line);
+    }
+    catch {
+        throw new LogCorruptError(`invalid JSON: ${line.slice(0, 80)}`);
+    }
+    if (typeof obj !== 'object' || obj === null)
+        throw new LogCorruptError('line is not an object');
+    const rec = obj;
+    const seq = rec.seq;
+    const id = rec.id;
+    const source = rec.source;
+    const type = rec.type;
+    const data = rec.data;
+    if (typeof seq !== 'string' || !SEQ_RE.test(seq))
+        throw new LogCorruptError('bad seq');
+    if (id !== undefined && typeof id !== 'string')
+        throw new LogCorruptError('bad id');
+    if (source !== undefined && typeof source !== 'string')
+        throw new LogCorruptError('bad source');
+    if (typeof type !== 'string')
+        throw new LogCorruptError('bad type');
+    if (typeof data !== 'object' || data === null)
+        throw new LogCorruptError('bad data');
+    // Callers that read from disk (openLogCursor) know the true consumed byte
+    // count — including a stripped BOM — and overwrite this default afterward.
+    return { seq: BigInt(seq), id, source, type, raw: line, bytesRead: Buffer.byteLength(line, 'utf8') + 1, data: data };
+}
+// Each batch retains at most 256 records / 256 KiB, plus one oversized record.
+// A single record cannot be split on the wire; memory also depends on its size.
+export const LOG_BATCH_RECORDS = 256;
+const BATCH_BYTES = 256 * 1024;
+const READ_BYTES = 64 * 1024;
+export async function openLogCursor(logPath, after) {
+    const handle = await open(logPath, 'r');
+    let offset = 0; // sole committed byte position, advanced only over complete lines
+    let lastSeq = after;
+    let positioned = after === 0n;
+    let window = Buffer.alloc(0);
+    let windowStart = 0;
+    // Recovery decodes the whole file with one non-streaming call, so the
+    // WHATWG decoder strips a BOM only if it is the file's first three bytes.
+    // Match that exactly: strip a BOM only for the record at byte offset 0, and
+    // preserve (so parseLine rejects) a BOM anywhere else, mid-log.
+    const firstLineDecoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false });
+    const laterLineDecoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+    async function nextLine(maxBytes, signal) {
+        let pos = offset;
+        const pieces = [];
+        let lineBytes = 0;
+        for (;;) {
+            if (signal?.aborted)
+                throw new LogReadAbortedError('log read aborted');
+            if (lineBytes >= maxBytes)
+                throw new LogReadLimitError('log record exceeds scan byte budget');
+            if (pos < windowStart || pos >= windowStart + window.length) {
+                const buffer = Buffer.allocUnsafe(Math.min(READ_BYTES, maxBytes - lineBytes + 1));
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, pos);
+                window = buffer.subarray(0, bytesRead);
+                windowStart = pos;
+                if (!bytesRead)
+                    return null; // torn tail: offset stays at the line start
+            }
+            const start = pos - windowStart;
+            const nl = window.indexOf(0x0a, start);
+            if (nl >= 0) {
+                if (lineBytes + nl - start + 1 > maxBytes)
+                    throw new LogReadLimitError('log record exceeds scan byte budget');
+                pieces.push(window.subarray(start, nl));
+                return Buffer.concat(pieces);
+            }
+            lineBytes += window.length - start;
+            if (lineBytes >= maxBytes)
+                throw new LogReadLimitError('log record exceeds scan byte budget');
+            pieces.push(window.subarray(start));
+            pos = windowStart + window.length;
+        }
+    }
+    return {
+        async readThrough(boundary, limits = {}) {
+            const out = [];
+            let bytes = 0;
+            while (lastSeq < boundary && out.length < Math.min(LOG_BATCH_RECORDS, limits.maxRecords ?? LOG_BATCH_RECORDS)
+                && bytes < BATCH_BYTES && bytes < (limits.maxBytes ?? Infinity)) {
+                const lineStart = offset;
+                let slice;
+                try {
+                    slice = await nextLine((limits.maxBytes ?? Infinity) - bytes, limits.signal);
+                }
+                catch (error) {
+                    // Offset already advanced for records in this batch. Return them before
+                    // reporting the limit on the next call, so a retry cannot skip them.
+                    if (out.length > 0 && (error instanceof LogReadLimitError || error instanceof LogReadAbortedError))
+                        return out;
+                    throw error;
+                }
+                if (slice === null)
+                    break;
+                let line;
+                try {
+                    line = (lineStart === 0 ? firstLineDecoder : laterLineDecoder).decode(slice);
+                }
+                catch {
+                    throw new LogCorruptError('invalid UTF-8 in log record');
+                }
+                const ev = parseLine(line);
+                const lineBytes = slice.length + 1;
+                ev.bytesRead = lineBytes;
+                if (!positioned) {
+                    if (ev.seq <= after) {
+                        offset += lineBytes;
+                        continue;
+                    }
+                    positioned = true;
+                }
+                if (ev.seq !== lastSeq + 1n) {
+                    throw new LogCorruptError(`non-contiguous seq: expected ${lastSeq + 1n} got ${ev.seq}`);
+                }
+                out.push(ev);
+                lastSeq = ev.seq;
+                offset += lineBytes;
+                bytes += lineBytes;
+            }
+            return out;
+        },
+        async close() { await handle.close(); },
+    };
+}

package/dist/log.js

@@ -0,0 +1,59 @@
+import { open, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { buildPublicEnvelope as buildEnvelope } from "./public-events.js";
+import { FILE_MODE, StorageError, fsyncDir, writeAll } from "./storage.js";
+/**
+ * The single writer for a session's `events.jsonl`. Appends are serialized onto
+ * a tail promise so seq assignment and byte order never interleave. Each append
+ * is durable before it is acknowledged: writeAll then fsync, then the high-water
+ * seq advances. A write failure poisons the log — every later append rejects
+ * rather than concatenate onto a possibly half-written line (the log is the
+ * source of truth). Recovery repairs and reopens; it does not append through a
+ * poisoned handle.
+ */
+export async function createLog(opts) {
+    const { filePath, sessionId, sequencer } = opts;
+    const isNew = !(await stat(filePath).then(() => true).catch(() => false));
+    const handle = await open(filePath, 'a', FILE_MODE);
+    if (isNew) {
+        try {
+            await handle.sync();
+            await fsyncDir(dirname(filePath));
+        }
+        catch (err) {
+            await handle.close();
+            throw err instanceof StorageError ? err : new StorageError('create-log', err);
+        }
+    }
+    let durableSeq = opts.startSeq ?? 0n;
+    let tail = Promise.resolve();
+    let poison = null;
+    const append = (input) => {
+        const result = tail.then(async () => {
+            if (poison)
+                throw poison;
+            const seq = durableSeq + 1n;
+            const event = buildEnvelope(sequencer ? sequencer.enrich(input) : input, seq, sessionId);
+            try {
+                await writeAll(handle, Buffer.from(`${JSON.stringify(event)}\n`));
+                await handle.sync();
+            }
+            catch (err) {
+                poison = err instanceof StorageError ? err : new StorageError('append', err);
+                throw poison;
+            }
+            durableSeq = seq;
+            // Ordered and durable: advance any sequencer state before the next append
+            // is processed, so a later change sees this commit and no earlier one does.
+            sequencer?.onCommitted(event);
+            return event;
+        });
+        tail = result.catch(() => undefined);
+        return result;
+    };
+    const close = async () => {
+        await tail;
+        await handle.close();
+    };
+    return { append, durableSeq: () => durableSeq, close };
+}

package/dist/maintenance.js

@@ -0,0 +1,255 @@
+import { access, open, readdir, rename, unlink } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { FILE_MODE, StorageError, fsyncDir, writeAll } from "./storage.js";
+import { blobPath, isValidHex, listSessions, onDiskHighWater, sessionLogPath, tombstonePath, } from "./store-reader.js";
+import { openLogCursor, LogCorruptError } from "./log-reader.js";
+import { PUBLIC_EVENT_TYPES as EVENT_TYPES } from "./public-events.js";
+/**
+ * Store maintenance for detached-only session deletion + GC (Stage 3, P5).
+ *
+ * Deletion is durable-tombstone-first: {@link publishTombstone} makes
+ * `removed.json` durable BEFORE {@link removeSessionHistory} removes the log, so
+ * a crash between the two leaves a durable tombstone the reader already 410s and
+ * a residual log GC finishes later. Nothing here touches the ACTIVE session or
+ * decides retention policy — the daemon gates admission (detached-only) and the
+ * caller supplies the session ids.
+ *
+ * Blob reclamation ({@link reclaimUnreferencedBlobs}) is a conservative,
+ * whole-store mark-and-sweep over the GLOBAL content-addressed store. Blobs are
+ * shared across sessions, so the live set is every hash referenced by every
+ * NON-removed session's durable log; anything else is swept. The mark phase is
+ * all-or-nothing: a missing, corrupt, or uninterpretable retained log aborts the
+ * whole sweep (deletes nothing) rather than risk deleting a live blob.
+ */
+const TOMBSTONE_BODY = Buffer.from('{"version":1}\n', 'utf8');
+const HISTORY_FILES = ['events.jsonl'];
+const SHARD_RE = /^[0-9a-f]{2}$/;
+const KNOWN_EVENT_TYPES = new Set(EVENT_TYPES);
+function sessionDir(storeDir, id) {
+    return dirname(tombstonePath(storeDir, id));
+}
+/** blobs/sha256 — the CAS root, derived from store-reader's blobPath so the
+ * layout lives in one place (blobPath gives `.../sha256/<ab>/<hex>`). */
+function blobBaseDir(storeDir) {
+    return dirname(dirname(blobPath(storeDir, '0'.repeat(64))));
+}
+/**
+ * Durably publish `sessions/<id>/removed.json = {"version":1}`: unique temp,
+ * `wx`/0600, write, fsync file, atomic rename over any prior marker, fsync the
+ * session dir. Idempotent — republishing is safe and required, because an
+ * existing marker does not prove the earlier dir-fsync completed.
+ */
+export async function publishTombstone(storeDir, id) {
+    const dest = tombstonePath(storeDir, id);
+    const dir = dirname(dest);
+    const tmp = `${dest}.${randomUUID()}.tmp`;
+    let handle;
+    try {
+        try {
+            handle = await open(tmp, 'wx', FILE_MODE);
+            await writeAll(handle, TOMBSTONE_BODY);
+            await handle.sync();
+        }
+        catch (err) {
+            throw new StorageError('write-tombstone', err);
+        }
+        finally {
+            await handle?.close();
+        }
+        try {
+            await rename(tmp, dest);
+        }
+        catch (err) {
+            throw new StorageError('rename-tombstone', err);
+        }
+        await fsyncDir(dir);
+    }
+    finally {
+        await unlink(tmp).catch(() => { });
+    }
+}
+/**
+ * Remove a removed session's history by an EXPLICIT inventory (never a recursive
+ * dir removal), preserving `removed.json` and the session dir so the reader still
+ * lists `{removed:true}` and 410s. fsync the dir so the removal is durable.
+ */
+export async function removeSessionHistory(storeDir, id) {
+    const dir = sessionDir(storeDir, id);
+    let removedAny = false;
+    for (const name of HISTORY_FILES) {
+        try {
+            await unlink(join(dir, name));
+            removedAny = true;
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw new StorageError('remove-history', err);
+        }
+    }
+    if (removedAny)
+        await fsyncDir(dir);
+}
+/** Whether `sessions/<id>/` exists. A well-formed id naming no dir is a deletion
+ * target the caller reports as not-found rather than manufacturing a tombstone. */
+export async function sessionExists(storeDir, id) {
+    try {
+        await access(sessionDir(storeDir, id));
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw new StorageError('stat-session', err);
+    }
+}
+/**
+ * Mark-and-sweep the global CAS: delete every blob NOT referenced by any
+ * non-removed session's durable log. Returns the number of blobs unlinked.
+ * Throws (deleting nothing further) if the mark phase cannot be completed
+ * safely, or if the {@link SweepAbort} predicate trips before an unlink.
+ */
+export async function reclaimUnreferencedBlobs(storeDir, abort) {
+    const live = new Set();
+    for (const s of await listSessions(storeDir)) {
+        if (s.removed)
+            continue;
+        await collectBlobRefs(storeDir, s.id, live); // throws on any unsafe condition
+    }
+    return sweepBlobs(storeDir, live, abort);
+}
+/**
+ * Add every blob hash one non-removed session's durable log references to `live`.
+ * Reads the whole log up to its durable high-water. Throws — never returns a
+ * partial set — if the log is missing, corrupt, carries an event type this
+ * version cannot interpret, or holds a content snapshot without a valid sha256.
+ */
+async function collectBlobRefs(storeDir, id, live) {
+    const logPath = sessionLogPath(storeDir, id);
+    const boundary = await onDiskHighWater(logPath); // throws LogCorruptError on a bad tail
+    let cursor;
+    try {
+        cursor = await openLogCursor(logPath, 0n);
+    }
+    catch (err) {
+        // A non-removed session must have a readable log; a missing one is unsafe to
+        // treat as an empty reference set (onDiskHighWater returns 0n for BOTH a
+        // missing and an empty log, so distinguish them here).
+        throw new StorageError('gc-mark-open', err);
+    }
+    try {
+        // Validate every complete record through the log's PHYSICAL end — never stop at
+        // the final record's declared seq. `readThrough(boundary + 1n)` keeps consuming
+        // past the high-water, so a log whose tail rewinds below an interior seq (e.g.
+        // 1, 2, 1) is caught by the cursor's contiguity check or the reached-seq
+        // assertion below, rather than silently skipping the records after the boundary.
+        let seq = 0n;
+        for (;;) {
+            const batch = await cursor.readThrough(boundary + 1n); // throws on non-contiguous seq
+            if (!batch.length)
+                break; // physical EOF (or a torn, uncommitted tail)
+            for (const ev of batch) {
+                addRefsFromEvent(ev.type, ev.data, live);
+                seq = ev.seq;
+            }
+        }
+        if (seq !== boundary) {
+            // The last complete record read is not the durable high-water: the log is
+            // short of, or runs past, its own final seq — corruption. Delete nothing.
+            throw new LogCorruptError(`gc-mark: read to seq ${seq}, not durable high-water ${boundary}`);
+        }
+    }
+    finally {
+        await cursor.close();
+    }
+}
+function addRefsFromEvent(type, data, live) {
+    if (!KNOWN_EVENT_TYPES.has(type)) {
+        // A newer/unknown type may reference blobs through a mechanism this version
+        // does not know. Refuse to sweep rather than risk deleting a live blob.
+        throw new LogCorruptError(`gc-mark: unknown event type ${type}; refusing to sweep`);
+    }
+    // A blob reference is exactly a canonical content snapshot ({kind:'content',
+    // sha256}). Collect them wherever they appear in the event's data — not just the
+    // fields this version happens to hard-code — so an additive blob-bearing field on
+    // an existing type is still marked, never orphaned and swept. Any other shape
+    // carries no blob and is ignored.
+    addRefsFromValue(data, live);
+}
+function addRefsFromValue(value, live) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            addRefsFromValue(item, live);
+        return;
+    }
+    if (typeof value !== 'object' || value === null)
+        return;
+    const record = value;
+    if (record.kind === 'content' || 'sha256' in record) {
+        // Anything shaped like a blob reference — a content snapshot, or any object
+        // carrying a sha256 — must be a fully valid content snapshot. A partial or
+        // malformed one (a sha256 without kind:'content', or a bad hex) is corruption
+        // this version cannot interpret: fail closed rather than silently drop the
+        // reference and sweep a blob it may protect.
+        const sha = record.sha256;
+        if (record.kind !== 'content' || typeof sha !== 'string' || !isValidHex(sha)) {
+            throw new LogCorruptError('gc-mark: malformed content snapshot');
+        }
+        live.add(sha);
+    }
+    for (const child of Object.values(record))
+        addRefsFromValue(child, live);
+}
+/** Delete validated CAS blobs not in `live`, fsyncing each changed shard. Only
+ * well-formed, correctly-sharded hash files are ever unlinked — a stray or
+ * misplaced file is left untouched. */
+async function sweepBlobs(storeDir, live, abort) {
+    const base = blobBaseDir(storeDir);
+    let shards;
+    try {
+        shards = await readdir(base);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return 0;
+        throw new StorageError('gc-sweep-readdir', err);
+    }
+    let removed = 0;
+    for (const shard of shards) {
+        if (!SHARD_RE.test(shard))
+            continue; // not a CAS shard directory
+        const shardDir = join(base, shard);
+        let names;
+        try {
+            names = await readdir(shardDir);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                continue;
+            throw new StorageError('gc-sweep-readdir', err);
+        }
+        let removedHere = 0;
+        for (const name of names) {
+            if (!isValidHex(name) || name.slice(0, 2) !== shard)
+                continue; // temp/stray/misplaced
+            if (live.has(name))
+                continue;
+            if (abort()) {
+                throw new StorageError('gc-sweep-aborted', new Error('store ownership lost mid-sweep'));
+            }
+            try {
+                await unlink(join(shardDir, name));
+                removed++;
+                removedHere++;
+            }
+            catch (err) {
+                if (err.code === 'ENOENT')
+                    continue;
+                throw new StorageError('gc-sweep-unlink', err);
+            }
+        }
+        if (removedHere > 0)
+            await fsyncDir(shardDir);
+    }
+    return removed;
+}

package/dist/mcp-forwarder.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * The Slipstream MCP forwarder — the whole subprocess a harness spawns.
+ *
+ * It wires these pieces together and owns nothing else:
+ *   - {@link ./mcp-protocol.ts}   — hand-rolled MCP-over-stdio JSON-RPC transport.
+ *   - {@link ./harness-context.ts} — fail-closed harness-identity resolver (SC3).
+ *   - {@link ./task-forwarder.ts} — begin_task orchestration with honest retry.
+ *   - {@link ./answer-forwarder.ts} — answer_question orchestration with honest retry.
+ *   - {@link ./control-client.ts} — the unix-socket control channel to the daemon.
+ *
+ * It exposes two tools, `slipstream_begin_task(title)` and
+ * `slipstream_answer_question(question_id, text)`. The forwarder is a control
+ * client: it never attaches, never captures, and never touches the store — it resolves the daemon's control socket from `--store` (shared with the CLI)
+ * and forwards a verified identity triple. A missing daemon fails fast as
+ * DAEMON_UNAVAILABLE rather than hanging, because the tool must return promptly.
+ */
+import { isMainModule } from "./entrypoint.js";
+import { dispatch, parseMessage } from "./mcp-protocol.js";
+import { createHarnessContext } from "./harness-context.js";
+import { forwardBeginTask } from "./task-forwarder.js";
+import { forwardAnswer } from "./answer-forwarder.js";
+import { sendControlRequest } from "./control-client.js";
+import { controlSocketPath, resolveStoreDir } from "./daemon-location.js";
+export const BEGIN_TASK_TOOL = {
+    name: 'slipstream_begin_task',
+    description: 'Declare the start of a task so the Slipstream feed groups the file changes you are about ' +
+        'to make under it. Call it right before you start working on a distinct piece of work.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            title: { type: 'string', description: 'A short human-readable title for the task.' },
+        },
+        required: ['title'],
+        additionalProperties: false,
+    },
+};
+export const ANSWER_QUESTION_TOOL = {
+    name: 'slipstream_answer_question',
+    description: 'Return your answer to a Slipstream question. Call it once per question with the exact ' +
+        'question_id from the Slipstream question context and your complete answer as text.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            question_id: { type: 'string', description: 'The exact Slipstream question id you are answering.' },
+            text: { type: 'string', description: 'Your complete answer for the user.' },
+        },
+        required: ['question_id', 'text'],
+        additionalProperties: false,
+    },
+};
+function isObject(v) {
+    return typeof v === 'object' && v !== null;
+}
+function stringArg(params, key) {
+    // Pass the raw value through; the daemon is the authority on validity (an
+    // empty/absent title or answer becomes its INVALID_TITLE / INVALID_ANSWER,
+    // not a second local rule).
+    const value = isObject(params) && isObject(params.arguments) ? params.arguments[key] : undefined;
+    return typeof value === 'string' ? value : '';
+}
+export function createForwarderHandlers(opts) {
+    const ctx = createHarnessContext();
+    return {
+        serverInfo: { name: 'slipstream-forwarder', version: '0.0.0' },
+        protocolVersion: '2025-06-18',
+        tools: [BEGIN_TASK_TOOL, ANSWER_QUESTION_TOOL],
+        onInitialize: (params) => {
+            const clientInfo = isObject(params) ? params.clientInfo : undefined;
+            ctx.initialize(clientInfo, opts.env);
+        },
+        callTool: (name, params) => {
+            const identity = ctx.identityForCall(params);
+            const send = (request) => sendControlRequest({ socketPath: opts.socketPath, request });
+            return name === ANSWER_QUESTION_TOOL.name
+                ? forwardAnswer({ identity, questionId: stringArg(params, 'question_id'), text: stringArg(params, 'text'), send })
+                : forwardBeginTask({ identity, title: stringArg(params, 'title'), send });
+        },
+    };
+}
+/** The largest single JSON-RPC line the forwarder will buffer from stdin. A well-
+ * formed request is a few hundred bytes; this cap is generous for a title yet far
+ * short of exhausting memory on an unterminated line. */
+export const MAX_STDIN_LINE_BYTES = 1024 * 1024;
+const NEWLINE = 0x0a;
+/**
+ * Split raw stdin bytes into newline-delimited lines with a hard byte cap. A line
+ * (terminated or not) that exceeds `maxBytes` is dropped and reported as
+ * `{ overflow: true }`; the bytes up to its terminating newline are then discarded
+ * rather than accumulated, so a peer streaming an endless unterminated line can
+ * never grow the buffer without bound. Blank lines are skipped.
+ */
+export function createStdinFramer(maxBytes = MAX_STDIN_LINE_BYTES) {
+    let buf = Buffer.alloc(0);
+    let discarding = false; // dropping the tail of an over-cap line until its newline
+    return {
+        push(chunk) {
+            buf = buf.length === 0 ? chunk : Buffer.concat([buf, chunk]);
+            const out = [];
+            for (;;) {
+                const nl = buf.indexOf(NEWLINE);
+                if (nl === -1)
+                    break;
+                const lineBuf = buf.subarray(0, nl);
+                buf = buf.subarray(nl + 1);
+                if (discarding) {
+                    discarding = false;
+                    continue;
+                }
+                if (lineBuf.length > maxBytes) {
+                    out.push({ overflow: true });
+                    continue;
+                }
+                const line = lineBuf.toString('utf8');
+                if (line.trim().length === 0)
+                    continue;
+                out.push({ line });
+            }
+            if (buf.length > maxBytes) {
+                if (!discarding)
+                    out.push({ overflow: true });
+                buf = Buffer.alloc(0);
+                discarding = true;
+            }
+            return out;
+        },
+    };
+}
+export async function runForwarder() {
+    let socketPath;
+    try {
+        socketPath = controlSocketPath(resolveStoreDir(process.argv.slice(2)));
+    }
+    catch (err) {
+        process.stderr.write(`slipstream-forwarder: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    const handlers = createForwarderHandlers({ socketPath, env: process.env });
+    const writeError = (code, message) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code, message } }) + '\n');
+    const framer = createStdinFramer();
+    for await (const chunk of process.stdin) {
+        for (const frame of framer.push(chunk)) {
+            if ('overflow' in frame) {
+                writeError(-32700, 'message exceeds byte cap');
+                continue;
+            }
+            const parsed = parseMessage(frame.line);
+            if (!parsed.ok) {
+                writeError(parsed.code, parsed.code === -32700 ? 'parse error' : 'invalid request');
+                continue;
+            }
+            const res = await dispatch(parsed.value, handlers);
+            if (res)
+                process.stdout.write(JSON.stringify(res) + '\n');
+        }
+    }
+}
+if (process.argv[1] && isMainModule(import.meta.url, process.argv[1])) {
+    await runForwarder();
+}