@abelxiaoxing/cadence 2.0.1 → 2.0.2

package/src/service-cli.mjs

@@ -3,7 +3,9 @@
 
 // src/service/cli.ts
 import { spawn } from "node:child_process";
+import { existsSync, mkdirSync as mkdirSync4 } from "node:fs";
 import { request } from "node:http";
+import { dirname as dirname8, join as join8, resolve as resolve5 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/task-types.ts
@@ -86,7 +88,10 @@ function safeChildEnv() {
     "TMPDIR",
     "LANG",
     "LC_ALL",
-    "PATHEXT"
+    "PATHEXT",
+    "ProgramFiles",
+    "ProgramFiles(x86)",
+    "ProgramW6432"
   ])
     if (process.env[key] !== undefined)
       env[key] = process.env[key];
@@ -2039,12 +2044,6 @@ class CaptureBudgetLease {
     this.forget();
   }
 }
-// src/service/coordination.ts
-import { randomBytes, randomUUID as randomUUID3 } from "node:crypto";
-import { opendirSync, realpathSync as realpathSync2 } from "node:fs";
-import { hostname as hostname2 } from "node:os";
-import { dirname as dirname3, isAbsolute as isAbsolute3, join as join3, relative as relative3, sep as sep3 } from "node:path";
-
 // src/task-store.ts
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
@@ -2114,11 +2113,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) {
@@ -2132,7 +2128,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)
@@ -2140,13 +2137,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) {
@@ -2156,7 +2169,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;
@@ -2234,6 +2247,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;
@@ -2242,9 +2272,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() {
@@ -2296,7 +2325,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");
     }
@@ -2316,7 +2345,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())
@@ -2396,7 +2425,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)
@@ -2436,6 +2470,297 @@ class TaskStore {
 }
 var TASK_CONFIG_SCHEMA = "cadence-assistant-checks/1";
 
