dahrk-node 0.1.3 → 0.1.5

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 existsSync6, mkdirSync as mkdirSync7, readFileSync as readFileSync5, realpathSync as realpathSync3, writeFileSync as writeFileSync7 } from "fs";
+import { randomUUID as randomUUID3 } from "crypto";
+import { homedir as homedir4 } from "os";
+import { basename, join as join9 } from "path";
 import { pathToFileURL } from "url";
 
 // ../../packages/edge/src/ws-client.ts
@@ -22,11 +22,11 @@ function createMockRunner(runtime) {
   return {
     runtime,
     async runBatch(ctx, onTrace) {
-      const tool2 = ctx.config.tools?.[0] ?? "shell";
+      const tool3 = ctx.config.tools?.[0] ?? "shell";
       const toolUseId = "mock-tool-1";
       const events = [
         { seq: 0, runtime, type: "thought", ts: nowIso(), text: "mock: planning the stage" },
-        { seq: 1, runtime, type: "action", ts: nowIso(), tool: tool2, toolUseId, input: { note: "mock action" } },
+        { seq: 1, runtime, type: "action", ts: nowIso(), tool: tool3, toolUseId, input: { note: "mock action" } },
         { seq: 2, runtime, type: "observation", ts: nowIso(), toolUseId, output: { ok: true } },
         { seq: 3, runtime, type: "response", ts: nowIso(), text: "mock: stage complete" }
       ];
@@ -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" });
@@ -371,6 +371,47 @@ function raceNextTurn(pending, idleMs, signal) {
     );
   });
 }
+function createElicitTurnRouter(turns, opts) {
+  const conversation = new ManagedMailbox();
+  const ref = { settle: null };
+  void (async () => {
+    try {
+      for await (const t of turns) {
+        const settle = ref.settle;
+        if (settle) settle({ kind: "reply", text: t.text });
+        else conversation.push(t);
+      }
+    } finally {
+      conversation.end();
+      const settle = ref.settle;
+      if (settle) settle({ kind: "cancel" });
+    }
+  })();
+  const ask = (firstReply, onRaise) => {
+    if (ref.settle) return Promise.resolve({ kind: "busy" });
+    onRaise();
+    return new Promise((resolve2) => {
+      let settled = false;
+      const finish = (o) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        opts.signal.removeEventListener("abort", onAbort);
+        ref.settle = null;
+        resolve2(o);
+      };
+      const onAbort = () => finish({ kind: "cancel" });
+      const timer = setTimeout(() => finish({ kind: "noreply" }), firstReply ? opts.firstReplyMs : opts.idleMs);
+      if (opts.signal.aborted) {
+        finish({ kind: "cancel" });
+        return;
+      }
+      opts.signal.addEventListener("abort", onAbort, { once: true });
+      ref.settle = finish;
+    });
+  };
+  return { conversation, ask };
+}
 
 // ../../packages/executor-worktree/src/stage-complete-tool.ts
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
@@ -401,6 +442,52 @@ function createStageCompleteTool() {
   };
 }
 
