jishushell 0.4.30 → 0.5.15

package/dist/services/webdav/xml-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml-builder.js","sourceRoot":"","sources":["../../../src/services/webdav/xml-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAqBH;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC9B,WAAmB,EACnB,SAAwB;IAExB,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/E,OAAO,CACL,0CAA0C;QAC1C,iCAAiC,SAAS,oBAAoB,CAC/D,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,WAAmB,EAAE,CAAc;IACxD,MAAM,IAAI,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IACvC,MAAM,SAAS,GAAa;QAC1B,kBAAkB,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,kBAAkB;QAC5D,CAAC,CAAC,KAAK;YACL,CAAC,CAAC,kDAAkD;YACpD,CAAC,CAAC,mBAAmB;QACvB,sBAAsB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,sBAAsB;QAC5D,mBAAmB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,mBAAmB;QACtD,cAAc,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc;QAC7C,oBAAoB;QACpB,oBAAoB;KACrB,CAAC;IACF,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;QACb,SAAS,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,IAAI,uBAAuB,CAAC,CAAC;QACrE,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;YACX,SAAS,CAAC,IAAI,CACZ,qBAAqB,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAC5D,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,CACL,cAAc;QACd,WAAW,IAAI,WAAW;QAC1B,cAAc;QACd,WAAW,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW;QACxC,sCAAsC;QACtC,eAAe;QACf,eAAe,CAChB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,SAAS,CAAC,WAAmB,EAAE,CAAc;IACpD,MAAM,WAAW,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtD,IAAI,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,WAAW,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,GAAG,WAAW,GAAG,CAAC;IACrE,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,IAAI,IAAI,GAAG,CAAC;IAChD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,WAAmB,EACnB,OAAe;IAEf,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;IACxE,OAAO,CACL,0CAA0C;QAC1C,gCAAgC;QAChC,cAAc;QACd,WAAW,SAAS,CAAC,IAAI,CAAC,WAAW;QACrC,6CAA6C;QAC7C,eAAe;QACf,oBAAoB,CACrB,CAAC;AACJ,CAAC;AAED,sDAAsD;AAEtD,MAAM,WAAW,GAA2B;IAC1C,GAAG,EAAE,OAAO;IACZ,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,QAAQ;CACd,CAAC;AAEF,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,OAAO,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,oEAAoE;IACpE,sEAAsE;IACtE,uCAAuC;IACvC,OAAO,kBAAkB,CAAC,GAAG,CAAC;SAC3B,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;SACpB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;SACrB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AACvE,MAAM,cAAc,GAAG;IACrB,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACxC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;CACzC,CAAC;AAEF,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,SAAS,EAAE,CAAE,CAAC;IAC7C,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,cAAc,CAAC,CAAC,CAAC,WAAW,EAAE,CAAE,CAAC;IACnD,MAAM,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,CAAC;IAChC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpD,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACtD,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACtD,OAAO,GAAG,OAAO,KAAK,GAAG,IAAI,SAAS,IAAI,IAAI,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,OAAO,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,MAA0B;IACnD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,CAAC,CAAC;IACtD,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,CAAC,CAAC;IACxB,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,CAAC,CAAC;IACxB,4DAA4D;IAC5D,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/services/workspace-builder.d.ts

@@ -0,0 +1,29 @@
+import type { FileMount } from "./runtime/types.js";
+export declare class WorkspaceBuilderError extends Error {
+    reason: string;
+    constructor(message: string, reason: string);
+}
+export interface RebuildWorkspaceArgs {
+    /** Absolute host path of the instance's openclaw-home directory. */
+    openclawHome: string;
+    /** Absolute host path of FILES_ROOT (~/.jishushell/files). */
+    filesRoot: string;
+    /** Validated mount set; pass through validateMounts before calling. */
+    mounts: FileMount[];
+    /** Owning instance — used by isolation rule. */
+    instanceId: string;
+}
+export interface RebuildResult {
+    /** What kind of workspace we produced. */
+    layout: "named" | "root" | "empty";
+    /** For "named", the alias → resolved abs target map for audit. */
+    symlinks: Record<string, string>;
+}
+export declare function rebuildWorkspace(args: RebuildWorkspaceArgs): RebuildResult;
+/**
+ * For audit / UI. Given the live workspace, report the layout in
+ * structural form without touching it.
+ */
+export declare function describeWorkspace(openclawHome: string): RebuildResult & {
+    exists: boolean;
+};

