@cardor/agent-harness-kit 1.11.0 → 2.1.0

package/README.md

@@ -88,8 +88,10 @@ ahk init
   └── creates config, agent definitions, task backlog, health check
 
 AI tool opens your project
-  └── reads .claude/mcp.json, opencode.json, or .codex/config.toml
-  └── spawns: npx ahk serve (stdio MCP server)
+  └── reads .claude/mcp.json, opencode.json, .codex/config.toml, or .grok/config.toml
+  └── spawns: ahk serve (stdio MCP server)
+      via your package manager (npx/pnpm exec/yarn run/bunx) when the
+      package is a local dependency, or the bare binary when it isn't
 
 Agent starts working
   └── tasks.get()         → picks a task from the backlog
@@ -109,7 +111,9 @@ Everything is stored locally in a SQLite database (`.harness/harness.db`). No cl
 
 ## Features
 
-- **Provider-agnostic** — works with Claude Code, OpenCode, Codex CLI, or any MCP-compatible AI tool. Switch providers without losing your task history or reconfiguring your workflow.
+- **Provider-agnostic** — works with Claude Code, OpenCode, Codex CLI, Grok Build, or any MCP-compatible AI tool. Switch providers without losing your task history or reconfiguring your workflow.
+
+> **Note:** "Grok Build" here refers to xAI's official Grok Build CLI (`provider: 'grok-cli'`) — it is unrelated to the unofficial, community-maintained `grok-cli`/`grok-dev` npm packages.
 - **Structured 5-agent workflow** — Lead, Explorer, Consultant, Builder, and Reviewer each have defined responsibilities and can only act within their role.
 - **Atomic task claiming** — agents use `tasks.claim()` which uses a SQLite transaction to prevent two agents from picking up the same task at the same time.
 - **Full audit trail** — every action, file touched, tool used, and section written is stored in SQLite and queryable.
@@ -117,7 +121,7 @@ Everything is stored locally in a SQLite database (`.harness/harness.db`). No cl
 - **Markdown fallback** — `current.md` is always regenerated so agents can understand the session state even without the MCP server.
 - **Docs search** — agents can call `docs.search(query)` to find relevant content in your project's docs folder before writing code.
 - **Multi-database support** — SQLite by default (uses `better-sqlite3` on Node ≥ 22 or `bun:sqlite` on Bun). Switch to PostgreSQL or MySQL with a single config line — same schema, same MCP tools, same workflow.
-- **Incremental scaffold** — `ahk init` preserves files you've already customized (agent definitions you've edited are kept). `ahk build` does too: it creates missing agent files and never touches existing ones. Use `ahk build --force` to regenerate them from the latest templates, discarding your edits (a backup is written first).
+- **Incremental scaffold** — `ahk init` preserves files you've already customized (agent definitions you've edited are kept). A hand-written `.harness/feature_list.json` backlog is **merged, never overwritten** — existing tasks survive and any first task you add during init is folded in (deduplicated by slug). `ahk build` also creates missing agent files and never touches existing ones. Use `ahk build --force` to regenerate them from the latest templates, discarding your edits (a backup is written first).
 - **Global installation** — `ahk init` can scaffold the harness into your home directory (`~/.claude` or `~/.config/opencode`) to share it across all projects.
 - **Input validation** — CLI prompts validate all inputs (name length, path format, task title, etc.) and retry with the error message instead of silently accepting bad values.
 
@@ -162,7 +166,7 @@ npx ahk init
 
 ## MCP command per package manager
 
-`ahk init` and `ahk build` detect which package manager your project uses and generate the MCP server launch command (`.mcp.json`, `opencode.json`, or `.codex/config.toml`) accordingly, instead of hardcoding `npx`:
+`ahk init` and `ahk build` detect which package manager your project uses and generate the MCP server launch command (`.mcp.json`, `opencode.json`, `.codex/config.toml`, or `.grok/config.toml`) accordingly, instead of hardcoding `npx`:
 
 | Package manager           | Detected via                                                              | Generated command                             |
 | -------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------- |
@@ -171,10 +175,15 @@ npx ahk init
 | yarn classic (v1)          | `packageManager` field (major 1) or `yarn.lock` without `.yarnrc.yml`       | `yarn run ahk serve --port <port>`             |
 | yarn berry (v2+, PnP or node-modules) | `packageManager` field (major ≥ 2) or `yarn.lock` + `.yarnrc.yml` | `yarn run ahk serve --port <port>`             |
 | bun                        | `packageManager` field or `bun.lockb`/`bun.lock`                            | `bunx --no-install ahk serve --port <port>`    |
+| **any — no local install** | `@cardor/agent-harness-kit` is not a dependency of your project             | `ahk serve --port <port>`                      |
 
 Detection order: the `packageManager` field in your `package.json` (e.g. `"packageManager": "pnpm@8.15.0"`) takes priority when present; otherwise `ahk` falls back to lockfile heuristics; if nothing is detected, it defaults to npm.
 
