@cardor/agent-harness-kit 1.11.0 → 2.0.0

package/dist/cli.js

@@ -12,20 +12,20 @@ import {
   resolveGlobalStorageDir,
   resolveSqlitePath,
   resolveSqlitePathForScope
-} from "./chunk-6PEIJ2D5.js";
+} from "./chunk-JTACLEGM.js";
 
 // src/cli.ts
-import { Command } from "commander";
-import pc19 from "picocolors";
+import { Command, InvalidArgumentError } from "commander";
+import pc20 from "picocolors";
 
 // src/commands/build.ts
 import { watch } from "fs";
 import * as p from "@clack/prompts";
-import pc from "picocolors";
+import pc2 from "picocolors";
 
 // src/core/materializer/claude-code.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
-import { join as join5, resolve as resolve3 } from "path";
+import { existsSync as existsSync6 } from "fs";
+import { join as join7 } from "path";
 
 // src/utils/file.ts
 import { mkdirSync, writeFileSync } from "fs";
@@ -37,24 +37,76 @@ var write = (cwd2, relPath, content, mode) => {
 };
 
 // src/core/materializer/detect-package-manager.ts
-import { existsSync, readFileSync } from "fs";
-import { join as join2 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { join as join4 } from "path";
+
+// src/core/local-install-guard.ts
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { join as join3 } from "path";
+import pc from "picocolors";
+
+// src/core/package-data.ts
+import { existsSync } from "fs";
+import { createRequire } from "module";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+var require2 = createRequire(import.meta.url);
+var here = dirname(fileURLToPath(import.meta.url));
+var candidates = [join2(here, "..", "..", "package.json"), join2(here, "..", "package.json")];
+var pkgPath = candidates.find((p8) => existsSync(p8)) ?? candidates[0];
+var pkg = require2(pkgPath);
+
+// src/core/local-install-guard.ts
+function isLocalInstallSatisfied(cwd2) {
+  const selfPkgPath = join3(cwd2, "package.json");
+  let projectPkg = null;
+  if (existsSync2(selfPkgPath)) {
+    try {
+      const selfPkg = JSON.parse(readFileSync(selfPkgPath, "utf8"));
+      if (selfPkg?.name === pkg.name) return true;
+      projectPkg = selfPkg;
+    } catch {
+    }
+  }
+  const [scope, name] = pkg.name.split("/");
+  const localPath = pkg.name.startsWith("@") ? join3(cwd2, "node_modules", scope, name) : join3(cwd2, "node_modules", pkg.name);
+  if (existsSync2(localPath)) return true;
+  const isPnp = existsSync2(join3(cwd2, ".pnp.cjs")) || existsSync2(join3(cwd2, ".pnp.loader.mjs"));
+  if (isPnp && projectPkg) {
+    const deps = {
+      ...projectPkg.dependencies ?? {},
+      ...projectPkg.devDependencies ?? {}
+    };
+    if (Object.prototype.hasOwnProperty.call(deps, pkg.name)) return true;
+  }
+  return false;
+}
+function printLocalInstallWarning() {
+  console.error(pc.yellow(`\u26A0 ${pkg.name} is not installed locally in this project.`));
+  console.error(pc.dim("  This is only a recommendation for reproducibility: pinning a local"));
+  console.error(pc.dim("  version keeps behavior consistent across your team and CI, instead of"));
+  console.error(pc.dim("  drifting with whatever version is installed globally on each machine."));
+  console.error(pc.dim(`  Run: npm install --save-dev ${pkg.name}`));
+  console.error(pc.dim("  (or the equivalent for your package manager: pnpm add -D, yarn add --dev, bun add -d)"));
+}
+
+// src/core/materializer/detect-package-manager.ts
 function detectPackageManager(cwd2) {
   const fromField = detectFromPackageManagerField(cwd2);
   if (fromField) return fromField;
-  if (existsSync(join2(cwd2, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync(join2(cwd2, "bun.lockb")) || existsSync(join2(cwd2, "bun.lock"))) return "bun";
-  if (existsSync(join2(cwd2, "yarn.lock"))) {
-    return existsSync(join2(cwd2, ".yarnrc.yml")) ? "yarn-berry" : "yarn-classic";
+  if (existsSync3(join4(cwd2, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync3(join4(cwd2, "bun.lockb")) || existsSync3(join4(cwd2, "bun.lock"))) return "bun";
+  if (existsSync3(join4(cwd2, "yarn.lock"))) {
+    return existsSync3(join4(cwd2, ".yarnrc.yml")) ? "yarn-berry" : "yarn-classic";
   }
-  if (existsSync(join2(cwd2, "package-lock.json"))) return "npm";
+  if (existsSync3(join4(cwd2, "package-lock.json"))) return "npm";
   return "npm";
 }
 function detectFromPackageManagerField(cwd2) {
-  const pkgPath2 = join2(cwd2, "package.json");
-  if (!existsSync(pkgPath2)) return null;
+  const pkgPath2 = join4(cwd2, "package.json");
+  if (!existsSync3(pkgPath2)) return null;
   try {
-    const pkg2 = JSON.parse(readFileSync(pkgPath2, "utf8"));
+    const pkg2 = JSON.parse(readFileSync2(pkgPath2, "utf8"));
     const field = pkg2?.packageManager;
     if (typeof field !== "string" || !field.trim()) return null;
     const match = field.match(/^([a-z]+)@(\d+)/i);
@@ -78,8 +130,11 @@ function detectFromPackageManagerField(cwd2) {
     return null;
   }
 }
-function getMcpCommandParts(pm, port) {
+function getMcpCommandParts(pm, port, cwd2) {
   const portStr = String(port);
+  if (!isLocalInstallSatisfied(cwd2)) {
+    return ["ahk", "serve", "--port", portStr];
+  }
   switch (pm) {
     case "pnpm":
       return ["pnpm", "exec", "ahk", "serve", "--port", portStr];
@@ -95,21 +150,21 @@ function getMcpCommandParts(pm, port) {
 }
 
 // src/core/materializer/mcp-merge.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { dirname } from "path";
-function mergeClaudeMcpJson(filePath, port, pm = "npm") {
-  const folderPath = dirname(filePath);
-  if (!existsSync2(folderPath)) {
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2 } from "path";
+function mergeClaudeMcpJson(filePath, port, cwd2, pm = "npm") {
+  const folderPath = dirname2(filePath);
+  if (!existsSync4(folderPath)) {
     mkdirSync2(folderPath, { recursive: true });
   }
   let existing = {};
-  if (existsSync2(filePath)) {
+  if (existsSync4(filePath)) {
     try {
-      existing = JSON.parse(readFileSync2(filePath, "utf8"));
+      existing = JSON.parse(readFileSync3(filePath, "utf8"));
     } catch {
     }
   }
-  const [command, ...args] = getMcpCommandParts(pm, port);
+  const [command, ...args] = getMcpCommandParts(pm, port, cwd2);
   const merged = {
     ...existing,
     mcpServers: {
@@ -121,15 +176,15 @@ function mergeClaudeMcpJson(filePath, port, pm = "npm") {
       }
     }
   };
-  mkdirSync2(dirname(filePath), { recursive: true });
+  mkdirSync2(dirname2(filePath), { recursive: true });
   writeFileSync2(filePath, JSON.stringify(merged, null, 2) + "\n", "utf8");
 }
 function mergeClaudeSettingsJson(filePath) {
-  mkdirSync2(dirname(filePath), { recursive: true });
+  mkdirSync2(dirname2(filePath), { recursive: true });
   let existing = {};
-  if (existsSync2(filePath)) {
+  if (existsSync4(filePath)) {
     try {
-      existing = JSON.parse(readFileSync2(filePath, "utf8"));
+      existing = JSON.parse(readFileSync3(filePath, "utf8"));
     } catch {
     }
   }
@@ -232,11 +287,11 @@ var MCP_CLAUDE_PERMISSIONS = [
   ])
 ];
 function mergeClaudeSettingsLocalJson(filePath) {
-  mkdirSync2(dirname(filePath), { recursive: true });
+  mkdirSync2(dirname2(filePath), { recursive: true });
   let existing = {};
-  if (existsSync2(filePath)) {
+  if (existsSync4(filePath)) {
     try {
-      existing = JSON.parse(readFileSync2(filePath, "utf8"));
+      existing = JSON.parse(readFileSync3(filePath, "utf8"));
     } catch {
     }
   }
@@ -255,15 +310,15 @@ function mergeClaudeSettingsLocalJson(filePath) {
   };
   writeFileSync2(filePath, JSON.stringify(merged, null, 2) + "\n", "utf8");
 }
-function mergeOpencodeJson(filePath, port, pm = "npm") {
-  const folderPath = dirname(filePath);
-  if (!existsSync2(folderPath)) {
+function mergeOpencodeJson(filePath, port, cwd2, pm = "npm") {
+  const folderPath = dirname2(filePath);
+  if (!existsSync4(folderPath)) {
     mkdirSync2(folderPath, { recursive: true });
   }
   let existing = {};
-  if (existsSync2(filePath)) {
+  if (existsSync4(filePath)) {
     try {
-      existing = JSON.parse(readFileSync2(filePath, "utf8"));
+      existing = JSON.parse(readFileSync3(filePath, "utf8"));
     } catch {
     }
   }
@@ -280,7 +335,7 @@ function mergeOpencodeJson(filePath, port, pm = "npm") {
         type: "local",
         // OpenCode's mcp.<name>.command field is a single array (unlike
         // Claude/Codex, which split command/args) — pass the full token list.
-        command: getMcpCommandParts(pm, port)
+        command: getMcpCommandParts(pm, port, cwd2)
       }
     }
   };
@@ -310,13 +365,13 @@ function mergeTomlSection(content, sectionName, sectionBody) {
   ];
   return newLines.join("\n");
 }
-function mergeCodexConfigToml(filePath, port, pm = "npm") {
-  mkdirSync2(dirname(filePath), { recursive: true });
+function mergeCodexConfigToml(filePath, port, cwd2, pm = "npm") {
+  mkdirSync2(dirname2(filePath), { recursive: true });
   let content = "";
-  if (existsSync2(filePath)) {
-    content = readFileSync2(filePath, "utf8");
+  if (existsSync4(filePath)) {
+    content = readFileSync3(filePath, "utf8");
   }
-  const [command, ...args] = getMcpCommandParts(pm, port);
+  const [command, ...args] = getMcpCommandParts(pm, port, cwd2);
   const sectionBody = [
     `command = ${JSON.stringify(command)}`,
     `args = ${JSON.stringify(args)}`,
@@ -327,14 +382,15 @@ function mergeCodexConfigToml(filePath, port, pm = "npm") {
 }
 
 // src/core/materializer/scaffold-utils.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
-import { dirname as dirname3, join as join4, resolve as resolve2 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { createHash } from "crypto";
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname4, join as join6, resolve as resolve2 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
 
 // src/core/materializer/templates.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { dirname as dirname2, join as join3 } from "path";
-import { fileURLToPath } from "url";
+import { readFileSync as readFileSync4 } from "fs";
+import { dirname as dirname3, join as join5 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/core/materializer/agent-restrictions.ts
 var AGENT_RESTRICTIONS = {
@@ -366,10 +422,10 @@ function codexRestrictionNotice(agentName) {
 }
 
 // src/core/materializer/templates.ts
-var __dirname = dirname2(fileURLToPath(import.meta.url));
-var TEMPLATES_DIR = join3(__dirname, "agent-templates");
+var __dirname = dirname3(fileURLToPath2(import.meta.url));
+var TEMPLATES_DIR = join5(__dirname, "agent-templates");
 function loadAgentTemplate(name, vars = {}) {
-  const raw = readFileSync3(join3(TEMPLATES_DIR, `${name}.md`), "utf8");
+  const raw = readFileSync4(join5(TEMPLATES_DIR, `${name}.md`), "utf8");
   return raw.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`);
 }
 var HEALTH_SH = `#!/usr/bin/env bash
@@ -424,10 +480,10 @@ If it exits non-zero, stop and report the issue. Do not proceed with codebase ch
 The harness exposes tools via MCP server on port ${port}. Use these instead of reading files directly.
 
 \`\`\`
-actions.start        taskId agent                           \u2192 start an action, returns actionId
+actions.start        taskId agent                           \u2192 start an action, returns a numeric actionId
 actions.write        actionId section text                  \u2192 record a section (result, blockers, ...)
-actions.record_tool  actionId toolName [argsJson] [summary] \u2192 log a tool call to the Tools dashboard
-actions.record_file  actionId filePath operation [notes]   \u2192 log a file touch to the Files dashboard
+actions.record_tool  actionId calls[]                        \u2192 batch-log tool calls to the Tools dashboard (array, min 1)
+actions.record_file  actionId files[]                        \u2192 batch-log file touches to the Files dashboard (array, min 1)
 actions.complete     actionId summary                       \u2192 close the action
 actions.get          taskId                                 \u2192 full action history for a task
 tasks.add            title [slug] [description] [acceptance] \u2192 create a new task from natural language
@@ -447,9 +503,8 @@ docs.search          query                                  \u2192 search ${docs
    - tasks.get('pending') \u2192 pick lowest id
 
 2. WORK  (lead \u2192 explorer \u2192 consultant \u2192 builder \u2192 reviewer)
-   - Each agent calls actions.start(taskId, agentName) \u2192 actionId
-   - After EVERY tool call: actions.record_tool(actionId, toolName, args, summary)
-   - After EVERY file change: actions.record_file(actionId, filePath, operation, notes)
+   - Each agent calls actions.start(taskId, agentName) \u2192 numeric actionId
+   - Accumulate tool calls / file touches as you work; flush periodically (every few calls or at a phase boundary) via actions.record_tool(actionId, calls: [...]) and actions.record_file(actionId, files: [...]) \u2014 both are batch-only, even a single entry goes through as a one-element array
    - Closes with actions.complete(actionId, summary)
 
 3. CLOSE
@@ -508,10 +563,10 @@ If it exits non-zero, stop and report the issue. Do not proceed with codebase ch
 The harness exposes tools via MCP server on port ${port}. Use these instead of reading files directly.
 
 \`\`\`
-actions.start        taskId agent                           \u2192 start an action, returns actionId
+actions.start        taskId agent                           \u2192 start an action, returns a numeric actionId
 actions.write        actionId section text                  \u2192 record a section (result, blockers, ...)
-actions.record_tool  actionId toolName [argsJson] [summary] \u2192 log a tool call to the Tools dashboard
-actions.record_file  actionId filePath operation [notes]   \u2192 log a file touch to the Files dashboard
+actions.record_tool  actionId calls[]                        \u2192 batch-log tool calls to the Tools dashboard (array, min 1)
+actions.record_file  actionId files[]                        \u2192 batch-log file touches to the Files dashboard (array, min 1)
 actions.complete     actionId summary                       \u2192 close the action
 actions.get          taskId                                 \u2192 full action history for a task
 tasks.add            title [slug] [description] [acceptance] \u2192 create a new task from natural language
@@ -532,9 +587,8 @@ docs.search          query                                  \u2192 search ${docs
    - No pending tasks? \u2192 ask user, infer fields, call tasks.add, then tasks.claim
 
 2. WORK  (lead \u2192 explorer \u2192 consultant \u2192 builder \u2192 reviewer)
-   - Each agent calls actions.start(taskId, agentName) \u2192 actionId
-   - After EVERY tool call: actions.record_tool(actionId, toolName, args, summary)
-   - After EVERY file change: actions.record_file(actionId, filePath, operation, notes)
+   - Each agent calls actions.start(taskId, agentName) \u2192 numeric actionId
+   - Accumulate tool calls / file touches as you work; flush periodically (every few calls or at a phase boundary) via actions.record_tool(actionId, calls: [...]) and actions.record_file(actionId, files: [...]) \u2014 both are batch-only, even a single entry goes through as a one-element array
    - Closes with actions.complete(actionId, summary)
 
 3. CLOSE
@@ -692,9 +746,6 @@ function agentConsultant(vars) {
 function agentReviewer(vars) {
   return loadAgentTemplate("reviewer", vars);
 }
-function featureListJson(tasks) {
-  return JSON.stringify(tasks, null, 2) + "\n";
-}
 function stripFrontmatter(md) {
   const parts = md.split(/^---\s*$/m);
   if (parts.length < 3) return { description: "", body: md };
@@ -768,6 +819,13 @@ ${values.map((v4) => `  - ${v4}`).join("\n")}
 ${body}${block}---
 `);
 }
+function appendFrontmatterScalar(md, key, value) {
+  const block = `${key}: ${value}
+`;
+  return md.replace(/^---\n([\s\S]*?)^---\n/m, (_m, body) => `---
+${body}${block}---
+`);
+}
 function appendFrontmatterMapping(md, key, entries) {
   const keys = Object.keys(entries);
   if (keys.length === 0) return md;
@@ -778,9 +836,12 @@ ${keys.map((k) => `  ${k}: ${entries[k]}`).join("\n")}
 ${body}${block}---
 `);
 }
-function translateFrontmatterForClaudeCode(md, agentName) {
+function translateFrontmatterForClaudeCode(md, agentName, opts) {
   let result = stripFrontmatterBlockSequence(md, "tools");
   result = stripFrontmatterBlockSequence(result, "disallowedTools");
+  if (opts?.model && opts.model !== "inherit") {
+    result = appendFrontmatterScalar(result, "model", opts.model);
+  }
   return appendFrontmatterBlockSequence(result, "disallowedTools", claudeDisallowedTools(agentName));
 }
 function translateFrontmatterForOpenCode(md, agentName) {
@@ -797,10 +858,10 @@ var GITIGNORE_ENTRIES = `
 `;
 
 // src/core/materializer/scaffold-utils.ts
-var __dirname2 = dirname3(fileURLToPath2(import.meta.url));
+var __dirname2 = dirname4(fileURLToPath3(import.meta.url));
 function writeAgentFiles(cwd2, entries, opts = {}) {
   const result = { created: [], overwritten: [], preserved: [] };
-  const existing = entries.filter((e) => existsSync3(join4(cwd2, e.relPath)));
+  const existing = entries.filter((e) => existsSync5(join6(cwd2, e.relPath)));
   if (opts.force && existing.length > 0) {
     if (!opts.backupRoot) {
       throw new Error(
@@ -808,12 +869,12 @@ function writeAgentFiles(cwd2, entries, opts = {}) {
       );
     }
     const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    const backupDir = join4(opts.backupRoot, `agents-${stamp}`);
+    const backupDir = join6(opts.backupRoot, `agents-${stamp}`);
     try {
       for (const entry of existing) {
-        const dest = join4(backupDir, entry.relPath);
+        const dest = join6(backupDir, entry.relPath);
         mkdirSync3(resolve2(dest, ".."), { recursive: true });
-        writeFileSync3(dest, readFileSync4(join4(cwd2, entry.relPath), "utf8"), "utf8");
+        writeFileSync3(dest, readFileSync5(join6(cwd2, entry.relPath), "utf8"), "utf8");
       }
     } catch (err) {
       throw new Error(
@@ -823,8 +884,8 @@ function writeAgentFiles(cwd2, entries, opts = {}) {
     result.backupDir = backupDir;
   }
   for (const entry of entries) {
-    const abs = join4(cwd2, entry.relPath);
-    const exists = existsSync3(abs);
+    const abs = join6(cwd2, entry.relPath);
+    const exists = existsSync5(abs);
     if (exists && !opts.force) {
       result.preserved.push(entry.relPath);
       continue;
@@ -836,9 +897,106 @@ function writeAgentFiles(cwd2, entries, opts = {}) {
   }
   return result;
 }
+var GENERATED_MARKER_RE = /^([\s\S]*)\n<!-- ahk:generated ([0-9a-f]{64}) -->\n?$/;
+function bodyFingerprint(body) {
+  return createHash("sha256").update(body, "utf8").digest("hex");
+}
+function stampGenerated(body) {
+  return `${body}
+<!-- ahk:generated ${bodyFingerprint(body)} -->
+`;
+}
+function readStamp(fileContent) {
+  const m = GENERATED_MARKER_RE.exec(fileContent);
+  if (!m) return null;
+  return { body: m[1], hash: m[2] };
+}
+function reconcileGeneratedFiles(cwd2, entries, opts = {}) {
+  const result = {
+    created: [],
+    current: [],
+    propagated: [],
+    preserved: [],
+    overwritten: []
+  };
+  const plans = [];
+  const toBackup = [];
+  for (const entry of entries) {
+    const abs = join6(cwd2, entry.relPath);
+    if (!existsSync5(abs)) {
+      plans.push({ entry, action: "create" });
+      continue;
+    }
+    const onDisk = readFileSync5(abs, "utf8");
+    const stamp = readStamp(onDisk);
+    const onDiskBody = stamp ? stamp.body : onDisk;
+    if (onDiskBody === entry.content) {
+      plans.push({ entry, action: "current" });
+      continue;
+    }
+    if (stamp && stamp.hash === bodyFingerprint(stamp.body)) {
+      plans.push({ entry, action: "propagate" });
+      continue;
+    }
+    if (opts.force) {
+      plans.push({ entry, action: "overwrite" });
+      toBackup.push(entry);
+    } else {
+      plans.push({ entry, action: "preserve" });
+    }
+  }
+  if (toBackup.length > 0) {
+    if (!opts.backupRoot) {
+      throw new Error(
+        "reconcileGeneratedFiles: force is set and hand-edited generated files would be overwritten, but no backupRoot was provided. Refusing to overwrite without a backup."
+      );
+    }
+    const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    const backupDir = join6(opts.backupRoot, `derived-${stamp}`);
+    try {
+      for (const entry of toBackup) {
+        const dest = join6(backupDir, entry.relPath);
+        mkdirSync3(resolve2(dest, ".."), { recursive: true });
+        writeFileSync3(dest, readFileSync5(join6(cwd2, entry.relPath), "utf8"), "utf8");
+      }
+    } catch (err) {
+      throw new Error(
+        `Could not back up existing generated files to ${backupDir} (${err instanceof Error ? err.message : String(err)}). Aborting WITHOUT overwriting anything \u2014 no file was modified.`
+      );
+    }
+    result.backupDir = backupDir;
+  }
+  for (const { entry, action } of plans) {
+    const abs = join6(cwd2, entry.relPath);
+    switch (action) {
+      case "current":
+        result.current.push(entry.relPath);
+        break;
+      case "preserve":
+        result.preserved.push(entry.relPath);
+        break;
+      case "create":
+        mkdirSync3(resolve2(abs, ".."), { recursive: true });
+        writeFileSync3(abs, stampGenerated(entry.content), "utf8");
+        result.created.push(entry.relPath);
+        break;
+      case "propagate":
+        mkdirSync3(resolve2(abs, ".."), { recursive: true });
+        writeFileSync3(abs, stampGenerated(entry.content), "utf8");
+        result.propagated.push(entry.relPath);
+        break;
+      case "overwrite":
+        mkdirSync3(resolve2(abs, ".."), { recursive: true });
+        writeFileSync3(abs, stampGenerated(entry.content), "utf8");
+        result.overwritten.push(entry.relPath);
+        break;
+    }
+  }
+  return result;
+}
 function appendGitignore(cwd2) {
-  const giPath = join4(cwd2, ".gitignore");
-  const existing = existsSync3(giPath) ? readFileSync4(giPath, "utf8") : "";
+  const giPath = join6(cwd2, ".gitignore");
+  const existing = existsSync5(giPath) ? readFileSync5(giPath, "utf8") : "";
   const toAdd = GITIGNORE_ENTRIES.split("\n").filter((line) => line && !existing.includes(line)).join("\n");
   if (toAdd.trim()) {
     writeFileSync3(giPath, existing + (existing.endsWith("\n") ? "" : "\n") + toAdd + "\n", "utf8");
@@ -850,36 +1008,34 @@ function slugify(title) {
 function writeSkills(cwd2, skillsDir) {
   const skillNames = ["ahk-ask", "ahk-consultant", "ahk-triage", "ahk-review"];
   for (const skillName of skillNames) {
-    const src = join4(__dirname2, "skills", skillName, "SKILL.md");
-    const destDir = join4(cwd2, skillsDir, skillName);
-    const dest = join4(destDir, "SKILL.md");
+    const src = join6(__dirname2, "skills", skillName, "SKILL.md");
+    const destDir = join6(cwd2, skillsDir, skillName);
+    const dest = join6(destDir, "SKILL.md");
     mkdirSync3(destDir, { recursive: true });
-    writeFileSync3(dest, readFileSync4(src, "utf8"), "utf8");
+    writeFileSync3(dest, readFileSync5(src, "utf8"), "utf8");
   }
 }
 
 // src/core/materializer/claude-code.ts
-function claudeAgentFiles(config) {
+function claudeAgentFiles(config, modelsByRole) {
   const projectName = config.project.name;
   return [
-    { relPath: ".claude/agents/lead.md", content: translateFrontmatterForClaudeCode(agentLead({ projectName }), "lead") },
-    { relPath: ".claude/agents/explorer.md", content: translateFrontmatterForClaudeCode(agentExplorer({ projectName }), "explorer") },
-    { relPath: ".claude/agents/consultant.md", content: translateFrontmatterForClaudeCode(agentConsultant({ projectName }), "consultant") },
-    { relPath: ".claude/agents/builder.md", content: translateFrontmatterForClaudeCode(agentBuilder({ projectName }), "builder") },
-    { relPath: ".claude/agents/reviewer.md", content: translateFrontmatterForClaudeCode(agentReviewer({ projectName }), "reviewer") }
+    { relPath: ".claude/agents/lead.md", content: translateFrontmatterForClaudeCode(agentLead({ projectName }), "lead", { model: modelsByRole?.lead }) },
+    { relPath: ".claude/agents/explorer.md", content: translateFrontmatterForClaudeCode(agentExplorer({ projectName }), "explorer", { model: modelsByRole?.explorer }) },
+    { relPath: ".claude/agents/consultant.md", content: translateFrontmatterForClaudeCode(agentConsultant({ projectName }), "consultant", { model: modelsByRole?.consultant }) },
+    { relPath: ".claude/agents/builder.md", content: translateFrontmatterForClaudeCode(agentBuilder({ projectName }), "builder", { model: modelsByRole?.builder }) },
+    { relPath: ".claude/agents/reviewer.md", content: translateFrontmatterForClaudeCode(agentReviewer({ projectName }), "reviewer", { model: modelsByRole?.reviewer }) }
   ];
 }
 var ClaudeCodeMaterializer = class {
   async scaffold(config, opts) {
-    const { cwd: cwd2 } = opts;
-    write(cwd2, "AGENTS.md", agentsMd(config));
-    write(cwd2, "CLAUDE.md", claudeMd(config));
-    if (!existsSync4(join5(cwd2, "health.sh"))) {
+    const { cwd: cwd2, claudeAgentModels } = opts;
+    write(cwd2, "AGENTS.md", stampGenerated(agentsMd(config)));
+    write(cwd2, "CLAUDE.md", stampGenerated(claudeMd(config)));
+    if (!existsSync6(join7(cwd2, "health.sh"))) {
       write(cwd2, "health.sh", HEALTH_SH, 493);
     }
-    const tasks = opts.firstTask ? [{ slug: slugify(opts.firstTask.title), ...opts.firstTask }] : [];
-    write(cwd2, "feature_list.json", featureListJson(tasks));
-    if (config.storage.scope === "local" && !existsSync4(join5(cwd2, config.storage.markdownFallback.path))) {
+    if (config.storage.scope === "local" && !existsSync6(join7(cwd2, config.storage.markdownFallback.path))) {
       write(
         cwd2,
         config.storage.markdownFallback.path,
@@ -892,30 +1048,31 @@ No tasks in progress.
 `
       );
     }
-    writeAgentFiles(cwd2, claudeAgentFiles(config));
-    mergeClaudeMcpJson(join5(cwd2, ".mcp.json"), config.tools.mcp.port, detectPackageManager(cwd2));
-    mergeClaudeSettingsJson(join5(cwd2, ".claude/settings.json"));
-    mergeClaudeSettingsLocalJson(join5(cwd2, ".claude/settings.local.json"));
+    writeAgentFiles(cwd2, claudeAgentFiles(config, claudeAgentModels));
+    mergeClaudeMcpJson(join7(cwd2, ".mcp.json"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
+    mergeClaudeSettingsJson(join7(cwd2, ".claude/settings.json"));
+    mergeClaudeSettingsLocalJson(join7(cwd2, ".claude/settings.local.json"));
     appendGitignore(cwd2);
     writeSkills(cwd2, ".claude/skills");
   }
   async build(config, cwd2, opts = {}) {
-    const write2 = (relPath, content) => {
-      const abs = join5(cwd2, relPath);
-      mkdirSync4(resolve3(abs, ".."), { recursive: true });
-      writeFileSync4(abs, content, "utf8");
-    };
-    write2("AGENTS.md", agentsMd(config));
-    write2("CLAUDE.md", claudeMd(config));
+    const derived = reconcileGeneratedFiles(
+      cwd2,
+      [
+        { relPath: "AGENTS.md", content: agentsMd(config) },
+        { relPath: "CLAUDE.md", content: claudeMd(config) }
+      ],
+      { force: opts.force, backupRoot: join7(cwd2, config.storage.dir, "backups") }
+    );
     const agents = writeAgentFiles(cwd2, claudeAgentFiles(config), {
       force: opts.force,
-      backupRoot: join5(cwd2, config.storage.dir, "backups")
+      backupRoot: join7(cwd2, config.storage.dir, "backups")
     });
-    mergeClaudeMcpJson(join5(cwd2, ".mcp.json"), config.tools.mcp.port, detectPackageManager(cwd2));
-    mergeClaudeSettingsJson(join5(cwd2, ".claude/settings.json"));
-    mergeClaudeSettingsLocalJson(join5(cwd2, ".claude/settings.local.json"));
+    mergeClaudeMcpJson(join7(cwd2, ".mcp.json"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
+    mergeClaudeSettingsJson(join7(cwd2, ".claude/settings.json"));
+    mergeClaudeSettingsLocalJson(join7(cwd2, ".claude/settings.local.json"));
     writeSkills(cwd2, ".claude/skills");
-    return { agents };
+    return { agents, derived };
   }
   async migrate(config, _to, _cwd) {
     void config;
@@ -942,8 +1099,8 @@ No tasks in progress.
 };
 
 // src/core/materializer/codex-cli.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync5, writeFileSync as writeFileSync5 } from "fs";
-import { join as join6, resolve as resolve4 } from "path";
+import { existsSync as existsSync7, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
+import { join as join8, resolve as resolve3 } from "path";
 function codexAgentFiles(config) {
   const projectName = config.project.name;
   return [
@@ -959,17 +1116,15 @@ var CodexCliMaterializer = class {
   async scaffold(config, opts) {
     const { cwd: cwd2 } = opts;
     const write2 = (relPath, content, mode) => {
-      const abs = join6(cwd2, relPath);
-      mkdirSync5(resolve4(abs, ".."), { recursive: true });
-      writeFileSync5(abs, content, { encoding: "utf8", mode });
+      const abs = join8(cwd2, relPath);
+      mkdirSync4(resolve3(abs, ".."), { recursive: true });
+      writeFileSync4(abs, content, { encoding: "utf8", mode });
     };
-    write2("AGENTS.md", agentsMd(config));
-    if (!existsSync5(join6(cwd2, "health.sh"))) {
+    write2("AGENTS.md", stampGenerated(agentsMd(config)));
+    if (!existsSync7(join8(cwd2, "health.sh"))) {
       write2("health.sh", HEALTH_SH, 493);
     }
-    const tasks = opts.firstTask ? [{ slug: slugify(opts.firstTask.title), ...opts.firstTask }] : [];
-    write2(join6(config.storage.dir, "feature_list.json"), featureListJson(tasks));
-    if (config.storage.scope === "local" && !existsSync5(join6(cwd2, config.storage.markdownFallback.path))) {
+    if (config.storage.scope === "local" && !existsSync7(join8(cwd2, config.storage.markdownFallback.path))) {
       write2(
         config.storage.markdownFallback.path,
         `<!-- AUTO-GENERATED by agent-harness-kit \u2014 DO NOT EDIT MANUALLY -->
@@ -982,24 +1137,23 @@ No tasks in progress.
       );
     }
     writeAgentFiles(cwd2, codexAgentFiles(config));
-    mergeCodexConfigToml(join6(cwd2, ".codex/config.toml"), config.tools.mcp.port, detectPackageManager(cwd2));
+    mergeCodexConfigToml(join8(cwd2, ".codex/config.toml"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
     appendGitignore(cwd2);
     writeSkills(cwd2, ".agents/skills");
   }
   async build(config, cwd2, opts = {}) {
-    const write2 = (relPath, content) => {
-      const abs = join6(cwd2, relPath);
-      mkdirSync5(resolve4(abs, ".."), { recursive: true });
-      writeFileSync5(abs, content, "utf8");
-    };
-    write2("AGENTS.md", agentsMd(config));
+    const derived = reconcileGeneratedFiles(
+      cwd2,
+      [{ relPath: "AGENTS.md", content: agentsMd(config) }],
+      { force: opts.force, backupRoot: join8(cwd2, config.storage.dir, "backups") }
+    );
     const agents = writeAgentFiles(cwd2, codexAgentFiles(config), {
       force: opts.force,
-      backupRoot: join6(cwd2, config.storage.dir, "backups")
+      backupRoot: join8(cwd2, config.storage.dir, "backups")
     });
-    mergeCodexConfigToml(join6(cwd2, ".codex/config.toml"), config.tools.mcp.port, detectPackageManager(cwd2));
+    mergeCodexConfigToml(join8(cwd2, ".codex/config.toml"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
     writeSkills(cwd2, ".agents/skills");
-    return { agents };
+    return { agents, derived };
   }
   async migrate(config, _to, _cwd) {
     void config;
@@ -1010,8 +1164,8 @@ No tasks in progress.
 };
 
 // src/core/materializer/opencode.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync6, writeFileSync as writeFileSync6 } from "fs";
-import { join as join7, resolve as resolve5 } from "path";
+import { existsSync as existsSync8, mkdirSync as mkdirSync5, writeFileSync as writeFileSync5 } from "fs";
+import { join as join9, resolve as resolve4 } from "path";
 function opencodeAgentFiles(config) {
   const projectName = config.project.name;
   return [
@@ -1026,17 +1180,15 @@ var OpenCodeMaterializer = class {
   async scaffold(config, opts) {
     const { cwd: cwd2 } = opts;
     const write2 = (relPath, content, mode) => {
-      const abs = join7(cwd2, relPath);
-      mkdirSync6(resolve5(abs, ".."), { recursive: true });
-      writeFileSync6(abs, content, { encoding: "utf8", mode });
+      const abs = join9(cwd2, relPath);
+      mkdirSync5(resolve4(abs, ".."), { recursive: true });
+      writeFileSync5(abs, content, { encoding: "utf8", mode });
     };
-    write2("AGENTS.md", agentsMd(config));
-    if (!existsSync6(join7(cwd2, "health.sh"))) {
+    write2("AGENTS.md", stampGenerated(agentsMd(config)));
+    if (!existsSync8(join9(cwd2, "health.sh"))) {
       write2("health.sh", HEALTH_SH, 493);
     }
-    const tasks = opts.firstTask ? [{ slug: slugify(opts.firstTask.title), ...opts.firstTask }] : [];
-    write2(join7(config.storage.dir, "feature_list.json"), featureListJson(tasks));
-    if (config.storage.scope === "local" && !existsSync6(join7(cwd2, config.storage.markdownFallback.path))) {
+    if (config.storage.scope === "local" && !existsSync8(join9(cwd2, config.storage.markdownFallback.path))) {
       write2(
         config.storage.markdownFallback.path,
         `<!-- AUTO-GENERATED by agent-harness-kit \u2014 DO NOT EDIT MANUALLY -->
@@ -1049,24 +1201,23 @@ No tasks in progress.
       );
     }
     writeAgentFiles(cwd2, opencodeAgentFiles(config));
-    mergeOpencodeJson(join7(cwd2, "opencode.json"), config.tools.mcp.port, detectPackageManager(cwd2));
+    mergeOpencodeJson(join9(cwd2, "opencode.json"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
     appendGitignore(cwd2);
     writeSkills(cwd2, ".opencode/skills");
   }
   async build(config, cwd2, opts = {}) {
-    const write2 = (relPath, content) => {
-      const abs = join7(cwd2, relPath);
-      mkdirSync6(resolve5(abs, ".."), { recursive: true });
-      writeFileSync6(abs, content, "utf8");
-    };
-    write2("AGENTS.md", agentsMd(config));
+    const derived = reconcileGeneratedFiles(
+      cwd2,
+      [{ relPath: "AGENTS.md", content: agentsMd(config) }],
+      { force: opts.force, backupRoot: join9(cwd2, config.storage.dir, "backups") }
+    );
     const agents = writeAgentFiles(cwd2, opencodeAgentFiles(config), {
       force: opts.force,
-      backupRoot: join7(cwd2, config.storage.dir, "backups")
+      backupRoot: join9(cwd2, config.storage.dir, "backups")
     });
-    mergeOpencodeJson(join7(cwd2, "opencode.json"), config.tools.mcp.port, detectPackageManager(cwd2));
+    mergeOpencodeJson(join9(cwd2, "opencode.json"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
     writeSkills(cwd2, ".opencode/skills");
-    return { agents };
+    return { agents, derived };
   }
   async migrate(config, _to, _cwd) {
     void config;
@@ -1119,8 +1270,37 @@ async function buildOnce(cwd2, force) {
     spinner6.message("Rebuilding files...");
     const materializer = getMaterializer(config.provider);
     const report = await materializer.build(config, cwd2, { force });
-    spinner6.stop(pc.green("Build complete"));
-    p.log.success("AGENTS.md");
+    spinner6.stop(pc2.green("Build complete"));
+    const d = report.derived;
+    const upToDate = [...d.created, ...d.current, ...d.propagated];
+    if (upToDate.length > 0) {
+      p.log.success(upToDate.join(", "));
+    }
+    if (d.propagated.length > 0) {
+      p.log.info(`Propagated config changes to ${d.propagated.length} generated file(s):
+  ${d.propagated.join("\n  ")}`);
+    }
+    if (d.overwritten.length > 0) {
+      p.log.warn(
+        pc2.yellow(
+          `--force REGENERATED ${d.overwritten.length} hand-edited generated file(s), discarding your edits:
+  ` + d.overwritten.join("\n  ")
+        )
+      );
+      if (d.backupDir) {
+        p.log.info(pc2.yellow(`  Previous content backed up \u2192 ${d.backupDir}`));
+      }
+    }
+    if (d.preserved.length > 0) {
+      p.log.warn(
+        pc2.yellow(
+          `Left ${d.preserved.length} hand-edited generated file(s) UNTOUCHED \u2014 your edits are safe:
+  ` + d.preserved.join("\n  ") + `
+  These no longer match the current config. Re-run with --force to regenerate them
+  (this DESTROYS your edits; a backup is written first).`
+        )
+      );
+    }
     p.log.success(`Agent definitions (${config.provider})`);
     p.log.success("MCP config");
     const { created, overwritten, preserved, backupDir } = report.agents;
@@ -1130,13 +1310,13 @@ async function buildOnce(cwd2, force) {
     }
     if (overwritten.length > 0) {
       p.log.warn(
-        pc.yellow(
+        pc2.yellow(
           `--force REGENERATED ${overwritten.length} existing agent file(s), discarding any customizations:
   ` + overwritten.join("\n  ")
         )
       );
       if (backupDir) {
-        p.log.info(pc.yellow(`  Previous content backed up \u2192 ${backupDir}`));
+        p.log.info(pc2.yellow(`  Previous content backed up \u2192 ${backupDir}`));
       }
     }
     if (preserved.length > 0) {
@@ -1147,7 +1327,7 @@ async function buildOnce(cwd2, force) {
       );
     }
   } catch (err) {
-    spinner6.stop(pc.red("Build failed"));
+    spinner6.stop(pc2.red("Build failed"));
     p.log.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
@@ -1155,34 +1335,41 @@ async function buildOnce(cwd2, force) {
 
 // src/commands/dashboard.ts
 import { homedir } from "os";
-import { dirname as dirname4, join as join9 } from "path";
-import { fileURLToPath as fileURLToPath3 } from "url";
-import pc2 from "picocolors";
+import { dirname as dirname5, join as join11 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
+import pc3 from "picocolors";
 
 // src/core/dashboard-server.ts
 import { watch as watch2 } from "fs";
-import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
-import { extname, join as join8 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync6 } from "fs";
+import { extname, join as join10 } from "path";
 import { serve } from "@hono/node-server";
 import { Hono } from "hono";
 import { WebSocketServer } from "ws";
 
 // src/core/port-utils.ts
 import { createServer } from "net";
-function isPortFree(port) {
-  return new Promise((resolve12) => {
+var DASHBOARD_BIND_HOST = void 0;
+function isPortFree(port, host = DASHBOARD_BIND_HOST) {
+  return new Promise((resolve11) => {
     const server = createServer();
-    server.once("error", () => resolve12(false));
+    server.once("error", () => resolve11(false));
     server.once("listening", () => {
-      server.close(() => resolve12(true));
+      server.close(() => resolve11(true));
     });
-    server.listen(port, "127.0.0.1");
+    server.listen(port, host);
   });
 }
-async function findFreePort(start, maxAttempts = 10) {
+async function findFreePort(start, options = {}) {
+  const { maxAttempts = 10, host = DASHBOARD_BIND_HOST } = options;
+  if (typeof start !== "number" || !Number.isInteger(start)) {
+    throw new Error(
+      `findFreePort requires an integer port number, received ${typeof start} ${JSON.stringify(start)}. The port must be coerced to a number before it reaches here (commander supplies --port as a string).`
+    );
+  }
   for (let i = 0; i < maxAttempts; i++) {
     const port = start + i;
-    if (await isPortFree(port)) return port;
+    if (await isPortFree(port, host)) return port;
   }
   throw new Error(
     `Could not find a free port after ${maxAttempts} attempts (tried ${start}-${start + maxAttempts - 1}). Please free a port and try again.`
@@ -1204,12 +1391,42 @@ var MIME = {
   ".ttf": "font/ttf"
 };
 function fileResponse(filePath) {
-  const content = readFileSync5(filePath);
+  const content = readFileSync6(filePath);
   const mime = MIME[extname(filePath)] ?? "application/octet-stream";
   return new Response(content, {
     headers: { "Content-Type": mime, "Cache-Control": "no-cache" }
   });
 }
+function awaitServerListening(server, port) {
+  return new Promise((resolve11, reject) => {
+    const closeQuietly = () => {
+      try {
+        server.close(() => {
+        });
+      } catch {
+      }
+    };
+    const onError = (err) => {
+      server.off("listening", onListening);
+      closeQuietly();
+      if (err.code === "EADDRINUSE") {
+        reject(
+          new Error(
+            `Port ${port} was taken by another process while starting the dashboard. Please retry, or pick a different port with --port.`
+          )
+        );
+        return;
+      }
+      reject(new Error(`Failed to start the dashboard on port ${port}: ${err.message}`));
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve11();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+  });
+}
 async function startDashboardServer(db, dbPath, staticPath, port) {
   const app = new Hono();
   const { tasks, actions, stats } = db;
@@ -1310,21 +1527,29 @@ async function startDashboardServer(db, dbPath, staticPath, port) {
   app.get("/*", (c) => {
     const urlPath = c.req.path;
     if (urlPath !== "/") {
-      const candidate = join8(staticPath, urlPath);
-      if (existsSync7(candidate)) {
+      const candidate = join10(staticPath, urlPath);
+      if (existsSync9(candidate)) {
         try {
           return fileResponse(candidate);
         } catch {
         }
       }
     }
-    return fileResponse(join8(staticPath, "index.html"));
+    return fileResponse(join10(staticPath, "index.html"));
   });
-  const resolvedPort = await findFreePort(port);
+  const resolvedPort = await findFreePort(port, { host: DASHBOARD_BIND_HOST });
   if (resolvedPort !== port) {
     console.log(`Port ${port} in use, using ${resolvedPort}`);
   }
-  const httpServer = serve({ fetch: app.fetch, port: resolvedPort });
+  const httpServer = serve({
+    fetch: app.fetch,
+    port: resolvedPort,
+    hostname: DASHBOARD_BIND_HOST
+  });
+  await awaitServerListening(httpServer, resolvedPort);
+  httpServer.on("error", (err) => {
+    console.error(`Dashboard server error: ${err.message}`);
+  });
   const wss = new WebSocketServer({ noServer: true });
   httpServer.on("upgrade", (req, socket, head) => {
     if (req.url === "/ws") {
@@ -1349,7 +1574,7 @@ async function startDashboardServer(db, dbPath, staticPath, port) {
   let watcher = null;
   if (dbPath) {
     const walPath = `${dbPath}-wal`;
-    const watchTarget = existsSync7(walPath) ? walPath : dbPath;
+    const watchTarget = existsSync9(walPath) ? walPath : dbPath;
     watcher = watch2(watchTarget, broadcast);
   }
   return {
@@ -1364,16 +1589,16 @@ async function startDashboardServer(db, dbPath, staticPath, port) {
 }
 
 // src/commands/dashboard.ts
-var __dirname3 = dirname4(fileURLToPath3(import.meta.url));
+var __dirname3 = dirname5(fileURLToPath4(import.meta.url));
 async function runDashboard(cwd2, opts) {
   const config = await loadConfig(cwd2);
   const db = await openDB(config, cwd2);
   const dbPath = config.database.type === "sqlite" ? resolveSqlitePath(config, cwd2, homedir()) : null;
-  const staticPath = join9(__dirname3, "dashboard-dist");
+  const staticPath = join11(__dirname3, "dashboard-dist");
   const { url } = await startDashboardServer(db, dbPath, staticPath, opts.port);
-  console.log(pc2.green(`\u2713`) + ` Dashboard running at ${pc2.bold(pc2.cyan(url))}`);
-  console.log(pc2.dim(`  WebSocket live updates enabled`));
-  console.log(pc2.dim(`  Press Ctrl+C to stop`));
+  console.log(pc3.green(`\u2713`) + ` Dashboard running at ${pc3.bold(pc3.cyan(url))}`);
+  console.log(pc3.dim(`  WebSocket live updates enabled`));
+  console.log(pc3.dim(`  Press Ctrl+C to stop`));
   if (opts.open) {
     const { default: open } = await import("open");
     await open(url);
@@ -1386,25 +1611,12 @@ async function runDashboard(cwd2, opts) {
 }
 
 // src/commands/doctor.ts
-import pc3 from "picocolors";
+import pc4 from "picocolors";
 
 // src/core/doctor.ts
-import { existsSync as existsSync9, readFileSync as readFileSync6 } from "fs";
-import { dirname as dirname6, join as join11 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync7 } from "fs";
+import { dirname as dirname6, join as join12 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
-
-// src/core/package-data.ts
-import { existsSync as existsSync8 } from "fs";
-import { createRequire } from "module";
-import { dirname as dirname5, join as join10 } from "path";
-import { fileURLToPath as fileURLToPath4 } from "url";
-var require2 = createRequire(import.meta.url);
-var here = dirname5(fileURLToPath4(import.meta.url));
-var candidates = [join10(here, "..", "..", "package.json"), join10(here, "..", "package.json")];
-var pkgPath = candidates.find((p8) => existsSync8(p8)) ?? candidates[0];
-var pkg = require2(pkgPath);
-
-// src/core/doctor.ts
 var REGISTRY_URL = `https://registry.npmjs.org/${pkg.name}/latest`;
 var TIMEOUT_MS = 2e3;
 var LIB_VERSION_CACHE_TTL_MS = 5 * 60 * 1e3;
@@ -1458,13 +1670,13 @@ function getProviderAgentInfo(provider) {
 }
 function checkAgentFilesAtRoot(agentsRoot, ext) {
   return AGENT_NAMES.map((name) => {
-    const filePath = join11(agentsRoot, `${name}${ext}`);
-    return { name, status: existsSync9(filePath) ? "ok" : "missing" };
+    const filePath = join12(agentsRoot, `${name}${ext}`);
+    return { name, status: existsSync10(filePath) ? "ok" : "missing" };
   });
 }
 function checkAgentFiles(cwd2, provider) {
   const { agentsDir, ext } = getProviderAgentInfo(provider);
-  return checkAgentFilesAtRoot(join11(cwd2, agentsDir), ext);
+  return checkAgentFilesAtRoot(join12(cwd2, agentsDir), ext);
 }
 function getProviderSkillsDir(provider) {
   switch (provider) {
@@ -1479,16 +1691,16 @@ function getProviderSkillsDir(provider) {
   }
 }
 function checkSkillsAtRoot(skillsRoot) {
-  const skillSourceBase = join11(__dirname4, "skills");
+  const skillSourceBase = join12(__dirname4, "skills");
   return SKILL_NAMES.map((name) => {
-    const livePath = join11(skillsRoot, name, "SKILL.md");
-    const sourcePath = join11(skillSourceBase, name, "SKILL.md");
-    if (!existsSync9(livePath)) {
+    const livePath = join12(skillsRoot, name, "SKILL.md");
+    const sourcePath = join12(skillSourceBase, name, "SKILL.md");
+    if (!existsSync10(livePath)) {
       return { name, status: "missing" };
     }
     try {
-      const live = readFileSync6(livePath, "utf8");
-      const source = readFileSync6(sourcePath, "utf8");
+      const live = readFileSync7(livePath, "utf8");
+      const source = readFileSync7(sourcePath, "utf8");
       return { name, status: live === source ? "ok" : "outdated" };
     } catch {
       return { name, status: "outdated" };
@@ -1497,7 +1709,7 @@ function checkSkillsAtRoot(skillsRoot) {
 }
 function checkSkills(cwd2, provider) {
   const skillsDir = getProviderSkillsDir(provider);
-  return checkSkillsAtRoot(join11(cwd2, skillsDir));
+  return checkSkillsAtRoot(join12(cwd2, skillsDir));
 }
 async function getDoctorStatus(cwd2) {
   const lib = await checkLibVersion();
@@ -1519,16 +1731,16 @@ async function getDoctorStatus(cwd2) {
 
 // src/commands/doctor.ts
 function ok(label, detail) {
-  console.log(`  ${pc3.cyan(label.padEnd(16))}${pc3.green("[\u2713]")} ${detail}`);
+  console.log(`  ${pc4.cyan(label.padEnd(16))}${pc4.green("[\u2713]")} ${detail}`);
 }
 function warn(label, detail, hint) {
-  console.log(`  ${pc3.cyan(label.padEnd(16))}${pc3.yellow("[!]")} ${detail}`);
+  console.log(`  ${pc4.cyan(label.padEnd(16))}${pc4.yellow("[!]")} ${detail}`);
   if (hint) {
-    console.log(`  ${"".padEnd(16)}    ${pc3.dim(hint)}`);
+    console.log(`  ${"".padEnd(16)}    ${pc4.dim(hint)}`);
   }
 }
 function neutral(label, detail) {
-  console.log(`  ${pc3.cyan(label.padEnd(16))}${pc3.dim("[~]")} ${detail}`);
+  console.log(`  ${pc4.cyan(label.padEnd(16))}${pc4.dim("[~]")} ${detail}`);
 }
 function printLibSection(lib) {
   if (lib.latest === null) {
@@ -1580,7 +1792,7 @@ async function runDoctor(cwd2) {
     configFound = false;
   }
   console.log("");
-  console.log(pc3.bold(`\u25CF ahk doctor ` + "\u2500".repeat(44)));
+  console.log(pc4.bold(`\u25CF ahk doctor ` + "\u2500".repeat(44)));
   console.log("");
   const status = await getDoctorStatus(cwd2);
   printLibSection(status.lib);
@@ -1598,11 +1810,11 @@ async function runDoctor(cwd2) {
 }
 
 // src/commands/export.ts
-import { writeFileSync as writeFileSync7 } from "fs";
-import pc4 from "picocolors";
+import { writeFileSync as writeFileSync6 } from "fs";
+import pc5 from "picocolors";
 async function runExport(cwd2, opts) {
   if (!opts.sql && !opts.json) {
-    console.error(pc4.red("Specify --sql or --json"));
+    console.error(pc5.red("Specify --sql or --json"));
     process.exit(1);
   }
   const config = await loadConfig(cwd2);
@@ -1612,14 +1824,14 @@ async function runExport(cwd2, opts) {
       const data = await db.exportJson();
       const out = JSON.stringify(data, null, 2) + "\n";
       if (opts.output) {
-        writeFileSync7(opts.output, out, "utf8");
-        console.log(pc4.green(`\u2713 Exported JSON \u2192 ${opts.output}`));
+        writeFileSync6(opts.output, out, "utf8");
+        console.log(pc5.green(`\u2713 Exported JSON \u2192 ${opts.output}`));
       } else {
         process.stdout.write(out);
       }
     }
     if (opts.sql) {
-      console.error(pc4.dim("SQL dump requires direct SQLite access \u2014 use: sqlite3 .harness/harness.db .dump"));
+      console.error(pc5.dim("SQL dump requires direct SQLite access \u2014 use: sqlite3 .harness/harness.db .dump"));
       process.exit(1);
     }
   } finally {
@@ -1629,28 +1841,28 @@ async function runExport(cwd2, opts) {
 
 // src/commands/health.ts
 import { spawnSync } from "child_process";
-import { existsSync as existsSync10 } from "fs";
+import { existsSync as existsSync11 } from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join12, resolve as resolve6 } from "path";
-import pc5 from "picocolors";
+import { join as join13, resolve as resolve5 } from "path";
+import pc6 from "picocolors";
 function checkLine(label, ok3, message, indent = 0) {
-  const prefix = label ? pc5.cyan(`[${label}] `) : " ".repeat(indent);
-  const icon = ok3 ? pc5.green("\u2713") : pc5.red("\u2717");
-  console.log(prefix + icon + " " + (ok3 ? pc5.green(message) : pc5.red(message)));
+  const prefix = label ? pc6.cyan(`[${label}] `) : " ".repeat(indent);
+  const icon = ok3 ? pc6.green("\u2713") : pc6.red("\u2717");
+  console.log(prefix + icon + " " + (ok3 ? pc6.green(message) : pc6.red(message)));
 }
 async function runHealth(cwd2) {
   let config;
   try {
     config = await loadConfig(cwd2);
   } catch {
-    console.error(pc5.red("\u2717 No config found. Run: ahk init"));
+    console.error(pc6.red("\u2717 No config found. Run: ahk init"));
     process.exit(1);
   }
   let allOk = true;
   let dbOk;
   if (config.database.type === "sqlite") {
     const dbPath = resolveSqlitePath(config, cwd2, homedir2());
-    dbOk = existsSync10(dbPath);
+    dbOk = existsSync11(dbPath);
     checkLine("checking DB", dbOk, `${dbPath} reachable`);
   } else {
     dbOk = true;
@@ -1663,8 +1875,8 @@ async function runHealth(cwd2) {
   const agentsLabelWidth = "[checking agents] ".length;
   for (let i = 0; i < agentNames.length; i++) {
     const name = agentNames[i];
-    const agentPath = join12(cwd2, agentsDir, `${name}${providerFiles.agentExtension}`);
-    const ok3 = existsSync10(agentPath);
+    const agentPath = join13(cwd2, agentsDir, `${name}${providerFiles.agentExtension}`);
+    const ok3 = existsSync11(agentPath);
     checkLine(
       i === 0 ? "checking agents" : null,
       ok3,
@@ -1675,19 +1887,19 @@ async function runHealth(cwd2) {
   }
   if (config.tools.mcp.enabled) {
     const mcpFile = providerFiles.mcpFile;
-    const mcpPath = resolve6(cwd2, mcpFile);
-    const mcpOk = existsSync10(mcpPath);
+    const mcpPath = resolve5(cwd2, mcpFile);
+    const mcpOk = existsSync11(mcpPath);
     checkLine("checking MCP", mcpOk, `${mcpFile} valid`);
     if (!mcpOk) allOk = false;
   }
   if (!allOk) {
     console.log("");
-    console.error(pc5.red("\u2717 Harness checks failed \u2014 fix the above before running health.sh"));
+    console.error(pc6.red("\u2717 Harness checks failed \u2014 fix the above before running health.sh"));
     process.exit(1);
   }
-  const scriptPath = resolve6(cwd2, config.health.scriptPath);
-  if (!existsSync10(scriptPath)) {
-    console.error(pc5.red(`\u2717 health.sh not found: ${scriptPath}`));
+  const scriptPath = resolve5(cwd2, config.health.scriptPath);
+  if (!existsSync11(scriptPath)) {
+    console.error(pc6.red(`\u2717 health.sh not found: ${scriptPath}`));
     console.error("  Run ahk init first.");
     process.exit(1);
   }
@@ -1697,14 +1909,14 @@ async function runHealth(cwd2) {
     encoding: "utf8"
   });
   if (result.error) {
-    console.error(pc5.red(`\u2717 Failed to run health.sh: ${result.error.message}`));
+    console.error(pc6.red(`\u2717 Failed to run health.sh: ${result.error.message}`));
     process.exit(1);
   }
   if (result.status === 0) {
-    console.log(pc5.green("\u2713 Health check passed"));
+    console.log(pc6.green("\u2713 Health check passed"));
     process.exit(0);
   } else {
-    console.error(pc5.red(`\u2717 Health check failed (exit ${result.status ?? "unknown"})`));
+    console.error(pc6.red(`\u2717 Health check failed (exit ${result.status ?? "unknown"})`));
     process.exit(result.status ?? 1);
   }
 }
@@ -1722,7 +1934,7 @@ function getProviderHealthFiles(provider) {
 }
 
 // src/commands/init.ts
-import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync8 } from "fs";
+import { existsSync as existsSync13, mkdirSync as mkdirSync6, readFileSync as readFileSync9, writeFileSync as writeFileSync7 } from "fs";
 import { join as join15 } from "path";
 import * as p3 from "@clack/prompts";
 import pc8 from "picocolors";
@@ -1781,45 +1993,6 @@ import { randomUUID } from "crypto";
 import { existsSync as existsSync12, readFileSync as readFileSync8 } from "fs";
 import { join as join14 } from "path";
 import pc7 from "picocolors";
-
-// src/core/local-install-guard.ts
-import { existsSync as existsSync11, readFileSync as readFileSync7 } from "fs";
-import { join as join13 } from "path";
-import pc6 from "picocolors";
-function isLocalInstallSatisfied(cwd2) {
-  const selfPkgPath = join13(cwd2, "package.json");
-  let projectPkg = null;
-  if (existsSync11(selfPkgPath)) {
-    try {
-      const selfPkg = JSON.parse(readFileSync7(selfPkgPath, "utf8"));
-      if (selfPkg?.name === pkg.name) return true;
-      projectPkg = selfPkg;
-    } catch {
-    }
-  }
-  const [scope, name] = pkg.name.split("/");
-  const localPath = pkg.name.startsWith("@") ? join13(cwd2, "node_modules", scope, name) : join13(cwd2, "node_modules", pkg.name);
-  if (existsSync11(localPath)) return true;
-  const isPnp = existsSync11(join13(cwd2, ".pnp.cjs")) || existsSync11(join13(cwd2, ".pnp.loader.mjs"));
-  if (isPnp && projectPkg) {
-    const deps = {
-      ...projectPkg.dependencies ?? {},
-      ...projectPkg.devDependencies ?? {}
-    };
-    if (Object.prototype.hasOwnProperty.call(deps, pkg.name)) return true;
-  }
-  return false;
-}
-function printLocalInstallWarning() {
-  console.error(pc6.yellow(`\u26A0 ${pkg.name} is not installed locally in this project.`));
-  console.error(pc6.dim("  This is only a recommendation for reproducibility: pinning a local"));
-  console.error(pc6.dim("  version keeps behavior consistent across your team and CI, instead of"));
-  console.error(pc6.dim("  drifting with whatever version is installed globally on each machine."));
-  console.error(pc6.dim(`  Run: npm install --save-dev ${pkg.name}`));
-  console.error(pc6.dim("  (or the equivalent for your package manager: pnpm add -D, yarn add --dev, bun add -d)"));
-}
-
-// src/commands/init-helpers.ts
 function readProjectNameFromPackageJson(cwd2) {
   try {
     const pkgPath2 = join14(cwd2, "package.json");
@@ -1918,6 +2091,34 @@ function printWelcomeMessage(projectName) {
 }
 
 // src/commands/init.ts
+async function reconcileFeatureList(db, installDir, storageDir, firstTask) {
+  const featureListPath = join15(installDir, storageDir, "feature_list.json");
+  let existingSeeds = [];
+  let parseFailed = false;
+  if (existsSync13(featureListPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync9(featureListPath, "utf8"));
+      if (!Array.isArray(parsed)) throw new Error("feature_list.json is not a JSON array");
+      existingSeeds = parsed;
+    } catch {
+      parseFailed = true;
+    }
+  }
+  const firstTaskSeed = firstTask ? {
+    slug: slugify(firstTask.title),
+    title: firstTask.title,
+    description: firstTask.description,
+    acceptance: firstTask.acceptance
+  } : void 0;
+  if (parseFailed) {
+    if (firstTaskSeed) await db.syncFromFeatureList([firstTaskSeed]);
+  } else {
+    const seeds = firstTaskSeed ? [...existingSeeds, firstTaskSeed] : existingSeeds;
+    await db.syncFromFeatureList(seeds);
+    await db.writeFeatureList(installDir);
+  }
+  return { parseFailed };
+}
 async function runInit(cwd2, flags) {
   const existingConfig = findConfigFile(cwd2);
   if (existingConfig) {
@@ -1985,6 +2186,34 @@ async function runInit(cwd2, flags) {
     }
     provider = val;
   }
+  const AGENT_LABELS = [
+    { key: "lead", label: "Lead" },
+    { key: "explorer", label: "Explorer" },
+    { key: "consultant", label: "Consultant" },
+    { key: "builder", label: "Builder" },
+    { key: "reviewer", label: "Reviewer" }
+  ];
+  const claudeAgentModels = {};
+  if (provider === "claude-code") {
+    for (const agent of AGENT_LABELS) {
+      const val = await p3.select({
+        message: `Model for ${agent.label}`,
+        options: [
+          { value: "inherit", label: "inherit (default)" },
+          { value: "haiku", label: "haiku" },
+          { value: "sonnet", label: "sonnet" },
+          { value: "opus", label: "opus" },
+          { value: "fable", label: "fable" }
+        ],
+        initialValue: "inherit"
+      });
+      if (p3.isCancel(val)) {
+        p3.cancel("Cancelled.");
+        process.exit(0);
+      }
+      claudeAgentModels[agent.key] = val;
+    }
+  }
   let docsPath;
   if (flags.docs) {
     docsPath = flags.docs;
@@ -2076,6 +2305,7 @@ async function runInit(cwd2, flags) {
     firstTask = { title: taskTitle, description: taskDesc, acceptance };
   }
   let configExt = "ts";
+  let featureListParseFailedPath = null;
   const spinner6 = p3.spinner();
   spinner6.start("Scaffolding...");
   try {
@@ -2102,19 +2332,14 @@ async function runInit(cwd2, flags) {
       scope: config.storage.scope,
       projectId: config.storage.projectId
     });
-    writeFileSync8(join15(installDir, configFileName), configContent, "utf8");
-    mkdirSync7(join15(installDir, config.storage.dir), { recursive: true });
+    writeFileSync7(join15(installDir, configFileName), configContent, "utf8");
+    mkdirSync6(join15(installDir, config.storage.dir), { recursive: true });
     const db = await openDB(config, installDir);
     await db.writeStorageState(installDir);
-    await materializer.scaffold(config, { cwd: installDir, firstTask });
-    if (firstTask) {
-      const slug = slugify(firstTask.title);
-      await db.addTask({
-        slug,
-        title: firstTask.title,
-        description: firstTask.description,
-        acceptance: firstTask.acceptance
-      });
+    await materializer.scaffold(config, { cwd: installDir, firstTask, claudeAgentModels });
+    const { parseFailed } = await reconcileFeatureList(db, installDir, config.storage.dir, firstTask);
+    if (parseFailed) {
+      featureListParseFailedPath = join15(config.storage.dir, "feature_list.json");
     }
     await db.close();
     spinner6.stop("");
@@ -2123,6 +2348,11 @@ async function runInit(cwd2, flags) {
     p3.log.error(err instanceof Error ? err.message : String(err));
     throw err;
   }
+  if (featureListParseFailedPath) {
+    console.log(
+      pc8.yellow("\u26A0") + " Existing " + pc8.bold(featureListParseFailedPath) + " is not valid JSON \u2014 left untouched. Fix it and run `ahk sync`."
+    );
+  }
   console.log(pc8.green("\u2713 Scaffolded harness in current directory"));
   const agentsDir = provider === "claude-code" ? ".claude/agents/" : ".opencode/agents/";
   const mcpFile = provider === "claude-code" ? ".claude/mcp.json" : "./opencode.json";
@@ -2204,9 +2434,9 @@ async function runMigrate(cwd2, opts) {
 }
 
 // src/commands/migrate-storage.ts
-import { copyFileSync, existsSync as existsSync13, mkdirSync as mkdirSync8, rmSync, writeFileSync as writeFileSync9 } from "fs";
+import { copyFileSync, existsSync as existsSync14, mkdirSync as mkdirSync7, rmSync, writeFileSync as writeFileSync8 } from "fs";
 import { homedir as homedir3 } from "os";
-import { dirname as dirname7, join as join16, resolve as resolve7 } from "path";
+import { dirname as dirname7, join as join16, resolve as resolve6 } from "path";
 import pc10 from "picocolors";
 function log5(msg) {
   console.log(msg);
@@ -2218,17 +2448,17 @@ function defaultMarkdownPathForConfig(config) {
   return config.storage.scope === "local" ? config.storage.markdownFallback.path : DEFAULT_MARKDOWN_PATH;
 }
 function currentMdPathForScope(scope, config, cwd2, homeDir) {
-  return scope === "global" ? join16(resolveGlobalStorageDir(config, homeDir), "current.md") : resolve7(cwd2, defaultMarkdownPathForConfig(config));
+  return scope === "global" ? join16(resolveGlobalStorageDir(config, homeDir), "current.md") : resolve6(cwd2, defaultMarkdownPathForConfig(config));
 }
 function defaultSqlitePathForConfig(config) {
   return config.storage.scope === "local" && config.database.type === "sqlite" ? config.storage.sqlitePath ?? DEFAULT_SQLITE_PATH : DEFAULT_SQLITE_PATH;
 }
 async function backupDestination(cwd2, storageDir, data) {
-  const backupsDir = resolve7(cwd2, storageDir, "backups");
+  const backupsDir = resolve6(cwd2, storageDir, "backups");
   const path = join16(backupsDir, `pre-migrate-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.json`);
   try {
-    mkdirSync8(backupsDir, { recursive: true });
-    writeFileSync9(path, JSON.stringify(data, null, 2) + "\n", "utf8");
+    mkdirSync7(backupsDir, { recursive: true });
+    writeFileSync8(path, JSON.stringify(data, null, 2) + "\n", "utf8");
   } catch (err) {
     throw new Error(
       `Could not write destination backup to ${path} (${err instanceof Error ? err.message : String(err)}). Aborting migration WITHOUT touching the destination \u2014 nothing was overwritten.`
@@ -2237,14 +2467,14 @@ async function backupDestination(cwd2, storageDir, data) {
   return path;
 }
 function copySqliteFile(srcPath, destPath) {
-  mkdirSync8(dirname7(destPath), { recursive: true });
+  mkdirSync7(dirname7(destPath), { recursive: true });
   copyFileSync(srcPath, destPath);
   for (const suffix of ["-wal", "-shm"]) {
-    if (existsSync13(`${srcPath}${suffix}`)) {
+    if (existsSync14(`${srcPath}${suffix}`)) {
       copyFileSync(`${srcPath}${suffix}`, `${destPath}${suffix}`);
     }
   }
-  if (!existsSync13(destPath)) {
+  if (!existsSync14(destPath)) {
     throw new Error(`Copy verification failed: ${destPath} does not exist after copy.`);
   }
 }
@@ -2303,8 +2533,8 @@ async function runMigrateStorage(cwd2, opts, homeDir = homedir3()) {
   return migrateAcrossDbType(cwd2, config, homeDir, realScope, opts);
 }
 async function probeTaskCount(dbPath) {
-  if (!existsSync13(dbPath)) return 0;
-  const { SQLiteDriver } = await import("./sqlite-TR4D324R.js");
+  if (!existsSync14(dbPath)) return 0;
+  const { SQLiteDriver } = await import("./sqlite-5OWKTUUZ.js");
   const driver = new SQLiteDriver(dbPath);
   try {
     await driver.ensureSchema();
@@ -2320,12 +2550,12 @@ async function migrateScopeOnly(cwd2, config, homeDir, fromScope, toScope, opts)
   const destDb = resolveSqlitePathForScope(toScope, sqlitePath, cwd2, config, homeDir);
   const srcMd = currentMdPathForScope(fromScope, config, cwd2, homeDir);
   const destMd = currentMdPathForScope(toScope, config, cwd2, homeDir);
-  if (!existsSync13(srcDb)) {
+  if (!existsSync14(srcDb)) {
     fail(`Source database not found at ${srcDb} (expected ${fromScope} scope) \u2014 nothing to move.`);
   }
-  const destExists = existsSync13(destDb);
+  const destExists = existsSync14(destDb);
   if (destExists) {
-    const { SQLiteDriver } = await import("./sqlite-TR4D324R.js");
+    const { SQLiteDriver } = await import("./sqlite-5OWKTUUZ.js");
     const destDriver = new SQLiteDriver(destDb);
     let destEmpty;
     try {
@@ -2340,12 +2570,12 @@ async function migrateScopeOnly(cwd2, config, homeDir, fromScope, toScope, opts)
       );
     }
     if (!destEmpty && opts.force) {
-      const { SQLiteDriver: Driver } = await import("./sqlite-TR4D324R.js");
+      const { SQLiteDriver: Driver } = await import("./sqlite-5OWKTUUZ.js");
       const backupDriver = new Driver(destDb);
       let data;
       try {
         await backupDriver.ensureSchema();
-        const { HarnessDB } = await import("./db-3OXHRFAR.js");
+        const { HarnessDB } = await import("./db-L3AADJF5.js");
         const tmpDb = new HarnessDB(backupDriver, config, homeDir);
         data = await tmpDb.exportJson();
       } finally {
@@ -2361,15 +2591,15 @@ async function migrateScopeOnly(cwd2, config, homeDir, fromScope, toScope, opts)
   }
   copySqliteFile(srcDb, destDb);
   log5(pc10.green(`\u2713 Copied database ${srcDb} \u2192 ${destDb}`));
-  if (existsSync13(srcMd)) {
-    mkdirSync8(dirname7(destMd), { recursive: true });
+  if (existsSync14(srcMd)) {
+    mkdirSync7(dirname7(destMd), { recursive: true });
     copyFileSync(srcMd, destMd);
     log5(pc10.green(`\u2713 Copied current.md ${srcMd} \u2192 ${destMd}`));
   }
   rmSync(srcDb, { force: true });
   rmSync(`${srcDb}-wal`, { force: true });
   rmSync(`${srcDb}-shm`, { force: true });
-  if (existsSync13(srcMd) && srcMd !== destMd) rmSync(srcMd, { force: true });
+  if (existsSync14(srcMd) && srcMd !== destMd) rmSync(srcMd, { force: true });
   const db = await openDB(config, cwd2, homeDir);
   try {
     await db.writeStorageState(cwd2);
@@ -2381,17 +2611,17 @@ async function migrateScopeOnly(cwd2, config, homeDir, fromScope, toScope, opts)
 async function migrateAcrossDbType(cwd2, config, homeDir, sourceScope, opts) {
   const sqlitePath = defaultSqlitePathForConfig(config);
   const srcPath = resolveSqlitePathForScope(sourceScope, sqlitePath, cwd2, config, homeDir);
-  if (!existsSync13(srcPath)) {
+  if (!existsSync14(srcPath)) {
     fail(`Source sqlite database not found at ${srcPath} (expected ${sourceScope} scope) \u2014 nothing to migrate.`);
   }
-  const { SQLiteDriver } = await import("./sqlite-TR4D324R.js");
+  const { SQLiteDriver } = await import("./sqlite-5OWKTUUZ.js");
   const srcDriver = new SQLiteDriver(srcPath);
   let sourceData;
   let sourceCounts;
   try {
     await srcDriver.ensureSchema();
     sourceCounts = await getRowCounts(srcDriver);
-    const { HarnessDB } = await import("./db-3OXHRFAR.js");
+    const { HarnessDB } = await import("./db-L3AADJF5.js");
     const srcDb = new HarnessDB(srcDriver, config, homeDir);
     sourceData = await srcDb.exportJson();
   } finally {
@@ -2444,16 +2674,16 @@ async function migrateAcrossDbType(cwd2, config, homeDir, sourceScope, opts) {
 }
 
 // src/commands/reset.ts
-import { existsSync as existsSync14, readdirSync, rmSync as rmSync2 } from "fs";
+import { existsSync as existsSync15, readdirSync, rmSync as rmSync2 } from "fs";
 import { homedir as homedir4 } from "os";
-import { join as join17, resolve as resolve8 } from "path";
+import { join as join17, resolve as resolve7 } from "path";
 import * as p5 from "@clack/prompts";
 import pc11 from "picocolors";
 var AGENT_MD_FILES = ["lead", "explorer", "consultant", "builder", "reviewer"];
 async function resetAgentMds(cwd2, provider) {
   const agentDir = provider === "claude-code" ? ".claude/agents" : ".opencode/agents";
-  const agentDirPath = resolve8(cwd2, agentDir);
-  if (!existsSync14(agentDirPath)) {
+  const agentDirPath = resolve7(cwd2, agentDir);
+  if (!existsSync15(agentDirPath)) {
     console.log(pc11.yellow(`  Skipping agent files \u2014 directory not found: ${agentDirPath}`));
     return;
   }
@@ -2505,11 +2735,11 @@ async function runReset(cwd2, opts) {
   }
   const storageDir = config.storage.dir || ".harness";
   const dbPath = config.database.type === "sqlite" ? resolveSqlitePath(config, cwd2, homedir4()) : null;
-  const featureListPath = resolve8(cwd2, storageDir, "feature_list.json");
+  const featureListPath = resolve7(cwd2, storageDir, "feature_list.json");
   let resetDb = false;
   let resetFeatureList = false;
   let resetAgentMdsFlag = false;
-  if (dbPath && existsSync14(dbPath)) {
+  if (dbPath && existsSync15(dbPath)) {
     if (opts.force) {
       resetDb = true;
     } else {
@@ -2531,7 +2761,7 @@ async function runReset(cwd2, opts) {
   } else if (!dbPath) {
     console.log(pc11.dim(`  Skipping DB reset \u2014 remote ${config.database.type} database is not managed by this command.`));
   }
-  if (existsSync14(featureListPath)) {
+  if (existsSync15(featureListPath)) {
     if (opts.force) {
       resetFeatureList = true;
     } else {
@@ -2580,8 +2810,8 @@ async function runReset(cwd2, opts) {
 }
 
 // src/core/mcp-server.ts
-import { existsSync as existsSync16, mkdirSync as mkdirSync9, readdirSync as readdirSync2, readFileSync as readFileSync9, statSync, writeFileSync as writeFileSync10 } from "fs";
-import { join as join19, resolve as resolve9 } from "path";
+import { existsSync as existsSync17, mkdirSync as mkdirSync8, readdirSync as readdirSync2, readFileSync as readFileSync10, statSync, writeFileSync as writeFileSync9 } from "fs";
+import { join as join19, resolve as resolve8 } from "path";
 import { Server } from "@modelcontextprotocol/sdk/server";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -2590,7 +2820,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 // src/core/permissions-check.ts
-import { existsSync as existsSync15 } from "fs";
+import { existsSync as existsSync16 } from "fs";
 import { join as join18 } from "path";
 var AGENTS = ["lead", "explorer", "consultant", "builder", "reviewer"];
 function checkPermissionsSync(cwd2, config) {
@@ -2601,7 +2831,7 @@ function checkPermissionsSync(cwd2, config) {
   let in_sync = true;
   for (const agent of AGENTS) {
     const filePath = join18(cwd2, ".claude", "agents", `${agent}.md`);
-    const exists = existsSync15(filePath);
+    const exists = existsSync16(filePath);
     if (!exists) in_sync = false;
     agents[agent] = exists ? { ok: true } : { ok: false, reason: "missing_file" };
   }
@@ -2613,7 +2843,7 @@ var VERSION = "0.1.0";
 var TOOLS = [
   {
     name: "actions.start",
-    description: "Start a new action for a task. Returns an actionId (UUID).",
+    description: "Start a new action for a task. Returns an actionId.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2628,18 +2858,18 @@ var TOOLS = [
   },
   {
     name: "actions.write",
-    description: "Record a section in an action. Standard sections: result, tools_used, blockers, next_steps. Note: files_modified is a plain-text note only \u2014 it does NOT populate the files dashboard. Use actions.record_file to register files in the dashboard.",
+    description: "Record a section in an action. Standard sections: result, tools_used, blockers, next_steps.",
     inputSchema: {
       type: "object",
       properties: {
-        actionId: { type: "string", description: "UUID returned by actions.start" },
+        actionId: { type: "number", description: "The actionId returned by actions.start" },
         sectionType: {
           type: "string",
           description: "Section name: result | tools_used | blockers | next_steps | <custom>. Do NOT use files_modified to track files \u2014 it is stored as plain text only. Use actions.record_file instead."
         },
         content: {
           type: "string",
-          description: "Content for this section. No length limit \u2014 include all information that's relevant and necessary, but avoid unnecessary padding to prevent context bottlenecks between agents."
+          description: "Content for this section. No length limit; avoid padding \u2014 it costs shared context for other agents."
         }
       },
       required: ["actionId", "sectionType", "content"]
@@ -2651,7 +2881,7 @@ var TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        actionId: { type: "string", description: "UUID of the action to close" },
+        actionId: { type: "number", description: "The actionId of the action to close" },
         summary: { type: "string", description: "One-line summary of what was done" }
       },
       required: ["actionId", "summary"]
@@ -2726,20 +2956,31 @@ var TOOLS = [
   },
   {
     name: "actions.record_file",
-    description: "Record a file touched during an action. This is the only way to populate the files-touched count shown in the dashboard. Call once per file.",
+    description: "Record one or more files touched during an action, atomically (all-or-nothing). This is the only way to populate the files-touched count shown in the dashboard. Batch every file from a step of work into a single call \u2014 a single-element array is correct when only one file was touched.",
     inputSchema: {
       type: "object",
       properties: {
-        actionId: { type: "string", description: "UUID returned by actions.start" },
-        filePath: { type: "string", description: "Absolute or repo-relative path of the file" },
-        operation: {
-          type: "string",
-          enum: ["read", "created", "modified", "deleted"],
-          description: "What was done to the file"
-        },
-        notes: { type: "string", description: "Optional short note about the change" }
+        actionId: { type: "number", description: "The actionId returned by actions.start" },
+        files: {
+          type: "array",
+          minItems: 1,
+          description: "Files touched, recorded atomically in one transaction.",
+          items: {
+            type: "object",
+            properties: {
+              filePath: { type: "string", description: "Absolute or repo-relative path of the file" },
+              operation: {
+                type: "string",
+                enum: ["read", "created", "modified", "deleted"],
+                description: "What was done to the file"
+              },
+              notes: { type: "string", description: "Optional short note about the change" }
+            },
+            required: ["filePath", "operation"]
+          }
+        }
       },
-      required: ["actionId", "filePath", "operation"]
+      required: ["actionId", "files"]
     }
   },
   {
@@ -2780,12 +3021,12 @@ var TOOLS = [
         },
         description: {
           type: "string",
-          description: "Longer description of the task goal. No length limit \u2014 include all information that's relevant and necessary, but avoid unnecessary padding to prevent context bottlenecks between agents."
+          description: "Longer description of the task goal. No length limit; avoid padding \u2014 it costs shared context for other agents."
         },
         acceptance: {
           type: "array",
           items: { type: "string" },
-          description: "List of acceptance criteria (plain sentences). No length limit \u2014 include all information that's relevant and necessary, but avoid unnecessary padding to prevent context bottlenecks between agents."
+          description: "List of acceptance criteria (plain sentences). No length limit; avoid padding \u2014 it costs shared context for other agents."
         }
       },
       required: ["title"]
@@ -2793,22 +3034,36 @@ var TOOLS = [
   },
   {
     name: "actions.record_tool",
-    description: "Record a tool call made during an action. This is the only way to populate the Tools dashboard. Call once per tool invocation.",
+    description: "Record one or more tool calls made during an action, atomically (all-or-nothing). This is the only way to populate the Tools dashboard. Batch every tool call from a step of work into a single call \u2014 a single-element array is correct when only one call was made.",
     inputSchema: {
       type: "object",
       properties: {
-        actionId: { type: "string", description: "UUID returned by actions.start" },
-        toolName: {
-          type: "string",
-          description: "Name of the tool that was called (e.g. Read, Bash, Edit)"
-        },
-        argsJson: {
-          type: "string",
-          description: "Optional JSON string of the arguments passed to the tool"
-        },
-        resultSummary: { type: "string", description: "Optional short summary of the tool result" }
+        actionId: { type: "number", description: "The actionId returned by actions.start" },
+        calls: {
+          type: "array",
+          minItems: 1,
+          description: "Tool calls made, recorded atomically in one transaction.",
+          items: {
+            type: "object",
+            properties: {
+              toolName: {
+                type: "string",
+                description: "Name of the tool that was called (e.g. Read, Bash, Edit)"
+              },
+              argsJson: {
+                type: "string",
+                description: "Optional JSON string of the arguments passed to the tool"
+              },
+              resultSummary: {
+                type: "string",
+                description: "Optional short summary of the tool result"
+              }
+            },
+            required: ["toolName"]
+          }
+        }
       },
-      required: ["actionId", "toolName"]
+      required: ["actionId", "calls"]
     }
   },
   {
@@ -2874,7 +3129,7 @@ var TOOLS = [
 ];
 async function startMcpServer(config, cwd2) {
   const db = await openDB(config, cwd2);
-  const docsPath = resolve9(cwd2, config.project.docsPath);
+  const docsPath = resolve8(cwd2, config.project.docsPath);
   const server = new Server(
     { name: "agent-harness-kit", version: VERSION },
     { capabilities: { tools: {} } }
@@ -2899,39 +3154,50 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
       const taskId = num(args, "taskId");
       const agent = str(args, "agent");
       const action = await db.startAction(taskId, agent);
-      return ok2(JSON.stringify({ actionId: action.id, taskId, agent, status: "in_progress" }));
+      return ok2(JSON.stringify({ actionId: action.id }));
     }
     case "actions.write": {
-      const actionId = str(args, "actionId");
+      const actionId = num(args, "actionId");
       const sectionType = str(args, "sectionType");
       const content = str(args, "content");
       await db.writeSection(actionId, sectionType, content);
-      return ok2(JSON.stringify({ actionId, sectionType, recorded: true }));
+      return ok2(JSON.stringify({ recorded: true }));
     }
     case "actions.complete": {
-      const actionId = str(args, "actionId");
+      const actionId = num(args, "actionId");
       const summary = str(args, "summary");
       const action = await db.completeAction(actionId, summary);
-      return ok2(
-        JSON.stringify({ actionId, status: action.status, completedAt: action.completed_at })
-      );
+      return ok2(JSON.stringify({ status: action.status, completedAt: action.completed_at }));
     }
     case "actions.get": {
       const taskId = num(args, "taskId");
       const actions = await db.getActionsForTask(taskId);
       const full = await Promise.all(
-        actions.map(async (a) => ({
-          ...a,
-          sections: await db.getActionSections(a.id)
-        }))
+        actions.map(async (a) => {
+          const sections = await db.getActionSections(a.id);
+          return {
+            id: a.id,
+            agent: a.agent,
+            status: a.status,
+            created_at: a.created_at,
+            completed_at: a.completed_at,
+            summary: a.summary,
+            sections: sections.map((s) => ({
+              id: s.id,
+              section_type: s.section_type,
+              content: s.content,
+              created_at: s.created_at
+            }))
+          };
+        })
       );
-      return ok2(JSON.stringify(full, null, 2));
+      return ok2(JSON.stringify(full));
     }
     case "tasks.get": {
       const status = args["status"];
       const includeArchived = args["includeArchived"];
       const tasks = status ? await db.getTasks(status, includeArchived ?? false) : await db.getTasks(void 0, includeArchived ?? false);
-      return ok2(JSON.stringify(tasks, null, 2));
+      return ok2(JSON.stringify(tasks));
     }
     case "tasks.claim": {
       const id = num(args, "id");
@@ -2962,15 +3228,17 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
     case "docs.search": {
       const query = str(args, "query");
       const results = searchDocs(docsPath, query);
-      return ok2(JSON.stringify(results, null, 2));
+      return ok2(JSON.stringify(results));
     }
     case "actions.record_file": {
-      const actionId = str(args, "actionId");
-      const filePath = str(args, "filePath");
-      const operation = str(args, "operation");
-      const notes = args["notes"];
-      await db.recordFile(actionId, filePath, operation, notes);
-      return ok2(JSON.stringify({ actionId, filePath, operation, recorded: true }));
+      const actionId = num(args, "actionId");
+      const files = nonEmptyArray(args, "files").map((f) => ({
+        filePath: str(f, "filePath"),
+        operation: str(f, "operation"),
+        notes: f["notes"]
+      }));
+      const recorded = await db.recordFiles(actionId, files);
+      return ok2(JSON.stringify({ recorded }));
     }
     case "tasks.acceptance.update": {
       const criterionId = num(args, "criterionId");
@@ -2980,15 +3248,17 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
     case "tasks.acceptance.get": {
       const taskId = num(args, "taskId");
       const criteria = await db.getTaskAcceptance(taskId);
-      return ok2(JSON.stringify(criteria, null, 2));
+      return ok2(JSON.stringify(criteria));
     }
     case "actions.record_tool": {
-      const actionId = str(args, "actionId");
-      const toolName = str(args, "toolName");
-      const argsJson = args["argsJson"];
-      const resultSummary = args["resultSummary"];
-      await db.recordTool(actionId, toolName, argsJson, resultSummary);
-      return ok2(JSON.stringify({ actionId, toolName, recorded: true }));
+      const actionId = num(args, "actionId");
+      const calls = nonEmptyArray(args, "calls").map((c) => ({
+        toolName: str(c, "toolName"),
+        argsJson: c["argsJson"],
+        resultSummary: c["resultSummary"]
+      }));
+      const recorded = await db.recordTools(actionId, calls);
+      return ok2(JSON.stringify({ recorded }));
     }
     case "tasks.edit": {
       const id = num(args, "id");
@@ -3019,22 +3289,22 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
     }
     case "permissions.check": {
       const result = checkPermissionsSync(cwd2, config);
-      return ok2(JSON.stringify(result, null, 2));
+      return ok2(JSON.stringify(result));
     }
     case "deps.snapshot": {
       const pkgPath2 = join19(cwd2, "package.json");
-      if (!existsSync16(pkgPath2)) {
+      if (!existsSync17(pkgPath2)) {
         return ok2("package.json not found in project root", true);
       }
-      const pkg2 = JSON.parse(readFileSync9(pkgPath2, "utf8"));
+      const pkg2 = JSON.parse(readFileSync10(pkgPath2, "utf8"));
       const snapshot = {
         capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
         dependencies: pkg2.dependencies ?? {},
         devDependencies: pkg2.devDependencies ?? {}
       };
       const harnessDir = join19(cwd2, ".harness");
-      mkdirSync9(harnessDir, { recursive: true });
-      writeFileSync10(join19(harnessDir, "deps-lock.json"), JSON.stringify(snapshot, null, 2), "utf8");
+      mkdirSync8(harnessDir, { recursive: true });
+      writeFileSync9(join19(harnessDir, "deps-lock.json"), JSON.stringify(snapshot, null, 2), "utf8");
       return ok2(
         JSON.stringify({
           message: "Snapshot saved to .harness/deps-lock.json",
@@ -3045,10 +3315,10 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
     case "deps.check": {
       const pkgPath2 = join19(cwd2, "package.json");
       const lockPath = join19(cwd2, ".harness", "deps-lock.json");
-      if (!existsSync16(pkgPath2)) {
+      if (!existsSync17(pkgPath2)) {
         return ok2("package.json not found in project root", true);
       }
-      if (!existsSync16(lockPath)) {
+      if (!existsSync17(lockPath)) {
         return ok2(
           JSON.stringify({
             status: "no-snapshot",
@@ -3056,8 +3326,8 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
           })
         );
       }
-      const pkg2 = JSON.parse(readFileSync9(pkgPath2, "utf8"));
-      const lock = JSON.parse(readFileSync9(lockPath, "utf8"));
+      const pkg2 = JSON.parse(readFileSync10(pkgPath2, "utf8"));
+      const lock = JSON.parse(readFileSync10(lockPath, "utf8"));
       const current = { ...pkg2.dependencies ?? {}, ...pkg2.devDependencies ?? {} };
       const previous = { ...lock.dependencies ?? {}, ...lock.devDependencies ?? {} };
       const added = [];
@@ -3111,7 +3381,7 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
           ok: status.skills.filter((s) => s.status === "ok").map((s) => s.name)
         }
       };
-      return ok2(JSON.stringify(result, null, 2));
+      return ok2(JSON.stringify(result));
     }
     default:
       return ok2(`Unknown tool: ${name}`, true);
@@ -3125,7 +3395,7 @@ function searchDocs(docsPath, query, maxResults = 10) {
     for (const file of files) {
       if (results.length >= maxResults) break;
       try {
-        const content = readFileSync9(file, "utf8");
+        const content = readFileSync10(file, "utf8");
         const lines = content.split("\n");
         for (let i = 0; i < lines.length; i++) {
           const lower = lines[i].toLowerCase();
@@ -3175,6 +3445,18 @@ function num(args, key) {
   if (typeof v4 !== "number") throw new Error(`${key} must be a number`);
   return v4;
 }
+function nonEmptyArray(args, key) {
+  const v4 = args[key];
+  if (!Array.isArray(v4) || v4.length === 0) {
+    throw new Error(`${key} must be a non-empty array`);
+  }
+  for (const item of v4) {
+    if (typeof item !== "object" || item === null) {
+      throw new Error(`${key} entries must be objects`);
+    }
+  }
+  return v4;
+}
 
 // src/commands/serve.ts
 async function runServe(cwd2, opts) {
@@ -3268,13 +3550,13 @@ async function runStatus(cwd2, opts) {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync17, readFileSync as readFileSync10 } from "fs";
-import { join as join20, resolve as resolve10 } from "path";
+import { existsSync as existsSync18, readFileSync as readFileSync11 } from "fs";
+import { join as join20, resolve as resolve9 } from "path";
 import pc13 from "picocolors";
 async function runSync(cwd2, opts) {
   const config = await loadConfig(cwd2);
   const direction = opts.direction ?? "both";
-  const featureListPath = resolve10(join20(cwd2, config.storage.dir, "feature_list.json"));
+  const featureListPath = resolve9(join20(cwd2, config.storage.dir, "feature_list.json"));
   const db = await openDB(config, cwd2);
   try {
     if (direction === "in" || direction === "both") {
@@ -3288,13 +3570,13 @@ async function runSync(cwd2, opts) {
   }
 }
 async function syncIn(featureListPath, db, dryRun) {
-  if (!existsSync17(featureListPath)) {
+  if (!existsSync18(featureListPath)) {
     console.log(pc13.dim(`feature_list.json not found at ${featureListPath} \u2014 skipping in-sync`));
     return;
   }
   let seeds;
   try {
-    seeds = JSON.parse(readFileSync10(featureListPath, "utf8"));
+    seeds = JSON.parse(readFileSync11(featureListPath, "utf8"));
   } catch (err) {
     console.error(pc13.red(`Failed to parse feature_list.json: ${err}`));
     process.exit(1);
@@ -3379,14 +3661,14 @@ async function runTaskAdd(cwd2) {
 
 // src/commands/task/done.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync18 } from "fs";
-import { resolve as resolve11 } from "path";
+import { existsSync as existsSync19 } from "fs";
+import { resolve as resolve10 } from "path";
 import pc15 from "picocolors";
 async function runTaskDone(cwd2, idOrSlug) {
   const config = await loadConfig(cwd2);
   if (config.health.required) {
-    const scriptPath = resolve11(cwd2, config.health.scriptPath);
-    if (existsSync18(scriptPath)) {
+    const scriptPath = resolve10(cwd2, config.health.scriptPath);
+    if (existsSync19(scriptPath)) {
       const result = spawnSync2("bash", [scriptPath], { cwd: cwd2, stdio: "pipe", encoding: "utf8" });
       if (result.status !== 0) {
         console.error(pc15.red("\u2717 Health check failed \u2014 cannot mark task as done."));
@@ -3557,27 +3839,93 @@ async function runTaskList(cwd2, opts) {
   }
 }
 
-// src/core/update-check.ts
+// src/core/path-probe.ts
+import { accessSync, constants, readdirSync as readdirSync3 } from "fs";
+import { join as join21 } from "path";
 import pc18 from "picocolors";
+var DEFAULT_PATHEXT = [".COM", ".EXE", ".BAT", ".CMD"];
+function defaultIsExecutable(filePath) {
+  try {
+    accessSync(filePath, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function normalizeExts(pathext) {
+  const raw = pathext && pathext.trim().length > 0 ? pathext : DEFAULT_PATHEXT.join(";");
+  return raw.split(";").map((ext) => ext.trim().toLowerCase()).filter((ext) => ext.length > 0).map((ext) => ext.startsWith(".") ? ext : `.${ext}`);
+}
+function resolveOnPath(name, options = {}) {
+  const {
+    pathValue = process.env.PATH,
+    pathext = process.env.PATHEXT,
+    platform = process.platform,
+    isExecutable = defaultIsExecutable
+  } = options;
+  if (!pathValue) return false;
+  const isWindows = platform === "win32";
+  const sep = isWindows ? ";" : ":";
+  const dirs = pathValue.split(sep).filter((dir) => dir.length > 0);
+  if (dirs.length === 0) return false;
+  if (isWindows) {
+    const lowerName = name.toLowerCase();
+    const candidates2 = /* @__PURE__ */ new Set([lowerName, ...normalizeExts(pathext).map((ext) => `${lowerName}${ext}`)]);
+    for (const dir of dirs) {
+      let entries;
+      try {
+        entries = readdirSync3(dir);
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (candidates2.has(entry.toLowerCase())) return true;
+      }
+    }
+    return false;
+  }
+  for (const dir of dirs) {
+    try {
+      if (isExecutable(join21(dir, name))) return true;
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}
+function isExecutableOnPath(name) {
+  return resolveOnPath(name);
+}
+function printMissingGlobalBinaryWarning() {
+  console.error(pc18.yellow("\u26A0 `ahk` was not found on your PATH."));
+  console.error(pc18.dim("  Your project has no local install, so the generated MCP config launches"));
+  console.error(pc18.dim("  `ahk serve` directly. Without `ahk` on your PATH, starting the MCP server"));
+  console.error(pc18.dim("  from that config will fail. This is only a warning \u2014 the command continues."));
+  console.error(pc18.dim(`  Run: npm i -g ${pkg.name}   (install globally)`));
+  console.error(pc18.dim(`  or:  npm install --save-dev ${pkg.name}   (install locally in this project)`));
+}
+
+// src/core/update-check.ts
+import pc19 from "picocolors";
 var REGISTRY_URL2 = `https://registry.npmjs.org/${pkg.name}/latest`;
 var TIMEOUT_MS2 = 2500;
 function checkForUpdate(currentVersion) {
-  return new Promise((resolve12) => {
-    const timer = setTimeout(() => resolve12(null), TIMEOUT_MS2);
+  return new Promise((resolve11) => {
+    const timer = setTimeout(() => resolve11(null), TIMEOUT_MS2);
     fetch(REGISTRY_URL2).then((res) => res.json()).then((data) => {
       clearTimeout(timer);
       const latest = data.version;
-      resolve12(isNewer2(latest, currentVersion) ? { current: currentVersion, latest } : null);
+      resolve11(isNewer2(latest, currentVersion) ? { current: currentVersion, latest } : null);
     }).catch(() => {
       clearTimeout(timer);
-      resolve12(null);
+      resolve11(null);
     });
   });
 }
 function printUpdateMessage({ current, latest }) {
   const lines = [
-    `  Update available ${pc18.dim(current)} \u2192 ${pc18.green(latest)}  `,
-    `  Run: ${pc18.cyan(`pnpm i ${pkg.name}@${latest}`)}          `
+    `  Update available ${pc19.dim(current)} \u2192 ${pc19.green(latest)}  `,
+    `  Run: ${pc19.cyan(`pnpm i ${pkg.name}@${latest}`)}          `
   ];
   drawBox(lines);
 }
@@ -3592,6 +3940,18 @@ function isNewer2(latest, current) {
 
 // src/cli.ts
 var cwd = process.cwd();
+function parsePort(raw) {
+  const trimmed = raw.trim();
+  const rangeHint = "must be an integer between 1 and 65535";
+  if (!/^\d+$/.test(trimmed)) {
+    throw new InvalidArgumentError(`--port ${rangeHint} (received "${raw}").`);
+  }
+  const port = Number(trimmed);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new InvalidArgumentError(`--port ${rangeHint} (received "${raw}").`);
+  }
+  return port;
+}
 var updateCheck = checkForUpdate(pkg.version);
 var program = new Command();
 program.name("ahk").description("agent-harness-kit \u2014 CLI scaffolding for multi-agent harness systems").version(pkg.version, "-v, --version");
@@ -3613,7 +3973,7 @@ program.command("status").description("Show task table and active actions").opti
 program.command("sync").description("Sync feature_list.json \u2194 SQLite").option("--dry-run", "Show what would change without applying").option("--direction <direction>", "in | out | both (default: both)").action(async (opts) => {
   await runSync(cwd, { dryRun: opts["dry-run"], direction: opts.direction });
 });
-program.command("serve").description("Start the MCP server (stdio)").option("--port <port>", "Port hint stored in config (default: 3742)", parseInt).action(async (opts) => {
+program.command("serve").description("Start the MCP server (stdio)").option("--port <port>", "Port hint stored in config (default: 3742)", parsePort).action(async (opts) => {
   await runServe(cwd, { port: opts.port });
 });
 var task = program.command("task").description("Manage tasks");
@@ -3629,8 +3989,8 @@ task.command("done <id|slug>").description("Mark a task as done").action(async (
 task.command("edit").description("Edit a task interactively").action(async () => {
   await runTaskEdit(cwd);
 });
-program.command("dashboard").description("Open web dashboard to visualize harness data").option("-p, --port <port>", "Port to listen on", "4242").option("--no-open", "Do not open browser automatically").action(async (opts) => {
-  await runDashboard(cwd, { port: parseInt(opts.port), open: opts.open });
+program.command("dashboard").description("Open web dashboard to visualize harness data").option("-p, --port <port>", "Port to listen on", parsePort, 4242).option("--no-open", "Do not open browser automatically").action(async (opts) => {
+  await runDashboard(cwd, { port: opts.port, open: opts.open });
 });
 var migrate = program.command("migrate").description("Migrate provider files to a different provider, or migrate harness storage (see subcommands)");
 migrate.command("provider").description("Migrate provider-specific files to a different provider").option("--to <provider>", "Target provider: claude-code | opencode | codex-cli").action(async (opts) => {
@@ -3642,7 +4002,7 @@ migrate.command("storage").description(
   try {
     await runMigrateStorage(cwd, { force: opts.force, dryRun: opts["dry-run"] });
   } catch (err) {
-    console.error(pc19.red(`\u2717 ${err instanceof Error ? err.message : String(err)}`));
+    console.error(pc20.red(`\u2717 ${err instanceof Error ? err.message : String(err)}`));
     process.exit(1);
   }
 });
@@ -3658,6 +4018,9 @@ program.command("doctor").description("Check lib version, agent files, and harne
 program.hook("preAction", () => {
   if (!isLocalInstallSatisfied(cwd)) {
     printLocalInstallWarning();
+    if (!isExecutableOnPath("ahk")) {
+      printMissingGlobalBinaryWarning();
+    }
   }
 });
 program.hook("postAction", async () => {