@cardor/agent-harness-kit 1.10.5 → 2.0.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 import {
   findConfigFile,
   loadConfig
-} from "./chunk-D64KK6UU.js";
+} from "./chunk-U3O77CGE.js";
 import {
   DEFAULT_MARKDOWN_PATH,
   DEFAULT_SQLITE_PATH,
@@ -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, readFileSync as readFileSync5, 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,18 +382,50 @@ 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 { 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 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 = {
+  lead: "no-write",
+  explorer: "no-write",
+  consultant: "no-write",
+  builder: "none",
+  reviewer: "no-write"
+};
+function restrictionFor(agentName) {
+  return AGENT_RESTRICTIONS[agentName] ?? "no-write";
+}
+function claudeDisallowedTools(agentName) {
+  return restrictionFor(agentName) === "no-write" ? ["Write", "Edit"] : [];
+}
+function opencodePermissions(agentName) {
+  return restrictionFor(agentName) === "no-write" ? { edit: "deny" } : {};
+}
+function codexSandboxMode(agentName) {
+  return restrictionFor(agentName) === "no-write" ? "read-only" : "workspace-write";
+}
+var CODEX_READ_ONLY_NOTICE = `## Tool restrictions (enforced by the sandbox)
+
+This agent runs with \`sandbox_mode = "read-only"\`. You MUST NOT create, modify, or delete any file: no \`Write\`, no \`Edit\`, no \`apply_patch\`, and no shell command that writes to disk (\`>\`, \`tee\`, \`sed -i\`, \`mv\`, \`rm\`, ...).
+
+These tools may still appear available to you. The sandbox will reject the call. Do not retry a rejected write \u2014 report it as a blocker instead.`;
+function codexRestrictionNotice(agentName) {
+  return restrictionFor(agentName) === "no-write" ? CODEX_READ_ONLY_NOTICE : "";
+}
+
 // src/core/materializer/templates.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { dirname as dirname2, join as join3 } from "path";
-import { fileURLToPath } from "url";
-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
@@ -393,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
@@ -416,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
@@ -477,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
@@ -501,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
@@ -530,11 +615,7 @@ If orchestrating: Agent definition files in .claude/agents/
 \`\`\`
 `;
 }
-function modelField(model) {
-  return model ? `, model: ${JSON.stringify(model)}` : "";
-}
 function configObjectBody(params) {
-  const models = params.models ?? {};
   const isGlobal = params.scope === "global";
   const markdownFallbackLine = isGlobal ? `markdownFallback: { enabled: true },` : `markdownFallback: { enabled: true, path: '.harness/current.md' },`;
   return `  project: {
@@ -545,14 +626,13 @@ function configObjectBody(params) {
 
   provider: '${params.provider}',
 
-  agents: {
-    lead:     { instructionsPath: null${modelField(models.lead)} },
-    explorer: { instructionsPath: null, allowedPaths: ['${params.docsPath}', './src']${modelField(models.explorer)} },
-    builder:  { instructionsPath: null, writablePaths: ['./src', './tests']${modelField(models.builder)} },
-    reviewer: { instructionsPath: null${modelField(models.reviewer)} },
-    ${models.consultant ? `consultant: { instructionsPath: null${modelField(models.consultant)} },
-    ` : ""}custom:   [],
-  },
+  // There is no 'agents' key. Agent files are yours: edit the role prompt and
+  // the 'model:' frontmatter line directly in the generated file. 'ahk build'
+  // creates them when missing and never overwrites them \u2014 use
+  // 'ahk build --force' to regenerate them from the packaged templates.
+  // What each role may NOT do is enforced per-tool inside those files
+  // (disallowedTools / permission.edit / sandbox_mode); see
+  // src/core/materializer/agent-restrictions.ts.
 
   // SQLite (default). Switch to postgres/mysql by changing database.type.
   // database: { type: 'postgres', connectionString: process.env.DATABASE_URL },
@@ -587,6 +667,47 @@ function configObjectBody(params) {
   },
 `;
 }
+function configObject(params) {
+  const isGlobal = params.scope === "global";
+  return {
+    project: {
+      name: params.name,
+      description: params.description,
+      docsPath: params.docsPath
+    },
+    provider: params.provider,
+    // There is no 'agents' key here either — it was removed from the config
+    // entirely, so the JSON variant must not reintroduce it.
+    database: { type: "sqlite" },
+    storage: {
+      dir: ".harness",
+      tasks: { adapter: params.tasksAdapter },
+      sections: {
+        toolsUsed: true,
+        filesModified: true,
+        result: true,
+        blockers: true,
+        nextSteps: false
+      },
+      // Same scope rule as configObjectBody(): 'global' has no local path to
+      // declare, so markdownFallback.path is omitted for it.
+      markdownFallback: isGlobal ? { enabled: true } : { enabled: true, path: ".harness/current.md" },
+      scope: params.scope,
+      projectId: params.projectId
+    },
+    health: {
+      scriptPath: "./health.sh",
+      required: true
+    },
+    tools: {
+      mcp: { enabled: true, port: params.port },
+      scripts: { enabled: true, outputDir: "./.harness/scripts" }
+    }
+  };
+}
+function configJson(params) {
+  return JSON.stringify(configObject(params), null, 2) + "\n";
+}
 function configTs(params) {
   return `import type { HarnessConfig } from '@cardor/agent-harness-kit'
 
@@ -625,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 };
@@ -643,81 +761,93 @@ function stripFrontmatter(md) {
   }
   return { description, body };
 }
-function toCodexToml(name, description, body, sandboxMode, model) {
+function toCodexToml(tomlName, agentName, description, body) {
   const safe = (s) => s.replace(/"""/g, '""\\u0022');
-  const trimmedModel = model?.trim() ?? "";
-  const modelLine = trimmedModel.length >= 3 ? `model = "${trimmedModel}"
-` : "";
-  return `name = "${name}"
+  const sandboxMode = codexSandboxMode(agentName);
+  const notice = codexRestrictionNotice(agentName);
+  const instructions = notice ? `${body.trimEnd()}
+
+---
+
+${notice}` : body.trimEnd();
+  return `name = "${tomlName}"
 sandbox_mode = "${sandboxMode}"
-${modelLine}
+
 description = """
 ${safe(description)}
 """
 
 developer_instructions = """
-${safe(body.trimEnd())}
+${safe(instructions)}
 """
 `;
 }
 function agentLeadToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("lead", vars));
-  return toCodexToml("lead", description, body, "read-only", vars.model);
+  return toCodexToml("lead", "lead", description, body);
 }
 function agentLeadAsDefaultToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("lead", vars));
-  return toCodexToml("default", description, body, "read-only", vars.model);
+  return toCodexToml("default", "lead", description, body);
 }
 function agentExplorerToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("explorer", vars));
-  return toCodexToml("explorer", description, body, "read-only", vars.model);
+  return toCodexToml("explorer", "explorer", description, body);
 }
 function agentBuilderToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("builder", vars));
-  return toCodexToml("builder", description, body, "workspace-write", vars.model);
+  return toCodexToml("builder", "builder", description, body);
 }
 function agentReviewerToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("reviewer", vars));
-  return toCodexToml("reviewer", description, body, "read-only", vars.model);
+  return toCodexToml("reviewer", "reviewer", description, body);
 }
 function agentConsultantToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("consultant", vars));
