agent-harness-kit 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Solo-dev harness engineering kit for Claude Code. Layered architecture, structural tests, garbage-collection ritual, review subagents — without the enterprise overhead.",
   "type": "module",
   "bin": {
@@ -42,7 +42,7 @@
     "lint": "echo 'no-op (kit is plain ESM JS)'",
     "selftest": "node bin/cli.mjs --version",
     "harness:eval": "node src/templates/_adapter-typescript/harness/eval-runner.mjs",
-    "harness:check": "echo 'no-op (kit-level structural rules are TBD; see .harness/eval/tasks/03-add-structural-rule.json)'"
+    "harness:check": "node scripts/kit-structural-check.mjs"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",

package/src/core/render-templates.mjs

@@ -87,16 +87,15 @@ async function* walk(dir) {
 }
 
 function buildContext({ projectName, preset, layers, stack, kitVersion }) {
-  const installCmd =
-    stack.language === "python"
-      ? "pip install -e '.[dev]'"
-      : stack.packageManager === "pnpm"
-        ? "pnpm install"
-        : stack.packageManager === "yarn"
-          ? "yarn"
-          : stack.packageManager === "bun"
-            ? "bun install"
-            : "npm install";
+  const installCmd = (() => {
+    if (stack.language === "python") return "pip install -e '.[dev]'";
+    if (stack.language === "go") return "go mod download";
+    if (stack.language === "rust") return "cargo build";
+    if (stack.packageManager === "pnpm") return "pnpm install";
+    if (stack.packageManager === "yarn") return "yarn";
+    if (stack.packageManager === "bun") return "bun install";
+    return "npm install";
+  })();
   const devCmd = (() => {
     switch (stack.framework) {
       case "nextjs":  return "npm run dev";
@@ -107,18 +106,28 @@ function buildContext({ projectName, preset, layers, stack, kitVersion }) {
       case "django":  return "python manage.py runserver";
       case "flask":   return "flask --app app run --debug";
       default:
-        return stack.language === "python" ? "python -m app" : "npm run dev";
+        if (stack.language === "python") return "python -m app";
+        if (stack.language === "go") return "go run ./cmd/...";
+        if (stack.language === "rust") return "cargo run";
+        return "npm run dev";
     }
   })();
   const testCmd = (() => {
     switch (stack.framework) {
       case "django": return "python manage.py test";
       default:
-        return stack.language === "python" ? "pytest -x" : "npm test";
+        if (stack.language === "python") return "pytest -x";
+        if (stack.language === "go") return "go test ./...";
+        if (stack.language === "rust") return "cargo test";
+        return "npm test";
     }
   })();
-  const lintCmd =
-    stack.language === "python" ? "ruff check ." : "npm run lint";
+  const lintCmd = (() => {
+    if (stack.language === "python") return "ruff check .";
+    if (stack.language === "go") return "go vet ./...";
+    if (stack.language === "rust") return "cargo clippy --all-targets -- -D warnings";
+    return "npm run lint";
+  })();
 
   return {
     projectName,
@@ -137,6 +146,8 @@ function buildContext({ projectName, preset, layers, stack, kitVersion }) {
     kitVersion,
     isTypescript: stack.language === "typescript",
     isPython: stack.language === "python",
+    isGo: stack.language === "go",
+    isRust: stack.language === "rust",
     isNextjs: stack.framework === "nextjs",
     isFastapi: stack.framework === "fastapi",
     isExpress: stack.framework === "express",
@@ -152,11 +163,27 @@ function buildContext({ projectName, preset, layers, stack, kitVersion }) {
 // into the root.
 function pathForStack(rel, stack) {
   if (rel.startsWith("_adapter-typescript/")) {
-    return stack.language === "typescript" ? rel.slice("_adapter-typescript/".length) : null;
+    const stripped = rel.slice("_adapter-typescript/".length);
+    if (stack.language === "typescript") return stripped;
+    // eval-runner.mjs is language-agnostic — share with Go/Rust users who
+    // don't ship a native runner. Avoids duplicating ~322 lines per adapter.
+    if (
+      stripped === "harness/eval-runner.mjs" &&
+      (stack.language === "go" || stack.language === "rust")
+    ) {
+      return stripped;
+    }
+    return null;
   }
   if (rel.startsWith("_adapter-python/")) {
     return stack.language === "python" ? rel.slice("_adapter-python/".length) : null;
   }
+  if (rel.startsWith("_adapter-go/")) {
+    return stack.language === "go" ? rel.slice("_adapter-go/".length) : null;
+  }
+  if (rel.startsWith("_adapter-rust/")) {
+    return stack.language === "rust" ? rel.slice("_adapter-rust/".length) : null;
+  }
   if (rel.startsWith("_preset-nextjs/")) {
     return stack.framework === "nextjs" ? rel.slice("_preset-nextjs/".length) : null;
   }

package/src/templates/CLAUDE.md.hbs

@@ -10,7 +10,7 @@ an encyclopedia.
 - Dev:        `{{devCmd}}`
 - Test:       `{{testCmd}}`
 - Lint:       `{{lintCmd}}`
-- Structural: `{{#if isPython}}python -m harness.structural_test{{else}}npm run harness:check{{/if}}` (must pass before any PR)
+- Structural: `{{#if isPython}}python -m harness.structural_test{{else}}{{#if isGo}}go run harness/structural_check.go{{else}}{{#if isRust}}node harness/structural-check.mjs{{else}}npm run harness:check{{/if}}{{/if}}{{/if}}` (must pass before any PR)
 
 ## Architecture (brief)
 

package/src/templates/_adapter-go/harness/structural_check.go.hbs

@@ -0,0 +1,263 @@
+// harness/structural_test.go — forward-only layer enforcement for Go.
+//
+// Reads harness.config.json + go.mod. For each domain, parses every .go
+// file's imports (via go/parser stdlib) and asserts that no internal
+// import goes "backward" through the layer order.
+//
+// Layer assignment: a file's layer = first path segment after `<root>/`.
+// E.g. `internal/repo/store.go` belongs to the `repo` layer when
+// `domains[0].root == "internal"`.
+//
+// External imports (stdlib, third-party modules) are ignored — only
+// imports starting with `<module-path>/<root>/` are checked.
+//
+// Exit codes:
+//   0 — clean (or only baselined violations)
+//   2 — new violations found
+//
+// Run: go run harness/structural_test.go [--file <path>]
+
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"go/parser"
+	"go/token"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+type Domain struct {
+	Name   string   `json:"name"`
+	Root   string   `json:"root"`
+	Layers []string `json:"layers"`
+}
+
+type Config struct {
+	Domains []Domain `json:"domains"`
+}
+
+type Violation struct {
+	File   string
+	Line   int
+	From   string
+	To     string
+	Domain string
+	Key    string
+}
+
+func readModulePath(repoRoot string) (string, error) {
+	data, err := os.ReadFile(filepath.Join(repoRoot, "go.mod"))
+	if err != nil {
+		return "", err
+	}
+	re := regexp.MustCompile(`(?m)^module\s+(\S+)`)
+	m := re.FindStringSubmatch(string(data))
+	if len(m) < 2 {
+		return "", fmt.Errorf("module declaration not found in go.mod")
+	}
+	return m[1], nil
+}
+
+func readConfig(repoRoot string) (*Config, error) {
+	data, err := os.ReadFile(filepath.Join(repoRoot, "harness.config.json"))
+	if err != nil {
+		return nil, err
+	}
+	var c Config
+	if err := json.Unmarshal(data, &c); err != nil {
+		return nil, err
+	}
+	return &c, nil
+}
+
+func readBaseline(repoRoot string) map[string]bool {
+	out := map[string]bool{}
+	data, err := os.ReadFile(filepath.Join(repoRoot, ".harness/structural-baseline.json"))
+	if err != nil {
+		return out
+	}
+	var keys []string
+	if err := json.Unmarshal(data, &keys); err != nil {
+		return out
+	}
+	for _, k := range keys {
+		out[k] = true
+	}
+	return out
+}
+
+// Returns (layerName, domainPtr) or ("", nil) if file doesn't belong to any layer.
+func layerOf(relPath string, cfg *Config) (string, *Domain) {
+	for i := range cfg.Domains {
+		d := &cfg.Domains[i]
+		if !strings.HasPrefix(relPath, d.Root+string(os.PathSeparator)) &&
+			!strings.HasPrefix(relPath, d.Root+"/") {
+			continue
+		}
+		stripped := strings.TrimPrefix(relPath, d.Root+string(os.PathSeparator))
+		stripped = strings.TrimPrefix(stripped, d.Root+"/")
+		parts := strings.SplitN(stripped, "/", 2)
+		if len(parts) == 0 {
+			continue
+		}
+		first := parts[0]
+		for _, l := range d.Layers {
+			if l == first {
+				return l, d
+			}
+		}
+	}
+	return "", nil
+}
+
+// For an import path like "github.com/foo/bar/internal/repo/store",
+// returns ("repo", domainPtr) when domain.root == "internal" and
+// modulePath == "github.com/foo/bar". Returns ("", nil) for external imports.
+func importLayer(importPath, modulePath string, cfg *Config) (string, *Domain) {
+	prefix := modulePath + "/"
+	if !strings.HasPrefix(importPath, prefix) {
+		return "", nil
+	}
+	relPath := strings.TrimPrefix(importPath, prefix)
+	return layerOf(relPath, cfg)
+}
+
+func indexOf(slice []string, s string) int {
+	for i, v := range slice {
+		if v == s {
+			return i
+		}
+	}
+	return -1
+}
+
+func main() {
+	repoRoot, err := os.Getwd()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+
+	scopedFile := ""
+	for i, a := range os.Args {
+		if a == "--file" && i+1 < len(os.Args) {
+			scopedFile = os.Args[i+1]
+		}
+	}
+
+	cfg, err := readConfig(repoRoot)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "read harness.config.json:", err)
+		os.Exit(1)
+	}
+	modulePath, err := readModulePath(repoRoot)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "read go.mod:", err)
+		os.Exit(1)
+	}
+	baseline := readBaseline(repoRoot)
+	baselineExists := len(baseline) > 0 || fileExists(filepath.Join(repoRoot, ".harness/structural-baseline.json"))
+
+	violations := []Violation{}
+	fset := token.NewFileSet()
+	walkErr := filepath.Walk(repoRoot, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if info.IsDir() {
+			if info.Name() == "vendor" || info.Name() == ".git" || strings.HasPrefix(info.Name(), ".") {
+				if path == repoRoot {
+					return nil
+				}
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+			return nil
+		}
+		if scopedFile != "" {
+			abs, _ := filepath.Abs(scopedFile)
+			if path != abs && path != filepath.Join(repoRoot, scopedFile) {
+				return nil
+			}
+		}
+		relPath, _ := filepath.Rel(repoRoot, path)
+		srcLayer, srcDomain := layerOf(relPath, cfg)
+		if srcDomain == nil {
+			return nil
+		}
+		srcIdx := indexOf(srcDomain.Layers, srcLayer)
+
+		f, err := parser.ParseFile(fset, path, nil, parser.ImportsOnly)
+		if err != nil {
+			return nil
+		}
+		for _, imp := range f.Imports {
+			impPath := strings.Trim(imp.Path.Value, `"`)
+			tgtLayer, tgtDomain := importLayer(impPath, modulePath, cfg)
+			if tgtDomain == nil || tgtDomain.Name != srcDomain.Name {
+				continue
+			}
+			tgtIdx := indexOf(tgtDomain.Layers, tgtLayer)
+			if srcIdx < tgtIdx {
+				key := fmt.Sprintf("%s::%s", relPath, impPath)
+				if baseline[key] {
+					continue
+				}
+				violations = append(violations, Violation{
+					File:   relPath,
+					Line:   fset.Position(imp.Pos()).Line,
+					From:   srcLayer,
+					To:     tgtLayer,
+					Domain: srcDomain.Name,
+					Key:    key,
+				})
+			}
+		}
+		return nil
+	})
+	if walkErr != nil {
+		fmt.Fprintln(os.Stderr, "walk:", walkErr)
+		os.Exit(1)
+	}
+
+	// First-run baseline: write current violations + exit 0.
+	if !baselineExists && len(violations) > 0 {
+		_ = os.MkdirAll(filepath.Join(repoRoot, ".harness"), 0o755)
+		keys := make([]string, len(violations))
+		for i, v := range violations {
+			keys[i] = v.Key
+		}
+		sort.Strings(keys)
+		out, _ := json.MarshalIndent(keys, "", "  ")
+		_ = os.WriteFile(filepath.Join(repoRoot, ".harness/structural-baseline.json"), append(out, '\n'), 0o644)
+		fmt.Printf("✓ structural test: baselined %d existing violations (.harness/structural-baseline.json).\n", len(violations))
+		fmt.Println("  New violations introduced after this point will block. Existing ones can be fixed incrementally.")
+		os.Exit(0)
+	}
+
+	if len(violations) == 0 {
+		fmt.Println("✓ structural test passed")
+		os.Exit(0)
+	}
+
+	for _, v := range violations {
+		fmt.Fprintf(os.Stderr, "✖ %s:%d  layer=%s → %s  (must be forward-only)\n", v.File, v.Line, v.From, v.To)
+	}
+	fmt.Fprintf(os.Stderr, "\n%d new layer violation(s). Fix the import direction.\n", len(violations))
+	if len(cfg.Domains) > 0 {
+		fmt.Fprintf(os.Stderr, "Layer order for domain %q: %s\n", cfg.Domains[0].Name, strings.Join(cfg.Domains[0].Layers, " → "))
+	}
+	os.Exit(2)
+}
+
+func fileExists(p string) bool {
+	_, err := os.Stat(p)
+	return err == nil
+}

package/src/templates/_adapter-rust/harness/structural-check.mjs.hbs

@@ -0,0 +1,198 @@
+// harness/structural-check.mjs — forward-only layer enforcement for Rust.
+//
+// Reads harness.config.json. For each domain, walks every .rs file under
+// the domain root (excluding target/, .git/, vendor/) and asserts no
+// `use crate::<layer>::...` import goes "backward" through the layer order.
+//
+// Layer assignment: a file's layer = first path segment after `<root>/`.
+// E.g. `src/repo/store.rs` belongs to the `repo` layer when
+// `domains[0].root == "src"`.
+//
+// Why Node + regex (not a Cargo binary):
+//   - Avoids polluting the user's Cargo workspace with a check crate.
+//   - Node is already required to install the kit (npx).
+//   - Regex over `use crate::<X>` is sufficient — we never need full
+//     parse trees because the layer rule is a syntactic property.
+//   - `super::` and `self::` are scoped to the current module, which is
+//     by definition the same layer, so we ignore them.
+//
+// Exit codes:
+//   0 — clean (or only baselined violations; or first-run baseline write)
+//   2 — new violations found
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+} from "node:fs";
+import { join, relative, sep } from "node:path";
+
+const repoRoot = process.cwd();
+const SKIP_DIRS = new Set([
+  ".git",
+  "target",
+  "node_modules",
+  ".harness",
+  "vendor",
+]);
+
+function readConfig() {
+  const path = join(repoRoot, "harness.config.json");
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function readBaseline() {
+  const path = join(repoRoot, ".harness/structural-baseline.json");
+  if (!existsSync(path)) return { exists: false, set: new Set() };
+  try {
+    const arr = JSON.parse(readFileSync(path, "utf8"));
+    return { exists: true, set: new Set(Array.isArray(arr) ? arr : []) };
+  } catch {
+    return { exists: true, set: new Set() };
+  }
+}
+
+function* walkRustFiles(root) {
+  if (!existsSync(root)) return;
+  for (const ent of readdirSync(root, { withFileTypes: true })) {
+    if (SKIP_DIRS.has(ent.name) || ent.name.startsWith(".")) continue;
+    const full = join(root, ent.name);
+    if (ent.isDirectory()) {
+      yield* walkRustFiles(full);
+    } else if (ent.isFile() && ent.name.endsWith(".rs")) {
+      yield full;
+    }
+  }
+}
+
+// Returns { layer, domain } or null.
+function layerOf(relPath, cfg) {
+  for (const d of cfg.domains) {
+    const altPrefix = d.root + "/";
+    const sepPrefix = d.root + sep;
+    let stripped;
+    if (relPath.startsWith(altPrefix)) stripped = relPath.slice(altPrefix.length);
+    else if (relPath.startsWith(sepPrefix))
+      stripped = relPath.slice(sepPrefix.length);
+    else continue;
+    const first = stripped.split(/[\/\\]/)[0];
+    if (d.layers.includes(first)) return { layer: first, domain: d };
+  }
+  return null;
+}
+
+// Capture the first identifier after `use crate::` (or `pub use crate::`).
+const USE_CRATE_RE = /\b(?:pub\s+)?use\s+crate::([a-zA-Z_][a-zA-Z0-9_]*)/g;
+
+function parseUseCrate(line) {
+  return [...line.matchAll(USE_CRATE_RE)].map((m) => m[1]);
+}
+
+// Return only the code portion of a line — strip line comments (//) and
+// double-quoted string contents so the regex can't match `use crate::X`
+// inside text like `"use crate::service"` or `// use crate::service`.
+// Block comments and char literals (single quotes — also Rust lifetimes)
+// are not handled; collisions are rare and would only cause noise, not
+// missed real violations.
+function stripCommentsAndStrings(line) {
+  let result = "";
+  let inStr = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (inStr) {
+      if (c === "\\" && i + 1 < line.length) {
+        i++;
+        continue;
+      }
+      if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') {
+      inStr = true;
+      continue;
+    }
+    if (c === "/" && i + 1 < line.length && line[i + 1] === "/") break;
+    result += c;
+  }
+  return result;
+}
+
+function main() {
+  const cfg = readConfig();
+  const { exists: baselineExists, set: baselineSet } = readBaseline();
+  const violations = [];
+
+  for (const d of cfg.domains) {
+    const rootDir = join(repoRoot, d.root);
+    for (const file of walkRustFiles(rootDir)) {
+      const relPath = relative(repoRoot, file);
+      const src = layerOf(relPath, cfg);
+      if (!src) continue;
+      const srcIdx = src.domain.layers.indexOf(src.layer);
+
+      const content = readFileSync(file, "utf8");
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const codeOnly = stripCommentsAndStrings(lines[i]);
+        const targets = parseUseCrate(codeOnly);
+        for (const tgtLayer of targets) {
+          if (!src.domain.layers.includes(tgtLayer)) continue;
+          const tgtIdx = src.domain.layers.indexOf(tgtLayer);
+          if (srcIdx < tgtIdx) {
+            const key = `${relPath}::${tgtLayer}`;
+            if (baselineSet.has(key)) continue;
+            violations.push({
+              file: relPath,
+              line: i + 1,
+              from: src.layer,
+              to: tgtLayer,
+              domain: src.domain.name,
+              key,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // First-run baseline: no baseline file + violations → record + exit 0.
+  if (!baselineExists && violations.length > 0) {
+    mkdirSync(join(repoRoot, ".harness"), { recursive: true });
+    const keys = [...new Set(violations.map((v) => v.key))].sort();
+    writeFileSync(
+      join(repoRoot, ".harness/structural-baseline.json"),
+      JSON.stringify(keys, null, 2) + "\n",
+    );
+    console.log(
+      `✓ structural test: baselined ${keys.length} existing violation(s) (.harness/structural-baseline.json).`,
+    );
+    console.log(
+      "  New violations introduced after this point will block. Existing ones can be fixed incrementally.",
+    );
+    process.exit(0);
+  }
+
+  if (violations.length === 0) {
+    console.log("✓ structural test passed");
+    process.exit(0);
+  }
+
+  for (const v of violations) {
+    console.error(
+      `✖ ${v.file}:${v.line}  layer=${v.from} → ${v.to}  (must be forward-only)`,
+    );
+  }
+  console.error(
+    `\n${violations.length} new layer violation(s). Fix the import direction.`,
+  );
+  if (cfg.domains.length > 0) {
+    console.error(
+      `Layer order for domain "${cfg.domains[0].name}": ${cfg.domains[0].layers.join(" → ")}`,
+    );
+  }
+  process.exit(2);
+}
+
+main();

package/src/templates/harness.config.json.hbs

@@ -7,14 +7,14 @@
   "domains": [
     {
       "name": "default",
-      "root": "{{#if isPython}}app{{else}}src{{/if}}",
+      "root": "{{#if isPython}}app{{else}}{{#if isGo}}internal{{else}}src{{/if}}{{/if}}",
       "layers": [{{#each layers}}"{{this}}"{{#unless @last}}, {{/unless}}{{/each}}]
     }
   ],
   "providers": ["auth", "telemetry", "feature-flags"],
   "goldenPrinciples": "docs/golden-principles.md",
   "structuralTest": {
-    "engine": "{{#if isPython}}libcst{{else}}ts-morph{{/if}}",
+    "engine": "{{#if isPython}}libcst{{else}}{{#if isGo}}go-parser{{else}}{{#if isRust}}rust-regex{{else}}ts-morph{{/if}}{{/if}}{{/if}}",
     "configPath": ".harness/structural-test.config.json",
     "blockOnViolation": true
   },
@@ -32,6 +32,9 @@
     "path": "CLAUDE.md",
     "maxInstructions": 200
   },
+  "recovery": {
+    "headless": false
+  },
   "models": {
     "main": "claude-sonnet-4-6",
     "reviewers": "claude-sonnet-4-6",

package/src/templates/scripts/precompletion-checklist.sh.hbs

@@ -4,8 +4,10 @@
 # failure context (not just check names) via stderr and exit 2. On second
 # stop (stop_hook_active=true), exit 0 to allow real exit.
 #
-# Optional: set AHK_HEADLESS_RECOVER=1 to spawn `claude -p` in the background
-# for one turn of recovery (costs tokens; off by default).
+# Optional headless recovery: when enabled, spawn `claude -p` in the background
+# for one turn of recovery on failure. Costs tokens; off by default. Configure
+# via harness.config.json `.recovery.headless` (persistent), or override per-run
+# with AHK_HEADLESS_RECOVER=1 (env var wins).
 set -e
 
 INPUT=$(cat)
@@ -163,12 +165,28 @@ fi
   echo "the task complete. Do NOT disable a check to make the hook pass."
 } >&2
 
-# Optional: opt-in headless recovery. Spawns a one-turn `claude -p` to
-# attempt the fix autonomously. Useful for unattended CI / cron contexts.
-# Off by default because it costs tokens.
-if [ "${AHK_HEADLESS_RECOVER:-}" = "1" ] && command -v claude >/dev/null 2>&1; then
+# Opt-in headless recovery. Spawns a one-turn `claude -p` to attempt the fix
+# autonomously. Useful for unattended CI / cron contexts. Off by default
+# because it costs tokens.
+#
+# Resolution order (first wins):
+#   1. AHK_HEADLESS_RECOVER=1   (env-var override, per-run)
+#   2. harness.config.json `.recovery.headless: true`   (persistent)
+HEADLESS_RECOVER=0
+HEADLESS_SOURCE=""
+if [ "${AHK_HEADLESS_RECOVER:-}" = "1" ]; then
+  HEADLESS_RECOVER=1
+  HEADLESS_SOURCE="AHK_HEADLESS_RECOVER"
+elif [ -f harness.config.json ] && command -v jq >/dev/null 2>&1; then
+  CFG_VAL=$(jq -r '.recovery.headless // false' harness.config.json 2>/dev/null)
+  if [ "$CFG_VAL" = "true" ]; then
+    HEADLESS_RECOVER=1
+    HEADLESS_SOURCE="harness.config.json:.recovery.headless"
+  fi
+fi
+if [ "$HEADLESS_RECOVER" = "1" ] && command -v claude >/dev/null 2>&1; then
   FAILED_LIST=$(tr '\n' ' ' < "$TMPDIR_HOOK/failed.list")
-  echo "[ahk] AHK_HEADLESS_RECOVER=1 — spawning recovery turn for: $FAILED_LIST" >&2
+  echo "[ahk] headless recovery enabled ($HEADLESS_SOURCE) — spawning recovery turn for: $FAILED_LIST" >&2
   claude -p \
     "The pre-completion checklist failed: $FAILED_LIST. Read the failure output in $TMPDIR_HOOK and apply the smallest fix. Do not disable any check." \
     --max-turns 5 \