moflo 4.9.36 → 4.10.0

package/dist/src/cli/memory/daemon-backend.js

@@ -0,0 +1,400 @@
+/**
+ * Daemon-side memory DB factory — TS twin of `bin/lib/get-backend.mjs`.
+ *
+ * Returns a handle whose surface matches the sql.js `Database` type that the
+ * controller registry + bridge code expect (prepare → Statement, run, exec,
+ * close, plus a `save()` that maps to the engine's preferred persistence).
+ * Currently always returns a node:sqlite-backed adapter — Phase 4 (#1083)
+ * flipped the SQLite default; Phase 5 (#1084) deletes the remaining sql.js
+ * paths in the bridge + memory-initializer.
+ *
+ * The sql.js Statement API the bridge code relies on:
+ *   - db.prepare(sql) → stmt
+ *   - db.run(sql, params?)
+ *   - db.exec(sql) → [{ columns, values }]
+ *   - db.close()
+ *   - stmt.bind(params)
+ *   - stmt.step() → boolean
+ *   - stmt.getAsObject() → row object
+ *   - stmt.run(params?) → boolean
+ *   - stmt.free()
+ *
+ * node:sqlite's `StatementSync` is stateless (each call takes params), so we
+ * shim a stateful wrapper via `stmt.iterate(...)` opened on first `step()`.
+ * This is the same shape implemented in bin/lib/get-backend.mjs — keep the
+ * two in lockstep until Phase 5 collapses them.
+ *
+ * @module v3/memory/daemon-backend
+ */
+// MUST come before `import 'node:sqlite'` below — that module fires
+// `ExperimentalWarning: SQLite is an experimental feature` exactly once per
+// process on first load. Once it fires, there's no way to scrub it from
+// stderr, and consumer-smoke's 200-char stderr tails get filled with it
+// (hiding the real error message; #1098).
+import './suppress-sqlite-warning.js';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+/**
+ * Coerce a caller-supplied parameter set into node:sqlite's `SQLInputValue[]`
+ * shape. Callers pass `any` (sql.js parity) so we just pass through after
+ * normalising null/undefined/array.
+ */
+function toParamsArray(params) {
+    if (params === undefined || params === null)
+        return [];
+    if (Array.isArray(params))
+        return params;
+    // sql.js's `Statement.bind(obj)` named-param shape isn't reachable from
+    // moflo's bridge code today — every caller passes an array. Tolerate
+    // anyway by wrapping the lone value.
+    return [params];
+}
+function wrapStatement(stmt) {
+    let pendingParams = [];
+    let iter = null;
+    let currentRow = null;
+    let columnNamesCache = null;
+    const ensureIter = () => {
+        if (!iter) {
+            iter = (pendingParams.length > 0
+                ? stmt.iterate(...pendingParams)
+                : stmt.iterate());
+        }
+    };
+    return {
+        bind(params) {
+            pendingParams = toParamsArray(params);
+            iter = null;
+            currentRow = null;
+            return true;
+        },
+        step() {
+            ensureIter();
+            const next = iter.next();
+            if (next.done) {
+                currentRow = null;
+                return false;
+            }
+            currentRow = next.value;
+            return true;
+        },
+        getAsObject(params) {
+            // sql.js semantics: with params it's a one-shot bind+step+return;
+            // without params it returns whatever the last step() materialised. The
+            // bridge uses both shapes (one-shot in bridge-entries.ts:bridgeGetEntry,
+            // iterator in list/search). Returning {} from the one-shot form when
+            // there's no row is correct (caller checks for nullish primary key).
+            if (params !== undefined) {
+                pendingParams = toParamsArray(params);
+                iter = null;
+                ensureIter();
+                const next = iter.next();
+                if (next.done) {
+                    currentRow = null;
+                    return {};
+                }
+                currentRow = next.value;
+                return currentRow;
+            }
+            return currentRow ?? {};
+        },
+        get(params) {
+            // sql.js `Statement.get()` semantics:
+            //   - With params: one-shot bind+step, returns positional values of the
+            //     first row (or [] if no rows).
+            //   - Without params: returns positional values of the CURRENT row —
+            //     the row that the most-recent `step()` landed on. Callers use it
+            //     in a `while (stmt.step()) { const row = stmt.get(); ... }` loop;
+            //     calling iter.next() again here would skip every other row.
+            if (params !== undefined) {
+                pendingParams = toParamsArray(params);
+                iter = null;
+                ensureIter();
+                const next = iter.next();
+                if (next.done) {
+                    currentRow = null;
+                    return [];
+                }
+                currentRow = next.value;
+            }
+            if (!currentRow)
+                return [];
+            const cols = columnNamesCache ?? Object.keys(currentRow);
+            columnNamesCache = cols;
+            return cols.map((c) => currentRow[c]);
+        },
+        getColumnNames() {
+            if (columnNamesCache)
+                return columnNamesCache;
+            // Force one step to materialise a row so column names are knowable.
+            ensureIter();
+            const next = iter.next();
+            if (next.done) {
+                columnNamesCache = [];
+                currentRow = null;
+                return [];
+            }
+            currentRow = next.value;
+            columnNamesCache = Object.keys(currentRow);
+            return columnNamesCache;
+        },
+        run(params) {
+            const arr = toParamsArray(params);
+            if (arr.length > 0)
+                stmt.run(...arr);
+            else
+                stmt.run();
+            return true;
+        },
+        reset() {
+            iter = null;
+            currentRow = null;
+        },
+        free() {
+            iter = null;
+            currentRow = null;
+            pendingParams = [];
+            columnNamesCache = null;
+        },
+    };
+}
+/**
+ * Per-process dedupe of network-FS warnings — emit once per (dbPath, process).
+ * Matches the JS twin's `_networkFsWarnedPaths` set so a session that opens
+ * both the daemon adapter and a bin/ writer on the same path only logs once.
+ */
+const _networkFsWarnedPaths = new Set();
+/**
+ * Read `journal_mode` back after we requested WAL. If the engine returned a
+ * different mode (`delete`, `truncate`, `persist`, `memory`, `off`), the
+ * underlying filesystem doesn't support WAL's shared-memory sidecar — a
+ * strong signal that POSIX advisory locks are also unreliable. Surface a
+ * one-line stderr warning naming the path so the user knows to move the
+ * project off the network mount. Deduped per (path, process).
+ *
+ * Twin: `bin/lib/get-backend.mjs:warnIfNotWal`. Must stay in lockstep until
+ * Phase 5 (#1084) extracts a shared module.
+ */
+function warnIfNotWal(db, dbPath) {
+    if (_networkFsWarnedPaths.has(dbPath))
+        return;
+    let mode;
+    try {
+        const stmt = db.prepare('PRAGMA journal_mode');
+        const row = stmt.get();
+        mode = String(row?.journal_mode ?? '').toLowerCase();
+    }
+    catch {
+        return;
+    }
+    if (mode && mode !== 'wal') {
+        _networkFsWarnedPaths.add(dbPath);
+        process.stderr.write(`[moflo] WARNING: SQLite journal_mode=${mode} on ${dbPath} (WAL not active). ` +
+            `If this directory is on NFS/SMB or another network filesystem, POSIX ` +
+            `advisory locks are unreliable and concurrent moflo processes can corrupt ` +
+            `the database. Move the project to a local disk to restore multi-process safety.\n`);
+    }
+}
+/** @internal — test hook only (resets the dedupe set). */
+export function _resetDaemonNetworkFsWarnings() {
+    _networkFsWarnedPaths.clear();
+}
+/**
+ * Heuristic: SQL is multi-statement if there's a `;` followed by anything
+ * substantive. node:sqlite's `db.prepare()` does NOT throw on multi-statement
+ * input — it silently parses only the first statement and discards the rest,
+ * which is the worst possible failure mode for DDL batches like
+ * `CREATE TABLE a; CREATE INDEX i; CREATE TABLE b;`. Detect explicitly and
+ * route multi-stmt SQL to `db.exec()` (which runs every statement).
+ *
+ * The bridge + controller schema strings don't embed literal `;` inside
+ * string literals, so the naive index-of check is sound. If that ever
+ * changes, this needs a real tokeniser.
+ */
+function isMultiStatement(sql) {
+    const trimmed = sql.trimEnd();
+    const semi = trimmed.indexOf(';');
+    if (semi === -1)
+        return false;
+    return /\S/.test(trimmed.slice(semi + 1));
+}
+function execAsRowsNodeSqlite(db, sql, params) {
+    // Multi-statement DDL: route to db.exec() so every statement runs.
+    // (sql.js's exec() runs every statement and returns row sets from any
+    // that produce rows; the bridge code only reads [0]?.values, so DDL
+    // batches correctly return []. Match that contract.)
+    if (isMultiStatement(sql)) {
+        db.exec(sql);
+        return [];
+    }
+    let stmt;
+    try {
+        stmt = db.prepare(sql);
+    }
+    catch {
+        // Last resort for any single-statement SQL that prepare rejects.
+        db.exec(sql);
+        return [];
+    }
+    const args = toParamsArray(params);
+    const rows = (args.length > 0 ? stmt.all(...args) : stmt.all());
+    if (rows.length === 0)
+        return [];
+    const columns = Object.keys(rows[0]);
+    const values = rows.map((r) => columns.map((c) => r[c]));
+    return [{ columns, values }];
+}
+/**
+ * Open the daemon's memory DB handle. Always returns a node:sqlite-backed
+ * adapter shaped like sql.js's Database so the existing bridge + controller
+ * surface keeps working.
+ *
+ * @param dbPath disk path or `:memory:`
+ */
+export function openDaemonDatabase(dbPath) {
+    // node:sqlite opens forgivingly even on non-SQLite files. Keep parity with
+    // openSqlJsDatabase's "create if missing" semantic — DatabaseSync handles
+    // file creation for us, BUT does NOT auto-create parent directories. The
+    // bridge's first-init path commonly lands on a path whose parent .moflo/
+    // doesn't exist yet (fresh consumer install, test fixtures with temp
+    // project roots) — without the mkdir below, DatabaseSync throws ENOENT,
+    // the controller-registry sets mofloDb=null, and the bridge silently
+    // falls back to a raw-sql.js write rooted at process.cwd() (catastrophic
+    // path drift bug; #1057 was about exactly this class of issue).
+    if (dbPath !== ':memory:') {
+        try {
+            mkdirSync(dirname(dbPath), { recursive: true });
+        }
+        catch { /* tolerate — DatabaseSync's ENOENT below is the real signal */ }
+    }
+    const db = new DatabaseSync(dbPath);
+    if (dbPath !== ':memory:') {
+        try {
+            // busy_timeout MUST be set BEFORE journal_mode=WAL, because the WAL
+            // pragma briefly takes an EXCLUSIVE lock and concurrent openers race
+            // on it. Without busy_timeout in place, parallel doctor probes /
+            // bridge initializations / indexer subprocess opens hit "database is
+            // locked" and the bridge tears down (CI #1097). Order matters:
+            //   1. busy_timeout — gives every subsequent pragma a retry budget
+            //   2. journal_mode = WAL — needs the budget on contention
+            //   3. synchronous — purely advisory, can come anytime
+            //
+            // Budget: 15000ms. The consumer-smoke harness exposes the realistic
+            // worst case — a background indexer subprocess opens its own write
+            // connection right after `npm install` and walks the entire consumer
+            // tree (hundreds of guidance/skill files). The whole-tree first-pass
+            // can hold a RESERVED/EXCLUSIVE lock for 5–8s while the doctor
+            // foreground probe races against it. 5000ms was the original Phase 4
+            // value and ran the budget out under that exact load on Windows CI
+            // (#1098); 15000ms gives the indexer's full first-pass time to finish
+            // before doctor's probe gives up. The price of being wrong-high here
+            // is one slow probe per session, not lost data.
+            db.exec('PRAGMA busy_timeout = 15000');
+            db.exec('PRAGMA journal_mode = WAL');
+            db.exec('PRAGMA synchronous = NORMAL');
+            // The daemon is the process most exposed to network-FS edge cases
+            // (long-lived MCP server, ~30s of writes per indexer pass). NFS/SMB
+            // mounts silently fall back from WAL to a rollback journal — surface
+            // a one-line warning so the user knows to move the project off the
+            // network mount. Mirrors `bin/lib/get-backend.mjs:warnIfNotWal`.
+            warnIfNotWal(db, dbPath);
+        }
+        catch (err) {
+            try {
+                db.close();
+            }
+            catch {
+                /* handle already dead */
+            }
+            throw err;
+        }
+    }
+    // sql.js's `db.run(sql, params?)` and `prepare/run` share state; node:sqlite
+    // requires fresh statements per call. Cache prepared statements keyed by SQL
+    // text so the indexer-equivalent tight write loops don't churn the compiler.
+    const runStmtCache = new Map();
+    let changesStmt = null;
+    return {
+        kind: 'node-sqlite',
+        _raw: db,
+        prepare(sql) {
+            return wrapStatement(db.prepare(sql));
+        },
+        run(sql, params) {
+            const arr = toParamsArray(params);
+            if (arr.length > 0) {
+                let s = runStmtCache.get(sql);
+                if (!s) {
+                    s = db.prepare(sql);
+                    runStmtCache.set(sql, s);
+                }
+                s.run(...arr);
+            }
+            else {
+                db.exec(sql);
+            }
+            return undefined;
+        },
+        exec(sql, params) {
+            return execAsRowsNodeSqlite(db, sql, params);
+        },
+        getRowsModified() {
+            if (!changesStmt)
+                changesStmt = db.prepare('SELECT changes() AS c');
+            const row = changesStmt.get();
+            const c = row?.c ?? 0;
+            return typeof c === 'bigint' ? Number(c) : c;
+        },
+        save() {
+            // node:sqlite persists incrementally via WAL — no-op. The shape exists
+            // so bridge-core's persistBridgeDb can call it unconditionally during
+            // the Phase 4/5 transition window. Once everything routes through this
+            // adapter, the explicit persist call becomes dead code (Phase 5).
+        },
+        export() {
+            // Bridge-core's old persist path used `db.export()` + atomicWriteFileSync.
+            // node:sqlite ships a `serialize()` that returns the same shape so the
+            // few callers that still need a buffer (e.g. tests, backup tooling) work.
+            // The bridge-core persist call itself is being switched to `save()` so
+            // this exists only as a safety net during the migration.
+            const buf = db.prepare('SELECT 1').all();
+            void buf;
+            // Real serialize. node:sqlite added `DatabaseSync.prototype.serialize()`
+            // in Node 22; the TS type for it landed later, so cast through the
+            // engine's runtime API.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const ser = db.serialize?.();
+            if (ser instanceof Uint8Array)
+                return ser;
+            if (ser && typeof ser === 'object' && 'buffer' in ser)
+                return new Uint8Array(ser);
+            // Last resort: read the file off disk. The caller knows the path; we
+            // don't, so this branch should never fire under normal flow.
+            return new Uint8Array();
+        },
+        close() {
+            runStmtCache.clear();
+            changesStmt = null;
+            db.close();
+        },
+    };
+}
+/**
+ * Seed an empty daemon DB from an existing file on disk. Equivalent to
+ * sql.js's `new SQL.Database(readFileSync(path))` round-trip — node:sqlite
+ * opens the path directly so this is just a wrapper that errors when the
+ * file doesn't exist (existing callers expected the sql.js behaviour).
+ */
+export function openDaemonDatabaseFromFile(dbPath) {
+    if (dbPath !== ':memory:' && !existsSync(dbPath)) {
+        throw new Error(`Database file not found: ${dbPath}`);
+    }
+    // Touch readFileSync so callers that previously expected eager I/O still
+    // observe the same failure shape (e.g. EACCES errors fire here, not
+    // lazily on first query). node:sqlite would lazy-error otherwise.
+    if (dbPath !== ':memory:')
+        readFileSync(dbPath, { flag: 'r' });
+    return openDaemonDatabase(dbPath);
+}
+//# sourceMappingURL=daemon-backend.js.map