package/dist/services/workspace-builder.js

@@ -0,0 +1,188 @@
+/**
+ * Build the workspace symlink layout for an instance (M1 W2 PR-2).
+ *
+ * Given a validated FileMount[] and the host paths involved, this module
+ * (re)creates `${openclawHome}/workspace/` so that:
+ *
+ *   - For named mounts: workspace is a real directory whose entries
+ *     are alias symlinks → FILES_ROOT/{mount.path}
+ *
+ *   - For a single root mount: workspace itself is a symlink →
+ *     FILES_ROOT/{mount.path}, replacing the directory wholesale
+ *
+ * Why we don't touch `${openclawHome}/.openclaw/workspace/`:
+ *   That subtree is OpenClaw's private state directory (skills config,
+ *   sessions, mcporter.json). We give the user-facing mount surface a
+ *   separate top-level directory `workspace/` directly under HOME,
+ *   keeping the two namespaces strictly disjoint.
+ *
+ * Safety contract — refuses to clobber unknown content:
+ *   - If workspace/ already contains plain files or non-symlink dirs
+ *     (i.e. data we don't recognize), throw rather than touch.
+ *   - Existing symlinks ARE removed — they were placed by a prior
+ *     rebuildWorkspace call.
+ *   - This means a *one-time legacy migration* (PR-7) must run first
+ *     for instances whose workspace currently contains real data.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { validateMounts, effectiveAlias, ensureMountTargets, } from "./files-mounts.js";
+export class WorkspaceBuilderError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "WorkspaceBuilderError";
+    }
+}
+const WORKSPACE_DIR_NAME = "workspace";
+export function rebuildWorkspace(args) {
+    const { openclawHome, filesRoot, mounts, instanceId } = args;
+    // Validate up front — caller may have skipped this; we are the last
+    // line of defense before fs writes.
+    const v = validateMounts(mounts, instanceId);
+    if (!v.ok) {
+        const summary = v.errors.slice(0, 5).map((e) => e.message).join("; ");
+        throw new WorkspaceBuilderError(`mount set is invalid: ${summary}`, "invalid-mounts");
+    }
+    // Make sure all mount targets exist on the host so docker can bind
+    // them and so symlinks resolve.
+    ensureMountTargets(filesRoot, mounts);
+    if (!fs.existsSync(openclawHome)) {
+        fs.mkdirSync(openclawHome, { recursive: true });
+    }
+    const ws = path.join(openclawHome, WORKSPACE_DIR_NAME);
+    // Resolve mode: empty list → empty workspace; one root mount →
+    // root layout; otherwise named.
+    if (mounts.length === 0) {
+        clearWorkspace(ws);
+        return { layout: "empty", symlinks: {} };
+    }
+    const rootMount = mounts.find((m) => m.alias === null || m.alias === "");
+    if (rootMount) {
+        // Root mode is exclusive (validateMounts has already enforced
+        // that mounts.length === 1). Workspace itself becomes a symlink.
+        const target = path.join(filesRoot, rootMount.path);
+        replaceWithSymlink(ws, target);
+        return { layout: "root", symlinks: { "": target } };
+    }
+    // Named mode: workspace is a real directory; each entry is a symlink.
+    const symlinks = {};
+    if (fs.existsSync(ws)) {
+        const lst = fs.lstatSync(ws);
+        if (lst.isSymbolicLink()) {
+            // Was previously root-mode; remove and recreate as dir
+            fs.unlinkSync(ws);
+            fs.mkdirSync(ws);
+        }
+        else if (lst.isDirectory()) {
+            pruneSymlinkChildren(ws);
+        }
+        else {
+            throw new WorkspaceBuilderError(`workspace at ${ws} is a file; refusing to clobber`, "non-directory");
+        }
+    }
+    else {
+        fs.mkdirSync(ws);
+    }
+    for (const m of mounts) {
+        const alias = effectiveAlias(m);
+        if (alias === null)
+            continue; // shouldn't happen here (rootMount filtered)
+        const target = path.join(filesRoot, m.path);
+        const linkPath = path.join(ws, alias);
+        fs.symlinkSync(target, linkPath);
+        symlinks[alias] = target;
+    }
+    return { layout: "named", symlinks };
+}
+function clearWorkspace(ws) {
+    if (!fs.existsSync(ws)) {
+        fs.mkdirSync(ws, { recursive: true });
+        return;
+    }
+    const lst = fs.lstatSync(ws);
+    if (lst.isSymbolicLink()) {
+        fs.unlinkSync(ws);
+        fs.mkdirSync(ws);
+        return;
+    }
+    if (lst.isDirectory()) {
+        pruneSymlinkChildren(ws);
+        return;
+    }
+    throw new WorkspaceBuilderError(`workspace at ${ws} is a file; refusing to clobber`, "non-directory");
+}
+/**
+ * Remove every entry under ws/ that is a symlink. Refuse if any entry
+ * is a plain file or non-symlink directory — that means a previous
+ * version had real data here that hasn't been migrated yet (PR-7).
+ */
+function pruneSymlinkChildren(ws) {
+    for (const name of fs.readdirSync(ws)) {
+        const full = path.join(ws, name);
+        const lst = fs.lstatSync(full);
+        if (lst.isSymbolicLink()) {
+            fs.unlinkSync(full);
+        }
+        else {
+            throw new WorkspaceBuilderError(`workspace contains non-symlink entry ${name}; legacy migration required before mount changes`, "needs-migration");
+        }
+    }
+}
+/** Replace `target` with a symlink to `linkTarget`, safe against existing
+ *  symlinks (atomic via unlink+symlinkSync). Symlink children of an
+ *  existing directory are pruned first; plain files trigger the legacy
+ *  migration error. */
+function replaceWithSymlink(target, linkTarget) {
+    if (fs.existsSync(target)) {
+        const lst = fs.lstatSync(target);
+        if (lst.isSymbolicLink()) {
+            fs.unlinkSync(target);
+        }
+        else if (lst.isDirectory()) {
+            // Reuse the same prune-or-throw policy as named mode so the
+            // named → root transition is symmetric with named → named.
+            pruneSymlinkChildren(target);
+            // After pruning, dir must be empty — otherwise pruneSymlinkChildren
+            // would have thrown.
+            fs.rmdirSync(target);
+        }
+        else {
+            throw new WorkspaceBuilderError(`workspace at ${target} is a regular file; refusing to clobber`, "non-directory");
+        }
+    }
+    fs.symlinkSync(linkTarget, target);
+}
+/**
+ * For audit / UI. Given the live workspace, report the layout in
+ * structural form without touching it.
+ */
+export function describeWorkspace(openclawHome) {
+    const ws = path.join(openclawHome, WORKSPACE_DIR_NAME);
+    if (!fs.existsSync(ws)) {
+        return { exists: false, layout: "empty", symlinks: {} };
+    }
+    const lst = fs.lstatSync(ws);
+    if (lst.isSymbolicLink()) {
+        const target = fs.readlinkSync(ws);
+        return { exists: true, layout: "root", symlinks: { "": target } };
+    }
+    if (!lst.isDirectory()) {
+        return { exists: true, layout: "empty", symlinks: {} };
+    }
+    const symlinks = {};
+    for (const name of fs.readdirSync(ws)) {
+        const full = path.join(ws, name);
+        const childLst = fs.lstatSync(full);
+        if (!childLst.isSymbolicLink())
+            continue;
+        symlinks[name] = fs.readlinkSync(full);
+    }
+    return {
+        exists: true,
+        layout: Object.keys(symlinks).length === 0 ? "empty" : "named",
+        symlinks,
+    };
+}
+//# sourceMappingURL=workspace-builder.js.map