-**Existing projects:** if you initialized your project before this change, your `.mcp.json`/`opencode.json`/`.codex/config.toml` may still have a hardcoded `npx` command. No migration step is needed — `ahk build` always regenerates (merges) these files from scratch on every run, so the command self-corrects the next time you run `ahk build` (or `ahk build --sync`), including if you've since switched package managers.
+**Global installs bypass the package manager entirely.** Every command in the table above asks your package manager to resolve a *locally installed* `ahk` binary — `npx --no` deliberately refuses to download one, and `pnpm exec`/`yarn run`/`bunx --no-install` have nothing to point at. If you installed the CLI globally and never added it to the project, all five of those commands fail. So `ahk` checks for the local install first (the same check that decides your config file format, above) and, when there is none, generates the bare `ahk serve --port <port>` — resolved from your `PATH` like any other global binary. The package-manager-specific commands are used only when a local install actually exists. If, on that global-install path, `ahk` is not resolvable on your `PATH` at generation time, `ahk` prints a non-blocking warning (the command still succeeds) pointing you at `npm i -g @cardor/agent-harness-kit` or a local install — moving the "binary not found" failure earlier instead of surfacing it later when the MCP server is spawned.
+
+Working inside the `agent-harness-kit` repository itself counts as a local install: the package manager can resolve the workspace binary, so the `pnpm exec` form is generated rather than the bare one.
+
+**Existing projects:** if you initialized your project before this change, your `.mcp.json`/`opencode.json`/`.codex/config.toml`/`.grok/config.toml` may still have a hardcoded `npx` command. No migration step is needed — `ahk build` always regenerates (merges) these files from scratch on every run, so the command self-corrects the next time you run `ahk build` (or `ahk build --sync`), including if you've since switched package managers.
 
 ---
 