+// ../../packages/executor-worktree/src/ask-user-question-tool.ts
+import { createSdkMcpServer as createSdkMcpServer2, tool as tool2 } from "@anthropic-ai/claude-agent-sdk";
+import { z as z2 } from "zod";
+var ASK_USER_QUESTION_TOOL_NAME = "mcp__ask__ask_user_question";
+var ASK_USER_QUESTION_ALIAS = "AskUserQuestion";
+var optionSchema = z2.object({
+  label: z2.string(),
+  description: z2.string().optional().default(""),
+  preview: z2.string().optional()
+});
+var questionSchema = z2.object({
+  question: z2.string(),
+  header: z2.string().optional().default(""),
+  options: z2.array(optionSchema).min(1),
+  multiSelect: z2.boolean().optional()
+});
+function toElicitQuestion(q) {
+  const options = q.options.map((o) => ({ label: o.label, value: o.label }));
+  const described = q.options.filter((o) => (o.description ?? "").trim());
+  const lines = described.map((o) => `- ${o.label}: ${(o.description ?? "").trim()}`);
+  const prompt = lines.length ? `${q.question}
+
+${lines.join("\n")}` : q.question;
+  return { prompt, options, ...q.multiSelect ? { multiSelect: true } : {} };
+}
+function createAskUserQuestionTool(deps) {
+  const askTool = tool2(
+    "ask_user_question",
+    "Ask the human a structured multiple-choice question and wait for their selection. Use this when you need the human to choose between options before you can continue.",
+    { questions: z2.array(questionSchema).min(1) },
+    async (args) => {
+      const first = args.questions[0];
+      const question = toElicitQuestion(first);
+      const prompt = args.questions.length > 1 ? `${question.prompt}
+
+(Note: ${args.questions.length} questions were asked at once; answer this one first, then ask the rest.)` : question.prompt;
+      const text = await deps.ask({ ...question, prompt });
+      return { content: [{ type: "text", text }] };
+    }
+  );
+  return {
+    server: createSdkMcpServer2({ name: "ask", version: "0.0.0", tools: [askTool] }),
+    allowedToolName: ASK_USER_QUESTION_TOOL_NAME
+  };
+}
+
 // ../../packages/executor-worktree/src/claude-adapter.ts
 var COALESCE_MS = Number(process.env.DAHRK_COALESCE_MS ?? process.env.SKAKEL_COALESCE_MS ?? 40);
 var MAX_TURNS = Number(process.env.DAHRK_MAX_TURNS ?? process.env.SKAKEL_MAX_TURNS ?? 64);
