dahrk-node 0.1.2 → 0.1.4

package/dist/main.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 // src/main.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync6, readFileSync as readFileSync5, realpathSync, writeFileSync as writeFileSync6 } from "fs";
-import { randomUUID as randomUUID2 } from "crypto";
-import { homedir as homedir2 } from "os";
-import { basename, join as join7 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync6, readFileSync as readFileSync5, realpathSync as realpathSync2, writeFileSync as writeFileSync6 } from "fs";
+import { randomUUID as randomUUID3 } from "crypto";
+import { homedir as homedir3 } from "os";
+import { basename, join as join8 } from "path";
 import { pathToFileURL } from "url";
 
 // ../../packages/edge/src/ws-client.ts
@@ -335,7 +335,7 @@ var ManagedMailbox = class {
         const v = this.q.shift();
         if (v !== void 0) return Promise.resolve({ value: v, done: false });
         if (this.done) return Promise.resolve({ value: void 0, done: true });
-        return new Promise((resolve) => this.waiters.push(resolve));
+        return new Promise((resolve2) => this.waiters.push(resolve2));
       }
     };
   }
@@ -346,7 +346,7 @@ function interactiveIdleWindows(ctx) {
   return { firstReplyMs: Math.max(firstReplyMs, idleMs), idleMs };
 }
 function raceNextTurn(pending, idleMs, signal) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     let settled = false;
     let timer;
     function finish(r) {
@@ -354,7 +354,7 @@ function raceNextTurn(pending, idleMs, signal) {
       settled = true;
       if (timer) clearTimeout(timer);
       signal.removeEventListener("abort", onAbort);
-      resolve(r);
+      resolve2(r);
     }
     function onAbort() {
       finish({ kind: "cancelled" });
@@ -412,6 +412,13 @@ var userMsg = (text) => ({
   message: { role: "user", content: text }
 });
 var sessionIdOf = (msg) => "session_id" in msg && typeof msg.session_id === "string" ? msg.session_id : void 0;
+var policyCanUseTool = async (ctx, toolName, input) => {
+  const verdict = ctx.authorizeToolUse?.(toolName, input);
+  if (verdict?.verdict === "deny") {
+    return { behavior: "deny", message: verdict.reason ?? `tool "${toolName}" denied by policy ${verdict.policy}` };
+  }
+  return { behavior: "allow", updatedInput: input };
+};
 function buildBrokeredMcpServers(ctx) {
   const servers = ctx.config.mcpServers;
   if (!servers || servers.length === 0 || !ctx.mcpProxyBaseUrl) return void 0;
@@ -477,7 +484,7 @@ function createClaudeRunner() {
         // Tools stay allowed by canUseTool below; we do NOT set a restrictive allowedTools here.
         ...mcpServers ? { mcpServers } : {},
         // Headless: allow tools to run without an interactive permission prompt (M6 wires policy).
-        canUseTool: async (_toolName, input) => ({ behavior: "allow", updatedInput: input })
+        canUseTool: async (toolName, input) => policyCanUseTool(ctx, toolName, input)
       };
       const state = newBufferState();
       let status = "ok";
@@ -512,7 +519,7 @@ function createClaudeRunner() {
         // Auto-approve the exit tool; `allowedTools` is an auto-approve list, not a whitelist, so it
         // does not restrict the other tools canUseTool allows.
         allowedTools: [stageTool.allowedToolName],
-        canUseTool: async (toolName, input) => summarising && toolName !== stageTool.allowedToolName ? { behavior: "deny", message: "Summarise from the work you just did; reply with the sentence only, no tools." } : { behavior: "allow", updatedInput: input },
+        canUseTool: async (toolName, input) => summarising && toolName !== stageTool.allowedToolName ? { behavior: "deny", message: "Summarise from the work you just did; reply with the sentence only, no tools." } : policyCanUseTool(ctx, toolName, input),
         maxTurns: MAX_TURNS,
         includePartialMessages: false
       };
@@ -1214,6 +1221,7 @@ import { dirname, isAbsolute, join as join2 } from "path";
 var noopLogger = { info: () => {
 }, warn: () => {
 } };
+var SCRATCH_DIR = ".skakel/scratch";
 function parseOwnerRepo(gitUrl) {
   const m = /[:/]([^/:]+)\/([^/]+?)(?:\.git)?$/.exec(gitUrl.trim());
   return m ? `${m[1]}/${m[2]}` : void 0;
@@ -1255,24 +1263,23 @@ function createGitService(opts = {}) {
     return (stderr?.trim() || err?.message || String(e)).split("\n")[0] ?? String(e);
   };
   const excludeScratchLocally = (worktreePath) => {
-    const entry = ".skakel/scratch/";
+    const entry = `${SCRATCH_DIR}/`;
     try {
       const rel = git(worktreePath, ["rev-parse", "--git-path", "info/exclude"]).trim();
       const excludePath = isAbsolute(rel) ? rel : join2(worktreePath, rel);
       const existing = existsSync(excludePath) ? readFileSync2(excludePath, "utf-8") : "";
       if (existing.split("\n").some((l) => l.trim() === entry)) return;
       mkdirSync(dirname(excludePath), { recursive: true });
-      const sep2 = existing && !existing.endsWith("\n") ? "\n" : "";
-      writeFileSync(excludePath, `${existing}${sep2}${entry}
+      const sep3 = existing && !existing.endsWith("\n") ? "\n" : "";
+      writeFileSync(excludePath, `${existing}${sep3}${entry}
 `);
     } catch (e) {
       log2.warn(`could not set worktree scratch exclude at ${worktreePath}: ${e.message}`);
     }
   };
   const commitPending = (worktreePath, message) => {
-    const SCRATCH = ".skakel/scratch";
     excludeScratchLocally(worktreePath);
-    git(worktreePath, ["rm", "-r", "--cached", "--ignore-unmatch", "--quiet", SCRATCH]);
+    git(worktreePath, ["rm", "-r", "--cached", "--ignore-unmatch", "--quiet", SCRATCH_DIR]);
     git(worktreePath, ["add", "-A", "--", "."]);
     const dirty = !gitOk(worktreePath, ["diff", "--cached", "--quiet"]);
     if (dirty) {
@@ -1394,6 +1401,11 @@ function createGitService(opts = {}) {
           if (!gitOk(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]);
+          if (!delta.some((p) => !isScratchPath(p))) {
+            return { headSha, pushed: false, nothingToCommit: true, commitsAhead, integration: "noop" };
+          }
           try {
             git(worktreePath, [
               "-c",
@@ -1667,7 +1679,7 @@ import { execFileSync as execFileSync3 } 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 { tmpdir as tmpdir2 } from "os";
-import { join as join6 } from "path";
+import { isAbsolute as isAbsolute2, join as join6, relative as relative2, resolve, sep as sep2 } from "path";
 import { attachedDocBasename as attachedDocBasename2 } from "@dahrk/contracts";
 
 // ../../packages/edge/src/builtins.ts
@@ -1841,11 +1853,11 @@ async function startMcpGateway(opts) {
     if (upstream.body) await pipeline(Readable.fromWeb(upstream.body), res);
     else res.end();
   };
-  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  await new Promise((resolve2) => server.listen(0, "127.0.0.1", resolve2));
   const { port } = server.address();
   return {
     baseUrl: `http://127.0.0.1:${port}`,
-    stop: () => new Promise((resolve) => server.close(() => resolve()))
+    stop: () => new Promise((resolve2) => server.close(() => resolve2()))
   };
 }
 
@@ -1933,9 +1945,24 @@ var SCRATCH_OUTPUT_DIR = ".skakel/scratch/output";
 function capContent(raw) {
   return raw.length > ARTIFACT_CAP_BYTES ? raw.slice(0, ARTIFACT_CAP_BYTES) : raw;
 }
+function resolveWorktreeRelativePath(ref, relPath) {
+  if (isAbsolute2(relPath)) return void 0;
+  const root = resolve(ref.worktreePath);
+  const target = resolve(root, relPath);
+  const fromRoot = relative2(root, target);
+  if (fromRoot === "" || fromRoot === ".." || fromRoot.startsWith(`..${sep2}`) || isAbsolute2(fromRoot)) {
+    return void 0;
+  }
+  return target;
+}
+function isSafeWorktreeRelativePath(ref, relPath) {
+  return resolveWorktreeRelativePath(ref, relPath) !== void 0;
+}
 function readEmittedArtifact(ref, relPath) {
+  const path = resolveWorktreeRelativePath(ref, relPath);
+  if (!path) return void 0;
   try {
-    const raw = readFileSync4(join6(ref.worktreePath, relPath), "utf8");
+    const raw = readFileSync4(path, "utf8");
     return { path: relPath, content: capContent(raw) };
   } catch {
     return void 0;
@@ -1981,7 +2008,7 @@ function resolveStageArtifact(ref, emitArtifact, handedBack) {
     const declared = readEmittedArtifact(ref, emitArtifact);
     if (declared && declared.content.trim().length > 0) return { artifact: declared, source: "declared-file" };
   }
-  if (handedBack && handedBack.content.trim().length > 0) {
+  if (handedBack && handedBack.content.trim().length > 0 && isSafeWorktreeRelativePath(ref, handedBack.path)) {
     return { artifact: { path: handedBack.path, content: capContent(handedBack.content) }, source: "tool-handoff" };
   }
   const scratch = scanScratchOutput(ref, emitArtifact);
@@ -2081,8 +2108,9 @@ function createStageRunner(deps) {
       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 (slash > 0) {
+        if (artifactDir && slash > 0) {
           try {
             mkdirSync5(join6(ref.worktreePath, job.agentConfig.emitArtifact.slice(0, slash)), { recursive: true });
           } catch {
@@ -2219,20 +2247,50 @@ function createStageRunner(deps) {
         return finish("fail", `${stageId}: denied at stage entry (${entry.policy})`, job.sessionId);
       }
       let denied = false;
+      const authorisedActions = [];
       const runtime = agentConfig.runtime;
+      const actionKey = (tool2, input) => {
+        try {
+          return `${tool2}\0${JSON.stringify(input)}`;
+        } catch {
+          return `${tool2}\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 = (tool2, input) => {
+        const verdict = evaluatePolicies({ kind: "action", stageId, tool: tool2, input }, rules);
+        if (verdict.verdict === "deny") {
+          recordDeny(verdict);
+        } else {
+          authorisedActions.push(actionKey(tool2, input));
+        }
+        return verdict;
+      };
       const onTrace = (event) => {
         if (event.type === "action") {
-          const verdict = evaluatePolicies(
-            { kind: "action", stageId, tool: event.tool, input: event.input },
-            rules
-          );
-          if (verdict.verdict === "deny") {
-            denied = true;
-            streamEvent(writer.append(event));
-            streamEvent(writer.append({ seq: 0, ts: nowIso2(), type: "observation", runtime, toolUseId: event.toolUseId, isError: true, output: { error: verdict.reason } }));
-            streamEvent(writer.append({ seq: 0, ts: nowIso2(), type: "state", runtime, event: "policy-deny", detail: verdict.reason }));
-            deps.sendProgress({ jobId, kind: "error", ts: nowIso2(), text: verdict.reason });
-            return;
+          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));
@@ -2260,7 +2318,8 @@ function createStageRunner(deps) {
         ...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
+        writeRaw: writer.writeRaw,
+        authorizeToolUse
       };
       const interactive = agentConfig.interaction === "interactive";
       let result;
@@ -2364,6 +2423,18 @@ function createStageRunner(deps) {
             base: job.base,
             ...job.workspaceRef.credentialToken ? { credentialToken: job.workspaceRef.credentialToken } : {}
           });
+          if (r.integration === "noop") {
+            return {
+              jobId,
+              status: "ok",
+              branch: job.branch,
+              headSha: r.headSha,
+              pushed: false,
+              nothingToCommit: true,
+              commitsAhead: r.commitsAhead,
+              summary: `no changes to deliver on ${job.branch} - work already present on ${job.base}`
+            };
+          }
           if (r.integration === "conflict") {
             return {
               jobId,
@@ -2442,11 +2513,27 @@ async function startEdgeNode(opts) {
   });
   let ws;
   let heartbeat;
+  let reconnectTimer;
+  let lastPongAt = 0;
   let shuttingDown = false;
   let onFatal;
   const send = (msg) => {
     if (ws && ws.readyState === WebSocket.OPEN) ws.send(encode(msg));
   };
+  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`);
+        sock.terminate();
+        return;
+      }
+      send({ type: "heartbeat" });
+      if (sock.readyState === WebSocket.OPEN) sock.ping();
+    }, intervalMs);
+  };
   const MAX_RESEND = 100;
   const lastResults = /* @__PURE__ */ new Map();
   const rememberResult = (jobId, frame) => {
@@ -2462,12 +2549,12 @@ async function startEdgeNode(opts) {
   const trace = {
     event: (frame) => send({ type: "trace-event", ...frame }),
     finalised: (frame) => send({ type: "trace-finalised", ...frame }),
-    requestBlobUrl: (req) => new Promise((resolve) => {
+    requestBlobUrl: (req) => new Promise((resolve2) => {
       const reqId = `${req.runId}:${req.stageId}:${req.attempt}:${blobReqCounter++}`;
-      pendingBlob.set(reqId, resolve);
+      pendingBlob.set(reqId, resolve2);
       send({ type: "blob-put-request", reqId, ...req });
       setTimeout(() => {
-        if (pendingBlob.delete(reqId)) resolve({ key: "" });
+        if (pendingBlob.delete(reqId)) resolve2({ key: "" });
       }, 3e4).unref?.();
     })
   };
@@ -2489,18 +2576,17 @@ async function startEdgeNode(opts) {
     if (msg.type === "welcome") {
       stageDeps.tenantId = msg.tenantId;
       if (opts.retention === void 0 && msg.retention) stageDeps.retention = msg.retention;
-      if (opts.heartbeatMs === void 0 && msg.heartbeatMs > 0) {
-        if (heartbeat) clearInterval(heartbeat);
-        heartbeat = setInterval(() => send({ type: "heartbeat" }), msg.heartbeatMs);
+      if (opts.heartbeatMs === void 0 && msg.heartbeatMs > 0 && ws) {
+        startHeartbeat(ws, msg.heartbeatMs);
       }
       log(`EDGE_WELCOMED:${msg.name} tenant=${msg.tenantId} credentialMode=${msg.credentialMode}`);
       return;
     }
     if (msg.type === "blob-put-url") {
-      const resolve = pendingBlob.get(msg.reqId);
-      if (resolve) {
+      const resolve2 = pendingBlob.get(msg.reqId);
+      if (resolve2) {
         pendingBlob.delete(msg.reqId);
-        resolve({ key: msg.key, ...msg.url ? { url: msg.url } : {} });
+        resolve2({ key: msg.key, ...msg.url ? { url: msg.url } : {} });
       }
       return;
     }
@@ -2522,6 +2608,12 @@ async function startEdgeNode(opts) {
         log(`PUSH_DUPLICATE:${job2.runId} ${job2.jobId}`);
         return;
       }
+      const cachedPush = lastResults.get(job2.jobId);
+      if (cachedPush) {
+        send(cachedPush);
+        log(`PUSH_REPLAY:${job2.runId} ${job2.jobId}`);
+        return;
+      }
       running.add(job2.jobId);
       log(`PUSH_STARTED:${job2.runId} ${job2.branch}`);
       try {
@@ -2550,6 +2642,12 @@ async function startEdgeNode(opts) {
       log(`JOB_DUPLICATE:${job.stageId} ${job.jobId}`);
       return;
     }
+    const cachedJob = lastResults.get(job.jobId);
+    if (cachedJob) {
+      send(cachedJob);
+      log(`JOB_REPLAY:${job.stageId} ${job.jobId}`);
+      return;
+    }
     running.add(job.jobId);
     log(`JOB_STARTED:${job.stageId} ${job.jobId}`);
     try {
@@ -2589,12 +2687,16 @@ async function startEdgeNode(opts) {
         clientVersion: opts.clientVersion ?? "0.0.0"
       });
       for (const frame of lastResults.values()) send(frame);
-      heartbeat = setInterval(() => send({ type: "heartbeat" }), opts.heartbeatMs ?? 5e3);
+      startHeartbeat(sock, opts.heartbeatMs ?? 5e3);
     });
     sock.on("message", (raw) => void onMessage(raw.toString()));
+    sock.on("pong", () => {
+      lastPongAt = Date.now();
+    });
     sock.on("error", (e) => log(`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";
@@ -2603,15 +2705,27 @@ async function startEdgeNode(opts) {
         onFatal?.(new Error(`hub rejected edge enrolment (${code}): ${detail}`));
         return;
       }
-      if (!shuttingDown) setTimeout(connect, 500);
+      if (!shuttingDown) reconnectTimer = setTimeout(connect, 500);
     });
   };
+  opts.signal?.addEventListener(
+    "abort",
+    () => {
+      shuttingDown = true;
+      if (heartbeat) clearInterval(heartbeat);
+      heartbeat = void 0;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      reconnectTimer = void 0;
+      ws?.close(1e3, "shutting down");
+    },
+    { once: true }
+  );
   connect();
-  await new Promise((resolve, reject) => {
+  await new Promise((resolve2, reject) => {
     const t = setInterval(() => {
       if (ws && ws.readyState === WebSocket.OPEN) {
         clearInterval(t);
-        resolve();
+        resolve2();
       }
     }, 50);
     onFatal = (err) => {
@@ -2629,11 +2743,11 @@ var PROBES = [
   { runtime: "pi", cmd: "pi" }
 ];
 function probe(cmd, timeoutMs) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     execFile(cmd, ["--version"], { timeout: timeoutMs }, (err, stdout) => {
-      if (err) return resolve(void 0);
+      if (err) return resolve2(void 0);
       const line = stdout.split("\n").map((s) => s.trim()).find(Boolean);
-      resolve(line ?? "");
+      resolve2(line ?? "");
     });
   });
 }
@@ -2676,7 +2790,7 @@ function probeHub(opts) {
     clientVersion = "0.0.0",
     timeoutMs = 8e3
   } = opts;
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     let settled = false;
     let opened = false;
     let ws;
@@ -2688,7 +2802,7 @@ function probeHub(opts) {
         ws.terminate();
       } catch {
       }
-      resolve(result);
+      resolve2(result);
     };
     const timer = setTimeout(
       () => done({ ok: false, reason: "timeout", detail: `no welcome within ${timeoutMs}ms` }),
@@ -2751,7 +2865,7 @@ function probeHub(opts) {
 
 // src/cli.ts
 import { parseArgs } from "util";
-var COMMANDS = /* @__PURE__ */ new Set(["start", "doctor"]);
+var COMMANDS = /* @__PURE__ */ new Set(["start", "run", "doctor", "update"]);
 var isCommand = (s) => COMMANDS.has(s);
 function parseCli(argv) {
   const [first, ...rest] = argv;
@@ -2769,6 +2883,8 @@ function parseCli(argv) {
     command = first;
     flagArgs = rest;
   }
+  if (command === "run") return parseRun(flagArgs);
+  if (command === "update") return parseUpdate(flagArgs);
   let values;
   try {
     ({ values } = parseArgs({
@@ -2794,6 +2910,55 @@ function parseCli(argv) {
   };
   return { kind: command, flags };
 }
+function parseRun(flagArgs) {
+  let values;
+  let positionals;
+  try {
+    ({ values, positionals } = parseArgs({
+      args: flagArgs,
+      options: {
+        repo: { type: "string" },
+        token: { type: "string" },
+        "hub-url": { type: "string" },
+        help: { type: "boolean", default: false }
+      },
+      allowPositionals: true
+    }));
+  } catch (e) {
+    return { kind: "error", message: e.message };
+  }
+  if (values.help) return { kind: "help", command: "run" };
+  if (positionals.length === 0) {
+    return { kind: "error", message: "run: missing workflow (e.g. `dahrk run preflight`)" };
+  }
+  if (positionals.length > 1) {
+    return { kind: "error", message: `run: unexpected argument "${positionals[1]}" (one workflow at a time)` };
+  }
+  const flags = {
+    workflow: positionals[0],
+    ...values.repo ? { repo: values.repo } : {},
+    ...values.token ? { token: values.token } : {},
+    ...values["hub-url"] ? { hubUrl: values["hub-url"] } : {}
+  };
+  return { kind: "run", flags };
+}
+function parseUpdate(flagArgs) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: flagArgs,
+      options: {
+        check: { 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: "update" };
+  return { kind: "update", flags: { check: values.check ?? false } };
+}
 function usage(bin, command) {
   if (command === "start") {
     return [
@@ -2808,6 +2973,22 @@ function usage(bin, command) {
       "  --ephemeral        Do not persist a node id; mint a throwaway one (CI / one-shot)."
     ].join("\n");
   }
+  if (command === "run") {
+    return [
+      `Usage: ${bin} run <workflow> [options]`,
+      "",
+      "Run a workflow through the engine locally against this node's worktree, streaming stage progress.",
+      "The engine-backed twin of `doctor`: the same run and stages, from the terminal - no Linear, no issue.",
+      "",
+      "Workflows:",
+      "  preflight    Is this floor sound enough to run? Checks node, repo, and tools, then reports.",
+      "",
+      "Options:",
+      "  --repo <path>      Repo to inspect (default: the current directory).",
+      "  --hub-url <url>    Hub WebSocket URL to probe for reachability (or set DAHRK_HUB_URL).",
+      "  --token <token>    Enrolment token to verify against the hub (or set DAHRK_ENROL_TOKEN)."
+    ].join("\n");
+  }
   if (command === "doctor") {
     return [
       `Usage: ${bin} doctor [options]`,
@@ -2819,12 +3000,26 @@ function usage(bin, command) {
       "  --hub-url <url>    Hub WebSocket URL to reach (or set DAHRK_HUB_URL)."
     ].join("\n");
   }
+  if (command === "update") {
+    return [
+      `Usage: ${bin} update [--check]`,
+      "",
+      "Update this client in place to the latest published release. Detects how it was installed",
+      "(npm / Homebrew / curl) and runs the right upgrade, or prints the exact command when it cannot.",
+      "Reports current -> latest, and a no-op when already current.",
+      "",
+      "Options:",
+      "  --check    Report whether an update is available without applying it (dry run)."
+    ].join("\n");
+  }
   return [
     `Usage: ${bin} <command> [options]`,
     "",
     "Commands:",
     "  start     Run the edge node (default). Needs a --token and a hub URL.",
+    "  run       Run a workflow locally (engine-backed), e.g. `run preflight`.",
     "  doctor    Preflight checks: Node, runtimes, hub reachability, token validity.",
+    "  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.",
     "",
@@ -2963,20 +3158,359 @@ async function runDoctor(inputs, deps = {}) {
   return checks.some((c) => c.status === "fail") ? 1 : 0;
 }
 
+// src/preflight.ts
+import { execFileSync as execFileSync4 } from "child_process";
+import { randomUUID as randomUUID2 } from "crypto";
+import { accessSync, constants as fsConstants, existsSync as existsSync4, readdirSync as readdirSync3, statfsSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join7 } from "path";
+var REPORT_BASE_URL = "https://app.dahrk.ai/r";
+var LOW_DISK_BYTES = 512 * 1024 * 1024;
+var PREFLIGHT_STAGES = [
+  { id: "check-node", label: "check node" },
+  { id: "check-repo", label: "check repo" },
+  { id: "check-tools", label: "check tools" },
+  { id: "analyse", label: "analyse" },
+  { id: "report", label: "report" }
+];
+function checkWorktreeRoot(writable2) {
+  return writable2 ? { status: "pass", label: "Worktree root", detail: "writable" } : { status: "fail", label: "Worktree root", detail: "not writable; the node cannot create worktrees here" };
+}
+function checkDiskSpace(freeBytes) {
+  if (freeBytes === void 0) {
+    return { status: "warn", label: "Free space", detail: "could not be determined" };
+  }
+  const gib = (freeBytes / (1024 * 1024 * 1024)).toFixed(1);
+  return freeBytes >= LOW_DISK_BYTES ? { status: "pass", label: "Free space", detail: `${gib} GiB` } : { status: "warn", label: "Free space", detail: `only ${gib} GiB free; a clone + worktree may not fit` };
+}
+function checkRepo(repo) {
+  if (!repo.isGitRepo) {
+    return {
+      status: "fail",
+      label: "Repository",
+      detail: `${repo.path} is not a git repository${repo.detail ? ` (${repo.detail})` : ""}`
+    };
+  }
+  if (!repo.headResolves) {
+    return { status: "warn", label: "Repository", detail: `${repo.path}: no commits yet (base branch does not resolve)` };
+  }
+  return { status: "pass", label: "Repository", detail: `${repo.path} on ${repo.baseBranch ?? "(detached)"}` };
+}
+function checkTools(tools) {
+  const git = tools.git ? { status: "pass", label: "git", detail: "installed" } : { status: "fail", label: "git", detail: "not found; git is required to run a workflow" };
+  const finding = (present, label, missing) => present ? { status: "pass", label, detail: "available" } : { status: "warn", label, detail: missing };
+  return [
+    git,
+    finding(tools.sshKey, "SSH key", "no key or agent identity found; pushing over SSH will fail"),
+    finding(tools.claude, "Claude runtime", "not on PATH; the node will serve no agent stages"),
+    finding(tools.gh, "gh CLI", "not installed; ambient PR opening is unavailable"),
+    finding(tools.docker, "docker", "not present; container stages are unavailable")
+  ];
+}
+function asFinding(check) {
+  return check.status === "fail" ? { ...check, status: "warn" } : check;
+}
+function synthesise(checks) {
+  const fails = checks.filter((c) => c.status === "fail");
+  const warns = checks.filter((c) => c.status === "warn");
+  const list2 = (cs) => cs.map((c) => `${c.label.toLowerCase()} (${c.detail ?? "finding"})`).join("; ");
+  if (fails.length > 0) {
+    return `The floor is unsound: ${list2(fails)}. Fix ${fails.length === 1 ? "this" : "these"} before running a workflow here.`;
+  }
+  if (warns.length > 0) {
+    return `The floor is sound, with ${warns.length} early warning${warns.length === 1 ? "" : "s"}: ${list2(warns)}. ${warns.length === 1 ? "It does" : "These do"} not block a run, but ${warns.length === 1 ? "is" : "are"} worth addressing.`;
+  }
+  return "The floor is sound. Node, repo, and tools all check out - this host is ready to run a workflow.";
+}
+function worst(checks) {
+  if (checks.some((c) => c.status === "fail")) return "fail";
+  if (checks.some((c) => c.status === "warn")) return "warn";
+  return "pass";
+}
+function renderStage(index, total, verdict, out) {
+  const head = `[${index}/${total}] ${verdict.label}`;
+  const findings = verdict.checks.filter((c) => c.status !== "pass");
+  if (findings.length === 0) {
+    out(`${head} \u2713`);
+    return;
+  }
+  out(head);
+  for (const f of findings) out(`      \u2022 ${f.label}: ${f.detail ?? f.status}`);
+}
+async function runPreflight(inputs, deps = {}) {
+  const d = { ...defaultDeps2(), ...deps };
+  const repoPath = inputs.repoPath ?? process.cwd();
+  const total = PREFLIGHT_STAGES.length;
+  const runId = d.newRunId();
+  d.out("dahrk run preflight");
+  d.out("");
+  const host = await d.gatherHost(repoPath);
+  const probe2 = inputs.hubUrl ? await d.probeHub({
+    hubUrl: inputs.hubUrl,
+    ...inputs.token ? { enrolToken: inputs.token } : {},
+    runtimes: host.tools.claude ? ["claude-code"] : [],
+    ...inputs.clientVersion ? { clientVersion: inputs.clientVersion } : {}
+  }) : void 0;
+  const nodeChecks = [
+    checkNode(d.nodeVersion),
+    checkWorktreeRoot(host.worktreeRootWritable),
+    checkDiskSpace(host.freeDiskBytes),
+    asFinding(checkHub(inputs.hubUrl, probe2)),
+    ...inputs.token ? [asFinding(checkToken(true, inputs.hubUrl, probe2))] : []
+  ];
+  const repoChecks = [checkRepo(host.repo)];
+  const toolChecks = checkTools(host.tools);
+  const stageVerdicts = [
+    { label: PREFLIGHT_STAGES[0].label, status: worst(nodeChecks), checks: nodeChecks },
+    { label: PREFLIGHT_STAGES[1].label, status: worst(repoChecks), checks: repoChecks },
+    { label: PREFLIGHT_STAGES[2].label, status: worst(toolChecks), checks: toolChecks }
+  ];
+  stageVerdicts.forEach((v, i) => renderStage(i + 1, total, v, d.out));
+  const allChecks = [...nodeChecks, ...repoChecks, ...toolChecks];
+  const read = synthesise(allChecks);
+  renderStage(4, total, { label: PREFLIGHT_STAGES[3].label, status: "pass", checks: [] }, d.out);
+  renderStage(5, total, { label: PREFLIGHT_STAGES[4].label, status: "pass", checks: [] }, d.out);
+  const failed = allChecks.filter((c) => c.status === "fail").length;
+  const warned = allChecks.filter((c) => c.status === "warn").length;
+  const summary = failed > 0 ? `UNSOUND - ${failed} floor check${failed === 1 ? "" : "s"} failed${warned ? `, ${warned} finding${warned === 1 ? "" : "s"}` : ""}.` : warned > 0 ? `SOUND with ${warned} finding${warned === 1 ? "" : "s"}.` : "SOUND - all checks green.";
+  d.out("");
+  d.out(read);
+  d.out("");
+  d.out(summary);
+  d.out(`Full report: ${REPORT_BASE_URL}/${runId}`);
+  d.out("");
+  d.out("no Linear, no OAuth, no issue. just the machine and the engine.");
+  return failed > 0 ? 1 : 0;
+}
+var defaultDeps2 = () => ({
+  nodeVersion: process.versions.node,
+  probeHub,
+  gatherHost: gatherHostFacts,
+  newRunId: () => randomUUID2(),
+  out: (line) => void process.stdout.write(`${line}
+`)
+});
+function commandPresent(cmd) {
+  try {
+    execFileSync4("sh", ["-c", `command -v ${cmd}`], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function sshKeyPresent() {
+  try {
+    const dir = join7(homedir2(), ".ssh");
+    if (existsSync4(dir) && readdirSync3(dir).some((f) => f.endsWith(".pub"))) return true;
+  } catch {
+  }
+  try {
+    execFileSync4("ssh-add", ["-l"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function writable(dir) {
+  try {
+    accessSync(dir, fsConstants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function worktreeRoot(env) {
+  return env.DAHRK_WORKTREES_DIR ?? join7(env.DAHRK_STATE_DIR ?? join7(homedir2(), ".dahrk"), "worktrees");
+}
+function nearestExisting(dir) {
+  let cur = dir;
+  while (!existsSync4(cur)) {
+    const parent = join7(cur, "..");
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return cur;
+}
+function freeDiskBytes(dir) {
+  try {
+    const s = statfsSync(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();
+  try {
+    if (git(["rev-parse", "--is-inside-work-tree"]) !== "true") {
+      return { path: repoPath, isGitRepo: false, headResolves: false, detail: "not inside a work tree" };
+    }
+  } catch {
+    return { path: repoPath, isGitRepo: false, headResolves: false };
+  }
+  let headResolves = false;
+  let baseBranch;
+  try {
+    git(["rev-parse", "--verify", "HEAD"]);
+    headResolves = true;
+    baseBranch = git(["rev-parse", "--abbrev-ref", "HEAD"]) || void 0;
+  } catch {
+  }
+  return { path: repoPath, isGitRepo: true, headResolves, ...baseBranch ? { baseBranch } : {} };
+}
+function gatherHostFacts(repoPath) {
+  const root = worktreeRoot(process.env);
+  return {
+    worktreeRootWritable: writable(nearestExisting(root)),
+    freeDiskBytes: freeDiskBytes(root),
+    tools: {
+      git: commandPresent("git"),
+      sshKey: sshKeyPresent(),
+      claude: commandPresent("claude"),
+      gh: commandPresent("gh"),
+      docker: commandPresent("docker")
+    },
+    repo: probeRepo(repoPath)
+  };
+}
+
+// src/update.ts
+import { execFileSync as execFileSync5 } from "child_process";
+import { realpathSync } from "fs";
+var LATEST_URL = "https://registry.npmjs.org/dahrk-node/latest";
+var CHANNEL_COMMANDS = {
+  npm: "npm install -g dahrk-node@latest",
+  homebrew: "brew upgrade dahrkai/tap/dahrk",
+  curl: "curl -fsSL https://dahrk.ai/install.sh | sh"
+};
+function upgradeCommand(channel) {
+  switch (channel) {
+    case "npm":
+      return { argv: ["npm", "install", "-g", "dahrk-node@latest"], display: CHANNEL_COMMANDS.npm };
+    case "homebrew":
+      return { argv: ["brew", "upgrade", "dahrkai/tap/dahrk"], display: CHANNEL_COMMANDS.homebrew };
+    case "unknown":
+      return null;
+  }
+}
+function detectChannel(binPath) {
+  if (!binPath) return "unknown";
+  let resolved = binPath;
+  try {
+    resolved = realpathSync(binPath);
+  } catch {
+  }
+  if (/[\\/]node_modules[\\/]dahrk-node[\\/]/.test(resolved)) return "npm";
+  if (/[\\/](Cellar|homebrew)[\\/]/.test(resolved)) return "homebrew";
+  return "unknown";
+}
+function core(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim().replace(/^v/, ""));
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function isNewer(latest, current) {
+  const a = core(latest);
+  const b = core(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] > b[i]) return true;
+    if (a[i] < b[i]) return false;
+  }
+  return false;
+}
+function printChannelCommands(out) {
+  out(`  npm:      ${CHANNEL_COMMANDS.npm}`);
+  out(`  Homebrew: ${CHANNEL_COMMANDS.homebrew}`);
+  out(`  curl:     ${CHANNEL_COMMANDS.curl}`);
+}
+async function runUpdate(inputs, deps = {}) {
+  const d = { ...defaultDeps3(), ...deps };
+  const current = inputs.currentVersion;
+  d.out("dahrk update");
+  d.out("");
+  let latest;
+  try {
+    latest = await d.fetchLatest();
+  } catch (e) {
+    d.out(`Could not determine the latest version: ${e.message}`);
+    d.out(`You are on ${current}. See https://www.npmjs.com/package/dahrk-node for releases.`);
+    return 1;
+  }
+  if (!isNewer(latest, current)) {
+    d.out(`Already on the latest version (${current}).`);
+    return 0;
+  }
+  d.out(`Update available: ${current} -> ${latest}`);
+  const channel = detectChannel(d.binPath);
+  const cmd = upgradeCommand(channel);
+  if (inputs.check) {
+    d.out("");
+    if (cmd) {
+      d.out(`Run \`dahrk update\` to upgrade (${channel}: ${cmd.display}).`);
+    } else {
+      d.out("Run `dahrk update`, or upgrade with the command for your install channel:");
+      printChannelCommands(d.out);
+    }
+    return 0;
+  }
+  if (!cmd) {
+    d.out("");
+    d.out("Could not tell how this client was installed. Upgrade with the command for your channel:");
+    printChannelCommands(d.out);
+    return 0;
+  }
+  d.out("");
+  d.out(`Upgrading via ${channel}: ${cmd.display}`);
+  d.out("");
+  const code = d.runUpgrade(cmd.argv);
+  d.out("");
+  if (code === 0) {
+    d.out(`Upgraded to ${latest}. Restart a running node (\`dahrk start\`) to pick it up.`);
+  } else {
+    d.out(`Upgrade exited with code ${code}. Run it yourself to see the error: ${cmd.display}`);
+  }
+  return code;
+}
+async function fetchLatestVersion() {
+  const res = await fetch(LATEST_URL, { headers: { accept: "application/json" } });
+  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");
+  return body.version;
+}
+function spawnUpgrade(argv) {
+  const [cmd, ...args] = argv;
+  try {
+    execFileSync5(cmd, args, { stdio: "inherit" });
+    return 0;
+  } catch (e) {
+    const status = e.status;
+    return typeof status === "number" ? status : 1;
+  }
+}
+var defaultDeps3 = () => ({
+  binPath: process.argv[1],
+  fetchLatest: fetchLatestVersion,
+  runUpgrade: spawnUpgrade,
+  out: (line) => void process.stdout.write(`${line}
+`)
+});
+
 // src/main.ts
-var CLIENT_VERSION = "0.1.2";
+var CLIENT_VERSION = "0.1.4";
 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"];
 var isRuntime = (r) => RUNTIMES.includes(r);
 function stateDir(env) {
-  return env.DAHRK_STATE_DIR ?? join7(homedir2(), ".dahrk");
+  return env.DAHRK_STATE_DIR ?? join8(homedir3(), ".dahrk");
 }
 function legacyStateDir(env) {
-  return env.DAHRK_STATE_DIR ? void 0 : join7(homedir2(), ".skakel");
+  return env.DAHRK_STATE_DIR ? void 0 : join8(homedir3(), ".skakel");
 }
 function readNodeId(file) {
-  if (!existsSync4(file)) return void 0;
+  if (!existsSync5(file)) return void 0;
   try {
     const parsed = JSON.parse(readFileSync5(file, "utf8"));
     if (typeof parsed.nodeId === "string" && parsed.nodeId) return parsed.nodeId;
@@ -2986,17 +3520,17 @@ function readNodeId(file) {
 }
 function resolveNodeId(env, opts = {}) {
   if (env.DAHRK_NODE_ID) return env.DAHRK_NODE_ID;
-  if (opts.ephemeral) return randomUUID2();
+  if (opts.ephemeral) return randomUUID3();
   const dir = stateDir(env);
-  const file = join7(dir, "node.json");
+  const file = join8(dir, "node.json");
   const existing = readNodeId(file);
   if (existing) return existing;
   const legacy = legacyStateDir(env);
   if (legacy) {
-    const legacyId = readNodeId(join7(legacy, "node.json"));
+    const legacyId = readNodeId(join8(legacy, "node.json"));
     if (legacyId) return legacyId;
   }
-  const nodeId = randomUUID2();
+  const nodeId = randomUUID3();
   try {
     mkdirSync6(dir, { recursive: true });
     writeFileSync6(file, `${JSON.stringify({ nodeId }, null, 2)}
@@ -3078,6 +3612,24 @@ async function start(flags) {
   const resolved = { nodeId, runtimes, clientVersion: CLIENT_VERSION };
   await startEdgeNode(buildEdgeOptions(env, resolved));
 }
+var KNOWN_WORKFLOWS = ["preflight"];
+async function runWorkflow(flags) {
+  if (flags.workflow !== "preflight") {
+    console.error(`unknown workflow: ${flags.workflow}
+`);
+    console.error(`Available workflows: ${KNOWN_WORKFLOWS.join(", ")}`);
+    return 2;
+  }
+  const env = applyEnvAliases(process.env);
+  const hubUrl = flags.hubUrl ?? env.DAHRK_HUB_URL;
+  const token = flags.token ?? env.DAHRK_ENROL_TOKEN;
+  return runPreflight({
+    ...flags.repo ? { repoPath: flags.repo } : {},
+    ...hubUrl ? { hubUrl } : {},
+    ...token ? { token } : {},
+    clientVersion: CLIENT_VERSION
+  });
+}
 async function main() {
   const invoked = basename(process.argv[1] ?? "");
   const bin = !invoked || invoked.startsWith("main.") ? "dahrk" : invoked;
@@ -3104,6 +3656,12 @@ async function main() {
       });
       break;
     }
+    case "run":
+      process.exitCode = await runWorkflow(parsed.flags);
+      break;
+    case "update":
+      process.exitCode = await runUpdate({ currentVersion: CLIENT_VERSION, check: parsed.flags.check });
+      break;
     case "start":
       await start(parsed.flags);
       break;
@@ -3113,7 +3671,7 @@ var invokedAsEntrypoint = (() => {
   const argv1 = process.argv[1];
   if (!argv1) return false;
   try {
-    return pathToFileURL(realpathSync(argv1)).href === import.meta.url;
+    return pathToFileURL(realpathSync2(argv1)).href === import.meta.url;
   } catch {
     return false;
   }
@@ -3126,6 +3684,7 @@ if (invokedAsEntrypoint) {
 }
 export {
   DEFAULT_HUB_URL,
+  KNOWN_WORKFLOWS,
   buildEdgeOptions,
   resolveNodeId,
   resolveRuntimes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dahrk-node",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",