@@ -184,10 +193,9 @@ Detection order: the `packageManager` field in your `package.json` (e.g. `"packa
 
 Interactive scaffold. Asks for your project name, description, AI provider, docs path, storage scope, task adapter, and an optional first task. Creates all harness files in the current directory.
 
-For Claude Code and Codex CLI (not OpenCode), you'll also be asked whether to personalize the model per agent (lead/explorer/consultant/builder/reviewer):
+Claude Code only, init asks you to pick a model for each of the 5 core roles (lead, explorer, consultant, builder, reviewer) one at a time: `inherit` (default), `haiku`, `sonnet`, `opus`, or `fable`. Each choice is written straight into that role's generated `.claude/agents/<role>.md` frontmatter as a `model:` line at scaffold time — it is never persisted to the config file. Picking `inherit` (the default) emits no `model:` line at all, leaving Claude Code to apply its own default. This prompt only runs during `ahk init`'s one-time scaffold, not on `ahk build` — agent files are user-owned once generated (see [Agent files are yours](#agent-files-are-yours) below), so after init the model is changed the same way as any other edit: hand-editing the `model:` frontmatter line directly.
 
-- Claude Code: pick from `inherit` (default), `haiku`, `sonnet`, `opus`, `fable` per agent.
-- Codex CLI: free-text model name per agent — Codex does not validate this value; leaving it blank or under 3 characters means no override is written to that agent's TOML file.
+OpenCode, Codex CLI, and Grok Build are unaffected by this prompt — it never appears for those providers. OpenCode and Grok Build have no closed model enum to prompt against, and Codex's model is still set by hand-editing `model = "..."` in its TOML.
 
 **Storage scope** — where the harness DB (and its `current.md` fallback) physically lives:
 
@@ -204,6 +212,7 @@ ahk init
 # Skip prompts with flags
 ahk init --name "my-app" --provider claude-code --docs ./docs --tasks local --storage-scope local
 ahk init --name "my-app" --provider codex-cli   --docs ./docs --tasks local --storage-scope global
+ahk init --name "my-app" --provider grok-cli    --docs ./docs --tasks local --storage-scope local
 ```
 
 Run this once per project. If the project is already initialized, the command prints an 'already initialized' message with suggested next-step commands (`ahk build`, `ahk build --sync`, `ahk reset`, `ahk serve`) and exits without overwriting anything.
@@ -225,9 +234,25 @@ ahk build --sync     # kept for backwards compatibility — now a no-op on every
 
 ### Agent files are yours
 
-`ahk build` **creates agent files that are missing and never modifies ones that already exist.** Edit `.claude/agents/<role>.md` (or `.opencode/agents/<role>.md`, or `.codex/agents/<role>.toml`) freely — change the role prompt, set a `model:` line, adjust the restriction fields. Rebuilding will not revert your work. `ahk doctor` does not report hand-edited files either; it checks existence only.
+`ahk build` **creates agent files that are missing and never modifies ones that already exist.** Edit `.claude/agents/<role>.md` (or `.opencode/agents/<role>.md`, `.codex/agents/<role>.toml`, or `.grok/agents/<role>.md`) freely — change the role prompt, set a `model:` line, adjust the restriction fields. Rebuilding will not revert your work. `ahk doctor` does not report hand-edited files either; it checks existence only.
+
+Everything else `build` writes — MCP config and skills — is derived from your config and **is** regenerated on every run.
+
+### `AGENTS.md` and `CLAUDE.md` — derived, but your edits are safe
+
+`AGENTS.md` (all providers) and `CLAUDE.md` (Claude Code only) are generated from your config, so a config change should flow into them — but they are also files people hand-edit. `build` reconciles both concerns with a **provenance marker**: every generated file ends with a comment holding a checksum of the exact bytes we wrote, e.g.
 
-Everything else `build` writes — `AGENTS.md`, `CLAUDE.md`, MCP config, skills — is derived from your config and **is** regenerated on every run.
+```
+<!-- ahk:generated 3f7a…c1 -->
+```
+
+On each build the marker lets `build` tell its own untouched output apart from a human edit, byte-for-byte:
+
+- **Untouched since we wrote it, config changed** → the file is regenerated so your config propagates. No prompt, no backup — it was provably our own output.
+- **Already up to date** → no-op.
+- **You edited the body** (the checksum no longer matches) **or the file has no marker** (written by an older version, e.g. a `CLAUDE.md` you customized before upgrading) → **left untouched**, and `build` prints a loud notice naming the file and telling you to run `--force` if you actually want it regenerated.
+
+Because the checksum is over the exact bytes, *any* change — even one space — counts as an edit and is preserved. The behavior is identical with or without a terminal (there is no prompt), so it is safe in scripts and CI. Leave the marker comment in place; deleting it just makes `build` treat the file as hand-edited (preserve it) on the next run.
 
 > **If you use OpenCode or Codex CLI, your agent files may be out of date right now.** Those two providers have always preserved existing agent files on build, which means they have never picked up template improvements shipped in newer versions of this package. Claude Code, by contrast, used to overwrite them on every build — that inconsistency was a bug, and it is now fixed in favour of preserving your edits. To pull in the current templates, run `ahk build --force` (read the warning below first).
 
@@ -240,9 +265,11 @@ ahk build --force
 ```
 
 - **It discards your customizations.** Every agent file is rewritten from the template. Prompt edits, `model:` lines, and restriction tweaks are all lost.
-- **It backs up first.** Before overwriting anything, the current content of every affected file is copied to `.harness/backups/agents-<timestamp>/`. If that backup cannot be written, the command aborts and **no file is modified** — the same fail-safe as [`ahk migrate storage --force`](#storage-migration).
+- **It backs up first.** Before overwriting anything, the current content of every affected file is copied under `.harness/backups/` — agent files to `agents-<timestamp>/`, hand-edited `AGENTS.md`/`CLAUDE.md` to `derived-<timestamp>/`. If that backup cannot be written, the command aborts and **no file is modified** — the same fail-safe as [`ahk migrate storage --force`](#storage-migration).
 - **It names what it touched.** The command prints every file it overwrote and the backup location, so you can diff or restore.
 
+`--force` also regenerates a hand-edited `AGENTS.md` or `CLAUDE.md` (backing it up first) — the only time you need it for those files, since an *unedited* one already re-generates on its own when config changes.
+
 `--watch` never forces, even if you pass both flags: an automatic rebuild triggered by a file change must not destroy your edits in the background.
 
 `--sync` used to rewrite the `tools:` frontmatter of agent files so it matched a canonical allowlist. Agent files no longer declare an allowlist at all — they inherit every tool and declare only restrictions — so there is nothing left to synchronise. Use `ahk build --force` to regenerate agent files.
@@ -259,7 +286,11 @@ ahk dashboard --port 8080      # custom port
 ahk dashboard --no-open        # start server without opening browser
 ```
 
-If the requested port (default `4242`) is already in use, `ahk dashboard` automatically tries up to 10 sequential ports (e.g. `4242 → 4243 → … → 4251`). The actual port opened is printed to the console. If all 10 ports are exhausted, the command exits with a clear error message showing which port range was attempted.
+`--port` must be an integer between `1` and `65535`; an invalid value (e.g. `ahk dashboard --port abc` or `--port 99999`) is rejected at the CLI with a clear error naming the flag and the valid range, rather than silently failing.
+
+If the requested port (default `4242`) is already in use, `ahk dashboard` automatically tries up to 10 sequential ports (e.g. `4242 → 4243 → … → 4251`), printing `Port 4242 in use, using 4243`. The actual port opened is printed to the console. If all 10 ports are exhausted, the command exits with a clear error message showing which port range was attempted.
+
+Port availability is checked against the same network interface the dashboard actually binds to, so an already-running `ahk dashboard` — or any other server holding that port — is reliably detected. The success banner is printed only after the server has genuinely bound; if the bind fails (for example, the port was claimed by another process in the moment between the check and the bind), the command reports an actionable error instead of crashing.
 
 The dashboard includes:
 
@@ -338,6 +369,8 @@ ahk serve
 ahk serve --port 3456    # store a port hint in config (stdio transport only)
 ```
 
+`--port` must be an integer between `1` and `65535`; an invalid value is rejected at the CLI with a clear error.
+
 ---
 
 ### `ahk task add`
@@ -386,13 +419,14 @@ ahk reset --force                  # skip all confirmation prompts
 ahk reset --provider claude-code   # also delete agent files for this provider
 ahk reset --provider opencode
 ahk reset --provider codex-cli
+ahk reset --provider grok-cli
 ```
 
 What it can reset:
 
 - The SQLite `.db` file (plus WAL and SHM files if present)
 - `.harness/feature_list.json`
-- Agent definition files in `.claude/agents/`, `.opencode/agents/`, or `.codex/agents/`
+- Agent definition files in `.claude/agents/`, `.opencode/agents/`, `.codex/agents/`, or `.grok/agents/`
 
 After a reset, run `ahk init` to scaffold a fresh harness.
 
@@ -410,6 +444,7 @@ Migrates provider-specific files from one AI provider to another. Useful when sw
 ahk migrate provider --to opencode
 ahk migrate provider --to claude-code
 ahk migrate provider --to codex-cli
+ahk migrate provider --to grok-cli
 
 # Backward-compatible alias (identical behavior):
 ahk migrate --to opencode
@@ -517,6 +552,23 @@ your-project/
         └── default.toml           ← overrides Codex's built-in default agent → routes to lead
 ```
 
+**Grok Build** (`provider: 'grok-cli'`):
+
+```
+your-project/
+├── agent-harness-kit.config.{json|ts|mjs|cjs}
+├── AGENTS.md
+├── health.sh
+├── .harness/
+└── .grok/
+    ├── config.toml                ← MCP server registration
+    └── agents/
+        ├── lead.md
+        ├── explorer.md
+        ├── builder.md
+        └── reviewer.md
+```
+
 ### What each file does
 
 | File                          | Purpose                                                                               | Edit it?                                                    |
@@ -535,6 +587,8 @@ your-project/
 | `opencode.json`               | MCP server + `default_agent` + compaction config for OpenCode. Merged by `ahk build`  | Yes, carefully                                              |
 | `.codex/agents/*.toml`        | Agent role definitions (Codex CLI). Created once, never overwritten (`ahk build --force` regenerates)                   | **Yes — customize agent behavior**                          |
 | `.codex/config.toml`          | MCP server registration for Codex CLI. Merged by `ahk build`                          | Yes, carefully                                              |
+| `.grok/agents/*.md`           | Agent role definitions (Grok Build). Created once, never overwritten (`ahk build --force` regenerates)                  | **Yes — customize agent behavior**                          |
+| `.grok/config.toml`           | MCP server registration for Grok Build. Merged by `ahk build`                         | Yes, carefully                                              |
 
 ---
 
@@ -560,7 +614,7 @@ const config: HarnessConfig = {
     docsPath: './docs', // where agents search for documentation
   },
 
-  provider: 'claude-code', // 'claude-code' | 'opencode' | 'codex-cli'
+  provider: 'claude-code', // 'claude-code' | 'opencode' | 'codex-cli' | 'grok-cli'
 
   // There is no `agents` key. Per-agent settings live in the generated agent
   // file itself, which is yours to edit — see "Agent files are yours" below.
@@ -758,12 +812,42 @@ You are the builder agent for MyApp. Follow these rules:
 
 Codex CLI has no per-agent tool denylist, so `sandbox_mode` is the only real mechanism: `"read-only"` for lead, explorer, consultant, and reviewer; `"workspace-write"` for builder. Because Codex keeps the write tools *visible* to the model even under a read-only sandbox, the restriction is additionally restated in prose inside `developer_instructions` — without it the model burns turns on calls the sandbox will reject.
 
-The equivalent constraint under Claude Code is expressed as `disallowedTools: [Write, Edit]`, and under OpenCode as `permission: { edit: deny }`.
+**Grok Build** (`.grok/agents/*.md`) uses markdown + YAML frontmatter, like Claude Code and OpenCode — but its `tools:` field is an **allowlist**, the inverse shape of Claude's `disallowedTools`. A restricted role must enumerate every tool it IS allowed to use, since there is no way to say "everything except Write/Edit":
+
+```markdown
+---
+name: explorer
+description: Explorer agent — reads and maps the codebase, never writes
+tools:
+  - Bash
+  - Read
+  - NotebookRead
+  - Grep
+  - Glob
+  - WebFetch
+  - WebSearch
+  - search_tool
+  - use_tool
+---
+
+# Explorer Agent
+
+You are the explorer agent for MyApp. Follow these rules:
+
+- Map the modules relevant to the task and report where each concern lives
+- Never modify files — record every file you read
+```
+
+For the builder, `tools:` is omitted entirely, same as every other provider — the agent inherits every tool.
+
+The equivalent constraint under Claude Code is expressed as `disallowedTools: [Write, Edit]`, under OpenCode as `permission: { edit: deny }`, and under Grok Build as the `tools:` allowlist shown above.
 
 ### `.harness/feature_list.json`
 
 The human-editable task backlog. Add tasks here, then run `ahk sync` to load them into SQLite.
 
+`ahk init` **never clobbers** this file: an existing backlog is merged into SQLite (deduplicated by slug) alongside any first task you add during init, then re-emitted — so a hand-written backlog is preserved. On a fresh project the file is created (empty `[]` if you skip the first-task prompt). If the file contains invalid JSON, init leaves it untouched and warns you to fix it and run `ahk sync`.
+
 ```json
 [
   {
@@ -799,8 +883,8 @@ The harness exposes these tools via MCP. Agents use them instead of reading file
 | `actions.write`           | `actionId, sectionType, content`                | Record a text section: `result \| tools_used \| blockers \| next_steps`. Does **not** populate the Files dashboard — use `actions.record_file` for that                             |
 | `actions.complete`        | `actionId, summary`                             | Close an action with a one-line summary                                                                                                                                             |
 | `actions.get`             | `taskId`                                        | Full action history for a task (all agents, all sections)                                                                                                                           |
-| `actions.record_file`     | `actionId, filePath, operation, notes?`         | Register a file touch. The **only** way to populate the Files dashboard. `operation`: `read \| created \| modified \| deleted`                                                      |
-| `actions.record_tool`     | `actionId, toolName, argsJson?, resultSummary?` | Register a tool call. The **only** way to populate the Tools dashboard                                                                                                              |
+| `actions.record_file`     | `actionId, files: [{ filePath, operation, notes? }, ...]` | Batch-register one or more file touches, atomically. The **only** way to populate the Files dashboard. `operation`: `read \| created \| modified \| deleted`. Batch-only — `files` requires at least one entry; a single touch is still a one-element array                             |
+| `actions.record_tool`     | `actionId, calls: [{ toolName, argsJson?, resultSummary? }, ...]` | Batch-register one or more tool calls, atomically. The **only** way to populate the Tools dashboard. Batch-only — `calls` requires at least one entry; a single call is still a one-element array                                                              |
 | `docs.search`             | `query`                                         | Search the `docsPath` folder for content matching the query                                                                                                                         |
 | `tasks.acceptance_get`    | `taskId`                                        | Returns all acceptance criteria for a task with their `id`, `task_id`, `criterion` text, and `met` status. Use the returned `id` values with `tasks.acceptance.update`              |
 | `deps.snapshot`           | _(none)_                                        | Snapshot current `package.json` dependencies to `.harness/deps-lock.json`                                                                                                           |
@@ -819,7 +903,7 @@ The harness exposes these tools via MCP. Agents use them instead of reading file
 | **builder**    | Implements the plan. The only role that writes — its write tools are enabled where every other role's are disabled. Records every file modified. |
 | **reviewer**   | Verifies all acceptance criteria are met. Approves or blocks. Runs health check before approving.                                           |
 
-> **Scope note.** What a role may not do is enforced **per tool, not per path**. There is no per-agent path scoping and it is not configurable: the `allowedPaths` / `writablePaths` fields were removed because they were only interpolated into prompt text and no provider ever enforced them — they looked like a security control without being one. The real restriction lives in `src/core/materializer/agent-restrictions.ts`, which each provider translates natively: `disallowedTools` in Claude Code, `permission.edit` in OpenCode, `sandbox_mode` in Codex CLI. If a config still declares the removed fields they are stripped at load time with a warning.
+> **Scope note.** What a role may not do is enforced **per tool, not per path**. There is no per-agent path scoping and it is not configurable: the `allowedPaths` / `writablePaths` fields were removed because they were only interpolated into prompt text and no provider ever enforced them — they looked like a security control without being one. The real restriction lives in `src/core/materializer/agent-restrictions.ts`, which each provider translates natively: `disallowedTools` in Claude Code, `permission.edit` in OpenCode, `sandbox_mode` in Codex CLI, and a `tools:` allowlist in Grok Build. If a config still declares the removed fields they are stripped at load time with a warning.
 >
 > **The entire `agents` config key has since been removed too**, for the same underlying reason: everything left in it was either dead or better expressed elsewhere. `instructionsPath`, `context` and `custom` were written by the generator and never read by anything; `model` was the only field with an effect, and it now belongs in the agent file's frontmatter alongside the role prompt, since that file is user-owned. A config that still declares `agents` loads normally — the key is ignored, with one aggregated warning pointing at the agent file.
 >
@@ -871,6 +955,8 @@ The harness exposes these tools via MCP. Agents use them instead of reading file
 | `opencode.json`               | Yes                 |
 | `.codex/agents/*.toml`        | Yes                 |
 | `.codex/config.toml`          | Yes                 |
+| `.grok/agents/*.md`           | Yes                 |
+| `.grok/config.toml`           | Yes                 |
 | `.harness/harness.db`         | **No** (gitignored, local scope only) |
 | `.harness/current.md`         | **No** (gitignored, local scope only) |
 | `.harness/storage-state.json` | Yes (metadata, not gitignored — always present regardless of scope) |
@@ -978,6 +1064,7 @@ See [SECURITY.md](./SECURITY.md) for the vulnerability reporting process, suppor
 - ✅ **Global installation** — `ahk init` can install the harness to your home directory, shared across projects.
 - ✅ **Input validation** — all CLI prompts validate and retry on bad values.
 - ✅ **Codex CLI provider** — full support for OpenAI Codex CLI. Generates `.codex/agents/*.toml` files with proper `sandbox_mode` per role and merges `.codex/config.toml` for MCP registration. Overrides the built-in `default` agent so the harness lead runs by default.
+- ✅ **Grok Build provider** — full support for xAI's Grok Build. Generates `.grok/agents/*.md` files with a `tools:` allowlist per role and merges `.grok/config.toml` for MCP registration.
 - **Graphify integration** — connect the harness to Graphify to visualize agent workflows, task dependencies, and action timelines as interactive graphs.
 - **Open Telemetry integration** — emit OpenTelemetry spans for all agent actions, file operations, and tool calls.
 - **Jira task adapter** — pull tasks directly from Jira instead of maintaining `feature_list.json` manually.

package/dist/agent-templates/builder.md

@@ -32,36 +32,42 @@ a blocker and stop.
 
 ## !! MANDATORY TRACKING — DO THIS FOR EVERY ACTION, NO EXCEPTIONS !!
 
-These three calls are **not optional**. The dashboard cannot display what you do not report. Missing any of them is a failure of your role.
+These calls are **not optional**. The dashboard cannot display what you do not report. Missing them is a failure of your role.
+
+Both `actions.record_tool` and `actions.record_file` are **batch-only** — each takes an array of entries, never a single bespoke call. Accumulate as you work and flush periodically (every few tool calls, or at a natural checkpoint/phase boundary) rather than round-tripping once per individual tool use. Even a single entry must still go through the array shape — a one-element array, never a bespoke single-call form, since that form no longer exists.
 
 ### 1. Log every tool call you make
 
-After **each** tool invocation (Read, Edit, Write, Bash), call **both**:
+Accumulate each tool invocation (Read, Edit, Write, Bash) as you go, then flush with:
 
 ```
-actions.record_tool(actionId, '<ToolName>', '<args-summary>', '<why>')
+actions.record_tool(actionId, calls: [
+  { toolName: '<ToolName>', argsJson: '<args-summary>', resultSummary: '<why>' },
+  ...
+])
 ```
 
-Examples:
-- `actions.record_tool(actionId, 'Read', 'src/auth/middleware.ts', 'understand existing JWT pattern')`
-- `actions.record_tool(actionId, 'Bash', 'npm test --testPathPattern=auth', 'verify auth tests pass')`
-- `actions.record_tool(actionId, 'Edit', 'src/auth/middleware.ts:45-78', 'add refresh token validation')`
+Example flush after a few calls:
+- `actions.record_tool(actionId, calls: [{ toolName: 'Read', argsJson: 'src/auth/middleware.ts', resultSummary: 'understand existing JWT pattern' }, { toolName: 'Edit', argsJson: 'src/auth/middleware.ts:45-78', resultSummary: 'add refresh token validation' }, { toolName: 'Bash', argsJson: 'npm test --testPathPattern=auth', resultSummary: 'verify auth tests pass' }])`
 
 ### 2. Log every file you touch
 
-After **each** file modification (Edit, Write), call:
+Accumulate each file modification (Edit, Write) as you go, then flush with:
 
 ```
-actions.record_file(actionId, '<file-path>', '<operation>', '<what changed and why>')
+actions.record_file(actionId, files: [
+  { filePath: '<file-path>', operation: '<operation>', notes: '<what changed and why>' },
+  ...
+])
 ```
 
 Operations: `created` | `modified` | `deleted`
 
-Example: `actions.record_file(actionId, 'src/auth/middleware.ts', 'modified', 'added refresh token expiry check in validateToken()')`
+Example: `actions.record_file(actionId, files: [{ filePath: 'src/auth/middleware.ts', operation: 'modified', notes: 'added refresh token expiry check in validateToken()' }])`
 
 ### 3. Do not complete your action without both logs being up to date
 
-If you touched 5 files and made 12 tool calls, there must be 5 `actions.record_file` calls and 12 `actions.record_tool` calls before you call `actions.complete`.
+If you touched 5 files and made 12 tool calls across the session, every one of those must appear as an entry inside some `actions.record_file`/`actions.record_tool` batch call before you call `actions.complete` — it doesn't need to be 5 and 12 separate MCP round-trips, but the union of all your batched arrays must account for all 5 files and all 12 tool calls.
 
 ---
 
@@ -83,7 +89,7 @@ actions.start(taskId, 'builder')   → save the returned actionId
 
 ### 3. Implement in small, verifiable steps
 
-Work through the plan item by item. Log each tool call and each file touched as described in the **MANDATORY TRACKING** section above — do it as you go, not at the end.
+Work through the plan item by item. Accumulate each tool call and each file touched as described in the **MANDATORY TRACKING** section above, and flush in batches as you go — do not wait until the very end of the session to record everything at once.
 
 ### 4. Follow existing patterns
 
@@ -167,8 +173,8 @@ Before writing a commit message, detect whether the repo already enforces a comm
 
 - **Read the plan and analysis first.** Never implement cold.
 - **Stay inside the project.** Never write outside the project root.
-- **Log every file you touch.** Call `actions.record_file(actionId, path, operation, notes)` after each Edit/Write.
-- **Log every tool call.** Call `actions.record_tool(actionId, toolName, args, summary)` after each Read, Edit, Write, Bash invocation.
+- **Log every file you touch.** Accumulate entries and flush via `actions.record_file(actionId, files: [...])` periodically as you Edit/Write — batch-only, even one file goes through as a one-element array.
+- **Log every tool call.** Accumulate entries and flush via `actions.record_tool(actionId, calls: [...])` periodically as you Read, Edit, Write, Bash — batch-only, even one call goes through as a one-element array.
 - **Leave tests green.** If tests fail after your changes, fix them before completing.
 - **Do not refactor beyond the task scope.** Implement what was asked, nothing more.
 - **If blocked, say so.** Do not invent workarounds for unclear requirements.

package/dist/agent-templates/explorer.md

@@ -34,18 +34,21 @@ These calls are **not optional**. The dashboard cannot display what you do not r
 
 ### Log every tool call you make
 
-After **each** tool invocation (Read, Bash, grep, docs.search), call:
+`actions.record_tool` is **batch-only** — it takes an array of calls, never a single bespoke call. Accumulate the tool invocations you make (Read, Bash, grep, docs.search) as you go, and flush them periodically — every few calls, or at a natural checkpoint like finishing a file or a research thread — via:
 
 ```
-actions.record_tool(actionId, '<ToolName>', '<args-summary>', '<why>')
+actions.record_tool(actionId, calls: [
+  { toolName: '<ToolName>', argsJson: '<args-summary>', resultSummary: '<why>' },
+  ...
+])
 ```
 
-Examples:
-- `actions.record_tool(actionId, 'Read', 'src/auth/middleware.ts', 'find existing JWT pattern')`
-- `actions.record_tool(actionId, 'Bash', 'grep -r "refreshToken" src/', 'locate all refresh token usages')`
-- `actions.record_tool(actionId, 'docs.search', 'authentication middleware', 'check project docs for auth guidance')`
+Even a single tool call must go through this array shape — a one-element array, never a bespoke single-call form.
 
-**Every single tool call must be logged.** No silent reads. The Tools dashboard is built entirely from these `actions.record_tool` calls.
+Example flush after a few calls:
+- `actions.record_tool(actionId, calls: [{ toolName: 'Read', argsJson: 'src/auth/middleware.ts', resultSummary: 'find existing JWT pattern' }, { toolName: 'Bash', argsJson: 'grep -r "refreshToken" src/', resultSummary: 'locate all refresh token usages' }, { toolName: 'docs.search', argsJson: 'authentication middleware', resultSummary: 'check project docs for auth guidance' }])`
+
+**Every tool call must be logged, eventually, in a batch.** No silent reads. The Tools dashboard is built entirely from these `actions.record_tool` calls — accumulate as you work and flush before completing, don't let entries pile up unflushed.
 
 ---
 
@@ -81,7 +84,7 @@ Do NOT read the entire codebase. Be targeted.
 
 ### 5. Log every tool call as you make it
 
-Log each invocation as described in the **MANDATORY TRACKING** section above — do it immediately after each tool call, not at the end.
+Accumulate each invocation as described in the **MANDATORY TRACKING** section above and flush periodically in batches — don't wait until the very end to record everything at once.
 
 ### 6. Produce a structured analysis
 

package/dist/agent-templates/lead.md

@@ -95,18 +95,21 @@ These calls are **not optional**. The dashboard cannot display what you do not r
 
 ### Log every tool call you make
 
-After **each** tool invocation (Bash, tasks.get, tasks.claim, actions.get), call:
+`actions.record_tool` is **batch-only** — it takes an array of calls, never a single bespoke call. As you work, accumulate the tool invocations you make (Bash, tasks.get, tasks.claim, actions.get) and flush them periodically — every few calls, or at a natural checkpoint — via:
 
 ```
-actions.record_tool(actionId, '<ToolName>', '<args-summary>', '<why>')
+actions.record_tool(actionId, calls: [
+  { toolName: '<ToolName>', argsJson: '<args-summary>', resultSummary: '<why/result>' },
+  ...
+])
 ```
 
-Examples:
-- `actions.record_tool(actionId, 'Bash', 'bash health.sh', 'verify codebase health before making changes')`
-- `actions.record_tool(actionId, 'tasks.get', 'pending', 'find next task to claim')`
-- `actions.record_tool(actionId, 'actions.get', 'taskId=abc123', 'read action history to resume in-progress task')`
+Even a single tool call must go through this array shape — a one-element array, never a bespoke single-call form.
 
-**Log every call.** This applies from the moment you have an `actionId` (after step 3 below).
+Example flush after a few calls:
+- `actions.record_tool(actionId, calls: [{ toolName: 'Bash', argsJson: 'bash health.sh', resultSummary: 'verify codebase health before making changes' }, { toolName: 'tasks.get', argsJson: 'pending', resultSummary: 'find next task to claim' }, { toolName: 'actions.get', argsJson: 'taskId=123', resultSummary: 'read action history to resume in-progress task' }])`
+
+**Log every call, batched.** This applies from the moment you have an `actionId` (after step 3 below) — flush at each phase boundary rather than round-tripping once per individual tool use, and never let calls go unrecorded by the time you complete the action.
 
 ---
 

package/dist/agent-templates/reviewer.md

@@ -27,15 +27,19 @@ These calls are **not optional**. The dashboard cannot display what you do not r
 
 ### 1. Log every tool call you make
 
-After **each** tool invocation (Read, Bash), call:
+`actions.record_tool` is **batch-only** — it takes an array of calls, never a single bespoke call. Accumulate each tool invocation (Read, Bash) as you go, and flush periodically — every few calls, or at a natural checkpoint — via:
 
 ```
-actions.record_tool(actionId, '<ToolName>', '<args-summary>', '<why>')
+actions.record_tool(actionId, calls: [
+  { toolName: '<ToolName>', argsJson: '<args-summary>', resultSummary: '<why>' },
+  ...
+])
 ```
 
-Examples:
-- `actions.record_tool(actionId, 'Read', 'src/auth/middleware.ts', 'verify refresh token logic matches criterion 2')`
-- `actions.record_tool(actionId, 'Bash', 'npm test --testPathPattern=auth', 'confirm all auth tests pass')`
+Even a single tool call must go through this array shape — a one-element array, never a bespoke single-call form.
+
+Example flush after a few calls:
+- `actions.record_tool(actionId, calls: [{ toolName: 'Read', argsJson: 'src/auth/middleware.ts', resultSummary: 'verify refresh token logic matches criterion 2' }, { toolName: 'Bash', argsJson: 'npm test --testPathPattern=auth', resultSummary: 'confirm all auth tests pass' }])`
 
 ### 2. Mark every acceptance criterion as you verify it
 

package/dist/{chunk-6PEIJ2D5.js → chunk-JTACLEGM.js}

@@ -1,5 +1,4 @@
 // src/core/db.ts
-import { randomUUID } from "crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { dirname, join, resolve } from "path";
@@ -10,10 +9,13 @@ var ActionRepository = class {
     this.driver = driver;
   }
   driver;
-  async create(id, taskId, agent, now) {
-    await this.driver.exec(
-      `INSERT INTO actions (id, task_id, agent, status, created_at) VALUES (?, ?, ?, 'in_progress', ?)`,
-      [id, taskId, agent, now]
+  /** Returns the new autoincrement id — mirrors TaskRepository.add(). Since
+   *  task #73, `actions.id` is a driver-generated INTEGER, not an
+   *  application-generated UUID, so callers no longer pass an id in. */
+  async create(taskId, agent, now) {
+    return this.driver.insert(
+      `INSERT INTO actions (task_id, agent, status, created_at) VALUES (?, ?, 'in_progress', ?)`,
+      [taskId, agent, now]
     );
   }
   async complete(actionId, summary, now) {
@@ -359,7 +361,7 @@ var TaskRepository = class {
 };
 
 // src/core/db.ts
-var AUTOINCREMENT_TABLES = ["tasks", "task_acceptance", "action_sections", "action_files", "action_tools"];
+var AUTOINCREMENT_TABLES = ["tasks", "task_acceptance", "actions", "action_sections", "action_files", "action_tools"];
 var TABLE_INSERT_ORDER = ["tasks", "task_acceptance", "actions", "action_sections", "action_files", "action_tools"];
 var TABLE_DELETE_ORDER = [...TABLE_INSERT_ORDER].reverse();
 var DEFAULT_SQLITE_PATH = ".harness/harness.db";
@@ -464,9 +466,8 @@ var HarnessDB = class {
   }
   // ─── Actions (public facade — delegates to ActionRepository) ──────────────
   async startAction(taskId, agent) {
-    const id = randomUUID();
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    await this.actions.create(id, taskId, agent, now);
+    const id = await this.actions.create(taskId, agent, now);
     await this.regenerateCurrentMd();
     return await this.actions.getById(id);
   }
@@ -494,12 +495,34 @@ var HarnessDB = class {
   async getActionSections(actionId) {
     return this.actions.getSections(actionId);
   }
-  async recordFile(actionId, filePath, operation, notes) {
-    return this.actions.addFile(actionId, filePath, operation, notes ?? null);
+  /** Batch-only (task #74) — records N files in one atomic transaction. There
+   *  is no single-entry variant; callers pass a one-element array to log a
+   *  single file. Mirrors the driver.transaction() pattern from claimTask()
+   *  above: a fresh ActionRepository is bound to the tx driver so every
+   *  insert in the loop participates in the same transaction and any failure
+   *  rolls back the whole batch. Returns the number of files recorded. */
+  async recordFiles(actionId, files) {
+    return this.driver.transaction(async (tx) => {
+      const txActions = new ActionRepository(tx);
+      for (const f of files) {
+        await txActions.addFile(actionId, f.filePath, f.operation, f.notes ?? null);
+      }
+      return files.length;
+    });
   }
-  async recordTool(actionId, toolName, argsJson, resultSummary) {
+  /** Batch-only (task #74) — records N tool calls in one atomic transaction.
+   *  See recordFiles() above for the pattern; a one-element array is the
+   *  only way to log a single tool call. Returns the number of calls
+   *  recorded. */
+  async recordTools(actionId, calls) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    return this.actions.addTool(actionId, toolName, argsJson ?? null, resultSummary ?? null, now);
+    return this.driver.transaction(async (tx) => {
+      const txActions = new ActionRepository(tx);
+      for (const c of calls) {
+        await txActions.addTool(actionId, c.toolName, c.argsJson ?? null, c.resultSummary ?? null, now);
+      }
+      return calls.length;
+    });
   }
   async getFilesForTask(taskId) {
     return this.actions.getFilesForTask(taskId);
@@ -696,6 +719,11 @@ async function resetAutoincrementSequences(tx, dbType) {
   }
 }
 async function importFullExport(destDriver, data, destDbType, opts = { truncateFirst: false }) {
+  if (data.actions.some((a) => typeof a.id !== "number")) {
+    throw new Error(
+      "This export was produced by an older version of agent-harness-kit (actions used text/UUID ids, pre-2.0) and cannot be imported into a database using the current integer-id actions schema. Re-exporting from the old build is the only way to fix this \u2014 importing this file as-is is not supported."
+    );
+  }
   await destDriver.transaction(async (tx) => {
     if (opts.truncateFirst) {
       await truncateAllTables(tx);
@@ -779,13 +807,13 @@ async function openDB(config, cwd, homeDir = homedir()) {
   const dbConfig = config.database;
   let driver;
   if (dbConfig.type === "postgres") {
-    const { PostgresDriver } = await import("./postgres-IOQE32DM.js");
+    const { PostgresDriver } = await import("./postgres-BB4GY4PN.js");
     driver = new PostgresDriver(dbConfig);
   } else if (dbConfig.type === "mysql") {
-    const { MySQLDriver } = await import("./mysql-THKQOXIS.js");
+    const { MySQLDriver } = await import("./mysql-AUPKARWA.js");
     driver = new MySQLDriver(dbConfig);
   } else {
-    const { SQLiteDriver } = await import("./sqlite-TR4D324R.js");
+    const { SQLiteDriver } = await import("./sqlite-5OWKTUUZ.js");
     if (dbConfig.type !== "sqlite") {
       throw new Error("Invalid database type");
     }
@@ -823,6 +851,7 @@ export {
   HarnessDB,
   getRowCounts,
   isEmptyDatabase,
+  resetAutoincrementSequences,
   importFullExport,
   resolveSqlitePathForScope,
   resolveSqlitePath,
@@ -831,4 +860,4 @@ export {
   readStorageStateFile,
   openDB
 };
-//# sourceMappingURL=chunk-6PEIJ2D5.js.map
+//# sourceMappingURL=chunk-JTACLEGM.js.map