package/dist/services/workspace-builder.js.map

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

package/dist/types.d.ts

@@ -111,6 +111,25 @@ export interface PanelConfig {
     };
     telemetry?: false;
     activation_reported?: boolean;
+    /**
+     * External mount points — let any host directory appear under
+     * ~/.jishushell/files/ as a virtual subtree. The user picks the
+     * alias; host_path can be any directory the panel user can read
+     * (sensitive system directories are flagged but allowed if the
+     * user insists). Mode "ro" forbids any write through the panel
+     * or WebDAV; "rw" allows it.
+     *
+     * Implementation: the panel does NOT create a real symlink in
+     * files/ — it virtualizes the path at the FilesManager layer.
+     * That avoids the symlink-defense conflict and works identically
+     * across docker / raw_exec / process modes.
+     */
+    external_mounts?: Array<{
+        alias: string;
+        host_path: string;
+        mode: "ro" | "rw";
+        description?: string;
+    }>;
     [key: string]: any;
 }
 export type AppTaskRuntime = "container" | "process" | "vm";
@@ -126,6 +145,16 @@ export interface AppTaskPort {
     host_port?: number;
     container_port?: number;
     visibility?: AppTaskPortVisibility;
+    /**
+     * Name of a Nomad `host_network` block declared in nomad.hcl. Default is
+     * "external" (eth0 / primary LAN interface). Use "docker_bridge" to
+     * publish on the docker0 IP (172.17.0.1) — required when peer containers
+     * in the same group dial this port via `host.docker.internal`. Without
+     * this, Nomad picks the wrong interface and cross-task
+     * host.docker.internal calls get "connection refused" (e.g. weknora-app
+     * → paradedb on port 18093).
+     */
+    host_network?: string;
 }
 export interface AppTaskHealth {
     http?: {
@@ -173,6 +202,19 @@ export interface AppTask {
      * the unified builder falls back to "host" by default.
      */
     user?: string;
+    /**
+     * Linux capabilities to add back on top of the runtime baseline
+     * (`cap_drop: ["ALL"]`). Validated against a tight allowlist
+     * (CHOWN / DAC_OVERRIDE / FOWNER / SETUID / SETGID / SETPCAP /
+     * NET_BIND_SERVICE) before passing to the docker driver. Required by
+     * canonical postgres/redis/-style images whose entrypoint runs as root
+     * and uses `gosu`+`chown` to drop privileges to a non-root user before
+     * exec'ing the main process. The container still drops to a non-root
+     * user before serving traffic — this only re-arms the kernel facilities
+     * the drop step needs. Caps outside the allowlist are silently dropped
+     * (fail-closed).
+     */
+    cap_add?: string[];
 }
 export interface AppTerminalCommandPreset {
     cmd: string;
@@ -232,6 +274,24 @@ export interface AppProvide {
      * should authenticate when calling the endpoint. Optional. Absent = no auth.
      */
     auth?: AppProvideAuth;
+    /**
+     * Controls how the instance detail page generates the iframe `src` for
+     * this capability:
+     *
+     *   - `"auto"` (default): direct LAN URL when the published port listens
+     *     on a non-loopback interface, fall back to panel proxy when only
+     *     loopback. Best for apps users typically reach by IP+port.
+     *   - `"proxy"`: always use the panel's same-origin reverse proxy path
+     *     (`/api/instances/:id/provides/:capability/`). Needed when the
+     *     upstream is on a network the browser can't dial directly (corp
+     *     firewall blocks high ports, VPN, mixed-content boundary) or when
+     *     the upstream emits `X-Frame-Options: SAMEORIGIN`/CSP that block
+     *     cross-origin iframe embedding — the proxy strips those headers.
+     *   - `"direct"`: always emit the direct LAN URL, never the proxy path.
+     *     Useful for upstreams that can't safely run behind a sub-path
+     *     reverse proxy (some SPAs hardcode absolute asset URLs).
+     */
+    embedded?: "auto" | "proxy" | "direct";
 }
 /**
  * §6 — describes how a consumer that binds this `provides[]` capability

package/dist/utils/path-locks.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Path-scoped advisory locks for the Files module (W1 PR-2).
+ *
+ * Single-process serialization: all callers using the same `path` string run
+ * in arrival order; different paths run independently in parallel.
+ *
+ * This is *advisory* — it only protects callers that opt in via withPathLock.
+ * It does not protect against external writers (Agent, WebDAV, ssh) that
+ * touch the file directly. Those paths have their own atomicity (POSIX
+ * rename) and the application's tolerance is "POSIX is source of truth".
+ *
+ * Stale locks (> 60s) are logged but not broken — correctness over recovery.
+ */
+/**
+ * Run `fn` while holding an advisory lock on `path`.
+ *
+ * If another caller holds the lock, this call queues behind it; the queue
+ * preserves arrival order.
+ *
+ * Throws (or resolves) propagate from `fn`. The lock is always released.
+ */
+export declare function withPathLock<T>(path: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Test-only: clear all locks. Do not use in production.
+ */
+export declare function _clearAllPathLocks(): void;
+/**
+ * Test-only: number of active locks. Do not use in production.
+ */
+export declare function _activePathLockCount(): number;

package/dist/utils/path-locks.js

@@ -0,0 +1,63 @@
+/**
+ * Path-scoped advisory locks for the Files module (W1 PR-2).
+ *
+ * Single-process serialization: all callers using the same `path` string run
+ * in arrival order; different paths run independently in parallel.
+ *
+ * This is *advisory* — it only protects callers that opt in via withPathLock.
+ * It does not protect against external writers (Agent, WebDAV, ssh) that
+ * touch the file directly. Those paths have their own atomicity (POSIX
+ * rename) and the application's tolerance is "POSIX is source of truth".
+ *
+ * Stale locks (> 60s) are logged but not broken — correctness over recovery.
+ */
+const locks = new Map();
+const STALE_LOCK_MS = 60_000;
+/**
+ * Run `fn` while holding an advisory lock on `path`.
+ *
+ * If another caller holds the lock, this call queues behind it; the queue
+ * preserves arrival order.
+ *
+ * Throws (or resolves) propagate from `fn`. The lock is always released.
+ */
+export async function withPathLock(path, fn) {
+    const existing = locks.get(path);
+    if (existing && Date.now() - existing.startedAt > STALE_LOCK_MS) {
+        console.warn(`[path-lock] stale lock detected for ${path} (held ${Date.now() - existing.startedAt}ms)`);
+    }
+    const previous = existing?.promise ?? Promise.resolve();
+    let release;
+    const next = new Promise((resolve) => {
+        release = resolve;
+    });
+    // Our slot in the chain: wait for previous holder, then release `next`
+    const ourPromise = previous.then(() => next);
+    const entry = { promise: ourPromise, startedAt: Date.now() };
+    locks.set(path, entry);
+    try {
+        await previous;
+        // Re-stamp startedAt to "actual hold start" for stale detection
+        entry.startedAt = Date.now();
+        return await fn();
+    }
+    finally {
+        release();
+        if (locks.get(path) === entry) {
+            locks.delete(path);
+        }
+    }
+}
+/**
+ * Test-only: clear all locks. Do not use in production.
+ */
+export function _clearAllPathLocks() {
+    locks.clear();
+}
+/**
+ * Test-only: number of active locks. Do not use in production.
+ */
+export function _activePathLockCount() {
+    return locks.size;
+}
+//# sourceMappingURL=path-locks.js.map

package/dist/utils/path-locks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-locks.js","sourceRoot":"","sources":["../../src/utils/path-locks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;AAC3C,MAAM,aAAa,GAAG,MAAM,CAAC;AAE7B;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,EAAoB;IAEpB,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,QAAQ,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,SAAS,GAAG,aAAa,EAAE,CAAC;QAChE,OAAO,CAAC,IAAI,CACV,uCAAuC,IAAI,UACzC,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,SACxB,KAAK,CACN,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,EAAE,OAAO,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAExD,IAAI,OAAoB,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACzC,OAAO,GAAG,OAAO,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,uEAAuE;IACvE,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAc,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IACxE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAEvB,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC;QACf,gEAAgE;QAChE,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,OAAO,EAAE,CAAC;QACV,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;YAC9B,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,KAAK,CAAC,IAAI,CAAC;AACpB,CAAC"}

package/dist/utils/path-safety.d.ts

@@ -0,0 +1,41 @@
+export declare class PathSafetyError extends Error {
+    reason: string;
+    constructor(message: string, reason: string);
+}
+/**
+ * Validate a user-provided relative path string against common attack
+ * vectors. Performs no IO.
+ *
+ * Accepted:
+ *   - "" (root)
+ *   - "notes/x.md", "深/文件.txt", "with-dashes_and.dots"
+ *
+ * Rejected (PathSafetyError):
+ *   - leading "/" (absolute)
+ *   - drive letters ("C:\\foo", "Z:foo")
+ *   - any "..", ".", or all-dot ("...", "....") segment
+ *   - empty segments ("a//b")
+ *   - leading or trailing "/"
+ *   - backslash anywhere
+ *   - null bytes or control chars (< 0x20)
+ *   - segments ending in "." or " " (Windows quirk; some sync tools misbehave)
+ *   - segment > 255 bytes (ext4 NAME_MAX)
+ *   - total > 4096 bytes (Linux PATH_MAX)
+ *   - non-string input
+ */
+export declare function validateRelativePath(input: unknown): void;
+/**
+ * Resolve a validated relative path inside a fixed root, then verify the
+ * resolved path is still inside that root using a separator-explicit prefix
+ * check (so `/foo` does not match `/foobar`).
+ *
+ * Performs no IO. Symlink resolution is the caller's responsibility.
+ *
+ * @throws PathSafetyError on validation failure or escape attempt
+ */
+export declare function resolveSafe(root: string, rel: string): string;
+/**
+ * Returns true if any segment of the path begins with ".".
+ * Used to optionally hide dotfiles in directory listings.
+ */
+export declare function isHidden(input: string): boolean;

package/dist/utils/path-safety.js

@@ -0,0 +1,119 @@
+/**
+ * Path safety utilities for the Files module (W1).
+ *
+ * Three layers of defense (per .omc/plans/files-w1.md § 7.1):
+ *   1. validateRelativePath — string-level checks (this module, no IO)
+ *   2. resolveSafe          — path.resolve + prefix check (this module, no IO)
+ *   3. realpath/symlink     — performed by FilesManager (defense 3, IO)
+ *
+ * Empty string is the conventional root path and is accepted by both functions.
+ */
+import { resolve, sep } from "path";
+const PATH_MAX_BYTES = 4096;
+const NAME_MAX_BYTES = 255;
+export class PathSafetyError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "PathSafetyError";
+    }
+}
+/**
+ * Validate a user-provided relative path string against common attack
+ * vectors. Performs no IO.
+ *
+ * Accepted:
+ *   - "" (root)
+ *   - "notes/x.md", "深/文件.txt", "with-dashes_and.dots"
+ *
+ * Rejected (PathSafetyError):
+ *   - leading "/" (absolute)
+ *   - drive letters ("C:\\foo", "Z:foo")
+ *   - any "..", ".", or all-dot ("...", "....") segment
+ *   - empty segments ("a//b")
+ *   - leading or trailing "/"
+ *   - backslash anywhere
+ *   - null bytes or control chars (< 0x20)
+ *   - segments ending in "." or " " (Windows quirk; some sync tools misbehave)
+ *   - segment > 255 bytes (ext4 NAME_MAX)
+ *   - total > 4096 bytes (Linux PATH_MAX)
+ *   - non-string input
+ */
+export function validateRelativePath(input) {
+    if (typeof input !== "string") {
+        throw new PathSafetyError("path must be a string", "type");
+    }
+    if (input === "")
+        return; // root, ok
+    if (Buffer.byteLength(input, "utf8") > PATH_MAX_BYTES) {
+        throw new PathSafetyError("path too long", "path-length");
+    }
+    if (input.startsWith("/")) {
+        throw new PathSafetyError("path must be relative (no leading /)", "absolute");
+    }
+    if (input.includes("\\")) {
+        throw new PathSafetyError("backslash not allowed", "backslash");
+    }
+    // Windows drive letter: e.g. "C:\\foo", "Z:foo", "Z:/foo"
+    if (/^[A-Za-z]:/.test(input)) {
+        throw new PathSafetyError("drive letter not allowed", "drive-letter");
+    }
+    for (let i = 0; i < input.length; i++) {
+        const code = input.charCodeAt(i);
+        if (code === 0) {
+            throw new PathSafetyError("null byte not allowed", "null-byte");
+        }
+        if (code < 0x20) {
+            throw new PathSafetyError("control character not allowed", "control-char");
+        }
+    }
+    if (input.endsWith("/")) {
+        throw new PathSafetyError("path must not end with /", "trailing-slash");
+    }
+    const segments = input.split("/");
+    for (const seg of segments) {
+        if (seg === "") {
+            throw new PathSafetyError("empty path segment", "empty-segment");
+        }
+        // Reject "." ".." and any all-dots variant ("..." "...." etc.)
+        if (/^\.+$/.test(seg)) {
+            throw new PathSafetyError(`all-dots segment "${seg}" not allowed`, "dot-segment");
+        }
+        if (Buffer.byteLength(seg, "utf8") > NAME_MAX_BYTES) {
+            throw new PathSafetyError("path segment too long", "segment-length");
+        }
+        if (seg.endsWith(".") || seg.endsWith(" ")) {
+            throw new PathSafetyError(`segment ends with "." or space`, "windows-quirk");
+        }
+    }
+}
+/**
+ * Resolve a validated relative path inside a fixed root, then verify the
+ * resolved path is still inside that root using a separator-explicit prefix
+ * check (so `/foo` does not match `/foobar`).
+ *
+ * Performs no IO. Symlink resolution is the caller's responsibility.
+ *
+ * @throws PathSafetyError on validation failure or escape attempt
+ */
+export function resolveSafe(root, rel) {
+    validateRelativePath(rel);
+    const resolved = resolve(root, rel);
+    const rootWithSep = root.endsWith(sep) ? root : root + sep;
+    const rootNoSep = root.endsWith(sep) ? root.slice(0, -1) : root;
+    if (resolved !== rootNoSep && !resolved.startsWith(rootWithSep)) {
+        throw new PathSafetyError("path escapes root", "escape");
+    }
+    return resolved;
+}
+/**
+ * Returns true if any segment of the path begins with ".".
+ * Used to optionally hide dotfiles in directory listings.
+ */
+export function isHidden(input) {
+    if (input === "")
+        return false;
+    return input.split("/").some(s => s.startsWith("."));
+}
+//# sourceMappingURL=path-safety.js.map

package/dist/utils/path-safety.js.map

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

package/dist/utils/safe-write.d.ts

@@ -0,0 +1,24 @@
+import { Readable } from "node:stream";
+export interface AtomicWriteOptions {
+    /** Compute streaming sha256 of the data while writing. Default: undefined */
+    hash?: "sha256";
+    /** Expected total size; if set and actual differs, throws. Default: no check */
+    expectedSize?: number;
+    /** Write mode (POSIX) of the final file. Default 0o644 */
+    mode?: number;
+}
+export interface AtomicWriteResult {
+    size: number;
+    hash?: string;
+}
+/**
+ * Stream `source` to `targetPath` atomically.
+ *
+ * Memory peak is the Node stream high-water-mark (~64KB), regardless of the
+ * total file size. Suitable for arbitrarily large files.
+ */
+export declare function atomicWriteStream(targetPath: string, source: Readable, opts?: AtomicWriteOptions): Promise<AtomicWriteResult>;
+/**
+ * Convenience wrapper for small Buffer writes. Uses the same atomic pipeline.
+ */
+export declare function safeWriteBuffer(targetPath: string, buf: Buffer, opts?: AtomicWriteOptions): Promise<AtomicWriteResult>;