package/dist/src/cli/memory/daemon-write-client.js

@@ -1,22 +1,38 @@
 /**
- * Daemon write client (#981 / #984 — single-writer architecture).
+ * Daemon RPC client (#981 / #984 / #1058 — single-writer architecture and
+ * its read-side symmetry).
  *
- * HTTP client for the `POST /api/memory/{store,delete,batch}` RPC added by
- * Story #983. Lets short-lived CLI processes and the long-lived MCP server
- * route their `.moflo/moflo.db` writes through the daemon, which owns the
- * authoritative sql.js handle. Avoids the multi-process clobber from #981.
+ * HTTP client for the `POST /api/memory/{store,delete,batch,get,search,list}`
+ * RPC added by Stories #983 and #1058. Lets short-lived CLI processes and
+ * the long-lived MCP server route their `.moflo/moflo.db` operations through
+ * the daemon, which owns the authoritative sql.js handle. Avoids the
+ * multi-process write clobber from #981 AND the stale read snapshot from
+ * #1058 (sql.js never re-reads disk after init).
  *
  * Contract — every function in this module:
- *   - Never throws. Any error path returns `{ routed: false }`.
+ *   - Never throws. Outcomes are reported via the result envelope.
  *   - Returns within ≤100ms even if the daemon is dead/slow (HTTP timeout).
- *   - Caches daemon health for 5s to keep the hot write path cheap.
+ *   - Caches daemon health for 5s to keep the hot path cheap.
  *   - Short-circuits without HTTP when:
  *       (a) `process.env.MOFLO_IS_DAEMON === '1'` (daemon's own process)
  *       (b) `moflo.yaml` has `daemon.auto_start: false`
  *
- * Story #984 ships the client without any consumer wiring — Story #985 / #986
- * add the routing preamble inside `storeEntry` / `deleteEntry` (see
- * `docs/internal/981-writer-audit.md`).
+ * Failure-shape contract (#1101 — surface 4xx as a real error):
+ *   - 4xx response                 → `routed: true, ok: false, error: <msg>` (writes)
+ *                                  → `routed: true, error: <msg>` (reads)
+ *                                  → caller PROPAGATES the error; does NOT fall back.
+ *   - 5xx, 503, timeout,           → `routed: false`
+ *     ECONNREFUSED, malformed JSON,  → caller falls back to bridge-direct.
+ *     socket destroyed mid-stream
+ *
+ * The 4xx codes only fire on daemon-side payload validation (see
+ * daemon-memory-rpc.ts). Bridge-direct has the same validation and would
+ * fail the same way — falling back silently loses the daemon's actionable
+ * error message. 5xx and transport faults are transient/daemon-side bugs;
+ * bridge-direct is the right next step.
+ *
+ * Naming note: the module is named `daemon-write-client` for compat with
+ * existing importers, but as of #1058 it also covers reads.
  *
  * @module cli/memory/daemon-write-client
  */
