@rynx-ai/daemon 0.1.10 → 0.1.11-beta.10

package/dist/pm2.d.ts

@@ -8,12 +8,21 @@ export declare function formatControlUrl(host: string, port: number): string;
  * entry from scratch (delete + start) so config flags are always fresh; the
  * `force === false` path short-circuits when it's already online.
  */
-export declare function startDaemon({ force, quiet }: {
+export declare function startDaemon({ force, quiet, launchEnvironment, }: {
     force: boolean;
     quiet?: boolean;
+    launchEnvironment?: NodeJS.ProcessEnv;
 }): number;
 export declare function isPm2DaemonOnline(): boolean;
-/** Stop and remove the daemon from pm2's process list. */
+/**
+ * Stop the daemon and terminate its dedicated pm2 supervisor.
+ *
+ * PM2_HOME lives below RYNX_HOME, so this supervisor cannot own unrelated
+ * applications. Leaving it alive across an npm replacement is unsafe: the
+ * daemon process container path is resolved inside the old pm2 package. Once
+ * npm swaps @rynx-ai/daemon, that cached path may no longer exist and every
+ * subsequent `rynx start` enters a restart loop before our code can run.
+ */
 export declare function stopDaemon(): number;
 /** Print a one-line status; exit 0 only when online. */
 export declare function statusDaemon(): number;

package/dist/pm2.js

@@ -10,15 +10,18 @@
 import { spawn, spawnSync } from "node:child_process";
 import { mkdirSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { loadConfig } from "@rynx-ai/core";
+import { userInfo } from "node:os";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { loadConfig, rynxHome } from "@rynx-ai/core";
 import { daemonEntryRestartRequired } from "./daemon-build-status.js";
+import { resolveDaemonEntry } from "./entry-path.js";
 const require = createRequire(import.meta.url);
 /** pm2 app name — single resident daemon per machine. */
 const APP_NAME = "rynx";
 const PM2_COMMAND_TIMEOUT_MS = 5_000;
+const LOGIN_SHELL_PATH_TIMEOUT_MS = 5_000;
+const LOGIN_SHELL_PATH_MAX_BYTES = 256 * 1024;
+const REFRESH_LOGIN_SHELL_PATH_ENV = "RYNX_REFRESH_LOGIN_SHELL_PATH";
 const DAEMON_PACKAGE_VERSION = require("../package.json").version;
 /**
  * Build a dialable control-console URL from the daemon's bind host/port. Bind-all
@@ -50,27 +53,76 @@ function pm2Bin() {
     // pm2 ships its CLI at bin/pm2; run it with our own node.
     return require.resolve("pm2/bin/pm2");
 }
-/** `index-daemon.js` sits next to this file in `dist/`. */
-function daemonEntryPath() {
-    return join(dirname(fileURLToPath(import.meta.url)), "index-daemon.js");
-}
 function logsDir() {
-    const home = process.env.RYNX_HOME?.trim() || join(homedir(), ".rynx");
-    const dir = join(home, "logs");
+    const dir = join(rynxHome(), "logs");
     mkdirSync(dir, { recursive: true });
     return dir;
 }
 function nodeRuntimeEnv() {
-    if (!process.versions.electron) {
-        return process.env;
+    const home = rynxHome();
+    const pm2Home = join(home, "pm2");
+    mkdirSync(pm2Home, { recursive: true, mode: 0o700 });
+    return {
+        ...process.env,
+        RYNX_HOME: home,
+        PM2_HOME: pm2Home,
+        ...(process.versions.electron
+            ? { ELECTRON_RUN_AS_NODE: "1" }
+            : {}),
+    };
+}
+/**
+ * A detached plugin updater intentionally receives a reduced environment and
+ * therefore has no SHELL. Starting the replacement daemon with that reduced
+ * PATH would make user-installed runtimes (for example an fnm-managed Codex)
+ * disappear after every upgrade. Recover the user's login-shell PATH only at
+ * this boundary; normal interactive starts keep their exact caller environment.
+ */
+function daemonStartEnv() {
+    const env = nodeRuntimeEnv();
+    const refreshLoginPath = env[REFRESH_LOGIN_SHELL_PATH_ENV] === "1";
+    delete env[REFRESH_LOGIN_SHELL_PATH_ENV];
+    if (!refreshLoginPath)
+        return env;
+    const shell = userInfo().shell?.trim();
+    if (!shell) {
+        throw new Error("cannot refresh daemon PATH: the user login shell is unavailable");
+    }
+    const result = spawnSync(shell, ["-lic", `printf '\\036%s\\037' "$PATH"`], {
+        encoding: "utf8",
+        // Do not feed an fnm/nvm "multishell" directory inherited from the old
+        // daemon back into the next login shell. Version managers prepend a new
+        // directory on every shell startup, so reusing the old PATH would grow
+        // it indefinitely across upgrades.
+        env: { ...env, SHELL: shell, PATH: loginShellBaselinePath() },
+        timeout: LOGIN_SHELL_PATH_TIMEOUT_MS,
+        killSignal: "SIGTERM",
+        maxBuffer: LOGIN_SHELL_PATH_MAX_BYTES,
+    });
+    if (result.error) {
+        throw new Error(`cannot refresh daemon PATH: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`cannot refresh daemon PATH: login shell exited ${result.status ?? "without status"}`);
     }
-    return { ...process.env, ELECTRON_RUN_AS_NODE: "1" };
+    const path = extractFramedPath(result.stdout);
+    if (!path) {
+        throw new Error("cannot refresh daemon PATH: login shell returned no framed PATH");
+    }
+    const npmPrefix = env.NPM_CONFIG_PREFIX?.trim();
+    const npmBin = npmPrefix && isAbsolute(npmPrefix)
+        ? join(npmPrefix, "bin")
+        : "";
+    const refreshedPath = npmBin === ""
+        ? path
+        : [npmBin, ...path.split(delimiter).filter((entry) => entry !== npmBin)].join(delimiter);
+    return { ...env, PATH: refreshedPath, SHELL: shell };
 }
 /** Run a pm2 command inheriting stdio; returns its exit code. */
-function runPm2(args, quiet = false) {
+function runPm2(args, quiet = false, env = nodeRuntimeEnv()) {
     const res = spawnSync(process.execPath, [pm2Bin(), ...args], {
         stdio: quiet ? "ignore" : "inherit",
-        env: nodeRuntimeEnv(),
+        env,
         timeout: PM2_COMMAND_TIMEOUT_MS,
         killSignal: "SIGTERM",
     });
@@ -112,7 +164,7 @@ function pm2ErrorMessage(error) {
  * entry from scratch (delete + start) so config flags are always fresh; the
  * `force === false` path short-circuits when it's already online.
  */
-export function startDaemon({ force, quiet = false }) {
+export function startDaemon({ force, quiet = false, launchEnvironment, }) {
     let existing;
     try {
         existing = describe();
@@ -134,6 +186,20 @@ export function startDaemon({ force, quiet = false }) {
     if (staleBuild && !quiet) {
         console.log("A newer daemon build is present on disk; restarting Rynx.");
     }
+    let startEnv;
+    try {
+        // Resolve the replacement environment before deleting an existing app.
+        // A broken/hung login shell must leave the known-good daemon untouched.
+        startEnv = {
+            ...daemonStartEnv(),
+            ...launchEnvironment,
+        };
+    }
+    catch (error) {
+        if (!quiet)
+            console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
     const dir = logsDir();
     if (existing) {
         const removed = runPm2(["delete", APP_NAME], quiet);
@@ -142,12 +208,12 @@ export function startDaemon({ force, quiet = false }) {
     }
     const status = runPm2([
         "start",
-        daemonEntryPath(),
+        resolveDaemonEntry(),
         "--name",
         APP_NAME,
-        // Resolve `.env` relative to where the user invoked `rynx start`.
+        // App and CLI share one daemon-owned state/workspace root.
         "--cwd",
-        process.cwd(),
+        rynxHome(),
         "--max-restarts",
         "10",
         "--restart-delay",
@@ -158,7 +224,7 @@ export function startDaemon({ force, quiet = false }) {
         join(dir, "err.log"),
         "--merge-logs",
         "--time",
-    ], quiet);
+    ], quiet, startEnv);
     if (status === 0 && !quiet) {
         console.log(`rynx ${force ? "restarted" : "started"} (pm2 app "${APP_NAME}", logs: ${dir}).`);
         console.log(`Control console: ${styleUrl(controlConsoleUrl())}`);
@@ -168,16 +234,35 @@ export function startDaemon({ force, quiet = false }) {
 export function isPm2DaemonOnline() {
     return describe()?.pm2_env?.status === "online";
 }
-/** Stop and remove the daemon from pm2's process list. */
+/**
+ * Stop the daemon and terminate its dedicated pm2 supervisor.
+ *
+ * PM2_HOME lives below RYNX_HOME, so this supervisor cannot own unrelated
+ * applications. Leaving it alive across an npm replacement is unsafe: the
+ * daemon process container path is resolved inside the old pm2 package. Once
+ * npm swaps @rynx-ai/daemon, that cached path may no longer exist and every
+ * subsequent `rynx start` enters a restart loop before our code can run.
+ */
 export function stopDaemon() {
-    if (!describe()) {
+    const existing = describe();
+    if (!existing) {
+        // Even an empty process list can belong to a resident PM2 daemon whose
+        // module path is about to be replaced. `pm2 kill` is idempotent and is
+        // the only reliable package-upgrade boundary.
+        const killed = runPm2(["kill"], true);
+        if (killed !== 0)
+            return killed;
         console.log("rynx is not running.");
         return 0;
     }
-    const status = runPm2(["delete", APP_NAME]);
-    if (status === 0)
-        console.log("rynx stopped.");
-    return status;
+    const removed = runPm2(["delete", APP_NAME]);
+    if (removed !== 0)
+        return removed;
+    const killed = runPm2(["kill"]);
+    if (killed !== 0)
+        return killed;
+    console.log("rynx stopped.");
+    return 0;
 }
 /** Print a one-line status; exit 0 only when online. */
 export function statusDaemon() {
@@ -204,7 +289,7 @@ export function streamLogs() {
 }
 function residentBuildRestartRequired(app) {
     const runningEntry = app.pm2_env?.pm_exec_path;
-    if (runningEntry && !sameEntryPath(runningEntry, daemonEntryPath()))
+    if (runningEntry && !sameEntryPath(runningEntry, resolveDaemonEntry()))
         return true;
     const runningVersion = app.pm2_env?.version;
     if (runningVersion &&
@@ -215,7 +300,7 @@ function residentBuildRestartRequired(app) {
     const startedAt = app.pm2_env?.pm_uptime;
     return typeof startedAt === "number" &&
         Number.isFinite(startedAt) &&
-        daemonEntryRestartRequired(daemonEntryPath(), startedAt);
+        daemonEntryRestartRequired(resolveDaemonEntry(), startedAt);
 }
 function sameEntryPath(left, right) {
     try {
@@ -225,3 +310,20 @@ function sameEntryPath(left, right) {
         return resolve(left) === resolve(right);
     }
 }
+function extractFramedPath(stdout) {
+    if (!stdout)
+        return undefined;
+    const start = stdout.lastIndexOf("\x1e");
+    if (start < 0)
+        return undefined;
+    const end = stdout.indexOf("\x1f", start + 1);
+    if (end < 0)
+        return undefined;
+    const value = stdout.slice(start + 1, end);
+    return value.trim() ? value : undefined;
+}
+function loginShellBaselinePath() {
+    return process.platform === "darwin"
+        ? "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+        : "/usr/local/bin:/usr/bin:/bin";
+}

package/dist/process.d.ts

@@ -0,0 +1,12 @@
+interface SupervisorProcess {
+    connected?: boolean;
+    disconnect?: () => void;
+}
+/** Release a parent/supervisor IPC handle after graceful daemon shutdown. */
+export declare function disconnectSupervisorIpc(target?: SupervisorProcess): void;
+/**
+ * Run the daemon in the current process. Process ownership and executable
+ * selection belong to the caller (CLI standalone lifecycle or App lifecycle).
+ */
+export declare function runDaemonProcess(): Promise<void>;
+export {};

package/dist/process.js

@@ -0,0 +1,91 @@
+import { startRynxDaemonServer } from "./daemon-server.js";
+import { ensureBundledOfficialPlugins } from "./bundled-plugins.js";
+import { installStdioEpipeGuard } from "./stdio-epipe-guard.js";
+/** Release a parent/supervisor IPC handle after graceful daemon shutdown. */
+export function disconnectSupervisorIpc(target = process) {
+    if (target.connected && typeof target.disconnect === "function") {
+        target.disconnect();
+    }
+}
+/**
+ * Run the daemon in the current process. Process ownership and executable
+ * selection belong to the caller (CLI standalone lifecycle or App lifecycle).
+ */
+export async function runDaemonProcess() {
+    installStdioEpipeGuard();
+    const followsApp = process.env.RYNX_DAEMON_LIFECYCLE === "follow-app";
+    let parentDisconnected = followsApp && !process.connected;
+    const recordParentDisconnect = () => {
+        parentDisconnected = true;
+    };
+    if (followsApp)
+        process.once("disconnect", recordParentDisconnect);
+    const preparePlugins = async () => {
+        try {
+            const bundled = await ensureBundledOfficialPlugins({ reclaimHostLeases: true });
+            if (bundled.status === "ready") {
+                console.log(JSON.stringify({
+                    level: "info",
+                    type: "bundled_plugins_ready",
+                    installed: bundled.installed,
+                    updated: bundled.updated,
+                }));
+            }
+        }
+        catch (error) {
+            console.error(JSON.stringify({
+                level: "error",
+                type: "bundled_plugins_failed",
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    };
+    let server;
+    try {
+        server = await startRynxDaemonServer({
+            preparePlugins,
+            onShutdownComplete: () => disconnectSupervisorIpc(),
+        });
+    }
+    catch (error) {
+        process.off("disconnect", recordParentDisconnect);
+        throw error;
+    }
+    let shutdownPromise;
+    const shutdown = (signal) => {
+        if (shutdownPromise)
+            return shutdownPromise;
+        process.off("SIGINT", onSigint);
+        process.off("SIGTERM", onSigterm);
+        process.off("disconnect", onDisconnect);
+        shutdownPromise = (async () => {
+            console.log(JSON.stringify({ level: "info", type: "shutdown", signal }));
+            await server.shutdown();
+        })();
+        shutdownPromise.catch((error) => {
+            process.exitCode = 1;
+            console.error(`Shutdown failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+        });
+        return shutdownPromise;
+    };
+    const onSigint = () => {
+        void shutdown("SIGINT");
+    };
+    const onSigterm = () => {
+        void shutdown("SIGTERM");
+    };
+    const onDisconnect = () => {
+        if (process.env.RYNX_DAEMON_LIFECYCLE === "follow-app") {
+            void shutdown("APP_DISCONNECT");
+        }
+    };
+    process.once("SIGINT", onSigint);
+    process.once("SIGTERM", onSigterm);
+    if (followsApp) {
+        process.once("disconnect", onDisconnect);
+        process.off("disconnect", recordParentDisconnect);
+        if (parentDisconnected || !process.connected) {
+            void shutdown("APP_DISCONNECT");
+        }
+    }
+}

package/dist/runtime-project-store.d.ts

@@ -0,0 +1,9 @@
+import { type RuntimeProject, type RuntimeProjectInput, type RuntimeProjectStore } from "@rynx-ai/core";
+/** SQLite-backed Project catalog owned by the current target Runtime. */
+export declare class SqliteRuntimeProjectStore implements RuntimeProjectStore {
+    list(): Promise<RuntimeProject[]>;
+    get(id: string): Promise<RuntimeProject | undefined>;
+    create(input: RuntimeProjectInput): Promise<RuntimeProject>;
+    update(id: string, input: RuntimeProjectInput): Promise<RuntimeProject | undefined>;
+    remove(id: string): Promise<boolean>;
+}

package/dist/runtime-project-store.js

@@ -0,0 +1,83 @@
+import { randomUUID } from "node:crypto";
+import { canonicalizeRuntimeProjectInput, runtimeProjectSchema, } from "@rynx-ai/core";
+import { db } from "./db.js";
+const COLUMNS = "id, name, directories_json, primary_dir, created_at, updated_at";
+/** SQLite-backed Project catalog owned by the current target Runtime. */
+export class SqliteRuntimeProjectStore {
+    async list() {
+        return db()
+            .prepare(`SELECT ${COLUMNS} FROM runtime_projects ORDER BY updated_at DESC, id`)
+            .all()
+            .map((row) => rowToProject(row));
+    }
+    async get(id) {
+        const row = db()
+            .prepare(`SELECT ${COLUMNS} FROM runtime_projects WHERE id = ?`)
+            .get(id);
+        return row ? rowToProject(row) : undefined;
+    }
+    async create(input) {
+        const resolved = await canonicalizeRuntimeProjectInput(input);
+        const timestamp = new Date().toISOString();
+        const project = {
+            id: randomUUID(),
+            ...resolved,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+        };
+        const parsed = runtimeProjectSchema.parse(project);
+        db()
+            .prepare(`INSERT INTO runtime_projects
+           (id, name, directories_json, primary_dir, created_at, updated_at)
+         VALUES (@id, @name, @directories, @primary, @createdAt, @updatedAt)`)
+            .run({
+            id: parsed.id,
+            name: parsed.name,
+            directories: JSON.stringify(parsed.directories),
+            primary: parsed.primary,
+            createdAt: parsed.createdAt,
+            updatedAt: parsed.updatedAt,
+        });
+        return parsed;
+    }
+    async update(id, input) {
+        const current = await this.get(id);
+        if (!current)
+            return undefined;
+        const resolved = await canonicalizeRuntimeProjectInput(input);
+        const project = runtimeProjectSchema.parse({
+            id: current.id,
+            ...resolved,
+            createdAt: current.createdAt,
+            updatedAt: new Date().toISOString(),
+        });
+        db()
+            .prepare(`UPDATE runtime_projects
+         SET name = @name,
+             directories_json = @directories,
+             primary_dir = @primary,
+             updated_at = @updatedAt
+         WHERE id = @id`)
+            .run({
+            id: project.id,
+            name: project.name,
+            directories: JSON.stringify(project.directories),
+            primary: project.primary,
+            updatedAt: project.updatedAt,
+        });
+        return project;
+    }
+    async remove(id) {
+        return db().prepare("DELETE FROM runtime_projects WHERE id = ?").run(id).changes > 0;
+    }
+}
+function rowToProject(row) {
+    return runtimeProjectSchema.parse({
+        id: row.id,
+        name: row.name,
+        directories: JSON.parse(row.directories_json),
+        primary: row.primary_dir,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    });
+}

package/dist/session-fallback-workspace.d.ts

@@ -0,0 +1,22 @@
+import { type SessionWorkspaceSnapshot } from "@rynx-ai/core";
+export interface SessionFallbackRootOptions {
+    platform?: NodeJS.Platform;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    readTextFile?: (path: string) => Promise<string>;
+}
+export interface SessionFallbackWorkspaceOptions extends SessionFallbackRootOptions {
+    now?: () => Date;
+    randomId?: () => string;
+}
+/**
+ * Resolve the user-visible root for Sessions created without a Project.
+ *
+ * Linux desktop environments can localize or relocate Documents through the
+ * XDG user-dirs file. Headless installations commonly omit that file, so they
+ * fall back to a visible `$HOME/Rynx` instead of creating an arbitrary
+ * `$HOME/Documents` tree. Other platforms retain the existing Documents root.
+ */
+export declare function resolveSessionFallbackRoot(options?: SessionFallbackRootOptions): Promise<string>;
+export declare function createSessionFallbackWorkspace(options?: SessionFallbackWorkspaceOptions): Promise<SessionWorkspaceSnapshot>;
+export declare function discardSessionFallbackWorkspace(workspace: SessionWorkspaceSnapshot, options?: SessionFallbackRootOptions): Promise<void>;

package/dist/session-fallback-workspace.js

@@ -0,0 +1,120 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, realpath, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, normalize, relative } from "node:path";
+import { sessionWorkspaceSnapshotSchema, } from "@rynx-ai/core";
+/**
+ * Resolve the user-visible root for Sessions created without a Project.
+ *
+ * Linux desktop environments can localize or relocate Documents through the
+ * XDG user-dirs file. Headless installations commonly omit that file, so they
+ * fall back to a visible `$HOME/Rynx` instead of creating an arbitrary
+ * `$HOME/Documents` tree. Other platforms retain the existing Documents root.
+ */
+export async function resolveSessionFallbackRoot(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const home = normalize(options.home ?? homedir());
+    if (!isAbsolute(home))
+        throw new Error("Session fallback home must be absolute");
+    if (platform !== "linux")
+        return join(home, "Documents", "Rynx");
+    const env = options.env ?? process.env;
+    const configHome = env.XDG_CONFIG_HOME && isAbsolute(env.XDG_CONFIG_HOME)
+        ? normalize(env.XDG_CONFIG_HOME)
+        : join(home, ".config");
+    const readTextFile = options.readTextFile ?? ((path) => readFile(path, "utf8"));
+    try {
+        const contents = await readTextFile(join(configHome, "user-dirs.dirs"));
+        const documents = parseXdgDocumentsDirectory(contents, home);
+        if (documents)
+            return join(documents, "Rynx");
+    }
+    catch {
+        // Missing or unreadable XDG configuration is normal on headless Linux.
+    }
+    return join(home, "Rynx");
+}
+export async function createSessionFallbackWorkspace(options = {}) {
+    const now = (options.now ?? (() => new Date()))();
+    const date = [
+        now.getFullYear(),
+        String(now.getMonth() + 1).padStart(2, "0"),
+        String(now.getDate()).padStart(2, "0"),
+    ].join("-");
+    const fallbackRoot = await resolveSessionFallbackRoot(options);
+    await mkdir(fallbackRoot, { recursive: true });
+    const canonicalFallbackRoot = await realpath(fallbackRoot);
+    const dateDirectory = join(canonicalFallbackRoot, date);
+    await mkdir(dateDirectory, { recursive: true });
+    const canonicalDateDirectory = await realpath(dateDirectory);
+    if (relative(canonicalFallbackRoot, canonicalDateDirectory) !== date) {
+        throw new Error("Session fallback date directory resolves outside the managed root");
+    }
+    const randomId = options.randomId ?? randomUUID;
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+        const directory = join(canonicalDateDirectory, randomId().slice(0, 8));
+        try {
+            await mkdir(directory);
+            const canonical = await realpath(directory);
+            return sessionWorkspaceSnapshotSchema.parse({
+                cwd: canonical,
+                allowedDirs: [canonical],
+            });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    throw new Error("could not allocate a unique Session workspace directory");
+}
+export async function discardSessionFallbackWorkspace(workspace, options = {}) {
+    if (workspace.allowedDirs.length !== 1
+        || workspace.allowedDirs[0] !== workspace.cwd) {
+        return;
+    }
+    let canonicalRoot;
+    try {
+        canonicalRoot = await realpath(await resolveSessionFallbackRoot(options));
+    }
+    catch {
+        return;
+    }
+    const relativePath = relative(canonicalRoot, workspace.cwd);
+    const segments = relativePath.split(/[\\/]/);
+    if (isAbsolute(relativePath)
+        || relativePath.startsWith("..")
+        || segments.length !== 2
+        || !/^\d{4}-\d{2}-\d{2}$/.test(segments[0] ?? "")
+        || !/^[0-9a-f]{8}$/.test(segments[1] ?? "")) {
+        return;
+    }
+    await rm(workspace.cwd, { recursive: true, force: true });
+}
+function parseXdgDocumentsDirectory(contents, home) {
+    for (const line of contents.split(/\r?\n/)) {
+        const match = line.match(/^\s*XDG_DOCUMENTS_DIR\s*=\s*"((?:\\.|[^"])*)"\s*(?:#.*)?$/);
+        if (!match)
+            continue;
+        const raw = match[1];
+        let expanded;
+        if (raw === "$HOME" || raw === "${HOME}") {
+            expanded = home;
+        }
+        else if (raw.startsWith("$HOME/")) {
+            expanded = join(home, decodeXdgPath(raw.slice("$HOME/".length)));
+        }
+        else if (raw.startsWith("${HOME}/")) {
+            expanded = join(home, decodeXdgPath(raw.slice("${HOME}/".length)));
+        }
+        else {
+            expanded = decodeXdgPath(raw);
+        }
+        if (!expanded.includes("\0") && isAbsolute(expanded))
+            return normalize(expanded);
+    }
+    return undefined;
+}
+function decodeXdgPath(value) {
+    return value.replace(/\\(.)/g, "$1");
+}

package/dist/session-fork-store.d.ts

@@ -0,0 +1,41 @@
+import { type MachineSessionRecord } from "@rynx-ai/core";
+import type { SessionItem } from "@rynx-ai/protocol";
+import { type MachineSessionForkOperationRecord, type MachineSessionForkStorePort } from "@rynx-ai/server";
+/**
+ * SQLite/resource-file implementation of the fork publication boundary.
+ *
+ * Provider context is prepared before {@link commit}; this store then publishes
+ * Session metadata, an independent canonical transcript, referenced committed
+ * resources, and the completed operation in one SQLite transaction. Resource
+ * files use deterministic target ids, so a crash before the transaction can be
+ * retried safely.
+ */
+export declare class SqliteSessionForkStore implements MachineSessionForkStorePort {
+    private readonly resourceRoot;
+    constructor(resourceRoot?: string);
+    claim(input: {
+        operationId: string;
+        requestHash: string;
+        sourceSessionId: string;
+        title?: string;
+    }): MachineSessionForkOperationRecord;
+    commit(input: {
+        operationId: string;
+        target: MachineSessionRecord;
+        items: SessionItem[];
+    }): void;
+    publishNativeFork(input: {
+        sourceSessionId: string;
+        target: MachineSessionRecord;
+        items: SessionItem[];
+    }): void;
+    private publishTarget;
+    markError(operationId: string, error: string): void;
+    listReserved(): MachineSessionForkOperationRecord[];
+    hasReservedSource(sessionId: string): boolean;
+    markTargetDeleted(sessionId: string): void;
+    private read;
+    private copyResourceFile;
+    private sessionDirectory;
+    private resourcePath;
+}