@abelxiaoxing/cadence 2.0.1 → 2.0.3

package/src/native-client.ts

@@ -1,6 +1,10 @@
 /** Native attachment only. No SDK/auth resolution, worker or storage mutation. */
 
-import { Agent } from "undici";
+import { existsSync, realpathSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Agent, Dispatcher1Wrapper } from "undici";
 import { nativeBuild } from "./native-build.ts";
 import { ServiceCoordination } from "./service/coordination.ts";
 import { ServiceClient } from "./service-client.ts";
@@ -10,10 +14,138 @@ import {
   type SessionBootstrap,
 } from "./service-contract.ts";
 import { HttpServiceTransport } from "./service-http-client.ts";
+import { effectiveWorkspace } from "./task-store.ts";
 
 export const MANAGEMENT_GUIDANCE =
   "Cadence owner absent, unavailable or incompatible. Explicitly run cadence-service status --workspace <path>, cadence-service diagnose --workspace <path>, or cadence-service start --workspace <path>. Stop older Cadence sessions first. For retained fences use cadence-service recover inspect; resolve requires a local terminal and separate process, credential and storage acknowledgments. Never treat unavailable/quarantined as stopped. No service was started and no embedded executor is available.";
 
+const UNIT = "cadence.service";
+/** Exists only when systemd booted the machine (sd_booted); without it there
+ * is no user manager, and `autostart install` reports unavailable. */
+const SYSTEMD_BOOTED = "/run/systemd/system";
+const xdg = (value: string | undefined, fallback: string) =>
+  value && isAbsolute(value) ? value : fallback;
+const cliPath = () =>
+  JSON.stringify(fileURLToPath(new URL("./service-cli.mjs", import.meta.url)));
+/** CADENCE_LINGER=0 keeps the explicit command login-only, too. */
+const installCommand = (env: NodeJS.ProcessEnv) =>
+  `node ${cliPath()} autostart install${env.CADENCE_LINGER === "0" ? "" : " --linger"}`;
+
+/** Linux: npm may skip or hide the Pi install hook that registers the user
+ * unit, so name the explicit command when it is absent. Reads two paths only. */
+export function autostartHint(): string {
+  if (process.platform !== "linux" || !existsSync(SYSTEMD_BOOTED)) return "";
+  const data = xdg(
+    process.env.XDG_DATA_HOME,
+    join(homedir(), ".local", "share"),
+  );
+  if (existsSync(join(data, "systemd", "user", UNIT))) return "";
+  return `\nTo run the shared service and WebUI (default http://127.0.0.1:17423) ${process.env.CADENCE_LINGER === "0" ? "at login" : "at boot"}: ${installCommand(process.env)}`;
+}
+
+export interface AutostartObservation {
+  platform: NodeJS.Platform;
+  env: NodeJS.ProcessEnv;
+  home: string;
+  /** Package root; only Pi's managed user copy registers itself. */
+  root: string;
+  /** logind keeps one flag file per lingering user name. */
+  lingerFile: string;
+  /** Exists only on a systemd-booted machine. */
+  systemd: string;
+}
+function hostObservation(): AutostartObservation {
+  let user = "";
+  try {
+    user = userInfo().username;
+  } catch {
+    // No passwd entry: linger is unobservable, so it reads as off.
+  }
+  return {
+    platform: process.platform,
+    env: process.env,
+    home: homedir(),
+    root: fileURLToPath(new URL("..", import.meta.url)),
+    lingerFile: user ? join("/var/lib/systemd/linger", user) : "",
+    systemd: SYSTEMD_BOOTED,
+  };
+}
+/** Same selection as Pi's getAgentDir: PI_CODING_AGENT_DIR or ~/.pi/agent. */
+function piUserCopy(o: AutostartObservation): boolean {
+  const selected = o.env.PI_CODING_AGENT_DIR;
+  const agent = !selected
+    ? join(o.home, ".pi", "agent")
+    : resolve(
+        selected === "~"
+          ? o.home
+          : selected.startsWith("~/")
+            ? join(o.home, selected.slice(2))
+            : selected,
+      );
+  try {
+    const managed = join(
+      agent,
+      "npm",
+      "node_modules",
+      "@abelxiaoxing",
+      "cadence",
+    );
+    return realpathSync(managed) === realpathSync(o.root);
+  } catch {
+    return false;
+  }
+}
+/** Startup-card line while boot start of the Linux user unit needs a human
+ * step. Path observations only: nothing is created, spawned or started. A
+ * machine without systemd, a disabled or (also runtime-)masked unit and
+ * CADENCE_AUTOSTART=0 are quiet; CADENCE_LINGER=0 never suggests linger. */
+export function autostartNotice(
+  o: AutostartObservation = hostObservation(),
+): string | undefined {
+  if (
+    o.platform !== "linux" ||
+    o.env.CADENCE_AUTOSTART === "0" ||
+    !existsSync(o.systemd)
+  )
+    return;
+  const data = xdg(o.env.XDG_DATA_HOME, join(o.home, ".local", "share"));
+  const config = xdg(o.env.XDG_CONFIG_HOME, join(o.home, ".config"));
+  const boot = o.env.CADENCE_LINGER !== "0";
+  if (!existsSync(join(data, "systemd", "user", UNIT)))
+    return piUserCopy(o)
+      ? `Cadence服务：未注册${boot ? "开机" : ""}自启（npm 可能跳过或隐藏了安装脚本）。注册并${boot ? "开机" : "登录后"}启动：${installCommand(o.env)}`
+      : undefined;
+  const user = join(config, "systemd", "user");
+  const runtime = o.env.XDG_RUNTIME_DIR;
+  if (
+    existsSync(join(user, UNIT)) ||
+    (runtime &&
+      isAbsolute(runtime) &&
+      existsSync(join(runtime, "systemd", "user", UNIT))) ||
+    !existsSync(join(user, "default.target.wants", UNIT)) ||
+    o.env.CADENCE_LINGER === "0" ||
+    existsSync(o.lingerFile)
+  )
+    return;
+  return "Cadence服务：linger 未开启，仅在登录后启动、注销时停止。开机启动：loginctl enable-linger";
+}
+
+/** Pi exits right after its session_shutdown handlers settle. An unsent
+ * detach leaves the attachment holding one of the owner's viewer slots until
+ * its idle expiry, so a departing session waits briefly for the detach; a
+ * slow or absent owner never holds Pi's quit longer than `ms`. */
+export async function departure(detaching: Promise<void>, ms = 1500) {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  await Promise.race([
+    detaching.catch(() => {}),
+    new Promise<void>((resolve) => {
+      timer = setTimeout(resolve, ms);
+      timer.unref?.();
+    }),
+  ]);
+  clearTimeout(timer);
+}
+
 export class NativeConnection {
   private transport?: HttpServiceTransport;
   private network?: Agent;
@@ -28,10 +160,17 @@ export class NativeConnection {
     // Failed detach keeps its exact transport/slot. Explicit re-entry may retry
     // detach, but never forget it and allocate a replacement on uncertainty.
     await this.detach();
-    const access = new ServiceCoordination(cwd).localAccess();
+    // Pi started in the home directory attaches to the ~/cadence landing owner,
+    // the same one the management client starts there. Observation only.
+    const access = new ServiceCoordination(
+      effectiveWorkspace(cwd).workspace,
+    ).localAccess();
     this.epoch = access.epoch;
     const network = new Agent();
     this.network = network;
+    // Node 22/24 built-in fetch bundles undici 6/7, whose legacy handlers an
+    // undici 8 Agent rejects. The public wrapper adapts them on every line.
+    const dispatcher = new Dispatcher1Wrapper(network);
     this.transport = new HttpServiceTransport({
       origin: access.endpoint,
       localCapability: access.capability,
@@ -43,7 +182,7 @@ export class NativeConnection {
       // process routes provider auth through a proxy. Public per-request Node
       // dispatcher only: never replace/restore the parent's global dispatcher.
       fetch: (url, init) =>
-        globalThis.fetch(url, Object.assign({}, init, { dispatcher: network })),
+        globalThis.fetch(url, Object.assign({}, init, { dispatcher })),
     });
     const client = new ServiceClient(this.transport);
     this.client = client;

package/src/operator-cli.mjs

@@ -136,11 +136,8 @@ function safeDirectory(path, create = false, inspectExisting) {
     at = join(at, part);
     let existing;
     try {
-      const st = lstatSync(at);
-      if (!st.isDirectory())
-        throw new Error("Unsafe directory");
       const checked = lstatSync(at);
-      if (checked.isSymbolicLink() || inspectExisting && !checked.isDirectory())
+      if (!checked.isDirectory() || checked.isSymbolicLink())
         throw new Error("Unsafe directory");
       existing = checked;
     } catch (error) {
@@ -154,7 +151,8 @@ function safeDirectory(path, create = false, inspectExisting) {
         if (!object(mkdirError) || mkdirError.code !== "EEXIST")
           throw mkdirError;
       }
-      if (!lstatSync(at).isDirectory() || lstatSync(at).isSymbolicLink())
+      const created = lstatSync(at);
+      if (!created.isDirectory() || created.isSymbolicLink())
         throw new Error("Unsafe directory");
     }
     if (existing)
@@ -162,13 +160,29 @@ function safeDirectory(path, create = false, inspectExisting) {
   }
   return true;
 }
-function readBounded(path, max) {
+var transientWindows = new Set(["EPERM", "EACCES", "EBUSY"]);
+function retryWindowsFileOperation(operation, recheck) {
+  if (process.platform !== "win32")
+    return operation();
+  const deadline = performance.now() + 2000;
+  for (let delay = 2;; delay = Math.min(delay * 2, 50)) {
+    try {
+      return operation();
+    } catch (error) {
+      if (!object(error) || !transientWindows.has(String(error.code)) || performance.now() >= deadline)
+        throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delay);
+      recheck?.();
+    }
+  }
+}
+function readBounded(path, max, packaged = false) {
   if (!safeDirectory(dirname(path)))
     return;
   let fd;
   try {
     const st = lstatSync(path);
-    if (!st.isFile() || st.isSymbolicLink() || st.nlink !== 1 || st.size > max)
+    if (!st.isFile() || st.isSymbolicLink() || !packaged && st.nlink !== 1 || st.size > max)
       throw new Error("Unsafe or oversized file");
     fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
   } catch (error) {
@@ -178,7 +192,7 @@ function readBounded(path, max) {
   }
   try {
     const st = fstatSync(fd);
-    if (!st.isFile() || st.nlink !== 1 || st.size > max)
+    if (!st.isFile() || !packaged && st.nlink !== 1 || st.size > max)
       throw new Error("Unsafe or oversized file");
     const buffer = Buffer.alloc(max + 1);
     let size = 0;
@@ -256,6 +270,23 @@ function canonicalAmbientRoot(path) {
     return join(canonicalAmbientRoot(parent), full.slice(parent.length));
   }
 }
+function privateRootFor(canonicalRoot, stateHome) {
+  return join(canonicalAmbientRoot(stateHome), "cadence-assistant-v1", createHash("sha256").update(canonicalRoot).digest("hex"));
+}
+function contains(root, path) {
+  const within = relative(root, resolve(path));
+  return !within || !within.startsWith(`..${sep}`) && within !== ".." && !isAbsolute(within);
+}
+function stateHomeInside(root, stateHome = defaultStateHome()) {
+  const canonical = realpathSync(root);
+  return contains(canonical, privateRootFor(canonical, stateHome));
+}
+var LANDING_WORKSPACE = "cadence";
+function effectiveWorkspace(requested, stateHome, home = homedir()) {
+  if (!stateHomeInside(resolveWorkspace(requested).root, stateHome))
+    return { workspace: requested, redirected: false };
+  return { workspace: join(home, LANDING_WORKSPACE), redirected: true };
+}
 
 class TaskStore {
   root;
@@ -264,9 +295,8 @@ class TaskStore {
   constructor(root, stateHome = defaultStateHome()) {
     this.root = realpathSync(root);
     this.tasks = join(this.root, ".cadence", "assistant", "tasks");
-    this.privateRoot = join(canonicalAmbientRoot(stateHome), "cadence-assistant-v1", createHash("sha256").update(this.root).digest("hex"));
-    const within = relative(this.root, resolve(this.privateRoot));
-    if (!within || !within.startsWith(`..${sep}`) && within !== ".." && !isAbsolute(within))
+    this.privateRoot = privateRootFor(this.root, stateHome);
+    if (contains(this.root, this.privateRoot))
       throw new Error("Private state home must be outside the working copy");
   }
   get lockPath() {
@@ -318,7 +348,7 @@ class TaskStore {
     };
     let fd;
     try {
-      fd = openSync(this.lockPath, "wx", 384);
+      fd = retryWindowsFileOperation(() => openSync(this.lockPath, "wx", 384));
     } catch {
       throw new Error("Checkout busy or unresolved lock; inspect and explicitly recover only a dead owner");
     }
@@ -338,7 +368,7 @@ class TaskStore {
     if (lock.pid !== process.pid || lock.host !== hostname())
       throw new Error("Only the owning process may release a lock");
     this.assertOwner(lock);
-    unlinkSync(this.lockPath);
+    retryWindowsFileOperation(() => unlinkSync(this.lockPath), () => this.assertOwner(lock));
   }
   recover(expected, acknowledgeEscapedProcesses) {
     if (!acknowledgeEscapedProcesses || expected.host !== hostname())
@@ -418,7 +448,12 @@ class TaskStore {
       const latest = readBounded(join(dir, "task.json"), MAX_RECORD_BYTES);
       if ((latest ? contentIdentity(latest) : undefined) !== expectedIdentity)
         throw new Error("Task content changed; replacement preserved without overwrite");
-      renameSync(temporary, join(dir, "task.json"));
+      retryWindowsFileOperation(() => renameSync(temporary, join(dir, "task.json")), () => {
+        this.assertOwner(lock);
+        const now = readBounded(join(dir, "task.json"), MAX_RECORD_BYTES);
+        if ((now ? contentIdentity(now) : undefined) !== expectedIdentity)
+          throw new Error("Task content changed; replacement preserved without overwrite");
+      });
       return next;
     } finally {
       if (!held)
@@ -459,8 +494,9 @@ class TaskStore {
 var TASK_CONFIG_SCHEMA = "cadence-assistant-checks/1";
 
 // src/operator-tools.ts
+var observed = (cwd) => resolveWorkspace(effectiveWorkspace(cwd).workspace);
 function inspectConsumer(cwd) {
-  const workspace = resolveWorkspace(cwd);
+  const workspace = observed(cwd);
   const store = new TaskStore(workspace.root);
   const tasks = store.list();
   const checks = store.checks();
@@ -481,7 +517,7 @@ function inspectConsumer(cwd) {
   };
 }
 function inspectRuns(cwd) {
-  const workspace = resolveWorkspace(cwd);
+  const workspace = observed(cwd);
   const store = new TaskStore(workspace.root);
   return {
     ok: true,

package/src/service/coordination.ts

@@ -19,6 +19,7 @@ import {
   text,
 } from "./contracts/core.ts";
 import {
+  DirectoryWalks,
   encoded,
   type FileSnapshot,
   hash,
@@ -282,8 +283,8 @@ export class ServiceCoordination {
       },
     };
   }
-  assertNamespace(): void {
-    if (!this.files.directory(this.directory)) refused();
+  assertNamespace(walks?: DirectoryWalks): void {
+    if (!this.files.directory(this.directory, false, walks)) refused();
     names(this.directory, [
       "format.json",
       "config.json",
@@ -295,13 +296,18 @@ export class ServiceCoordination {
       "host-config.json",
       "history-v2",
     ]);
-    this.files.directory(join(this.directory, "history-v2"));
+    this.files.directory(join(this.directory, "history-v2"), false, walks);
   }
   private selected(): Selected | undefined {
-    if (!this.files.directory(this.directory)) return undefined;
-    this.assertNamespace();
-    const manifest = this.files.read(this.path("format.json"));
-    const config = this.files.read(this.path("config.json"));
+    const walks = new DirectoryWalks();
+    if (!this.files.directory(this.directory, false, walks)) return undefined;
+    this.assertNamespace(walks);
+    const manifest = this.files.read(
+      this.path("format.json"),
+      undefined,
+      walks,
+    );
+    const config = this.files.read(this.path("config.json"), undefined, walks);
     if (!manifest || !config) refused();
     const f = closed(json(manifest), [
       "schema",
@@ -314,12 +320,24 @@ export class ServiceCoordination {
     literal(f.stateHome, this.stateHome);
     literal(f.configIdentity, config.identity);
     const c = decodeOwnerConfig(json(config));
-    const hostConfig = this.files.read(this.path("host-config.json"));
+    const hostConfig = this.files.read(
+      this.path("host-config.json"),
+      undefined,
+      walks,
+    );
     if (hostConfig && hostConfig.identity !== c.policyIdentity) refused();
-    const registration = this.files.read(this.path("registration.json"));
-    const owner = this.files.read(this.path("owner.lock"));
-    const capability = this.files.read(this.path("local-capability.json"));
-    const checkout = this.files.read(this.store.lockPath, 8192);
+    const registration = this.files.read(
+      this.path("registration.json"),
+      undefined,
+      walks,
+    );
+    const owner = this.files.read(this.path("owner.lock"), undefined, walks);
+    const capability = this.files.read(
+      this.path("local-capability.json"),
+      undefined,
+      walks,
+    );
+    const checkout = this.files.read(this.store.lockPath, 8192, walks);
     const value = registration
       ? decodeRegistration(json(registration))
       : undefined;
@@ -808,8 +826,9 @@ export class OwnerLease {
       this.selected.value.host !== hostname()
     )
       throw new ContractError("conflict");
-    const c = this.coordination;
-    c.assertNamespace();
+    const c = this.coordination,
+      walks = new DirectoryWalks();
+    c.assertNamespace(walks);
     for (const [name, snapshot] of [
       ["config.json", this.selected.config],
       ["host-config.json", this.selected.hostConfig],
@@ -818,8 +837,8 @@ export class OwnerLease {
       ["owner.lock", this.selected.owner],
       ["local-capability.json", this.selected.capability],
     ] as const)
-      c.files.assert(c.path(name), snapshot);
-    c.files.assert(c.store.lockPath, this.selected.checkout, 8192);
+      c.files.assert(c.path(name), snapshot, undefined, walks);
+    c.files.assert(c.store.lockPath, this.selected.checkout, 8192, walks);
     c.store.assertOwner(this.checkout);
   }
   phase(phase: OwnerPhase): void {

package/src/service/private-files.ts

@@ -5,14 +5,16 @@ import {
   fstatSync,
   fsyncSync,
   lstatSync,
+  mkdirSync,
   openSync,
+  readSync,
   renameSync,
   type Stats,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { readBounded, safeDirectory } from "../task-store.ts";
+import { retryWindowsFileOperation, safeDirectory } from "../task-store.ts";
 import { ContractError, parseWireJson } from "./contracts/core.ts";
 
 export const METADATA_BYTES = 16 * 1024;
@@ -24,10 +26,14 @@ export function refused(): never {
 export function hash(bytes: string | Buffer): string {
   return createHash("sha256").update(bytes).digest("hex");
 }
-function privateMode(st: Stats): void {
+/** Owner-only mode for state Cadence creates. External sources it only reads
+ * (Pi's agent directory and files) keep whatever mode the user's umask gave
+ * them, such as 0755/0775 from Pi itself; ownership is still required. */
+function privateMode(st: Stats, ownerOnly = true): void {
   if (
     process.platform !== "win32" &&
-    ((st.mode & 0o077) !== 0 || (process.getuid && st.uid !== process.getuid()))
+    ((ownerOnly && (st.mode & 0o077) !== 0) ||
+      (process.getuid && st.uid !== process.getuid()))
   )
     refused();
 }
@@ -46,37 +52,132 @@ function same(a: Stats, b: Stats): boolean {
 function missing(error: unknown): boolean {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
+// Advances once per job, at its first microtask checkpoint. Nothing queued
+// retains a scope, so a dropped read budget is collected as usual.
+let job = 0,
+  advancing = false;
+function currentJob(): number {
+  if (!advancing) {
+    advancing = true;
+    queueMicrotask(() => {
+      job++;
+      advancing = false;
+    });
+  }
+  return job;
+}
+/** Directories that ONE synchronous operation already walked. Reuse re-observes
+ * the directory itself, no-follow, with the walked dev/ino and private mode: an
+ * ancestor substituted for other content resolves elsewhere and walks again. It
+ * goes stale at the next microtask checkpoint, so an await or a later call
+ * always walks; an ancestor's mode change inside one operation is seen by the
+ * next. Absence, refusal and any changed identity fall back to the full walk.
+ */
+export class DirectoryWalks {
+  private readonly job = currentJob();
+  private readonly walked = new Map<string, { dev: number; ino: number }>();
+  private open(): boolean {
+    if (this.job === job) return true;
+    this.walked.clear();
+    return false;
+  }
+  remember(path: string, st: Stats): void {
+    if (this.open()) this.walked.set(path, { dev: st.dev, ino: st.ino });
+  }
+  reuse(path: string, ownerOnly = true): boolean {
+    const walked = this.open() ? this.walked.get(path) : undefined;
+    if (!walked) return false;
+    let st: Stats;
+    try {
+      st = lstatSync(path);
+    } catch (error) {
+      if (!missing(error)) throw error;
+      this.walked.delete(path);
+      return false;
+    }
+    if (
+      !st.isDirectory() ||
+      st.isSymbolicLink() ||
+      st.dev !== walked.dev ||
+      st.ino !== walked.ino
+    ) {
+      this.walked.delete(path);
+      return false;
+    }
+    privateMode(st, ownerOnly);
+    return true;
+  }
+}
 /** Strengthens the existing helpers only inside the owned private namespace.
  * Ambient ancestors retain TaskStore's canonicalization policy. No directory CAS
  * or hostile-same-user guarantee; failed temporaries are deliberately preserved.
  */
 export class PrivateFiles {
-  constructor(readonly namespace: string) {}
-  directory(path: string, create = false): boolean {
+  /** `ownerOnly: false` for an external namespace such as Pi's agent directory. */
+  constructor(
+    readonly namespace: string,
+    readonly ownerOnly = true,
+  ) {}
+  directory(path: string, create = false, walks?: DirectoryWalks): boolean {
     const tail = relative(this.namespace, path);
     if (isAbsolute(tail) || tail === ".." || tail.startsWith(`..${sep}`))
       refused();
     if (!create) {
+      const full = resolve(path);
+      if (walks?.reuse(full, this.ownerOnly)) return true;
       const namespace = resolve(this.namespace);
-      let inside = false;
-      return safeDirectory(path, false, (at, st) => {
+      let inside = false,
+        last: Stats | undefined;
+      const found = safeDirectory(path, false, (at, st) => {
         // Exact segment boundary, not a textual prefix. One synchronous walk
         // checks every ambient ancestor and each existing private ancestor,
-        // including an unsafe parent before a missing child. Nothing is cached.
+        // including an unsafe parent before a missing child. Only the caller's
+        // DirectoryWalks keeps the result, for that same synchronous operation.
         if (at === namespace) inside = true;
-        if (inside) privateMode(st);
+        if (inside) privateMode(st, this.ownerOnly);
+        last = st;
       });
+      if (found && last) walks?.remember(full, last);
+      return found;
     }
+    // Walk the namespace and its ambient ancestors once, then check each
+    // private segment exactly once, creating a missing one privately.
+    if (!safeDirectory(this.namespace, true)) return false;
+    privateMode(lstatSync(this.namespace), this.ownerOnly);
     let at = this.namespace;
-    for (const part of ["", ...tail.split(sep).filter(Boolean)]) {
-      if (part) at = join(at, part);
-      if (!safeDirectory(at, create)) return false;
-      privateMode(lstatSync(at));
+    for (const part of tail.split(sep).filter(Boolean)) {
+      at = join(at, part);
+      let st: Stats;
+      try {
+        st = lstatSync(at);
+      } catch (error) {
+        if (!missing(error)) throw error;
+        try {
+          mkdirSync(at, { mode: 0o700 });
+        } catch (mkdirError) {
+          if (
+            !(
+              mkdirError instanceof Error &&
+              "code" in mkdirError &&
+              mkdirError.code === "EEXIST"
+            )
+          )
+            throw mkdirError;
+        }
+        st = lstatSync(at);
+      }
+      if (!st.isDirectory() || st.isSymbolicLink())
+        throw new Error("Unsafe directory");
+      privateMode(st, this.ownerOnly);
     }
     return true;
   }
-  read(path: string, maximum = METADATA_BYTES): FileSnapshot | undefined {
-    if (!this.directory(dirname(path))) return undefined;
+  read(
+    path: string,
+    maximum = METADATA_BYTES,
+    walks?: DirectoryWalks,
+  ): FileSnapshot | undefined {
+    if (!this.directory(dirname(path), false, walks)) return undefined;
     let before: Stats;
     try {
       before = lstatSync(path);
@@ -86,20 +187,25 @@ export class PrivateFiles {
     }
     if (!before.isFile() || before.nlink !== 1 || before.size > maximum)
       refused();
-    privateMode(before);
+    privateMode(before, this.ownerOnly);
     const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
     try {
       const opened = fstatSync(fd);
       if (!same(before, opened)) refused();
-      // Reuse the bounded no-follow reader; surround its read with descriptor and
-      // selected-path identity checks rather than weakening legacy behavior.
-      // The caller's independent maximum was already checked above. Bound the
-      // inner allocation to this exact selected size (+1 growth sentinel); keep
-      // its full ancestor/open checks and our final descriptor/path checks.
-      const bytes = readBounded(path, opened.size);
+      // Read this already opened, no-follow, identity-checked descriptor: its
+      // parents were walked just above, so a second walk and open add nothing.
+      // Bound the read to the selected size (+1 growth sentinel) and keep the
+      // final descriptor/path identity checks.
+      const buffer = Buffer.alloc(opened.size + 1);
+      let size = 0;
+      while (size < buffer.length) {
+        const n = readSync(fd, buffer, size, buffer.length - size, null);
+        if (!n) break;
+        size += n;
+      }
+      const bytes = buffer.subarray(0, size);
       if (
-        !bytes ||
-        bytes.length !== opened.size ||
+        size !== opened.size ||
         !same(opened, fstatSync(fd)) ||
         !same(opened, lstatSync(path))
       )
@@ -113,8 +219,9 @@ export class PrivateFiles {
     path: string,
     expected: FileSnapshot | undefined,
     maximum = METADATA_BYTES,
+    walks?: DirectoryWalks,
   ): void {
-    const current = this.read(path, maximum);
+    const current = this.read(path, maximum, walks);
     if (
       current?.identity !== expected?.identity ||
       current?.stamp !== expected?.stamp
@@ -124,7 +231,7 @@ export class PrivateFiles {
   create(path: string, bytes: string, maximum = METADATA_BYTES): FileSnapshot {
     if (Buffer.byteLength(bytes) > maximum) throw new ContractError("oversize");
     this.directory(dirname(path), true);
-    const fd = openSync(path, "wx", 0o600);
+    const fd = retryWindowsFileOperation(() => openSync(path, "wx", 0o600));
     try {
       writeFileSync(fd, bytes);
       fsyncSync(fd);
@@ -146,7 +253,10 @@ export class PrivateFiles {
     const temporary = join(dirname(path), `pending-${randomUUID()}.json`);
     this.create(temporary, bytes, maximum);
     this.assert(path, expected, maximum);
-    renameSync(temporary, path);
+    retryWindowsFileOperation(
+      () => renameSync(temporary, path),
+      () => this.assert(path, expected, maximum),
+    );
     this.syncDirectory(dirname(path));
     const result = this.read(path, maximum);
     if (!result || result.identity !== hash(bytes)) refused();
@@ -154,7 +264,10 @@ export class PrivateFiles {
   }
   remove(path: string, expected: FileSnapshot, maximum = METADATA_BYTES): void {
     this.assert(path, expected, maximum);
-    unlinkSync(path);
+    retryWindowsFileOperation(
+      () => unlinkSync(path),
+      () => this.assert(path, expected, maximum),
+    );
     this.syncDirectory(dirname(path));
   }
   private syncDirectory(path: string): void {