@@ -136,6 +152,7 @@ export async function tryDaemonStore(opts) {
         value: opts.value,
         tags: opts.tags,
         ttl: opts.ttl,
+        metadata: opts.metadata,
     });
 }
 /**
@@ -150,9 +167,90 @@ export async function tryDaemonDelete(opts) {
         key: opts.key,
     });
 }
+/**
+ * Route a single-entry retrieve through the daemon (#1058). Returns
+ * `{ routed: false }` if the daemon is unavailable; otherwise
+ * `{ routed: true, data: { found, entry? } }`. The `entry` field is the
+ * same shape as `getEntry`'s in-process return.
+ */
+export async function tryDaemonGet(opts) {
+    if (!(await isDaemonAvailable()))
+        return { routed: false };
+    return postReadJson('/api/memory/get', { namespace: opts.namespace, key: opts.key }, (data) => ({
+        found: !!data?.found,
+        entry: data?.entry,
+    }));
+}
+/**
+ * Route a semantic search through the daemon (#1058).
+ */
+export async function tryDaemonSearch(opts) {
+    if (!(await isDaemonAvailable()))
+        return { routed: false };
+    return postReadJson('/api/memory/search', {
+        query: opts.query,
+        namespace: opts.namespace,
+        limit: opts.limit,
+        threshold: opts.threshold,
+    }, (data) => ({
+        results: Array.isArray(data?.results) ? data.results : [],
+        searchTime: typeof data?.searchTime === 'number' ? data.searchTime : undefined,
+    }));
+}
+/**
+ * Route a paginated list through the daemon (#1058).
+ */
+export async function tryDaemonList(opts) {
+    if (!(await isDaemonAvailable()))
+        return { routed: false };
+    return postReadJson('/api/memory/list', {
+        namespace: opts.namespace,
+        limit: opts.limit,
+        offset: opts.offset,
+    }, (data) => ({
+        entries: Array.isArray(data?.entries) ? data.entries : [],
+        total: typeof data?.total === 'number' ? data.total : 0,
+    }));
+}
 // ============================================================================
 // Internal HTTP poster — never throws, bounded timeout
 // ============================================================================