+// src/service/autostart.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+import {
+  lstatSync as lstatSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync,
+  realpathSync as realpathSync2,
+  renameSync as renameSync2,
+  rmSync,
+  statSync,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { delimiter, dirname as dirname2, isAbsolute as isAbsolute2, join as join2, resolve as resolve2, sep as sep2 } from "node:path";
+var UNIT = "cadence.service";
+var MARKER = "# Generated by @abelxiaoxing/cadence";
+function hostSystem(root) {
+  const run = (command, args) => {
+    const r = spawnSync2(command, args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return { status: r.error ? null : r.status, stdout: r.stdout ?? "" };
+  };
+  return {
+    platform: process.platform,
+    env: process.env,
+    home: homedir2(),
+    node: process.execPath,
+    root,
+    unit: UNIT,
+    systemctl: (args) => run("systemctl", ["--user", ...args]),
+    linger: () => {
+      const r = run("loginctl", [
+        "show-user",
+        String(process.getuid?.()),
+        "--property=Linger",
+        "--value"
+      ]);
+      return r.status === 0 ? r.stdout.trim() === "yes" : undefined;
+    }
+  };
+}
+function expandHome(value, home) {
+  if (value === "~")
+    return home;
+  return value.startsWith("~/") ? join2(home, value.slice(2)) : value;
+}
+function agentDirectory(s) {
+  const selected = s.env.PI_CODING_AGENT_DIR;
+  return resolve2(selected ? expandHome(selected, s.home) : join2(s.home, ".pi", "agent"));
+}
+function piUserInstall(s) {
+  try {
+    const managed = join2(agentDirectory(s), "npm", "node_modules", "@abelxiaoxing", "cadence");
+    return realpathSync2(managed) === realpathSync2(s.root);
+  } catch {
+    return false;
+  }
+}
+function sdkPackages(root) {
+  let start;
+  try {
+    start = realpathSync2(join2(root, "src"));
+  } catch {
+    return;
+  }
+  const found = [];
+  for (const name of ["pi-coding-agent", "pi-ai"]) {
+    let hit;
+    for (let dir = start;!hit; dir = dirname2(dir)) {
+      const candidate = join2(dir, "node_modules", "@earendil-works", name, "package.json");
+      if (regularFile(candidate))
+        hit = candidate;
+      else if (dirname2(dir) === dir)
+        return;
+    }
+    found.push(hit);
+  }
+  return found;
+}
+function unitPath(s) {
+  const data = s.env.XDG_DATA_HOME;
+  return join2(data && isAbsolute2(data) ? data : join2(s.home, ".local", "share"), "systemd", "user", s.unit);
+}
+function servicePath(value) {
+  const kept = (value ?? "").split(delimiter).filter((entry) => isAbsolute2(entry) && !entry.endsWith(`${sep2}node_modules${sep2}.bin`) && !entry.includes(`${sep2}node-gyp-bin`));
+  return kept.length ? [...new Set(kept)].join(delimiter) : "/usr/local/bin:/usr/bin:/bin";
+}
+function serviceEnvironment(s) {
+  const out = [["PATH", servicePath(s.env.PATH)]];
+  for (const key of ["LANG", "LC_ALL"]) {
+    const value = s.env[key];
+    if (value)
+      out.push([key, value]);
+  }
+  const state = s.env.XDG_STATE_HOME;
+  if (state && isAbsolute2(state))
+    out.push(["XDG_STATE_HOME", state]);
+  if (s.env.PI_CODING_AGENT_DIR)
+    out.push(["PI_CODING_AGENT_DIR", agentDirectory(s)]);
+  return out;
+}
+function checked(value) {
+  if (/[\u0000-\u001f\u007f]/.test(value))
+    throw new ContractError("invalid");
+  return value;
+}
+var specifiers = (value) => checked(value).replaceAll("%", "%%");
+var quoted = (value) => `"${specifiers(value).replace(/["\\]/g, "\\$&")}"`;
+var argument = (value) => quoted(value).replaceAll("$", "$$$$");
+function buildUnit(u) {
+  const command = (args) => [u.node, u.cli, ...args].map(argument).join(" ");
+  return [
+    `${MARKER} on Pi package install/update; upgrades rewrite this file.`,
+    "# Override with `systemctl --user edit cadence`; opt out with `systemctl --user disable --now cadence` or `mask`.",
+    "[Unit]",
+    "Description=Cadence shared task service and WebUI",
+    "Documentation=https://github.com/abelxiaoxing/cadence/blob/main/docs/service-management.md",
+    `ConditionPathExists=${specifiers(u.cli)}`,
+    `ConditionPathExists=${specifiers(join2(u.agentDir, "auth.json"))}`,
+    ...u.sdk.map((path) => `ConditionPathExists=${specifiers(path)}`),
+    "StartLimitIntervalSec=300",
+    "StartLimitBurst=3",
+    "",
+    "[Service]",
+    "Type=simple",
+    `WorkingDirectory=${specifiers(u.workspace)}`,
+    ...u.environment.map(([k, v]) => `Environment=${quoted(`${k}=${v}`)}`),
+    `ExecStart=${command(["start", "--foreground", "--workspace", u.workspace])}`,
+    `ExecStop=-${command(["stop", "--workspace", u.workspace])}`,
+    "KillMode=mixed",
+    "TimeoutStopSec=90",
+    "Restart=on-failure",
+    "RestartSec=10",
+    "",
+    "[Install]",
+    "WantedBy=default.target",
+    ""
+  ].join(`
+`);
+}
+function readGenerated(path) {
+  try {
+    if (!lstatSync2(path).isFile())
+      return null;
+    const text2 = readFileSync(path, "utf8");
+    return text2.startsWith(MARKER) ? text2 : null;
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return;
+    throw error;
+  }
+}
+function generatedWorkspace(text2) {
+  return text2?.match(/^WorkingDirectory=(.+)$/m)?.[1].replaceAll("%%", "%");
+}
+function directory(path) {
+  try {
+    return isAbsolute2(path) && statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function unitStateHome(s) {
+  const state = s.env.XDG_STATE_HOME;
+  return state && isAbsolute2(state) ? state : join2(s.home, ".local", "state");
+}
+function selectWorkspace(s, requested, previous) {
+  let chosen;
+  if (requested) {
+    chosen = expandHome(requested, s.home);
+    if (!directory(chosen))
+      throw new ContractError("invalid");
+    chosen = resolve2(chosen);
+  } else {
+    const kept = generatedWorkspace(previous);
+    if (kept && directory(kept))
+      chosen = kept;
+  }
+  const landing = chosen ? effectiveWorkspace(chosen, unitStateHome(s), s.home) : { workspace: join2(s.home, LANDING_WORKSPACE), redirected: false };
+  if (landing.workspace !== chosen)
+    mkdirSync2(landing.workspace, { recursive: true });
+  return landing.redirected ? { workspace: landing.workspace, redirectedFrom: chosen } : { workspace: landing.workspace };
+}
+function write(path, content) {
+  mkdirSync2(dirname2(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync2(temporary, content, { mode: 420, flag: "wx" });
+    renameSync2(temporary, path);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+function regularFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+function configureAutostart(s, mode, requested) {
+  if (s.platform !== "linux")
+    return { status: "skipped" };
+  if (mode === "refresh" && (s.env.CADENCE_AUTOSTART === "0" || !piUserInstall(s)))
+    return { status: "skipped" };
+  if (s.systemctl(["show-environment"]).status !== 0)
+    return { status: "unavailable" };
+  const path = unitPath(s);
+  const previous = readGenerated(path);
+  if (previous === null)
+    return { status: "foreign", unit: path };
+  const sdk = sdkPackages(s.root);
+  if (!sdk)
+    return { status: "missing-pi-sdk" };
+  const { workspace, redirectedFrom } = selectWorkspace(s, requested ?? s.env.CADENCE_WORKSPACE, previous);
+  const agentDir = agentDirectory(s);
+  const content = buildUnit({
+    node: s.node,
+    cli: join2(s.root, "src", "service-cli.mjs"),
+    workspace,
+    agentDir,
+    sdk,
+    environment: serviceEnvironment(s)
+  });
+  const enabled = s.systemctl(["is-enabled", s.unit]).stdout.trim();
+  const active = s.systemctl(["is-active", "--quiet", s.unit]).status === 0;
+  if (active)
+    s.systemctl(["stop", s.unit]);
+  write(path, content);
+  s.systemctl(["daemon-reload"]);
+  const result = {
+    unit: path,
+    workspace,
+    ...redirectedFrom ? { redirectedFrom } : {}
+  };
+  if (enabled.startsWith("masked"))
+    return { status: "masked", ...result };
+  const wanted = mode === "install" || previous === undefined || enabled === "enabled";
+  if (wanted && enabled !== "enabled" && s.systemctl(["enable", s.unit]).status !== 0)
+    return { status: "failed", ...result };
+  if (!wanted && !active)
+    return { status: "disabled", ...result };
+  if (!regularFile(join2(agentDir, "auth.json")))
+    return { status: "waiting-for-pi-login", ...result };
+  s.systemctl(["reset-failed", s.unit]);
+  const started = s.systemctl(["start", s.unit]).status === 0;
+  return { status: started ? "started" : "failed", ...result };
+}
+function removeAutostart(s) {
+  if (s.platform !== "linux")
+    return { status: "skipped" };
+  const path = unitPath(s);
+  const previous = readGenerated(path);
+  if (previous === null)
+    return { status: "foreign", unit: path };
+  if (previous === undefined)
+    return { status: "absent" };
+  if (s.systemctl(["show-environment"]).status !== 0)
+    return { status: "unavailable", unit: path };
+  if (s.systemctl(["disable", "--now", s.unit]).status !== 0)
+    return { status: "failed", unit: path };
+  rmSync(path);
+  s.systemctl(["daemon-reload"]);
+  s.systemctl(["reset-failed", s.unit]);
+  return { status: "removed", unit: path };
+}
+function autostartStatus(s) {
+  if (s.platform !== "linux")
+    return { status: "skipped" };
+  const path = unitPath(s);
+  const previous = readGenerated(path);
+  if (previous === null)
+    return { status: "foreign", unit: path };
+  if (previous === undefined)
+    return { status: "absent" };
+  return {
+    status: s.systemctl(["is-active", s.unit]).stdout.trim() || "unknown",
+    enabled: s.systemctl(["is-enabled", s.unit]).stdout.trim() || "unknown",
+    unit: path,
+    workspace: generatedWorkspace(previous)
+  };
+}
+
+// src/service/coordination.ts
+import { randomBytes, randomUUID as randomUUID3 } from "node:crypto";
+import { opendirSync, realpathSync as realpathSync3 } from "node:fs";
+import { hostname as hostname2 } from "node:os";
+import { dirname as dirname4, isAbsolute as isAbsolute4, join as join4, relative as relative3, sep as sep4 } from "node:path";
+
 // src/service/private-files.ts
 import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
 import {
@@ -2443,13 +2768,15 @@ import {
   constants as constants2,
   fstatSync as fstatSync2,
   fsyncSync as fsyncSync2,
-  lstatSync as lstatSync2,
+  lstatSync as lstatSync3,
+  mkdirSync as mkdirSync3,
   openSync as openSync2,
-  renameSync as renameSync2,
+  readSync as readSync2,
+  renameSync as renameSync3,
   unlinkSync as unlinkSync2,
-  writeFileSync as writeFileSync2
+  writeFileSync as writeFileSync3
 } from "node:fs";
-import { dirname as dirname2, isAbsolute as isAbsolute2, join as join2, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
+import { dirname as dirname3, isAbsolute as isAbsolute3, join as join3, relative as relative2, resolve as resolve3, sep as sep3 } from "node:path";
 var METADATA_BYTES = 16 * 1024;
 var REGISTRY_BYTES = 1024 * 1024;
 var REGISTRY_ENTRIES = 128;
@@ -2469,42 +2796,112 @@ function same(a, b) {
 function missing(error) {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
+var job = 0;
+var advancing = false;
+function currentJob() {
+  if (!advancing) {
+    advancing = true;
+    queueMicrotask(() => {
+      job++;
+      advancing = false;
+    });
+  }
+  return job;
+}
+
+class DirectoryWalks {
+  job = currentJob();
+  walked = new Map;
+  open() {
+    if (this.job === job)
+      return true;
+    this.walked.clear();
+    return false;
+  }
+  remember(path, st) {
+    if (this.open())
+      this.walked.set(path, { dev: st.dev, ino: st.ino });
+  }
+  reuse(path) {
+    const walked = this.open() ? this.walked.get(path) : undefined;
+    if (!walked)
+      return false;
+    let st;
+    try {
+      st = lstatSync3(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);
+    return true;
+  }
+}
 
 class PrivateFiles {
   namespace;
   constructor(namespace) {
     this.namespace = namespace;
   }
-  directory(path, create = false) {
+  directory(path, create = false, walks) {
     const tail = relative2(this.namespace, path);
-    if (isAbsolute2(tail) || tail === ".." || tail.startsWith(`..${sep2}`))
+    if (isAbsolute3(tail) || tail === ".." || tail.startsWith(`..${sep3}`))
       refused();
     if (!create) {
-      const namespace = resolve2(this.namespace);
-      let inside = false;
-      return safeDirectory(path, false, (at2, st) => {
+      const full = resolve3(path);
+      if (walks?.reuse(full))
+        return true;
+      const namespace = resolve3(this.namespace);
+      let inside = false, last;
+      const found = safeDirectory(path, false, (at2, st) => {
         if (at2 === namespace)
           inside = true;
         if (inside)
           privateMode(st);
+        last = st;
       });
+      if (found && last)
+        walks?.remember(full, last);
+      return found;
     }
+    if (!safeDirectory(this.namespace, true))
+      return false;
+    privateMode(lstatSync3(this.namespace));
     let at = this.namespace;
-    for (const part of ["", ...tail.split(sep2).filter(Boolean)]) {
-      if (part)
-        at = join2(at, part);
-      if (!safeDirectory(at, create))
-        return false;
-      privateMode(lstatSync2(at));
+    for (const part of tail.split(sep3).filter(Boolean)) {
+      at = join3(at, part);
+      let st;
+      try {
+        st = lstatSync3(at);
+      } catch (error) {
+        if (!missing(error))
+          throw error;
+        try {
+          mkdirSync3(at, { mode: 448 });
+        } catch (mkdirError) {
+          if (!(mkdirError instanceof Error && ("code" in mkdirError) && mkdirError.code === "EEXIST"))
+            throw mkdirError;
+        }
+        st = lstatSync3(at);
+      }
+      if (!st.isDirectory() || st.isSymbolicLink())
+        throw new Error("Unsafe directory");
+      privateMode(st);
     }
     return true;
   }
-  read(path, maximum = METADATA_BYTES) {
-    if (!this.directory(dirname2(path)))
+  read(path, maximum = METADATA_BYTES, walks) {
+    if (!this.directory(dirname3(path), false, walks))
       return;
     let before;
     try {
-      before = lstatSync2(path);
+      before = lstatSync3(path);
     } catch (error) {
       if (missing(error))
         return;
@@ -2518,31 +2915,39 @@ class PrivateFiles {
       const opened = fstatSync2(fd);
       if (!same(before, opened))
         refused();
-      const bytes = readBounded(path, opened.size);
-      if (!bytes || bytes.length !== opened.size || !same(opened, fstatSync2(fd)) || !same(opened, lstatSync2(path)))
+      const buffer = Buffer.alloc(opened.size + 1);
+      let size = 0;
+      while (size < buffer.length) {
+        const n = readSync2(fd, buffer, size, buffer.length - size, null);
+        if (!n)
+          break;
+        size += n;
+      }
+      const bytes = buffer.subarray(0, size);
+      if (size !== opened.size || !same(opened, fstatSync2(fd)) || !same(opened, lstatSync3(path)))
         refused();
       return { bytes, identity: hash(bytes), stamp: stamp(opened) };
     } finally {
       closeSync2(fd);
     }
   }
-  assert(path, expected, maximum = METADATA_BYTES) {
-    const current = this.read(path, maximum);
+  assert(path, expected, maximum = METADATA_BYTES, walks) {
+    const current = this.read(path, maximum, walks);
     if (current?.identity !== expected?.identity || current?.stamp !== expected?.stamp)
       throw new ContractError("conflict");
   }
   create(path, bytes, maximum = METADATA_BYTES) {
     if (Buffer.byteLength(bytes) > maximum)
       throw new ContractError("oversize");
-    this.directory(dirname2(path), true);
-    const fd = openSync2(path, "wx", 384);
+    this.directory(dirname3(path), true);
+    const fd = retryWindowsFileOperation(() => openSync2(path, "wx", 384));
     try {
-      writeFileSync2(fd, bytes);
+      writeFileSync3(fd, bytes);
       fsyncSync2(fd);
     } finally {
       closeSync2(fd);
     }
-    this.syncDirectory(dirname2(path));
+    this.syncDirectory(dirname3(path));
     const result = this.read(path, maximum);
     if (!result || result.identity !== hash(bytes))
       refused();
@@ -2550,11 +2955,11 @@ class PrivateFiles {
   }
   replace(path, expected, bytes, maximum = METADATA_BYTES) {
     this.assert(path, expected, maximum);
-    const temporary = join2(dirname2(path), `pending-${randomUUID2()}.json`);
+    const temporary = join3(dirname3(path), `pending-${randomUUID2()}.json`);
     this.create(temporary, bytes, maximum);
     this.assert(path, expected, maximum);
-    renameSync2(temporary, path);
-    this.syncDirectory(dirname2(path));
+    retryWindowsFileOperation(() => renameSync3(temporary, path), () => this.assert(path, expected, maximum));
+    this.syncDirectory(dirname3(path));
     const result = this.read(path, maximum);
     if (!result || result.identity !== hash(bytes))
       refused();
@@ -2562,8 +2967,8 @@ class PrivateFiles {
   }
   remove(path, expected, maximum = METADATA_BYTES) {
     this.assert(path, expected, maximum);
-    unlinkSync2(path);
-    this.syncDirectory(dirname2(path));
+    retryWindowsFileOperation(() => unlinkSync2(path), () => this.assert(path, expected, maximum));
+    this.syncDirectory(dirname3(path));
   }
   syncDirectory(path) {
     if (process.platform === "win32")
@@ -2617,7 +3022,7 @@ var registrationKeys = [
 var reservationKeys = registrationKeys.filter((k) => !["schema", "phase", "checkoutToken"].includes(k));
 function pathValue(value) {
   const path = text(value, 4096, true);
-  if (!isAbsolute3(path))
+  if (!isAbsolute4(path))
     refused();
   return path;
 }
@@ -2674,7 +3079,7 @@ function decodeRegistration(value) {
 function rootsOverlap(a, b) {
   const within = (x, y) => {
     const r = relative3(x, y);
-    return r === "" || r !== ".." && !r.startsWith(`..${sep3}`) && !isAbsolute3(r);
+    return r === "" || r !== ".." && !r.startsWith(`..${sep4}`) && !isAbsolute4(r);
   };
   return within(a, b) || within(b, a);
 }
@@ -2726,17 +3131,17 @@ class ServiceCoordination {
   stateHome;
   constructor(workspace, stateHome) {
     this.store = new TaskStore(resolveWorkspace(workspace).root, stateHome);
-    const namespace = dirname3(this.store.privateRoot);
+    const namespace = dirname4(this.store.privateRoot);
     this.files = new PrivateFiles(namespace);
-    this.stateHome = dirname3(namespace);
-    this.directory = join3(this.store.privateRoot, "service-v1");
-    this.registryDirectory = join3(namespace, "service-registry-v1");
+    this.stateHome = dirname4(namespace);
+    this.directory = join4(this.store.privateRoot, "service-v1");
+    this.registryDirectory = join4(namespace, "service-registry-v1");
   }
   path(name) {
-    return join3(this.directory, name);
+    return join4(this.directory, name);
   }
   registryPath(name) {
-    return join3(this.registryDirectory, name);
+    return join4(this.registryDirectory, name);
   }
   registry() {
     if (!this.files.directory(this.registryDirectory))
@@ -2756,7 +3161,7 @@ class ServiceCoordination {
     const o = closed(json(snapshot, REGISTRY_BYTES), ["schema", "entries"]);
     const entries = list(o.entries, REGISTRY_ENTRIES, decodeReservation);
     for (const [i, row] of entries.entries()) {
-      if (row.stateHome !== this.stateHome || realpathSync2(row.root) !== row.root)
+      if (row.stateHome !== this.stateHome || realpathSync3(row.root) !== row.root)
         refused();
       if (entries.slice(0, i).some((other) => rootsOverlap(row.root, other.root) || row.endpoint === other.endpoint))
         refused();
@@ -2770,8 +3175,8 @@ class ServiceCoordination {
       }
     };
   }
-  assertNamespace() {
-    if (!this.files.directory(this.directory))
+  assertNamespace(walks) {
+    if (!this.files.directory(this.directory, false, walks))
       refused();
     names(this.directory, [
       "format.json",
@@ -2784,14 +3189,15 @@ class ServiceCoordination {
       "host-config.json",
       "history-v2"
     ]);
-    this.files.directory(join3(this.directory, "history-v2"));
+    this.files.directory(join4(this.directory, "history-v2"), false, walks);
   }
   selected() {
-    if (!this.files.directory(this.directory))
+    const walks = new DirectoryWalks;
+    if (!this.files.directory(this.directory, false, walks))
       return;
-    this.assertNamespace();
-    const manifest = this.files.read(this.path("format.json"));
-    const config = this.files.read(this.path("config.json"));
+    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), [
@@ -2805,13 +3211,13 @@ 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;
     if (value && (value.root !== this.store.root || value.stateHome !== this.stateHome || value.configIdentity !== config.identity || !endpointMatches(c.endpoint, value.endpoint)))
       refused();
@@ -3158,8 +3564,8 @@ class OwnerLease {
   assert() {
     if (this.released || this.selected.value.pid !== process.pid || this.selected.value.host !== hostname2())
       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],
@@ -3168,8 +3574,8 @@ class OwnerLease {
       ["owner.lock", this.selected.owner],
       ["local-capability.json", this.selected.capability]
     ])
-      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) {
@@ -3208,8 +3614,8 @@ import { isatty } from "node:tty";
 
 // src/history/recovery.ts
 import { createHash as createHash5, randomUUID as randomUUID5 } from "node:crypto";
-import { lstatSync as lstatSync5, opendirSync as opendirSync3 } from "node:fs";
-import { join as join5, relative as relative4 } from "node:path";
+import { lstatSync as lstatSync6, opendirSync as opendirSync3 } from "node:fs";
+import { join as join6, relative as relative4 } from "node:path";
 
 // src/service/recovery.ts
 async function inspectRecovery(coordination, history) {
@@ -3263,13 +3669,13 @@ import {
   constants as constants4,
   fstatSync as fstatSync4,
   fsyncSync as fsyncSync3,
-  lstatSync as lstatSync4,
+  lstatSync as lstatSync5,
   opendirSync as opendirSync2,
   openSync as openSync4,
   statfsSync
 } from "node:fs";
 import { open } from "node:fs/promises";
-import { dirname as dirname5, join as join4 } from "node:path";
+import { dirname as dirname6, join as join5 } from "node:path";
 
 // src/history/admission.ts
 function decodeRunAdmission(value) {
@@ -3293,19 +3699,19 @@ import {
   closeSync as closeSync3,
   constants as constants3,
   fstatSync as fstatSync3,
-  lstatSync as lstatSync3,
+  lstatSync as lstatSync4,
   openSync as openSync3,
-  readSync as readSync2
+  readSync as readSync3
 } from "node:fs";
-import { dirname as dirname4 } from "node:path";
+import { dirname as dirname5 } from "node:path";
 function bad() {
   throw new ContractError("corrupt-selected");
 }
 var stamp2 = (s) => [s.dev, s.ino, s.size, s.mode, s.uid, s.nlink, s.ctimeMs, s.mtimeMs].join(":");
-function selected(files, path, read) {
-  if (!files.files.directory(dirname4(path)))
+function selected(files, path, read, walks) {
+  if (!files.files.directory(dirname5(path), false, walks))
     bad();
-  const before = lstatSync3(path);
+  const before = lstatSync4(path);
   if (!before.isFile() || before.nlink !== 1 || process.platform !== "win32" && (before.mode & 63 || process.getuid && before.uid !== process.getuid()))
     bad();
   const fd = openSync3(path, constants3.O_RDONLY | (constants3.O_NOFOLLOW ?? 0));
@@ -3313,7 +3719,7 @@ function selected(files, path, read) {
     if (stamp2(fstatSync3(fd)) !== stamp2(before))
       bad();
     const result = read(fd, before.size, stamp2(before));
-    if (stamp2(fstatSync3(fd)) !== stamp2(before) || stamp2(lstatSync3(path)) !== stamp2(before))
+    if (stamp2(fstatSync3(fd)) !== stamp2(before) || stamp2(lstatSync4(path)) !== stamp2(before))
       bad();
     return result;
   } finally {
@@ -3764,13 +4170,24 @@ function decodeJournalText(line) {
 
 // src/history/files.ts
 class HistoryReadBudget {
+  clock;
   started = performance.now();
   bytes = 0;
+  walks = new DirectoryWalks;
+  constructor(clock = true) {
+    this.clock = clock;
+  }
+  static authority() {
+    return new HistoryReadBudget(false);
+  }
   reserve(bytes) {
-    if (!Number.isSafeInteger(bytes) || bytes < 0 || this.bytes + bytes > LIMITS.searchBytes || performance.now() - this.started >= LIMITS.searchMs)
+    if (!Number.isSafeInteger(bytes) || bytes < 0 || this.bytes + bytes > LIMITS.searchBytes || this.elapsed)
       throw new ContractError("receipt-inconclusive");
     this.bytes += bytes;
   }
+  get elapsed() {
+    return this.clock && performance.now() - this.started >= LIMITS.searchMs;
+  }
 }
 function corrupt() {
   throw new ContractError("corrupt-selected");
@@ -3789,14 +4206,14 @@ class HistoryFiles {
     this.coordination = coordination;
     this.format = format;
     this.formatSnapshot = formatSnapshot;
-    this.directory = join4(coordination.directory, "history-v2");
+    this.directory = join5(coordination.directory, "history-v2");
     this.files = coordination.files;
   }
   static open(coordination) {
-    const dir = join4(coordination.directory, "history-v2");
+    const dir = join5(coordination.directory, "history-v2");
     if (!coordination.files.directory(dir))
       return;
-    const file = coordination.files.read(join4(dir, "format.json"));
+    const file = coordination.files.read(join5(dir, "format.json"));
     if (!file)
       corrupt();
     const format = decodeFormat(json(file));
@@ -3812,7 +4229,7 @@ class HistoryFiles {
       existing.assertWritable();
       return existing;
     }
-    const dir = join4(c.directory, "history-v2");
+    const dir = join5(c.directory, "history-v2");
     const format = {
       schema: FORMAT,
       storeId: randomUUID4(),
@@ -3822,19 +4239,19 @@ class HistoryFiles {
     c.files.directory(dir, true);
     for (const name of ["commands", "ledger", "runs", "indexes"]) {
       lease.assert();
-      c.files.directory(join4(dir, name), true);
+      c.files.directory(join5(dir, name), true);
     }
     lease.assert();
-    const keyPath = join4(dir, "read-proof-key.json");
+    const keyPath = join5(dir, "read-proof-key.json");
     c.files.create(keyPath, encoded({
       schema: "cadence-history-read-key/1",
       storeId: format.storeId,
       key: randomBytes2(32).toString("base64url")
     }));
     lease.assert();
-    const snapshot = c.files.create(join4(dir, "format.json"), encoded(format));
+    const snapshot = c.files.create(join5(dir, "format.json"), encoded(format));
     const result = new HistoryFiles(c, format, snapshot);
-    result.syncParents(join4(dir, "format.json"));
+    result.syncParents(join5(dir, "format.json"));
     result.assertWritable();
     return result;
   }
@@ -3869,7 +4286,7 @@ class HistoryFiles {
       throw new ContractError("quarantine");
   }
   assertFormat() {
-    this.files.assert(join4(this.directory, "format.json"), this.formatSnapshot);
+    this.files.assert(join5(this.directory, "format.json"), this.formatSnapshot);
   }
   readProofMaterial(budget) {
     if (this.format.schema !== FORMAT)
@@ -3878,7 +4295,7 @@ class HistoryFiles {
       this.assertReadFormat(budget);
     else
       this.assertFormat();
-    const selected2 = this.readBudgeted(join4(this.directory, "read-proof-key.json"), 512, budget);
+    const selected2 = this.readBudgeted(join5(this.directory, "read-proof-key.json"), 512, budget);
     if (!selected2 || this.proofSnapshot && (selected2.identity !== this.proofSnapshot.identity || selected2.stamp !== this.proofSnapshot.stamp))
       corrupt();
     try {
@@ -3906,17 +4323,17 @@ class HistoryFiles {
       return;
     }
     this.assertFormat();
-    assertIncarnation(this, join4(this.directory, "read-proof-key.json"), this.proofSnapshot.stamp);
+    assertIncarnation(this, join5(this.directory, "read-proof-key.json"), this.proofSnapshot.stamp);
   }
   segmentPath(segment) {
-    return join4(this.directory, "ledger", `${String(segment).padStart(12, "0")}.jsonl`);
+    return join5(this.directory, "ledger", `${String(segment).padStart(12, "0")}.jsonl`);
   }
   artifactPath(ref) {
-    return join4(this.directory, "runs", ref.runId, "artifacts", ref.artifactId, `${ref.part}.part`);
+    return join5(this.directory, "runs", ref.runId, "artifacts", ref.artifactId, `${ref.part}.part`);
   }
   admissionPath(runId) {
     decodeId(runId);
-    return join4(this.directory, "runs", runId, "admission.json");
+    return join5(this.directory, "runs", runId, "admission.json");
   }
   writeAdmission(lease, input) {
     lease.assert();
@@ -3930,19 +4347,19 @@ class HistoryFiles {
       return this.files.read(path, maximum);
     let size;
     try {
-      size = lstatSync4(path).size;
+      size = lstatSync5(path).size;
     } catch {
-      return this.files.read(path, 0);
+      return this.files.read(path, 0, budget.walks);
     }
     if (size > maximum)
       corrupt();
     budget.reserve(size);
-    return this.files.read(path, size);
+    return this.files.read(path, size, budget.walks);
   }
   readCommand(commandId, budget) {
     decodeId(commandId);
     this.assertReadFormat(budget);
-    return this.readBudgeted(join4(this.directory, "commands", commandId, "intent.json"), RECORD_BYTES, budget);
+    return this.readBudgeted(join5(this.directory, "commands", commandId, "intent.json"), RECORD_BYTES, budget);
   }
   readAdmission(runId, identity, budget) {
     return this.readAdmissionIdentity(runId, hash(canonicalJson(identity)), budget);
@@ -3963,7 +4380,7 @@ class HistoryFiles {
   syncParents(file) {
     if (process.platform === "win32")
       return;
-    for (let path = dirname5(file);; path = dirname5(path)) {
+    for (let path = dirname6(file);; path = dirname6(path)) {
       if (!this.files.directory(path))
         corrupt();
       const fd = openSync4(path, constants4.O_RDONLY | constants4.O_DIRECTORY);
@@ -3974,13 +4391,13 @@ class HistoryFiles {
       }
       if (path === this.coordination.directory)
         break;
-      if (path === dirname5(path))
+      if (path === dirname6(path))
         corrupt();
     }
   }
   assertReadFormat(budget) {
     budget.reserve(this.formatSnapshot.bytes.length);
-    this.files.assert(join4(this.directory, "format.json"), this.formatSnapshot, this.formatSnapshot.bytes.length);
+    this.files.assert(join5(this.directory, "format.json"), this.formatSnapshot, this.formatSnapshot.bytes.length);
   }
   assertPublished(segment, end, seq) {
     const fence = publicationFences.get(this.directory);
@@ -4018,7 +4435,7 @@ class HistoryFiles {
       const dir = opendirSync2(path);
       try {
         for (let e = dir.readSync();e; e = dir.readSync()) {
-          const p = join4(path, e.name), st = lstatSync4(p);
+          const p = join5(path, e.name), st = lstatSync5(p);
           if (st.isDirectory())
             bytes += walk(p, depth + 1);
           else {
@@ -4053,7 +4470,7 @@ class HistoryFiles {
     state.bytes = 0;
     state.identity = null;
     let count = 0;
-    const ledger = join4(this.directory, "ledger");
+    const ledger = join5(this.directory, "ledger");
     if (!this.files.directory(ledger))
       corrupt();
     const dir = opendirSync2(ledger);
@@ -4218,7 +4635,7 @@ class HistoryFiles {
     let committed;
     const fd = await open(path, constants4.O_WRONLY | constants4.O_APPEND | (constants4.O_NOFOLLOW ?? 0));
     const assertOriginal = (bytes) => {
-      const original = fstatSync4(fd.fd), selected2 = lstatSync4(path);
+      const original = fstatSync4(fd.fd), selected2 = lstatSync5(path);
       if (original.dev !== selected2.dev || original.ino !== selected2.ino || original.nlink !== 1)
         corrupt();
       const snapshot = this.files.read(path, LIMITS.segmentBytes);
@@ -4335,7 +4752,7 @@ class HistoryFiles {
     try {
       lease.assert();
       this.files.assert(path, before, LIMITS.segmentBytes);
-      const opened = await fd.stat(), selected2 = lstatSync4(path);
+      const opened = await fd.stat(), selected2 = lstatSync5(path);
       if (opened.ino !== selected2.ino || opened.dev !== selected2.dev || opened.nlink !== 1)
         corrupt();
       beforeEffect?.();
@@ -4370,7 +4787,7 @@ class HistoryFiles {
   checkpoint(lease, state) {
     lease.assert();
     this.assertWritable();
-    const path = join4(this.directory, "checkpoint.json"), old = this.files.read(path);
+    const path = join5(this.directory, "checkpoint.json"), old = this.files.read(path);
     const body = encoded({
       schema: "cadence-history-checkpoint/2",
       storeId: this.format.storeId,
@@ -4783,8 +5200,8 @@ function digestHistory(files, exclude) {
   const walk = (path, depth) => {
     if (depth > 8 || !files.files.directory(path))
       throw new ContractError("corrupt-selected");
-    const directory = lstatSync5(path);
-    digest.update(`incarnation:${directory.dev}:${directory.ino}
+    const directory2 = lstatSync6(path);
+    digest.update(`incarnation:${directory2.dev}:${directory2.ino}
 `);
     const dir = opendirSync3(path), names2 = [];
     try {
@@ -4797,11 +5214,11 @@ function digestHistory(files, exclude) {
       dir.closeSync();
     }
     for (const name of names2.sort()) {
-      const selected2 = join5(path, name);
+      const selected2 = join6(path, name);
       if (selected2 === exclude)
         continue;
       const rel = relative4(files.directory, selected2);
-      if (lstatSync5(selected2).isDirectory()) {
+      if (lstatSync6(selected2).isDirectory()) {
         digest.update(`directory:${Buffer.byteLength(rel)}:${rel}
 `);
         walk(selected2, depth + 1);
@@ -5015,7 +5432,7 @@ async function confirm(expected) {
       `resolve ${expected.epoch}`
     ]
   ];
-  await new Promise((resolve3, reject) => {
+  await new Promise((resolve4, reject) => {
     let index = 0, line = "", done = false;
     const raw = process.stdin.isRaw;
     const finish = (ok) => {
@@ -5031,7 +5448,7 @@ async function confirm(expected) {
       process.stdout.write(`\x1B[?2004l
 `);
       if (ok)
-        resolve3();
+        resolve4();
       else
         reject(new ContractError("forbidden"));
     };
@@ -5107,8 +5524,8 @@ async function localRecovery(c, operation) {
 }
 
 // src/service/runtime.ts
-import { homedir as homedir2 } from "node:os";
-import { dirname as dirname6, isAbsolute as isAbsolute4, join as join6, resolve as resolve3 } from "node:path";
+import { homedir as homedir3 } from "node:os";
+import { dirname as dirname7, isAbsolute as isAbsolute5, join as join7, resolve as resolve4 } from "node:path";
 
 // src/service/config.ts
 import { isIP } from "node:net";
@@ -5162,7 +5579,7 @@ function localOrigin(policy, actualPort) {
 var STARTUP_INPUT_BYTES = 16 * 1024;
 function absolute(value) {
   const result = text(value, 4096, true);
-  if (!isAbsolute4(result))
+  if (!isAbsolute5(result))
     throw new ContractError("invalid");
   return result;
 }
@@ -5242,7 +5659,7 @@ function selectStart(options, ambient) {
     throw new ContractError("invalid");
   let fromFile;
   if (options.config) {
-    const path = resolve3(options.config), f = new PrivateFiles(dirname6(path));
+    const path = resolve4(options.config), f = new PrivateFiles(dirname7(path));
     const bytes = f.read(path);
     if (!bytes)
       throw new ContractError("corrupt-selected");
@@ -5257,11 +5674,11 @@ function selectStart(options, ambient) {
       port: options.port ?? 17423,
       proxy: null
     },
-    agentDir: resolve3(options.agentDir ?? ambient.PI_CODING_AGENT_DIR ?? join6(ambient.HOME ?? ambient.USERPROFILE ?? homedir2(), ".pi", "agent")),
+    agentDir: resolve4(options.agentDir ?? ambient.PI_CODING_AGENT_DIR ?? join7(ambient.HOME ?? ambient.USERPROFILE ?? homedir3(), ".pi", "agent")),
     tokenSource: options.tokenFile ? "file" : env ? "environment" : "generated",
-    tokenFile: options.tokenFile ? resolve3(options.tokenFile) : null
+    tokenFile: options.tokenFile ? resolve4(options.tokenFile) : null
   });
-  if (fromFile && encoded(fromFile) !== encoded(selected2) || options.port !== undefined && options.port !== selected2.http.port || options.host !== undefined && options.host !== selected2.http.host || options.agentDir !== undefined && resolve3(options.agentDir) !== selected2.agentDir || options.tokenFile !== undefined && resolve3(options.tokenFile) !== selected2.tokenFile || env && selected2.tokenSource !== "environment" || selected2.tokenSource === "environment" && !env || resolveWorkspace(selected2.cwd).root !== workspace.root)
+  if (fromFile && encoded(fromFile) !== encoded(selected2) || options.port !== undefined && options.port !== selected2.http.port || options.host !== undefined && options.host !== selected2.http.host || options.agentDir !== undefined && resolve4(options.agentDir) !== selected2.agentDir || options.tokenFile !== undefined && resolve4(options.tokenFile) !== selected2.tokenFile || env && selected2.tokenSource !== "environment" || selected2.tokenSource === "environment" && !env || resolveWorkspace(selected2.cwd).root !== workspace.root)
     throw new ContractError("conflict");
   return {
     workspace: workspace.root,
@@ -5293,21 +5710,37 @@ function portValue(value) {
     throw new ContractError("invalid");
   return integer(Number(value), 0, 65535);
 }
+var STARTUP_STAGES = [
+  "package",
+  "pi-agent-directory",
+  "pi-auth",
+  "pi-models",
+  "pi-runtime",
+  "service"
+];
+function decodeStartupReport(value) {
+  const o = closed(value, ["status", "error", "stage"]);
+  return {
+    status: oneOf(o.status, ["refused", "quarantined"]),
+    error: oneOf(o.error, ERROR_CODES),
+    stage: oneOf(o.stage, STARTUP_STAGES)
+  };
+}
 
 // src/service/cli.ts
 function nativeCall(c, operation, reveal = false) {
   const access = c.localAccess();
   const url = new URL(`${access.endpoint}/local/v1/admin/${operation}`);
-  const write = !["status", "diagnose"].includes(operation);
-  const body = write ? JSON.stringify(reveal ? { reveal: true } : {}) : undefined;
-  return new Promise((resolve4, reject) => {
+  const write2 = !["status", "diagnose"].includes(operation);
+  const body = write2 ? JSON.stringify(reveal ? { reveal: true } : {}) : undefined;
+  return new Promise((resolve6, reject) => {
     let timer;
     const fail = () => {
       clearTimeout(timer);
       reject(new ContractError("unavailable"));
     };
     const req = request(url, {
-      method: write ? "POST" : "GET",
+      method: write2 ? "POST" : "GET",
       agent: false,
       headers: {
         "X-Cadence-Local": access.capability,
@@ -5341,7 +5774,7 @@ function nativeCall(c, operation, reveal = false) {
               throw new ContractError("stale");
           }
           clearTimeout(timer);
-          resolve4(reply.value);
+          resolve6(reply.value);
         } catch {
           fail();
         }
@@ -5356,7 +5789,7 @@ function nativeCall(c, operation, reveal = false) {
     req.end(body);
   });
 }
-var pause = (ms) => new Promise((resolve4) => setTimeout(resolve4, ms));
+var pause = (ms) => new Promise((resolve6) => setTimeout(resolve6, ms));
 async function serviceStatus(c, diagnose = false) {
   const observed = c.inspect();
   if (observed.status === "absent" || observed.status === "stopped")
@@ -5393,7 +5826,38 @@ async function stopService(c) {
   return { status: "unconfirmed", epoch };
 }
 function failedStatus(result) {
-  return !!(result && typeof result === "object" && ("status" in result) && ["unconfirmed", "unavailable", "quarantined"].includes(String(result.status)));
+  return !!(result && typeof result === "object" && ("status" in result) && ["unconfirmed", "unavailable", "quarantined", "refused"].includes(String(result.status)));
+}
+function startupGuidance(result, input) {
+  let report;
+  try {
+    report = decodeStartupReport(result);
+  } catch {
+    return "";
+  }
+  const agent = input.config.agentDir;
+  const inspect = `Inspect: cadence-service diagnose|recover inspect --workspace ${JSON.stringify(input.workspace)}
+`;
+  switch (report.stage) {
+    case "package":
+      return `Cadence refused its installed package files (web/dist or agents); reinstall the package rather than editing it.
+`;
+    case "pi-agent-directory":
+      return `Pi's agent directory ${agent} must be an existing real directory owned by you with mode 0700 (chmod 700).
+`;
+    case "pi-auth":
+      return `${join8(agent, "auth.json")} must be your own single-link regular file with mode 0600 holding valid Pi credentials; log in to Pi first.
+`;
+    case "pi-models":
+      return `${join8(agent, "models.json")} must be your own single-link regular file with mode 0600, using only fields Cadence's pinned Pi SDK supports; a field only newer Pi understands is refused.
+`;
+    case "pi-runtime":
+      return `Loading Pi's SDK model runtime failed after the owner registered (optional SDK packages missing, or sources the SDK refuses); it stays quarantined.
+${inspect}`;
+    default:
+      return report.status === "quarantined" ? `The owner registered, then refused; it stays quarantined.
+${inspect}` : "";
+  }
 }
 async function startService(options, foreground, hostUrl) {
   const network = networkSnapshot(process.env);
@@ -5420,18 +5884,18 @@ async function startService(options, foreground, hostUrl) {
     stdio: ["pipe", "pipe", "ignore"]
   });
   let completed = false;
-  const closure = new Promise((resolve4) => child.once("close", (code, signal) => {
+  const closure = new Promise((resolve6) => child.once("close", (code, signal) => {
     completed = true;
     if (foreground && (code !== 0 || signal !== null))
       process.exitCode = 1;
-    resolve4();
+    resolve6();
   }));
-  const startup = new Promise((resolve4) => {
+  const startup = new Promise((resolve6) => {
     let bytes = "", resolved = false;
     const finish = (value) => {
       if (!resolved) {
         resolved = true;
-        resolve4(value);
+        resolve6(value);
       }
     };
     child.on("error", () => finish({ status: "unconfirmed" }));
@@ -5447,7 +5911,12 @@ async function startService(options, foreground, hostUrl) {
 `))
         return;
       try {
-        const ready = closed(parseWireJson(bytes, 4096), ["status", "epoch"]);
+        const line = parseWireJson(bytes, 4096);
+        if (line && typeof line === "object" && "status" in line && line.status !== "ready") {
+          finish(decodeStartupReport(line));
+          return;
+        }
+        const ready = closed(line, ["status", "epoch"]);
         if (ready.status !== "ready")
           throw new ContractError("unavailable");
         const epoch = decodeId(ready.epoch);
@@ -5466,11 +5935,14 @@ async function startService(options, foreground, hostUrl) {
   let timer;
   const result = await Promise.race([
     startup,
-    new Promise((resolve4) => {
-      timer = setTimeout(() => resolve4({ status: "unconfirmed" }), LIMITS.startWaitMs);
+    new Promise((resolve6) => {
+      timer = setTimeout(() => resolve6({ status: "unconfirmed" }), LIMITS.startWaitMs);
     })
   ]);
   clearTimeout(timer);
+  const guidance = startupGuidance(result, input);
+  if (guidance)
+    process.stderr.write(guidance);
   child.stdout.destroy();
   child.stdin.destroy();
   if (!foreground)
@@ -5485,6 +5957,104 @@ async function startService(options, foreground, hostUrl) {
   }
   return result;
 }
+async function observeStarted(workspace) {
+  const deadline = performance.now() + LIMITS.startWaitMs + 2000;
+  let service = "unconfirmed";
+  while (performance.now() < deadline) {
+    try {
+      const c = new ServiceCoordination(workspace);
+      const observed = await serviceStatus(c);
+      if (observed && typeof observed === "object" && "status" in observed)
+        service = String(observed.status);
+      if (service === "alive")
+        return { service, endpoint: c.localAccess().endpoint };
+      if (service === "quarantined")
+        break;
+    } catch {}
+    await pause(250);
+  }
+  return { service };
+}
+function autostartGuidance(s, result) {
+  const name = s.unit.replace(/\.service$/, "");
+  const cli = JSON.stringify(join8(s.root, "src", "service-cli.mjs"));
+  const workspace = JSON.stringify(result.workspace ?? "");
+  const manage = `Manage: systemctl --user status|restart|stop ${name}; logs: journalctl --user -u ${name}; opt out: systemctl --user disable --now ${name}`;
+  const note = result.redirectedFrom ? `Cadence workspace: ${result.workspace} (${result.redirectedFrom} contains Cadence's private state)
+` : "";
+  return note + autostartStatusGuidance(s, result, name, cli, workspace, manage);
+}
+function autostartStatusGuidance(s, result, name, cli, workspace, manage) {
+  switch (result.status) {
+    case "started": {
+      if (result.service !== "alive")
+        return `${s.unit} started for ${result.workspace}, but the owner reports ${result.service}.
+Inspect: node ${cli} diagnose --workspace ${workspace}
+${manage}
+`;
+      const linger = s.linger() === false ? "Linger is off: Cadence starts at login and stops at logout. `loginctl enable-linger` keeps it running and starts it at boot.\n" : "";
+      return `Cadence WebUI: ${result.endpoint} (${s.unit}, workspace ${result.workspace})
+Enter with your private link: node ${cli} token-link --workspace ${workspace} --reveal
+${manage}
+${linger}`;
+    }
+    case "waiting-for-pi-login":
+      return `${s.unit} is enabled for ${result.workspace}; it starts once Pi has ${join8(agentDirectory(s), "auth.json")}.
+Log in to Pi, then: systemctl --user start ${name}
+`;
+    case "disabled":
+      return `${s.unit} refreshed for ${result.workspace}; left disabled as configured.
+`;
+    case "masked":
+      return `${s.unit} is masked; Cadence did not enable or start it.
+`;
+    case "missing-pi-sdk":
+      return `Cadence did not register or refresh ${s.unit}: the Pi SDK packages pi-coding-agent and pi-ai (scope @earendil-works) do not resolve from ${s.root}, for example after installing without optional dependencies; an owner without them would quarantine.
+`;
+    case "foreign":
+      return `${result.unit} was not generated by Cadence; left unchanged.
+`;
+    case "unavailable":
+      return `No systemd user manager; start Cadence explicitly: node ${cli} start --workspace /absolute/project
+`;
+    case "failed":
+      return `Could not enable or start ${s.unit}; see systemctl --user status ${name} and journalctl --user -u ${name}.
+`;
+    default:
+      return "";
+  }
+}
+async function autostartMain(argv, hostUrl) {
+  const action = argv.shift();
+  let requested;
+  if (action === "install" && argv[0] === "--workspace" && argv[1])
+    requested = resolve5(argv.splice(0, 2)[1]);
+  if (argv.length || !["install", "refresh", "remove", "status"].includes(action ?? ""))
+    throw new ContractError("invalid");
+  const s = hostSystem(dirname8(dirname8(fileURLToPath(hostUrl))));
+  let result;
+  if (action === "remove")
+    result = removeAutostart(s);
+  else if (action === "status")
+    result = autostartStatus(s);
+  else {
+    try {
+      result = configureAutostart(s, action === "install" ? "install" : "refresh", requested);
+    } catch (error) {
+      if (error instanceof ContractError && error.code === "invalid")
+        process.stderr.write(`Cadence autostart needs an existing absolute workspace directory (--workspace or CADENCE_WORKSPACE).
+`);
+      throw error;
+    }
+    if (result.status === "started" && result.workspace)
+      Object.assign(result, await observeStarted(result.workspace));
+    process.stderr.write(autostartGuidance(s, result));
+  }
+  process.stdout.write(`${JSON.stringify(result)}
+`);
+  if (["failed", "foreign", "unavailable"].includes(result.status))
+    process.exitCode = 1;
+}
 async function managementMain(argv, hostUrl) {
   try {
     if (!process.versions.node || process.versions.bun)
@@ -5492,12 +6062,17 @@ async function managementMain(argv, hostUrl) {
     const command = argv.shift();
     if (command === "--help" && !argv.length) {
       process.stdout.write(`cadence-service start|status|diagnose|stop|token-link --reveal|token-rotate|recover inspect|recover resolve [--workspace PATH] [--state-home PATH]
-Explicit start only; default detached or --foreground. Start accepts --config, --agent-dir, --host, --port, --token-file.
+cadence-service autostart install [--workspace PATH]|refresh|remove|status
+Start is explicit, or the Linux systemd user unit that Pi's user-scope install registers (CADENCE_AUTOSTART=0, disable or mask opts out). Default detached or --foreground. Start accepts --config, --agent-dir, --host, --port, --token-file.
 Return/quit detaches clients; only explicit Cancel/Stop requests stop. Unconfirmed/quarantined is not stopped.
 Recovery resolve requires this local native terminal, exact unchanged dead-owner resources and separate process/credential/storage acknowledgments. No --yes, network recovery, killing, repair or cleanup.
 `);
       return;
     }
+    if (command === "autostart") {
+      await autostartMain(argv, hostUrl);
+      return;
+    }
     let recovery;
     if (![
       "start",
@@ -5555,10 +6130,23 @@ Recovery resolve requires this local native terminal, exact unchanged dead-owner
       else
         throw new ContractError("invalid");
     }
+    const landing = effectiveWorkspace(options.workspace, options.stateHome);
+    if (landing.redirected) {
+      if (seen.has("--workspace"))
+        process.stderr.write(`Cadence workspace: ${landing.workspace} (${options.workspace} contains Cadence's private state)
+`);
+      options.workspace = landing.workspace;
+      if (command === "start")
+        mkdirSync4(landing.workspace, { recursive: true });
+    }
     let result;
     if (command === "start")
       result = await startService(options, foreground, hostUrl);
-    else {
+    else if (landing.redirected && !existsSync(landing.workspace)) {
+      if (command !== "status" && command !== "diagnose")
+        throw new ContractError("unavailable");
+      result = { status: "absent" };
+    } else {
       const c = new ServiceCoordination(options.workspace, options.stateHome);
       if (command === "recover" && recovery)
         result = await localRecovery(c, recovery);
@@ -5576,6 +6164,8 @@ Recovery resolve requires this local native terminal, exact unchanged dead-owner
       else
         throw new ContractError("invalid");
     }
+    if (landing.redirected && result && typeof result === "object")
+      result = { ...result, workspace: landing.workspace };
     if (result !== null)
       process.stdout.write(`${JSON.stringify(result)}
 `);