-  return toCodexToml("consultant", description, body, "read-only", vars.model);
-}
-function translateFrontmatterForClaudeCode(md, agentName, model) {
-  const permissionsMap = {
-    lead: [...MCP_CLAUDE_PERMISSIONS_LEAD],
-    explorer: [...MCP_CLAUDE_PERMISSIONS_EXPLORER],
-    consultant: [...MCP_CLAUDE_PERMISSIONS_CONSULTANT],
-    builder: [...MCP_CLAUDE_PERMISSIONS_BUILDER],
-    reviewer: [...MCP_CLAUDE_PERMISSIONS_REVIEWER]
-  };
-  const permissions = permissionsMap[agentName] ?? MCP_CLAUDE_PERMISSIONS;
-  const mcpLines = permissions.map((t) => `  - ${t}`).join("\n");
-  let result = md.replace(/(tools:\n(?:  - (?!mcp__)[^\n]+\n)+)/, (match) => {
-    const trimmed = match.trimEnd();
-    return `${trimmed}
-  - Task
-${mcpLines}
+  return toCodexToml("consultant", "consultant", description, body);
+}
+function stripFrontmatterBlockSequence(md, key) {
+  const re = new RegExp(`^${key}:\\n(?:  - [^\\n]+\\n)+`, "m");
+  return md.replace(re, "");
+}
+function appendFrontmatterBlockSequence(md, key, values) {
+  if (values.length === 0) return md;
+  const block = `${key}:
+${values.map((v4) => `  - ${v4}`).join("\n")}
 `;
-  });
-  if (model) {
-    result = injectModelFrontmatterLine(result, model);
-  }
-  return result;
+  return md.replace(/^---\n([\s\S]*?)^---\n/m, (_m, body) => `---
+${body}${block}---
+`);
 }
-function injectModelFrontmatterLine(md, model) {
-  if (/^model:\s*.*$/m.test(md)) {
-    return md.replace(/^model:\s*.*$/m, `model: ${model}`);
+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;
+  const block = `${key}:
+${keys.map((k) => `  ${k}: ${entries[k]}`).join("\n")}
+`;
+  return md.replace(/^---\n([\s\S]*?)^---\n/m, (_m, body) => `---
+${body}${block}---
+`);
+}
+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 md.replace(/^(name:.*)$/m, `$1
-model: ${model}`);
+  return appendFrontmatterBlockSequence(result, "disallowedTools", claudeDisallowedTools(agentName));
 }
-function translateFrontmatterForOpenCode(md) {
-  return md.replace(/(tools:\n(?:  - [^\n]+\n)+)/, (match) => {
-    const tools = [...match.matchAll(/  - ([^\n]+)/g)].map((m) => m[1].trim());
-    return "tools:\n" + tools.map((t) => `  ${t.toLocaleLowerCase()}: true`).join("\n") + "\n";
-  });
+function translateFrontmatterForOpenCode(md, agentName) {
+  let result = stripFrontmatterBlockSequence(md, "tools");
+  result = stripFrontmatterBlockSequence(result, "disallowedTools");
+  return appendFrontmatterMapping(result, "permission", opencodePermissions(agentName));
 }
 var GITIGNORE_ENTRIES = `
 # agent-harness-kit
@@ -728,16 +858,145 @@ var GITIGNORE_ENTRIES = `
 `;
 
 // src/core/materializer/scaffold-utils.ts
-var __dirname2 = dirname3(fileURLToPath2(import.meta.url));
-function writeAgentFile(cwd2, relPath, content) {
-  const abs = join4(cwd2, relPath);
-  if (existsSync3(abs)) return;
-  mkdirSync3(resolve2(abs, ".."), { recursive: true });
-  writeFileSync3(abs, content, "utf8");
+var __dirname2 = dirname4(fileURLToPath3(import.meta.url));
+function writeAgentFiles(cwd2, entries, opts = {}) {
+  const result = { created: [], overwritten: [], preserved: [] };
+  const existing = entries.filter((e) => existsSync5(join6(cwd2, e.relPath)));
+  if (opts.force && existing.length > 0) {
+    if (!opts.backupRoot) {
+      throw new Error(
+        "writeAgentFiles: force is set and existing agent 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, `agents-${stamp}`);
+    try {
+      for (const entry of existing) {
+        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 agent files to ${backupDir} (${err instanceof Error ? err.message : String(err)}). Aborting WITHOUT overwriting anything \u2014 no agent file was modified.`
+      );
+    }
+    result.backupDir = backupDir;
+  }
+  for (const entry of entries) {
+    const abs = join6(cwd2, entry.relPath);
+    const exists = existsSync5(abs);
+    if (exists && !opts.force) {
+      result.preserved.push(entry.relPath);
+      continue;
+    }
+    mkdirSync3(resolve2(abs, ".."), { recursive: true });
+    writeFileSync3(abs, entry.content, "utf8");
+    if (exists) result.overwritten.push(entry.relPath);
+    else result.created.push(entry.relPath);
+  }
+  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");
@@ -749,26 +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, modelsByRole) {
+  const projectName = config.project.name;
+  return [
+    { 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,
@@ -781,106 +1048,83 @@ No tasks in progress.
 `
       );
     }
-    const projectName = config.project.name;
-    const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-    const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    const leadModel = config.agents.lead.model;
-    const explorerModel = config.agents.explorer.model;
-    const consultantModel = config.agents.consultant?.model;
-    const builderModel = config.agents.builder.model;
-    const reviewerModel = config.agents.reviewer.model;
-    writeAgentFile(cwd2, ".claude/agents/lead.md", translateFrontmatterForClaudeCode(agentLead({ projectName }), "lead", leadModel));
-    writeAgentFile(cwd2, ".claude/agents/explorer.md", translateFrontmatterForClaudeCode(agentExplorer({ projectName, allowedPaths }), "explorer", explorerModel));
-    writeAgentFile(cwd2, ".claude/agents/consultant.md", translateFrontmatterForClaudeCode(agentConsultant({ projectName }), "consultant", consultantModel));
-    writeAgentFile(cwd2, ".claude/agents/builder.md", translateFrontmatterForClaudeCode(agentBuilder({ projectName, writablePaths }), "builder", builderModel));
-    writeAgentFile(cwd2, ".claude/agents/reviewer.md", translateFrontmatterForClaudeCode(agentReviewer({ projectName }), "reviewer", reviewerModel));
-    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) {
-    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 projectName = config.project.name;
-    const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-    const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    const leadModel = config.agents.lead.model;
-    const explorerModel = config.agents.explorer.model;
-    const consultantModel = config.agents.consultant?.model;
-    const builderModel = config.agents.builder.model;
-    const reviewerModel = config.agents.reviewer.model;
-    write2(".claude/agents/lead.md", translateFrontmatterForClaudeCode(agentLead({ projectName }), "lead", leadModel));
-    write2(".claude/agents/explorer.md", translateFrontmatterForClaudeCode(agentExplorer({ projectName, allowedPaths }), "explorer", explorerModel));
-    write2(".claude/agents/consultant.md", translateFrontmatterForClaudeCode(agentConsultant({ projectName }), "consultant", consultantModel));
-    write2(".claude/agents/builder.md", translateFrontmatterForClaudeCode(agentBuilder({ projectName, writablePaths }), "builder", builderModel));
-    write2(".claude/agents/reviewer.md", translateFrontmatterForClaudeCode(agentReviewer({ projectName }), "reviewer", reviewerModel));
-    mergeClaudeMcpJson(join5(cwd2, ".mcp.json"), config.tools.mcp.port, detectPackageManager(cwd2));
-    mergeClaudeSettingsJson(join5(cwd2, ".claude/settings.json"));
-    mergeClaudeSettingsLocalJson(join5(cwd2, ".claude/settings.local.json"));
+  async build(config, cwd2, opts = {}) {
+    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: join7(cwd2, config.storage.dir, "backups")
+    });
+    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, derived };
   }
   async migrate(config, _to, _cwd) {
     void config;
   }
-  async syncPermissions(cwd2) {
-    const AGENT_TOOLS = {
-      lead: [...MCP_CLAUDE_PERMISSIONS_LEAD],
-      explorer: [...MCP_CLAUDE_PERMISSIONS_EXPLORER],
-      consultant: [...MCP_CLAUDE_PERMISSIONS_CONSULTANT],
-      builder: [...MCP_CLAUDE_PERMISSIONS_BUILDER],
-      reviewer: [...MCP_CLAUDE_PERMISSIONS_REVIEWER]
-    };
-    for (const [agent, tools] of Object.entries(AGENT_TOOLS)) {
-      const filePath = join5(cwd2, ".claude", "agents", `${agent}.md`);
-      if (!existsSync4(filePath)) {
-        console.log(`  ${agent}.md not found \u2014 skipping`);
-        continue;
-      }
-      const content = readFileSync5(filePath, "utf-8");
-      const updated = content.replace(
-        /(tools:\n)((?:  - [^\n]+\n)*)/m,
-        (_match, header, toolsSection) => {
-          const nativeLines = toolsSection.split("\n").filter((line) => line.trim() && !line.includes("mcp__"));
-          const nativeSection = nativeLines.length ? nativeLines.join("\n") + "\n" : "";
-          const mcpSection = tools.map((t) => `  - ${t}`).join("\n") + "\n";
-          return header + nativeSection + mcpSection;
-        }
-      );
-      if (updated === content) {
-        console.log(`  ${agent}.md already in sync`);
-      } else {
-        writeFileSync4(filePath, updated, "utf-8");
-        console.log(`  ${agent}.md updated`);
-      }
-    }
+  /**
+   * No-op by design.
+   *
+   * This used to rewrite the `tools:` frontmatter block of every agent file,
+   * re-injecting the canonical `mcp__agent-harness-kit__*` allowlist. Agent
+   * files no longer declare `tools` at all: they inherit the full tool set
+   * (Task and every MCP tool included) and express restrictions as a
+   * `disallowedTools` denylist instead.
+   *
+   * Keeping the old rewrite alive would be actively harmful — on a project
+   * upgraded from an older version, whose agent files still carry a legacy
+   * `tools:` block, it would re-inject the allowlist and silently undo the
+   * migration on exactly the files that most need it. Run `ahk build` to
+   * regenerate agent files in the current shape.
+   */
+  async syncPermissions(_cwd) {
+    console.log("  Agent files inherit tools and declare a disallowedTools denylist \u2014");
+    console.log("  there is no permission allowlist to sync. Run `ahk build` to regenerate them.");
   }
 };
 
 // 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 [
+    { relPath: ".codex/agents/lead.toml", content: agentLeadToml({ projectName }) },
+    { relPath: ".codex/agents/explorer.toml", content: agentExplorerToml({ projectName }) },
+    { relPath: ".codex/agents/consultant.toml", content: agentConsultantToml({ projectName }) },
+    { relPath: ".codex/agents/builder.toml", content: agentBuilderToml({ projectName }) },
+    { relPath: ".codex/agents/reviewer.toml", content: agentReviewerToml({ projectName }) },
+    { relPath: ".codex/agents/default.toml", content: agentLeadAsDefaultToml({ projectName }) }
+  ];
+}
 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 -->
@@ -892,47 +1136,24 @@ No tasks in progress.
 `
       );
     }
-    const projectName = config.project.name;
-    const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-    const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    const leadModel = config.agents.lead.model;
-    const explorerModel = config.agents.explorer.model;
-    const consultantModel = config.agents.consultant?.model;
-    const builderModel = config.agents.builder.model;
-    const reviewerModel = config.agents.reviewer.model;
-    writeAgentFile(cwd2, ".codex/agents/lead.toml", agentLeadToml({ projectName, model: leadModel }));
-    writeAgentFile(cwd2, ".codex/agents/explorer.toml", agentExplorerToml({ projectName, allowedPaths, model: explorerModel }));
-    writeAgentFile(cwd2, ".codex/agents/consultant.toml", agentConsultantToml({ projectName, model: consultantModel }));
-    writeAgentFile(cwd2, ".codex/agents/builder.toml", agentBuilderToml({ projectName, writablePaths, model: builderModel }));
-    writeAgentFile(cwd2, ".codex/agents/reviewer.toml", agentReviewerToml({ projectName, model: reviewerModel }));
-    writeAgentFile(cwd2, ".codex/agents/default.toml", agentLeadAsDefaultToml({ projectName, model: leadModel }));
-    mergeCodexConfigToml(join6(cwd2, ".codex/config.toml"), config.tools.mcp.port, detectPackageManager(cwd2));
+    writeAgentFiles(cwd2, codexAgentFiles(config));
+    mergeCodexConfigToml(join8(cwd2, ".codex/config.toml"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
     appendGitignore(cwd2);
     writeSkills(cwd2, ".agents/skills");
   }
-  async build(config, cwd2) {
-    const write2 = (relPath, content) => {
-      const abs = join6(cwd2, relPath);
-      mkdirSync5(resolve4(abs, ".."), { recursive: true });
-      writeFileSync5(abs, content, "utf8");
-    };
-    write2("AGENTS.md", agentsMd(config));
-    const projectName = config.project.name;
-    const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-    const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    const leadModel = config.agents.lead.model;
-    const explorerModel = config.agents.explorer.model;
-    const consultantModel = config.agents.consultant?.model;
-    const builderModel = config.agents.builder.model;
-    const reviewerModel = config.agents.reviewer.model;
-    writeAgentFile(cwd2, ".codex/agents/lead.toml", agentLeadToml({ projectName, model: leadModel }));
-    writeAgentFile(cwd2, ".codex/agents/explorer.toml", agentExplorerToml({ projectName, allowedPaths, model: explorerModel }));
-    writeAgentFile(cwd2, ".codex/agents/consultant.toml", agentConsultantToml({ projectName, model: consultantModel }));
-    writeAgentFile(cwd2, ".codex/agents/builder.toml", agentBuilderToml({ projectName, writablePaths, model: builderModel }));
-    writeAgentFile(cwd2, ".codex/agents/reviewer.toml", agentReviewerToml({ projectName, model: reviewerModel }));
-    writeAgentFile(cwd2, ".codex/agents/default.toml", agentLeadAsDefaultToml({ projectName, model: leadModel }));
-    mergeCodexConfigToml(join6(cwd2, ".codex/config.toml"), config.tools.mcp.port, detectPackageManager(cwd2));
+  async build(config, cwd2, opts = {}) {
+    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: join8(cwd2, config.storage.dir, "backups")
+    });
+    mergeCodexConfigToml(join8(cwd2, ".codex/config.toml"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
     writeSkills(cwd2, ".agents/skills");
+    return { agents, derived };
   }
   async migrate(config, _to, _cwd) {
     void config;
@@ -943,23 +1164,31 @@ 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 [
+    { relPath: ".opencode/agents/lead.md", content: translateFrontmatterForOpenCode(agentLead({ projectName }), "lead") },
+    { relPath: ".opencode/agents/explorer.md", content: translateFrontmatterForOpenCode(agentExplorer({ projectName }), "explorer") },
+    { relPath: ".opencode/agents/consultant.md", content: translateFrontmatterForOpenCode(agentConsultant({ projectName }), "consultant") },
+    { relPath: ".opencode/agents/builder.md", content: translateFrontmatterForOpenCode(agentBuilder({ projectName }), "builder") },
+    { relPath: ".opencode/agents/reviewer.md", content: translateFrontmatterForOpenCode(agentReviewer({ projectName }), "reviewer") }
+  ];
+}
 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 -->
@@ -971,35 +1200,24 @@ No tasks in progress.
 `
       );
     }
-    const projectName = config.project.name;
-    const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-    const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    writeAgentFile(cwd2, ".opencode/agents/lead.md", translateFrontmatterForOpenCode(agentLead({ projectName })));
-    writeAgentFile(cwd2, ".opencode/agents/explorer.md", translateFrontmatterForOpenCode(agentExplorer({ projectName, allowedPaths })));
-    writeAgentFile(cwd2, ".opencode/agents/consultant.md", translateFrontmatterForOpenCode(agentConsultant({ projectName })));
-    writeAgentFile(cwd2, ".opencode/agents/builder.md", translateFrontmatterForOpenCode(agentBuilder({ projectName, writablePaths })));
-    writeAgentFile(cwd2, ".opencode/agents/reviewer.md", translateFrontmatterForOpenCode(agentReviewer({ projectName })));
-    mergeOpencodeJson(join7(cwd2, "opencode.json"), config.tools.mcp.port, detectPackageManager(cwd2));
+    writeAgentFiles(cwd2, opencodeAgentFiles(config));
+    mergeOpencodeJson(join9(cwd2, "opencode.json"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
     appendGitignore(cwd2);
     writeSkills(cwd2, ".opencode/skills");
   }
-  async build(config, cwd2) {
-    const write2 = (relPath, content) => {
-      const abs = join7(cwd2, relPath);
-      mkdirSync6(resolve5(abs, ".."), { recursive: true });
-      writeFileSync6(abs, content, "utf8");
-    };
-    write2("AGENTS.md", agentsMd(config));
-    const projectName = config.project.name;
-    const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-    const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    writeAgentFile(cwd2, ".opencode/agents/lead.md", translateFrontmatterForOpenCode(agentLead({ projectName })));
-    writeAgentFile(cwd2, ".opencode/agents/explorer.md", translateFrontmatterForOpenCode(agentExplorer({ projectName, allowedPaths })));
-    writeAgentFile(cwd2, ".opencode/agents/consultant.md", translateFrontmatterForOpenCode(agentConsultant({ projectName })));
-    writeAgentFile(cwd2, ".opencode/agents/builder.md", translateFrontmatterForOpenCode(agentBuilder({ projectName, writablePaths })));
-    writeAgentFile(cwd2, ".opencode/agents/reviewer.md", translateFrontmatterForOpenCode(agentReviewer({ projectName })));
-    mergeOpencodeJson(join7(cwd2, "opencode.json"), config.tools.mcp.port, detectPackageManager(cwd2));
+  async build(config, cwd2, opts = {}) {
+    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: join9(cwd2, config.storage.dir, "backups")
+    });
+    mergeOpencodeJson(join9(cwd2, "opencode.json"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
     writeSkills(cwd2, ".opencode/skills");
+    return { agents, derived };
   }
   async migrate(config, _to, _cwd) {
     void config;
@@ -1025,7 +1243,7 @@ function getMaterializer(provider) {
 
 // src/commands/build.ts
 async function runBuild(cwd2, opts) {
-  await buildOnce(cwd2);
+  await buildOnce(cwd2, opts.force);
   if (opts.sync) {
     p.log.step("Syncing agent permissions...");
     const config = await loadConfig(cwd2);
@@ -1037,27 +1255,79 @@ async function runBuild(cwd2, opts) {
     watch(cwd2, { recursive: false }, async (_, filename) => {
       if (filename?.startsWith("agent-harness-kit.config")) {
         p.log.step("Config changed \u2014 rebuilding...");
-        await buildOnce(cwd2);
+        await buildOnce(cwd2, false);
       }
     });
     await new Promise(() => {
     });
   }
 }
-async function buildOnce(cwd2) {
+async function buildOnce(cwd2, force) {
   const spinner6 = p.spinner();
   spinner6.start("Loading config...");
   try {
     const config = await loadConfig(cwd2);
     spinner6.message("Rebuilding files...");
     const materializer = getMaterializer(config.provider);
-    await materializer.build(config, cwd2);
-    spinner6.stop(pc.green("Build complete"));
-    p.log.success("AGENTS.md");
+    const report = await materializer.build(config, cwd2, { force });
+    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;
+    if (created.length > 0) {
+      p.log.info(`Created ${created.length} missing agent file(s):
+  ${created.join("\n  ")}`);
+    }
+    if (overwritten.length > 0) {
+      p.log.warn(
+        pc2.yellow(
+          `--force REGENERATED ${overwritten.length} existing agent file(s), discarding any customizations:
+  ` + overwritten.join("\n  ")
+        )
+      );
+      if (backupDir) {
+        p.log.info(pc2.yellow(`  Previous content backed up \u2192 ${backupDir}`));
+      }
+    }
+    if (preserved.length > 0) {
+      p.log.info(
+        `Left ${preserved.length} existing agent file(s) untouched \u2014 agent files are yours to edit.
+  Re-run with --force to regenerate them from the packaged templates (this DESTROYS your edits;
+  a backup is written first).`
+      );
+    }
   } 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);
   }
@@ -1065,34 +1335,41 @@ async function buildOnce(cwd2) {
 
 // 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 readFileSync6 } 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.`
@@ -1120,6 +1397,36 @@ function fileResponse(filePath) {
     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;
@@ -1220,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") {
@@ -1259,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 {
@@ -1274,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);
@@ -1296,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 readFileSync7 } 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;
@@ -1366,68 +1668,15 @@ function getProviderAgentInfo(provider) {
       return { agentsDir: ".claude/agents", ext: ".md" };
   }
 }
-function generateExpectedAgentContent(agentName, provider, vars) {
-  const { projectName, allowedPaths, writablePaths, model } = vars;
-  if (provider === "claude-code") {
-    const templateFns = {
-      lead: () => agentLead({ projectName }),
-      explorer: () => agentExplorer({ projectName, allowedPaths }),
-      consultant: () => agentConsultant({ projectName }),
-      builder: () => agentBuilder({ projectName, writablePaths }),
-      reviewer: () => agentReviewer({ projectName })
-    };
-    return translateFrontmatterForClaudeCode(templateFns[agentName](), agentName, model);
-  }
-  if (provider === "opencode") {
-    const templateFns = {
-      lead: () => agentLead({ projectName }),
-      explorer: () => agentExplorer({ projectName, allowedPaths }),
-      consultant: () => agentConsultant({ projectName }),
-      builder: () => agentBuilder({ projectName, writablePaths }),
-      reviewer: () => agentReviewer({ projectName })
-    };
-    return translateFrontmatterForOpenCode(templateFns[agentName]());
-  }
-  const tomlFns = {
-    lead: () => agentLeadToml({ projectName, model }),
-    explorer: () => agentExplorerToml({ projectName, allowedPaths, model }),
-    consultant: () => agentConsultantToml({ projectName, model }),
-    builder: () => agentBuilderToml({ projectName, writablePaths, model }),
-    reviewer: () => agentReviewerToml({ projectName, model })
-  };
-  return tomlFns[agentName]();
-}
-function checkAgentFilesAtRoot(agentsRoot, ext, provider, projectName, allowedPaths, writablePaths, models) {
+function checkAgentFilesAtRoot(agentsRoot, ext) {
   return AGENT_NAMES.map((name) => {
-    const filePath = join11(agentsRoot, `${name}${ext}`);
-    if (!existsSync9(filePath)) {
-      return { name, status: "missing" };
-    }
-    try {
-      const live = readFileSync7(filePath, "utf8");
-      const expected = generateExpectedAgentContent(name, provider, {
-        projectName,
-        allowedPaths,
-        writablePaths,
-        model: models[name]
-      });
-      return { name, status: live === expected ? "ok" : "outdated" };
-    } catch {
-      return { name, status: "outdated" };
-    }
+    const filePath = join12(agentsRoot, `${name}${ext}`);
+    return { name, status: existsSync10(filePath) ? "ok" : "missing" };
   });
 }
-function checkAgentFiles(cwd2, provider, projectName, allowedPaths, writablePaths, models) {
+function checkAgentFiles(cwd2, provider) {
   const { agentsDir, ext } = getProviderAgentInfo(provider);
-  return checkAgentFilesAtRoot(
-    join11(cwd2, agentsDir),
-    ext,
-    provider,
-    projectName,
-    allowedPaths,
-    writablePaths,
-    models
-  );
+  return checkAgentFilesAtRoot(join12(cwd2, agentsDir), ext);
 }
 function getProviderSkillsDir(provider) {
   switch (provider) {
@@ -1442,11 +1691,11 @@ 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 {
@@ -1460,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();
@@ -1475,33 +1724,23 @@ async function getDoctorStatus(cwd2) {
     };
   }
   const provider = config.provider;
-  const projectName = config.project.name;
-  const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-  const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-  const models = {
-    lead: config.agents.lead.model,
-    explorer: config.agents.explorer.model,
-    consultant: config.agents.consultant?.model,
-    builder: config.agents.builder.model,
-    reviewer: config.agents.reviewer.model
-  };
-  const agents = checkAgentFiles(cwd2, provider, projectName, allowedPaths, writablePaths, models);
+  const agents = checkAgentFiles(cwd2, provider);
   const skills = checkSkills(cwd2, provider);
   return { lib, agents, skills };
 }
 
 // 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) {
@@ -1522,17 +1761,13 @@ function printAgentsSection(agents) {
     return;
   }
   const missing = agents.filter((a) => a.status === "missing");
-  const outdated = agents.filter((a) => a.status === "outdated");
-  if (missing.length === 0 && outdated.length === 0) {
-    ok("agent files", "all up to date");
+  if (missing.length === 0) {
+    ok("agent files", "all present");
     return;
   }
   for (const agent of missing) {
     warn("agent files", `${agent.name} missing`, "run: ahk build");
   }
-  for (const agent of outdated) {
-    warn("agent files", `${agent.name} outdated`, "run: ahk build");
-  }
 }
 function printSkillsSection(skills) {
   if (skills.length === 0) {
@@ -1557,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);
@@ -1575,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);
@@ -1589,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 {
@@ -1606,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;
@@ -1640,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,
@@ -1652,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);
   }
@@ -1674,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);
   }
 }
@@ -1699,10 +1934,10 @@ function getProviderHealthFiles(provider) {
 }
 
 // src/commands/init.ts
-import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync8 } from "fs";
-import { join as join14 } from "path";
+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 pc7 from "picocolors";
+import pc8 from "picocolors";
 
 // src/schema/init.ts
 import * as v from "valibot";
@@ -1755,13 +1990,13 @@ var cliFormWithRetry = async (formFn, schema) => {
 
 // src/commands/init-helpers.ts
 import { randomUUID } from "crypto";
-import { existsSync as existsSync11, readFileSync as readFileSync8 } from "fs";
-import { join as join13 } from "path";
-import pc6 from "picocolors";
+import { existsSync as existsSync12, readFileSync as readFileSync8 } from "fs";
+import { join as join14 } from "path";
+import pc7 from "picocolors";
 function readProjectNameFromPackageJson(cwd2) {
   try {
-    const pkgPath2 = join13(cwd2, "package.json");
-    if (!existsSync11(pkgPath2)) return null;
+    const pkgPath2 = join14(cwd2, "package.json");
+    if (!existsSync12(pkgPath2)) return null;
     const content = readFileSync8(pkgPath2, "utf8");
     const pkg2 = JSON.parse(content);
     const name = pkg2?.name;
@@ -1772,10 +2007,11 @@ function readProjectNameFromPackageJson(cwd2) {
   }
 }
 function detectConfigExtension(cwd2) {
+  if (!isLocalInstallSatisfied(cwd2)) return "json";
   try {
-    if (existsSync11(join13(cwd2, "tsconfig.json"))) return "ts";
-    const pkgPath2 = join13(cwd2, "package.json");
-    if (!existsSync11(pkgPath2)) return "mjs";
+    if (existsSync12(join14(cwd2, "tsconfig.json"))) return "ts";
+    const pkgPath2 = join14(cwd2, "package.json");
+    if (!existsSync12(pkgPath2)) return "mjs";
     const pkg2 = JSON.parse(readFileSync8(pkgPath2, "utf8"));
     if (pkg2?.type === "module") return "mjs";
   } catch {
@@ -1783,7 +2019,6 @@ function detectConfigExtension(cwd2) {
   return "mjs";
 }
 function applyConfigDefaults(params) {
-  const models = params.models ?? {};
   const scope = params.scope ?? "local";
   const projectId = params.projectId ?? randomUUID();
   const baseStorage = {
@@ -1806,22 +2041,10 @@ function applyConfigDefaults(params) {
       docsPath: params.docsPath,
       agentsMd: "./AGENTS.md"
     },
-    agents: {
-      lead: { instructionsPath: null, ...models.lead && { model: models.lead } },
-      explorer: {
-        instructionsPath: null,
-        allowedPaths: [params.docsPath, "./src"],
-        ...models.explorer && { model: models.explorer }
-      },
-      builder: {
-        instructionsPath: null,
-        writablePaths: ["./src", "./tests"],
-        ...models.builder && { model: models.builder }
-      },
-      reviewer: { instructionsPath: null, ...models.reviewer && { model: models.reviewer } },
-      ...models.consultant && { consultant: { instructionsPath: null, model: models.consultant } },
-      custom: []
-    },
+    // No `agents` key: per-agent settings (model, role instructions) live in
+    // the generated agent file, which is user-owned. This object is the runtime
+    // twin of the config body emitted by configObjectBody() in templates.ts —
+    // drift between the two is the bug this pairing has to keep out.
     database: { type: "sqlite" },
     storage,
     health: {
@@ -1840,27 +2063,27 @@ function stripAnsi(str2) {
 function drawBox(lines) {
   const width = Math.max(...lines.map((l) => stripAnsi(l).length));
   const border = "\u2500".repeat(width);
-  console.log(pc6.yellow(`\u250C${border}\u2510`));
+  console.log(pc7.yellow(`\u250C${border}\u2510`));
   for (const line of lines) {
     const pad = width - stripAnsi(line).length;
     const padStr = pad > 0 ? " ".repeat(pad) : "";
-    console.log(pc6.yellow("\u2502") + line + padStr + pc6.yellow("\u2502"));
+    console.log(pc7.yellow("\u2502") + line + padStr + pc7.yellow("\u2502"));
   }
-  console.log(pc6.yellow(`\u2514${border}\u2518`));
+  console.log(pc7.yellow(`\u2514${border}\u2518`));
 }
 function printWelcomeMessage(projectName) {
   const sep = "\u2500".repeat(38);
   const lines = [
-    `  ${pc6.bold(pc6.white("agent-harness-kit"))}  `,
-    `  ${pc6.gray("\u2014")} harness scaffolding ${pc6.gray("\u2014")}  `,
-    `  ${pc6.gray(sep)}  `,
-    `  ${pc6.bold("Project:")}  ${projectName || "\u2014"}  `,
-    `  ${pc6.bold("Status:")}   ${pc6.green("ready to configure")}  `,
-    `  ${pc6.gray(sep)}  `,
-    `  ${pc6.gray("Next steps:")}  `,
-    `  ${pc6.gray("\u2192")} ${pc6.gray("Set up your AI provider config")}  `,
-    `  ${pc6.gray("\u2192")} ${pc6.gray("Run your health check to verify")}  `,
-    `  ${pc6.gray("\u2192")} ${pc6.gray("Start adding tasks for your agents")}  `
+    `  ${pc7.bold(pc7.white("agent-harness-kit"))}  `,
+    `  ${pc7.gray("\u2014")} harness scaffolding ${pc7.gray("\u2014")}  `,
+    `  ${pc7.gray(sep)}  `,
+    `  ${pc7.bold("Project:")}  ${projectName || "\u2014"}  `,
+    `  ${pc7.bold("Status:")}   ${pc7.green("ready to configure")}  `,
+    `  ${pc7.gray(sep)}  `,
+    `  ${pc7.gray("Next steps:")}  `,
+    `  ${pc7.gray("\u2192")} ${pc7.gray("Set up your AI provider config")}  `,
+    `  ${pc7.gray("\u2192")} ${pc7.gray("Run your health check to verify")}  `,
+    `  ${pc7.gray("\u2192")} ${pc7.gray("Start adding tasks for your agents")}  `
   ];
   console.log();
   drawBox(lines);
@@ -1868,22 +2091,50 @@ 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) {
     console.log(
-      pc7.yellow("\u26A0") + " " + pc7.bold("Project already initialized.") + pc7.dim(` (${existingConfig})`)
+      pc8.yellow("\u26A0") + " " + pc8.bold("Project already initialized.") + pc8.dim(` (${existingConfig})`)
     );
     console.log();
-    console.log(pc7.dim("Suggested next steps:"));
+    console.log(pc8.dim("Suggested next steps:"));
     console.log(
-      "  " + pc7.cyan("ahk build") + pc7.dim("         \u2014 re-sync agent files after updating the library")
+      "  " + pc8.cyan("ahk build") + pc8.dim("         \u2014 re-sync agent files after updating the library")
     );
-    console.log("  " + pc7.cyan("ahk build --sync") + pc7.dim("  \u2014 also sync agent permissions"));
+    console.log("  " + pc8.cyan("ahk build --sync") + pc8.dim("  \u2014 also sync agent permissions"));
     console.log(
-      "  " + pc7.cyan("ahk reset") + pc7.dim("         \u2014 wipe and re-initialize from scratch")
+      "  " + pc8.cyan("ahk reset") + pc8.dim("         \u2014 wipe and re-initialize from scratch")
     );
-    console.log("  " + pc7.cyan("ahk dashboard") + pc7.dim("         \u2014 open the harness dashboard"));
+    console.log("  " + pc8.cyan("ahk dashboard") + pc8.dim("         \u2014 open the harness dashboard"));
     process.exit(0);
   }
   const detectedName = flags.name ?? readProjectNameFromPackageJson(cwd2);
@@ -1942,52 +2193,25 @@ async function runInit(cwd2, flags) {
     { key: "builder", label: "Builder" },
     { key: "reviewer", label: "Reviewer" }
   ];
-  const modelOverrides = {};
-  if (provider === "claude-code" || provider === "codex-cli") {
-    const wantsModelCustomization = await p3.confirm({
-      message: "Customize the model per agent?",
-      initialValue: false
-    });
-    if (p3.isCancel(wantsModelCustomization)) {
-      p3.cancel("Cancelled.");
-      process.exit(0);
-    }
-    if (wantsModelCustomization) {
-      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);
-          }
-          modelOverrides[agent.key] = val;
-        }
-      } else {
-        for (const agent of AGENT_LABELS) {
-          const val = await p3.text({
-            message: `Model for ${agent.label} (Codex does not validate this value)`,
-            placeholder: "e.g. gpt-5 (empty or <3 chars = no override)"
-          });
-          if (p3.isCancel(val)) {
-            p3.cancel("Cancelled.");
-            process.exit(0);
-          }
-          const trimmed = val.trim();
-          if (trimmed.length >= 3) {
-            modelOverrides[agent.key] = trimmed;
-          }
-        }
+  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;
@@ -2081,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 {
@@ -2090,14 +2315,13 @@ async function runInit(cwd2, flags) {
       provider,
       docsPath,
       tasksAdapter,
-      models: modelOverrides,
       scope: storageScope
     });
     const materializer = getMaterializer(provider);
     const installDir = cwd2;
     configExt = detectConfigExtension(cwd2);
     const configFileName = `agent-harness-kit.config.${configExt}`;
-    const templateFn = configExt === "ts" ? configTs : configExt === "mjs" ? configMjs : configCjs;
+    const templateFn = configExt === "json" ? configJson : configExt === "ts" ? configTs : configExt === "mjs" ? configMjs : configCjs;
     const configContent = templateFn({
       name,
       description,
@@ -2105,23 +2329,17 @@ async function runInit(cwd2, flags) {
       docsPath,
       tasksAdapter,
       port: config.tools.mcp.port,
-      models: modelOverrides,
       scope: config.storage.scope,
       projectId: config.storage.projectId
     });
-    writeFileSync8(join14(installDir, configFileName), configContent, "utf8");
-    mkdirSync7(join14(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("");
@@ -2130,39 +2348,44 @@ async function runInit(cwd2, flags) {
     p3.log.error(err instanceof Error ? err.message : String(err));
     throw err;
   }
-  console.log(pc7.green("\u2713 Scaffolded harness in current directory"));
+  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";
   console.log("");
-  console.log(pc7.green(`\u2713 agent-harness-kit.config.${configExt}`));
-  console.log(pc7.green("\u2713 AGENTS.md"));
-  console.log(pc7.green("\u2713 health.sh"));
+  console.log(pc8.green(`\u2713 agent-harness-kit.config.${configExt}`));
+  console.log(pc8.green("\u2713 AGENTS.md"));
+  console.log(pc8.green("\u2713 health.sh"));
   console.log(
-    pc7.green(
+    pc8.green(
       storageScope === "global" ? "\u2713 ~/.harness/dbs/<projectId>/harness.db" : "\u2713 .harness/harness.db"
     )
   );
   console.log(
-    pc7.green(
+    pc8.green(
       storageScope === "global" ? "\u2713 ~/.harness/dbs/<projectId>/current.md" : "\u2713 .harness/current.md"
     )
   );
-  console.log(pc7.green("\u2713 .harness/storage-state.json"));
-  console.log(pc7.green(`\u2713 ${agentsDir}lead.md`));
-  console.log(pc7.green(`\u2713 ${agentsDir}explorer.md`));
-  console.log(pc7.green(`\u2713 ${agentsDir}builder.md`));
-  console.log(pc7.green(`\u2713 ${agentsDir}reviewer.md`));
-  console.log(pc7.green(`\u2713 ${mcpFile}`));
-  console.log(pc7.green("\u2713 .gitignore entries added"));
+  console.log(pc8.green("\u2713 .harness/storage-state.json"));
+  console.log(pc8.green(`\u2713 ${agentsDir}lead.md`));
+  console.log(pc8.green(`\u2713 ${agentsDir}explorer.md`));
+  console.log(pc8.green(`\u2713 ${agentsDir}builder.md`));
+  console.log(pc8.green(`\u2713 ${agentsDir}reviewer.md`));
+  console.log(pc8.green(`\u2713 ${mcpFile}`));
+  console.log(pc8.green("\u2713 .gitignore entries added"));
   console.log("");
-  console.log(pc7.cyan("\u2192") + ` Edit ${pc7.cyan("health.sh")} with your project checks`);
-  console.log(pc7.cyan("\u2192") + ` ${pc7.cyan("ahk task add")} to queue work for agents`);
+  console.log(pc8.cyan("\u2192") + ` Edit ${pc8.cyan("health.sh")} with your project checks`);
+  console.log(pc8.cyan("\u2192") + ` ${pc8.cyan("ahk task add")} to queue work for agents`);
   console.log(
-    pc7.cyan("\u2192") + ` Enrich your docs with knowledge graphs: ${pc7.cyan("https://github.com/safishamsi/graphify")}`
+    pc8.cyan("\u2192") + ` Enrich your docs with knowledge graphs: ${pc8.cyan("https://github.com/safishamsi/graphify")}`
   );
   const recommendations = [
     `   Give a try to Heimdall MCP: Transparent proxy that traces every MCP tool call with OpenTelemetry.  `,
-    `   Learn more: ${pc7.cyan("https://github.com/enmanuelmag/heimdall-mcp")}                              `
+    `   Learn more: ${pc8.cyan("https://github.com/enmanuelmag/heimdall-mcp")}                              `
   ];
   console.log("");
   drawBox(recommendations);
@@ -2170,7 +2393,7 @@ async function runInit(cwd2, flags) {
 
 // src/commands/migrate.ts
 import * as p4 from "@clack/prompts";
-import pc8 from "picocolors";
+import pc9 from "picocolors";
 async function runMigrate(cwd2, opts) {
   const config = await loadConfig(cwd2);
   let target;
@@ -2192,7 +2415,7 @@ async function runMigrate(cwd2, opts) {
     target = val;
   }
   if (target === config.provider) {
-    console.log(pc8.dim(`Already on ${target} \u2014 nothing to migrate.`));
+    console.log(pc9.dim(`Already on ${target} \u2014 nothing to migrate.`));
     return;
   }
   const spinner6 = p4.spinner();
@@ -2200,21 +2423,21 @@ async function runMigrate(cwd2, opts) {
   try {
     const targetMaterializer = getMaterializer(target);
     await targetMaterializer.build(config, cwd2);
-    spinner6.stop(pc8.green(`Migrated to ${target}`));
+    spinner6.stop(pc9.green(`Migrated to ${target}`));
     p4.log.warn(`Update agent-harness-kit.config.ts: set provider: '${target}'`);
     p4.log.warn(`Then run: ahk build`);
   } catch (err) {
-    spinner6.stop(pc8.red("Migration failed"));
+    spinner6.stop(pc9.red("Migration failed"));
     p4.log.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
 }
 
 // src/commands/migrate-storage.ts
-import { copyFileSync, existsSync as existsSync12, 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 join15, resolve as resolve7 } from "path";
-import pc9 from "picocolors";
+import { dirname as dirname7, join as join16, resolve as resolve6 } from "path";
+import pc10 from "picocolors";
 function log5(msg) {
   console.log(msg);
 }
@@ -2225,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" ? join15(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 path = join15(backupsDir, `pre-migrate-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.json`);
+  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.`
@@ -2244,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 (existsSync12(`${srcPath}${suffix}`)) {
+    if (existsSync14(`${srcPath}${suffix}`)) {
       copyFileSync(`${srcPath}${suffix}`, `${destPath}${suffix}`);
     }
   }
-  if (!existsSync12(destPath)) {
+  if (!existsSync14(destPath)) {
     throw new Error(`Copy verification failed: ${destPath} does not exist after copy.`);
   }
 }
@@ -2279,13 +2502,13 @@ async function runMigrateStorage(cwd2, opts, homeDir = homedir3()) {
       } finally {
         await db.close();
       }
-      log5(pc9.dim("storage-state.json was missing; no data found at either candidate location. Nothing to migrate \u2014 state recorded."));
+      log5(pc10.dim("storage-state.json was missing; no data found at either candidate location. Nothing to migrate \u2014 state recorded."));
       return;
     }
     realScope = localCount > 0 ? "local" : "global";
     realDbType = "sqlite";
     log5(
-      pc9.yellow(
+      pc10.yellow(
         `storage-state.json was missing. Detected real data at ${realScope} sqlite location (${realScope === "local" ? localPath : globalPath}) \u2014 using it as the migration source.`
       )
     );
@@ -2296,7 +2519,7 @@ async function runMigrateStorage(cwd2, opts, homeDir = homedir3()) {
   const desiredScope = config.storage.scope;
   const desiredDbType = config.database.type;
   if (realScope === desiredScope && realDbType === desiredDbType) {
-    log5(pc9.green(`\u2713 Storage already matches config (scope=${desiredScope}, database=${desiredDbType}) \u2014 nothing to migrate.`));
+    log5(pc10.green(`\u2713 Storage already matches config (scope=${desiredScope}, database=${desiredDbType}) \u2014 nothing to migrate.`));
     return;
   }
   if (realDbType !== "sqlite") {
@@ -2310,8 +2533,8 @@ async function runMigrateStorage(cwd2, opts, homeDir = homedir3()) {
   return migrateAcrossDbType(cwd2, config, homeDir, realScope, opts);
 }
 async function probeTaskCount(dbPath) {
-  if (!existsSync12(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();
@@ -2327,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 (!existsSync12(srcDb)) {
+  if (!existsSync14(srcDb)) {
     fail(`Source database not found at ${srcDb} (expected ${fromScope} scope) \u2014 nothing to move.`);
   }
-  const destExists = existsSync12(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 {
@@ -2347,58 +2570,58 @@ 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 {
         await backupDriver.close();
       }
       const backupPath = await backupDestination(cwd2, config.storage.dir, data);
-      log5(pc9.yellow(`  Backed up existing destination data \u2192 ${backupPath}`));
+      log5(pc10.yellow(`  Backed up existing destination data \u2192 ${backupPath}`));
     }
   }
   if (opts.dryRun) {
-    log5(pc9.dim(`[dry-run] Would copy ${srcDb} \u2192 ${destDb} (scope ${fromScope} \u2192 ${toScope}), and move current.md.`));
+    log5(pc10.dim(`[dry-run] Would copy ${srcDb} \u2192 ${destDb} (scope ${fromScope} \u2192 ${toScope}), and move current.md.`));
     return;
   }
   copySqliteFile(srcDb, destDb);
-  log5(pc9.green(`\u2713 Copied database ${srcDb} \u2192 ${destDb}`));
-  if (existsSync12(srcMd)) {
-    mkdirSync8(dirname7(destMd), { recursive: true });
+  log5(pc10.green(`\u2713 Copied database ${srcDb} \u2192 ${destDb}`));
+  if (existsSync14(srcMd)) {
+    mkdirSync7(dirname7(destMd), { recursive: true });
     copyFileSync(srcMd, destMd);
-    log5(pc9.green(`\u2713 Copied current.md ${srcMd} \u2192 ${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 (existsSync12(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);
   } finally {
     await db.close();
   }
-  log5(pc9.green(`\u2713 Storage migrated: scope ${fromScope} \u2192 ${toScope}`));
+  log5(pc10.green(`\u2713 Storage migrated: scope ${fromScope} \u2192 ${toScope}`));
 }
 async function migrateAcrossDbType(cwd2, config, homeDir, sourceScope, opts) {
   const sqlitePath = defaultSqlitePathForConfig(config);
   const srcPath = resolveSqlitePathForScope(sourceScope, sqlitePath, cwd2, config, homeDir);
-  if (!existsSync12(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 {
@@ -2424,7 +2647,7 @@ async function migrateAcrossDbType(cwd2, config, homeDir, sourceScope, opts) {
     }
     if (opts.dryRun) {
       log5(
-        pc9.dim(
+        pc10.dim(
           `[dry-run] Would migrate ${sourceCounts.tasks} task(s) from sqlite (${sourceScope}, ${srcPath}) to ${config.database.type}${destEmpty ? "" : " (destination has data \u2014 would back up first, then overwrite)"}.`
         )
       );
@@ -2434,34 +2657,34 @@ async function migrateAcrossDbType(cwd2, config, homeDir, sourceScope, opts) {
     if (!destEmpty && opts.force) {
       const currentDestData = await destDb.exportJson();
       backupPath = await backupDestination(cwd2, config.storage.dir, currentDestData);
-      log5(pc9.yellow(`  Backed up existing destination data \u2192 ${backupPath}`));
+      log5(pc10.yellow(`  Backed up existing destination data \u2192 ${backupPath}`));
     }
     await destDb.importFullExport(sourceData, config.database.type, { truncateFirst: !destEmpty });
     await destDb.writeStorageState(cwd2);
     log5(
-      pc9.green(
+      pc10.green(
         `\u2713 Migrated ${sourceData.tasks.length} task(s), ${sourceData.actions.length} action(s) from sqlite (${sourceScope}) \u2192 ${config.database.type}.`
       )
     );
-    if (backupPath) log5(pc9.dim(`  Destination backup: ${backupPath}`));
-    log5(pc9.yellow(`  Note: the original sqlite file at ${srcPath} was NOT deleted \u2014 remove it manually once you've verified the migration.`));
+    if (backupPath) log5(pc10.dim(`  Destination backup: ${backupPath}`));
+    log5(pc10.yellow(`  Note: the original sqlite file at ${srcPath} was NOT deleted \u2014 remove it manually once you've verified the migration.`));
   } finally {
     await destDb.close();
   }
 }
 
 // src/commands/reset.ts
-import { existsSync as existsSync13, 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 join16, resolve as resolve8 } from "path";
+import { join as join17, resolve as resolve7 } from "path";
 import * as p5 from "@clack/prompts";
-import pc10 from "picocolors";
+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 (!existsSync13(agentDirPath)) {
-    console.log(pc10.yellow(`  Skipping agent files \u2014 directory not found: ${agentDirPath}`));
+  const agentDirPath = resolve7(cwd2, agentDir);
+  if (!existsSync15(agentDirPath)) {
+    console.log(pc11.yellow(`  Skipping agent files \u2014 directory not found: ${agentDirPath}`));
     return;
   }
   const existingFiles = [];
@@ -2473,11 +2696,11 @@ async function resetAgentMds(cwd2, provider) {
       }
     }
   } catch {
-    console.log(pc10.yellow(`  Skipping agent files \u2014 ${agentDirPath} is not readable`));
+    console.log(pc11.yellow(`  Skipping agent files \u2014 ${agentDirPath} is not readable`));
     return;
   }
   if (existingFiles.length === 0) {
-    console.log(pc10.yellow(`  No agent MD files found in ${agentDir}/`));
+    console.log(pc11.yellow(`  No agent MD files found in ${agentDir}/`));
     return;
   }
   for (const file of existingFiles) {
@@ -2486,19 +2709,19 @@ async function resetAgentMds(cwd2, provider) {
       initialValue: true
     });
     if (p5.isCancel(confirm3)) {
-      console.log(pc10.red("  Cancelled by user."));
+      console.log(pc11.red("  Cancelled by user."));
       return;
     }
     if (confirm3) {
       try {
-        const filePath = join16(agentDirPath, file);
+        const filePath = join17(agentDirPath, file);
         rmSync2(filePath, { force: true });
-        console.log(pc10.green(`  Removed ${file}`));
+        console.log(pc11.green(`  Removed ${file}`));
       } catch {
-        console.error(pc10.red(`  Failed to remove ${file}`));
+        console.error(pc11.red(`  Failed to remove ${file}`));
       }
     } else {
-      console.log(pc10.cyan(`  Skipped ${file}`));
+      console.log(pc11.cyan(`  Skipped ${file}`));
     }
   }
 }
@@ -2507,21 +2730,21 @@ async function runReset(cwd2, opts) {
   try {
     config = await loadConfig(cwd2);
   } catch {
-    console.error(pc10.red("\u2717 No agent-harness-kit.config found. Run: ahk init"));
+    console.error(pc11.red("\u2717 No agent-harness-kit.config found. Run: ahk init"));
     process.exit(1);
   }
   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 && existsSync13(dbPath)) {
+  if (dbPath && existsSync15(dbPath)) {
     if (opts.force) {
       resetDb = true;
     } else {
       if (config.database.type !== "sqlite") {
-        console.log(pc10.yellow(`  Skipping DB reset \u2014 database type "${config.database.type}" is not managed by this command.`));
+        console.log(pc11.yellow(`  Skipping DB reset \u2014 database type "${config.database.type}" is not managed by this command.`));
         resetDb = false;
       } else {
         const confirm3 = await p5.confirm({
@@ -2529,16 +2752,16 @@ async function runReset(cwd2, opts) {
           initialValue: true
         });
         if (p5.isCancel(confirm3)) {
-          console.log(pc10.red("  Cancelled by user."));
+          console.log(pc11.red("  Cancelled by user."));
           return;
         }
         resetDb = confirm3;
       }
     }
   } else if (!dbPath) {
-    console.log(pc10.dim(`  Skipping DB reset \u2014 remote ${config.database.type} database is not managed by this command.`));
+    console.log(pc11.dim(`  Skipping DB reset \u2014 remote ${config.database.type} database is not managed by this command.`));
   }
-  if (existsSync13(featureListPath)) {
+  if (existsSync15(featureListPath)) {
     if (opts.force) {
       resetFeatureList = true;
     } else {
@@ -2547,7 +2770,7 @@ async function runReset(cwd2, opts) {
         initialValue: true
       });
       if (p5.isCancel(confirm3)) {
-        console.log(pc10.red("  Cancelled by user."));
+        console.log(pc11.red("  Cancelled by user."));
         return;
       }
       resetFeatureList = confirm3;
@@ -2561,17 +2784,17 @@ async function runReset(cwd2, opts) {
       rmSync2(dbPath, { force: true });
       rmSync2(`${dbPath}-wal`, { force: true });
       rmSync2(`${dbPath}-shm`, { force: true });
-      console.log(pc10.green(`  \u2713 Removed ${dbPath}`));
+      console.log(pc11.green(`  \u2713 Removed ${dbPath}`));
     } catch {
-      console.error(pc10.red(`  \u2717 Failed to remove ${dbPath}`));
+      console.error(pc11.red(`  \u2717 Failed to remove ${dbPath}`));
     }
   }
   if (resetFeatureList) {
     try {
       rmSync2(featureListPath, { force: true });
-      console.log(pc10.green(`  \u2713 Removed ${storageDir}/feature_list.json`));
+      console.log(pc11.green(`  \u2713 Removed ${storageDir}/feature_list.json`));
     } catch {
-      console.error(pc10.red(`  \u2717 Failed to remove ${featureListPath}`));
+      console.error(pc11.red(`  \u2717 Failed to remove ${featureListPath}`));
     }
   }
   if (resetAgentMdsFlag) {
@@ -2579,16 +2802,16 @@ async function runReset(cwd2, opts) {
     await resetAgentMds(cwd2, opts.provider || "claude-code");
   }
   if (!resetDb && !resetFeatureList && !resetAgentMdsFlag) {
-    console.log(pc10.yellow("  Nothing to reset (all items missing or skipped)."));
+    console.log(pc11.yellow("  Nothing to reset (all items missing or skipped)."));
     return;
   }
   console.log("");
-  console.log(pc10.green('\u2713 Reset complete. Run "ahk init" to scaffold a fresh harness.'));
+  console.log(pc11.green('\u2713 Reset complete. Run "ahk init" to scaffold a fresh harness.'));
 }
 
 // src/core/mcp-server.ts
-import { existsSync as existsSync15, mkdirSync as mkdirSync9, readdirSync as readdirSync2, readFileSync as readFileSync10, statSync, writeFileSync as writeFileSync10 } from "fs";
-import { join as join18, 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 {
@@ -2597,45 +2820,20 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 // src/core/permissions-check.ts
-import { existsSync as existsSync14, readFileSync as readFileSync9 } from "fs";
-import { join as join17 } from "path";
-var CANONICAL = {
-  lead: [...MCP_CLAUDE_PERMISSIONS_LEAD],
-  explorer: [...MCP_CLAUDE_PERMISSIONS_EXPLORER],
-  consultant: [...MCP_CLAUDE_PERMISSIONS_CONSULTANT],
-  builder: [...MCP_CLAUDE_PERMISSIONS_BUILDER],
-  reviewer: [...MCP_CLAUDE_PERMISSIONS_REVIEWER]
-};
-function parseToolsFromFrontmatter(content) {
-  const match = content.match(/^---\n([\s\S]*?)\n---/m);
-  if (!match) return [];
-  const fm = match[1];
-  const toolsMatch = fm.match(/^tools:\n((?:  - [^\n]+\n?)*)/m);
-  if (!toolsMatch) return [];
-  return toolsMatch[1].split("\n").map((l) => l.trim().replace(/^- /, "")).filter((l) => l.startsWith("mcp__"));
-}
+import { existsSync as existsSync16 } from "fs";
+import { join as join18 } from "path";
+var AGENTS = ["lead", "explorer", "consultant", "builder", "reviewer"];
 function checkPermissionsSync(cwd2, config) {
   if (config.provider !== "claude-code") {
     return { in_sync: true };
   }
   const agents = {};
   let in_sync = true;
-  for (const agent of ["lead", "explorer", "consultant", "builder", "reviewer"]) {
-    const filePath = join17(cwd2, ".claude", "agents", `${agent}.md`);
-    if (!existsSync14(filePath)) {
-      const missing2 = CANONICAL[agent];
-      agents[agent] = { ok: false, missing: missing2, extra: [] };
-      in_sync = false;
-      continue;
-    }
-    const content = readFileSync9(filePath, "utf-8");
-    const installed = parseToolsFromFrontmatter(content);
-    const canonical = CANONICAL[agent];
-    const missing = canonical.filter((t) => !installed.includes(t));
-    const extra = installed.filter((t) => !canonical.includes(t));
-    const ok3 = missing.length === 0 && extra.length === 0;
-    if (!ok3) in_sync = false;
-    agents[agent] = { ok: ok3, missing, extra };
+  for (const agent of AGENTS) {
+    const filePath = join18(cwd2, ".claude", "agents", `${agent}.md`);
+    const exists = existsSync16(filePath);
+    if (!exists) in_sync = false;
+    agents[agent] = exists ? { ok: true } : { ok: false, reason: "missing_file" };
   }
   return { in_sync, agents };
 }
@@ -2645,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: {
@@ -2660,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"]
@@ -2683,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"]
@@ -2758,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"]
     }
   },
   {
@@ -2812,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"]
@@ -2825,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"]
     }
   },
   {
@@ -2885,7 +3108,7 @@ var TOOLS = [
   },
   {
     name: "permissions.check",
-    description: "Check whether the .claude/agents/*.md tool permission lists are in sync with the current canonical permission constants. Returns per-agent diff with missing and extra tools. Call this at session start to detect outdated agent files after an ahk upgrade.",
+    description: 'Check that a .claude/agents/*.md definition file exists for every role. Returns { in_sync, agents } where each agent is { ok } or { ok: false, reason: "missing_file" }. Agent file CONTENTS are never inspected \u2014 they are meant to be customised freely \u2014 so this never reports drift, only absence. Run `ahk build` to restore a missing file.',
     inputSchema: { type: "object", properties: {}, required: [] }
   },
   {
@@ -2906,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: {} } }
@@ -2931,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");
@@ -2994,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");
@@ -3012,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");
@@ -3051,11 +3289,11 @@ 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 = join18(cwd2, "package.json");
-      if (!existsSync15(pkgPath2)) {
+      const pkgPath2 = join19(cwd2, "package.json");
+      if (!existsSync17(pkgPath2)) {
         return ok2("package.json not found in project root", true);
       }
       const pkg2 = JSON.parse(readFileSync10(pkgPath2, "utf8"));
@@ -3064,9 +3302,9 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
         dependencies: pkg2.dependencies ?? {},
         devDependencies: pkg2.devDependencies ?? {}
       };
-      const harnessDir = join18(cwd2, ".harness");
-      mkdirSync9(harnessDir, { recursive: true });
-      writeFileSync10(join18(harnessDir, "deps-lock.json"), JSON.stringify(snapshot, null, 2), "utf8");
+      const harnessDir = join19(cwd2, ".harness");
+      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",
@@ -3075,12 +3313,12 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
       );
     }
     case "deps.check": {
-      const pkgPath2 = join18(cwd2, "package.json");
-      const lockPath = join18(cwd2, ".harness", "deps-lock.json");
-      if (!existsSync15(pkgPath2)) {
+      const pkgPath2 = join19(cwd2, "package.json");
+      const lockPath = join19(cwd2, ".harness", "deps-lock.json");
+      if (!existsSync17(pkgPath2)) {
         return ok2("package.json not found in project root", true);
       }
-      if (!existsSync15(lockPath)) {
+      if (!existsSync17(lockPath)) {
         return ok2(
           JSON.stringify({
             status: "no-snapshot",
@@ -3131,9 +3369,10 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
       const status = await getDoctorStatus(cwd2);
       const result = {
         lib: { current: status.lib.current, latest: status.lib.latest, outdated: status.lib.outdated },
+        // Agents are existence-checked only — there is no `outdated` bucket.
+        // Hand-edited agent definitions are supported and must not be flagged.
         agents: {
           missing: status.agents.filter((a) => a.status === "missing").map((a) => a.name),
-          outdated: status.agents.filter((a) => a.status === "outdated").map((a) => a.name),
           ok: status.agents.filter((a) => a.status === "ok").map((a) => a.name)
         },
         skills: {
@@ -3142,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);
@@ -3181,7 +3420,7 @@ function collectMarkdownFiles(dir) {
   const files = [];
   try {
     for (const entry of readdirSync2(dir)) {
-      const full = join18(dir, entry);
+      const full = join19(dir, entry);
       const stat = statSync(full);
       if (stat.isDirectory()) {
         files.push(...collectMarkdownFiles(full));
@@ -3206,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) {
@@ -3217,14 +3468,8 @@ async function runServe(cwd2, opts) {
 `);
   const syncResult = checkPermissionsSync(cwd2, config);
   if (!syncResult.in_sync && syncResult.agents) {
-    const affected = Object.entries(syncResult.agents).filter(([, r]) => !r.ok).map(([name, r]) => {
-      const parts = [];
-      if (r.missing.length) parts.push(`missing: ${r.missing.map((t) => t.replace("mcp__agent-harness-kit__", "")).join(", ")}`);
-      if (r.extra.length) parts.push(`extra: ${r.extra.map((t) => t.replace("mcp__agent-harness-kit__", "")).join(", ")}`);
-      return `${name} (${parts.join("; ")})`;
-    }).join("\n   ");
-    process.stderr.write(`[agent-harness-kit] Agent permissions out of sync. Run: ahk build --sync
-   ${affected}
+    const affected = Object.entries(syncResult.agents).filter(([, r]) => !r.ok).map(([name]) => name).join(", ");
+    process.stderr.write(`[agent-harness-kit] Agent definition files missing: ${affected}. Run: ahk build
 `);
   }
   await startMcpServer(config, cwd2);
@@ -3232,12 +3477,12 @@ async function runServe(cwd2, opts) {
 
 // src/commands/status.ts
 import Table from "cli-table3";
-import pc11 from "picocolors";
+import pc12 from "picocolors";
 var STATUS_COLOR = {
-  pending: (s) => pc11.dim(s),
-  in_progress: (s) => pc11.cyan(s),
-  done: (s) => pc11.green(s),
-  blocked: (s) => pc11.red(s)
+  pending: (s) => pc12.dim(s),
+  in_progress: (s) => pc12.cyan(s),
+  done: (s) => pc12.green(s),
+  blocked: (s) => pc12.red(s)
 };
 async function runStatus(cwd2, opts) {
   const config = await loadConfig(cwd2);
@@ -3258,11 +3503,11 @@ async function runStatus(cwd2, opts) {
       return;
     }
     if (tasks.length === 0) {
-      console.log(pc11.dim("No tasks yet. Run: ahk task add"));
+      console.log(pc12.dim("No tasks yet. Run: ahk task add"));
       return;
     }
     const table = new Table({
-      head: ["ID", "Slug", "Title", "Status", "Assigned", "Started"].map((h) => pc11.bold(h)),
+      head: ["ID", "Slug", "Title", "Status", "Assigned", "Started"].map((h) => pc12.bold(h)),
       style: { head: [], border: [] }
     });
     for (const t of tasks) {
@@ -3280,12 +3525,12 @@ async function runStatus(cwd2, opts) {
     const inProgress = tasks.filter((t) => t.status === "in_progress");
     if (inProgress.length > 0) {
       console.log("");
-      console.log(pc11.bold("Active actions:"));
+      console.log(pc12.bold("Active actions:"));
       for (const t of inProgress) {
         const actions = await db.getActionsForTask(t.id);
         const active = actions.filter((a) => a.status === "in_progress");
         for (const a of active) {
-          console.log(`  ${pc11.cyan(a.agent.padEnd(10))} \u2192 task #${t.id} ${t.slug}`);
+          console.log(`  ${pc12.cyan(a.agent.padEnd(10))} \u2192 task #${t.id} ${t.slug}`);
         }
       }
     }
@@ -3294,10 +3539,10 @@ async function runStatus(cwd2, opts) {
       const fn = STATUS_COLOR[s.status] ?? ((x) => x);
       return `${fn(s.status)}: ${s.total}`;
     });
-    console.log(pc11.dim("Tasks \u2014 ") + parts.join(pc11.dim(" | ")));
+    console.log(pc12.dim("Tasks \u2014 ") + parts.join(pc12.dim(" | ")));
     const archivedTasks = await db.getArchivedTasks();
     if (archivedTasks.length > 0) {
-      console.log(pc11.dim(`${archivedTasks.length} archived (use \`ahk task list --archived\` to view)`));
+      console.log(pc12.dim(`${archivedTasks.length} archived (use \`ahk task list --archived\` to view)`));
     }
   } finally {
     await db.close();
@@ -3305,13 +3550,13 @@ async function runStatus(cwd2, opts) {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync16, readFileSync as readFileSync11 } from "fs";
-import { join as join19, resolve as resolve10 } from "path";
-import pc12 from "picocolors";
+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(join19(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") {
@@ -3325,44 +3570,44 @@ async function runSync(cwd2, opts) {
   }
 }
 async function syncIn(featureListPath, db, dryRun) {
-  if (!existsSync16(featureListPath)) {
-    console.log(pc12.dim(`feature_list.json not found at ${featureListPath} \u2014 skipping in-sync`));
+  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(readFileSync11(featureListPath, "utf8"));
   } catch (err) {
-    console.error(pc12.red(`Failed to parse feature_list.json: ${err}`));
+    console.error(pc13.red(`Failed to parse feature_list.json: ${err}`));
     process.exit(1);
   }
   if (dryRun) {
-    console.log(pc12.bold("Dry run \u2014 in-sync (feature_list.json \u2192 SQLite):"));
+    console.log(pc13.bold("Dry run \u2014 in-sync (feature_list.json \u2192 SQLite):"));
     for (const t of seeds) {
       const existing = await db.getTaskBySlug(t.slug);
-      console.log(`  ${existing ? pc12.dim("skip") : pc12.green("add ")} ${t.slug}`);
+      console.log(`  ${existing ? pc13.dim("skip") : pc13.green("add ")} ${t.slug}`);
     }
     return;
   }
   const result = await db.syncFromFeatureList(seeds);
-  console.log(pc12.green(`\u2713 In-sync: ${result.added} added, ${result.skipped} already existed`));
+  console.log(pc13.green(`\u2713 In-sync: ${result.added} added, ${result.skipped} already existed`));
 }
 async function syncOut(db, cwd2, dryRun) {
   if (dryRun) {
     const tasks = await db.getTasks();
-    console.log(pc12.bold("Dry run \u2014 out-sync (SQLite \u2192 feature_list.json):"));
+    console.log(pc13.bold("Dry run \u2014 out-sync (SQLite \u2192 feature_list.json):"));
     console.log(`  ${tasks.length} tasks would be written`);
     return;
   }
   await db.writeFeatureList(cwd2);
-  console.log(pc12.green("\u2713 Out-sync: feature_list.json updated"));
+  console.log(pc13.green("\u2713 Out-sync: feature_list.json updated"));
 }
 
 // src/commands/task/add.ts
 import * as p6 from "@clack/prompts";
-import pc13 from "picocolors";
+import pc14 from "picocolors";
 async function runTaskAdd(cwd2) {
-  p6.intro(pc13.bold("agent-harness-kit \u2014 add task"));
+  p6.intro(pc14.bold("agent-harness-kit \u2014 add task"));
   const title = await cliFormWithRetry(
     async () => {
       const val = await p6.text({ message: "Task title" });
@@ -3405,10 +3650,10 @@ async function runTaskAdd(cwd2) {
     await db.writeFeatureList(cwd2);
     await db.close();
     spinner6.stop("");
-    console.log(pc13.green(`\u2713 Task #${task2.id} added \u2014 ${task2.slug} (pending)`));
-    console.log(pc13.cyan("\u2192") + " " + pc13.cyan("ahk status") + " to see all tasks");
+    console.log(pc14.green(`\u2713 Task #${task2.id} added \u2014 ${task2.slug} (pending)`));
+    console.log(pc14.cyan("\u2192") + " " + pc14.cyan("ahk status") + " to see all tasks");
   } catch (err) {
-    spinner6.stop(pc13.red("Failed"));
+    spinner6.stop(pc14.red("Failed"));
     p6.log.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
@@ -3416,17 +3661,17 @@ async function runTaskAdd(cwd2) {
 
 // src/commands/task/done.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync17 } from "fs";
-import { resolve as resolve11 } from "path";
-import pc14 from "picocolors";
+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 (existsSync17(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(pc14.red("\u2717 Health check failed \u2014 cannot mark task as done."));
+        console.error(pc15.red("\u2717 Health check failed \u2014 cannot mark task as done."));
         if (result.stdout) console.error(result.stdout);
         if (result.stderr) console.error(result.stderr);
         process.exit(1);
@@ -3439,16 +3684,16 @@ async function runTaskDone(cwd2, idOrSlug) {
     const isId = !isNaN(parsed);
     const task2 = isId ? await db.getTaskById(parsed) : await db.getTaskBySlug(idOrSlug);
     if (!task2) {
-      console.error(pc14.red(`Task not found: ${idOrSlug}`));
+      console.error(pc15.red(`Task not found: ${idOrSlug}`));
       process.exit(1);
     }
     if (task2.status === "done") {
-      console.log(pc14.dim(`Task #${task2.id} is already done.`));
+      console.log(pc15.dim(`Task #${task2.id} is already done.`));
       return;
     }
     await db.updateTaskStatus(task2.id, "done");
     await db.writeFeatureList(cwd2);
-    console.log(pc14.green(`\u2713 Task #${task2.id} \u2014 ${task2.slug} marked as done`));
+    console.log(pc15.green(`\u2713 Task #${task2.id} \u2014 ${task2.slug} marked as done`));
   } finally {
     await db.close();
   }
@@ -3456,9 +3701,9 @@ async function runTaskDone(cwd2, idOrSlug) {
 
 // src/commands/task/edit.ts
 import * as p7 from "@clack/prompts";
-import pc15 from "picocolors";
+import pc16 from "picocolors";
 async function runTaskEdit(cwd2) {
-  p7.intro(pc15.bold("agent-harness-kit \u2014 edit task"));
+  p7.intro(pc16.bold("agent-harness-kit \u2014 edit task"));
   const config = await loadConfig(cwd2);
   const db = await openDB(config, cwd2);
   try {
@@ -3536,9 +3781,9 @@ async function runTaskEdit(cwd2) {
       await db.updateTaskAcceptance(task2.id, newAcceptance);
       await db.writeFeatureList(cwd2);
       spinner6.stop("");
-      console.log(pc15.green(`\u2713 Task #${task2.id} updated \u2014 ${newSlug}`));
+      console.log(pc16.green(`\u2713 Task #${task2.id} updated \u2014 ${newSlug}`));
     } catch (err) {
-      spinner6.stop(pc15.red("Failed"));
+      spinner6.stop(pc16.red("Failed"));
       p7.log.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
@@ -3549,12 +3794,12 @@ async function runTaskEdit(cwd2) {
 
 // src/commands/task/list.ts
 import Table2 from "cli-table3";
-import pc16 from "picocolors";
+import pc17 from "picocolors";
 var STATUS_COLOR2 = {
-  pending: (s) => pc16.dim(s),
-  in_progress: (s) => pc16.cyan(s),
-  done: (s) => pc16.green(s),
-  blocked: (s) => pc16.red(s)
+  pending: (s) => pc17.dim(s),
+  in_progress: (s) => pc17.cyan(s),
+  done: (s) => pc17.green(s),
+  blocked: (s) => pc17.red(s)
 };
 async function runTaskList(cwd2, opts) {
   const config = await loadConfig(cwd2);
@@ -3571,11 +3816,11 @@ async function runTaskList(cwd2, opts) {
       let msg = "No tasks";
       if (filterStatus) msg += ` with status: ${filterStatus}`;
       if (opts.archived) msg += " (archived)";
-      console.log(pc16.dim(msg + "."));
+      console.log(pc17.dim(msg + "."));
       return;
     }
     const table = new Table2({
-      head: ["ID", "Slug", "Title", "Status"].map((h) => pc16.bold(h)),
+      head: ["ID", "Slug", "Title", "Status"].map((h) => pc17.bold(h)),
       style: { head: [], border: [] }
     });
     for (const t of tasks) {
@@ -3586,7 +3831,7 @@ async function runTaskList(cwd2, opts) {
     if (!opts.archived && !opts.includeArchived) {
       const archivedTasks = await db.getArchivedTasks();
       if (archivedTasks.length > 0) {
-        console.log(pc16.dim(`${archivedTasks.length} archived task${archivedTasks.length !== 1 ? "s" : ""} (use --archived to view)`));
+        console.log(pc17.dim(`${archivedTasks.length} archived task${archivedTasks.length !== 1 ? "s" : ""} (use --archived to view)`));
       }
     }
   } finally {
@@ -3594,64 +3839,93 @@ async function runTaskList(cwd2, opts) {
   }
 }
 
-// src/core/local-install-guard.ts
-import { existsSync as existsSync18, readFileSync as readFileSync12 } from "fs";
-import { join as join20 } from "path";
-import pc17 from "picocolors";
-function isLocalInstallSatisfied(cwd2) {
-  const selfPkgPath = join20(cwd2, "package.json");
-  let projectPkg = null;
-  if (existsSync18(selfPkgPath)) {
+// 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 {
-      const selfPkg = JSON.parse(readFileSync12(selfPkgPath, "utf8"));
-      if (selfPkg?.name === pkg.name) return true;
-      projectPkg = selfPkg;
+      if (isExecutable(join21(dir, name))) return true;
     } catch {
+      continue;
     }
   }
-  const [scope, name] = pkg.name.split("/");
-  const localPath = pkg.name.startsWith("@") ? join20(cwd2, "node_modules", scope, name) : join20(cwd2, "node_modules", pkg.name);
-  if (existsSync18(localPath)) return true;
-  const isPnp = existsSync18(join20(cwd2, ".pnp.cjs")) || existsSync18(join20(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(pc17.yellow(`\u26A0 ${pkg.name} is not installed locally in this project.`));
-  console.error(pc17.dim("  This is only a recommendation for reproducibility: pinning a local"));
-  console.error(pc17.dim("  version keeps behavior consistent across your team and CI, instead of"));
-  console.error(pc17.dim("  drifting with whatever version is installed globally on each machine."));
-  console.error(pc17.dim(`  Run: npm install --save-dev ${pkg.name}`));
-  console.error(pc17.dim("  (or the equivalent for your package manager: pnpm add -D, yarn add --dev, bun add -d)"));
+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 pc18 from "picocolors";
+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);
 }
@@ -3666,13 +3940,28 @@ 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");
 program.command("init").description("Scaffold a harness interactively in the current directory").option("--name <name>", "Project name (skip prompt)").option("--provider <provider>", "AI provider: claude-code | opencode (skip prompt)").option("--docs <path>", "Docs folder path (skip prompt)").option("--tasks <adapter>", "Task adapter: local | jira | linear (skip prompt)").option("--storage-scope <scope>", "Storage scope: local | global (skip prompt)").action(async (opts) => {
   await runInit(cwd, opts);
 });
-program.command("build").description("Regenerate AGENTS.md and provider files from agent-harness-kit.config.ts").option("--watch", "Rebuild on config changes").option("--sync", "Sync tools: frontmatter in existing .claude/agents/*.md to match current permission constants").action(async (opts) => {
+program.command("build").description("Regenerate AGENTS.md and provider files from agent-harness-kit.config.ts").option("--watch", "Rebuild on config changes").option("--sync", "Sync tools: frontmatter in existing .claude/agents/*.md to match current permission constants").option(
+  "--force",
+  "Regenerate agent files that already exist, DESTROYING your customizations (a backup is written first). Without this flag, build only creates agent files that are missing and never modifies existing ones."
+).action(async (opts) => {
   await runBuild(cwd, opts);
 });
 program.command("health").description("Run health.sh and report result").action(async () => {
@@ -3684,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");
@@ -3700,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) => {
@@ -3713,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);
   }
 });
@@ -3729,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 () => {