+/**
+ * Extract a human-readable error message from a daemon 4xx response body.
+ * Prefers `message` (the daemon's specific reason — e.g. "invalid namespace"),
+ * falls back to `error` (the daemon's error category), then to a generic
+ * status-code string when the body is non-JSON.
+ */
+function parse4xxError(buf, status) {
+    try {
+        const data = JSON.parse(buf);
+        const detail = typeof data?.message === 'string' ? data.message
+            : typeof data?.error === 'string' ? data.error
+                : undefined;
+        if (detail)
+            return detail;
+    }
+    catch {
+        // Non-JSON 4xx body — fall through to the generic message.
+    }
+    return `daemon returned ${status}`;
+}
+/**
+ * Narrow a parsed JSON value to the `{ dimensions, model }` embedding-response
+ * shape (#1065). Returns `undefined` when the field is missing or malformed —
+ * a malformed field is treated as "no embedding info" rather than failing the
+ * whole response, so an older daemon that hasn't been updated still works.
+ */
+function parseEmbeddingField(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const v = value;
+    if (typeof v.dimensions !== 'number' || !Number.isFinite(v.dimensions))
+        return undefined;
+    if (typeof v.model !== 'string' || v.model.length === 0)
+        return undefined;
+    return { dimensions: v.dimensions, model: v.model };
+}
 function postJson(path, body) {
     return new Promise((resolve) => {
         let done = false;
@@ -183,15 +281,23 @@ function postJson(path, body) {
             res.setEncoding('utf8');
             res.on('data', (chunk) => { buf += chunk; });
             res.on('end', () => {
-                // Status >=500 is a daemon-side fault; treat as unrouted so the
-                // caller falls back. Status 4xx (validation) is ALSO unrouted —
-                // we don't want a malformed payload silently lost just because
-                // the HTTP delivery succeeded.
+                // #1101 — per-shape failure contract:
+                //   2xx  → routed:true,  ok:true   (caller uses data)
+                //   4xx  → routed:true,  ok:false  (caller propagates daemon error)
+                //   5xx  → routed:false           (caller falls back to bridge)
+                //   parse fail → routed:false (fall back)
                 const status = res.statusCode ?? 0;
-                if (status < 200 || status >= 300) {
+                if (status >= 500 || status < 200) {
                     finish({ routed: false });
                     return;
                 }
+                if (status >= 400) {
+                    // Daemon validated the payload and rejected it. Bridge-direct
+                    // has the same validation; falling back loses the actionable
+                    // error. Surface it to the caller instead.
+                    finish({ routed: true, ok: false, error: parse4xxError(buf, status) });
+                    return;
+                }
                 try {
                     const data = JSON.parse(buf);
                     finish({
@@ -199,6 +305,7 @@ function postJson(path, body) {
                         ok: !!data?.ok,
                         id: typeof data?.id === 'string' ? data.id : undefined,
                         deleted: typeof data?.deleted === 'boolean' ? data.deleted : undefined,
+                        embedding: parseEmbeddingField(data?.embedding),
                         error: typeof data?.error === 'string' ? data.error : undefined,
                     });
                 }
@@ -214,4 +321,74 @@ function postJson(path, body) {
         req.end();
     });
 }
+/**
+ * Generic JSON POST that returns a daemon-read envelope. Same transport
+ * guarantees as `postJson`: never throws, bounded timeout, invalidates health
+ * cache on routed-failure.
+ *
+ * The `shape` callback maps the daemon's parsed JSON payload to the typed
+ * data shape the caller expects. Returning `null` from `shape` (or a parse
+ * failure) downgrades to `{ routed: false }` so the caller falls back.
+ */
+function postReadJson(path, body, shape) {
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            if (result.routed === false)
+                healthCache = null;
+            resolve(result);
+        };
+        const payload = JSON.stringify(body);
+        const req = http.request({
+            host: '127.0.0.1',
+            port: getDaemonPort(),
+            path,
+            method: 'POST',
+            timeout: DAEMON_HTTP_TIMEOUT_MS,
+            headers: {
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(payload),
+            },
+        }, (res) => {
+            let buf = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => { buf += chunk; });
+            res.on('end', () => {
+                // #1101 — mirror postJson contract for reads:
+                //   2xx  → routed:true with shaped data
+                //   4xx  → routed:true with error (no data) — caller propagates
+                //   5xx  → routed:false (caller falls back)
+                const status = res.statusCode ?? 0;
+                if (status >= 500 || status < 200) {
+                    finish({ routed: false });
+                    return;
+                }
+                if (status >= 400) {
+                    finish({ routed: true, error: parse4xxError(buf, status) });
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(buf);
+                    const shaped = shape(parsed);
+                    if (shaped === null) {
+                        finish({ routed: false });
+                        return;
+                    }
+                    finish({ routed: true, data: shaped });
+                }
+                catch {
+                    finish({ routed: false });
+                }
+            });
+            res.on('error', () => finish({ routed: false }));
+        });
+        req.on('error', () => finish({ routed: false }));
+        req.on('timeout', () => { req.destroy(); finish({ routed: false }); });
+        req.write(payload);
+        req.end();
+    });
+}
 //# sourceMappingURL=daemon-write-client.js.map