@vaubaan/harness 1.3.2 → 1.4.0

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { dirname as dirname8, resolve as resolve8 } from "path";
+import { dirname as dirname9, resolve as resolve9 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command } from "commander";
 
@@ -727,7 +727,7 @@ function formatReportText(report) {
 }
 
 // src/version.ts
-var VERSION = "1.3.2";
+var VERSION = "1.4.0";
 
 // src/cli/check.ts
 import { existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
@@ -768,185 +768,216 @@ function checkCommand(repoRoot) {
 }
 
 // src/cli/init.ts
-import { existsSync as existsSync10, mkdirSync, writeFileSync as writeFileSync3 } from "fs";
-import { dirname as dirname4, join as join11, resolve as resolve4 } from "path";
-import { fileURLToPath } from "url";
-
-// src/loader.ts
-import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
-import { join as join5 } from "path";
-import fg6 from "fast-glob";
-import { z as z2 } from "zod";
-
-// src/parser/common.ts
-import { readFileSync as readFileSync3 } from "fs";
-import matter2 from "gray-matter";
-
-// src/parser/schemas.ts
-import { z } from "zod";
-
-// src/types.ts
-var AGENT_IDS = ["coding", "review", "merge", "planning"];
-var ENGINES = ["claude-code", "codex-cli", "opencode"];
-var CAPABILITIES = ["multi-step", "slash-command", "inline-exec"];
-var CAPABILITIES_MATRIX = {
-  "claude-code": ["multi-step", "slash-command", "inline-exec"],
-  "codex-cli": ["multi-step", "slash-command", "inline-exec"],
-  opencode: ["multi-step", "slash-command", "inline-exec"]
-};
-var DEGRADED_CAPABILITIES = {
-  "codex-cli": ["multi-step"]
-};
+import { existsSync as existsSync13, mkdirSync as mkdirSync2, rmSync, writeFileSync as writeFileSync4 } from "fs";
+import { dirname as dirname6, join as join15, resolve as resolve7 } from "path";
 
-// src/parser/schemas.ts
-var IdSchema = z.string().min(1).regex(/^[a-z][a-z0-9-]*$/, "id must be kebab-case (lowercase + digits + hyphens)");
-var SkillFrontmatterSchema = z.object({
-  id: IdSchema,
-  description: z.string().min(1),
-  engines: z.array(z.enum(ENGINES)).min(1).optional(),
-  requires: z.array(z.enum(CAPABILITIES)).optional(),
-  tags: z.array(z.string()).optional()
-}).strict();
-var CmdArgEnumSchema = z.object({
-  name: z.string().min(1),
-  type: z.literal("enum"),
-  values: z.array(z.string()).min(1),
-  default: z.string().optional()
-}).strict();
-var CmdArgStringSchema = z.object({
-  name: z.string().min(1),
-  type: z.literal("string"),
-  default: z.string().optional()
-}).strict();
-var CmdArgSchema = z.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
-var CmdFrontmatterSchema = z.object({
-  id: IdSchema,
-  trigger: z.string().regex(/^\/[a-z][a-z0-9-]*$/, "trigger must be /kebab-case"),
-  invokes_skill: IdSchema,
-  args: z.array(CmdArgSchema).optional(),
-  description: z.string().min(1)
-}).strict();
-var AgentFrontmatterSchema = z.object({
-  id: z.enum(AGENT_IDS),
-  description: z.string().min(1)
-}).strict();
-var Schemas = {
-  Skill: SkillFrontmatterSchema,
-  Cmd: CmdFrontmatterSchema,
-  Agent: AgentFrontmatterSchema
-};
-var ParseError = class extends Error {
-  constructor(file, issues) {
-    const messages = issues.map((i) => `  - ${i.path.join(".") || "<root>"}: ${i.message}`).join("\n");
-    super(`Frontmatter validation failed for ${file}:
-${messages}`);
-    this.file = file;
-    this.issues = issues;
-    this.name = "ParseError";
+// src/cli/managed-paths.ts
+import { lstatSync, realpathSync, statSync as statSync2 } from "fs";
+import { basename as basename2, dirname as dirname2, isAbsolute as isAbsolute2, join as join5, resolve as resolve2, win32 } from "path";
+var MANAGED_FILES = /* @__PURE__ */ new Set([
+  "AGENTS.md",
+  "CLAUDE.md",
+  ".mcp.json",
+  ".harness-manifest.json",
+  ".claude/settings.json",
+  ".codex/config.toml",
+  ".codex/hooks.json",
+  ".opencode/opencode.json",
+  ".opencode/mcp.json"
+]);
+var MANAGED_DIRECTORIES = [
+  ".claude/agents/",
+  ".claude/commands/",
+  ".claude/skills/",
+  ".codex/agents/",
+  ".codex/commands/",
+  ".codex/skills/",
+  ".agents/skills/",
+  ".opencode/agents/",
+  ".opencode/commands/",
+  ".opencode/skills/",
+  ".opencode/plugins/"
+];
+function canonicalTargetRoot(root) {
+  let ancestor = resolve2(root);
+  const missing = [];
+  while (!lstatSync(ancestor, { throwIfNoEntry: false })) {
+    missing.unshift(basename2(ancestor));
+    ancestor = dirname2(ancestor);
   }
-  file;
-  issues;
-};
-
-// src/parser/common.ts
-function parseWithSchema(filePath, source, schema) {
-  const parsed = matter2(source);
-  const result = schema.safeParse(parsed.data);
-  if (!result.success) {
-    throw new ParseError(filePath, result.error.issues);
+  const canonical = realpathSync(ancestor);
+  if (!statSync2(canonical).isDirectory()) {
+    throw new Error(`harness target is not a directory: ${root}`);
   }
-  return {
-    meta: result.data,
-    body: parsed.content.trim(),
-    sourcePath: filePath
-  };
+  return join5(canonical, ...missing);
 }
-
-// src/parser/agent.ts
-function parseAgent(filePath, source) {
-  return parseWithSchema(filePath, source, Schemas.Agent);
+function assertManagedLocation(path) {
+  const invalidSegment = path.split("/").some((part) => part === "" || part === "." || part === "..");
+  if (isAbsolute2(path) || win32.isAbsolute(path) || path.includes("\\") || path.includes("\0") || invalidSegment) {
+    throw new Error(`unsafe harness path: ${path}`);
+  }
+  if (!MANAGED_FILES.has(path) && !MANAGED_DIRECTORIES.some((prefix) => path.startsWith(prefix))) {
+    throw new Error(`path is outside harness-managed locations: ${path}`);
+  }
 }
-
-// src/parser/cmd.ts
-function parseCmd(filePath, source) {
-  return parseWithSchema(filePath, source, Schemas.Cmd);
+function assertNoSymbolicComponents(root, path) {
+  const parts = path.split("/");
+  let current = root;
+  for (const [index, part] of parts.entries()) {
+    current = join5(current, part);
+    const info = lstatSync(current, { throwIfNoEntry: false });
+    if (!info) return;
+    if (info.isSymbolicLink()) {
+      throw new Error(`symbolic link in harness path: ${path}`);
+    }
+    const isLeaf = index === parts.length - 1;
+    if (isLeaf ? !info.isFile() : !info.isDirectory()) {
+      throw new Error(`unexpected file type in harness path: ${path}`);
+    }
+  }
 }
-
-// src/parser/skill.ts
-function parseSkill(filePath, source) {
-  return parseWithSchema(filePath, source, Schemas.Skill);
+function assertManagedPaths(root, files) {
+  for (const path of files) assertManagedLocation(path);
+  const canonicalRoot2 = canonicalTargetRoot(root);
+  for (const path of files) assertNoSymbolicComponents(canonicalRoot2, path);
 }
 
-// src/util/yaml.ts
-import { parse as yamlParse } from "yaml";
-function parseYAML(source) {
-  return yamlParse(source);
-}
+// src/cli/manifest.ts
+import { createHash } from "crypto";
+import { chmodSync, existsSync as existsSync7, readFileSync as readFileSync5, writeFileSync } from "fs";
+import { join as join8 } from "path";
+import { z as z3 } from "zod";
 
-// src/loader.ts
-var DisableYamlSchema = z2.object({ disable: z2.array(z2.string()).optional() }).passthrough();
-function loadHarness(packageDir, opts = {}) {
-  const agentsDir = opts.agentsDir ?? join5(packageDir, "agents");
-  const skillsDir = opts.skillsDir ?? join5(packageDir, "skills");
-  const commandsDir = opts.commandsDir ?? join5(packageDir, "commands");
-  const agentFiles = fg6.sync("*.agent.md", { cwd: agentsDir, absolute: true });
-  const skillFiles = fg6.sync("*.skill.md", { cwd: skillsDir, absolute: true });
-  const cmdFiles = fg6.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
-  return {
-    agents: agentFiles.map((f) => parseAgent(f, readFileSync4(f, "utf8"))),
-    skills: skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8"))),
-    cmds: cmdFiles.map((f) => parseCmd(f, readFileSync4(f, "utf8")))
-  };
+// src/cli/opencode-config.ts
+import { existsSync as existsSync5, readFileSync as readFileSync3 } from "fs";
+import { join as join6 } from "path";
+import { isDeepStrictEqual } from "util";
+import { z } from "zod";
+var OPENCODE_CONFIG_PATH = ".opencode/opencode.json";
+var CLAUDE_MCP_PATH = ".mcp.json";
+var OPENCODE_SCHEMA = "https://opencode.ai/config.json";
+var ObjectSchema = z.record(z.unknown());
+var OPENCODE_TARGET = {
+  path: OPENCODE_CONFIG_PATH,
+  key: "mcp",
+  label: "OpenCode",
+  schema: OPENCODE_SCHEMA
+};
+var CLAUDE_TARGET = {
+  path: CLAUDE_MCP_PATH,
+  key: "mcpServers",
+  label: "Claude Code"
+};
+var OpenCodeConfigOwnershipSchema = z.object({
+  createdFile: z.boolean(),
+  addedMcp: z.boolean(),
+  addedSchema: z.boolean(),
+  entries: z.record(ObjectSchema)
+});
+function parseConfig(target, content) {
+  try {
+    const config = ObjectSchema.parse(JSON.parse(content));
+    if (Object.hasOwn(config, target.key)) ObjectSchema.parse(config[target.key]);
+    return config;
+  } catch {
+    throw new Error(`invalid ${target.path}: expected a JSON object with an MCP object`);
+  }
 }
-function loadProjectSkills(targetDir) {
-  const skillsDir = join5(targetDir, "docs", "skills");
-  if (!existsSync5(skillsDir)) return [];
-  const skillFiles = fg6.sync("*.skill.md", { cwd: skillsDir, absolute: true });
-  return skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8")));
+function removeOwnedEntries(target, config, ownership, warnings) {
+  if (Object.hasOwn(config, target.key)) {
+    const mcp = ObjectSchema.parse(config[target.key]);
+    for (const [id, installed] of Object.entries(ownership.entries)) {
+      if (!Object.hasOwn(mcp, id)) continue;
+      if (isDeepStrictEqual(mcp[id], installed)) delete mcp[id];
+      else warnings.push(`preserved modified ${target.label} MCP server: ${id}`);
+    }
+    config[target.key] = mcp;
+    if (ownership.addedMcp && Object.keys(mcp).length === 0)
+      Reflect.deleteProperty(config, target.key);
+  }
+  if (target.schema && ownership.addedSchema && config.$schema === target.schema)
+    Reflect.deleteProperty(config, "$schema");
 }
-function loadOverrides(worktreeDir) {
-  const overridesDir = join5(worktreeDir, ".harness-overrides");
-  if (!existsSync5(overridesDir)) return void 0;
-  const added = loadHarness(overridesDir, {
-    agentsDir: join5(overridesDir, "agents"),
-    skillsDir: join5(overridesDir, "skills"),
-    commandsDir: join5(overridesDir, "commands")
-  });
-  const disablePath = join5(overridesDir, "disable.yaml");
-  let disable = [];
-  if (existsSync5(disablePath)) {
-    try {
-      const parsed = DisableYamlSchema.safeParse(parseYAML(readFileSync4(disablePath, "utf8")));
-      if (parsed.success && parsed.data.disable) {
-        disable = parsed.data.disable;
+function addMissingEntries(target, config, desired, createdFile, warnings) {
+  const requested = ObjectSchema.parse(parseConfig(target, desired.content)[target.key]);
+  const mcp = ObjectSchema.parse(config[target.key] ?? {});
+  const entries = {};
+  for (const [id, entry] of Object.entries(requested)) {
+    if (Object.hasOwn(mcp, id)) {
+      if (!isDeepStrictEqual(mcp[id], entry)) {
+        warnings.push(
+          `preserved existing ${target.label} MCP server instead of replacing it: ${id}`
+        );
       }
-    } catch {
+      continue;
     }
+    entries[id] = ObjectSchema.parse(entry);
+    mcp[id] = entry;
   }
-  return { add: added, disable };
+  if (Object.keys(entries).length === 0) return void 0;
+  const ownership = {
+    createdFile,
+    addedMcp: !Object.hasOwn(config, target.key),
+    addedSchema: target.schema !== void 0 && !Object.hasOwn(config, "$schema"),
+    entries
+  };
+  config[target.key] = mcp;
+  if (target.schema && ownership.addedSchema) config.$schema = target.schema;
+  return ownership;
 }
-
-// src/mcp.ts
-var MCP_SERVER_IDS = ["context7"];
-var MCP_SERVERS = {
-  context7: {
-    id: "context7",
-    description: "Upstash Context7 \u2014 fetches up-to-date library docs via resolve-library-id + get-library-docs.",
-    command: "npx",
-    args: ["-y", "@upstash/context7-mcp"]
+function planMcpJson(target, root, desired, previous) {
+  const warnings = [];
+  if (!desired && !previous) return { remove: false, warnings };
+  const path = join6(root, target.path);
+  const existed = existsSync5(path);
+  if (!existed && !desired) return { remove: false, warnings };
+  const original = existed ? readFileSync3(path, "utf8") : void 0;
+  const config = original === void 0 ? {} : parseConfig(target, original);
+  const before = structuredClone(config);
+  if (previous) removeOwnedEntries(target, config, previous, warnings);
+  const createdFile = !existed || previous?.createdFile === true;
+  const ownership = desired ? addMissingEntries(target, config, desired, createdFile, warnings) : void 0;
+  if (!ownership && createdFile && Object.keys(config).length === 0) {
+    return { remove: existed, warnings };
   }
-};
-function resolveMcpIds(requested) {
-  return requested.map((id) => {
-    if (!MCP_SERVER_IDS.includes(id)) {
-      throw new Error(`unknown MCP server: ${id} (expected one of ${MCP_SERVER_IDS.join(", ")})`);
-    }
-    return id;
-  });
+  return {
+    remove: false,
+    ownership,
+    warnings,
+    ...!existed || !isDeepStrictEqual(before, config) ? { write: { path: target.path, content: `${JSON.stringify(config, null, 2)}
+` } } : {}
+  };
+}
+function planOpenCodeConfig(root, desired, previous) {
+  return planMcpJson(OPENCODE_TARGET, root, desired, previous);
+}
+function planClaudeMcpConfig(root, desired, previous) {
+  return planMcpJson(CLAUDE_TARGET, root, desired, previous);
 }
 
+// src/cli/update-config.ts
+import { existsSync as existsSync6, readFileSync as readFileSync4 } from "fs";
+import { join as join7 } from "path";
+import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
+import { z as z2 } from "zod";
+
 // src/renderers/common.ts
 import { stringify as yamlStringify } from "yaml";
+
+// src/types.ts
+var AGENT_IDS = ["coding", "review", "merge", "planning"];
+var ENGINES = ["claude-code", "codex-cli", "opencode"];
+var CAPABILITIES = ["multi-step", "slash-command", "inline-exec"];
+var CAPABILITIES_MATRIX = {
+  "claude-code": ["multi-step", "slash-command", "inline-exec"],
+  "codex-cli": ["multi-step", "slash-command", "inline-exec"],
+  opencode: ["multi-step", "slash-command", "inline-exec"]
+};
+var DEGRADED_CAPABILITIES = {
+  "codex-cli": ["multi-step"]
+};
+
+// src/renderers/common.ts
 var STOP_HOOK_PACKAGE = "@vaubaan/harness";
 function checkSkillCapabilities(skill, engine) {
   const blockingWarnings = [];
@@ -1390,274 +1421,7 @@ function getRenderer(engine) {
   return RENDERERS[engine];
 }
 
-// src/render.ts
-var RenderError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "RenderError";
-  }
-};
-function mergeById(stock, added) {
-  const result = /* @__PURE__ */ new Map();
-  for (const item of stock) result.set(item.meta.id, item);
-  if (added) {
-    for (const item of added) result.set(item.meta.id, item);
-  }
-  return Array.from(result.values());
-}
-function removeByIds(items, disabled) {
-  if (disabled.length === 0) return [...items];
-  const disabledSet = new Set(disabled);
-  return items.filter((item) => !disabledSet.has(item.meta.id));
-}
-function applyOverrides(harness, overrides) {
-  const disabled = overrides?.disable ?? [];
-  return {
-    agents: removeByIds(mergeById(harness.agents, overrides?.add?.agents), disabled),
-    skills: removeByIds(mergeById(harness.skills, overrides?.add?.skills), disabled),
-    cmds: removeByIds(mergeById(harness.cmds, overrides?.add?.cmds), disabled)
-  };
-}
-var CLAUDE_MD_STUB = "@AGENTS.md\n";
-function opencodeLast(engines) {
-  return [...engines].sort((a, b) => Number(a === "opencode") - Number(b === "opencode"));
-}
-function render(input) {
-  const { engines } = input;
-  if (engines.length === 0) {
-    throw new RenderError("at least one engine must be selected");
-  }
-  const base = input.projectSkills?.length ? { ...input.harness, skills: mergeById(input.harness.skills, input.projectSkills) } : input.harness;
-  const harness = applyOverrides(base, input.overrides);
-  if (harness.agents.length === 0) {
-    throw new RenderError("No agents found in harness");
-  }
-  const files = [];
-  const warnings = [];
-  const exposedSkills = /* @__PURE__ */ new Map();
-  const exposedCmds = /* @__PURE__ */ new Map();
-  for (const engine of opencodeLast(engines)) {
-    const renderer = getRenderer(engine);
-    const renderedSkills = [];
-    for (const skill of harness.skills) {
-      const result = renderer.renderSkill(skill);
-      warnings.push(...result.warnings);
-      if (result.files.length > 0) {
-        const alreadyVisible = engine === "opencode" && exposedSkills.has(skill.meta.id);
-        if (!alreadyVisible) files.push(...result.files);
-        renderedSkills.push(skill);
-        exposedSkills.set(skill.meta.id, skill);
-      }
-    }
-    const renderedSkillIds = new Set(renderedSkills.map((s) => s.meta.id));
-    const renderedCmds = [];
-    for (const cmd of harness.cmds) {
-      if (!renderedSkillIds.has(cmd.meta.invokes_skill)) continue;
-      const result = renderer.renderCmd(cmd);
-      warnings.push(...result.warnings);
-      if (result.files.length > 0) {
-        files.push(...result.files);
-        renderedCmds.push(cmd);
-        exposedCmds.set(cmd.meta.id, cmd);
-      }
-    }
-    const agentsResult = renderer.renderAgents(harness.agents);
-    warnings.push(...agentsResult.warnings);
-    files.push(...agentsResult.files);
-    if (input.mcpServers && input.mcpServers.length > 0) {
-      const specs = input.mcpServers.map((id) => MCP_SERVERS[id]);
-      const mcpResult = renderer.renderMcp(specs);
-      warnings.push(...mcpResult.warnings);
-      files.push(...mcpResult.files);
-    }
-    if (input.withStopHook !== false) {
-      const hookResult = renderer.renderStopHook();
-      warnings.push(...hookResult.warnings);
-      files.push(...hookResult.files);
-    }
-  }
-  const hasProjectSkills = (input.projectSkills?.length ?? 0) > 0;
-  const umbrellaContent = buildUmbrellaBody(harness.agents, {
-    availableSkills: Array.from(exposedSkills.values()),
-    availableCommands: Array.from(exposedCmds.values()),
-    hasProjectSkills,
-    hasQualityDoc: input.hasQualityDoc === true
-  });
-  files.push({ path: "AGENTS.md", content: umbrellaContent });
-  if (engines.includes("claude-code")) {
-    files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
-  }
-  return { files, warnings };
-}
-
-// src/cli/managed-paths.ts
-import { lstatSync, realpathSync, statSync as statSync2 } from "fs";
-import { basename as basename2, dirname as dirname2, isAbsolute as isAbsolute2, join as join6, resolve as resolve2, win32 } from "path";
-var MANAGED_FILES = /* @__PURE__ */ new Set([
-  "AGENTS.md",
-  "CLAUDE.md",
-  ".mcp.json",
-  ".harness-manifest.json",
-  ".claude/settings.json",
-  ".codex/config.toml",
-  ".codex/hooks.json",
-  ".opencode/opencode.json",
-  ".opencode/mcp.json"
-]);
-var MANAGED_DIRECTORIES = [
-  ".claude/agents/",
-  ".claude/commands/",
-  ".claude/skills/",
-  ".codex/agents/",
-  ".codex/commands/",
-  ".codex/skills/",
-  ".agents/skills/",
-  ".opencode/agents/",
-  ".opencode/commands/",
-  ".opencode/skills/",
-  ".opencode/plugins/"
-];
-function canonicalTargetRoot(root) {
-  let ancestor = resolve2(root);
-  const missing = [];
-  while (!lstatSync(ancestor, { throwIfNoEntry: false })) {
-    missing.unshift(basename2(ancestor));
-    ancestor = dirname2(ancestor);
-  }
-  const canonical = realpathSync(ancestor);
-  if (!statSync2(canonical).isDirectory()) {
-    throw new Error(`harness target is not a directory: ${root}`);
-  }
-  return join6(canonical, ...missing);
-}
-function assertManagedLocation(path) {
-  const invalidSegment = path.split("/").some((part) => part === "" || part === "." || part === "..");
-  if (isAbsolute2(path) || win32.isAbsolute(path) || path.includes("\\") || path.includes("\0") || invalidSegment) {
-    throw new Error(`unsafe harness path: ${path}`);
-  }
-  if (!MANAGED_FILES.has(path) && !MANAGED_DIRECTORIES.some((prefix) => path.startsWith(prefix))) {
-    throw new Error(`path is outside harness-managed locations: ${path}`);
-  }
-}
-function assertNoSymbolicComponents(root, path) {
-  const parts = path.split("/");
-  let current = root;
-  for (const [index, part] of parts.entries()) {
-    current = join6(current, part);
-    const info = lstatSync(current, { throwIfNoEntry: false });
-    if (!info) return;
-    if (info.isSymbolicLink()) {
-      throw new Error(`symbolic link in harness path: ${path}`);
-    }
-    const isLeaf = index === parts.length - 1;
-    if (isLeaf ? !info.isFile() : !info.isDirectory()) {
-      throw new Error(`unexpected file type in harness path: ${path}`);
-    }
-  }
-}
-function assertManagedPaths(root, files) {
-  for (const path of files) assertManagedLocation(path);
-  const canonicalRoot2 = canonicalTargetRoot(root);
-  for (const path of files) assertNoSymbolicComponents(canonicalRoot2, path);
-}
-
-// src/cli/manifest.ts
-import { createHash } from "crypto";
-import { chmodSync, existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync } from "fs";
-import { join as join9 } from "path";
-import { z as z5 } from "zod";
-
-// src/cli/opencode-config.ts
-import { existsSync as existsSync6, readFileSync as readFileSync5 } from "fs";
-import { join as join7 } from "path";
-import { isDeepStrictEqual } from "util";
-import { z as z3 } from "zod";
-var OPENCODE_CONFIG_PATH = ".opencode/opencode.json";
-var OPENCODE_SCHEMA = "https://opencode.ai/config.json";
-var ObjectSchema = z3.record(z3.unknown());
-var OpenCodeConfigOwnershipSchema = z3.object({
-  createdFile: z3.boolean(),
-  addedMcp: z3.boolean(),
-  addedSchema: z3.boolean(),
-  entries: z3.record(ObjectSchema)
-});
-function parseConfig(content) {
-  try {
-    const config = ObjectSchema.parse(JSON.parse(content));
-    if (Object.hasOwn(config, "mcp")) ObjectSchema.parse(config.mcp);
-    return config;
-  } catch {
-    throw new Error(`invalid ${OPENCODE_CONFIG_PATH}: expected a JSON object with an MCP object`);
-  }
-}
-function removeOwnedEntries(config, ownership, warnings) {
-  if (Object.hasOwn(config, "mcp")) {
-    const mcp = ObjectSchema.parse(config.mcp);
-    for (const [id, installed] of Object.entries(ownership.entries)) {
-      if (!Object.hasOwn(mcp, id)) continue;
-      if (isDeepStrictEqual(mcp[id], installed)) delete mcp[id];
-      else warnings.push(`preserved modified OpenCode MCP server: ${id}`);
-    }
-    config.mcp = mcp;
-    if (ownership.addedMcp && Object.keys(mcp).length === 0) Reflect.deleteProperty(config, "mcp");
-  }
-  if (ownership.addedSchema && config.$schema === OPENCODE_SCHEMA)
-    Reflect.deleteProperty(config, "$schema");
-}
-function addMissingEntries(config, desired, createdFile, warnings) {
-  const requested = ObjectSchema.parse(parseConfig(desired.content).mcp);
-  const mcp = ObjectSchema.parse(config.mcp ?? {});
-  const entries = {};
-  for (const [id, entry] of Object.entries(requested)) {
-    if (Object.hasOwn(mcp, id)) {
-      if (!isDeepStrictEqual(mcp[id], entry)) {
-        warnings.push(`preserved existing OpenCode MCP server instead of replacing it: ${id}`);
-      }
-      continue;
-    }
-    entries[id] = ObjectSchema.parse(entry);
-    mcp[id] = entry;
-  }
-  if (Object.keys(entries).length === 0) return void 0;
-  const ownership = {
-    createdFile,
-    addedMcp: !Object.hasOwn(config, "mcp"),
-    addedSchema: !Object.hasOwn(config, "$schema"),
-    entries
-  };
-  config.mcp = mcp;
-  if (ownership.addedSchema) config.$schema = OPENCODE_SCHEMA;
-  return ownership;
-}
-function planOpenCodeConfig(root, desired, previous) {
-  const warnings = [];
-  if (!desired && !previous) return { remove: false, warnings };
-  const path = join7(root, OPENCODE_CONFIG_PATH);
-  const existed = existsSync6(path);
-  if (!existed && !desired) return { remove: false, warnings };
-  const original = existed ? readFileSync5(path, "utf8") : void 0;
-  const config = original === void 0 ? {} : parseConfig(original);
-  const before = structuredClone(config);
-  if (previous) removeOwnedEntries(config, previous, warnings);
-  const createdFile = !existed || previous?.createdFile === true;
-  const ownership = desired ? addMissingEntries(config, desired, createdFile, warnings) : void 0;
-  if (!ownership && createdFile && Object.keys(config).length === 0) {
-    return { remove: existed, warnings };
-  }
-  return {
-    remove: false,
-    ownership,
-    warnings,
-    ...!existed || !isDeepStrictEqual(before, config) ? { write: { path: OPENCODE_CONFIG_PATH, content: `${JSON.stringify(config, null, 2)}
-` } } : {}
-  };
-}
-
 // src/cli/update-config.ts
-import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
-import { join as join8 } from "path";
-import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
-import { z as z4 } from "zod";
 var LEGACY_OPENCODE_CONFIG = ".opencode/mcp.json";
 var SHARED_CONFIG_PATHS = [
   ".mcp.json",
@@ -1667,15 +1431,15 @@ var SHARED_CONFIG_PATHS = [
   ".claude/settings.json",
   ".codex/hooks.json"
 ];
-var ObjectSchema2 = z4.record(z4.unknown());
-var HookEntrySchema = z4.object({ group: ObjectSchema2, hook: ObjectSchema2 });
-var HookConfigOwnershipSchema = z4.object({
-  createdFile: z4.boolean(),
-  addedHooks: z4.boolean(),
-  addedStop: z4.boolean(),
-  entries: z4.array(HookEntrySchema)
+var ObjectSchema2 = z2.record(z2.unknown());
+var HookEntrySchema = z2.object({ group: ObjectSchema2, hook: ObjectSchema2 });
+var HookConfigOwnershipSchema = z2.object({
+  createdFile: z2.boolean(),
+  addedHooks: z2.boolean(),
+  addedStop: z2.boolean(),
+  entries: z2.array(HookEntrySchema)
 });
-var HookConfigsOwnershipSchema = z4.object({
+var HookConfigsOwnershipSchema = z2.object({
   ".claude/settings.json": HookConfigOwnershipSchema.optional(),
   ".codex/hooks.json": HookConfigOwnershipSchema.optional()
 }).strict();
@@ -1799,8 +1563,8 @@ function planHookConfigCleanup(root, ownership) {
   assertManagedPaths(root, Object.keys(validated));
   for (const path of Object.keys(HOOK_ENGINES)) {
     const owned = validated[path];
-    if (!owned || !existsSync7(join8(root, path))) continue;
-    const before = parseObject(readFileSync6(join8(root, path), "utf8"), path);
+    if (!owned || !existsSync6(join7(root, path))) continue;
+    const before = parseObject(readFileSync4(join7(root, path), "utf8"), path);
     const config = structuredClone(before);
     removeOwnedHooks(config, owned, path, plan.warnings);
     recordMutation(plan, path, before, config, owned.createdFile);
@@ -1809,12 +1573,12 @@ function planHookConfigCleanup(root, ownership) {
 }
 function planActiveHook(root, path, previous, claimExisting, plan) {
   assertManagedPaths(root, [path]);
-  const existed = existsSync7(join8(root, path));
+  const existed = existsSync6(join7(root, path));
   if (!existed && previous?.entries.length) {
     plan.warnings.push(`preserved removed harness Stop hook configuration: ${path}`);
     return previous;
   }
-  const before = existed ? parseObject(readFileSync6(join8(root, path), "utf8"), path) : void 0;
+  const before = existed ? parseObject(readFileSync4(join7(root, path), "utf8"), path) : void 0;
   const config = structuredClone(before ?? {});
   const groups = stopHooks(config, path);
   const hooks = asObject(config.hooks) ?? {};
@@ -1826,10 +1590,11 @@ function planActiveHook(root, path, previous, claimExisting, plan) {
     plan.warnings,
     path
   );
+  const legacyWholeFile = !previous && claimExisting && existed;
   const ownership = {
-    createdFile: !existed || previous?.createdFile === true,
-    addedHooks: previous?.addedHooks ?? !Object.hasOwn(config, "hooks"),
-    addedStop: previous?.addedStop ?? !Object.hasOwn(hooks, "Stop"),
+    createdFile: !existed || previous?.createdFile === true || legacyWholeFile,
+    addedHooks: previous?.addedHooks ?? (legacyWholeFile || !Object.hasOwn(config, "hooks")),
+    addedStop: previous?.addedStop ?? (legacyWholeFile || !Object.hasOwn(hooks, "Stop")),
     entries: normalized.entries
   };
   if (!isDeepStrictEqual2(groups, normalized.groups)) {
@@ -1840,10 +1605,10 @@ function planActiveHook(root, path, previous, claimExisting, plan) {
 }
 function planLegacyOpenCode(root, previous, plan) {
   if (!previous.files.includes(LEGACY_OPENCODE_CONFIG)) return;
-  const legacyPath = join8(root, LEGACY_OPENCODE_CONFIG);
-  if (!existsSync7(legacyPath)) return;
+  const legacyPath = join7(root, LEGACY_OPENCODE_CONFIG);
+  if (!existsSync6(legacyPath)) return;
   assertManagedPaths(root, [LEGACY_OPENCODE_CONFIG, OPENCODE_CONFIG_PATH]);
-  const legacy = parseObject(readFileSync6(legacyPath, "utf8"), LEGACY_OPENCODE_CONFIG);
+  const legacy = parseObject(readFileSync4(legacyPath, "utf8"), LEGACY_OPENCODE_CONFIG);
   if (!asObject(legacy.mcp)) {
     throw new Error(
       `invalid shared configuration ${LEGACY_OPENCODE_CONFIG}: expected an MCP object`
@@ -1907,45 +1672,24 @@ function planUpdateConfigs(root, previous, hookEngines) {
 // src/cli/manifest.ts
 var MANIFEST_FILENAME = ".harness-manifest.json";
 var MANIFEST_VERSION = "6";
-var ManifestSchema = z5.object({
-  version: z5.enum(["4", "5", MANIFEST_VERSION]),
-  engines: z5.array(z5.string()),
-  renderedAt: z5.string(),
-  files: z5.array(z5.string()),
-  stopHookInstalled: z5.boolean().optional(),
-  stopHookEngines: z5.array(z5.string()).optional(),
+var ManifestSchema = z3.object({
+  version: z3.enum(["4", "5", MANIFEST_VERSION]),
+  engines: z3.array(z3.string()),
+  renderedAt: z3.string(),
+  files: z3.array(z3.string()),
+  stopHookInstalled: z3.boolean().optional(),
+  stopHookEngines: z3.array(z3.string()).optional(),
   opencodeConfig: OpenCodeConfigOwnershipSchema.optional(),
+  /** Entries the harness added to `.mcp.json` (Claude Code). */
+  mcpConfig: OpenCodeConfigOwnershipSchema.optional(),
   hookConfigs: HookConfigsOwnershipSchema.optional(),
-  harnessVersion: z5.string().optional(),
-  overridesDir: z5.string().optional(),
-  fileHashes: z5.record(z5.string().regex(/^[a-f0-9]{64}$/)).optional(),
-  preservedFiles: z5.array(z5.string()).optional()
+  harnessVersion: z3.string().optional(),
+  overridesDir: z3.string().optional(),
+  fileHashes: z3.record(z3.string().regex(/^[a-f0-9]{64}$/)).optional(),
+  preservedFiles: z3.array(z3.string()).optional()
 });
 function manifestPath(targetDir) {
-  return join9(targetDir, MANIFEST_FILENAME);
-}
-function writeManifest(targetDir, engines, files, extras = {}) {
-  assertManagedPaths(targetDir, [MANIFEST_FILENAME]);
-  const manifest = {
-    version: MANIFEST_VERSION,
-    harnessVersion: VERSION,
-    engines: [...engines].sort(),
-    renderedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    files: [...files].sort(),
-    fileHashes: Object.fromEntries(
-      files.filter((file) => existsSync8(join9(targetDir, file))).sort().map((file) => [file, hashContent(readFileSync7(join9(targetDir, file)))])
-    ),
-    ...extras.overridesDir ? { overridesDir: extras.overridesDir } : {},
-    ...extras.preservedFiles ? { preservedFiles: extras.preservedFiles } : {},
-    ...extras.hookConfigs ? { hookConfigs: extras.hookConfigs } : {},
-    ...extras.opencodeConfig ? { opencodeConfig: extras.opencodeConfig } : {},
-    ...extras.stopHookInstalled !== void 0 ? { stopHookInstalled: extras.stopHookInstalled } : {},
-    ...extras.stopHookEngines !== void 0 ? { stopHookEngines: [...extras.stopHookEngines].sort() } : {}
-  };
-  const path = manifestPath(targetDir);
-  if (existsSync8(path)) chmodSync(path, 384);
-  writeFileSync(path, `${JSON.stringify(manifest, null, 2)}
-`, { mode: 384 });
+  return join8(targetDir, MANIFEST_FILENAME);
 }
 function hashContent(content) {
   return createHash("sha256").update(content).digest("hex");
@@ -1953,99 +1697,291 @@ function hashContent(content) {
 function readManifest(targetDir) {
   assertManagedPaths(targetDir, [MANIFEST_FILENAME]);
   const path = manifestPath(targetDir);
-  if (!existsSync8(path)) return null;
-  const raw = JSON.parse(readFileSync7(path, "utf8"));
+  if (!existsSync7(path)) return null;
+  const raw = JSON.parse(readFileSync5(path, "utf8"));
   return ManifestSchema.parse(raw);
 }
 
-// src/cli/uninstall.ts
-import { existsSync as existsSync9, readdirSync, rmdirSync, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname3, join as join10, relative as relative2, resolve as resolve3 } from "path";
-function uninstallCommand(args) {
-  const root = resolve3(args.targetDir);
-  const warnings = [];
-  assertManagedPaths(root, [MANIFEST_FILENAME]);
-  const manifest = readManifest(root);
-  if (!manifest) {
-    warnings.push(`no manifest found at ${manifestPath(root)} \u2014 nothing to uninstall`);
-    return { filesRemoved: [], dirsPruned: [], warnings };
-  }
-  assertManagedPaths(root, [
-    ...manifest.files,
-    ...manifest.opencodeConfig ? [OPENCODE_CONFIG_PATH] : [],
-    ...Object.keys(manifest.hookConfigs ?? {})
-  ]);
-  const config = planOpenCodeConfig(root, void 0, manifest.opencodeConfig);
-  const hooks = planHookConfigCleanup(root, manifest.hookConfigs);
-  const sharedHooks = new Set(Object.keys(manifest.hookConfigs ?? {}));
-  const ownedFiles = manifest.files.filter(
-    (file) => file !== OPENCODE_CONFIG_PATH && !sharedHooks.has(file)
-  );
-  if (config.remove) ownedFiles.push(OPENCODE_CONFIG_PATH);
-  ownedFiles.push(...hooks.removals);
-  const { filesRemoved, dirsPruned, missing } = removeRenderedFiles(root, ownedFiles);
-  if (config.write) writeFileSync2(join10(root, config.write.path), config.write.content);
-  for (const file of hooks.writes) writeFileSync2(join10(root, file.path), file.content);
-  warnings.push(...config.warnings, ...hooks.warnings);
-  if (manifest.files.includes(OPENCODE_CONFIG_PATH) && !manifest.opencodeConfig) {
-    warnings.push(`preserved legacy shared configuration: ${OPENCODE_CONFIG_PATH}`);
-  }
-  for (const rel of missing) warnings.push(`file in manifest is already missing: ${rel}`);
-  unlinkSync(manifestPath(root));
-  return { filesRemoved, dirsPruned, warnings };
+// src/cli/plan-render.ts
+import { existsSync as existsSync9 } from "fs";
+import { dirname as dirname3, join as join10, resolve as resolve3 } from "path";
+import { fileURLToPath } from "url";
+
+// src/loader.ts
+import { existsSync as existsSync8, readFileSync as readFileSync7 } from "fs";
+import { join as join9 } from "path";
+import fg6 from "fast-glob";
+import { z as z5 } from "zod";
+
+// src/parser/common.ts
+import { readFileSync as readFileSync6 } from "fs";
+import matter2 from "gray-matter";
+
+// src/parser/schemas.ts
+import { z as z4 } from "zod";
+var IdSchema = z4.string().min(1).regex(/^[a-z][a-z0-9-]*$/, "id must be kebab-case (lowercase + digits + hyphens)");
+var SkillFrontmatterSchema = z4.object({
+  id: IdSchema,
+  description: z4.string().min(1),
+  engines: z4.array(z4.enum(ENGINES)).min(1).optional(),
+  requires: z4.array(z4.enum(CAPABILITIES)).optional(),
+  tags: z4.array(z4.string()).optional()
+}).strict();
+var CmdArgEnumSchema = z4.object({
+  name: z4.string().min(1),
+  type: z4.literal("enum"),
+  values: z4.array(z4.string()).min(1),
+  default: z4.string().optional()
+}).strict();
+var CmdArgStringSchema = z4.object({
+  name: z4.string().min(1),
+  type: z4.literal("string"),
+  default: z4.string().optional()
+}).strict();
+var CmdArgSchema = z4.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
+var CmdFrontmatterSchema = z4.object({
+  id: IdSchema,
+  trigger: z4.string().regex(/^\/[a-z][a-z0-9-]*$/, "trigger must be /kebab-case"),
+  invokes_skill: IdSchema,
+  args: z4.array(CmdArgSchema).optional(),
+  description: z4.string().min(1)
+}).strict();
+var AgentFrontmatterSchema = z4.object({
+  id: z4.enum(AGENT_IDS),
+  description: z4.string().min(1)
+}).strict();
+var Schemas = {
+  Skill: SkillFrontmatterSchema,
+  Cmd: CmdFrontmatterSchema,
+  Agent: AgentFrontmatterSchema
+};
+var ParseError = class extends Error {
+  constructor(file, issues) {
+    const messages = issues.map((i) => `  - ${i.path.join(".") || "<root>"}: ${i.message}`).join("\n");
+    super(`Frontmatter validation failed for ${file}:
+${messages}`);
+    this.file = file;
+    this.issues = issues;
+    this.name = "ParseError";
+  }
+  file;
+  issues;
+};
+
+// src/parser/common.ts
+function parseWithSchema(filePath, source, schema) {
+  const parsed = matter2(source);
+  const result = schema.safeParse(parsed.data);
+  if (!result.success) {
+    throw new ParseError(filePath, result.error.issues);
+  }
+  return {
+    meta: result.data,
+    body: parsed.content.trim(),
+    sourcePath: filePath
+  };
 }
-function removeRenderedFiles(root, files) {
-  assertManagedPaths(root, files);
-  const filesRemoved = [];
-  const missing = [];
-  const dirsToConsider = /* @__PURE__ */ new Set();
-  for (const rel of files) {
-    const full = join10(root, rel);
-    if (existsSync9(full)) {
-      unlinkSync(full);
-      filesRemoved.push(rel);
-      dirsToConsider.add(dirname3(full));
-    } else {
-      missing.push(rel);
+
+// src/parser/agent.ts
+function parseAgent(filePath, source) {
+  return parseWithSchema(filePath, source, Schemas.Agent);
+}
+
+// src/parser/cmd.ts
+function parseCmd(filePath, source) {
+  return parseWithSchema(filePath, source, Schemas.Cmd);
+}
+
+// src/parser/skill.ts
+function parseSkill(filePath, source) {
+  return parseWithSchema(filePath, source, Schemas.Skill);
+}
+
+// src/util/yaml.ts
+import { parse as yamlParse } from "yaml";
+function parseYAML(source) {
+  return yamlParse(source);
+}
+
+// src/loader.ts
+var DisableYamlSchema = z5.object({ disable: z5.array(z5.string()).optional() }).passthrough();
+function loadHarness(packageDir, opts = {}) {
+  const agentsDir = opts.agentsDir ?? join9(packageDir, "agents");
+  const skillsDir = opts.skillsDir ?? join9(packageDir, "skills");
+  const commandsDir = opts.commandsDir ?? join9(packageDir, "commands");
+  const agentFiles = fg6.sync("*.agent.md", { cwd: agentsDir, absolute: true });
+  const skillFiles = fg6.sync("*.skill.md", { cwd: skillsDir, absolute: true });
+  const cmdFiles = fg6.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
+  return {
+    agents: agentFiles.map((f) => parseAgent(f, readFileSync7(f, "utf8"))),
+    skills: skillFiles.map((f) => parseSkill(f, readFileSync7(f, "utf8"))),
+    cmds: cmdFiles.map((f) => parseCmd(f, readFileSync7(f, "utf8")))
+  };
+}
+function loadProjectSkills(targetDir) {
+  const skillsDir = join9(targetDir, "docs", "skills");
+  if (!existsSync8(skillsDir)) return [];
+  const skillFiles = fg6.sync("*.skill.md", { cwd: skillsDir, absolute: true });
+  return skillFiles.map((f) => parseSkill(f, readFileSync7(f, "utf8")));
+}
+function loadOverrides(worktreeDir) {
+  const overridesDir = join9(worktreeDir, ".harness-overrides");
+  if (!existsSync8(overridesDir)) return void 0;
+  const added = loadHarness(overridesDir, {
+    agentsDir: join9(overridesDir, "agents"),
+    skillsDir: join9(overridesDir, "skills"),
+    commandsDir: join9(overridesDir, "commands")
+  });
+  const disablePath = join9(overridesDir, "disable.yaml");
+  let disable = [];
+  if (existsSync8(disablePath)) {
+    try {
+      const parsed = DisableYamlSchema.safeParse(parseYAML(readFileSync7(disablePath, "utf8")));
+      if (parsed.success && parsed.data.disable) {
+        disable = parsed.data.disable;
+      }
+    } catch {
     }
   }
-  return { filesRemoved, dirsPruned: pruneEmptyDirs(root, dirsToConsider), missing };
+  return { add: added, disable };
 }
-function pruneEmptyDirs(root, leaves) {
-  const candidates = /* @__PURE__ */ new Set();
-  for (const leaf of leaves) {
-    let cur = leaf;
-    while (cur !== root && cur.startsWith(`${root}/`)) {
-      candidates.add(cur);
-      cur = dirname3(cur);
+
+// src/mcp.ts
+var MCP_SERVER_IDS = ["context7"];
+var MCP_SERVERS = {
+  context7: {
+    id: "context7",
+    description: "Upstash Context7 \u2014 fetches up-to-date library docs via resolve-library-id + get-library-docs.",
+    command: "npx",
+    args: ["-y", "@upstash/context7-mcp"]
+  }
+};
+function resolveMcpIds(requested) {
+  return requested.map((id) => {
+    if (!MCP_SERVER_IDS.includes(id)) {
+      throw new Error(`unknown MCP server: ${id} (expected one of ${MCP_SERVER_IDS.join(", ")})`);
+    }
+    return id;
+  });
+}
+
+// src/render.ts
+var RenderError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RenderError";
+  }
+};
+function mergeById(stock, added) {
+  const result = /* @__PURE__ */ new Map();
+  for (const item of stock) result.set(item.meta.id, item);
+  if (added) {
+    for (const item of added) result.set(item.meta.id, item);
+  }
+  return Array.from(result.values());
+}
+function removeByIds(items, disabled) {
+  if (disabled.length === 0) return [...items];
+  const disabledSet = new Set(disabled);
+  return items.filter((item) => !disabledSet.has(item.meta.id));
+}
+function applyOverrides(harness, overrides) {
+  const disabled = overrides?.disable ?? [];
+  return {
+    agents: removeByIds(mergeById(harness.agents, overrides?.add?.agents), disabled),
+    skills: removeByIds(mergeById(harness.skills, overrides?.add?.skills), disabled),
+    cmds: removeByIds(mergeById(harness.cmds, overrides?.add?.cmds), disabled)
+  };
+}
+var CLAUDE_MD_STUB = "@AGENTS.md\n";
+function opencodeLast(engines) {
+  return [...engines].sort((a, b) => Number(a === "opencode") - Number(b === "opencode"));
+}
+function render(input) {
+  const { engines } = input;
+  if (engines.length === 0) {
+    throw new RenderError("at least one engine must be selected");
+  }
+  const base = input.projectSkills?.length ? { ...input.harness, skills: mergeById(input.harness.skills, input.projectSkills) } : input.harness;
+  const harness = applyOverrides(base, input.overrides);
+  if (harness.agents.length === 0) {
+    throw new RenderError("No agents found in harness");
+  }
+  const files = [];
+  const warnings = [];
+  const exposedSkills = /* @__PURE__ */ new Map();
+  const exposedCmds = /* @__PURE__ */ new Map();
+  for (const engine of opencodeLast(engines)) {
+    const renderer = getRenderer(engine);
+    const renderedSkills = [];
+    for (const skill of harness.skills) {
+      const result = renderer.renderSkill(skill);
+      warnings.push(...result.warnings);
+      if (result.files.length > 0) {
+        const alreadyVisible = engine === "opencode" && exposedSkills.has(skill.meta.id);
+        if (!alreadyVisible) files.push(...result.files);
+        renderedSkills.push(skill);
+        exposedSkills.set(skill.meta.id, skill);
+      }
+    }
+    const renderedSkillIds = new Set(renderedSkills.map((s) => s.meta.id));
+    const renderedCmds = [];
+    for (const cmd of harness.cmds) {
+      if (!renderedSkillIds.has(cmd.meta.invokes_skill)) continue;
+      const result = renderer.renderCmd(cmd);
+      warnings.push(...result.warnings);
+      if (result.files.length > 0) {
+        files.push(...result.files);
+        renderedCmds.push(cmd);
+        exposedCmds.set(cmd.meta.id, cmd);
+      }
+    }
+    const agentsResult = renderer.renderAgents(harness.agents);
+    warnings.push(...agentsResult.warnings);
+    files.push(...agentsResult.files);
+    if (input.mcpServers && input.mcpServers.length > 0) {
+      const specs = input.mcpServers.map((id) => MCP_SERVERS[id]);
+      const mcpResult = renderer.renderMcp(specs);
+      warnings.push(...mcpResult.warnings);
+      files.push(...mcpResult.files);
+    }
+    if (input.withStopHook !== false) {
+      const hookResult = renderer.renderStopHook();
+      warnings.push(...hookResult.warnings);
+      files.push(...hookResult.files);
     }
   }
-  const pruned = [];
-  const sorted = [...candidates].sort((a, b) => b.length - a.length);
-  for (const dir of sorted) {
-    if (!existsSync9(dir)) continue;
-    if (readdirSync(dir).length > 0) continue;
-    rmdirSync(dir);
-    pruned.push(relative2(root, dir));
+  const hasProjectSkills = (input.projectSkills?.length ?? 0) > 0;
+  const umbrellaContent = buildUmbrellaBody(harness.agents, {
+    availableSkills: Array.from(exposedSkills.values()),
+    availableCommands: Array.from(exposedCmds.values()),
+    hasProjectSkills,
+    hasQualityDoc: input.hasQualityDoc === true
+  });
+  files.push({ path: "AGENTS.md", content: umbrellaContent });
+  if (engines.includes("claude-code")) {
+    files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
   }
-  return pruned;
+  return { files, warnings };
 }
 
-// src/cli/init.ts
+// src/cli/plan-render.ts
 var QUALITY_DOC_PATH = "docs/quality/code-quality.md";
 function resolveEngineList(requested) {
-  if (!requested || requested.length === 0) return [...ENGINES];
-  return requested.map((e) => {
+  if (!requested) return [...ENGINES];
+  if (requested.length === 0) throw new Error("no engine selected");
+  const engines = requested.map((e) => {
     if (!ENGINES.includes(e)) {
       throw new Error(`unknown engine: ${e} (expected one of ${ENGINES.join(", ")})`);
     }
     return e;
   });
+  return [...new Set(engines)];
 }
 function defaultPackageDir() {
-  const here = dirname4(fileURLToPath(import.meta.url));
-  if (existsSync10(join11(here, "agents"))) return here;
-  return resolve4(here, "..");
+  const here = dirname3(fileURLToPath(import.meta.url));
+  if (existsSync9(join10(here, "agents"))) return here;
+  return resolve3(here, "..");
 }
 function planInit(args) {
   const engines = resolveEngineList(args.engines);
@@ -2053,7 +1989,7 @@ function planInit(args) {
   const harness = loadHarness(packageDir);
   const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
   const projectSkills = loadProjectSkills(args.targetDir);
-  const hasQualityDoc = existsSync10(join11(args.targetDir, QUALITY_DOC_PATH));
+  const hasQualityDoc = existsSync9(join10(args.targetDir, QUALITY_DOC_PATH));
   const mcpServers = args.mcpServers ? resolveMcpIds(args.mcpServers) : void 0;
   const stopHookInstalled = args.withStopHook !== false;
   const output = render({
@@ -2067,338 +2003,302 @@ function planInit(args) {
   });
   return { engines, output, stopHookInstalled };
 }
-function writeFilesToTarget(files, targetDir) {
-  assertManagedPaths(
-    targetDir,
-    files.map((file) => file.path)
-  );
-  const written = [];
-  for (const f of files) {
-    const full = join11(targetDir, f.path);
-    mkdirSync(dirname4(full), { recursive: true });
-    writeFileSync3(full, f.content);
-    written.push(f.path);
+
+// src/cli/uninstall.ts
+import {
+  existsSync as existsSync10,
+  readFileSync as readFileSync8,
+  readdirSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { dirname as dirname4, join as join11, relative as relative2, resolve as resolve4 } from "path";
+function uninstallCommand(args) {
+  const root = resolve4(args.targetDir);
+  const warnings = [];
+  assertManagedPaths(root, [MANIFEST_FILENAME]);
+  const manifest = readManifest(root);
+  if (!manifest) {
+    warnings.push(`no manifest found at ${manifestPath(root)} \u2014 nothing to uninstall`);
+    return { filesRemoved: [], dirsPruned: [], warnings };
   }
-  return written;
-}
-function initCommand(args) {
-  const { engines, output, stopHookInstalled } = planInit(args);
-  const previous = readManifest(args.targetDir);
-  assertManagedPaths(args.targetDir, [
-    MANIFEST_FILENAME,
-    ...previous?.files ?? [],
-    ...output.files.map((file) => file.path),
-    ...previous?.opencodeConfig ? [OPENCODE_CONFIG_PATH] : []
+  assertManagedPaths(root, [
+    ...manifest.files,
+    ...manifest.opencodeConfig ? [OPENCODE_CONFIG_PATH] : [],
+    ...manifest.mcpConfig ? [CLAUDE_MCP_PATH] : [],
+    ...Object.keys(manifest.hookConfigs ?? {})
   ]);
-  const desiredConfig = output.files.find((file) => file.path === OPENCODE_CONFIG_PATH);
-  const config = planOpenCodeConfig(args.targetDir, desiredConfig, previous?.opencodeConfig);
-  const next = new Set(output.files.map((f) => f.path));
-  const stale = (previous?.files ?? []).filter((f) => !next.has(f) && f !== OPENCODE_CONFIG_PATH);
-  if (config.remove) stale.push(OPENCODE_CONFIG_PATH);
-  const staleFilesRemoved = removeRenderedFiles(resolve4(args.targetDir), stale).filesRemoved;
-  const ownedFiles = output.files.filter((file) => file.path !== OPENCODE_CONFIG_PATH);
-  const filesWritten = writeFilesToTarget(ownedFiles, args.targetDir);
-  if (config.write) writeFilesToTarget([config.write], args.targetDir);
-  writeManifest(args.targetDir, engines, filesWritten, {
-    stopHookInstalled,
-    stopHookEngines: stopHookInstalled ? engines : void 0,
-    opencodeConfig: config.ownership,
-    overridesDir: args.overridesDir ? resolve4(args.overridesDir) === resolve4(args.targetDir) ? "." : resolve4(args.overridesDir) : void 0
+  const config = planOpenCodeConfig(root, void 0, manifest.opencodeConfig);
+  const mcp = planClaudeMcpConfig(root, void 0, manifest.mcpConfig);
+  const hooks = planHookConfigCleanup(root, manifest.hookConfigs);
+  const sharedHooks = new Set(Object.keys(manifest.hookConfigs ?? {}));
+  const modified = manifest.files.filter((file) => {
+    const hash2 = manifest.fileHashes?.[file];
+    const full = join11(root, file);
+    return hash2 !== void 0 && existsSync10(full) && hashContent(readFileSync8(full)) !== hash2;
   });
-  if (config.write) filesWritten.push(OPENCODE_CONFIG_PATH);
-  const warnings = [...output.warnings, ...config.warnings];
-  if (previous?.files.includes(OPENCODE_CONFIG_PATH) && !previous.opencodeConfig) {
+  const ownedFiles = manifest.files.filter(
+    (file) => file !== OPENCODE_CONFIG_PATH && !(manifest.mcpConfig && file === CLAUDE_MCP_PATH) && !sharedHooks.has(file) && !modified.includes(file)
+  );
+  if (config.remove) ownedFiles.push(OPENCODE_CONFIG_PATH);
+  if (mcp.remove) ownedFiles.push(CLAUDE_MCP_PATH);
+  ownedFiles.push(...hooks.removals);
+  const { filesRemoved, dirsPruned, missing } = removeRenderedFiles(root, ownedFiles);
+  for (const file of [config.write, mcp.write, ...hooks.writes]) {
+    if (file) writeFileSync2(join11(root, file.path), file.content);
+  }
+  warnings.push(...config.warnings, ...mcp.warnings, ...hooks.warnings);
+  for (const file of modified) warnings.push(`kept modified harness file: ${file}`);
+  if (manifest.files.includes(OPENCODE_CONFIG_PATH) && !manifest.opencodeConfig) {
     warnings.push(`preserved legacy shared configuration: ${OPENCODE_CONFIG_PATH}`);
   }
-  return { filesWritten, staleFilesRemoved, warnings, stopHookInstalled };
+  for (const rel of missing) warnings.push(`file in manifest is already missing: ${rel}`);
+  unlinkSync(manifestPath(root));
+  return { filesRemoved, dirsPruned, warnings };
 }
-
-// src/cli/render.ts
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync4 } from "fs";
-import { dirname as dirname5, join as join12 } from "path";
-function renderCommand(args) {
-  const engineList = args.engines && args.engines.length > 0 ? args.engines.map((e) => {
-    if (!ENGINES.includes(e)) {
-      throw new Error(`unknown engine: ${e}`);
+function removeRenderedFiles(root, files) {
+  assertManagedPaths(root, files);
+  const filesRemoved = [];
+  const missing = [];
+  const dirsToConsider = /* @__PURE__ */ new Set();
+  for (const rel of files) {
+    const full = join11(root, rel);
+    if (existsSync10(full)) {
+      unlinkSync(full);
+      filesRemoved.push(rel);
+      dirsToConsider.add(dirname4(full));
+    } else {
+      missing.push(rel);
     }
-    return e;
-  }) : [...ENGINES];
-  const harness = loadHarness(args.packageDir);
-  const mcpServers = args.mcpServers ? resolveMcpIds(args.mcpServers) : void 0;
-  const output = render({
-    harness,
-    engines: engineList,
-    mcpServers,
-    withStopHook: args.withStopHook !== false
-  });
-  const filesWritten = [];
-  for (const f of output.files) {
-    const full = join12(args.outDir, f.path);
-    mkdirSync2(dirname5(full), { recursive: true });
-    writeFileSync4(full, f.content);
-    filesWritten.push(f.path);
   }
-  return { filesWritten, warnings: output.warnings };
+  return { filesRemoved, dirsPruned: pruneEmptyDirs(root, dirsToConsider), missing };
 }
-
-// src/cli/stop-hook.ts
-import { readFileSync as readFileSync9 } from "fs";
-import { resolve as resolve5 } from "path";
-
-// src/stop-hook/adapters/claude.ts
-var claudeAdapter = {
-  parseInput(stdin) {
-    const parsed = stdin.trim() === "" ? {} : JSON.parse(stdin);
-    return {
-      sessionId: typeof parsed.session_id === "string" ? parsed.session_id : "default",
-      stopHookActive: parsed.stop_hook_active === true
-    };
-  },
-  respond(decision) {
-    if (decision.kind === "inject") {
-      return {
-        stdout: `${JSON.stringify({ decision: "block", reason: decision.reason ?? "" })}
-`,
-        stderr: "",
-        exitCode: 0
-      };
-    }
-    if (decision.kind === "terminate") {
-      return {
-        stdout: "",
-        stderr: `${decision.reason ?? ""}
-`,
-        exitCode: 0
-      };
-    }
-    return { stdout: "", stderr: "", exitCode: 0 };
-  }
-};
-
-// src/stop-hook/adapters/codex.ts
-var codexAdapter = {
-  parseInput(stdin) {
-    const parsed = stdin.trim() === "" ? {} : JSON.parse(stdin);
-    return {
-      sessionId: typeof parsed.session_id === "string" ? parsed.session_id : "default",
-      stopHookActive: parsed.stop_hook_active === true
-    };
-  },
-  respond(decision) {
-    if (decision.kind === "inject") {
-      return {
-        stdout: `${JSON.stringify({ decision: "block", reason: decision.reason ?? "" })}
-`,
-        stderr: "",
-        exitCode: 0
-      };
-    }
-    if (decision.kind === "terminate") {
-      return {
-        stdout: "",
-        stderr: `${decision.reason ?? ""}
-`,
-        exitCode: 0
-      };
+function pruneEmptyDirs(root, leaves) {
+  const candidates = /* @__PURE__ */ new Set();
+  for (const leaf of leaves) {
+    let cur = leaf;
+    while (cur !== root && cur.startsWith(`${root}/`)) {
+      candidates.add(cur);
+      cur = dirname4(cur);
     }
-    return { stdout: "", stderr: "", exitCode: 0 };
   }
-};
-
-// src/stop-hook/adapters/opencode.ts
-var opencodeAdapter = {
-  parseInput(stdin) {
-    const parsed = stdin.trim() === "" ? {} : JSON.parse(stdin);
-    const sessionId = typeof parsed.sessionID === "string" ? parsed.sessionID : typeof parsed.session_id === "string" ? parsed.session_id : "default";
-    return { sessionId, stopHookActive: false };
-  },
-  respond(decision) {
-    if (decision.kind === "inject") {
-      return { stdout: "", stderr: `${decision.reason ?? ""}
-`, exitCode: 2 };
-    }
-    if (decision.kind === "terminate") {
-      return { stdout: "", stderr: `${decision.reason ?? ""}
-`, exitCode: 0 };
-    }
-    return { stdout: "", stderr: "", exitCode: 0 };
+  const pruned = [];
+  const sorted = [...candidates].sort((a, b) => b.length - a.length);
+  for (const dir of sorted) {
+    if (!existsSync10(dir)) continue;
+    if (readdirSync(dir).length > 0) continue;
+    rmdirSync(dir);
+    pruned.push(relative2(root, dir));
   }
-};
-
-// src/stop-hook/adapters/index.ts
-var ADAPTERS = {
-  claude: claudeAdapter,
-  codex: codexAdapter,
-  opencode: opencodeAdapter
-};
-function getAdapter(engine) {
-  return ADAPTERS[engine];
+  return pruned;
 }
 
-// src/stop-hook/core.ts
-import { execFileSync as execFileSync2 } from "child_process";
-import { createHash as createHash2 } from "crypto";
-
-// src/stop-hook/state.ts
-import { existsSync as existsSync11, mkdirSync as mkdirSync3, readFileSync as readFileSync8, rmSync, writeFileSync as writeFileSync5 } from "fs";
-import { dirname as dirname6, join as join13 } from "path";
-import { z as z6 } from "zod";
-var LintStateSchema = z6.object({
-  attempts: z6.number().int().nonnegative(),
-  lastLintHash: z6.string(),
-  updatedAt: z6.string()
-});
-var STATE_DIR = ".harness/state";
-function safeSessionId(sessionId) {
-  return sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80) || "default";
-}
-function statePath(cwd, sessionId) {
-  return join13(cwd, STATE_DIR, `lint-${safeSessionId(sessionId)}.json`);
-}
-function readState(cwd, sessionId) {
-  const path = statePath(cwd, sessionId);
-  if (!existsSync11(path)) return null;
-  try {
-    const raw = JSON.parse(readFileSync8(path, "utf8"));
-    return LintStateSchema.parse(raw);
-  } catch {
-    return null;
+// src/cli/update-transaction.ts
+import { createHash as createHash2, randomUUID } from "crypto";
+import {
+  chmodSync as chmodSync2,
+  closeSync,
+  fsyncSync,
+  lstatSync as lstatSync2,
+  mkdirSync,
+  openSync,
+  readFileSync as readFileSync9,
+  readdirSync as readdirSync2,
+  realpathSync as realpathSync2,
+  rmdirSync as rmdirSync2,
+  unlinkSync as unlinkSync2,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { homedir } from "os";
+import { basename as basename3, dirname as dirname5, isAbsolute as isAbsolute3, join as join12, relative as relative3, resolve as resolve5, sep } from "path";
+var MANIFEST_PATH = ".harness-manifest.json";
+var PRIVATE_FILES = /* @__PURE__ */ new Set([
+  MANIFEST_PATH,
+  ".mcp.json",
+  ".codex/config.toml",
+  ".codex/hooks.json",
+  ".claude/settings.json",
+  ".opencode/opencode.json",
+  ".opencode/mcp.json"
+]);
+function canonicalRoot(root) {
+  let ancestor = resolve5(root);
+  const missing = [];
+  while (!lstatSync2(ancestor, { throwIfNoEntry: false })) {
+    missing.unshift(basename3(ancestor));
+    ancestor = dirname5(ancestor);
   }
+  return join12(realpathSync2(ancestor), ...missing);
 }
-function writeState(cwd, sessionId, state) {
-  const path = statePath(cwd, sessionId);
-  mkdirSync3(dirname6(path), { recursive: true });
-  writeFileSync5(path, `${JSON.stringify(state, null, 2)}
-`);
-}
-function resetState(cwd, sessionId) {
-  const path = statePath(cwd, sessionId);
-  if (existsSync11(path)) rmSync(path, { force: true });
-}
-
-// src/stop-hook/types.ts
-var STOP_HOOK_ENGINES = ["claude", "codex", "opencode"];
-var DEFAULT_MAX_ATTEMPTS = 3;
-
-// src/stop-hook/core.ts
-function exhaustedReason(attempts, lintOutput) {
-  return `Harness lint: still failing after ${attempts} attempts.
-
-${lintOutput}`;
-}
-function noProgressReason(lintOutput) {
-  return `Harness lint: no progress between attempts.
-
-${lintOutput}`;
+function contains(parent, child) {
+  const path = relative3(parent, child);
+  return path === "" || !isAbsolute3(path) && path !== ".." && !path.startsWith(`..${sep}`);
 }
-function hash(s) {
-  return createHash2("sha256").update(s).digest("hex").slice(0, 16);
+function assertBackupLocation(root, backup) {
+  if (contains(root, backup) || contains(backup, root)) {
+    throw new Error(`update backup must be outside the target project: ${backup}`);
+  }
+  const ancestors = [];
+  for (let path = backup; ; path = dirname5(path)) {
+    ancestors.unshift(path);
+    if (dirname5(path) === path) break;
+  }
+  for (const path of ancestors) {
+    const info = lstatSync2(path, { throwIfNoEntry: false });
+    if (!info) continue;
+    if (info.isSymbolicLink() || !info.isDirectory()) {
+      throw new Error(`unsafe update backup directory: ${path}`);
+    }
+  }
+  if (lstatSync2(backup, { throwIfNoEntry: false })) {
+    throw new Error(`update backup directory already exists: ${backup}`);
+  }
 }
-function maxAttempts(env) {
-  const raw = env.HARNESS_LINT_MAX_ATTEMPTS;
-  if (!raw) return DEFAULT_MAX_ATTEMPTS;
-  const n = Number.parseInt(raw, 10);
-  return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_ATTEMPTS;
+function createDirectories(path, created, mode = 511) {
+  const missing = [];
+  for (let current = path; !lstatSync2(current, { throwIfNoEntry: false }); current = dirname5(current)) {
+    missing.unshift(current);
+  }
+  for (const directory of missing) {
+    mkdirSync(directory, { mode });
+    created.push(directory);
+  }
 }
-function defaultGitStatus(cwd) {
+function writeBackupFile(path, content) {
+  createDirectories(dirname5(path), [], 448);
+  const fd = openSync(path, "wx", 384);
   try {
-    return execFileSync2("git", ["status", "--porcelain"], {
-      cwd,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"]
-    });
-  } catch {
-    return "";
+    writeFileSync3(fd, content);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
   }
 }
-function defaultRunLint(cwd) {
-  const report = runLinters(cwd);
-  return { pass: report.summary.pass, output: formatReportText(report) };
-}
-function decide(payload, coreEnv) {
-  if (coreEnv.env.HARNESS_LINT_DISABLE === "1") {
-    return { kind: "passthrough" };
-  }
-  if (payload.stopHookActive) {
-    return { kind: "passthrough" };
-  }
-  const dirty = coreEnv.gitStatus(coreEnv.cwd);
-  if (dirty.trim() === "") {
-    resetState(coreEnv.cwd, payload.sessionId);
-    return { kind: "passthrough" };
-  }
-  const lintResult = coreEnv.runLint(coreEnv.cwd);
-  if (lintResult.pass) {
-    resetState(coreEnv.cwd, payload.sessionId);
-    return { kind: "passthrough" };
+function saveSnapshot(root, paths, backup) {
+  const entries = [];
+  createDirectories(dirname5(backup), [], 448);
+  mkdirSync(backup, { mode: 448 });
+  for (const path of paths) {
+    const full = join12(root, path);
+    const info = lstatSync2(full, { throwIfNoEntry: false });
+    if (!info) {
+      entries.push({ path, exists: false });
+      continue;
+    }
+    const content = readFileSync9(full);
+    writeBackupFile(join12(backup, "files", path), content);
+    entries.push({
+      path,
+      exists: true,
+      mode: info.mode & 4095,
+      sha256: createHash2("sha256").update(content).digest("hex")
+    });
   }
-  const lintHash = hash(lintResult.output);
-  const prev = readState(coreEnv.cwd, payload.sessionId);
-  if (prev && prev.attempts > 0 && prev.lastLintHash === lintHash) {
-    resetState(coreEnv.cwd, payload.sessionId);
-    return { kind: "terminate", reason: noProgressReason(lintResult.output) };
+  writeBackupFile(
+    join12(backup, "snapshot.json"),
+    `${JSON.stringify({ version: 1, root, createdAt: (/* @__PURE__ */ new Date()).toISOString(), entries }, null, 2)}
+`
+  );
+  return entries;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function rollback(root, backup, entries, touched, createdDirectories) {
+  const errors = [];
+  for (const path of [...touched].reverse()) {
+    try {
+      assertManagedPaths(root, [path]);
+      const entry = entries.get(path);
+      const full = join12(root, path);
+      const current = lstatSync2(full, { throwIfNoEntry: false });
+      if (!entry?.exists) {
+        if (current) unlinkSync2(full);
+        continue;
+      }
+      const original = readFileSync9(join12(backup, "files", path));
+      if (!current || !readFileSync9(full).equals(original)) {
+        if (current) unlinkSync2(full);
+        writeFileSync3(full, original, { mode: 384 });
+      }
+      chmodSync2(full, entry.mode);
+    } catch (error) {
+      errors.push(`${path}: ${errorMessage(error)}`);
+    }
   }
-  const nextAttempts = (prev?.attempts ?? 0) + 1;
-  const limit = maxAttempts(coreEnv.env);
-  if (nextAttempts > limit) {
-    resetState(coreEnv.cwd, payload.sessionId);
-    return { kind: "terminate", reason: exhaustedReason(limit, lintResult.output) };
+  for (const directory of [...createdDirectories].reverse()) {
+    try {
+      if (readdirSync2(directory).length === 0) rmdirSync2(directory);
+    } catch (error) {
+      errors.push(`${directory}: ${errorMessage(error)}`);
+    }
   }
-  writeState(coreEnv.cwd, payload.sessionId, {
-    attempts: nextAttempts,
-    lastLintHash: lintHash,
-    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-  });
-  return { kind: "inject", reason: lintResult.output };
+  return errors;
 }
-
-// src/cli/stop-hook.ts
-function readStdinSync() {
+function applyUpdateTransaction(root, writes, removals, backupDir) {
+  const paths = [.../* @__PURE__ */ new Set([...removals, ...writes.map((file) => file.path)])];
+  assertManagedPaths(root, paths);
+  const target = canonicalRoot(root);
+  const backup = resolve5(
+    backupDir ?? join12(homedir(), ".local", "state", "vaubaan-harness", "backups", randomUUID())
+  );
+  assertBackupLocation(target, backup);
+  let snapshot;
   try {
-    return readFileSync9(0, "utf8");
-  } catch {
-    return "";
+    snapshot = saveSnapshot(target, paths, backup);
+  } catch (error) {
+    throw new Error(
+      `could not prepare update backup at ${backup}; project unchanged: ${errorMessage(error)}`,
+      { cause: error }
+    );
   }
-}
-function assertEngine(engine) {
-  if (!STOP_HOOK_ENGINES.includes(engine)) {
-    throw new Error(`unknown engine: ${engine} (expected one of ${STOP_HOOK_ENGINES.join(", ")})`);
+  const entries = new Map(snapshot.map((entry) => [entry.path, entry]));
+  const touched = /* @__PURE__ */ new Set();
+  const createdDirectories = [];
+  try {
+    assertManagedPaths(target, paths);
+    for (const path of removals) {
+      if (!lstatSync2(join12(target, path), { throwIfNoEntry: false })) continue;
+      touched.add(path);
+      unlinkSync2(join12(target, path));
+    }
+    for (const file of writes) {
+      const full = join12(target, file.path);
+      createDirectories(dirname5(full), createdDirectories);
+      touched.add(file.path);
+      const entry = entries.get(file.path);
+      const mode = file.path === MANIFEST_PATH ? 384 : entry?.exists ? entry.mode : PRIVATE_FILES.has(file.path) ? 384 : 420;
+      if (entry?.exists && file.path === MANIFEST_PATH) chmodSync2(full, mode);
+      writeFileSync3(full, file.content, { mode });
+      if (entry?.exists) chmodSync2(full, mode);
+    }
+  } catch (error) {
+    const failures = rollback(target, backup, entries, touched, createdDirectories);
+    const restoration = failures.length > 0 ? `rollback errors: ${failures.join("; ")}` : "rollback completed";
+    throw new Error(`update failed; backup: ${backup}; ${restoration}: ${errorMessage(error)}`, {
+      cause: error
+    });
   }
-  return engine;
-}
-function stopHookCommand(args, stdin) {
-  const engine = assertEngine(args.engine);
-  const cwd = resolve5(args.cwd ?? ".");
-  const adapter = getAdapter(engine);
-  const payload = adapter.parseInput(stdin, process.env);
-  const decision = decide(payload, {
-    cwd,
-    env: process.env,
-    gitStatus: defaultGitStatus,
-    runLint: defaultRunLint
-  });
-  return adapter.respond(decision);
-}
-function stopHookCommandFromStdin(args) {
-  return stopHookCommand(args, readStdinSync());
+  return { backupDir: backup };
 }
 
 // src/cli/update.ts
-import { existsSync as existsSync13, readFileSync as readFileSync12 } from "fs";
-import { join as join16, resolve as resolve7 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync11 } from "fs";
+import { join as join14, resolve as resolve6 } from "path";
 import { isDeepStrictEqual as isDeepStrictEqual3 } from "util";
 
 // src/cli/update-manifest.ts
-import { existsSync as existsSync12, readFileSync as readFileSync10 } from "fs";
-import { join as join14 } from "path";
-import { z as z7 } from "zod";
-var EngineSchema = z7.enum(ENGINES);
-var LegacySchema = z7.object({
-  version: z7.enum(["1", "2", "3"]),
+import { existsSync as existsSync11, readFileSync as readFileSync10 } from "fs";
+import { join as join13 } from "path";
+import { z as z6 } from "zod";
+var EngineSchema = z6.enum(ENGINES);
+var LegacySchema = z6.object({
+  version: z6.enum(["1", "2", "3"]),
   engine: EngineSchema.optional(),
-  engines: z7.array(EngineSchema).nonempty().optional(),
-  renderedAt: z7.string(),
-  files: z7.array(z7.string())
+  engines: z6.array(EngineSchema).nonempty().optional(),
+  renderedAt: z6.string(),
+  files: z6.array(z6.string())
 });
 var HOOK_PATHS = {
   "claude-code": [".claude/settings.json"],
@@ -2410,10 +2310,10 @@ var HOOK_PATHS = {
 };
 function readUpdateInstallation(root) {
   assertManagedPaths(root, [MANIFEST_FILENAME]);
-  if (!existsSync12(join14(root, MANIFEST_FILENAME))) {
+  if (!existsSync11(join13(root, MANIFEST_FILENAME))) {
     throw new Error("no harness manifest found; use init for a new installation");
   }
-  const raw = JSON.parse(readFileSync10(join14(root, MANIFEST_FILENAME), "utf8"));
+  const raw = JSON.parse(readFileSync10(join13(root, MANIFEST_FILENAME), "utf8"));
   const sourceVersion = String(raw?.version);
   let manifest;
   if (["1", "2", "3"].includes(sourceVersion)) {
@@ -2421,7 +2321,7 @@ function readUpdateInstallation(root) {
     const engines2 = legacy.version === "1" ? [EngineSchema.parse(legacy.engine)] : legacy.engines;
     manifest = {
       version: "4",
-      engines: z7.array(EngineSchema).nonempty().parse(engines2),
+      engines: z6.array(EngineSchema).nonempty().parse(engines2),
       files: legacy.files,
       renderedAt: legacy.renderedAt
     };
@@ -2430,8 +2330,8 @@ function readUpdateInstallation(root) {
     if (!current) throw new Error("harness manifest disappeared during planning");
     manifest = current;
   }
-  const engines = [...new Set(z7.array(EngineSchema).nonempty().parse(manifest.engines))];
-  const hookEngines = manifest.stopHookInstalled === false ? [] : manifest.stopHookEngines !== void 0 ? z7.array(EngineSchema).parse(manifest.stopHookEngines) : manifest.stopHookInstalled === true ? engines : engines.filter(
+  const engines = [...new Set(z6.array(EngineSchema).nonempty().parse(manifest.engines))];
+  const hookEngines = manifest.stopHookInstalled === false ? [] : manifest.stopHookEngines !== void 0 ? z6.array(EngineSchema).parse(manifest.stopHookEngines) : manifest.stopHookInstalled === true ? engines : engines.filter(
     (engine) => HOOK_PATHS[engine].some((path) => manifest.files.includes(path))
   );
   if (hookEngines.some((engine) => !engines.includes(engine))) {
@@ -2440,335 +2340,556 @@ function readUpdateInstallation(root) {
   return { manifest, sourceVersion, engines, hookEngines: [...new Set(hookEngines)] };
 }
 
-// src/cli/update-transaction.ts
-import { createHash as createHash3, randomUUID } from "crypto";
-import {
-  chmodSync as chmodSync2,
-  closeSync,
-  fsyncSync,
-  lstatSync as lstatSync2,
-  mkdirSync as mkdirSync4,
-  openSync,
-  readFileSync as readFileSync11,
-  readdirSync as readdirSync2,
-  realpathSync as realpathSync2,
-  rmdirSync as rmdirSync2,
-  unlinkSync as unlinkSync2,
-  writeFileSync as writeFileSync6
-} from "fs";
-import { homedir } from "os";
-import { basename as basename3, dirname as dirname7, isAbsolute as isAbsolute3, join as join15, relative as relative3, resolve as resolve6, sep } from "path";
-var MANIFEST_PATH = ".harness-manifest.json";
-var PRIVATE_FILES = /* @__PURE__ */ new Set([
-  MANIFEST_PATH,
-  ".mcp.json",
-  ".codex/config.toml",
-  ".codex/hooks.json",
-  ".claude/settings.json",
-  ".opencode/opencode.json",
-  ".opencode/mcp.json"
-]);
-function canonicalRoot(root) {
-  let ancestor = resolve6(root);
-  const missing = [];
-  while (!lstatSync2(ancestor, { throwIfNoEntry: false })) {
-    missing.unshift(basename3(ancestor));
-    ancestor = dirname7(ancestor);
-  }
-  return join15(realpathSync2(ancestor), ...missing);
+// src/cli/update.ts
+var CODEX_CONFIG_PATH = ".codex/config.toml";
+function currentContent(root, path) {
+  return existsSync12(join14(root, path)) ? readFileSync11(join14(root, path), "utf8") : void 0;
 }
-function contains(parent, child) {
-  const path = relative3(parent, child);
-  return path === "" || !isAbsolute3(path) && path !== ".." && !path.startsWith(`..${sep}`);
+function ownedUnchanged(root, previous, path) {
+  const content = currentContent(root, path);
+  if (content === void 0 || !previous.files.includes(path)) return false;
+  const hash2 = previous.fileHashes?.[path];
+  return hash2 === void 0 || hash2 === hashContent(content);
 }
-function assertBackupLocation(root, backup) {
-  if (contains(root, backup) || contains(backup, root)) {
-    throw new Error(`update backup must be outside the target project: ${backup}`);
+function checkArtifactConflicts(root, previous, writes, removals) {
+  const desired = new Map(writes.map((file) => [file.path, file.content]));
+  const conflicts = [];
+  for (const path of [...desired.keys(), ...removals]) {
+    if (SHARED_CONFIG_PATHS.includes(path)) continue;
+    const content = currentContent(root, path);
+    if (content === void 0 || content === desired.get(path)) continue;
+    if (!previous.files.includes(path)) {
+      conflicts.push(`existing file outside harness manifest: ${path}`);
+      continue;
+    }
+    const hash2 = previous.fileHashes?.[path];
+    if (hash2 && hash2 !== hashContent(content)) conflicts.push(`modified harness file: ${path}`);
   }
-  const ancestors = [];
-  for (let path = backup; ; path = dirname7(path)) {
-    ancestors.unshift(path);
-    if (dirname7(path) === path) break;
+  if (conflicts.length) {
+    throw new Error(
+      `${conflicts.join("\n")}
+move their content to docs/ or .harness-overrides/, or keep them as yours with --preserve <path>`
+    );
   }
-  for (const path of ancestors) {
-    const info = lstatSync2(path, { throwIfNoEntry: false });
-    if (!info) continue;
-    if (info.isSymbolicLink() || !info.isDirectory()) {
-      throw new Error(`unsafe update backup directory: ${path}`);
-    }
+}
+function legacyMcpOwnership(root, previous) {
+  if (!ownedUnchanged(root, previous, CLAUDE_MCP_PATH)) return void 0;
+  try {
+    const servers = JSON.parse(currentContent(root, CLAUDE_MCP_PATH) ?? "").mcpServers;
+    if (!servers || typeof servers !== "object" || Array.isArray(servers)) return void 0;
+    return { createdFile: true, addedMcp: true, addedSchema: false, entries: servers };
+  } catch {
+    return void 0;
   }
-  if (lstatSync2(backup, { throwIfNoEntry: false })) {
-    throw new Error(`update backup directory already exists: ${backup}`);
+}
+function planMcp(root, settings, rendered, pendingWrites) {
+  const { previous } = settings;
+  const plan = {
+    writes: [],
+    removals: [],
+    owned: [],
+    plannedOpenCode: false,
+    warnings: []
+  };
+  const claudeOwnership = previous.mcpConfig ?? legacyMcpOwnership(root, previous);
+  const codexOwned = ownedUnchanged(root, previous, CODEX_CONFIG_PATH);
+  if (settings.mcpServers === void 0) {
+    if (codexOwned) plan.owned.push(CODEX_CONFIG_PATH);
+    plan.mcpConfig = claudeOwnership;
+    return plan;
+  }
+  const desired = (path) => rendered.find((file) => file.path === path);
+  if (!pendingWrites.some((file) => file.path === OPENCODE_CONFIG_PATH)) {
+    plan.plannedOpenCode = true;
+    if (previous.files.includes(OPENCODE_CONFIG_PATH) && !previous.opencodeConfig) {
+      plan.warnings.push(`preserved legacy shared configuration: ${OPENCODE_CONFIG_PATH}`);
+    }
+    const opencode = planOpenCodeConfig(
+      root,
+      desired(OPENCODE_CONFIG_PATH),
+      previous.opencodeConfig
+    );
+    if (opencode.write) plan.writes.push(opencode.write);
+    if (opencode.remove) plan.removals.push(OPENCODE_CONFIG_PATH);
+    plan.opencodeConfig = opencode.ownership;
+    plan.warnings.push(...opencode.warnings);
+  }
+  const claude = planClaudeMcpConfig(root, desired(CLAUDE_MCP_PATH), claudeOwnership);
+  if (claude.write) plan.writes.push(claude.write);
+  if (claude.remove) plan.removals.push(CLAUDE_MCP_PATH);
+  plan.mcpConfig = claude.ownership;
+  plan.warnings.push(...claude.warnings);
+  const codex = desired(CODEX_CONFIG_PATH);
+  const codexExists = existsSync12(join14(root, CODEX_CONFIG_PATH));
+  if (codex && (!codexExists || codexOwned)) {
+    plan.writes.push(codex);
+    plan.owned.push(CODEX_CONFIG_PATH);
+  } else if (codex) {
+    plan.warnings.push(
+      `left ${CODEX_CONFIG_PATH} unchanged; add this block to it to enable MCP in Codex:
+${codex.content.trimEnd()}`
+    );
+  } else if (codexOwned) {
+    plan.removals.push(CODEX_CONFIG_PATH);
   }
+  return plan;
 }
-function createDirectories(path, created, mode = 511) {
-  const missing = [];
-  for (let current = path; !lstatSync2(current, { throwIfNoEntry: false }); current = dirname7(current)) {
-    missing.unshift(current);
+function planInstallation(args, settings) {
+  const root = resolve6(args.targetDir);
+  const { previous, engines, hookEngines } = settings;
+  const preserved = [
+    .../* @__PURE__ */ new Set([...previous.preservedFiles ?? [], ...args.preserveFiles ?? []])
+  ].sort();
+  if (preserved.includes(MANIFEST_FILENAME))
+    throw new Error("cannot preserve the harness manifest");
+  if (preserved.some((path) => SHARED_CONFIG_PATHS.includes(path))) {
+    throw new Error(
+      "--preserve applies to generated artifacts; shared configurations use entry-level preservation"
+    );
   }
-  for (const directory of missing) {
-    mkdirSync4(directory, { mode });
-    created.push(directory);
+  assertManagedPaths(root, [...previous.files, ...preserved, ...SHARED_CONFIG_PATHS]);
+  const requestedOverrides = args.overridesDir ?? previous.overridesDir;
+  const overridesDir = args.overridesDir ? resolve6(args.overridesDir) : previous.overridesDir ? resolve6(root, previous.overridesDir) : root;
+  if (requestedOverrides && !existsSync12(join14(overridesDir, ".harness-overrides"))) {
+    throw new Error(`recorded overrides are missing: ${overridesDir}/.harness-overrides`);
+  }
+  const hasOverrides = existsSync12(join14(overridesDir, ".harness-overrides"));
+  const disablePath = join14(overridesDir, ".harness-overrides", "disable.yaml");
+  if (existsSync12(disablePath)) {
+    try {
+      DisableYamlSchema.parse(parseYAML(readFileSync11(disablePath, "utf8")));
+    } catch {
+      throw new Error(`invalid override selection: ${disablePath}`);
+    }
+  }
+  const rendered = planInit({
+    targetDir: root,
+    packageDir: args.packageDir,
+    engines,
+    overridesDir: hasOverrides ? overridesDir : void 0,
+    mcpServers: settings.mcpServers,
+    withStopHook: false
+  });
+  const generated = rendered.output.files.filter(
+    (file) => !SHARED_CONFIG_PATHS.includes(file.path)
+  );
+  const config = planUpdateConfigs(root, previous, hookEngines);
+  const mcp = planMcp(root, settings, rendered.output.files, config.writes);
+  const output = [...generated, ...config.writes, ...mcp.writes].filter(
+    (file) => !preserved.includes(file.path)
+  );
+  const owned = [
+    .../* @__PURE__ */ new Set([...generated.map((file) => file.path), ...config.ownedFiles, ...mcp.owned])
+  ].filter((file) => !preserved.includes(file)).sort();
+  const removals = [
+    .../* @__PURE__ */ new Set([
+      ...previous.files.filter(
+        (file) => !owned.includes(file) && !SHARED_CONFIG_PATHS.includes(file)
+      ),
+      ...config.removals,
+      ...mcp.removals
+    ])
+  ].filter((file) => !preserved.includes(file));
+  assertManagedPaths(root, [...output.map((file) => file.path), ...removals]);
+  checkArtifactConflicts(root, previous, output, removals);
+  const hashes = Object.fromEntries(
+    owned.map((path) => {
+      const content = output.find((file) => file.path === path)?.content ?? currentContent(root, path);
+      if (content === void 0) throw new Error(`missing planned harness file: ${path}`);
+      return [path, hashContent(content)];
+    })
+  );
+  const opencodeConfig = mcp.plannedOpenCode ? mcp.opencodeConfig : config.opencodeConfig;
+  const manifest = {
+    version: MANIFEST_VERSION,
+    harnessVersion: VERSION,
+    engines: [...engines].sort(),
+    renderedAt: previous.renderedAt,
+    files: owned,
+    fileHashes: hashes,
+    stopHookInstalled: hookEngines.length > 0,
+    stopHookEngines: [...hookEngines].sort(),
+    ...hasOverrides ? { overridesDir: overridesDir === root ? "." : overridesDir } : {},
+    ...preserved.length ? { preservedFiles: preserved } : {},
+    ...opencodeConfig ? { opencodeConfig } : {},
+    ...mcp.mcpConfig ? { mcpConfig: mcp.mcpConfig } : {},
+    ...config.hookConfigs ? { hookConfigs: config.hookConfigs } : {}
+  };
+  const writes = output.filter((file) => currentContent(root, file.path) !== file.content);
+  const existingRemovals = removals.filter((path) => existsSync12(join14(root, path)));
+  if (writes.length || existingRemovals.length || !isDeepStrictEqual3(previous, manifest)) {
+    manifest.renderedAt = (/* @__PURE__ */ new Date()).toISOString();
+    writes.push({ path: MANIFEST_FILENAME, content: `${JSON.stringify(manifest, null, 2)}
+` });
   }
+  const warnings = [...rendered.output.warnings, ...config.warnings, ...mcp.warnings];
+  if (preserved.length) warnings.push(`preserved user-owned artifacts: ${preserved.join(", ")}`);
+  return { writes, removals: existingRemovals, owned, manifest, warnings };
 }
-function writeBackupFile(path, content) {
-  createDirectories(dirname7(path), [], 448);
-  const fd = openSync(path, "wx", 384);
-  try {
-    writeFileSync6(fd, content);
-    fsyncSync(fd);
-  } finally {
-    closeSync(fd);
+function planUpdate(args) {
+  const root = resolve6(args.targetDir);
+  const { manifest: previous, sourceVersion, engines, hookEngines } = readUpdateInstallation(root);
+  const plan = planInstallation(args, { previous, sourceVersion, engines, hookEngines });
+  const warnings = [...plan.warnings];
+  if (!previous.fileHashes) {
+    warnings.push(
+      "legacy manifest has no file fingerprints: managed artifacts will be regenerated; backup preserves their previous contents"
+    );
   }
+  if (engines.includes("codex-cli"))
+    warnings.push("ensure .agents/ is ignored by Git (run harness check)");
+  return {
+    writes: plan.writes,
+    removals: plan.removals,
+    owned: plan.owned,
+    result: {
+      version: VERSION,
+      fromManifestVersion: sourceVersion,
+      dryRun: args.dryRun === true,
+      upToDate: plan.writes.length === 0 && plan.removals.length === 0,
+      filesToWrite: plan.writes.map((file) => file.path),
+      filesToRemove: plan.removals,
+      warnings
+    }
+  };
 }
-function saveSnapshot(root, paths, backup) {
-  const entries = [];
-  createDirectories(dirname7(backup), [], 448);
-  mkdirSync4(backup, { mode: 448 });
-  for (const path of paths) {
-    const full = join15(root, path);
-    const info = lstatSync2(full, { throwIfNoEntry: false });
-    if (!info) {
-      entries.push({ path, exists: false });
-      continue;
+function updateCommand(args) {
+  const plan = planUpdate(args);
+  if (args.dryRun || plan.result.upToDate) return plan.result;
+  const { backupDir } = applyUpdateTransaction(
+    resolve6(args.targetDir),
+    plan.writes,
+    plan.removals,
+    args.backupDir
+  );
+  return { ...plan.result, backupDir };
+}
+
+// src/cli/init.ts
+function emptyManifest(engines) {
+  return { version: MANIFEST_VERSION, engines: [...engines], renderedAt: "", files: [] };
+}
+function initCommand(args) {
+  const root = resolve7(args.targetDir);
+  const engines = resolveEngineList(args.engines);
+  const stopHookInstalled = args.withStopHook !== false;
+  const previous = readManifest(root) ?? emptyManifest(engines);
+  const plan = planInstallation(
+    {
+      targetDir: root,
+      packageDir: args.packageDir,
+      overridesDir: args.overridesDir,
+      preserveFiles: args.preserveFiles
+    },
+    {
+      previous,
+      sourceVersion: previous.version,
+      engines,
+      hookEngines: stopHookInstalled ? engines : [],
+      mcpServers: args.mcpServers ?? []
     }
-    const content = readFileSync11(full);
-    writeBackupFile(join15(backup, "files", path), content);
-    entries.push({
-      path,
-      exists: true,
-      mode: info.mode & 4095,
-      sha256: createHash3("sha256").update(content).digest("hex")
-    });
-  }
-  writeBackupFile(
-    join15(backup, "snapshot.json"),
-    `${JSON.stringify({ version: 1, root, createdAt: (/* @__PURE__ */ new Date()).toISOString(), entries }, null, 2)}
-`
   );
-  return entries;
+  const touchedExisting = [...plan.writes.map((file) => file.path), ...plan.removals].some(
+    (path) => path !== MANIFEST_FILENAME && existsSync13(join15(root, path))
+  );
+  let backupDir;
+  if (plan.writes.length || plan.removals.length) {
+    backupDir = applyUpdateTransaction(root, plan.writes, plan.removals, args.backupDir).backupDir;
+    if (!touchedExisting && !args.backupDir) {
+      rmSync(backupDir, { recursive: true, force: true });
+      backupDir = void 0;
+    }
+    pruneEmptyDirs(root, new Set(plan.removals.map((path) => dirname6(join15(root, path)))));
+  }
+  const sharedWritten = plan.writes.map((file) => file.path).filter((path) => SHARED_CONFIG_PATHS.includes(path) && !plan.owned.includes(path));
+  return {
+    filesWritten: [...plan.owned, ...sharedWritten],
+    staleFilesRemoved: plan.removals,
+    warnings: plan.warnings,
+    stopHookInstalled,
+    engines,
+    ...backupDir ? { backupDir } : {}
+  };
 }
-function errorMessage(error) {
-  return error instanceof Error ? error.message : String(error);
+
+// src/cli/render.ts
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname7, join as join16 } from "path";
+function renderCommand(args) {
+  const engineList = args.engines && args.engines.length > 0 ? args.engines.map((e) => {
+    if (!ENGINES.includes(e)) {
+      throw new Error(`unknown engine: ${e}`);
+    }
+    return e;
+  }) : [...ENGINES];
+  const harness = loadHarness(args.packageDir);
+  const mcpServers = args.mcpServers ? resolveMcpIds(args.mcpServers) : void 0;
+  const output = render({
+    harness,
+    engines: engineList,
+    mcpServers,
+    withStopHook: args.withStopHook !== false
+  });
+  const filesWritten = [];
+  for (const f of output.files) {
+    const full = join16(args.outDir, f.path);
+    mkdirSync3(dirname7(full), { recursive: true });
+    writeFileSync5(full, f.content);
+    filesWritten.push(f.path);
+  }
+  return { filesWritten, warnings: output.warnings };
 }
-function rollback(root, backup, entries, touched, createdDirectories) {
-  const errors = [];
-  for (const path of [...touched].reverse()) {
-    try {
-      assertManagedPaths(root, [path]);
-      const entry = entries.get(path);
-      const full = join15(root, path);
-      const current = lstatSync2(full, { throwIfNoEntry: false });
-      if (!entry?.exists) {
-        if (current) unlinkSync2(full);
-        continue;
-      }
-      const original = readFileSync11(join15(backup, "files", path));
-      if (!current || !readFileSync11(full).equals(original)) {
-        if (current) unlinkSync2(full);
-        writeFileSync6(full, original, { mode: 384 });
-      }
-      chmodSync2(full, entry.mode);
-    } catch (error) {
-      errors.push(`${path}: ${errorMessage(error)}`);
+
+// src/cli/stop-hook.ts
+import { readFileSync as readFileSync13 } from "fs";
+import { resolve as resolve8 } from "path";
+
+// src/stop-hook/adapters/claude.ts
+var claudeAdapter = {
+  parseInput(stdin) {
+    const parsed = stdin.trim() === "" ? {} : JSON.parse(stdin);
+    return {
+      sessionId: typeof parsed.session_id === "string" ? parsed.session_id : "default",
+      stopHookActive: parsed.stop_hook_active === true
+    };
+  },
+  respond(decision) {
+    if (decision.kind === "inject") {
+      return {
+        stdout: `${JSON.stringify({ decision: "block", reason: decision.reason ?? "" })}
+`,
+        stderr: "",
+        exitCode: 0
+      };
     }
+    if (decision.kind === "terminate") {
+      return {
+        stdout: "",
+        stderr: `${decision.reason ?? ""}
+`,
+        exitCode: 0
+      };
+    }
+    return { stdout: "", stderr: "", exitCode: 0 };
   }
-  for (const directory of [...createdDirectories].reverse()) {
-    try {
-      if (readdirSync2(directory).length === 0) rmdirSync2(directory);
-    } catch (error) {
-      errors.push(`${directory}: ${errorMessage(error)}`);
+};
+
+// src/stop-hook/adapters/codex.ts
+var codexAdapter = {
+  parseInput(stdin) {
+    const parsed = stdin.trim() === "" ? {} : JSON.parse(stdin);
+    return {
+      sessionId: typeof parsed.session_id === "string" ? parsed.session_id : "default",
+      stopHookActive: parsed.stop_hook_active === true
+    };
+  },
+  respond(decision) {
+    if (decision.kind === "inject") {
+      return {
+        stdout: `${JSON.stringify({ decision: "block", reason: decision.reason ?? "" })}
+`,
+        stderr: "",
+        exitCode: 0
+      };
     }
+    if (decision.kind === "terminate") {
+      return {
+        stdout: "",
+        stderr: `${decision.reason ?? ""}
+`,
+        exitCode: 0
+      };
+    }
+    return { stdout: "", stderr: "", exitCode: 0 };
   }
-  return errors;
+};
+
+// src/stop-hook/adapters/opencode.ts
+var opencodeAdapter = {
+  parseInput(stdin) {
+    const parsed = stdin.trim() === "" ? {} : JSON.parse(stdin);
+    const sessionId = typeof parsed.sessionID === "string" ? parsed.sessionID : typeof parsed.session_id === "string" ? parsed.session_id : "default";
+    return { sessionId, stopHookActive: false };
+  },
+  respond(decision) {
+    if (decision.kind === "inject") {
+      return { stdout: "", stderr: `${decision.reason ?? ""}
+`, exitCode: 2 };
+    }
+    if (decision.kind === "terminate") {
+      return { stdout: "", stderr: `${decision.reason ?? ""}
+`, exitCode: 0 };
+    }
+    return { stdout: "", stderr: "", exitCode: 0 };
+  }
+};
+
+// src/stop-hook/adapters/index.ts
+var ADAPTERS = {
+  claude: claudeAdapter,
+  codex: codexAdapter,
+  opencode: opencodeAdapter
+};
+function getAdapter(engine) {
+  return ADAPTERS[engine];
 }
-function applyUpdateTransaction(root, writes, removals, backupDir) {
-  const paths = [.../* @__PURE__ */ new Set([...removals, ...writes.map((file) => file.path)])];
-  assertManagedPaths(root, paths);
-  const target = canonicalRoot(root);
-  const backup = resolve6(
-    backupDir ?? join15(homedir(), ".local", "state", "vaubaan-harness", "backups", randomUUID())
-  );
-  assertBackupLocation(target, backup);
-  let snapshot;
+
+// src/stop-hook/core.ts
+import { execFileSync as execFileSync2 } from "child_process";
+import { createHash as createHash3 } from "crypto";
+
+// src/stop-hook/state.ts
+import { existsSync as existsSync14, mkdirSync as mkdirSync4, readFileSync as readFileSync12, rmSync as rmSync2, writeFileSync as writeFileSync6 } from "fs";
+import { dirname as dirname8, join as join17 } from "path";
+import { z as z7 } from "zod";
+var LintStateSchema = z7.object({
+  attempts: z7.number().int().nonnegative(),
+  lastLintHash: z7.string(),
+  updatedAt: z7.string()
+});
+var STATE_DIR = ".harness/state";
+function safeSessionId(sessionId) {
+  return sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80) || "default";
+}
+function statePath(cwd, sessionId) {
+  return join17(cwd, STATE_DIR, `lint-${safeSessionId(sessionId)}.json`);
+}
+function readState(cwd, sessionId) {
+  const path = statePath(cwd, sessionId);
+  if (!existsSync14(path)) return null;
   try {
-    snapshot = saveSnapshot(target, paths, backup);
-  } catch (error) {
-    throw new Error(
-      `could not prepare update backup at ${backup}; project unchanged: ${errorMessage(error)}`,
-      { cause: error }
-    );
+    const raw = JSON.parse(readFileSync12(path, "utf8"));
+    return LintStateSchema.parse(raw);
+  } catch {
+    return null;
   }
-  const entries = new Map(snapshot.map((entry) => [entry.path, entry]));
-  const touched = /* @__PURE__ */ new Set();
-  const createdDirectories = [];
+}
+function writeState(cwd, sessionId, state) {
+  const path = statePath(cwd, sessionId);
+  mkdirSync4(dirname8(path), { recursive: true });
+  writeFileSync6(path, `${JSON.stringify(state, null, 2)}
+`);
+}
+function resetState(cwd, sessionId) {
+  const path = statePath(cwd, sessionId);
+  if (existsSync14(path)) rmSync2(path, { force: true });
+}
+
+// src/stop-hook/types.ts
+var STOP_HOOK_ENGINES = ["claude", "codex", "opencode"];
+var DEFAULT_MAX_ATTEMPTS = 3;
+
+// src/stop-hook/core.ts
+function exhaustedReason(attempts, lintOutput) {
+  return `Harness lint: still failing after ${attempts} attempts.
+
+${lintOutput}`;
+}
+function noProgressReason(lintOutput) {
+  return `Harness lint: no progress between attempts.
+
+${lintOutput}`;
+}
+function hash(s) {
+  return createHash3("sha256").update(s).digest("hex").slice(0, 16);
+}
+function maxAttempts(env) {
+  const raw = env.HARNESS_LINT_MAX_ATTEMPTS;
+  if (!raw) return DEFAULT_MAX_ATTEMPTS;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_ATTEMPTS;
+}
+function defaultGitStatus(cwd) {
   try {
-    assertManagedPaths(target, paths);
-    for (const path of removals) {
-      if (!lstatSync2(join15(target, path), { throwIfNoEntry: false })) continue;
-      touched.add(path);
-      unlinkSync2(join15(target, path));
-    }
-    for (const file of writes) {
-      const full = join15(target, file.path);
-      createDirectories(dirname7(full), createdDirectories);
-      touched.add(file.path);
-      const entry = entries.get(file.path);
-      const mode = file.path === MANIFEST_PATH ? 384 : entry?.exists ? entry.mode : PRIVATE_FILES.has(file.path) ? 384 : 420;
-      if (entry?.exists && file.path === MANIFEST_PATH) chmodSync2(full, mode);
-      writeFileSync6(full, file.content, { mode });
-      if (entry?.exists) chmodSync2(full, mode);
-    }
-  } catch (error) {
-    const failures = rollback(target, backup, entries, touched, createdDirectories);
-    const restoration = failures.length > 0 ? `rollback errors: ${failures.join("; ")}` : "rollback completed";
-    throw new Error(`update failed; backup: ${backup}; ${restoration}: ${errorMessage(error)}`, {
-      cause: error
+    return execFileSync2("git", ["status", "--porcelain"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
     });
+  } catch {
+    return "";
   }
-  return { backupDir: backup };
 }
-
-// src/cli/update.ts
-function currentContent(root, path) {
-  return existsSync13(join16(root, path)) ? readFileSync12(join16(root, path), "utf8") : void 0;
+function defaultRunLint(cwd) {
+  const report = runLinters(cwd);
+  return { pass: report.summary.pass, output: formatReportText(report) };
 }
-function checkArtifactConflicts(root, previous, writes, removals) {
-  const desired = new Map(writes.map((file) => [file.path, file.content]));
-  for (const path of [...desired.keys(), ...removals]) {
-    if (SHARED_CONFIG_PATHS.includes(path)) continue;
-    const content = currentContent(root, path);
-    if (content === void 0) continue;
-    if (!previous.files.includes(path)) {
-      throw new Error(
-        `existing file outside harness manifest: ${path}; use overrides or --preserve`
-      );
-    }
-    const hash2 = previous.fileHashes?.[path];
-    if (hash2 && hash2 !== hashContent(content) && content !== desired.get(path)) {
-      throw new Error(`modified harness file: ${path}; move edits to overrides or use --preserve`);
-    }
+function decide(payload, coreEnv) {
+  if (coreEnv.env.HARNESS_LINT_DISABLE === "1") {
+    return { kind: "passthrough" };
   }
-}
-function planUpdate(args) {
-  const root = resolve7(args.targetDir);
-  const { manifest: previous, sourceVersion, engines, hookEngines } = readUpdateInstallation(root);
-  const preserved = [
-    .../* @__PURE__ */ new Set([...previous.preservedFiles ?? [], ...args.preserveFiles ?? []])
-  ].sort();
-  if (preserved.includes(MANIFEST_FILENAME))
-    throw new Error("cannot preserve the harness manifest");
-  if (preserved.some((path) => SHARED_CONFIG_PATHS.includes(path))) {
-    throw new Error(
-      "--preserve applies to generated artifacts; shared configurations use entry-level preservation"
-    );
+  if (payload.stopHookActive) {
+    return { kind: "passthrough" };
   }
-  assertManagedPaths(root, [...previous.files, ...preserved, ...SHARED_CONFIG_PATHS]);
-  const requestedOverrides = args.overridesDir ?? previous.overridesDir;
-  const overridesDir = args.overridesDir ? resolve7(args.overridesDir) : previous.overridesDir ? resolve7(root, previous.overridesDir) : root;
-  if (requestedOverrides && !existsSync13(join16(overridesDir, ".harness-overrides"))) {
-    throw new Error(`recorded overrides are missing: ${overridesDir}/.harness-overrides`);
+  const dirty = coreEnv.gitStatus(coreEnv.cwd);
+  if (dirty.trim() === "") {
+    resetState(coreEnv.cwd, payload.sessionId);
+    return { kind: "passthrough" };
   }
-  const hasOverrides = existsSync13(join16(overridesDir, ".harness-overrides"));
-  const disablePath = join16(overridesDir, ".harness-overrides", "disable.yaml");
-  if (existsSync13(disablePath)) {
-    try {
-      DisableYamlSchema.parse(parseYAML(readFileSync12(disablePath, "utf8")));
-    } catch {
-      throw new Error(`invalid override selection: ${disablePath}`);
-    }
+  const lintResult = coreEnv.runLint(coreEnv.cwd);
+  if (lintResult.pass) {
+    resetState(coreEnv.cwd, payload.sessionId);
+    return { kind: "passthrough" };
   }
-  const rendered = planInit({
-    targetDir: root,
-    packageDir: args.packageDir,
-    engines,
-    overridesDir: hasOverrides ? overridesDir : void 0,
-    withStopHook: false
+  const lintHash = hash(lintResult.output);
+  const prev = readState(coreEnv.cwd, payload.sessionId);
+  if (prev && prev.attempts > 0 && prev.lastLintHash === lintHash) {
+    resetState(coreEnv.cwd, payload.sessionId);
+    return { kind: "terminate", reason: noProgressReason(lintResult.output) };
+  }
+  const nextAttempts = (prev?.attempts ?? 0) + 1;
+  const limit = maxAttempts(coreEnv.env);
+  if (nextAttempts > limit) {
+    resetState(coreEnv.cwd, payload.sessionId);
+    return { kind: "terminate", reason: exhaustedReason(limit, lintResult.output) };
+  }
+  writeState(coreEnv.cwd, payload.sessionId, {
+    attempts: nextAttempts,
+    lastLintHash: lintHash,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   });
-  const config = planUpdateConfigs(root, previous, hookEngines);
-  const output = [...rendered.output.files, ...config.writes].filter(
-    (file) => !preserved.includes(file.path)
-  );
-  const owned = [
-    .../* @__PURE__ */ new Set([...rendered.output.files.map((file) => file.path), ...config.ownedFiles])
-  ].filter((file) => !preserved.includes(file)).sort();
-  const removals = [
-    .../* @__PURE__ */ new Set([
-      ...previous.files.filter(
-        (file) => !owned.includes(file) && !SHARED_CONFIG_PATHS.includes(file)
-      ),
-      ...config.removals
-    ])
-  ].filter((file) => !preserved.includes(file));
-  assertManagedPaths(root, [...output.map((file) => file.path), ...removals]);
-  checkArtifactConflicts(root, previous, output, removals);
-  const hashes = Object.fromEntries(
-    owned.map((path) => {
-      const content = output.find((file) => file.path === path)?.content ?? currentContent(root, path);
-      if (content === void 0) throw new Error(`missing planned harness file: ${path}`);
-      return [path, hashContent(content)];
-    })
-  );
-  const manifest = {
-    version: MANIFEST_VERSION,
-    harnessVersion: VERSION,
-    engines: [...engines].sort(),
-    renderedAt: previous.renderedAt,
-    files: owned,
-    fileHashes: hashes,
-    stopHookInstalled: hookEngines.length > 0,
-    stopHookEngines: [...hookEngines].sort(),
-    ...hasOverrides ? { overridesDir: overridesDir === root ? "." : overridesDir } : {},
-    ...preserved.length ? { preservedFiles: preserved } : {},
-    ...config.opencodeConfig ? { opencodeConfig: config.opencodeConfig } : {},
-    ...config.hookConfigs ? { hookConfigs: config.hookConfigs } : {}
-  };
-  const writes = output.filter((file) => currentContent(root, file.path) !== file.content);
-  const existingRemovals = removals.filter((path) => existsSync13(join16(root, path)));
-  if (writes.length || existingRemovals.length || !isDeepStrictEqual3(previous, manifest)) {
-    manifest.renderedAt = (/* @__PURE__ */ new Date()).toISOString();
-    writes.push({ path: MANIFEST_FILENAME, content: `${JSON.stringify(manifest, null, 2)}
-` });
+  return { kind: "inject", reason: lintResult.output };
+}
+
+// src/cli/stop-hook.ts
+function readStdinSync() {
+  try {
+    return readFileSync13(0, "utf8");
+  } catch {
+    return "";
   }
-  const warnings = [...rendered.output.warnings, ...config.warnings];
-  if (!previous.fileHashes) {
-    warnings.push(
-      "legacy manifest has no file fingerprints: managed artifacts will be regenerated; backup preserves their previous contents"
-    );
+}
+function assertEngine(engine) {
+  if (!STOP_HOOK_ENGINES.includes(engine)) {
+    throw new Error(`unknown engine: ${engine} (expected one of ${STOP_HOOK_ENGINES.join(", ")})`);
   }
-  if (preserved.length) warnings.push(`preserved user-owned artifacts: ${preserved.join(", ")}`);
-  if (engines.includes("codex-cli"))
-    warnings.push("ensure .agents/ is ignored by Git (run harness check)");
-  return {
-    writes,
-    removals: existingRemovals,
-    result: {
-      version: VERSION,
-      fromManifestVersion: sourceVersion,
-      dryRun: args.dryRun === true,
-      upToDate: writes.length === 0 && existingRemovals.length === 0,
-      filesToWrite: writes.map((file) => file.path),
-      filesToRemove: existingRemovals,
-      warnings
-    }
-  };
+  return engine;
 }
-function updateCommand(args) {
-  const plan = planUpdate(args);
-  if (args.dryRun || plan.result.upToDate) return plan.result;
-  const { backupDir } = applyUpdateTransaction(
-    resolve7(args.targetDir),
-    plan.writes,
-    plan.removals,
-    args.backupDir
-  );
-  return { ...plan.result, backupDir };
+function stopHookCommand(args, stdin) {
+  const engine = assertEngine(args.engine);
+  const cwd = resolve8(args.cwd ?? ".");
+  const adapter = getAdapter(engine);
+  const payload = adapter.parseInput(stdin, process.env);
+  const decision = decide(payload, {
+    cwd,
+    env: process.env,
+    gitStatus: defaultGitStatus,
+    runLint: defaultRunLint
+  });
+  return adapter.respond(decision);
+}
+function stopHookCommandFromStdin(args) {
+  return stopHookCommand(args, readStdinSync());
 }
 
 // src/cli/index.ts
 function resolvePackageDir() {
-  const here = dirname8(fileURLToPath2(import.meta.url));
-  return resolve8(here, "..");
+  const here = dirname9(fileURLToPath2(import.meta.url));
+  return resolve9(here, "..");
+}
+function parseList(raw) {
+  if (raw === void 0) return void 0;
+  return raw.split(",").map((item) => item.trim()).filter(Boolean);
 }
 var program = new Command();
 program.name("vaubaan-harness").description(
@@ -2785,10 +2906,9 @@ program.command("init").description(
 ).option(
   "--no-stop-hook",
   "skip rendering the Stop-hook configs that run lint at end of each agent turn"
-).action((targetDir, opts) => {
+).option("--preserve <paths>", "comma-separated generated files to leave under user ownership").option("--backup-dir <dir>", "new backup directory outside the project").action((targetDir, opts) => {
   const packageDir = opts.packageDir ?? resolvePackageDir();
-  const enginesRaw = opts.engines;
-  const engines = enginesRaw ? enginesRaw.split(",").map((s) => s.trim()) : void 0;
+  const engines = parseList(opts.engines);
   const withMcpRaw = opts.withMcp;
   const mcpServers = withMcpRaw ? withMcpRaw.split(",").map((s) => s.trim()) : void 0;
   const result = initCommand({
@@ -2797,7 +2917,9 @@ program.command("init").description(
     overridesDir: opts.overridesDir,
     packageDir,
     mcpServers,
-    withStopHook: opts.stopHook !== false
+    withStopHook: opts.stopHook !== false,
+    preserveFiles: parseList(opts.preserve),
+    backupDir: opts.backupDir
   });
   process.stdout.write(`rendered ${result.filesWritten.length} files to ${targetDir}
 `);
@@ -2809,12 +2931,14 @@ program.command("init").description(
   }
   if (result.stopHookInstalled) {
     process.stdout.write("stop-hook installed (runs lint at end-of-turn)\n");
-    if (result.filesWritten.includes(".codex/hooks.json")) {
+    if (result.engines.includes("codex-cli")) {
       process.stdout.write(
         "codex: the hook runs once you trust this project and approve the hook (startup review or /hooks)\n"
       );
     }
   }
+  if (result.backupDir) process.stdout.write(`backup: ${result.backupDir}
+`);
   for (const w of result.warnings) process.stderr.write(`warning: ${w}
 `);
 });
@@ -2869,7 +2993,7 @@ program.command("lint").description("Run all mechanical linters and exit non-zer
   "--pillar <pillar>",
   "filter by pillar (spec, decisions, handbook, tests, workflow, quality)"
 ).option("--format <fmt>", "text | json", "text").option("--cwd <dir>", "repo root", ".").action((opts) => {
-  const repoRoot = resolve8(opts.cwd ?? ".");
+  const repoRoot = resolve9(opts.cwd ?? ".");
   const lintOpts = opts.pillar ? { pillar: opts.pillar } : {};
   const report = runLinters(repoRoot, lintOpts);
   if (opts.format === "json") {
@@ -2889,8 +3013,7 @@ program.command("render").description("Render harness for preview (no overrides
   "comma-separated MCP servers to render config for (context7) \u2014 opt-in"
 ).option("--no-stop-hook", "skip rendering the Stop-hook configs").action((opts) => {
   const packageDir = opts.packageDir ?? resolvePackageDir();
-  const enginesRaw = opts.engines;
-  const engines = enginesRaw ? enginesRaw.split(",").map((s) => s.trim()) : void 0;
+  const engines = parseList(opts.engines);
   const withMcpRaw = opts.withMcp;
   const mcpServers = withMcpRaw ? withMcpRaw.split(",").map((s) => s.trim()) : void 0;
   const result = renderCommand({