opensquid 0.5.395

package/dist/engine/config.js

@@ -0,0 +1,223 @@
+/**
+ * Engine binary discovery + persisted-path management.
+ *
+ * Resolution chain (per T.1 audit §J + src.legacy precedent):
+ *   1. `OPENSQUID_ENGINE_BIN` env var — explicit override, always wins
+ *   2. `~/.opensquid/engine-config.json` `engine_bin` field — persisted choice
+ *   3. Bundled npm optional dep (`opensquid-engine-<platform>-<arch>`)
+ *      — returns `null` until npm stubs ship (follow-up track)
+ *   4. Auto-search dev paths under `~/projects/*` and `~/work/*`
+ *   5. `loop-engine` on `$PATH`
+ *   6. `null` — caller surfaces a helpful error
+ *
+ * First successful resolution from (4) or (5) is persisted to
+ * `~/.opensquid/engine-config.json` so the next session skips the search.
+ * Bundled-binary hits (3) are NOT persisted because the path is
+ * deterministic from the npm install layout and persisting it would
+ * point at a stale `node_modules/` path after upgrades.
+ *
+ * The persisted file is engine-specific so it doesn't collide with the
+ * existing `~/.opensquid/config.json` written by the chat-daemon stack.
+ *
+ * Imports `OPENSQUID_HOME` from `runtime/paths.ts` so the data root
+ * honors the `OPENSQUID_HOME` env override (tests + relocatable installs).
+ */
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { OPENSQUID_HOME } from '../runtime/paths.js';
+import { resolveBundledEngineBin } from './resolver.js';
+const ENGINE_BIN_NAME = 'loop-engine';
+const ENGINE_CONFIG_FILE = 'engine-config.json';
+const DEFAULT_CONFIG = { version: 1 };
+function engineConfigPath() {
+    return path.join(OPENSQUID_HOME(), ENGINE_CONFIG_FILE);
+}
+export async function loadEngineConfig() {
+    let raw;
+    try {
+        raw = await fs.readFile(engineConfigPath(), 'utf8');
+    }
+    catch (e) {
+        // Missing file is the common-case (no persisted choice yet) —
+        // silent. Other read errors (EACCES, EIO) are unusual — warn so
+        // users know why their persisted engine_bin isn't being picked up.
+        const code = e.code;
+        if (code !== 'ENOENT') {
+            process.stderr.write(`[opensquid] engine-config read failed at ${engineConfigPath()} (${String(e)}); ` +
+                `using defaults.\n`);
+        }
+        return { ...DEFAULT_CONFIG };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed.version === 1)
+            return parsed;
+        // Wrong version — treat as malformed for the warning path below.
+        process.stderr.write(`[opensquid] engine-config at ${engineConfigPath()} has unexpected version=${String(parsed.version)} (want 1); using defaults.\n`);
+    }
+    catch (e) {
+        // Parse-error path is loud — a typo silently dropping the persisted
+        // engine_bin was the bug A.05 addresses. Return default to keep boot
+        // resilient but surface the cause so users can fix the file.
+        process.stderr.write(`[opensquid] engine-config parse failed at ${engineConfigPath()} (${String(e)}); ` +
+            `using defaults — fix or delete the file to silence this warning.\n`);
+    }
+    return { ...DEFAULT_CONFIG };
+}
+export async function saveEngineConfig(config) {
+    const p = engineConfigPath();
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.writeFile(p, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+/**
+ * Resolve the engine binary path using the priority chain above. Writes
+ * the resolved path back to config when discovered via search so the
+ * next session is instant. Returns `null` if no working binary could be
+ * located.
+ *
+ * **Re-resolution on every start** (T.7 / T.1.P): a persisted
+ * `engine_bin` that no longer points at an executable file is cleared
+ * from the config and the resolver falls through to bundled → dev →
+ * `$PATH`. This adds ~10-100ms (one extra `fs.stat`) but means a
+ * deleted / moved / freshly-rebuilt binary silently self-heals on the
+ * next start instead of failing loudly with `ENOENT`. Bundled hits
+ * are NOT persisted (deterministic from npm layout); dev-path + `$PATH`
+ * hits ARE persisted so subsequent sessions skip the search.
+ */
+export async function resolveEngineBin() {
+    const fromEnv = process.env.OPENSQUID_ENGINE_BIN?.trim();
+    if (fromEnv)
+        return fromEnv;
+    let config = await loadEngineConfig();
+    if (config.engine_bin) {
+        if (await isExecutable(config.engine_bin)) {
+            return config.engine_bin;
+        }
+        // Stale persisted path (binary deleted / moved / chmod -x).
+        // Clear + persist so subsequent calls don't repeat the stat.
+        delete config.engine_bin;
+        delete config.engine_bin_resolved_at;
+        await saveEngineConfig(config);
+        // Reload so the in-memory `config` matches what's on disk before
+        // the success-branch writes below mutate + save again.
+        config = await loadEngineConfig();
+    }
+    const bundled = resolveBundledEngineBin();
+    if (bundled && (await isExecutable(bundled))) {
+        // Do NOT persist — the npm layout determines this deterministically
+        // and persisting a `node_modules/` path makes upgrades hostile.
+        return bundled;
+    }
+    const found = await searchCommonPaths();
+    if (found) {
+        config.engine_bin = found;
+        config.engine_bin_resolved_at = new Date().toISOString();
+        await saveEngineConfig(config);
+        return found;
+    }
+    const onPath = await whichBinary(ENGINE_BIN_NAME);
+    if (onPath) {
+        config.engine_bin = onPath;
+        config.engine_bin_resolved_at = new Date().toISOString();
+        await saveEngineConfig(config);
+        return onPath;
+    }
+    return null;
+}
+/**
+ * Set the engine binary path explicitly and persist. Validates that the
+ * path points at an executable file before writing.
+ */
+export async function setEngineBin(binPath) {
+    const abs = path.resolve(binPath);
+    if (!(await isExecutable(abs))) {
+        throw new Error(`not an executable file: ${abs}`);
+    }
+    const config = await loadEngineConfig();
+    config.engine_bin = abs;
+    config.engine_bin_resolved_at = new Date().toISOString();
+    await saveEngineConfig(config);
+    return { resolved: abs };
+}
+/**
+ * Forget the persisted engine binary path. Forces re-discovery on the
+ * next `resolveEngineBin` call.
+ */
+export async function forgetEngineBin() {
+    const config = await loadEngineConfig();
+    delete config.engine_bin;
+    delete config.engine_bin_resolved_at;
+    await saveEngineConfig(config);
+}
+async function isExecutable(p) {
+    try {
+        const stat = await fs.stat(p);
+        if (!stat.isFile())
+            return false;
+        return (stat.mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Walk common dev-machine layouts looking for a release binary.
+ * Conservative — only checks paths that look like sibling projects of
+ * the user's `$HOME`. Returns the first hit.
+ *
+ * Covered layouts:
+ *   ~/projects/<*>/engine/target/release/loop-engine   (loop workspace)
+ *   ~/projects/<*>/target/release/loop-engine          (standalone engine repo)
+ *   ~/work/<*>/{engine,}/target/release/loop-engine    (alt convention)
+ */
+async function searchCommonPaths() {
+    const home = os.homedir();
+    const candidates = [];
+    const projectsRoot = path.join(home, 'projects');
+    try {
+        const dirs = await fs.readdir(projectsRoot, { withFileTypes: true });
+        for (const entry of dirs) {
+            if (!entry.isDirectory())
+                continue;
+            candidates.push(path.join(projectsRoot, entry.name, 'engine', 'target', 'release', ENGINE_BIN_NAME), path.join(projectsRoot, entry.name, 'target', 'release', ENGINE_BIN_NAME));
+        }
+    }
+    catch {
+        // ~/projects doesn't exist — skip.
+    }
+    const workRoot = path.join(home, 'work');
+    try {
+        const dirs = await fs.readdir(workRoot, { withFileTypes: true });
+        for (const entry of dirs) {
+            if (!entry.isDirectory())
+                continue;
+            candidates.push(path.join(workRoot, entry.name, 'engine', 'target', 'release', ENGINE_BIN_NAME), path.join(workRoot, entry.name, 'target', 'release', ENGINE_BIN_NAME));
+        }
+    }
+    catch {
+        // ~/work doesn't exist — skip.
+    }
+    for (const cand of candidates) {
+        if (await isExecutable(cand))
+            return cand;
+    }
+    return null;
+}
+/**
+ * Cross-platform `which` — search $PATH for an executable named `bin`.
+ * Returns absolute path or null.
+ */
+async function whichBinary(bin) {
+    const pathEnv = process.env.PATH ?? '';
+    const sep = process.platform === 'win32' ? ';' : ':';
+    for (const dir of pathEnv.split(sep)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, bin);
+        if (await isExecutable(candidate))
+            return candidate;
+    }
+    return null;
+}
+//# sourceMappingURL=config.js.map

package/dist/engine/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/engine/config.ts"],"names":[],"mappings":"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"}

package/dist/engine/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Barrel re-export for `opensquid` engine integration.
+ *
+ * Public surface:
+ *   - EngineClient + RpcError + ENGINE_ERROR (`./client.js`)
+ *   - resolveEngineBin / setEngineBin / forgetEngineBin / loadEngineConfig
+ *     (`./config.js`)
+ *   - resolveBundledEngineBin + platform probe helpers (`./resolver.js`)
+ *   - registerEngineCli + EngineCliError (`./cli.js`)
+ *   - All wire-shape types (`./types.js`)
+ */
+export { EngineClient, ENGINE_ERROR, RpcError } from './client.js';
+export { forgetEngineBin, loadEngineConfig, resolveEngineBin, saveEngineConfig, setEngineBin, type EngineConfig, } from './config.js';
+export { binaryNameForPlatform, currentPlatform, packageForPlatform, resolveBundledEngineBin, type PlatformProbe, } from './resolver.js';
+export { EngineCliError, registerEngineCli } from './cli.js';
+export type { CreateMemoryResult, GetMemoryResult, LessonCaptureFeedbackResult, LessonCreateParams, LessonCreateResult, LessonDiscardResult, LessonListResult, LessonListRow, LessonPromoteResult, LessonRecallHit, LessonRecallResult, LessonSupersedeResult, ManifestActiveLesson, ManifestAssembleParams, ManifestAssembleResult, ManifestMemory, MemoryDeleteResult, MemoryListResult, MemoryListRow, MemoryOrigin, MemoryScope, MemorySearchHit, MemorySearchParams, MemorySearchResult, MemoryUpdateResult, ScopeFilterWire, TaskGetLedgerResult, TaskLogPhaseResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7D,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,2BAA2B,EAC3B,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,YAAY,CAAC"}

package/dist/engine/index.js

@@ -0,0 +1,16 @@
+/**
+ * Barrel re-export for `opensquid` engine integration.
+ *
+ * Public surface:
+ *   - EngineClient + RpcError + ENGINE_ERROR (`./client.js`)
+ *   - resolveEngineBin / setEngineBin / forgetEngineBin / loadEngineConfig
+ *     (`./config.js`)
+ *   - resolveBundledEngineBin + platform probe helpers (`./resolver.js`)
+ *   - registerEngineCli + EngineCliError (`./cli.js`)
+ *   - All wire-shape types (`./types.js`)
+ */
+export { EngineClient, ENGINE_ERROR, RpcError } from './client.js';
+export { forgetEngineBin, loadEngineConfig, resolveEngineBin, saveEngineConfig, setEngineBin, } from './config.js';
+export { binaryNameForPlatform, currentPlatform, packageForPlatform, resolveBundledEngineBin, } from './resolver.js';
+export { EngineCliError, registerEngineCli } from './cli.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,GAEb,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,uBAAuB,GAExB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC"}

package/dist/engine/resolver.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Bundled-binary resolver for the loop-engine subprocess.
+ *
+ * Pattern: esbuild / biomejs / swc — main opensquid package would declare
+ * 6 platform-specific packages as `optionalDependencies`; each one ships
+ * a single binary at `bin/loop-engine` (or `.exe` on Windows). npm's
+ * `os`/`cpu` fields cause wrong-platform packages to skip install, so on
+ * any given host exactly one optional dep is present and provides the
+ * right binary.
+ *
+ * NOTE: opensquid 0.5.108 ships LOCAL-BUILD ONLY (per T.1.J §10). The
+ * `optionalDependencies` block is not yet declared in package.json — npm
+ * stubs land in a follow-up track. This resolver returns `null` on every
+ * call until then, and callers fall through to `config.ts` dev-path +
+ * `$PATH` discovery. The mapping table is kept now so the wiring is
+ * already correct when stubs land.
+ *
+ * Runtime path:
+ *   1. Map `(process.platform, process.arch)` → optional-dep name.
+ *   2. Try `createRequire(import.meta.url).resolve(...)` on that
+ *      package's package.json. Returns `<dir>/bin/<name>` if installed.
+ *   3. If not installed (npm `--no-optional`, wrong-platform install,
+ *      local pre-publish dev), return `null`. Caller falls back to the
+ *      dev-path + $PATH chain in `config.ts`.
+ *
+ * Resolution is synchronous + side-effect-free.
+ */
+export interface PlatformProbe {
+    platform: NodeJS.Platform;
+    arch: string;
+}
+/**
+ * Compute the (platform, arch) tuple for the current process. Wrapped
+ * for unit testability — tests inject a synthetic probe.
+ */
+export declare function currentPlatform(): PlatformProbe;
+/**
+ * Look up the optional-dep package name for a given platform. Returns
+ * `null` when the (platform, arch) pair isn't in the supported matrix.
+ */
+export declare function packageForPlatform(probe: PlatformProbe): string | null;
+/**
+ * Look up the binary filename for a given platform (`.exe` on Windows).
+ */
+export declare function binaryNameForPlatform(probe: PlatformProbe): string | null;
+/**
+ * Resolve the bundled binary path via the optional-dep mechanism.
+ *
+ * Returns `null` when:
+ *   - the current (platform, arch) isn't in the supported matrix,
+ *   - the optional dep isn't installed (pre-publish dev, npm
+ *     `--no-optional`, wrong-platform install), or
+ *   - the dep is installed but the expected `bin/<name>` file is missing
+ *     (broken publish — diagnostic-only; caller falls through).
+ *
+ * v0.6c audit fix: use `path.dirname + path.join` not string slice — on
+ * Windows `require.resolve` returns `\` separators; slicing on the
+ * `"/package.json".length` suffix would silently mis-strip and the
+ * concatenation would mix separators.
+ */
+export declare function resolveBundledEngineBin(probe?: PlatformProbe): string | null;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/engine/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/engine/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAoCH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,aAAa,CAE/C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAGtE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAGzE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,GAAE,aAAiC,GAAG,MAAM,GAAG,IAAI,CAa/F"}

package/dist/engine/resolver.js

@@ -0,0 +1,103 @@
+/**
+ * Bundled-binary resolver for the loop-engine subprocess.
+ *
+ * Pattern: esbuild / biomejs / swc — main opensquid package would declare
+ * 6 platform-specific packages as `optionalDependencies`; each one ships
+ * a single binary at `bin/loop-engine` (or `.exe` on Windows). npm's
+ * `os`/`cpu` fields cause wrong-platform packages to skip install, so on
+ * any given host exactly one optional dep is present and provides the
+ * right binary.
+ *
+ * NOTE: opensquid 0.5.108 ships LOCAL-BUILD ONLY (per T.1.J §10). The
+ * `optionalDependencies` block is not yet declared in package.json — npm
+ * stubs land in a follow-up track. This resolver returns `null` on every
+ * call until then, and callers fall through to `config.ts` dev-path +
+ * `$PATH` discovery. The mapping table is kept now so the wiring is
+ * already correct when stubs land.
+ *
+ * Runtime path:
+ *   1. Map `(process.platform, process.arch)` → optional-dep name.
+ *   2. Try `createRequire(import.meta.url).resolve(...)` on that
+ *      package's package.json. Returns `<dir>/bin/<name>` if installed.
+ *   3. If not installed (npm `--no-optional`, wrong-platform install,
+ *      local pre-publish dev), return `null`. Caller falls back to the
+ *      dev-path + $PATH chain in `config.ts`.
+ *
+ * Resolution is synchronous + side-effect-free.
+ */
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+/**
+ * Supported targets and their optional-dep package names. Stays in sync
+ * with `optionalDependencies` in package.json (when added) and with the
+ * loop-engine release matrix. If you change any of those, change all.
+ */
+const PACKAGE_FOR_PLATFORM = {
+    'darwin-x64': 'opensquid-engine-darwin-x64',
+    'darwin-arm64': 'opensquid-engine-darwin-arm64',
+    'linux-x64': 'opensquid-engine-linux-x64',
+    'linux-arm64': 'opensquid-engine-linux-arm64',
+    'win32-x64': 'opensquid-engine-win32-x64',
+    'win32-arm64': 'opensquid-engine-win32-arm64',
+};
+const BIN_NAME_FOR_PLATFORM = {
+    'darwin-x64': 'loop-engine',
+    'darwin-arm64': 'loop-engine',
+    'linux-x64': 'loop-engine',
+    'linux-arm64': 'loop-engine',
+    'win32-x64': 'loop-engine.exe',
+    'win32-arm64': 'loop-engine.exe',
+};
+/**
+ * Compute the (platform, arch) tuple for the current process. Wrapped
+ * for unit testability — tests inject a synthetic probe.
+ */
+export function currentPlatform() {
+    return { platform: process.platform, arch: process.arch };
+}
+/**
+ * Look up the optional-dep package name for a given platform. Returns
+ * `null` when the (platform, arch) pair isn't in the supported matrix.
+ */
+export function packageForPlatform(probe) {
+    const key = `${probe.platform}-${probe.arch}`;
+    return PACKAGE_FOR_PLATFORM[key] ?? null;
+}
+/**
+ * Look up the binary filename for a given platform (`.exe` on Windows).
+ */
+export function binaryNameForPlatform(probe) {
+    const key = `${probe.platform}-${probe.arch}`;
+    return BIN_NAME_FOR_PLATFORM[key] ?? null;
+}
+/**
+ * Resolve the bundled binary path via the optional-dep mechanism.
+ *
+ * Returns `null` when:
+ *   - the current (platform, arch) isn't in the supported matrix,
+ *   - the optional dep isn't installed (pre-publish dev, npm
+ *     `--no-optional`, wrong-platform install), or
+ *   - the dep is installed but the expected `bin/<name>` file is missing
+ *     (broken publish — diagnostic-only; caller falls through).
+ *
+ * v0.6c audit fix: use `path.dirname + path.join` not string slice — on
+ * Windows `require.resolve` returns `\` separators; slicing on the
+ * `"/package.json".length` suffix would silently mis-strip and the
+ * concatenation would mix separators.
+ */
+export function resolveBundledEngineBin(probe = currentPlatform()) {
+    const pkg = packageForPlatform(probe);
+    const binName = binaryNameForPlatform(probe);
+    if (!pkg || !binName)
+        return null;
+    const req = createRequire(import.meta.url);
+    try {
+        const pkgJson = req.resolve(`${pkg}/package.json`);
+        return path.join(path.dirname(pkgJson), 'bin', binName);
+    }
+    catch {
+        // MODULE_NOT_FOUND — optional dep not installed for this host.
+        return null;
+    }
+}
+//# sourceMappingURL=resolver.js.map

package/dist/engine/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../src/engine/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAUlC;;;;GAIG;AACH,MAAM,oBAAoB,GAAgC;IACxD,YAAY,EAAE,6BAA6B;IAC3C,cAAc,EAAE,+BAA+B;IAC/C,WAAW,EAAE,4BAA4B;IACzC,aAAa,EAAE,8BAA8B;IAC7C,WAAW,EAAE,4BAA4B;IACzC,aAAa,EAAE,8BAA8B;CAC9C,CAAC;AAEF,MAAM,qBAAqB,GAAgC;IACzD,YAAY,EAAE,aAAa;IAC3B,cAAc,EAAE,aAAa;IAC7B,WAAW,EAAE,aAAa;IAC1B,aAAa,EAAE,aAAa;IAC5B,WAAW,EAAE,iBAAiB;IAC9B,aAAa,EAAE,iBAAiB;CACjC,CAAC;AAOF;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;AAC5D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAoB;IACrD,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAiB,CAAC;IAC7D,OAAO,oBAAoB,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAoB;IACxD,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAiB,CAAC;IAC7D,OAAO,qBAAqB,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAuB,eAAe,EAAE;IAC9E,MAAM,GAAG,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAC7C,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAElC,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,GAAG,eAAe,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;QAC/D,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/engine/singleton.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Daemon-singleton acquire-or-spawn for the loop-engine UDS daemon.
+ *
+ * One engine process per host. All opensquid hooks + sessions share
+ * the same engine over a Unix domain socket at
+ * `~/.opensquid/loop-engine.sock`. This is the keystone for cross-
+ * session memory recall — session A writes a memory, session B reads
+ * it through the same engine without per-process spawn cost.
+ *
+ * Flow (per spec T.4 / audit T.1.Y + T.1.Z + T.1.BB + T.1.DD):
+ *
+ *  1. Windows guard — UDS is Unix-only; named-pipe support is a
+ *     follow-up. Windows callers fall back to per-process stdio spawn
+ *     by setting `OPENSQUID_ENGINE_SOCKET=disable` upstream.
+ *
+ *  2. Path-byte guard — macOS limits UDS paths to 104 bytes (Linux
+ *     108). `~/.opensquid/loop-engine.sock` ≈ 30 chars on typical
+ *     homes, but exotic `$HOME` values can exceed it. Refuse at 100
+ *     to leave margin.
+ *
+ *  3. Fast path — if the socket file exists, try to connect. Success
+ *     means an engine is already running; return the socket with
+ *     `spawnedByUs: false`. ECONNREFUSED means the file is stale (a
+ *     previous engine crashed without unlinking); unlink and fall
+ *     through to the spawn path.
+ *
+ *  4. Slow path (lock + spawn):
+ *     a. Touch `~/.opensquid/loop-engine.lock` so `proper-lockfile`
+ *        has a stable inode to lock against.
+ *     b. Acquire the lock with retry — serializes concurrent spawn
+ *        attempts across multiple opensquid processes.
+ *     c. RECHECK after the lock: another process may have spawned
+ *        the engine while we waited. If yes, connect + return.
+ *     d. Resolve the engine binary via existing `resolveEngineBin()`.
+ *     e. Spawn detached + `stdio: 'ignore'` so the engine outlives
+ *        the parent (true daemon semantics). `'inherit'` would hold
+ *        the parent's stdout/stderr pipes open and block parent exit
+ *        (per subprocess-lifecycle audit). Engine logs route to
+ *        /dev/null in this mode; `RUST_LOG=...` + a redirect-to-file
+ *        is the workaround if diagnostics are needed.
+ *     f. Write `~/.opensquid/loop-engine.pid` with the spawned pid
+ *        BEFORE `proc.unref()` so T.7's `engine kill` command can
+ *        find it.
+ *     g. `proc.unref()` — let the parent event loop exit without
+ *        waiting on the engine.
+ *     h. Wait for the socket file to appear (engine binds before
+ *        accept; 10s budget covers cold-start HNSW rehydrate of
+ *        ~76 memories on typical hardware).
+ *     i. Connect; return with `spawnedByUs: true`.
+ *
+ *  5. Always release the lock in a `finally` block.
+ *
+ * NOT a singleton class — exported as a plain async function so
+ * callers can compose / inject without instance state. Concurrency
+ * safety lives in `proper-lockfile`, not in this module.
+ */
+import { type Socket } from 'node:net';
+/** Engine socket path. Override `OPENSQUID_HOME` to relocate. */
+export declare function engineSocketPath(): string;
+/** Lock file used to serialize concurrent spawn attempts. */
+export declare function engineLockPath(): string;
+/**
+ * Pidfile path used by `engine kill` (T.7). Written after spawn
+ * returns, before `unref()`. Note: the engine process itself does
+ * NOT manage this file — opensquid owns its lifecycle since opensquid
+ * is the one that spawned the engine. T.7 will add a startup-time
+ * cleanup hook for the spawned-by-us case.
+ */
+export declare function enginePidPath(): string;
+export interface EngineConnection {
+    /** Connected socket to the engine's UDS endpoint. */
+    socket: Socket;
+    /**
+     * `true` when this caller's invocation was the one that spawned the
+     * engine process (cold start path). `false` when an existing engine
+     * was found and connected to (warm path). Useful for telemetry +
+     * test assertions; production callers usually ignore it.
+     */
+    spawnedByUs: boolean;
+}
+/**
+ * Acquire a connection to the shared loop-engine daemon, spawning
+ * one if none is running. Safe to call concurrently from multiple
+ * processes — `proper-lockfile` serializes spawn attempts so only
+ * one engine starts per `~/.opensquid/loop-engine.sock` lifetime.
+ *
+ * Throws on:
+ *  - Windows (UDS unsupported; use stdio mode upstream)
+ *  - socket path exceeds platform byte limit
+ *  - engine binary not resolvable
+ *  - socket never appears within `SOCKET_WAIT_TIMEOUT_MS`
+ *  - underlying spawn / connect / lock errors
+ */
+export declare function acquireOrSpawnEngine(): Promise<EngineConnection>;
+//# sourceMappingURL=singleton.d.ts.map

package/dist/engine/singleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.d.ts","sourceRoot":"","sources":["../../src/engine/singleton.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAKH,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAoChD,iEAAiE;AACjE,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,6DAA6D;AAC7D,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAcD,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAkJtE"}