@@ -412,6 +499,17 @@ 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 };
+};
+var interactiveCanUseTool = (summarising, stageAllowedToolName, ctx, toolName, input) => summarising && toolName !== stageAllowedToolName ? Promise.resolve({
+  behavior: "deny",
+  message: "Summarise from the work you just did; reply with the sentence only, no tools."
+}) : policyCanUseTool(ctx, toolName, input);
 function buildBrokeredMcpServers(ctx) {
   const servers = ctx.config.mcpServers;
   if (!servers || servers.length === 0 || !ctx.mcpProxyBaseUrl) return void 0;
@@ -477,7 +575,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";
@@ -500,6 +598,27 @@ function createClaudeRunner() {
     async runInteractive(ctx, turns, onTrace) {
       const emit = makeEmit("claude-code", onTrace);
       const stageTool = createStageCompleteTool();
+      const { firstReplyMs, idleMs } = interactiveIdleWindows(ctx);
+      let awaitingFirstReply = true;
+      const router = createElicitTurnRouter(turns, { signal: abortController.signal, firstReplyMs, idleMs });
+      const askTool = createAskUserQuestionTool({
+        ask: async (question) => {
+          const outcome = await router.ask(awaitingFirstReply, () => {
+            emit({ type: "elicitation", prompt: question.prompt, signal: "select", options: question.options });
+            ctx.emitElicit?.(question);
+          });
+          switch (outcome.kind) {
+            case "reply":
+              return `The user selected: ${outcome.text}`;
+            case "busy":
+              return "Only one question can be asked at a time; wait for the current one to be answered, then ask again.";
+            case "noreply":
+              return "No response from the user; proceed with your best judgement.";
+            case "cancel":
+              return "The question was cancelled.";
+          }
+        }
+      });
       const brokered = buildBrokeredMcpServers(ctx);
       let summarising = false;
       const options = {
@@ -507,12 +626,17 @@ function createClaudeRunner() {
         // Keep the cwd-anchoring preset; fold the stage instruction in via `append` so the
         // interactive persona still gets it without losing the working-directory context.
         systemPrompt: hasSystemPrompt(ctx) ? { type: "preset", preset: "claude_code", append: resolveStagePrompt(ctx) } : CLAUDE_CODE_SYSTEM_PROMPT,
-        // Inject the stage-complete exit tool alongside any brokered MCP servers (parity with batch).
-        mcpServers: { dahrk: stageTool.server, ...brokered ?? {} },
-        // 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 },
+        // Inject the stage-complete exit tool and the AskUserQuestion shadow alongside any brokered
+        // MCP servers (parity with batch).
+        mcpServers: { dahrk: stageTool.server, ask: askTool.server, ...brokered ?? {} },
+        // Redirect the built-in AskUserQuestion to the shadow tool so a structured question surfaces
+        // as a Linear elicitation. The redirect is name-only and single-hop; the tool still runs, so
+        // this is mapping, not gating (DHK-344 / DHK-223).
+        toolAliases: { [ASK_USER_QUESTION_ALIAS]: askTool.allowedToolName },
+        // Auto-approve the injected tools; `allowedTools` is an auto-approve list, not a whitelist, so
+        // it does not restrict the other tools canUseTool allows.
+        allowedTools: [stageTool.allowedToolName, askTool.allowedToolName],
+        canUseTool: async (toolName, input) => interactiveCanUseTool(summarising, stageTool.allowedToolName, ctx, toolName, input),
         maxTurns: MAX_TURNS,
         includePartialMessages: false
       };
@@ -522,7 +646,7 @@ function createClaudeRunner() {
       const q = query({ prompt: mailbox, options });
       active = q;
       const it = q[Symbol.asyncIterator]();
-      const humanIter = turns[Symbol.asyncIterator]();
+      const humanIter = router.conversation[Symbol.asyncIterator]();
       const state = newBufferState();
       const consumeTurn = async () => {
         for (; ; ) {
@@ -532,8 +656,6 @@ function createClaudeRunner() {
           if (res.isResult) return res.responseText;
         }
       };
-      const { firstReplyMs, idleMs } = interactiveIdleWindows(ctx);
-      let awaitingFirstReply = true;
       let exited = null;
       let pending = humanIter.next();
       try {
@@ -1214,6 +1336,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;
@@ -1222,8 +1345,11 @@ function sanitizeBranchName(name) {
   if (!name) return name;
   return name.replace(/[`~^:?*[\]\\@{}\s]/g, "-").replace(/\.{2,}/g, ".").replace(/\/{2,}/g, "/").replace(/\.lock(\/|$)/g, "$1").replace(/^[.\-/]+/, "").replace(/[.\-/]+$/, "").replace(/-{2,}/g, "-");
 }
+function resolveWorktreesDir(override) {
+  return override ?? process.env.DAHRK_WORKTREES_DIR ?? process.env.SKAKEL_WORKTREES_DIR ?? join2(homedir(), ".dahrk", "worktrees");
+}
 function createGitService(opts = {}) {
-  const worktreesDir = opts.worktreesDir ?? process.env.DAHRK_WORKTREES_DIR ?? process.env.SKAKEL_WORKTREES_DIR ?? join2(homedir(), ".dahrk", "worktrees");
+  const worktreesDir = resolveWorktreesDir(opts.worktreesDir);
   const mirrorsDir = opts.mirrorsDir ?? process.env.DAHRK_MIRRORS_DIR ?? process.env.SKAKEL_MIRRORS_DIR ?? join2(homedir(), ".dahrk", "mirrors");
   const authorName = opts.authorName ?? process.env.DAHRK_GIT_AUTHOR_NAME ?? "Dahrk";
   const authorEmail = opts.authorEmail ?? process.env.DAHRK_GIT_AUTHOR_EMAIL ?? "noreply@dahrk.ai";
@@ -1255,24 +1381,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) {
@@ -1327,6 +1452,7 @@ function createGitService(opts = {}) {
     scratchPath: join2(worktreePath, ".skakel", "scratch")
   });
   return {
+    worktreesDir,
     async createWorktree(spec) {
       const { repoId, gitUrl, baseBranch, runId } = spec;
       const branchName = sanitizeBranchName(spec.branch ?? `dahrk/${runId}`);
@@ -1394,6 +1520,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",
@@ -1650,12 +1781,12 @@ function evaluatePolicies(event, rules) {
   }
   return ALLOW;
 }
-function denyToolRule(tool2) {
+function denyToolRule(tool3) {
   return {
     name: "deny_tool",
     evaluate(event) {
-      if (event.kind === "action" && event.tool === tool2) {
-        return { verdict: "deny", policy: "deny_tool", reason: `tool "${tool2}" is denied` };
+      if (event.kind === "action" && event.tool === tool3) {
+        return { verdict: "deny", policy: "deny_tool", reason: `tool "${tool3}" is denied` };
       }
       return null;
     }
@@ -1667,7 +1798,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
@@ -1736,7 +1867,15 @@ function buildRules(policies, ctx) {
   const rules = [];
   let stageToolCalls = 0;
   for (const p of policies) {
-    if ("write_scope" in p) {
+    if ("read_only" in p && p.read_only) {
+      rules.push({
+        name: "read_only",
+        evaluate(event) {
+          if (event.kind !== "action" || !WRITE_TOOLS.has(event.tool)) return null;
+          return { verdict: "deny", policy: "read_only", reason: `read-only stage: "${event.tool}" is not permitted` };
+        }
+      });
+    } else if ("write_scope" in p) {
       const { branches, repos } = p.write_scope;
       rules.push({
         name: "write_scope",
@@ -1841,11 +1980,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 +2072,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 +2135,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 +2235,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 +2374,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 = (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 {
+          authorisedActions.push(actionKey(tool3, 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 +2445,18 @@ 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,
+        // 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;
@@ -2364,6 +2560,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 +2650,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 +2686,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?.();
     })
   };
@@ -2478,6 +2702,9 @@ async function startEdgeNode(opts) {
     ...opts.tenantId ? { tenantId: opts.tenantId } : {},
     rules,
     sendProgress: (progress) => send({ type: "progress", progress }),
+    // DHK-344: relay a mid-interactive-stage AskUserQuestion to the hub as an `elicit` frame; the hub
+    // raises the Linear elicitation and the human's pick returns on the existing `turn` frame.
+    sendElicit: (frame) => send({ type: "elicit", ...frame }),
     trace,
     ...opts.retention ? { retention: opts.retention } : {}
   };
@@ -2489,18 +2716,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 +2748,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 +2782,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 {
@@ -2586,15 +2824,23 @@ async function startEdgeNode(opts) {
         ...opts.name ? { name: opts.name } : {},
         os: osPlatform(),
         arch: osArch(),
-        clientVersion: opts.clientVersion ?? "0.0.0"
+        clientVersion: opts.clientVersion ?? "0.0.0",
+        // Advertise the resolved worktree base so the hub records each run's real worktree location in
+        // the projection instead of an advisory placeholder. Single-sourced from the git service so it
+        // always matches where worktrees actually land.
+        worktreesDir: gitService.worktreesDir
       });
       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 +2849,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 +2887,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 +2934,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 +2946,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 +3009,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", "service", "doctor", "update"]);
 var isCommand = (s) => COMMANDS.has(s);
 function parseCli(argv) {
   const [first, ...rest] = argv;
@@ -2769,6 +3027,9 @@ function parseCli(argv) {
     command = first;
     flagArgs = rest;
   }
+  if (command === "run") return parseRun(flagArgs);
+  if (command === "service") return parseService(flagArgs);
+  if (command === "update") return parseUpdate(flagArgs);
   let values;
   try {
     ({ values } = parseArgs({
@@ -2794,6 +3055,93 @@ 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 };
+}
+var SERVICE_ACTIONS = /* @__PURE__ */ new Set(["install", "uninstall"]);
+var isServiceAction = (s) => SERVICE_ACTIONS.has(s);
+function parseService(flagArgs) {
+  let values;
+  let positionals;
+  try {
+    ({ values, positionals } = parseArgs({
+      args: flagArgs,
+      options: {
+        token: { type: "string" },
+        name: { 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: "service" };
+  if (positionals.length === 0) {
+    return { kind: "error", message: "service: missing action (`dahrk service install` or `uninstall`)" };
+  }
+  if (positionals.length > 1) {
+    return { kind: "error", message: `service: unexpected argument "${positionals[1]}" (one action at a time)` };
+  }
+  const action = positionals[0];
+  if (!isServiceAction(action)) {
+    return { kind: "error", message: `service: unknown action "${action}" (expected install or uninstall)` };
+  }
+  const flags = {
+    action,
+    ...values.token ? { token: values.token } : {},
+    ...values.name ? { name: values.name } : {},
+    ...values["hub-url"] ? { hubUrl: values["hub-url"] } : {}
+  };
+  return { kind: "service", 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 +3156,40 @@ 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 === "service") {
+    return [
+      `Usage: ${bin} service install|uninstall [options]`,
+      "",
+      "Install (or remove) the node as an always-on service that starts on boot and restarts on",
+      "failure - a launchd LaunchAgent on macOS, a systemd user service on Linux. No pm2, no root.",
+      "The node id persisted at ~/.dahrk/node.json means it re-attaches as the same node across reboots.",
+      "",
+      "Actions:",
+      "  install      Generate and register the service, then start it.",
+      "  uninstall    Stop, deregister, and remove the service.",
+      "",
+      "Options (install; baked into the service, uninstall ignores them):",
+      "  --token <token>    Enrolment token (required; 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 === "doctor") {
     return [
       `Usage: ${bin} doctor [options]`,
@@ -2819,12 +3201,27 @@ 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`.",
+    "  service   Install/uninstall the node as an always-on service (launchd/systemd).",
     "  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 +3360,607 @@ 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/service.ts
+import { execFileSync as execFileSync5 } from "child_process";
+import { 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";
+var LAUNCHD_LABEL = "ai.dahrk.node";
+var SYSTEMD_UNIT = "dahrk-node.service";
+function detectManager(plat) {
+  if (plat === "darwin") return "launchd";
+  if (plat === "linux") return "systemd";
+  return "unsupported";
+}
+function serviceEnv(inputs) {
+  return {
+    DAHRK_ENROL_TOKEN: inputs.token,
+    ...inputs.hubUrl ? { DAHRK_HUB_URL: inputs.hubUrl } : {},
+    ...inputs.name ? { DAHRK_NODE_NAME: inputs.name } : {},
+    ...inputs.pathEnv ? { PATH: inputs.pathEnv } : {}
+  };
+}
+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 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>
+    <string>${xmlEscape(v)}</string>`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${progArgs}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envEntries}
+  </dict>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(inputs.homeDir)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(join8(inputs.logDir, "node.out.log"))}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(join8(inputs.logDir, "node.err.log"))}</string>
+</dict>
+</plist>
+`;
+}
+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 env = serviceEnv(inputs);
+  const envLines = Object.entries(env).map(([k, v]) => `Environment=${k}=${systemdEnvValue(v)}`).join("\n");
+  return `[Unit]
+Description=Dahrk node (self-managed edge node)
+Documentation=https://dahrk.ai/docs
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${exec}
+${envLines}
+WorkingDirectory=${inputs.homeDir}
+Restart=on-failure
+RestartSec=3
+RestartPreventExitStatus=78
+
+[Install]
+WantedBy=default.target
+`;
+}
+function buildPlan(inputs) {
+  if (inputs.manager === "launchd") {
+    const filePath2 = join8(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.
+      installCommands: [
+        { argv: ["launchctl", "unload", filePath2], ignoreFailure: true },
+        { argv: ["launchctl", "load", "-w", filePath2] }
+      ],
+      uninstallCommands: [{ argv: ["launchctl", "unload", "-w", filePath2], ignoreFailure: true }],
+      logHint: `tail -f ${join8(inputs.logDir, "node.err.log")}`
+    };
+  }
+  const filePath = join8(inputs.homeDir, ".config", "systemd", "user", SYSTEMD_UNIT);
+  const user = userInfo().username;
+  return {
+    manager: "systemd",
+    label: SYSTEMD_UNIT,
+    filePath,
+    content: renderSystemdUnit(inputs),
+    // Reload to see the new unit, enable+start it, then enable linger so it survives logout / boots
+    // headless. Linger can be denied without privilege on some hosts, so it is best-effort.
+    installCommands: [
+      { argv: ["systemctl", "--user", "daemon-reload"] },
+      { argv: ["systemctl", "--user", "enable", "--now", SYSTEMD_UNIT] },
+      { argv: ["loginctl", "enable-linger", user], 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`
+  };
+}
+function printUnsupported(out) {
+  out("dahrk service is supported on macOS (launchd) and Linux (systemd) only.");
+  out("On other platforms, run the node under a process manager such as pm2 (see the README).");
+  return 1;
+}
+function runCommands(commands, d) {
+  for (const cmd of commands) {
+    const code = d.run(cmd.argv);
+    if (code !== 0 && !cmd.ignoreFailure) {
+      d.out(`  command failed (${code}): ${cmd.argv.join(" ")}`);
+      return code;
+    }
+  }
+  return 0;
+}
+async function runServiceInstall(inputs, deps = {}) {
+  const d = { ...defaultDeps3(), ...deps };
+  d.out("dahrk service install");
+  d.out("");
+  const manager = detectManager(d.platform);
+  if (manager === "unsupported") return printUnsupported(d.out);
+  if (!inputs.token) {
+    d.out("No enrolment token: pass --token <token> or set DAHRK_ENROL_TOKEN.");
+    d.out("Get one at https://app.dahrk.ai.");
+    return 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
+  });
+  try {
+    if (manager === "launchd") 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 1;
+  }
+  d.out(`Wrote ${plan.manager} service: ${plan.filePath}`);
+  const code = runCommands(plan.installCommands, d);
+  d.out("");
+  if (code !== 0) {
+    d.out(`The service file is in place but registering it failed (exit ${code}).`);
+    d.out("Fix the reported error and re-run `dahrk service install`, or load it yourself.");
+    return code;
+  }
+  d.out("Installed. The node will start on boot and restart on failure.");
+  d.out(`  logs:      ${plan.logHint}`);
+  d.out("  uninstall: dahrk service uninstall");
+  return 0;
+}
+async function runServiceUninstall(deps = {}) {
+  const d = { ...defaultDeps3(), ...deps };
+  d.out("dahrk service uninstall");
+  d.out("");
+  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 (${plan.filePath} not found). Nothing to do.`);
+    return 0;
+  }
+  runCommands(plan.uninstallCommands, d);
+  try {
+    d.removeFile(plan.filePath);
+  } catch (e) {
+    d.out(`Deregistered, but could not delete ${plan.filePath}: ${e.message}`);
+    return 1;
+  }
+  d.out(`Removed ${plan.filePath}. The node will no longer start on boot.`);
+  return 0;
+}
+function dirOf(path) {
+  const i = path.lastIndexOf("/");
+  return i <= 0 ? path : path.slice(0, i);
+}
+function resolveScriptPath() {
+  const argv1 = process.argv[1] ?? "";
+  try {
+    return realpathSync(argv1);
+  } catch {
+    return argv1;
+  }
+}
+var defaultDeps3 = () => ({
+  platform: osPlatform3(),
+  homeDir: homedir3(),
+  nodeBin: process.execPath,
+  scriptPath: resolveScriptPath(),
+  logDir: join8(process.env.DAHRK_STATE_DIR ?? join8(homedir3(), ".dahrk"), "logs"),
+  // 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 }),
+  writeFile: (path, content) => writeFileSync6(path, content),
+  removeFile: (path) => rmSync4(path, { force: true }),
+  fileExists: (path) => existsSync5(path),
+  run: (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;
+    }
+  },
+  out: (line) => void process.stdout.write(`${line}
+`)
+});
+
+// src/update.ts
+import { execFileSync as execFileSync6 } from "child_process";
+import { realpathSync as realpathSync2 } 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 = realpathSync2(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 = { ...defaultDeps4(), ...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 {
+    execFileSync6(cmd, args, { stdio: "inherit" });
+    return 0;
+  } catch (e) {
+    const status = e.status;
+    return typeof status === "number" ? status : 1;
+  }
+}
+var defaultDeps4 = () => ({
+  binPath: process.argv[1],
+  fetchLatest: fetchLatestVersion,
+  runUpgrade: spawnUpgrade,
+  out: (line) => void process.stdout.write(`${line}
+`)
+});
+
 // src/main.ts
-var CLIENT_VERSION = "0.1.3";
+var CLIENT_VERSION = "0.1.5";
 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 ?? join9(homedir4(), ".dahrk");
 }
 function legacyStateDir(env) {
-  return env.DAHRK_STATE_DIR ? void 0 : join7(homedir2(), ".skakel");
+  return env.DAHRK_STATE_DIR ? void 0 : join9(homedir4(), ".skakel");
 }
 function readNodeId(file) {
-  if (!existsSync4(file)) return void 0;
+  if (!existsSync6(file)) return void 0;
   try {
     const parsed = JSON.parse(readFileSync5(file, "utf8"));
     if (typeof parsed.nodeId === "string" && parsed.nodeId) return parsed.nodeId;
@@ -2986,20 +3970,20 @@ 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 = join9(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(join9(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)}
+    mkdirSync7(dir, { recursive: true });
+    writeFileSync7(file, `${JSON.stringify({ nodeId }, null, 2)}
 `);
   } catch (e) {
     console.warn(`could not persist node id to ${file}: ${e.message}`);
@@ -3078,6 +4062,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 +4106,28 @@ async function main() {
       });
       break;
     }
+    case "run":
+      process.exitCode = await runWorkflow(parsed.flags);
+      break;
+    case "service": {
+      if (parsed.flags.action === "uninstall") {
+        process.exitCode = await runServiceUninstall();
+        break;
+      }
+      const env = applyEnvAliases(process.env);
+      const token = parsed.flags.token ?? env.DAHRK_ENROL_TOKEN;
+      const name = parsed.flags.name ?? env.DAHRK_NODE_NAME;
+      const hubUrl = parsed.flags.hubUrl ?? env.DAHRK_HUB_URL;
+      process.exitCode = await runServiceInstall({
+        ...token ? { token } : {},
+        ...name ? { name } : {},
+        ...hubUrl ? { hubUrl } : {}
+      });
+      break;
+    }
+    case "update":
+      process.exitCode = await runUpdate({ currentVersion: CLIENT_VERSION, check: parsed.flags.check });
+      break;
     case "start":
       await start(parsed.flags);
       break;
@@ -3113,7 +4137,7 @@ var invokedAsEntrypoint = (() => {
   const argv1 = process.argv[1];
   if (!argv1) return false;
   try {
-    return pathToFileURL(realpathSync(argv1)).href === import.meta.url;
+    return pathToFileURL(realpathSync3(argv1)).href === import.meta.url;
   } catch {
     return false;
   }
@@ -3126,6 +4150,7 @@ if (invokedAsEntrypoint) {
 }
 export {
   DEFAULT_HUB_URL,
+  KNOWN_WORKFLOWS,
   buildEdgeOptions,
   resolveNodeId,
   resolveRuntimes