dahrk-node 0.1.8 → 0.1.10

package/dist/main.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
 // src/main.ts
-import { execFileSync as execFileSync7 } from "child_process";
-import { existsSync as existsSync7, realpathSync as realpathSync3 } from "fs";
+import { execFileSync as execFileSync8 } from "child_process";
+import { existsSync as existsSync12, realpathSync as realpathSync4 } from "fs";
 import { randomUUID as randomUUID3 } from "crypto";
 import { homedir as homedir5, platform as osPlatform4 } from "os";
-import { basename, join as join10 } from "path";
+import { basename as basename2, join as join14 } from "path";
 import { pathToFileURL } from "url";
 
 // ../../packages/edge/src/ws-client.ts
@@ -1333,7 +1333,7 @@ var PROVIDER_BY_ENV = {
 import { execFileSync } from "child_process";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync as readFileSync2, rmSync, writeFileSync } from "fs";
 import { homedir, tmpdir } from "os";
-import { dirname, isAbsolute, join as join2 } from "path";
+import { basename, dirname, isAbsolute, join as join2 } from "path";
 var noopLogger = { info: () => {
 }, warn: () => {
 } };
@@ -1349,12 +1349,16 @@ function sanitizeBranchName(name) {
 function resolveWorktreesDir(override) {
   return override ?? process.env.DAHRK_WORKTREES_DIR ?? process.env.SKAKEL_WORKTREES_DIR ?? join2(homedir(), ".dahrk", "worktrees");
 }
+function resolveMirrorsDir(override) {
+  return override ?? process.env.DAHRK_MIRRORS_DIR ?? process.env.SKAKEL_MIRRORS_DIR ?? join2(homedir(), ".dahrk", "mirrors");
+}
 function createGitService(opts = {}) {
   const worktreesDir = resolveWorktreesDir(opts.worktreesDir);
-  const mirrorsDir = opts.mirrorsDir ?? process.env.DAHRK_MIRRORS_DIR ?? process.env.SKAKEL_MIRRORS_DIR ?? join2(homedir(), ".dahrk", "mirrors");
+  const mirrorsDir = resolveMirrorsDir(opts.mirrorsDir);
   const authorName = opts.authorName ?? process.env.DAHRK_GIT_AUTHOR_NAME ?? "Dahrk";
   const authorEmail = opts.authorEmail ?? process.env.DAHRK_GIT_AUTHOR_EMAIL ?? "noreply@dahrk.ai";
-  const log2 = opts.logger ?? noopLogger;
+  const isBusy = opts.isBusy;
+  const log = opts.logger ?? noopLogger;
   const git = (cwd, args, env) => execFileSync("git", args, {
     cwd,
     stdio: ["pipe", "pipe", "pipe"],
@@ -1366,7 +1370,7 @@ function createGitService(opts = {}) {
     encoding: "utf-8",
     ...env ? { env } : {}
   });
-  const gitOk = (cwd, args) => {
+  const gitOk2 = (cwd, args) => {
     try {
       git(cwd, args);
       return true;
@@ -1393,14 +1397,14 @@ function createGitService(opts = {}) {
       writeFileSync(excludePath, `${existing}${sep3}${entry}
 `);
     } catch (e) {
-      log2.warn(`could not set worktree scratch exclude at ${worktreePath}: ${e.message}`);
+      log.warn(`could not set worktree scratch exclude at ${worktreePath}: ${e.message}`);
     }
   };
   const commitPending = (worktreePath, message) => {
     excludeScratchLocally(worktreePath);
     git(worktreePath, ["rm", "-r", "--cached", "--ignore-unmatch", "--quiet", SCRATCH_DIR]);
     git(worktreePath, ["add", "-A", "--", "."]);
-    const dirty = !gitOk(worktreePath, ["diff", "--cached", "--quiet"]);
+    const dirty = !gitOk2(worktreePath, ["diff", "--cached", "--quiet"]);
     if (dirty) {
       git(worktreePath, [
         "-c",
@@ -1426,22 +1430,108 @@ function createGitService(opts = {}) {
   const netEnv = (authEnv) => authEnv ?? { ...process.env, GIT_TERMINAL_PROMPT: "0" };
   const withTokenUser = (gitUrl) => /^https:\/\/[^@/]+@/.test(gitUrl) ? gitUrl : gitUrl.replace(/^https:\/\//, "https://x-access-token@");
   const mirrorPathFor = (repoId) => join2(mirrorsDir, sanitizeBranchName(repoId));
+  const listWorktrees = (mirror) => {
+    let out;
+    try {
+      out = git(mirror, ["worktree", "list", "--porcelain"]);
+    } catch {
+      return [];
+    }
+    const entries = [];
+    let path = "";
+    for (const line of out.split("\n")) {
+      if (line.startsWith("worktree ")) path = line.slice(9).trim();
+      else if (line.startsWith("branch ")) {
+        const branch = line.slice(7).trim().replace(/^refs\/heads\//, "");
+        if (path) entries.push({ path, branch });
+      } else if (line.trim() === "") path = "";
+    }
+    return entries;
+  };
+  const teardownWorktreePath = (mirror, worktreePath) => {
+    try {
+      git(mirror, ["worktree", "remove", "--force", worktreePath]);
+    } catch (e) {
+      log.warn(`git worktree remove failed for ${worktreePath}: ${e.message}`);
+    }
+    rmSync(worktreePath, { recursive: true, force: true });
+    gitOk2(mirror, ["worktree", "prune"]);
+  };
+  const TRACKING_REFSPEC = "+refs/heads/*:refs/remotes/origin/*";
+  const migrateMirrorConfig = (mirror, repoId) => {
+    const isMirror = gitOk2(mirror, ["config", "--get", "remote.origin.mirror"]);
+    const refspecs = (() => {
+      try {
+        return git(mirror, ["config", "--get-all", "remote.origin.fetch"]).split("\n").map((s) => s.trim());
+      } catch {
+        return [];
+      }
+    })();
+    if (!isMirror && refspecs.length === 1 && refspecs[0] === TRACKING_REFSPEC) return;
+    log.info(`mirror ${repoId}: migrating to the tracking-refspec layout (was mirror=${isMirror})`);
+    for (const args of [
+      ["config", "--unset-all", "remote.origin.mirror"],
+      ["config", "--unset-all", "remote.origin.push"]
+    ]) {
+      gitOk2(mirror, args);
+    }
+    git(mirror, ["config", "--replace-all", "remote.origin.fetch", TRACKING_REFSPEC]);
+  };
+  const salvageOrphanedTip = (mirror, branchName, start2) => {
+    try {
+      if (!gitOk2(mirror, ["rev-parse", "--verify", "-q", `refs/heads/${branchName}`])) return;
+      if (gitOk2(mirror, ["merge-base", "--is-ancestor", `refs/heads/${branchName}`, start2])) return;
+      const sha = git(mirror, ["rev-parse", `refs/heads/${branchName}`]).trim();
+      const ref = `refs/dahrk/salvage/${branchName}/${sha.slice(0, 12)}`;
+      git(mirror, ["update-ref", ref, sha]);
+      log.warn(`parked orphaned tip of ${branchName} (${sha.slice(0, 8)}) at ${ref} before reset`);
+    } catch (e) {
+      log.warn(`could not salvage tip of ${branchName}: ${e.message}`);
+    }
+  };
+  const gcShadowHeads = (mirror) => {
+    let heads;
+    try {
+      heads = git(mirror, ["for-each-ref", "--format=%(refname:short)", "refs/heads/"]).split("\n").map((s) => s.trim()).filter(Boolean);
+    } catch {
+      return;
+    }
+    const held = new Set(listWorktrees(mirror).map((w) => w.branch));
+    const ownHead = (() => {
+      try {
+        return git(mirror, ["symbolic-ref", "--quiet", "--short", "HEAD"]).trim();
+      } catch {
+        return "";
+      }
+    })();
+    for (const h of heads) {
+      if (h === ownHead || held.has(h)) continue;
+      if (!gitOk2(mirror, ["rev-parse", "--verify", "-q", `refs/remotes/origin/${h}`])) continue;
+      if (!gitOk2(mirror, ["merge-base", "--is-ancestor", `refs/heads/${h}`, `refs/remotes/origin/${h}`])) continue;
+      gitOk2(mirror, ["branch", "-D", h]);
+    }
+  };
   const ensureMirror = (repoId, gitUrl, authEnv) => {
     const mirror = mirrorPathFor(repoId);
-    if (existsSync(mirror) && gitOk(mirror, ["rev-parse", "--git-dir"])) {
-      log2.info(`refreshing mirror ${repoId}`);
+    if (existsSync(mirror) && gitOk2(mirror, ["rev-parse", "--git-dir"])) {
+      log.info(`refreshing mirror ${repoId}`);
       try {
-        git(mirror, ["remote", "update", "--prune"], netEnv(authEnv));
+        migrateMirrorConfig(mirror, repoId);
+        git(mirror, ["fetch", "--prune", "origin"], netEnv(authEnv));
+        gcShadowHeads(mirror);
         return { mirror, refreshed: true };
       } catch (e) {
-        log2.warn(`mirror remote update failed for ${repoId}: ${e.message}`);
+        log.warn(`mirror fetch failed for ${repoId}: ${e.message}`);
         return { mirror, refreshed: false };
       }
     }
-    mkdirSync(mirrorsDir, { recursive: true });
+    mkdirSync(mirror, { recursive: true });
     const cloneUrl = authEnv ? withTokenUser(gitUrl) : gitUrl;
-    log2.info(`cloning mirror ${repoId} from ${gitUrl}`);
-    gitBare(["clone", "--mirror", cloneUrl, mirror], netEnv(authEnv));
+    log.info(`cloning mirror ${repoId} from ${gitUrl}`);
+    gitBare(["init", "--bare", "--quiet", mirror]);
+    git(mirror, ["remote", "add", "origin", cloneUrl]);
+    git(mirror, ["config", "--replace-all", "remote.origin.fetch", TRACKING_REFSPEC]);
+    git(mirror, ["fetch", "--prune", "origin"], netEnv(authEnv));
     return { mirror, refreshed: true };
   };
   const refFor = (spec, worktreePath) => ({
@@ -1459,28 +1549,42 @@ function createGitService(opts = {}) {
       const branchName = sanitizeBranchName(spec.branch ?? `dahrk/${runId}`);
       const worktreePath = join2(worktreesDir, runId);
       mkdirSync(worktreesDir, { recursive: true });
-      if (existsSync(worktreePath) && gitOk(worktreePath, ["rev-parse", "--git-dir"])) {
-        log2.info(`reusing existing worktree at ${worktreePath}`);
+      if (existsSync(worktreePath) && gitOk2(worktreePath, ["rev-parse", "--git-dir"])) {
+        log.info(`reusing existing worktree at ${worktreePath}`);
         mkdirSync(join2(worktreePath, ".skakel", "scratch"), { recursive: true });
         return refFor(spec, worktreePath);
       }
       const auth = spec.credentialToken ? setupAuth(spec.credentialToken) : void 0;
       try {
         const { mirror, refreshed } = ensureMirror(repoId, gitUrl, auth?.env);
-        if (gitOk(mirror, ["rev-parse", "--verify", branchName])) {
-          git(mirror, ["worktree", "add", "--force", worktreePath, branchName]);
-        } else {
-          if (!refreshed) {
-            log2.info(`mirror refresh failed; fetching base ${baseBranch} before branching ${branchName}`);
-            git(mirror, ["fetch", "origin", `+refs/heads/${baseBranch}:refs/heads/${baseBranch}`], netEnv(auth?.env));
+        gitOk2(mirror, ["worktree", "prune"]);
+        for (const w of listWorktrees(mirror)) {
+          if (w.branch !== branchName || w.path === worktreePath) continue;
+          const holder = basename(w.path);
+          if (isBusy?.(holder)) {
+            throw new Error(`branch ${branchName} is held by in-flight run ${holder} (${w.path})`);
           }
-          log2.info(`creating worktree at ${worktreePath} from ${baseBranch} on ${branchName}`);
-          git(mirror, ["worktree", "add", "-b", branchName, worktreePath, baseBranch]);
+          log.warn(`clearing stale worktree ${w.path} which still claims ${branchName}`);
+          teardownWorktreePath(mirror, w.path);
+        }
+        const remoteBranch = `refs/remotes/origin/${branchName}`;
+        const remoteBase = `refs/remotes/origin/${baseBranch}`;
+        if (!refreshed) {
+          log.info(`mirror refresh failed; fetching base ${baseBranch} before branching ${branchName}`);
+          git(mirror, ["fetch", "origin", `+refs/heads/${baseBranch}:${remoteBase}`], netEnv(auth?.env));
+        }
+        const seed = spec.seedRef && gitOk2(mirror, ["rev-parse", "--verify", "-q", spec.seedRef]) ? spec.seedRef : void 0;
+        const start2 = seed ?? (gitOk2(mirror, ["rev-parse", "--verify", "-q", remoteBranch]) ? remoteBranch : remoteBase);
+        if (!gitOk2(mirror, ["rev-parse", "--verify", "-q", start2])) {
+          throw new Error(`start point '${start2}' does not resolve in mirror ${repoId}`);
         }
+        salvageOrphanedTip(mirror, branchName, start2);
+        log.info(`creating worktree at ${worktreePath} from ${start2} on ${branchName}`);
+        git(mirror, ["worktree", "add", "--force", "-B", branchName, worktreePath, start2]);
       } finally {
         auth?.cleanup();
       }
-      if (!gitOk(worktreePath, ["rev-parse", "--verify", "-q", "HEAD"])) {
+      if (!gitOk2(worktreePath, ["rev-parse", "--verify", "-q", "HEAD"])) {
         throw new Error(`base '${baseBranch}' did not materialise into ${worktreePath} (unborn HEAD)`);
       }
       mkdirSync(join2(worktreePath, ".skakel", "scratch"), { recursive: true });
@@ -1488,14 +1592,14 @@ function createGitService(opts = {}) {
     },
     async commitAndPush(ref, opts2) {
       const { worktreePath } = ref;
-      if (!existsSync(worktreePath) || !gitOk(worktreePath, ["rev-parse", "--git-dir"])) {
+      if (!existsSync(worktreePath) || !gitOk2(worktreePath, ["rev-parse", "--git-dir"])) {
         throw new Error(`worktree missing for push: ${worktreePath}`);
       }
       const branch = sanitizeBranchName(opts2.branch);
       const { headSha: committedSha, dirty } = commitPending(worktreePath, opts2.message);
       let headSha = committedSha;
       let commitsAhead = 0;
-      for (const baseRef of [opts2.base, `origin/${opts2.base}`, `refs/heads/${opts2.base}`]) {
+      for (const baseRef of ["FETCH_HEAD", `origin/${opts2.base}`, opts2.base, `refs/heads/${opts2.base}`]) {
         if (!baseRef) continue;
         try {
           commitsAhead = Number.parseInt(git(worktreePath, ["rev-list", "--count", `${baseRef}..HEAD`]).trim(), 10) || 0;
@@ -1514,15 +1618,15 @@ function createGitService(opts = {}) {
             git(worktreePath, ["fetch", remote, opts2.base], netEnv(auth?.env));
             fetched = true;
           } catch (e) {
-            log2.warn(`base fetch failed for ${opts2.base}; skipping push-time integration: ${e.message}`);
+            log.warn(`base fetch failed for ${opts2.base}; skipping push-time integration: ${e.message}`);
           }
         }
         if (fetched) {
-          if (!gitOk(worktreePath, ["merge-base", "HEAD", "FETCH_HEAD"])) {
+          if (!gitOk2(worktreePath, ["merge-base", "HEAD", "FETCH_HEAD"])) {
             return { headSha, pushed: false, nothingToCommit: !dirty, commitsAhead, integration: "diverged" };
           }
           const delta = git(worktreePath, ["diff", "--name-only", "FETCH_HEAD...HEAD"]).split("\n").map((l) => l.trim()).filter(Boolean);
-          const isScratchPath = (p) => p === SCRATCH_DIR || p.startsWith(`${SCRATCH_DIR}/`) || gitOk(worktreePath, ["check-ignore", "-q", "--no-index", "--", p]);
+          const isScratchPath = (p) => p === SCRATCH_DIR || p.startsWith(`${SCRATCH_DIR}/`) || gitOk2(worktreePath, ["check-ignore", "-q", "--no-index", "--", p]);
           if (!delta.some((p) => !isScratchPath(p))) {
             return { headSha, pushed: false, nothingToCommit: true, commitsAhead, integration: "noop" };
           }
@@ -1539,7 +1643,7 @@ function createGitService(opts = {}) {
             integration = "clean";
             headSha = git(worktreePath, ["rev-parse", "HEAD"]).trim();
           } catch (mergeErr) {
-            const inMerge = gitOk(worktreePath, ["rev-parse", "--verify", "-q", "MERGE_HEAD"]);
+            const inMerge = gitOk2(worktreePath, ["rev-parse", "--verify", "-q", "MERGE_HEAD"]);
             if (inMerge) {
               const conflictFiles = git(worktreePath, ["diff", "--name-only", "--diff-filter=U"]).split("\n").map((l) => l.trim()).filter(Boolean);
               git(worktreePath, ["merge", "--abort"]);
@@ -1561,7 +1665,7 @@ function createGitService(opts = {}) {
     },
     async backupPush(ref, opts2) {
       const { worktreePath } = ref;
-      if (!existsSync(worktreePath) || !gitOk(worktreePath, ["rev-parse", "--git-dir"])) {
+      if (!existsSync(worktreePath) || !gitOk2(worktreePath, ["rev-parse", "--git-dir"])) {
         throw new Error(`worktree missing for backup push: ${worktreePath}`);
       }
       const wipRef = sanitizeBranchName(opts2.branch);
@@ -1618,18 +1722,145 @@ function createGitService(opts = {}) {
       }
     },
     async teardownWorktree(ref) {
-      if (!existsSync(ref.worktreePath)) return;
-      const mirror = mirrorPathFor(ref.repoId);
-      try {
-        git(mirror, ["worktree", "remove", "--force", ref.worktreePath]);
-      } catch (e) {
-        log2.warn(`git worktree remove failed for ${ref.worktreePath}: ${e.message}`);
+      teardownWorktreePath(mirrorPathFor(ref.repoId), ref.worktreePath);
+    }
+  };
+}
+
+// ../../packages/executor-worktree/src/worktree-reaper.ts
+import { execFileSync as execFileSync2 } from "child_process";
+import { existsSync as existsSync2, readdirSync, realpathSync, rmSync as rmSync2, statSync } from "fs";
+import { join as join3 } from "path";
+var MINUTE = 6e4;
+var HOUR = 60 * MINUTE;
+var DEFAULTS = {
+  // Deliberately non-optional defaults. "No policy configured" used to mean "never collect anything",
+  // which is precisely how the disk reached 65 GB. Absent config must mean sane collection, not none.
+  maxRuns: 20,
+  maxIdleMs: 6 * HOUR,
+  activityGraceMs: 30 * MINUTE
+};
+var noop = { info: () => {
+}, warn: () => {
+} };
+var gitOk = (cwd, args) => {
+  try {
+    execFileSync2("git", args, { cwd, stdio: ["pipe", "pipe", "pipe"] });
+    return true;
+  } catch {
+    return false;
+  }
+};
+var gitOut = (cwd, args) => execFileSync2("git", args, { cwd, stdio: ["pipe", "pipe", "pipe"], encoding: "utf-8" });
+var canonical = (p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+};
+function lastUsedMs(worktreePath) {
+  const candidates = [join3(worktreePath, ".skakel", "scratch", "state.json"), worktreePath];
+  let newest = 0;
+  for (const p of candidates) {
+    try {
+      newest = Math.max(newest, statSync(p).mtimeMs);
+    } catch {
+    }
+  }
+  return newest;
+}
+function registeredWorktrees(mirror) {
+  let out;
+  try {
+    out = gitOut(mirror, ["worktree", "list", "--porcelain"]);
+  } catch {
+    return [];
+  }
+  return out.split("\n").filter((l) => l.startsWith("worktree ")).map((l) => canonical(l.slice(9).trim())).filter((p) => p && p !== canonical(mirror));
+}
+function createWorktreeReaper(opts) {
+  const log = opts.logger ?? noop;
+  const mirrors = () => {
+    try {
+      return readdirSync(opts.mirrorsDir).map((d) => join3(opts.mirrorsDir, d)).filter((m) => gitOk(m, ["rev-parse", "--git-dir"]));
+    } catch {
+      return [];
+    }
+  };
+  const ownerOf = (worktreePath, all) => {
+    for (const [mirror, paths] of all) if (paths.includes(worktreePath)) return mirror;
+    return void 0;
+  };
+  return {
+    async reap(policy = {}) {
+      const maxRuns = policy.maxRuns ?? DEFAULTS.maxRuns;
+      const maxIdleMs = policy.maxIdleMs ?? DEFAULTS.maxIdleMs;
+      const graceMs = policy.activityGraceMs ?? DEFAULTS.activityGraceMs;
+      const dryRun = policy.dryRun ?? false;
+      const report = { scanned: 0, reaped: [], skipped: 0, errors: [] };
+      const now = Date.now();
+      const registered = /* @__PURE__ */ new Map();
+      for (const m of mirrors()) {
+        gitOk(m, ["worktree", "prune"]);
+        registered.set(m, registeredWorktrees(m));
       }
-      rmSync(ref.worktreePath, { recursive: true, force: true });
-      try {
-        git(mirror, ["worktree", "prune"]);
-      } catch {
+      const onDisk = (() => {
+        try {
+          return readdirSync(opts.worktreesDir).map((d) => canonical(join3(opts.worktreesDir, d)));
+        } catch {
+          return [];
+        }
+      })();
+      const candidates = [.../* @__PURE__ */ new Set([...onDisk, ...[...registered.values()].flat()])];
+      const entries = [];
+      for (const path of candidates) {
+        report.scanned++;
+        const runId = path.split("/").pop() ?? path;
+        if (opts.isBusy?.(runId)) {
+          report.skipped++;
+          continue;
+        }
+        const idleMs = now - lastUsedMs(path);
+        if (idleMs < graceMs) {
+          report.skipped++;
+          continue;
+        }
+        const broken = !existsSync2(path) || !gitOk(path, ["rev-parse", "--verify", "-q", "HEAD"]);
+        entries.push({ path, runId, idleMs, broken, ...ownerOf(path, registered) ? { mirror: ownerOf(path, registered) } : {} });
+      }
+      entries.sort((a, b) => b.idleMs - a.idleMs);
+      const keep = entries.filter((e) => !e.broken && e.idleMs <= maxIdleMs);
+      const doomed = [];
+      for (const e of entries) {
+        if (e.broken) doomed.push({ ...e, reason: "broken" });
+        else if (e.idleMs > maxIdleMs) doomed.push({ ...e, reason: "idle" });
+      }
+      const survivors = keep.filter((e) => !doomed.some((d) => d.path === e.path));
+      for (const e of survivors.slice(0, Math.max(0, survivors.length - maxRuns))) {
+        doomed.push({ ...e, reason: "over-count" });
       }
+      for (const d of doomed) {
+        if (dryRun) {
+          log.info(`reaper (dry-run): would reap ${d.runId} (${d.reason}, idle ${Math.round(d.idleMs / MINUTE)}m)`);
+          report.reaped.push({ runId: d.runId, path: d.path, reason: d.reason });
+          continue;
+        }
+        try {
+          if (d.mirror) {
+            gitOk(d.mirror, ["worktree", "remove", "--force", d.path]);
+          }
+          rmSync2(d.path, { recursive: true, force: true });
+          if (d.mirror) gitOk(d.mirror, ["worktree", "prune"]);
+          report.reaped.push({ runId: d.runId, path: d.path, reason: d.reason });
+        } catch (e) {
+          report.errors.push(`${d.runId}: ${e.message}`);
+        }
+      }
+      if (report.reaped.length) {
+        log.info(`reaper: reaped ${report.reaped.length} worktree(s), skipped ${report.skipped}`);
+      }
+      return report;
     }
   };
 }
@@ -1637,15 +1868,15 @@ function createGitService(opts = {}) {
 // ../../packages/executor-worktree/src/trace-writer.ts
 import { createHash } from "crypto";
 import { appendFileSync, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 var DEFAULT_SPILL_BYTES = 8192;
 function createTraceWriter(scratchPath, meta, opts = {}) {
   const spillBytes = opts.spillBytes ?? DEFAULT_SPILL_BYTES;
-  const dir = join3(scratchPath, "traces", meta.stageId, `attempt-${meta.attempt}`);
-  mkdirSync2(join3(dir, "blobs"), { recursive: true });
-  mkdirSync2(join3(dir, "raw"), { recursive: true });
-  const tracePath = join3(dir, "trace.jsonl");
-  const metaPath = join3(dir, "meta.json");
+  const dir = join4(scratchPath, "traces", meta.stageId, `attempt-${meta.attempt}`);
+  mkdirSync2(join4(dir, "blobs"), { recursive: true });
+  mkdirSync2(join4(dir, "raw"), { recursive: true });
+  const tracePath = join4(dir, "trace.jsonl");
+  const metaPath = join4(dir, "meta.json");
   let current = { ...meta };
   let nextSeq = 0;
   let rawCount = 0;
@@ -1657,8 +1888,8 @@ function createTraceWriter(scratchPath, meta, opts = {}) {
   const spillValue = (value) => {
     const data = typeof value === "string" ? value : JSON.stringify(value);
     const sha = createHash("sha256").update(data).digest("hex");
-    writeFileSync2(join3(dir, "blobs", sha), data);
-    return join3("blobs", sha);
+    writeFileSync2(join4(dir, "blobs", sha), data);
+    return join4("blobs", sha);
   };
   const spill = (event) => {
     if (event.type === "thought" && event.text !== void 0 && tooBig(event.text)) {
@@ -1688,8 +1919,8 @@ function createTraceWriter(scratchPath, meta, opts = {}) {
       return written;
     },
     writeRaw(record) {
-      const rel = join3("raw", `${rawCount++}.json`);
-      writeFileSync2(join3(dir, rel), JSON.stringify(record, null, 2));
+      const rel = join4("raw", `${rawCount++}.json`);
+      writeFileSync2(join4(dir, rel), JSON.stringify(record, null, 2));
       return rel;
     },
     finalise(patch = {}) {
@@ -1704,13 +1935,13 @@ function createTraceWriter(scratchPath, meta, opts = {}) {
 
 // ../../packages/executor-worktree/src/pack-cache.ts
 import { createHash as createHash2 } from "crypto";
-import { cpSync, existsSync as existsSync2, mkdirSync as mkdirSync3, mkdtempSync as mkdtempSync2, readdirSync, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
-import { dirname as dirname2, join as join4, relative, sep } from "path";
+import { cpSync, existsSync as existsSync3, mkdirSync as mkdirSync3, mkdtempSync as mkdtempSync2, readdirSync as readdirSync2, rmSync as rmSync3, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname2, join as join5, relative, sep } from "path";
 function readManifestFiles(dir) {
   const out = [];
   const walk = (cur) => {
-    for (const entry of readdirSync(cur, { withFileTypes: true })) {
-      const abs = join4(cur, entry.name);
+    for (const entry of readdirSync2(cur, { withFileTypes: true })) {
+      const abs = join5(cur, entry.name);
       if (entry.isDirectory()) walk(abs);
       else out.push(relative(dir, abs).split(sep).join("/"));
     }
@@ -1720,8 +1951,8 @@ function readManifestFiles(dir) {
 }
 
 // ../../packages/executor-worktree/src/overlay.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "fs";
-import { dirname as dirname3, join as join5 } from "path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "fs";
+import { dirname as dirname3, join as join6 } from "path";
 function sameBytes(dest, bytes) {
   try {
     return readFileSync3(dest).equals(bytes);
@@ -1741,10 +1972,10 @@ async function overlayComponents(opts) {
     }
     const { dir } = await cache.materialise(ref);
     for (const relPath of readManifestFiles(dir)) {
-      const src = join5(dir, relPath);
-      const dest = join5(worktreePath, relPath);
+      const src = join6(dir, relPath);
+      const dest = join6(worktreePath, relPath);
       const bytes = readFileSync3(src);
-      if (existsSync3(dest)) {
+      if (existsSync4(dest)) {
         if (sameBytes(dest, bytes)) continue;
         result.skippedRepoLocal.push(relPath);
         continue;
@@ -1773,6 +2004,386 @@ function makeRunner(runtime) {
   return runtime === "codex" ? createCodexRunner() : createClaudeRunner();
 }
 
+// ../../packages/edge/src/health.ts
+import { statfsSync } from "fs";
+var HealthCounters = class {
+  startedAt = Date.now();
+  errors = /* @__PURE__ */ new Map();
+  crashes = 0;
+  /** Connections made this process lifetime. The flapping signal: this climbing while uptime ALSO climbs
+   *  means the socket keeps dropping under a process that is otherwise fine. */
+  connectCount = 0;
+  /** Jobs in flight. A node stuck at 1 for an hour is wedged, and nothing else reveals it. */
+  activeJobs = 0;
+  /** Worktrees on disk. Climbing without bound was the shape of the leak DHK-371 fixed. */
+  worktreeCount = 0;
+  /** Bucket a stage failure. The CLASS only - the message would carry their paths. */
+  recordError(kind) {
+    this.errors.set(kind, (this.errors.get(kind) ?? 0) + 1);
+  }
+  recordCrash() {
+    this.crashes++;
+  }
+  uptimeSec() {
+    return Math.round((Date.now() - this.startedAt) / 1e3);
+  }
+  errorCounts() {
+    return Object.fromEntries(this.errors);
+  }
+  crashCount() {
+    return this.crashes;
+  }
+};
+function diskFreeBytes(path) {
+  try {
+    const st = statfsSync(path);
+    return Number(st.bfree) * Number(st.bsize);
+  } catch {
+    return void 0;
+  }
+}
+function collectHealth(inputs) {
+  const { counters } = inputs;
+  const free = diskFreeBytes(inputs.worktreesDir);
+  const errors = counters.errorCounts();
+  return {
+    uptimeSec: counters.uptimeSec(),
+    clientVersion: inputs.clientVersion,
+    activeJobs: counters.activeJobs,
+    connectCount: counters.connectCount,
+    worktreeCount: counters.worktreeCount,
+    ...free !== void 0 ? { diskFreeBytes: free } : {},
+    runtimes: inputs.runtimes,
+    ...Object.keys(errors).length > 0 ? { errors } : {},
+    ...counters.crashCount() > 0 ? { crashes: counters.crashCount() } : {}
+  };
+}
+
+// ../../packages/edge/src/log-shipper.ts
+import { shouldShip } from "@dahrk/contracts";
+var SHIP_BUFFER_MAX = 500;
+var SHIP_BATCH_MAX = 200;
+var SHIP_FLUSH_MS = 2e3;
+var LogShipper = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+    this.ceiling = opts.ceiling ?? { health: true, logs: "debug" };
+    this.policy = this.clampToCeiling(opts.initial ?? { health: true, logs: "off" });
+  }
+  opts;
+  buffer = [];
+  policy;
+  ceiling;
+  timer;
+  /** Attached once the socket exists. The shipper is constructed FIRST, because it has to be a pino
+   *  stream before the logger is built, which is before the client is started. Until `attach`, records
+   *  simply accumulate in the (bounded) ring. */
+  send;
+  /** Records we threw away because the buffer was full. Reported, never hidden. */
+  dropped = 0;
+  /** Give the shipper its transport. Called by the client once the socket exists. */
+  attach(send) {
+    this.send = send;
+  }
+  /** The hub may only ever ask for LESS than the local ceiling allows. */
+  clampToCeiling(p) {
+    const rank = { off: 0, error: 1, warn: 2, info: 3, debug: 4 };
+    const logs = rank[p.logs] > rank[this.ceiling.logs] ? this.ceiling.logs : p.logs;
+    return { health: p.health && this.ceiling.health, logs };
+  }
+  /** Apply a policy from the hub (`welcome`, or a live `policy` frame). */
+  setPolicy(p) {
+    this.policy = this.clampToCeiling(p);
+    if (this.policy.logs === "off") this.buffer = [];
+  }
+  current() {
+    return this.policy;
+  }
+  /** Offer a record. Cheap and synchronous - this sits on the logging hot path. */
+  offer(record) {
+    if (this.policy.logs === "off") return;
+    if (!shouldShip(record.level, this.policy.logs)) return;
+    this.buffer.push(record);
+    if (this.buffer.length > (this.opts.bufferMax ?? SHIP_BUFFER_MAX)) {
+      this.buffer.shift();
+      this.dropped++;
+    }
+  }
+  /** Send one batch if there is anything to send and the socket will take it. */
+  flush() {
+    if (this.buffer.length === 0 || !this.send) return;
+    const batch = this.buffer.slice(0, SHIP_BATCH_MAX);
+    if (!this.send(batch)) return;
+    this.buffer = this.buffer.slice(batch.length);
+  }
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => this.flush(), this.opts.flushMs ?? SHIP_FLUSH_MS);
+    this.timer.unref?.();
+  }
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = void 0;
+  }
+  /** For the health report and for tests. */
+  pending() {
+    return this.buffer.length;
+  }
+};
+function shipperStream(shipper) {
+  return {
+    write(chunk) {
+      try {
+        const r = JSON.parse(chunk);
+        if (!r.msg) return;
+        shipper.offer({
+          level: r.level,
+          time: r.time,
+          msg: r.msg,
+          ...r.runId ? { runId: r.runId } : {},
+          ...r.stageId ? { stageId: r.stageId } : {},
+          ...r.jobId ? { jobId: r.jobId } : {},
+          ...r.component ? { component: r.component } : {},
+          ...r.err ? { err: r.err } : {}
+        });
+      } catch {
+      }
+    }
+  };
+}
+function ceilingFromEnv(env) {
+  const v = env.DAHRK_TELEMETRY?.toLowerCase();
+  if (v === "off" || v === "0" || v === "false") return { health: false, logs: "off" };
+  if (v === "health") return { health: true, logs: "off" };
+  return { health: true, logs: "debug" };
+}
+
+// ../../packages/edge/src/logger.ts
+import { closeSync, existsSync as existsSync5, mkdirSync as mkdirSync5, openSync, renameSync, rmSync as rmSync4, statSync as statSync2, writeSync } from "fs";
+import { join as join7 } from "path";
+import pino from "pino";
+
+// ../../packages/edge/src/redact.ts
+var SENSITIVE_KEY_PATTERNS = [
+  "token",
+  "secret",
+  "password",
+  "passwd",
+  "apikey",
+  "api_key",
+  "authorization",
+  "auth_header",
+  "cookie",
+  "private_key",
+  "privatekey",
+  "client_secret",
+  "clientsecret",
+  "refresh_token",
+  "access_token",
+  "bearer",
+  "credential",
+  "enroltoken",
+  "enrol_token"
+];
+var REDACTED = "[REDACTED]";
+var MAX_DEPTH = 8;
+var KEY_ALLOWLIST = /* @__PURE__ */ new Set(["credentialmode"]);
+function isSensitiveKey(key) {
+  const lower = key.toLowerCase();
+  if (KEY_ALLOWLIST.has(lower)) return false;
+  return SENSITIVE_KEY_PATTERNS.some((p) => lower.includes(p));
+}
+var INLINE_TOKEN_RE = /\b(github_pat_[A-Za-z0-9_]{20,}|gh[pousr]_[A-Za-z0-9]{20,}|glpat-[A-Za-z0-9_-]{16,}|xox[abprs]-[A-Za-z0-9-]{10,}|lin_(?:api|oauth)_[A-Za-z0-9]{20,}|sk-ant-[A-Za-z0-9_-]{20,}|sk-[A-Za-z0-9]{20,}|AKIA[A-Z0-9]{16})\b/g;
+var URL_CREDENTIAL_RE = /(\b[a-z][a-z0-9+.-]*:\/\/)([^/\s:@]+):([^/\s@]+)@/gi;
+var JWT_RE = /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g;
+function scrubString(s) {
+  return s.replace(URL_CREDENTIAL_RE, `$1$2:${REDACTED}@`).replace(INLINE_TOKEN_RE, REDACTED).replace(JWT_RE, REDACTED).replace(/Bearer\s+[A-Za-z0-9._\-+/=]{16,}/gi, `Bearer ${REDACTED}`).replace(/([?&](?:token|access_token|api_key|key|secret)=)[^&\s"']+/gi, `$1${REDACTED}`);
+}
+function looksLikeWholeToken(s) {
+  if (s.length < 20 || /\s/.test(s)) return false;
+  return /^(gh[pousr]|github_pat)_/i.test(s) || /^xox[abprs]-/i.test(s) || /^glpat-/i.test(s) || /^lin_(api|oauth)_/i.test(s) || /^sk-/i.test(s);
+}
+function scrubValue(value, depth = 0) {
+  if (depth > MAX_DEPTH) return REDACTED;
+  if (value === null || value === void 0) return value;
+  if (typeof value === "string") {
+    return looksLikeWholeToken(value) ? REDACTED : scrubString(value);
+  }
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return value;
+  if (value instanceof Error) {
+    const out = new Error(scrubString(value.message));
+    out.name = value.name;
+    if (value.stack) out.stack = scrubString(value.stack);
+    return out;
+  }
+  if (Array.isArray(value)) return value.map((v) => scrubValue(v, depth + 1));
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = isSensitiveKey(k) ? REDACTED : scrubValue(v, depth + 1);
+    }
+    return out;
+  }
+  return value;
+}
+
+// ../../packages/edge/src/logger.ts
+var LEVELS = ["trace", "debug", "info", "warn", "error", "fatal", "silent"];
+var isLevel = (v) => v !== void 0 && LEVELS.includes(v);
+function levelFromEnv(env) {
+  const v = env.DAHRK_LOG_LEVEL?.toLowerCase();
+  return isLevel(v) ? v : "info";
+}
+function fileLevelFromEnv(env) {
+  const off = env.DAHRK_LOG_FILE?.toLowerCase();
+  if (off === "0" || off === "off" || off === "false") return "off";
+  const v = env.DAHRK_LOG_FILE_LEVEL?.toLowerCase();
+  return isLevel(v) ? v : "debug";
+}
+var RotatingFile = class {
+  constructor(path, maxBytes, maxFiles) {
+    this.path = path;
+    this.maxBytes = maxBytes;
+    this.maxFiles = maxFiles;
+    this.open();
+  }
+  path;
+  maxBytes;
+  maxFiles;
+  fd;
+  size = 0;
+  failed = false;
+  open() {
+    try {
+      this.fd = openSync(this.path, "a");
+      this.size = existsSync5(this.path) ? statSync2(this.path).size : 0;
+    } catch (e) {
+      this.disable(e);
+    }
+  }
+  /** Report once, then go quiet. A logger that spams stderr about being unable to log is worse than one
+   *  that silently degrades. */
+  disable(e) {
+    if (!this.failed) {
+      this.failed = true;
+      process.stderr.write(`dahrk: file logging disabled (${e.message})
+`);
+    }
+    if (this.fd !== void 0) {
+      try {
+        closeSync(this.fd);
+      } catch {
+      }
+    }
+    this.fd = void 0;
+  }
+  /** node.jsonl -> node.jsonl.1, .1 -> .2, ... dropping the oldest. */
+  rotate() {
+    if (this.fd === void 0) return;
+    try {
+      closeSync(this.fd);
+      this.fd = void 0;
+      const oldest = `${this.path}.${this.maxFiles}`;
+      if (existsSync5(oldest)) rmSync4(oldest, { force: true });
+      for (let i = this.maxFiles - 1; i >= 1; i--) {
+        const from = `${this.path}.${i}`;
+        if (existsSync5(from)) renameSync(from, `${this.path}.${i + 1}`);
+      }
+      if (existsSync5(this.path)) renameSync(this.path, `${this.path}.1`);
+      this.open();
+    } catch (e) {
+      this.disable(e);
+    }
+  }
+  write(line) {
+    if (this.failed) return;
+    if (this.fd === void 0) return;
+    try {
+      const buf = Buffer.from(line, "utf8");
+      if (this.size > 0 && this.size + buf.length > this.maxBytes) {
+        this.rotate();
+        if (this.fd === void 0) return;
+      }
+      writeSync(this.fd, buf);
+      this.size += buf.length;
+    } catch (e) {
+      this.disable(e);
+    }
+  }
+};
+var humanSink = {
+  write(chunk) {
+    let msg;
+    try {
+      msg = JSON.parse(chunk).msg ?? "";
+    } catch {
+      msg = chunk.trimEnd();
+    }
+    if (!msg) return;
+    try {
+      process.stdout.write(`${msg}
+`);
+    } catch {
+    }
+  }
+};
+var pipeGuardInstalled = false;
+function guardBrokenPipe() {
+  if (pipeGuardInstalled) return;
+  pipeGuardInstalled = true;
+  const ignoreEpipe = (err) => {
+    if (err.code !== "EPIPE") throw err;
+  };
+  process.stdout.on("error", ignoreEpipe);
+  process.stderr.on("error", ignoreEpipe);
+}
+function lowest(a, b) {
+  const rank = (l) => LEVELS.indexOf(l);
+  return rank(a) <= rank(b) ? a : b;
+}
+function createNodeLogger(opts = {}) {
+  guardBrokenPipe();
+  const level = opts.level ?? "info";
+  const fileLevel = opts.fileLevel ?? "debug";
+  const streams = [];
+  if (level !== "silent") streams.push({ level, stream: humanSink });
+  if (opts.dir && fileLevel !== "silent") {
+    try {
+      mkdirSync5(opts.dir, { recursive: true, mode: 448 });
+      const file = new RotatingFile(join7(opts.dir, "node.jsonl"), opts.maxBytes ?? 10 * 1024 * 1024, opts.maxFiles ?? 5);
+      streams.push({ level: fileLevel, stream: file });
+    } catch (e) {
+      process.stderr.write(`dahrk: file logging disabled (${e.message})
+`);
+    }
+  }
+  if (opts.ship) streams.push({ level: "trace", stream: opts.ship });
+  const base = streams.length === 0 ? "silent" : opts.ship ? "trace" : opts.dir ? lowest(level, fileLevel) : level;
+  return pino(
+    {
+      level: base,
+      base: opts.base ?? {},
+      // ISO time reads better than epoch millis in a support bundle a human is scanning.
+      timestamp: pino.stdTimeFunctions.isoTime,
+      hooks: {
+        logMethod(args, method) {
+          method.apply(this, scrubValue(args));
+        }
+      }
+    },
+    pino.multistream(streams)
+  );
+}
+function createNodeLoggerFromEnv(env, dir, base, ship) {
+  const fileLevel = fileLevelFromEnv(env);
+  return createNodeLogger({
+    level: levelFromEnv(env),
+    ...fileLevel === "off" ? {} : { dir, fileLevel },
+    ...base ? { base } : {},
+    ...ship ? { ship } : {}
+  });
+}
+
 // ../../packages/edge/src/policy.ts
 var ALLOW = { verdict: "allow", policy: "none" };
 function evaluatePolicies(event, rules) {
@@ -1795,15 +2406,15 @@ function denyToolRule(tool3) {
 }
 
 // ../../packages/edge/src/stage-runner.ts
-import { execFileSync as execFileSync3 } from "child_process";
+import { execFileSync as execFileSync4 } from "child_process";
 import { createHash as createHash3 } from "crypto";
-import { mkdirSync as mkdirSync5, readdirSync as readdirSync2, readFileSync as readFileSync4, rmSync as rmSync3, writeFileSync as writeFileSync5 } from "fs";
+import { mkdirSync as mkdirSync6, readdirSync as readdirSync3, readFileSync as readFileSync4, rmSync as rmSync5, writeFileSync as writeFileSync5 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
-import { isAbsolute as isAbsolute2, join as join6, relative as relative2, resolve, sep as sep2 } from "path";
+import { isAbsolute as isAbsolute2, join as join8, relative as relative2, resolve, sep as sep2 } from "path";
 import { attachedDocBasename as attachedDocBasename2 } from "@dahrk/contracts";
 
 // ../../packages/edge/src/builtins.ts
-import { execFileSync as execFileSync2 } from "child_process";
+import { execFileSync as execFileSync3 } from "child_process";
 var WRITE_TOOLS = /* @__PURE__ */ new Set([
   "Write",
   "Edit",
@@ -1845,7 +2456,7 @@ function isDangerousRm(cmd) {
 }
 function currentBranch(worktreePath) {
   try {
-    return execFileSync2("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: worktreePath }).toString().trim();
+    return execFileSync3("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: worktreePath }).toString().trim();
   } catch {
     return "";
   }
@@ -1992,11 +2603,12 @@ async function startMcpGateway(opts) {
 // ../../packages/edge/src/stage-runner.ts
 var nowIso2 = () => (/* @__PURE__ */ new Date()).toISOString();
 var PREVIEW = 500;
+var RESULT = 16e3;
 var putBytes = async (url, body, contentType) => {
   await fetch(url, { method: "PUT", headers: { "content-type": contentType }, body: new Uint8Array(body) });
 };
 function previewOf(event) {
-  const clip = (v) => (typeof v === "string" ? v : JSON.stringify(v) ?? "").slice(0, PREVIEW);
+  const clip = (v, max = PREVIEW) => (typeof v === "string" ? v : JSON.stringify(v) ?? "").slice(0, max);
   switch (event.type) {
     case "response":
       return event.text !== void 0 ? { text: event.text } : {};
@@ -2005,9 +2617,16 @@ function previewOf(event) {
     case "thought":
       return event.text !== void 0 ? { text: clip(event.text) } : {};
     case "action":
-      return { tool: event.tool, ...event.input !== void 0 ? { text: clip(event.input) } : {} };
+      return {
+        tool: event.tool,
+        toolUseId: event.toolUseId,
+        ...event.input !== void 0 ? { text: clip(event.input) } : {}
+      };
     case "observation":
-      return event.output !== void 0 ? { text: clip(event.output) } : {};
+      return {
+        toolUseId: event.toolUseId,
+        ...event.output !== void 0 ? { text: clip(event.output, RESULT) } : {}
+      };
     case "error":
       return { text: clip(event.message) };
     default:
@@ -2020,7 +2639,7 @@ var attemptOf = (jobId) => {
 };
 var digest = (value) => `sha256:${createHash3("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 16)}`;
 function writeScratchState(ref, job, attempt, status) {
-  const statePath = join6(ref.scratchPath, "state.json");
+  const statePath = join8(ref.scratchPath, "state.json");
   let state;
   try {
     state = JSON.parse(readFileSync4(statePath, "utf8"));
@@ -2028,24 +2647,24 @@ function writeScratchState(ref, job, attempt, status) {
     state = { runId: job.runId, tenantId: job.tenantId, stages: {} };
   }
   state.stages[job.stageId] = { currentAttempt: attempt, status };
-  mkdirSync5(ref.scratchPath, { recursive: true });
+  mkdirSync6(ref.scratchPath, { recursive: true });
   writeFileSync5(statePath, JSON.stringify(state, null, 2));
 }
 function writeIssueContext(ref, issueContext) {
   if (issueContext === void 0) return;
   try {
-    mkdirSync5(ref.scratchPath, { recursive: true });
-    writeFileSync5(join6(ref.scratchPath, "issue.md"), issueContext);
+    mkdirSync6(ref.scratchPath, { recursive: true });
+    writeFileSync5(join8(ref.scratchPath, "issue.md"), issueContext);
   } catch {
   }
 }
 function writeAttachedDocuments(ref, docs) {
   if (!docs || docs.length === 0) return;
   try {
-    const dir = join6(ref.scratchPath, "docs");
-    mkdirSync5(dir, { recursive: true });
+    const dir = join8(ref.scratchPath, "docs");
+    mkdirSync6(dir, { recursive: true });
     for (const doc of docs) {
-      writeFileSync5(join6(dir, `${attachedDocBasename2(doc)}.md`), doc.content);
+      writeFileSync5(join8(dir, `${attachedDocBasename2(doc)}.md`), doc.content);
     }
   } catch {
   }
@@ -2063,8 +2682,8 @@ ${lines.join("\n")}
 function writeGuidance(ref, guidance) {
   if (!guidance || guidance.length === 0) return;
   try {
-    mkdirSync5(ref.scratchPath, { recursive: true });
-    writeFileSync5(join6(ref.scratchPath, "guidance.md"), renderGuidanceMarkdown(guidance));
+    mkdirSync6(ref.scratchPath, { recursive: true });
+    writeFileSync5(join8(ref.scratchPath, "guidance.md"), renderGuidanceMarkdown(guidance));
   } catch {
   }
 }
@@ -2098,13 +2717,13 @@ function readEmittedArtifact(ref, relPath) {
 }
 function scanScratchOutput(ref, preferRel) {
   try {
-    const names = readdirSync2(join6(ref.worktreePath, SCRATCH_OUTPUT_DIR)).filter(
+    const names = readdirSync3(join8(ref.worktreePath, SCRATCH_OUTPUT_DIR)).filter(
       (n) => n.toLowerCase().endsWith(".md")
     );
     if (names.length === 0) return void 0;
     const preferBase = preferRel?.split("/").pop();
     const pick = preferBase && names.includes(preferBase) ? preferBase : names[0];
-    const raw = readFileSync4(join6(ref.worktreePath, SCRATCH_OUTPUT_DIR, pick), "utf8");
+    const raw = readFileSync4(join8(ref.worktreePath, SCRATCH_OUTPUT_DIR, pick), "utf8");
     if (raw.trim().length === 0) return void 0;
     return { path: `${SCRATCH_OUTPUT_DIR}/${pick}`, content: capContent(raw) };
   } catch {
@@ -2114,7 +2733,7 @@ function scanScratchOutput(ref, preferRel) {
 function scanChangedMarkdown(ref) {
   const git = (args) => {
     try {
-      return execFileSync3("git", ["-C", ref.worktreePath, ...args], { encoding: "utf8" }).split("\n").map((s) => s.trim()).filter(Boolean);
+      return execFileSync4("git", ["-C", ref.worktreePath, ...args], { encoding: "utf8" }).split("\n").map((s) => s.trim()).filter(Boolean);
     } catch {
       return [];
     }
@@ -2124,7 +2743,7 @@ function scanChangedMarkdown(ref) {
   );
   for (const rel of rels) {
     try {
-      const raw = readFileSync4(join6(ref.worktreePath, rel), "utf8");
+      const raw = readFileSync4(join8(ref.worktreePath, rel), "utf8");
       if (raw.trim().length > 0) return { path: rel, content: capContent(raw) };
     } catch {
     }
@@ -2147,22 +2766,34 @@ function resolveStageArtifact(ref, emitArtifact, handedBack) {
 }
 function createStageRunner(deps) {
   const worktrees = /* @__PURE__ */ new Map();
+  const log = deps.logger ?? createNodeLogger({ level: "silent" });
   const active = /* @__PURE__ */ new Map();
   const turnQueues = /* @__PURE__ */ new Map();
   const runToolCalls = /* @__PURE__ */ new Map();
   const lastUsed = /* @__PURE__ */ new Map();
   const inFlight = /* @__PURE__ */ new Map();
+  const isBusy = (runId) => (inFlight.get(runId) ?? 0) > 0;
+  const reaperDryRun = process.env.DAHRK_REAPER_DRY_RUN === "1";
+  const reaper = createWorktreeReaper({
+    worktreesDir: deps.gitService.worktreesDir,
+    mirrorsDir: resolveMirrorsDir(),
+    isBusy,
+    logger: { info: (m) => console.log(`REAPER ${m}`), warn: (m) => console.warn(`REAPER ${m}`) }
+  });
   const scratchOnly = /* @__PURE__ */ new Set();
   const teardownRun = async (runId) => {
     const ref = worktrees.get(runId);
     if (ref) {
       if (scratchOnly.has(runId)) {
         try {
-          rmSync3(ref.worktreePath, { recursive: true, force: true });
-        } catch {
+          rmSync5(ref.worktreePath, { recursive: true, force: true });
+        } catch (e) {
+          log.warn({ err: e, runId, path: ref.worktreePath }, "teardown: could not remove scratch dir");
         }
       } else {
-        await deps.gitService.teardownWorktree(ref).catch(() => void 0);
+        await deps.gitService.teardownWorktree(ref).catch((e) => {
+          log.warn({ err: e, runId, path: ref.worktreePath }, "teardown: could not remove worktree");
+        });
       }
     }
     worktrees.delete(runId);
@@ -2172,6 +2803,11 @@ function createStageRunner(deps) {
   };
   const applyRetention = async (keepRunId) => {
     const policy = deps.retention;
+    await reaper.reap({
+      ...policy?.maxRuns !== void 0 ? { maxRuns: policy.maxRuns } : {},
+      ...policy?.maxAgeMs !== void 0 ? { maxIdleMs: policy.maxAgeMs } : {},
+      ...reaperDryRun ? { dryRun: true } : {}
+    }).catch(() => void 0);
     if (!policy) return;
     const prunable = (id) => id !== keepRunId && (inFlight.get(id) ?? 0) === 0;
     const now = Date.now();
@@ -2191,6 +2827,10 @@ function createStageRunner(deps) {
     }
   };
   return {
+    isBusy,
+    async reapWorktrees() {
+      return reaper.reap(reaperDryRun ? { dryRun: true } : {});
+    },
     async runJob(job) {
       const { stageId, jobId, runId, agentConfig } = job;
       const attempt = attemptOf(jobId);
@@ -2206,299 +2846,307 @@ function createStageRunner(deps) {
         return { jobId, status: "fail", summary: `edge does not serve repo "${job.workspaceRef.repoId}"` };
       }
       inFlight.set(runId, (inFlight.get(runId) ?? 0) + 1);
-      lastUsed.set(runId, Date.now());
-      let ref = worktrees.get(runId);
-      if (!ref) {
-        if (job.workspaceRef) {
-          ref = await deps.gitService.createWorktree({
-            repoId: job.workspaceRef.repoId,
-            gitUrl: job.workspaceRef.gitUrl,
-            baseBranch: job.workspaceRef.baseBranch,
-            runId,
-            repo: job.workspaceRef.repo,
-            // Stable per-issue branch (continuation); absent = legacy dahrk/<runId>.
-            ...job.workspaceRef.branch ? { branch: job.workspaceRef.branch } : {},
-            // Brokered git credential for this job; absent on ambient nodes (host creds used).
-            ...job.workspaceRef.credentialToken ? { credentialToken: job.workspaceRef.credentialToken } : {}
-          });
-        } else {
-          const base = deps.scratchRoot ?? join6(tmpdir2(), "dahrk", "scratch");
-          const worktreePath = join6(base, runId);
-          const scratchPath = join6(worktreePath, ".skakel", "scratch");
-          mkdirSync5(scratchPath, { recursive: true });
-          ref = { repoId: "", gitUrl: "", repo: "", baseBranch: "", worktreePath, scratchPath };
-          scratchOnly.add(runId);
+      try {
+        lastUsed.set(runId, Date.now());
+        let ref = worktrees.get(runId);
+        if (!ref) {
+          if (job.workspaceRef) {
+            ref = await deps.gitService.createWorktree({
+              repoId: job.workspaceRef.repoId,
+              gitUrl: job.workspaceRef.gitUrl,
+              baseBranch: job.workspaceRef.baseBranch,
+              runId,
+              repo: job.workspaceRef.repo,
+              // Stable per-issue branch (continuation); absent = legacy dahrk/<runId>.
+              ...job.workspaceRef.branch ? { branch: job.workspaceRef.branch } : {},
+              // Re-enter from work a prior backup push preserved, rather than starting over from the base
+              // (DHK-264). Carried on the contract but never plumbed through to the git service until now.
+              ...job.workspaceRef.seedRef ? { seedRef: job.workspaceRef.seedRef } : {},
+              // Brokered git credential for this job; absent on ambient nodes (host creds used).
+              ...job.workspaceRef.credentialToken ? { credentialToken: job.workspaceRef.credentialToken } : {}
+            });
+          } else {
+            const base = deps.scratchRoot ?? join8(tmpdir2(), "dahrk", "scratch");
+            const worktreePath = join8(base, runId);
+            const scratchPath = join8(worktreePath, ".skakel", "scratch");
+            mkdirSync6(scratchPath, { recursive: true });
+            ref = { repoId: "", gitUrl: "", repo: "", baseBranch: "", worktreePath, scratchPath };
+            scratchOnly.add(runId);
+          }
+          worktrees.set(runId, ref);
         }
-        worktrees.set(runId, ref);
-      }
-      writeScratchState(ref, job, attempt, "in-flight");
-      writeIssueContext(ref, job.issueContext);
-      writeGuidance(ref, job.guidance);
-      writeAttachedDocuments(ref, job.attachedDocuments);
-      if (job.agentConfig.emitArtifact) {
-        const artifactDir = resolveWorktreeRelativePath(ref, job.agentConfig.emitArtifact);
-        const slash = job.agentConfig.emitArtifact.lastIndexOf("/");
-        if (artifactDir && slash > 0) {
+        writeScratchState(ref, job, attempt, "in-flight");
+        writeIssueContext(ref, job.issueContext);
+        writeGuidance(ref, job.guidance);
+        writeAttachedDocuments(ref, job.attachedDocuments);
+        if (job.agentConfig.emitArtifact) {
+          const artifactDir = resolveWorktreeRelativePath(ref, job.agentConfig.emitArtifact);
+          const slash = job.agentConfig.emitArtifact.lastIndexOf("/");
+          if (artifactDir && slash > 0) {
+            try {
+              mkdirSync6(join8(ref.worktreePath, job.agentConfig.emitArtifact.slice(0, slash)), { recursive: true });
+            } catch {
+            }
+          }
+        }
+        let gateway;
+        const meta = {
+          tenantId: job.tenantId,
+          runId,
+          stageId,
+          jobId,
+          attempt,
+          runtime: agentConfig.runtime,
+          model: agentConfig.model,
+          sessionId: job.sessionId,
+          configDigest: digest(agentConfig),
+          startedAt: nowIso2()
+        };
+        const writer = createTraceWriter(ref.scratchPath, meta);
+        const streamEvent = (e) => deps.trace?.event({ runId, stageId, attempt, tenantId: job.tenantId, event: e });
+        streamEvent(
+          writer.append({ seq: 0, ts: nowIso2(), type: "state", runtime: agentConfig.runtime, event: "attempt-start" })
+        );
+        const shipFinalTrace = async (finalMeta) => {
+          const sink = deps.trace;
+          if (!sink) return;
+          const base = { tenantId: job.tenantId, runId, stageId, attempt };
           try {
-            mkdirSync5(join6(ref.worktreePath, job.agentConfig.emitArtifact.slice(0, slash)), { recursive: true });
+            for (const name of readdirSync3(join8(writer.dir, "blobs"))) {
+              const bytes = readFileSync4(join8(writer.dir, "blobs", name));
+              const { url } = await sink.requestBlobUrl({
+                ...base,
+                sha256: name,
+                size: bytes.length,
+                contentType: "application/octet-stream",
+                slot: "blob"
+              });
+              if (url) await putBytes(url, bytes, "application/octet-stream");
+            }
           } catch {
           }
-        }
-      }
-      let gateway;
-      const meta = {
-        tenantId: job.tenantId,
-        runId,
-        stageId,
-        jobId,
-        attempt,
-        runtime: agentConfig.runtime,
-        model: agentConfig.model,
-        sessionId: job.sessionId,
-        configDigest: digest(agentConfig),
-        startedAt: nowIso2()
-      };
-      const writer = createTraceWriter(ref.scratchPath, meta);
-      const streamEvent = (e) => deps.trace?.event({ runId, stageId, attempt, tenantId: job.tenantId, event: e });
-      streamEvent(
-        writer.append({ seq: 0, ts: nowIso2(), type: "state", runtime: agentConfig.runtime, event: "attempt-start" })
-      );
-      const shipFinalTrace = async (finalMeta) => {
-        const sink = deps.trace;
-        if (!sink) return;
-        const base = { tenantId: job.tenantId, runId, stageId, attempt };
-        try {
-          for (const name of readdirSync2(join6(writer.dir, "blobs"))) {
-            const bytes = readFileSync4(join6(writer.dir, "blobs", name));
-            const { url } = await sink.requestBlobUrl({
+          let archiveKey;
+          try {
+            const bytes = readFileSync4(join8(writer.dir, "trace.jsonl"));
+            const sha = createHash3("sha256").update(bytes).digest("hex");
+            const { key, url } = await sink.requestBlobUrl({
               ...base,
-              sha256: name,
+              sha256: sha,
               size: bytes.length,
-              contentType: "application/octet-stream",
-              slot: "blob"
+              contentType: "application/x-ndjson",
+              slot: "archive"
             });
-            if (url) await putBytes(url, bytes, "application/octet-stream");
+            if (url) await putBytes(url, bytes, "application/x-ndjson");
+            archiveKey = key;
+          } catch {
           }
-        } catch {
-        }
-        let archiveKey;
-        try {
-          const bytes = readFileSync4(join6(writer.dir, "trace.jsonl"));
-          const sha = createHash3("sha256").update(bytes).digest("hex");
-          const { key, url } = await sink.requestBlobUrl({
-            ...base,
-            sha256: sha,
-            size: bytes.length,
-            contentType: "application/x-ndjson",
-            slot: "archive"
-          });
-          if (url) await putBytes(url, bytes, "application/x-ndjson");
-          archiveKey = key;
-        } catch {
-        }
-        sink.finalised({ ...base, meta: finalMeta, eventCount: writer.count(), ...archiveKey ? { archiveKey } : {} });
-      };
-      const finish = async (status2, summary2, sessionId, costUsd, handedBackDoc) => {
-        active.delete(jobId);
-        turnQueues.delete(jobId);
-        await gateway?.stop().catch(() => void 0);
-        gateway = void 0;
-        streamEvent(
-          writer.append({ seq: 0, ts: nowIso2(), type: "state", runtime: agentConfig.runtime, event: "stage-exit", status: status2 })
-        );
-        const endedAt = nowIso2();
-        writer.finalise({ status: status2, endedAt, ...sessionId ? { sessionId } : {} });
-        writeScratchState(ref, job, attempt, status2);
-        const finalMeta = {
-          ...meta,
-          status: status2,
-          endedAt,
-          ...sessionId ? { sessionId } : {},
-          ...costUsd !== void 0 ? { costUsd } : {}
+          sink.finalised({ ...base, meta: finalMeta, eventCount: writer.count(), ...archiveKey ? { archiveKey } : {} });
         };
-        await shipFinalTrace(finalMeta).catch(() => void 0);
-        lastUsed.set(runId, Date.now());
-        inFlight.set(runId, Math.max(0, (inFlight.get(runId) ?? 1) - 1));
-        await applyRetention(runId).catch(() => void 0);
-        const wantsArtifact = agentConfig.emitArtifact !== void 0 || handedBackDoc !== void 0;
-        const resolved = status2 === "ok" && wantsArtifact ? resolveStageArtifact(ref, agentConfig.emitArtifact, handedBackDoc) : void 0;
-        if (status2 === "ok" && wantsArtifact) {
-          const detail = resolved ? `source=${resolved.source} path=${resolved.artifact.path} bytes=${resolved.artifact.content.length}` : "no document resolved (declared path, tool handoff, and scratch/changed-file scans all empty)";
+        const finish = async (status2, summary2, sessionId, costUsd, handedBackDoc) => {
+          active.delete(jobId);
+          turnQueues.delete(jobId);
+          await gateway?.stop().catch((e) => log.warn({ err: e, jobId }, "mcp gateway: stop failed"));
+          gateway = void 0;
           streamEvent(
-            writer.append({ seq: 0, ts: nowIso2(), type: "state", runtime: agentConfig.runtime, event: "artifact", detail })
+            writer.append({ seq: 0, ts: nowIso2(), type: "state", runtime: agentConfig.runtime, event: "stage-exit", status: status2 })
           );
-        }
-        return {
-          jobId,
-          status: status2,
-          summary: summary2,
-          ...sessionId ? { sessionId } : {},
-          ...costUsd !== void 0 ? { costUsd } : {},
-          ...resolved ? { artifact: resolved.artifact } : {}
-        };
-      };
-      if (deps.packCache && job.provision && job.provision.length > 0) {
-        try {
-          const overlay = await overlayComponents({
-            worktreePath: ref.worktreePath,
-            runtime: agentConfig.runtime,
-            components: job.provision,
-            cache: deps.packCache
-          });
-          const detail = `provision: ${overlay.written.length} written, ${overlay.skippedRepoLocal.length} repo-local, ${overlay.warnings.length} warning(s)`;
-          streamEvent(
-            writer.append({ seq: 0, ts: nowIso2(), type: "state", runtime: agentConfig.runtime, event: "provision", detail })
+          const endedAt = nowIso2();
+          writer.finalise({ status: status2, endedAt, ...sessionId ? { sessionId } : {} });
+          writeScratchState(ref, job, attempt, status2);
+          const finalMeta = {
+            ...meta,
+            status: status2,
+            endedAt,
+            ...sessionId ? { sessionId } : {},
+            ...costUsd !== void 0 ? { costUsd } : {}
+          };
+          await shipFinalTrace(finalMeta).catch(
+            (e) => log.error({ err: e, runId, stageId: job.stageId, jobId, attempt }, "trace: failed to ship the final trace to the hub")
           );
-          const noteText = overlay.warnings.length > 0 ? `${detail}; ${overlay.warnings.join("; ")}` : detail;
-          deps.sendProgress({ jobId, kind: "observation", ts: nowIso2(), text: noteText });
-        } catch (e) {
-          const msg = `component provisioning failed: ${e.message}`;
-          writer.append({ seq: 0, ts: nowIso2(), type: "error", runtime: agentConfig.runtime, kind: "provision-failed", message: msg });
-          deps.sendProgress({ jobId, kind: "error", ts: nowIso2(), text: msg });
-          return finish("fail", `${stageId}: ${msg}`, job.sessionId);
-        }
-      }
-      let counter = runToolCalls.get(runId);
-      if (!counter) {
-        counter = { count: 0 };
-        runToolCalls.set(runId, counter);
-      }
-      const jobRules = buildRules(job.policies ?? [], {
-        worktreePath: ref.worktreePath,
-        repoName: job.workspaceRef?.repo ?? "",
-        runToolCalls: counter
-      });
-      const rules = [...jobRules, ...deps.rules];
-      const entry = evaluatePolicies({ kind: "stage-entry", stageId }, rules);
-      if (entry.verdict === "deny") {
-        writer.append({ seq: 0, ts: nowIso2(), type: "state", runtime: agentConfig.runtime, event: "policy-deny", detail: entry.reason });
-        return finish("fail", `${stageId}: denied at stage entry (${entry.policy})`, job.sessionId);
-      }
-      let denied = false;
-      const authorisedActions = [];
-      const runtime = agentConfig.runtime;
-      const actionKey = (tool3, input) => {
-        try {
-          return `${tool3}\0${JSON.stringify(input)}`;
-        } catch {
-          return `${tool3}\0`;
+          lastUsed.set(runId, Date.now());
+          await applyRetention(runId).catch((e) => log.warn({ err: e, runId }, "retention: pass failed"));
+          const wantsArtifact = agentConfig.emitArtifact !== void 0 || handedBackDoc !== void 0;
+          const resolved = status2 === "ok" && wantsArtifact ? resolveStageArtifact(ref, agentConfig.emitArtifact, handedBackDoc) : void 0;
+          if (status2 === "ok" && wantsArtifact) {
+            const detail = resolved ? `source=${resolved.source} path=${resolved.artifact.path} bytes=${resolved.artifact.content.length}` : "no document resolved (declared path, tool handoff, and scratch/changed-file scans all empty)";
+            streamEvent(
+              writer.append({ seq: 0, ts: nowIso2(), type: "state", runtime: agentConfig.runtime, event: "artifact", detail })
+            );
+          }
+          return {
+            jobId,
+            status: status2,
+            summary: summary2,
+            ...sessionId ? { sessionId } : {},
+            ...costUsd !== void 0 ? { costUsd } : {},
+            ...resolved ? { artifact: resolved.artifact } : {}
+          };
+        };
+        if (deps.packCache && job.provision && job.provision.length > 0) {
+          try {
+            const overlay = await overlayComponents({
+              worktreePath: ref.worktreePath,
+              runtime: agentConfig.runtime,
+              components: job.provision,
+              cache: deps.packCache
+            });
+            const detail = `provision: ${overlay.written.length} written, ${overlay.skippedRepoLocal.length} repo-local, ${overlay.warnings.length} warning(s)`;
+            streamEvent(
+              writer.append({ seq: 0, ts: nowIso2(), type: "state", runtime: agentConfig.runtime, event: "provision", detail })
+            );
+            const noteText = overlay.warnings.length > 0 ? `${detail}; ${overlay.warnings.join("; ")}` : detail;
+            deps.sendProgress({ jobId, kind: "observation", ts: nowIso2(), text: noteText });
+          } catch (e) {
+            const msg = `component provisioning failed: ${e.message}`;
+            writer.append({ seq: 0, ts: nowIso2(), type: "error", runtime: agentConfig.runtime, kind: "provision-failed", message: msg });
+            deps.sendProgress({ jobId, kind: "error", ts: nowIso2(), text: msg });
+            return finish("fail", `${stageId}: ${msg}`, job.sessionId);
+          }
         }
-      };
-      const policyReason = (verdict) => verdict.reason ?? `tool action denied by ${verdict.policy}`;
-      const recordDeny = (verdict, toolUseId) => {
-        denied = true;
-        const reason = policyReason(verdict);
-        if (toolUseId) {
-          streamEvent(writer.append({ seq: 0, ts: nowIso2(), type: "observation", runtime, toolUseId, isError: true, output: { error: reason } }));
+        let counter = runToolCalls.get(runId);
+        if (!counter) {
+          counter = { count: 0 };
+          runToolCalls.set(runId, counter);
         }
-        streamEvent(writer.append({ seq: 0, ts: nowIso2(), type: "state", runtime, event: "policy-deny", detail: reason }));
-        deps.sendProgress({ jobId, kind: "error", ts: nowIso2(), text: reason });
-      };
-      const authorizeToolUse = (tool3, input) => {
-        const verdict = evaluatePolicies({ kind: "action", stageId, tool: tool3, input }, rules);
-        if (verdict.verdict === "deny") {
-          recordDeny(verdict);
-        } else {
-          authorisedActions.push(actionKey(tool3, input));
+        const jobRules = buildRules(job.policies ?? [], {
+          worktreePath: ref.worktreePath,
+          repoName: job.workspaceRef?.repo ?? "",
+          runToolCalls: counter
+        });
+        const rules = [...jobRules, ...deps.rules];
+        const entry = evaluatePolicies({ kind: "stage-entry", stageId }, rules);
+        if (entry.verdict === "deny") {
+          writer.append({ seq: 0, ts: nowIso2(), type: "state", runtime: agentConfig.runtime, event: "policy-deny", detail: entry.reason });
+          return finish("fail", `${stageId}: denied at stage entry (${entry.policy})`, job.sessionId);
         }
-        return verdict;
-      };
-      const onTrace = (event) => {
-        if (event.type === "action") {
-          const key = actionKey(event.tool, event.input);
-          const authorised = authorisedActions.indexOf(key);
-          if (authorised >= 0) {
-            authorisedActions.splice(authorised, 1);
+        let denied = false;
+        const authorisedActions = [];
+        const runtime = agentConfig.runtime;
+        const actionKey = (tool3, input) => {
+          try {
+            return `${tool3}\0${JSON.stringify(input)}`;
+          } catch {
+            return `${tool3}\0`;
+          }
+        };
+        const policyReason = (verdict) => verdict.reason ?? `tool action denied by ${verdict.policy}`;
+        const recordDeny = (verdict, toolUseId) => {
+          denied = true;
+          const reason = policyReason(verdict);
+          if (toolUseId) {
+            streamEvent(writer.append({ seq: 0, ts: nowIso2(), type: "observation", runtime, toolUseId, isError: true, output: { error: reason } }));
+          }
+          streamEvent(writer.append({ seq: 0, ts: nowIso2(), type: "state", runtime, event: "policy-deny", detail: reason }));
+          deps.sendProgress({ jobId, kind: "error", ts: nowIso2(), text: reason });
+        };
+        const authorizeToolUse = (tool3, input) => {
+          const verdict = evaluatePolicies({ kind: "action", stageId, tool: tool3, input }, rules);
+          if (verdict.verdict === "deny") {
+            recordDeny(verdict);
           } else {
-            const verdict = evaluatePolicies(
-              { kind: "action", stageId, tool: event.tool, input: event.input },
-              rules
-            );
-            if (verdict.verdict === "deny") {
-              streamEvent(writer.append(event));
-              recordDeny(verdict, event.toolUseId);
-              return;
+            authorisedActions.push(actionKey(tool3, input));
+          }
+          return verdict;
+        };
+        const onTrace = (event) => {
+          if (event.type === "action") {
+            const key = actionKey(event.tool, event.input);
+            const authorised = authorisedActions.indexOf(key);
+            if (authorised >= 0) {
+              authorisedActions.splice(authorised, 1);
+            } else {
+              const verdict = evaluatePolicies(
+                { kind: "action", stageId, tool: event.tool, input: event.input },
+                rules
+              );
+              if (verdict.verdict === "deny") {
+                streamEvent(writer.append(event));
+                recordDeny(verdict, event.toolUseId);
+                return;
+              }
             }
           }
+          streamEvent(writer.append(event));
+          if (event.type !== "state") deps.sendProgress({ jobId, kind: event.type, ts: event.ts, ...previewOf(event) });
+        };
+        const mcpServers = agentConfig.mcpServers;
+        if (mcpServers && mcpServers.length > 0 && runtime === "claude-code") {
+          gateway = await startMcpGateway({ servers: mcpServers, creds: job.brokeredCreds ?? {} });
         }
-        streamEvent(writer.append(event));
-        if (event.type !== "state") deps.sendProgress({ jobId, kind: event.type, ts: event.ts, ...previewOf(event) });
-      };
-      const mcpServers = agentConfig.mcpServers;
-      if (mcpServers && mcpServers.length > 0 && runtime === "claude-code") {
-        gateway = await startMcpGateway({ servers: mcpServers, creds: job.brokeredCreds ?? {} });
-      }
-      const runner = deps.makeRunner(runtime);
-      active.set(jobId, runner);
-      const ctx = {
-        config: agentConfig,
-        workspace: ref,
-        sessionId: job.sessionId,
-        ...job.issueContext !== void 0 ? { issueContext: job.issueContext } : {},
-        ...job.guidance !== void 0 ? { guidance: job.guidance } : {},
-        ...job.gateFeedback !== void 0 ? { gateFeedback: job.gateFeedback } : {},
-        ...job.attachedDocuments !== void 0 ? { attachedDocuments: job.attachedDocuments } : {},
-        ...gateway ? { mcpProxyBaseUrl: gateway.baseUrl } : {},
-        // brokered inference env for a managed node (no operator login). The runtime adapter
-        // (Pi) / container executor apply it as the inference process env, so the raw key is
-        // never surfaced to the agent's own tool calls. Absent on ambient nodes; inert for the Claude/
-        // Codex adapters, which use ambient inference.
-        ...job.runtimeEnv ? { runtimeEnv: job.runtimeEnv } : {},
-        // The adapter persists each runtime-native record under the attempt's raw/ sidecar
-        // and stamps the rawRef onto the emitted event.
-        writeRaw: writer.writeRaw,
-        authorizeToolUse,
-        // Wire the interactive AskUserQuestion elicitation seam (DHK-344): the adapter calls this when
-        // the agent asks a structured question, and the edge relays it to the hub as an `elicit` frame.
-        ...deps.sendElicit ? {
-          emitElicit: (question) => deps.sendElicit({
-            jobId,
-            prompt: question.prompt,
-            options: question.options,
-            ...question.multiSelect ? { multiSelect: true } : {}
-          })
-        } : {}
-      };
-      const interactive = agentConfig.interaction === "interactive";
-      let result;
-      let timedOut = false;
-      const killMs = Math.max(0, Math.floor((job.timeout ?? 0) * 1e3));
-      const killTimer = killMs > 0 ? setTimeout(() => {
-        timedOut = true;
-        void runner.cancel();
-      }, killMs) : void 0;
-      try {
-        if (interactive) {
-          const mailbox = new ManagedMailbox();
-          turnQueues.set(jobId, mailbox);
-          result = await runner.runInteractive(ctx, mailbox, onTrace);
-        } else {
-          result = await runner.runBatch(ctx, onTrace);
+        const runner = deps.makeRunner(runtime);
+        active.set(jobId, runner);
+        const ctx = {
+          config: agentConfig,
+          workspace: ref,
+          sessionId: job.sessionId,
+          ...job.issueContext !== void 0 ? { issueContext: job.issueContext } : {},
+          ...job.guidance !== void 0 ? { guidance: job.guidance } : {},
+          ...job.gateFeedback !== void 0 ? { gateFeedback: job.gateFeedback } : {},
+          ...job.attachedDocuments !== void 0 ? { attachedDocuments: job.attachedDocuments } : {},
+          ...gateway ? { mcpProxyBaseUrl: gateway.baseUrl } : {},
+          // brokered inference env for a managed node (no operator login). The runtime adapter
+          // (Pi) / container executor apply it as the inference process env, so the raw key is
+          // never surfaced to the agent's own tool calls. Absent on ambient nodes; inert for the Claude/
+          // Codex adapters, which use ambient inference.
+          ...job.runtimeEnv ? { runtimeEnv: job.runtimeEnv } : {},
+          // The adapter persists each runtime-native record under the attempt's raw/ sidecar
+          // and stamps the rawRef onto the emitted event.
+          writeRaw: writer.writeRaw,
+          authorizeToolUse,
+          // Wire the interactive AskUserQuestion elicitation seam (DHK-344): the adapter calls this when
+          // the agent asks a structured question, and the edge relays it to the hub as an `elicit` frame.
+          ...deps.sendElicit ? {
+            emitElicit: (question) => deps.sendElicit({
+              jobId,
+              prompt: question.prompt,
+              options: question.options,
+              ...question.multiSelect ? { multiSelect: true } : {}
+            })
+          } : {}
+        };
+        const interactive = agentConfig.interaction === "interactive";
+        let result;
+        let timedOut = false;
+        const killMs = Math.max(0, Math.floor((job.timeout ?? 0) * 1e3));
+        const killTimer = killMs > 0 ? setTimeout(() => {
+          timedOut = true;
+          void runner.cancel();
+        }, killMs) : void 0;
+        try {
+          if (interactive) {
+            const mailbox = new ManagedMailbox();
+            turnQueues.set(jobId, mailbox);
+            result = await runner.runInteractive(ctx, mailbox, onTrace);
+          } else {
+            result = await runner.runBatch(ctx, onTrace);
+          }
+        } finally {
+          if (killTimer) clearTimeout(killTimer);
         }
-      } finally {
-        if (killTimer) clearTimeout(killTimer);
-      }
-      let status = timedOut ? "timeout" : result.status;
-      if (status === "ok" && job.hooks && job.hooks.length > 0) {
-        for (const cmd of job.hooks) {
-          try {
-            execFileSync3("sh", ["-c", cmd], { cwd: ref.worktreePath, stdio: ["pipe", "pipe", "pipe"] });
-          } catch (e) {
-            status = "fail";
-            writer.append({ seq: 0, ts: nowIso2(), type: "error", runtime, kind: "hook-failed", message: `hook "${cmd}" failed: ${e.message}` });
-            break;
+        let status = timedOut ? "timeout" : result.status;
+        if (status === "ok" && job.hooks && job.hooks.length > 0) {
+          for (const cmd of job.hooks) {
+            try {
+              execFileSync4("sh", ["-c", cmd], { cwd: ref.worktreePath, stdio: ["pipe", "pipe", "pipe"] });
+            } catch (e) {
+              status = "fail";
+              writer.append({ seq: 0, ts: nowIso2(), type: "error", runtime, kind: "hook-failed", message: `hook "${cmd}" failed: ${e.message}` });
+              break;
+            }
           }
         }
-      }
-      let summary = result.summary ?? `${stageId}: ${status}`;
-      if (!interactive && status === "ok") {
-        try {
-          summary = await runner.summarise(ctx);
-        } catch {
+        let summary = result.summary ?? `${stageId}: ${status}`;
+        if (!interactive && status === "ok") {
+          try {
+            summary = await runner.summarise(ctx);
+          } catch {
+          }
         }
+        if (denied) summary += "\n\n(note: one or more tool actions were blocked by a deny-only policy guard.)";
+        return finish(status, summary, result.sessionId ?? job.sessionId, result.costUsd, result.artifact);
+      } finally {
+        inFlight.set(runId, Math.max(0, (inFlight.get(runId) ?? 1) - 1));
       }
-      if (denied) summary += "\n\n(note: one or more tool actions were blocked by a deny-only policy guard.)";
-      return finish(status, summary, result.sessionId ?? job.sessionId, result.costUsd, result.artifact);
     },
     async runPush(job) {
       const { runId, jobId } = job;
@@ -2641,34 +3289,71 @@ function createStageRunner(deps) {
 
 // ../../packages/edge/src/ws-client.ts
 var ENROLMENT_REJECTED_EXIT_CODE = 78;
-var log = (line) => void process.stdout.write(`${line}
-`);
+function classifyError(e) {
+  const msg = e instanceof Error ? e.message : String(e);
+  if (/\bgit\b|worktree|clone|fetch|branch|checkout|remote/i.test(msg)) return "git";
+  if (/policy|denied|not permitted|forbidden/i.test(msg)) return "policy";
+  if (/hub|websocket|socket|awakeable/i.test(msg)) return "hub";
+  if (/runtime|claude|codex|\bpi\b|model|sdk|api key/i.test(msg)) return "runtime";
+  return "internal";
+}
 async function startEdgeNode(opts) {
+  const log = opts.logger ?? createNodeLogger({ level: levelFromEnv(process.env) });
   const rules = opts.denyTool ? [denyToolRule(opts.denyTool)] : [];
+  const counters = new HealthCounters();
+  const shipper = opts.shipper;
+  const telemetryCeiling = ceilingFromEnv(process.env);
+  const gitLog = log.child({ component: "git" });
+  const gitLogger = {
+    info: (msg) => gitLog.debug(msg),
+    warn: (msg) => gitLog.warn(msg)
+  };
+  let stageRunnerRef;
   const gitService = createGitService({
     worktreesDir: opts.worktreesDir,
-    mirrorsDir: opts.mirrorsDir
+    mirrorsDir: opts.mirrorsDir,
+    isBusy: (runId) => stageRunnerRef?.isBusy(runId) ?? false,
+    logger: gitLogger
   });
   let ws;
   let heartbeat;
   let reconnectTimer;
   let lastPongAt = 0;
   let shuttingDown = false;
+  let connectCount = 0;
   let onFatal;
   const send = (msg) => {
     if (ws && ws.readyState === WebSocket.OPEN) ws.send(encode(msg));
   };
+  shipper?.attach((records) => {
+    if (!ws || ws.readyState !== WebSocket.OPEN) return false;
+    ws.send(encode({ type: "node-log", records }));
+    return true;
+  });
+  shipper?.start();
   const MISSED_PONGS_BEFORE_DEAD = 3;
   const startHeartbeat = (sock, intervalMs) => {
     if (heartbeat) clearInterval(heartbeat);
     lastPongAt = Date.now();
     heartbeat = setInterval(() => {
-      if (Date.now() - lastPongAt > MISSED_PONGS_BEFORE_DEAD * intervalMs) {
-        log(`EDGE_STALE:${Date.now() - lastPongAt}ms without a pong, terminating socket`);
+      const sincePongMs = Date.now() - lastPongAt;
+      if (sincePongMs > MISSED_PONGS_BEFORE_DEAD * intervalMs) {
+        log.warn({ sincePongMs, intervalMs }, `EDGE_STALE:${sincePongMs}ms without a pong, terminating socket`);
         sock.terminate();
         return;
       }
-      send({ type: "heartbeat" });
+      const health = shipper?.current().health ?? telemetryCeiling.health;
+      send(
+        health ? {
+          type: "heartbeat",
+          health: collectHealth({
+            counters,
+            clientVersion: opts.clientVersion ?? "0.0.0",
+            runtimes: opts.runtimes,
+            worktreesDir: gitService.worktreesDir
+          })
+        } : { type: "heartbeat" }
+      );
       if (sock.readyState === WebSocket.OPEN) sock.ping();
     }, intervalMs);
   };
@@ -2699,6 +3384,7 @@ async function startEdgeNode(opts) {
   const stageDeps = {
     gitService,
     makeRunner,
+    logger: log,
     ...opts.servesRepoIds ? { servesRepoIds: opts.servesRepoIds } : {},
     ...opts.tenantId ? { tenantId: opts.tenantId } : {},
     rules,
@@ -2710,6 +3396,17 @@ async function startEdgeNode(opts) {
     ...opts.retention ? { retention: opts.retention } : {}
   };
   const stageRunner = createStageRunner(stageDeps);
+  stageRunnerRef = stageRunner;
+  void stageRunner.reapWorktrees().then((r) => {
+    counters.worktreeCount = Math.max(r.scanned - r.reaped.length, 0);
+    if (r.reaped.length) {
+      log.info(
+        { reaped: r.reaped, scanned: r.scanned, skipped: r.skipped },
+        `EDGE_REAPED:${r.reaped.length} worktrees (scanned ${r.scanned}, skipped ${r.skipped})`
+      );
+    }
+    for (const e of r.errors) log.warn({ reapError: e }, `EDGE_REAP_ERROR:${e}`);
+  }).catch((e) => log.warn({ err: e }, `EDGE_REAP_ERROR:${e.message}`));
   const nodeId = opts.nodeId ?? randomUUID();
   const running = /* @__PURE__ */ new Set();
   const onMessage = async (raw) => {
@@ -2720,7 +3417,17 @@ async function startEdgeNode(opts) {
       if (opts.heartbeatMs === void 0 && msg.heartbeatMs > 0 && ws) {
         startHeartbeat(ws, msg.heartbeatMs);
       }
-      log(`EDGE_WELCOMED:${msg.name} tenant=${msg.tenantId} credentialMode=${msg.credentialMode}`);
+      if (msg.telemetry && shipper) shipper.setPolicy(msg.telemetry);
+      log.info(
+        {
+          name: msg.name,
+          tenantId: msg.tenantId,
+          credentialMode: msg.credentialMode,
+          heartbeatMs: msg.heartbeatMs,
+          ...shipper ? { telemetry: shipper.current() } : {}
+        },
+        `EDGE_WELCOMED:${msg.name} tenant=${msg.tenantId} credentialMode=${msg.credentialMode}`
+      );
       try {
         opts.onEnrolled?.({
           name: msg.name,
@@ -2728,7 +3435,7 @@ async function startEdgeNode(opts) {
           credentialMode: msg.credentialMode
         });
       } catch (e) {
-        log(`EDGE_ENROL_PERSIST_FAILED ${e.message}`);
+        log.warn({ err: e }, `EDGE_ENROL_PERSIST_FAILED ${e.message}`);
       }
       return;
     }
@@ -2740,8 +3447,13 @@ async function startEdgeNode(opts) {
       }
       return;
     }
+    if (msg.type === "policy") {
+      shipper?.setPolicy(msg.telemetry);
+      log.info({ telemetry: shipper?.current() ?? msg.telemetry }, `EDGE_POLICY:logs=${shipper?.current().logs ?? msg.telemetry.logs}`);
+      return;
+    }
     if (msg.type === "cancel") {
-      log(`JOB_CANCEL:${msg.jobId}`);
+      log.info({ jobId: msg.jobId }, `JOB_CANCEL:${msg.jobId}`);
       stageRunner.cancel(msg.jobId);
       return;
     }
@@ -2749,29 +3461,34 @@ async function startEdgeNode(opts) {
       if (msg.end === "cancel") stageRunner.cancel(msg.jobId);
       else if (msg.end === "complete") stageRunner.endTurns(msg.jobId);
       else if (msg.turn) stageRunner.enqueueTurn(msg.jobId, msg.turn);
-      log(`JOB_TURN:${msg.jobId}${msg.end ? `:${msg.end}` : ""}`);
+      log.info({ jobId: msg.jobId, ...msg.end ? { end: msg.end } : {} }, `JOB_TURN:${msg.jobId}${msg.end ? `:${msg.end}` : ""}`);
       return;
     }
     if (msg.type === "push") {
       const { job: job2 } = msg;
+      const pushLog = log.child({ runId: job2.runId, jobId: job2.jobId, branch: job2.branch });
       if (running.has(job2.jobId)) {
-        log(`PUSH_DUPLICATE:${job2.runId} ${job2.jobId}`);
+        pushLog.warn({}, `PUSH_DUPLICATE:${job2.runId} ${job2.jobId}`);
         return;
       }
       const cachedPush = lastResults.get(job2.jobId);
       if (cachedPush) {
         send(cachedPush);
-        log(`PUSH_REPLAY:${job2.runId} ${job2.jobId}`);
+        pushLog.info({}, `PUSH_REPLAY:${job2.runId} ${job2.jobId}`);
         return;
       }
       running.add(job2.jobId);
-      log(`PUSH_STARTED:${job2.runId} ${job2.branch}`);
+      const pushStartedAt = Date.now();
+      pushLog.info({}, `PUSH_STARTED:${job2.runId} ${job2.branch}`);
       try {
         const result = await stageRunner.runPush(job2);
         const frame = { type: "push-result", awakeableId: job2.awakeableId, result };
         rememberResult(job2.jobId, frame);
         send(frame);
-        log(`PUSH_DONE:${job2.runId} ${result.status}${result.status !== "ok" ? ` - ${result.summary}` : ""}`);
+        pushLog.info(
+          { status: result.status, summary: result.summary, durationMs: Date.now() - pushStartedAt },
+          `PUSH_DONE:${job2.runId} ${result.status}${result.status !== "ok" ? ` - ${result.summary}` : ""}`
+        );
       } catch (e) {
         const frame = {
           type: "push-result",
@@ -2780,7 +3497,7 @@ async function startEdgeNode(opts) {
         };
         rememberResult(job2.jobId, frame);
         send(frame);
-        log(`PUSH_ERROR:${job2.runId} ${e.message}`);
+        pushLog.error({ err: e, durationMs: Date.now() - pushStartedAt }, `PUSH_ERROR:${job2.runId} ${e.message}`);
       } finally {
         running.delete(job2.jobId);
       }
@@ -2788,24 +3505,37 @@ async function startEdgeNode(opts) {
     }
     if (msg.type !== "job") return;
     const { job } = msg;
+    const jobLog = log.child({
+      runId: job.runId,
+      stageId: job.stageId,
+      jobId: job.jobId,
+      ...job.tenantId ? { tenantId: job.tenantId } : {},
+      ...job.agentConfig?.runtime ? { runtime: job.agentConfig.runtime } : {},
+      ...job.agentConfig?.model ? { model: job.agentConfig.model } : {}
+    });
     if (running.has(job.jobId)) {
-      log(`JOB_DUPLICATE:${job.stageId} ${job.jobId}`);
+      jobLog.warn({}, `JOB_DUPLICATE:${job.stageId} ${job.jobId}`);
       return;
     }
     const cachedJob = lastResults.get(job.jobId);
     if (cachedJob) {
       send(cachedJob);
-      log(`JOB_REPLAY:${job.stageId} ${job.jobId}`);
+      jobLog.info({}, `JOB_REPLAY:${job.stageId} ${job.jobId}`);
       return;
     }
     running.add(job.jobId);
-    log(`JOB_STARTED:${job.stageId} ${job.jobId}`);
+    counters.activeJobs = running.size;
+    const startedAt = Date.now();
+    jobLog.info({}, `JOB_STARTED:${job.stageId} ${job.jobId}`);
     try {
       const result = await stageRunner.runJob(job);
       const frame = { type: "result", awakeableId: job.awakeableId, result };
       rememberResult(job.jobId, frame);
       send(frame);
-      log(`JOB_DONE:${job.stageId} ${result.status}`);
+      jobLog.info(
+        { status: result.status, costUsd: result.costUsd, summary: result.summary, durationMs: Date.now() - startedAt },
+        `JOB_DONE:${job.stageId} ${result.status}`
+      );
     } catch (e) {
       const frame = {
         type: "result",
@@ -2814,16 +3544,20 @@ async function startEdgeNode(opts) {
       };
       rememberResult(job.jobId, frame);
       send(frame);
-      log(`JOB_ERROR:${job.stageId} ${e.message}`);
+      counters.recordError(classifyError(e));
+      jobLog.error({ err: e, durationMs: Date.now() - startedAt }, `JOB_ERROR:${job.stageId} ${e.message}`);
     } finally {
       running.delete(job.jobId);
+      counters.activeJobs = running.size;
     }
   };
   const connect = () => {
     const sock = new WebSocket(opts.hubUrl);
     ws = sock;
     sock.on("open", () => {
-      log("EDGE_CONNECTED");
+      connectCount++;
+      counters.connectCount = connectCount;
+      log.info({ hubUrl: opts.hubUrl, nodeId, connectCount }, "EDGE_CONNECTED");
       send({
         type: "hello",
         enrolToken: opts.enrolToken ?? "",
@@ -2847,19 +3581,22 @@ async function startEdgeNode(opts) {
     sock.on("pong", () => {
       lastPongAt = Date.now();
     });
-    sock.on("error", (e) => log(`EDGE_ERROR ${e.message}`));
+    sock.on("error", (e) => log.error({ err: e, hubUrl: opts.hubUrl }, `EDGE_ERROR ${e.message}`));
     sock.on("close", (code, reason) => {
       if (heartbeat) clearInterval(heartbeat);
       heartbeat = void 0;
       if (isEnrolmentRejection(code)) {
         shuttingDown = true;
         const detail = reason.toString() || "enrolment rejected";
-        log(`EDGE_REJECTED:${code} ${detail}`);
+        log.error({ closeCode: code, detail, fatal: true }, `EDGE_REJECTED:${code} ${detail}`);
         process.exitCode = ENROLMENT_REJECTED_EXIT_CODE;
         onFatal?.(new Error(`hub rejected edge enrolment (${code}): ${detail}`));
         return;
       }
-      if (!shuttingDown) reconnectTimer = setTimeout(connect, 500);
+      if (!shuttingDown) {
+        log.warn({ closeCode: code, reason: reason.toString(), connectCount }, `EDGE_DISCONNECTED:${code} reconnecting in 500ms`);
+        reconnectTimer = setTimeout(connect, 500);
+      }
     });
   };
   opts.signal?.addEventListener(
@@ -3019,7 +3756,19 @@ function probeHub(opts) {
 
 // src/cli.ts
 import { parseArgs } from "util";
-var COMMANDS = /* @__PURE__ */ new Set(["start", "run", "service", "doctor", "status", "update"]);
+var DEFAULT_LOG_LINES = 200;
+var COMMANDS = /* @__PURE__ */ new Set([
+  "start",
+  "stop",
+  "restart",
+  "logs",
+  "diagnose",
+  "run",
+  "service",
+  "doctor",
+  "status",
+  "update"
+]);
 var isCommand = (s) => COMMANDS.has(s);
 function parseCli(argv) {
   const [first, ...rest] = argv;
@@ -3040,6 +3789,8 @@ function parseCli(argv) {
   if (command === "run") return parseRun(flagArgs);
   if (command === "service") return parseService(flagArgs);
   if (command === "update") return parseUpdate(flagArgs);
+  if (command === "logs") return parseLogs(flagArgs);
+  if (command === "diagnose") return parseDiagnose(flagArgs);
   let values;
   try {
     ({ values } = parseArgs({
@@ -3049,6 +3800,7 @@ function parseCli(argv) {
         name: { type: "string" },
         "hub-url": { type: "string" },
         ephemeral: { type: "boolean", default: false },
+        foreground: { type: "boolean", default: false },
         help: { type: "boolean", default: false }
       },
       allowPositionals: false
@@ -3057,14 +3809,74 @@ function parseCli(argv) {
     return { kind: "error", message: e.message };
   }
   if (values.help) return { kind: "help", command };
+  const ephemeral = values.ephemeral ?? false;
   const flags = {
     ...values.token ? { token: values.token } : {},
     ...values.name ? { name: values.name } : {},
     ...values["hub-url"] ? { hubUrl: values["hub-url"] } : {},
-    ephemeral: values.ephemeral ?? false
+    ephemeral,
+    // An ephemeral node mints a throwaway id and persists nothing, so there is nothing coherent to hand to
+    // a supervisor that restarts it on boot. It is a foreground node by definition.
+    foreground: (values.foreground ?? false) || ephemeral
   };
+  if (command === "stop") return { kind: "stop" };
   return { kind: command, flags };
 }
+var LOG_LEVELS = ["trace", "debug", "info", "warn", "error", "fatal"];
+function parseLogs(flagArgs) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: flagArgs,
+      options: {
+        follow: { type: "boolean", short: "f", default: false },
+        lines: { type: "string", short: "n" },
+        level: { type: "string" },
+        run: { type: "string" },
+        json: { type: "boolean", default: false },
+        help: { type: "boolean", default: false }
+      },
+      allowPositionals: false
+    }));
+  } catch (e) {
+    return { kind: "error", message: e.message };
+  }
+  if (values.help) return { kind: "help", command: "logs" };
+  const lines = values.lines === void 0 ? DEFAULT_LOG_LINES : Number(values.lines);
+  if (!Number.isInteger(lines) || lines < 0) {
+    return { kind: "error", message: `logs: --lines must be a non-negative whole number (got "${values.lines}")` };
+  }
+  if (values.level !== void 0 && !LOG_LEVELS.includes(values.level)) {
+    return { kind: "error", message: `logs: --level must be one of ${LOG_LEVELS.join(", ")} (got "${values.level}")` };
+  }
+  return {
+    kind: "logs",
+    flags: {
+      lines,
+      follow: values.follow ?? false,
+      ...values.level ? { level: values.level } : {},
+      ...values.run ? { run: values.run } : {},
+      json: values.json ?? false
+    }
+  };
+}
+function parseDiagnose(flagArgs) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: flagArgs,
+      options: {
+        out: { type: "string" },
+        help: { type: "boolean", default: false }
+      },
+      allowPositionals: false
+    }));
+  } catch (e) {
+    return { kind: "error", message: e.message };
+  }
+  if (values.help) return { kind: "help", command: "diagnose" };
+  return { kind: "diagnose", flags: { ...values.out ? { out: values.out } : {} } };
+}
 function parseRun(flagArgs) {
   let values;
   let positionals;
@@ -3157,16 +3969,96 @@ function usage(bin, command) {
     return [
       `Usage: ${bin} start [--token <token>] [options]`,
       "",
-      "Run the edge node: dial the hub over WebSocket and serve Jobs in git worktrees.",
+      "Make this node run, and keep running: install it as an always-on service (launchd / systemd), start",
+      "it, and return. It restarts on failure and comes back after a reboot. Running it again is a no-op if",
+      "the node is already up, so it is safe to repeat.",
       "",
       "A token is needed only to enrol. Once the hub accepts it, it is cached in ~/.dahrk/node.json and",
       "every later `start` re-attaches without one. Pass --token again to re-enrol (rotated token, new pool).",
       "",
+      "Once it is running:",
+      `  ${bin} logs -f      Watch what it is doing.`,
+      `  ${bin} status       Is it enrolled, and is it up?`,
+      `  ${bin} stop         Stop it (it stays stopped until the next \`start\`).`,
+      "",
       "Options:",
       "  --token <token>    Enrolment token (first run only; or set DAHRK_ENROL_TOKEN).",
       "  --hub-url <url>    Hub WebSocket URL (or set DAHRK_HUB_URL).",
       "  --name <name>      Display-name override (else the hub assigns one).",
-      "  --ephemeral        Do not persist (or read) node id and token; mint a throwaway id (CI / one-shot)."
+      "  --foreground       Run the node in THIS terminal and block, instead of as a service. For",
+      "                     containers, pm2, CI, or just watching one work. Ctrl-C stops it. Same thing as",
+      "                     setting DAHRK_FOREGROUND=1, which is easier to set in a Dockerfile or pm2 config.",
+      "  --ephemeral        Do not persist (or read) node id and token; mint a throwaway id (CI / one-shot).",
+      "                     Implies --foreground: a node with no persistent identity has nothing to daemonise.",
+      "",
+      "Only one node may run at a time on a host - they would share this machine's node id and race each",
+      "other for Jobs - so a second `start` refuses rather than dialling the hub twice."
+    ].join("\n");
+  }
+  if (command === "stop") {
+    return [
+      `Usage: ${bin} stop`,
+      "",
+      "Stop the node. It stays stopped across reboots until you run `dahrk start` again - a stop that",
+      "quietly undid itself at the next boot would not be a stop.",
+      "",
+      "The service stays installed, so starting it again is instant. To remove it entirely, use",
+      "`dahrk service uninstall`. To stop a node running in a terminal (--foreground), press Ctrl-C."
+    ].join("\n");
+  }
+  if (command === "restart") {
+    return [
+      `Usage: ${bin} restart [options]`,
+      "",
+      "Stop the node and start it again. Picks up a new client version, a rotated token, or a runtime you",
+      "have just installed (the node detects runtimes at boot, so a fresh `claude` on PATH needs a restart).",
+      "",
+      "Options:",
+      "  --token <token>    Re-enrol with a new token (or set DAHRK_ENROL_TOKEN).",
+      "  --hub-url <url>    Hub WebSocket URL (or set DAHRK_HUB_URL).",
+      "  --name <name>      Display-name override (else the hub assigns one)."
+    ].join("\n");
+  }
+  if (command === "logs") {
+    return [
+      `Usage: ${bin} logs [-f] [-n <lines>] [--level <l>] [--run <id>] [--json]`,
+      "",
+      "Show what the node has been doing: its connect / welcome handshake, the Jobs it has run, and anything",
+      "it has crashed on.",
+      "",
+      "There are two logs, and this reads whichever you ask for. On its own it tails the transcript the",
+      "service captured (~/.dahrk/logs/node.out.log and node.err.log) - the same lines the node printed.",
+      "Pass --level, --run or --json and it reads node.jsonl instead: the node's own structured log, which",
+      "is the one carrying levels, timestamps, correlation ids and full error stacks. It is written at",
+      "debug even when the terminal is not, so the detail for an incident is already there afterwards.",
+      "",
+      "Options:",
+      "  -f, --follow       Keep watching as new lines arrive (Ctrl-C to stop).",
+      "  -n, --lines <n>    Lines of history to show first (default 200).",
+      "  --level <level>    Only this level and above: trace, debug, info, warn, error, fatal.",
+      "  --run <runId>      Only this run. The runId is the hub's - so `logs --run <id>` and the hub's",
+      "                     view of the same run describe the same thing from both ends.",
+      "  --json             Print the raw JSON records (for jq) rather than a rendered line.",
+      "",
+      "A node run with --foreground prints to its terminal, but it still writes node.jsonl - so --run and",
+      "--level work for it too."
+    ].join("\n");
+  }
+  if (command === "diagnose") {
+    return [
+      `Usage: ${bin} diagnose [--out <path>]`,
+      "",
+      "Write a support bundle: everything needed to debug this node, in one file you can read.",
+      "",
+      "It collects this node's id, name, tenant, version and host; the doctor's verdict; the tail of the",
+      "structured log; and every crash record. Secrets are stripped and the enrolment token is not",
+      "included. Your source code, prompts and issue content are not included.",
+      "",
+      "Nothing is uploaded. There is no flag to upload it. The file is written locally so that you can open",
+      "it, read every line, and decide for yourself whether to send it on.",
+      "",
+      "Options:",
+      "  --out <path>       Write the bundle here (default: ./dahrk-diagnose-<timestamp>.json)."
     ].join("\n");
   }
   if (command === "run") {
@@ -3242,19 +4134,139 @@ function usage(bin, command) {
     `Usage: ${bin} <command> [options]`,
     "",
     "Commands:",
-    "  start     Run the edge node (default). Needs a --token to enrol; cached thereafter.",
+    "  start     Run the node, and keep it running (installs the service). --token to enrol, once.",
+    "  stop      Stop the node. It stays stopped until the next `start`.",
+    "  restart   Stop it and start it again.",
+    "  logs      Show what the node is doing (-f to follow, --run <id> to narrow to one run).",
+    "  diagnose  Write a support bundle you can read, and send on if you choose. Uploads nothing.",
+    "  status    Is this node enrolled, and is it up? (local, dials nothing)",
     "  run       Run a workflow locally (engine-backed), e.g. `run preflight`.",
-    "  service   Install/uninstall the node as an always-on service (launchd/systemd).",
-    "  status    Is this node enrolled, and is the service running? (local, dials nothing)",
     "  doctor    Preflight checks: Node, runtimes, hub reachability, token validity.",
+    "  service   Install/uninstall the always-on service by hand (`start` does this for you).",
     "  update    Update the client to the latest release (or print how for your channel).",
     "  version   Print the client version.",
     "  help      Show this help, or `help <command>` for a command's options.",
     "",
-    `Run \`${bin} help <command>\` for command-specific options.`
+    `Run \`${bin} help <command>\` for command-specific options.`,
+    `To run a node in this terminal instead of as a service: \`${bin} start --foreground\`.`
   ].join("\n");
 }
 
+// src/diagnose.ts
+import { existsSync as existsSync6, mkdirSync as mkdirSync7, readdirSync as readdirSync4, readFileSync as readFileSync5, statSync as statSync3, writeFileSync as writeFileSync6 } from "fs";
+import { join as join9 } from "path";
+var BUNDLE_LOG_LINES = 2e3;
+function tailJsonl(raw, n) {
+  const records = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      records.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return n > 0 ? records.slice(-n) : records;
+}
+async function buildBundle(deps) {
+  const warnings = [];
+  let state = {};
+  if (deps.exists(deps.stateFile)) {
+    try {
+      const parsed = JSON.parse(deps.readFile(deps.stateFile));
+      const { enrolToken: _dropped, ...rest } = parsed;
+      state = rest;
+    } catch (e) {
+      warnings.push(`could not read node state (${e.message})`);
+    }
+  } else {
+    warnings.push("no node.json - this node has never enrolled");
+  }
+  let log = [];
+  if (deps.exists(deps.jsonlFile)) {
+    try {
+      log = tailJsonl(deps.readFile(deps.jsonlFile), BUNDLE_LOG_LINES);
+    } catch (e) {
+      warnings.push(`could not read node.jsonl (${e.message})`);
+    }
+  } else {
+    warnings.push("no node.jsonl - the node has not run since structured logging was added");
+  }
+  const crashes = [];
+  if (deps.exists(deps.crashDir)) {
+    for (const name of deps.listDir(deps.crashDir).filter((f) => f.endsWith(".json")).sort()) {
+      try {
+        crashes.push(JSON.parse(deps.readFile(join9(deps.crashDir, name))));
+      } catch (e) {
+        warnings.push(`could not read crash record ${name} (${e.message})`);
+      }
+    }
+  }
+  let doctor;
+  if (deps.doctor) {
+    try {
+      doctor = await deps.doctor();
+    } catch (e) {
+      warnings.push(`doctor failed (${e.message})`);
+    }
+  }
+  const bundle = {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    clientVersion: deps.clientVersion,
+    node: {
+      state,
+      platform: process.platform,
+      arch: process.arch,
+      nodeVersion: process.version
+    },
+    ...doctor ? { doctor } : {},
+    log,
+    crashes,
+    warnings
+  };
+  return scrubValue(bundle);
+}
+async function runDiagnose(deps) {
+  const bundle = await buildBundle(deps);
+  try {
+    deps.writeFile(deps.outFile, `${JSON.stringify(bundle, null, 2)}
+`);
+  } catch (e) {
+    deps.out(`Could not write the bundle: ${e.message}`);
+    return 1;
+  }
+  deps.out(`Wrote a support bundle to ${deps.outFile}`);
+  deps.out("");
+  deps.out(`It contains: this node's id, name and tenant; its version and host; ${bundle.log.length} log`);
+  deps.out(`lines; and ${bundle.crashes.length} crash record(s). Secrets are stripped and the enrolment`);
+  deps.out("token is not in it. Your source code, prompts and issue content are not in it.");
+  deps.out("");
+  deps.out("Nothing has been sent anywhere. Open the file, read it, and send it on only if you are happy to.");
+  if (bundle.warnings.length > 0) {
+    deps.out("");
+    deps.out("Note:");
+    for (const w of bundle.warnings) deps.out(`  - ${w}`);
+  }
+  return 0;
+}
+var defaultDiagnoseDeps = (paths, clientVersion, doctor) => ({
+  ...paths,
+  clientVersion,
+  ...doctor ? { doctor } : {},
+  readFile: (p) => readFileSync5(p, "utf8"),
+  listDir: (p) => readdirSync4(p),
+  exists: (p) => existsSync6(p),
+  writeFile: (p, content) => {
+    const dir = join9(p, "..");
+    if (!existsSync6(dir)) mkdirSync7(dir, { recursive: true });
+    writeFileSync6(p, content, { mode: 384 });
+  },
+  out: (line) => void process.stdout.write(`${line}
+`)
+});
+function defaultBundlePath(cwd, now) {
+  return join9(cwd, `dahrk-diagnose-${now.toISOString().replace(/[:.]/g, "-")}.json`);
+}
+
 // src/doctor.ts
 var MIN_NODE_MAJOR = 22;
 var TAG = { pass: "[PASS]", warn: "[WARN]", fail: "[FAIL]" };
@@ -3386,12 +4398,222 @@ async function runDoctor(inputs, deps = {}) {
   return checks.some((c) => c.status === "fail") ? 1 : 0;
 }
 
+// src/lock.ts
+import { existsSync as existsSync7, mkdirSync as mkdirSync8, readFileSync as readFileSync6, rmSync as rmSync6, writeFileSync as writeFileSync7 } from "fs";
+import { dirname as dirname4 } from "path";
+function parseLock(content) {
+  if (!content) return void 0;
+  const pid = Number(content.trim());
+  return Number.isInteger(pid) && pid > 0 ? pid : void 0;
+}
+function acquireLock(deps) {
+  const held = parseLock(deps.readFile(deps.file));
+  if (held !== void 0 && held !== deps.pid && deps.isAlive(held)) {
+    return { ok: false, heldBy: held };
+  }
+  deps.writeFile(deps.file, `${deps.pid}
+`);
+  return { ok: true, release: () => releaseLock(deps) };
+}
+function releaseLock(deps) {
+  if (parseLock(deps.readFile(deps.file)) !== deps.pid) return;
+  deps.removeFile(deps.file);
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+var defaultLockDeps = (file) => ({
+  file,
+  pid: process.pid,
+  readFile: (path) => {
+    try {
+      return readFileSync6(path, "utf8");
+    } catch {
+      return void 0;
+    }
+  },
+  writeFile: (path, content) => {
+    if (!existsSync7(dirname4(path))) mkdirSync8(dirname4(path), { recursive: true, mode: 448 });
+    writeFileSync7(path, content);
+  },
+  removeFile: (path) => rmSync6(path, { force: true }),
+  isAlive
+});
+
+// src/logs.ts
+import { spawn } from "child_process";
+import { copyFileSync, existsSync as existsSync8, readFileSync as readFileSync7, statSync as statSync4, truncateSync } from "fs";
+var MAX_LOG_BYTES = 10 * 1024 * 1024;
+function logsCommand(inputs) {
+  return [
+    "tail",
+    "-n",
+    String(inputs.lines),
+    ...inputs.follow ? ["-f"] : [],
+    ...inputs.files
+  ];
+}
+var LEVEL_RANK = { trace: 10, debug: 20, info: 30, warn: 40, error: 50, fatal: 60 };
+var levelName = (n) => Object.entries(LEVEL_RANK).find(([, rank]) => rank === n)?.[0] ?? String(n);
+function parseRecords(raw) {
+  const out = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return out;
+}
+function filterRecords(records, q) {
+  const min = q.level ? LEVEL_RANK[q.level] ?? 0 : 0;
+  const matched = records.filter((r) => r.level >= min && (q.run === void 0 || r.runId === q.run));
+  return q.lines > 0 ? matched.slice(-q.lines) : matched;
+}
+function renderRecord(r) {
+  const where = [r.runId, r.stageId].filter(Boolean).join("/");
+  const scope = where ? ` [${where}]` : r.component ? ` [${r.component}]` : "";
+  const head = `${r.time} ${levelName(r.level).toUpperCase().padEnd(5)}${scope} ${r.msg}`;
+  const lines = [head];
+  if (r.err?.stack) lines.push(...r.err.stack.split("\n").map((l) => `    ${l}`));
+  return lines;
+}
+async function runLogs(inputs, deps) {
+  if (inputs.level !== void 0 || inputs.run !== void 0 || inputs.json) {
+    return runStructuredLogs(inputs, deps);
+  }
+  const files = [deps.files.out, deps.files.err].filter((f) => deps.fileExists(f));
+  if (files.length === 0) {
+    deps.out("No logs yet - this node has not run under the service.");
+    deps.out("Start it with `dahrk start`, or check what it thinks it is doing with `dahrk status`.");
+    deps.out("");
+    deps.out("(A node run in a terminal with `--foreground` logs to that terminal, not to a file.)");
+    return 0;
+  }
+  return deps.run(logsCommand({ files, lines: inputs.lines, follow: inputs.follow }));
+}
+async function runStructuredLogs(inputs, deps) {
+  if (!deps.fileExists(deps.jsonlFile)) {
+    deps.out("No structured log yet - this node has not run since structured logging was added.");
+    deps.out("Start it with `dahrk start`; it writes ~/.dahrk/logs/node.jsonl from the first boot.");
+    return 0;
+  }
+  if (inputs.follow) {
+    deps.out("(--follow on the structured log streams it unfiltered; pipe it through jq to narrow it:)");
+    deps.out(`  tail -f ${deps.jsonlFile} | jq -c 'select(.runId == "<runId>")'`);
+    deps.out("");
+    return deps.run(["tail", "-n", String(inputs.lines), "-f", deps.jsonlFile]);
+  }
+  const records = filterRecords(parseRecords(deps.readFile(deps.jsonlFile)), {
+    level: inputs.level,
+    run: inputs.run,
+    lines: inputs.lines
+  });
+  if (records.length === 0) {
+    const narrowed = [inputs.run ? `run ${inputs.run}` : void 0, inputs.level ? `level ${inputs.level}+` : void 0].filter(Boolean).join(" at ");
+    deps.out(narrowed ? `No records for ${narrowed}.` : "No records.");
+    return 0;
+  }
+  for (const r of records) {
+    if (inputs.json) deps.out(JSON.stringify(r));
+    else for (const line of renderRecord(r)) deps.out(line);
+  }
+  return 0;
+}
+function rotateIfLarge(file, maxBytes = MAX_LOG_BYTES) {
+  try {
+    if (!existsSync8(file) || statSync4(file).size <= maxBytes) return;
+    copyFileSync(file, `${file}.1`);
+    truncateSync(file, 0);
+  } catch {
+  }
+}
+var defaultLogsDeps = (files, jsonlFile) => ({
+  files,
+  jsonlFile,
+  fileExists: (path) => existsSync8(path),
+  readFile: (path) => readFileSync7(path, "utf8"),
+  run: (argv) => new Promise((resolve2) => {
+    const [cmd, ...args] = argv;
+    const child = spawn(cmd, args, { stdio: "inherit" });
+    child.on("error", () => resolve2(1));
+    child.on("close", (code) => resolve2(code ?? 0));
+  }),
+  out: (line) => void process.stdout.write(`${line}
+`)
+});
+
+// src/process-safety.ts
+import { mkdirSync as mkdirSync9, writeFileSync as writeFileSync8 } from "fs";
+import { join as join10 } from "path";
+function writeCrashRecord(dir, record) {
+  try {
+    mkdirSync9(dir, { recursive: true, mode: 448 });
+    const file = join10(dir, `${record.at.replace(/[:.]/g, "-")}.json`);
+    writeFileSync8(file, `${JSON.stringify(record, null, 2)}
+`, { mode: 384 });
+    return file;
+  } catch {
+    return void 0;
+  }
+}
+function toRecord(kind, reason, opts) {
+  const err = reason instanceof Error ? reason : void 0;
+  return {
+    at: (/* @__PURE__ */ new Date()).toISOString(),
+    kind,
+    name: err?.name ?? typeof reason,
+    message: err?.message ?? String(reason),
+    ...err?.stack ? { stack: err.stack } : {},
+    clientVersion: opts.clientVersion,
+    nodeVersion: process.version,
+    platform: process.platform,
+    arch: process.arch,
+    uptimeSec: Math.round(process.uptime()),
+    ...opts.activeJobIds ? { activeJobIds: opts.activeJobIds() } : {}
+  };
+}
+function makeCrashHandlers(opts) {
+  const handle = (kind, reason) => {
+    const record = toRecord(kind, reason, opts);
+    const file = opts.crashDir ? writeCrashRecord(opts.crashDir, record) : void 0;
+    opts.logger.error(
+      { err: reason, kind, ...file ? { crashFile: file } : {}, activeJobIds: record.activeJobIds },
+      `NODE_CRASH:${kind} ${record.name}: ${record.message}`
+    );
+  };
+  return {
+    onUnhandledRejection: (reason) => handle("unhandledRejection", reason),
+    onUncaughtException: (err) => {
+      handle("uncaughtException", err);
+      if (opts.exitOnCrash) process.exit(1);
+    }
+  };
+}
+function installProcessSafetyNet(opts) {
+  const { onUnhandledRejection, onUncaughtException } = makeCrashHandlers(opts);
+  process.on("unhandledRejection", onUnhandledRejection);
+  process.on("uncaughtException", onUncaughtException);
+  return {
+    uninstall: () => {
+      process.off("unhandledRejection", onUnhandledRejection);
+      process.off("uncaughtException", onUncaughtException);
+    }
+  };
+}
+
 // src/preflight.ts
-import { execFileSync as execFileSync4 } from "child_process";
+import { execFileSync as execFileSync5 } from "child_process";
 import { randomUUID as randomUUID2 } from "crypto";
-import { accessSync, constants as fsConstants, existsSync as existsSync4, readdirSync as readdirSync3, statfsSync } from "fs";
+import { accessSync, constants as fsConstants, existsSync as existsSync9, readdirSync as readdirSync5, statfsSync as statfsSync2 } from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join7 } from "path";
+import { join as join11 } from "path";
 var REPORT_BASE_URL = "https://app.dahrk.ai/r";
 var LOW_DISK_BYTES = 512 * 1024 * 1024;
 var PREFLIGHT_STAGES = [
@@ -3520,7 +4742,7 @@ var defaultDeps2 = () => ({
 });
 function commandPresent(cmd) {
   try {
-    execFileSync4("sh", ["-c", `command -v ${cmd}`], { stdio: "ignore" });
+    execFileSync5("sh", ["-c", `command -v ${cmd}`], { stdio: "ignore" });
     return true;
   } catch {
     return false;
@@ -3528,12 +4750,12 @@ function commandPresent(cmd) {
 }
 function sshKeyPresent() {
   try {
-    const dir = join7(homedir2(), ".ssh");
-    if (existsSync4(dir) && readdirSync3(dir).some((f) => f.endsWith(".pub"))) return true;
+    const dir = join11(homedir2(), ".ssh");
+    if (existsSync9(dir) && readdirSync5(dir).some((f) => f.endsWith(".pub"))) return true;
   } catch {
   }
   try {
-    execFileSync4("ssh-add", ["-l"], { stdio: "ignore" });
+    execFileSync5("ssh-add", ["-l"], { stdio: "ignore" });
     return true;
   } catch {
     return false;
@@ -3548,12 +4770,12 @@ function writable(dir) {
   }
 }
 function worktreeRoot(env) {
-  return env.DAHRK_WORKTREES_DIR ?? join7(env.DAHRK_STATE_DIR ?? join7(homedir2(), ".dahrk"), "worktrees");
+  return env.DAHRK_WORKTREES_DIR ?? join11(env.DAHRK_STATE_DIR ?? join11(homedir2(), ".dahrk"), "worktrees");
 }
 function nearestExisting(dir) {
   let cur = dir;
-  while (!existsSync4(cur)) {
-    const parent = join7(cur, "..");
+  while (!existsSync9(cur)) {
+    const parent = join11(cur, "..");
     if (parent === cur) break;
     cur = parent;
   }
@@ -3561,14 +4783,14 @@ function nearestExisting(dir) {
 }
 function freeDiskBytes(dir) {
   try {
-    const s = statfsSync(nearestExisting(dir));
+    const s = statfsSync2(nearestExisting(dir));
     return s.bavail * s.bsize;
   } catch {
     return void 0;
   }
 }
 function probeRepo(repoPath) {
-  const git = (args) => execFileSync4("git", ["-C", repoPath, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  const git = (args) => execFileSync5("git", ["-C", repoPath, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
   try {
     if (git(["rev-parse", "--is-inside-work-tree"]) !== "true") {
       return { path: repoPath, isGitRepo: false, headResolves: false, detail: "not inside a work tree" };
@@ -3603,10 +4825,97 @@ function gatherHostFacts(repoPath) {
 }
 
 // src/service.ts
-import { execFileSync as execFileSync5 } from "child_process";
-import { chmodSync, existsSync as existsSync5, mkdirSync as mkdirSync6, realpathSync, rmSync as rmSync4, writeFileSync as writeFileSync6 } from "fs";
-import { homedir as homedir3, platform as osPlatform3, userInfo } from "os";
-import { join as join8 } from "path";
+import { execFileSync as execFileSync6 } from "child_process";
+import { chmodSync as chmodSync2, existsSync as existsSync11, mkdirSync as mkdirSync11, readFileSync as readFileSync9, realpathSync as realpathSync2, rmSync as rmSync7, writeFileSync as writeFileSync10 } from "fs";
+import { homedir as homedir4, platform as osPlatform3, userInfo } from "os";
+import { join as join13 } from "path";
+
+// src/state.ts
+import { chmodSync, existsSync as existsSync10, mkdirSync as mkdirSync10, readFileSync as readFileSync8, writeFileSync as writeFileSync9 } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join12 } from "path";
+var STRING_FIELDS = ["nodeId", "enrolToken", "name", "tenantId", "updateCheckedAt", "updateLatest"];
+var isDesired = (v) => v === "running" || v === "stopped";
+var FILE_MODE = 384;
+var DIR_MODE = 448;
+function stateDir(env) {
+  return env.DAHRK_STATE_DIR ?? join12(homedir3(), ".dahrk");
+}
+function legacyStateDir(env) {
+  return env.DAHRK_STATE_DIR ? void 0 : join12(homedir3(), ".skakel");
+}
+function stateFile(env) {
+  return join12(stateDir(env), "node.json");
+}
+function logDir(env) {
+  return join12(stateDir(env), "logs");
+}
+function logFiles(env) {
+  const dir = logDir(env);
+  return { out: join12(dir, "node.out.log"), err: join12(dir, "node.err.log") };
+}
+function jsonlLogFile(env) {
+  return join12(logDir(env), "node.jsonl");
+}
+function crashDir(env) {
+  return join12(logDir(env), "crashes");
+}
+function lockFile(env) {
+  return join12(stateDir(env), "node.pid");
+}
+function setDesired(env, desired) {
+  writeState(env, { desired });
+}
+function readState(file) {
+  if (!existsSync10(file)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync8(file, "utf8"));
+    const state = {};
+    for (const key of STRING_FIELDS) {
+      const value = parsed[key];
+      if (typeof value === "string" && value) state[key] = value;
+    }
+    if (isDesired(parsed["desired"])) state.desired = parsed["desired"];
+    return state;
+  } catch {
+    return {};
+  }
+}
+function writeState(env, patch) {
+  const dir = stateDir(env);
+  const file = stateFile(env);
+  try {
+    mkdirSync10(dir, { recursive: true, mode: DIR_MODE });
+    const next = { ...readState(file), ...patch };
+    writeFileSync9(file, `${JSON.stringify(next, null, 2)}
+`, { mode: FILE_MODE });
+    chmodSync(file, FILE_MODE);
+  } catch (e) {
+    console.warn(`could not persist node state to ${file}: ${e.message}`);
+  }
+}
+function readPersistedToken(env) {
+  return readState(stateFile(env)).enrolToken;
+}
+function persistEnrolment(env, enrolment) {
+  const { token, name, tenantId } = enrolment;
+  if (!token) return;
+  const current = readState(stateFile(env));
+  const unchanged = current.enrolToken === token && (name === void 0 || current.name === name) && (tenantId === void 0 || current.tenantId === tenantId);
+  if (unchanged) return;
+  writeState(env, {
+    enrolToken: token,
+    ...name ? { name } : {},
+    ...tenantId ? { tenantId } : {}
+  });
+}
+function resolveEnrolToken(env, opts = {}) {
+  if (env.DAHRK_ENROL_TOKEN) return env.DAHRK_ENROL_TOKEN;
+  if (opts.ephemeral) return void 0;
+  return readPersistedToken(env);
+}
+
+// src/service.ts
 var UNIT_FILE_MODE = 384;
 var LAUNCHD_LABEL = "ai.dahrk.node";
 var SYSTEMD_UNIT = "dahrk-node.service";
@@ -3615,9 +4924,13 @@ function detectManager(plat) {
   if (plat === "linux") return "systemd";
   return "unsupported";
 }
+function serviceArgv(inputs) {
+  return [inputs.nodeBin, inputs.scriptPath, "start", "--foreground"];
+}
 function serviceEnv(inputs) {
   return {
     DAHRK_ENROL_TOKEN: inputs.token,
+    DAHRK_SUPERVISED: "1",
     ...inputs.hubUrl ? { DAHRK_HUB_URL: inputs.hubUrl } : {},
     ...inputs.name ? { DAHRK_NODE_NAME: inputs.name } : {},
     ...inputs.pathEnv ? { PATH: inputs.pathEnv } : {}
@@ -3627,7 +4940,7 @@ function xmlEscape(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
 function renderLaunchdPlist(inputs) {
-  const argv = [inputs.nodeBin, inputs.scriptPath, "start"];
+  const argv = serviceArgv(inputs);
   const env = serviceEnv(inputs);
   const progArgs = argv.map((a) => `    <string>${xmlEscape(a)}</string>`).join("\n");
   const envEntries = Object.entries(env).map(([k, v]) => `    <key>${xmlEscape(k)}</key>
@@ -3655,9 +4968,9 @@ ${envEntries}
   <key>ThrottleInterval</key>
   <integer>10</integer>
   <key>StandardOutPath</key>
-  <string>${xmlEscape(join8(inputs.logDir, "node.out.log"))}</string>
+  <string>${xmlEscape(join13(inputs.logDir, "node.out.log"))}</string>
   <key>StandardErrorPath</key>
-  <string>${xmlEscape(join8(inputs.logDir, "node.err.log"))}</string>
+  <string>${xmlEscape(join13(inputs.logDir, "node.err.log"))}</string>
 </dict>
 </plist>
 `;
@@ -3666,7 +4979,7 @@ function systemdEnvValue(v) {
   return /\s/.test(v) ? `"${v.replace(/"/g, '\\"')}"` : v;
 }
 function renderSystemdUnit(inputs) {
-  const exec = [inputs.nodeBin, inputs.scriptPath, "start"].map((a) => /\s/.test(a) ? `"${a}"` : a).join(" ");
+  const exec = serviceArgv(inputs).map((a) => /\s/.test(a) ? `"${a}"` : a).join(" ");
   const env = serviceEnv(inputs);
   const envLines = Object.entries(env).map(([k, v]) => `Environment=${k}=${systemdEnvValue(v)}`).join("\n");
   return `[Unit]
@@ -3680,6 +4993,8 @@ Type=simple
 ExecStart=${exec}
 ${envLines}
 WorkingDirectory=${inputs.homeDir}
+StandardOutput=append:${join13(inputs.logDir, "node.out.log")}
+StandardError=append:${join13(inputs.logDir, "node.err.log")}
 Restart=on-failure
 RestartSec=3
 RestartPreventExitStatus=78
@@ -3690,22 +5005,24 @@ WantedBy=default.target
 }
 function buildPlan(inputs) {
   if (inputs.manager === "launchd") {
-    const filePath2 = join8(inputs.homeDir, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+    const filePath2 = join13(inputs.homeDir, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
     return {
       manager: "launchd",
       label: LAUNCHD_LABEL,
       filePath: filePath2,
       content: renderLaunchdPlist(inputs),
-      // Unload first so a re-install picks up the rewritten plist; a not-loaded unload is a no-op.
+      // Unload first so a re-install picks up the rewritten plist; a not-loaded unload is a no-op. The
+      // `-w` on load also clears the "disabled" flag a previous `dahrk stop` set, so start-after-stop works.
       installCommands: [
         { argv: ["launchctl", "unload", filePath2], ignoreFailure: true },
         { argv: ["launchctl", "load", "-w", filePath2] }
       ],
+      stopCommands: [{ argv: ["launchctl", "unload", "-w", filePath2], ignoreFailure: true }],
       uninstallCommands: [{ argv: ["launchctl", "unload", "-w", filePath2], ignoreFailure: true }],
-      logHint: `tail -f ${join8(inputs.logDir, "node.err.log")}`
+      logHint: "dahrk logs -f"
     };
   }
-  const filePath = join8(inputs.homeDir, ".config", "systemd", "user", SYSTEMD_UNIT);
+  const filePath = join13(inputs.homeDir, ".config", "systemd", "user", SYSTEMD_UNIT);
   const user = userInfo().username;
   return {
     manager: "systemd",
@@ -3719,15 +5036,23 @@ function buildPlan(inputs) {
       { argv: ["systemctl", "--user", "enable", "--now", SYSTEMD_UNIT] },
       { argv: ["loginctl", "enable-linger", user], ignoreFailure: true }
     ],
+    // `disable`, not `stop`: a stopped-but-enabled unit comes straight back at the next boot, which is not
+    // what anyone means by `dahrk stop`. `dahrk start` re-enables it (`enable --now` above).
+    stopCommands: [
+      { argv: ["systemctl", "--user", "disable", "--now", SYSTEMD_UNIT], ignoreFailure: true }
+    ],
     uninstallCommands: [
       { argv: ["systemctl", "--user", "disable", "--now", SYSTEMD_UNIT], ignoreFailure: true },
       { argv: ["systemctl", "--user", "daemon-reload"], ignoreFailure: true }
     ],
-    logHint: `journalctl --user -u ${SYSTEMD_UNIT} -f`
+    logHint: "dahrk logs -f"
   };
 }
+function unitIsCurrent(plan, onDisk) {
+  return onDisk === plan.content;
+}
 function unitPath(manager, homeDir) {
-  return manager === "launchd" ? join8(homeDir, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`) : join8(homeDir, ".config", "systemd", "user", SYSTEMD_UNIT);
+  return manager === "launchd" ? join13(homeDir, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`) : join13(homeDir, ".config", "systemd", "user", SYSTEMD_UNIT);
 }
 function statusCommand(manager) {
   return manager === "launchd" ? ["launchctl", "list", LAUNCHD_LABEL] : ["systemctl", "--user", "show", SYSTEMD_UNIT, "-p", "ActiveState", "-p", "MainPID"];
@@ -3782,7 +5107,7 @@ async function runServiceInstall(inputs, deps = {}) {
     logDir: d.logDir
   });
   try {
-    if (manager === "launchd") d.mkdirp(d.logDir);
+    d.mkdirp(d.logDir);
     d.mkdirp(dirOf(plan.filePath));
     d.writeFile(plan.filePath, plan.content);
   } catch (e) {
@@ -3802,6 +5127,105 @@ async function runServiceInstall(inputs, deps = {}) {
   d.out("  uninstall: dahrk service uninstall");
   return 0;
 }
+function availabilityCommand(manager) {
+  return manager === "systemd" ? ["systemctl", "--user", "show", "-p", "Version"] : void 0;
+}
+async function runNodeStart(inputs, deps = {}) {
+  const d = { ...defaultDeps3(), ...deps };
+  const manager = detectManager(d.platform);
+  if (manager === "unsupported") {
+    return { kind: "foreground", reason: "no supported supervisor on this platform (launchd / systemd)" };
+  }
+  const probeCmd = availabilityCommand(manager);
+  if (probeCmd && d.capture(probeCmd).code !== 0) {
+    return { kind: "foreground", reason: "no systemd user session on this host (a container, typically)" };
+  }
+  const filePath = unitPath(manager, d.homeDir);
+  const unitExists = d.fileExists(filePath);
+  if (!inputs.token && !unitExists) {
+    d.out("No enrolment token: pass --token <token> or set DAHRK_ENROL_TOKEN.");
+    d.out("Get one at https://app.dahrk.ai.");
+    return { kind: "error", code: 2 };
+  }
+  const plan = buildPlan({
+    manager,
+    nodeBin: d.nodeBin,
+    scriptPath: d.scriptPath,
+    token: inputs.token ?? "-",
+    ...inputs.name ? { name: inputs.name } : {},
+    ...inputs.hubUrl ? { hubUrl: inputs.hubUrl } : {},
+    ...d.pathEnv ? { pathEnv: d.pathEnv } : {},
+    homeDir: d.homeDir,
+    logDir: d.logDir
+  });
+  const canRender = inputs.token !== void 0;
+  const current = canRender && unitExists && unitIsCurrent(plan, d.readFile(filePath));
+  const probe2 = unitExists ? d.capture(statusCommand(manager)) : { code: 1, stdout: "" };
+  const status = parseServiceStatus(manager, unitExists, probe2);
+  if (current && status.running) {
+    d.out(`Node is already running${status.pid ? ` (pid ${status.pid})` : ""}.`);
+    d.out(`  logs: ${plan.logHint}`);
+    return { kind: "running", code: 0 };
+  }
+  if (canRender && !current) {
+    try {
+      d.mkdirp(d.logDir);
+      d.mkdirp(dirOf(plan.filePath));
+      d.writeFile(plan.filePath, plan.content);
+    } catch (e) {
+      d.out(`Could not write the service file at ${plan.filePath}: ${e.message}`);
+      return { kind: "error", code: 1 };
+    }
+    d.out(unitExists ? `Updated ${plan.manager} service: ${plan.filePath}` : `Installed ${plan.manager} service: ${plan.filePath}`);
+  }
+  const code = runCommands(plan.installCommands, d);
+  if (code !== 0) {
+    d.out(`The service file is in place but starting it failed (exit ${code}).`);
+    return { kind: "error", code };
+  }
+  d.out("Node is running. It will start on boot and restart on failure.");
+  d.out(`  logs:   ${plan.logHint}`);
+  d.out("  stop:   dahrk stop");
+  return { kind: "running", code: 0 };
+}
+var STOP_FOREIGN_NODE = 3;
+function foreignNodePid(lock, servicePid, isAlive2) {
+  const held = parseLock(lock);
+  if (held === void 0 || held === servicePid) return void 0;
+  return isAlive2(held) ? held : void 0;
+}
+async function runNodeStop(deps = {}) {
+  const d = { ...defaultDeps3(), ...deps };
+  const manager = detectManager(d.platform);
+  if (manager === "unsupported") return printUnsupported(d.out);
+  const plan = buildPlan({
+    manager,
+    nodeBin: d.nodeBin,
+    scriptPath: d.scriptPath,
+    token: "-",
+    homeDir: d.homeDir,
+    logDir: d.logDir
+  });
+  if (!d.fileExists(plan.filePath)) {
+    d.out("No service installed, so there is nothing to stop.");
+    d.out("If you are running a node in a terminal (`dahrk start --foreground`), stop it with Ctrl-C.");
+    return reportForeignNode(d, void 0) ?? 0;
+  }
+  const servicePid = parseServiceStatus(manager, true, d.capture(statusCommand(manager))).pid;
+  runCommands(plan.stopCommands, d);
+  d.out("Node stopped. It will stay stopped across reboots until you run `dahrk start`.");
+  return reportForeignNode(d, servicePid) ?? 0;
+}
+function reportForeignNode(d, servicePid) {
+  const pid = foreignNodePid(d.readFile(d.lockFile), servicePid, d.isAlive);
+  if (pid === void 0) return void 0;
+  d.out("");
+  d.out(`WARNING: a node is STILL RUNNING on this host (pid ${pid}). \`dahrk stop\` cannot stop it.`);
+  d.out("Something else is supervising it: pm2, a container, or `dahrk start --foreground` in a terminal.");
+  d.out("It is not a stray copy - it holds this node's identity, so it is still connected to the hub and");
+  d.out("still taking Jobs. Stop it where it was started (e.g. `pm2 delete dahrk-node`), or kill the pid.");
+  return STOP_FOREIGN_NODE;
+}
 async function runServiceUninstall(deps = {}) {
   const d = { ...defaultDeps3(), ...deps };
   d.out("dahrk service uninstall");
@@ -3837,7 +5261,7 @@ function dirOf(path) {
 function resolveScriptPath() {
   const argv1 = process.argv[1] ?? "";
   try {
-    return realpathSync(argv1);
+    return realpathSync2(argv1);
   } catch {
     return argv1;
   }
@@ -3851,49 +5275,71 @@ function stableNodeBin(execPath, realpath) {
 }
 var realpathOrUndefined = (p) => {
   try {
-    return realpathSync(p);
+    return realpathSync2(p);
   } catch {
     return void 0;
   }
 };
 var defaultDeps3 = () => ({
   platform: osPlatform3(),
-  homeDir: homedir3(),
+  homeDir: homedir4(),
   // Not `process.execPath` raw: that is the versioned Homebrew Cellar path, which the next
   // `brew upgrade node` deletes out from under the unit. See `stableNodeBin`.
   nodeBin: stableNodeBin(process.execPath, realpathOrUndefined),
   scriptPath: resolveScriptPath(),
-  logDir: join8(process.env.DAHRK_STATE_DIR ?? join8(homedir3(), ".dahrk"), "logs"),
+  logDir: logDir(process.env),
+  lockFile: lockFile(process.env),
+  isAlive,
   // Snapshot the operator's PATH at install time so the daemon finds git + the runtime CLIs (Homebrew /
   // npm-global bins) that a supervisor's minimal PATH would otherwise hide.
   pathEnv: process.env.PATH,
-  mkdirp: (dir) => void mkdirSync6(dir, { recursive: true }),
+  mkdirp: (dir) => void mkdirSync11(dir, { recursive: true }),
   // The unit's environment block carries the enrolment token, so the file is a secret: write it
   // owner-only. `writeFileSync`'s `mode` applies only when it CREATES the file, so chmod explicitly
   // too - re-installing over a unit an older client left at 0644 must tighten it, not keep it.
   writeFile: (path, content) => {
-    writeFileSync6(path, content, { mode: UNIT_FILE_MODE });
-    chmodSync(path, UNIT_FILE_MODE);
+    writeFileSync10(path, content, { mode: UNIT_FILE_MODE });
+    chmodSync2(path, UNIT_FILE_MODE);
   },
-  removeFile: (path) => rmSync4(path, { force: true }),
-  fileExists: (path) => existsSync5(path),
+  readFile: (path) => {
+    try {
+      return readFileSync9(path, "utf8");
+    } catch {
+      return void 0;
+    }
+  },
+  removeFile: (path) => rmSync7(path, { force: true }),
+  fileExists: (path) => existsSync11(path),
   run: (argv) => {
     const [cmd, ...args] = argv;
     try {
-      execFileSync5(cmd, args, { stdio: "inherit" });
+      execFileSync6(cmd, args, { stdio: "inherit" });
       return 0;
     } catch (e) {
       const status = e.status;
       return typeof status === "number" ? status : 1;
     }
   },
+  capture: (argv) => {
+    const [cmd, ...args] = argv;
+    try {
+      const stdout = execFileSync6(cmd, args, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"]
+      });
+      return { code: 0, stdout };
+    } catch (e) {
+      const status = e.status;
+      return { code: typeof status === "number" ? status : 1, stdout: "" };
+    }
+  },
   out: (line) => void process.stdout.write(`${line}
 `)
 });
 
 // src/update.ts
-import { execFileSync as execFileSync6 } from "child_process";
-import { realpathSync as realpathSync2 } from "fs";
+import { execFileSync as execFileSync7 } from "child_process";
+import { realpathSync as realpathSync3 } from "fs";
 var LATEST_URL = "https://registry.npmjs.org/dahrk-node/latest";
 var CHANNEL_COMMANDS = {
   npm: "npm install -g dahrk-node@latest",
@@ -3914,7 +5360,7 @@ function detectChannel(binPath) {
   if (!binPath) return "unknown";
   let resolved = binPath;
   try {
-    resolved = realpathSync2(binPath);
+    resolved = realpathSync3(binPath);
   } catch {
   }
   if (/[\\/]node_modules[\\/]dahrk-node[\\/]/.test(resolved)) return "npm";
@@ -3989,8 +5435,11 @@ async function runUpdate(inputs, deps = {}) {
   }
   return code;
 }
-async function fetchLatestVersion() {
-  const res = await fetch(LATEST_URL, { headers: { accept: "application/json" } });
+async function fetchLatestVersion(signal) {
+  const res = await fetch(LATEST_URL, {
+    headers: { accept: "application/json" },
+    ...signal ? { signal } : {}
+  });
   if (!res.ok) throw new Error(`registry responded ${res.status}`);
   const body = await res.json();
   if (typeof body.version !== "string" || !body.version) throw new Error("registry returned no version");
@@ -3999,7 +5448,7 @@ async function fetchLatestVersion() {
 function spawnUpgrade(argv) {
   const [cmd, ...args] = argv;
   try {
-    execFileSync6(cmd, args, { stdio: "inherit" });
+    execFileSync7(cmd, args, { stdio: "inherit" });
     return 0;
   } catch (e) {
     const status = e.status;
@@ -4014,68 +5463,56 @@ var defaultDeps4 = () => ({
 `)
 });
 
-// src/state.ts
-import { chmodSync as chmodSync2, existsSync as existsSync6, mkdirSync as mkdirSync7, readFileSync as readFileSync5, writeFileSync as writeFileSync7 } from "fs";
-import { homedir as homedir4 } from "os";
-import { join as join9 } from "path";
-var STRING_FIELDS = ["nodeId", "enrolToken", "name", "tenantId"];
-var FILE_MODE = 384;
-var DIR_MODE = 448;
-function stateDir(env) {
-  return env.DAHRK_STATE_DIR ?? join9(homedir4(), ".dahrk");
-}
-function legacyStateDir(env) {
-  return env.DAHRK_STATE_DIR ? void 0 : join9(homedir4(), ".skakel");
-}
-function stateFile(env) {
-  return join9(stateDir(env), "node.json");
-}
-function readState(file) {
-  if (!existsSync6(file)) return {};
-  try {
-    const parsed = JSON.parse(readFileSync5(file, "utf8"));
-    const state = {};
-    for (const key of STRING_FIELDS) {
-      const value = parsed[key];
-      if (typeof value === "string" && value) state[key] = value;
-    }
-    return state;
-  } catch {
-    return {};
+// src/update-check.ts
+var DEFAULT_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 1500;
+function checkSuppressed(env) {
+  return Boolean(env.DAHRK_NO_UPDATE_CHECK || env.NO_UPDATE_NOTIFIER || env.CI);
+}
+function checkIntervalMs(env) {
+  const raw = env.DAHRK_UPDATE_CHECK_INTERVAL_MS;
+  if (raw === void 0) return DEFAULT_INTERVAL_MS;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : DEFAULT_INTERVAL_MS;
+}
+function shouldCheck(now, checkedAt, intervalMs, env) {
+  if (checkSuppressed(env)) return false;
+  if (!checkedAt) return true;
+  const last = Date.parse(checkedAt);
+  if (!Number.isFinite(last)) return true;
+  return now - last >= intervalMs || last > now;
+}
+function jitterMs(random, spreadMs = 60 * 60 * 1e3) {
+  return Math.floor(random * spreadMs);
+}
+function renderUpdateNotice(u) {
+  const cmd = upgradeCommand(u.channel);
+  const how = cmd ? ` (${u.channel}: ${cmd.display})` : " (run `dahrk update`)";
+  return `update available: ${u.current} -> ${u.latest}${how}`;
+}
+function renderUpdateLogLine(u) {
+  return `UPDATE_AVAILABLE:${u.latest} current=${u.current}`;
+}
+async function checkForUpdate(currentVersion, deps) {
+  if (checkSuppressed(deps.env)) return void 0;
+  const state = deps.readState();
+  if (!shouldCheck(deps.now(), state.updateCheckedAt, checkIntervalMs(deps.env), deps.env)) {
+    return cachedUpdate(state, currentVersion, deps.binPath);
   }
-}
-function writeState(env, patch) {
-  const dir = stateDir(env);
-  const file = stateFile(env);
+  let latest;
   try {
-    mkdirSync7(dir, { recursive: true, mode: DIR_MODE });
-    const next = { ...readState(file), ...patch };
-    writeFileSync7(file, `${JSON.stringify(next, null, 2)}
-`, { mode: FILE_MODE });
-    chmodSync2(file, FILE_MODE);
-  } catch (e) {
-    console.warn(`could not persist node state to ${file}: ${e.message}`);
+    latest = await deps.fetchLatest(AbortSignal.timeout(FETCH_TIMEOUT_MS));
+  } catch {
+    return void 0;
   }
+  deps.saveResult({ updateCheckedAt: new Date(deps.now()).toISOString(), updateLatest: latest });
+  if (!isNewer(latest, currentVersion)) return void 0;
+  return { current: currentVersion, latest, channel: detectChannel(deps.binPath) };
 }
-function readPersistedToken(env) {
-  return readState(stateFile(env)).enrolToken;
-}
-function persistEnrolment(env, enrolment) {
-  const { token, name, tenantId } = enrolment;
-  if (!token) return;
-  const current = readState(stateFile(env));
-  const unchanged = current.enrolToken === token && (name === void 0 || current.name === name) && (tenantId === void 0 || current.tenantId === tenantId);
-  if (unchanged) return;
-  writeState(env, {
-    enrolToken: token,
-    ...name ? { name } : {},
-    ...tenantId ? { tenantId } : {}
-  });
-}
-function resolveEnrolToken(env, opts = {}) {
-  if (env.DAHRK_ENROL_TOKEN) return env.DAHRK_ENROL_TOKEN;
-  if (opts.ephemeral) return void 0;
-  return readPersistedToken(env);
+function cachedUpdate(state, currentVersion, binPath) {
+  const latest = state.updateLatest;
+  if (!latest || !isNewer(latest, currentVersion)) return void 0;
+  return { current: currentVersion, latest, channel: detectChannel(binPath) };
 }
 
 // src/status.ts
@@ -4092,7 +5529,12 @@ function renderStatus(f) {
     lines.push(bullet("Enrolled", "no - run `dahrk start --token <token>` once to enrol"));
   }
   lines.push(bullet("Node id", nodeId ?? "not yet minted (first `dahrk start` mints one)"));
-  lines.push(bullet("Client", f.clientVersion));
+  lines.push(
+    bullet(
+      "Client",
+      f.update ? `${f.clientVersion} (update available: ${f.update.latest} - run \`dahrk update\`)` : f.clientVersion
+    )
+  );
   lines.push(bullet("Hub", f.hubUrl));
   lines.push(
     bullet(
@@ -4101,19 +5543,24 @@ function renderStatus(f) {
     )
   );
   if (!f.service) {
-    lines.push(bullet("Service", "not supported on this host (run `dahrk start` under pm2 instead)"));
+    lines.push(bullet("Node", "no supervisor on this host - run `dahrk start --foreground` (or under pm2)"));
   } else if (!f.service.installed) {
-    lines.push(bullet("Service", "not installed - run `dahrk service install` to run on boot"));
+    lines.push(bullet("Node", "not installed - run `dahrk start` to run it always-on"));
   } else if (f.service.running) {
     const pid = f.service.pid ? ` (pid ${f.service.pid})` : "";
-    lines.push(bullet("Service", `running${pid}`));
+    lines.push(bullet("Node", `running${pid}`));
+  } else if (f.state.desired === "stopped") {
+    lines.push(bullet("Node", "stopped - run `dahrk start` to bring it back"));
   } else {
-    lines.push(bullet("Service", "INSTALLED BUT NOT RUNNING - it is failing to start or crash-looping"));
+    lines.push(bullet("Node", "INSTALLED BUT NOT RUNNING - it is failing to start or crash-looping"));
     if (f.logHint) lines.push(bullet("", `check the logs: ${f.logHint}`));
   }
   lines.push("", `State file: ${f.stateFile}`);
   return lines;
 }
+function isUnhealthy(f) {
+  return Boolean(f.service?.installed && !f.service.running && f.state.desired !== "stopped");
+}
 async function runStatus(inputs, deps) {
   const manager = detectManager(deps.platform);
   let service;
@@ -4123,24 +5570,27 @@ async function runStatus(inputs, deps) {
     const exists = deps.fileExists(unit);
     const probe2 = exists ? deps.capture(statusCommand(manager)) : { code: 1, stdout: "" };
     service = parseServiceStatus(manager, exists, probe2);
-    logHint = manager === "launchd" ? `tail -f ${deps.homeDir}/.dahrk/logs/node.err.log` : "journalctl --user -u dahrk-node.service -f";
+    logHint = "dahrk logs -f";
   }
+  const state = readState(stateFile(deps.env));
+  const update = checkSuppressed(deps.env) ? void 0 : cachedUpdate(state, inputs.clientVersion, deps.binPath);
   const facts = {
     clientVersion: inputs.clientVersion,
     hubUrl: inputs.hubUrl,
     stateFile: stateFile(deps.env),
-    state: readState(stateFile(deps.env)),
+    state,
     envToken: Boolean(deps.env.DAHRK_ENROL_TOKEN),
     runtimes: await deps.detectRuntimes(),
     ...service ? { service } : {},
-    ...logHint ? { logHint } : {}
+    ...logHint ? { logHint } : {},
+    ...update ? { update } : {}
   };
   for (const line of renderStatus(facts)) deps.out(line);
-  return service?.installed && !service.running ? 1 : 0;
+  return isUnhealthy(facts) ? 1 : 0;
 }
 
 // src/main.ts
-var CLIENT_VERSION = "0.1.8";
+var CLIENT_VERSION = "0.1.10";
 var DEFAULT_HUB_URL = "wss://api.dahrk.ai";
 var list = (v) => (v ?? "").split(",").map((s) => s.trim()).filter(Boolean);
 var RUNTIMES = ["claude-code", "codex", "pi"];
@@ -4152,7 +5602,7 @@ function resolveNodeId(env, opts = {}) {
   if (existing) return existing;
   const legacy = legacyStateDir(env);
   if (legacy) {
-    const legacyId = readState(join10(legacy, "node.json")).nodeId;
+    const legacyId = readState(join14(legacy, "node.json")).nodeId;
     if (legacyId) return legacyId;
   }
   const nodeId = randomUUID3();
@@ -4219,9 +5669,49 @@ function envWithFlags(env, flags) {
   if (flags.hubUrl) merged.DAHRK_HUB_URL = flags.hubUrl;
   return merged;
 }
+function wantsForeground(env, flags) {
+  return flags.foreground || env.DAHRK_FOREGROUND === "1" || env.DAHRK_SUPERVISED === "1";
+}
 async function start(flags) {
   const env = envWithFlags(process.env, flags);
+  if (wantsForeground(env, flags)) return startForeground(env, flags);
+  await offerUpdate(env);
+  const outcome = await runNodeStart({
+    ...resolveEnrolToken(env) ? { token: resolveEnrolToken(env) } : {},
+    ...env.DAHRK_NODE_NAME ? { name: env.DAHRK_NODE_NAME } : {},
+    ...env.DAHRK_HUB_URL ? { hubUrl: env.DAHRK_HUB_URL } : {}
+  });
+  if (outcome.kind === "error") return outcome.code;
+  if (outcome.kind === "running") {
+    setDesired(env, "running");
+    return 0;
+  }
+  console.warn(`${outcome.reason}; running the node in this terminal instead.`);
+  console.warn("Use `dahrk start --foreground` (or DAHRK_FOREGROUND=1) to ask for this explicitly.");
+  return startForeground(env, flags);
+}
+async function startForeground(env, flags) {
+  if (!flags.ephemeral) {
+    const lock = acquireLock(defaultLockDeps(lockFile(env)));
+    if (!lock.ok) {
+      console.error(`A node is already running on this host (pid ${lock.heldBy}).`);
+      console.error("Follow it with `dahrk logs -f`, or stop it with `dahrk stop` first.");
+      return 1;
+    }
+    process.on("exit", lock.release);
+  }
+  const files = logFiles(env);
+  rotateIfLarge(files.out);
+  rotateIfLarge(files.err);
   const nodeId = resolveNodeId(env, { ephemeral: flags.ephemeral });
+  const shipper = new LogShipper({ ceiling: ceilingFromEnv(env) });
+  const logger = createNodeLoggerFromEnv(env, logDir(env), { nodeId, clientVersion: CLIENT_VERSION }, shipperStream(shipper));
+  installProcessSafetyNet({
+    logger,
+    crashDir: crashDir(env),
+    clientVersion: CLIENT_VERSION,
+    ...env.DAHRK_CRASH_EXIT === "1" ? { exitOnCrash: true } : {}
+  });
   const token = resolveEnrolToken(env, { ephemeral: flags.ephemeral });
   if (token) env.DAHRK_ENROL_TOKEN = token;
   const runtimes = await resolveRuntimes(env);
@@ -4230,26 +5720,78 @@ async function start(flags) {
       "no agent runtimes detected on this host (claude/codex/pi not on PATH); the node will advertise none and serve no Jobs. Install a runtime or set DAHRK_RUNTIMES to override. Run `dahrk doctor` to check."
     );
   }
+  if (!flags.ephemeral) setDesired(env, "running");
+  scheduleUpdateChecks(env);
   const resolved = { nodeId, runtimes, clientVersion: CLIENT_VERSION };
   const persist = token !== void 0 && !flags.ephemeral;
   await startEdgeNode({
     ...buildEdgeOptions(env, resolved),
+    logger,
+    shipper,
     ...persist ? {
       onEnrolled: (welcome) => persistEnrolment(env, { token, name: welcome.name, tenantId: welcome.tenantId })
     } : {}
   });
+  return 0;
+}
+async function stop(env) {
+  const code = await runNodeStop();
+  if (code === 0 || code === STOP_FOREIGN_NODE) setDesired(env, "stopped");
+  return code;
+}
+function updateCheckDeps(env) {
+  return {
+    env,
+    now: () => Date.now(),
+    binPath: process.argv[1],
+    readState: () => readState(stateFile(env)),
+    saveResult: (patch) => writeState(env, patch),
+    fetchLatest: fetchLatestVersion
+  };
+}
+var isInteractive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+async function confirm(question) {
+  const { createInterface } = await import("readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question(`${question} [Y/n] `)).trim().toLowerCase();
+    return answer === "" || answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+async function offerUpdate(env) {
+  const available = await checkForUpdate(CLIENT_VERSION, updateCheckDeps(env));
+  if (!available) return;
+  console.log(renderUpdateNotice(available));
+  if (!isInteractive()) return;
+  if (!await confirm("update now?")) return;
+  const code = await runUpdate({ currentVersion: CLIENT_VERSION, check: false });
+  if (code !== 0) console.warn("Update failed; starting the node on the current version anyway.");
+}
+function scheduleUpdateChecks(env) {
+  if (checkSuppressed(env)) return;
+  const deps = updateCheckDeps(env);
+  const tick = async () => {
+    const available = await checkForUpdate(CLIENT_VERSION, deps);
+    if (available) process.stdout.write(`${renderUpdateLogLine(available)}
+`);
+  };
+  setTimeout(() => void tick(), jitterMs(Math.random())).unref();
+  setInterval(() => void tick(), checkIntervalMs(env)).unref();
 }
 function statusDeps(env) {
   return {
     platform: osPlatform4(),
     homeDir: homedir5(),
     env,
+    binPath: process.argv[1],
     detectRuntimes: () => resolveRuntimes(env),
-    fileExists: (path) => existsSync7(path),
+    fileExists: (path) => existsSync12(path),
     capture: (argv) => {
       const [cmd, ...args] = argv;
       try {
-        const stdout = execFileSync7(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        const stdout = execFileSync8(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
         return { code: 0, stdout };
       } catch (e) {
         const status = e.status;
@@ -4279,7 +5821,7 @@ async function runWorkflow(flags) {
   });
 }
 async function main() {
-  const invoked = basename(process.argv[1] ?? "");
+  const invoked = basename2(process.argv[1] ?? "");
   const bin = !invoked || invoked.startsWith("main.") ? "dahrk" : invoked;
   const parsed = parseCli(process.argv.slice(2));
   switch (parsed.kind) {
@@ -4337,22 +5879,84 @@ async function main() {
       process.exitCode = await runUpdate({ currentVersion: CLIENT_VERSION, check: parsed.flags.check });
       break;
     case "start":
-      await start(parsed.flags);
+      process.exitCode = await start(parsed.flags);
+      break;
+    case "stop":
+      process.exitCode = await stop(applyEnvAliases(process.env));
+      break;
+    case "restart": {
+      const env = envWithFlags(process.env, parsed.flags);
+      const code = await stop(env);
+      if (code !== 0) {
+        process.exitCode = code;
+        break;
+      }
+      process.exitCode = await start(parsed.flags);
+      break;
+    }
+    case "logs": {
+      const env = applyEnvAliases(process.env);
+      process.exitCode = await runLogs(parsed.flags, defaultLogsDeps(logFiles(env), jsonlLogFile(env)));
+      break;
+    }
+    case "diagnose": {
+      const env = applyEnvAliases(process.env);
+      const doctorLines = [];
+      const doctor = async () => {
+        await runDoctor(
+          {
+            ...resolveEnrolToken(env) ? { token: resolveEnrolToken(env) } : {},
+            hubUrl: env.DAHRK_HUB_URL ?? DEFAULT_HUB_URL
+          },
+          { out: (line) => void doctorLines.push(line) }
+        );
+        return doctorLines;
+      };
+      process.exitCode = await runDiagnose(
+        defaultDiagnoseDeps(
+          {
+            stateFile: stateFile(env),
+            jsonlFile: jsonlLogFile(env),
+            crashDir: crashDir(env),
+            outFile: parsed.flags.out ?? defaultBundlePath(process.cwd(), /* @__PURE__ */ new Date())
+          },
+          CLIENT_VERSION,
+          doctor
+        )
+      );
       break;
+    }
   }
 }
 var invokedAsEntrypoint = (() => {
   const argv1 = process.argv[1];
   if (!argv1) return false;
   try {
-    return pathToFileURL(realpathSync3(argv1)).href === import.meta.url;
+    return pathToFileURL(realpathSync4(argv1)).href === import.meta.url;
   } catch {
     return false;
   }
 })();
 if (invokedAsEntrypoint) {
   main().catch((err) => {
+    const enrolmentRejected = process.exitCode === ENROLMENT_REJECTED_EXIT_CODE;
     console.error(err instanceof Error ? err.message : String(err));
+    if (!enrolmentRejected) {
+      if (err instanceof Error && err.stack) console.error(err.stack);
+      const env = applyEnvAliases(process.env);
+      writeCrashRecord(crashDir(env), {
+        at: (/* @__PURE__ */ new Date()).toISOString(),
+        kind: "uncaughtException",
+        name: err instanceof Error ? err.name : typeof err,
+        message: err instanceof Error ? err.message : String(err),
+        ...err instanceof Error && err.stack ? { stack: err.stack } : {},
+        clientVersion: CLIENT_VERSION,
+        nodeVersion: process.version,
+        platform: process.platform,
+        arch: process.arch,
+        uptimeSec: Math.round(process.uptime())
+      });
+    }
     process.exit(process.exitCode || 1);
   });
 }