harnery 0.7.1 → 0.9.0

package/dist/core/workflow/spawn-cursor.js

@@ -0,0 +1,72 @@
+/**
+ * cursor spawn adapter: runs one subagent as a headless `cursor-agent -p`
+ * subprocess with `--output-format json`.
+ *
+ * Contract notes (LIVE-VERIFIED 2026-07-17 against cursor-agent
+ * 2026.07.16-899851b: schema-gated triage + text stages round-trip via
+ * `--harness cursor`, session_id parses from the envelope):
+ * - `cursor-agent -p "<prompt>" --output-format json` prints a single result
+ *   envelope modeled on Claude Code's (`{type: "result", is_error, result,
+ *   session_id, …}`).
+ * - `--trust` is required: headless runs refuse untrusted workspaces (exit 1,
+ *   "Workspace Trust Required") — see the argv comment below.
+ * - Envelope drift guard: when stdout doesn't parse as JSON but the process
+ *   exited 0, the raw stdout is returned as the reply text.
+ * - No per-run cost surface → undefined. No max-turns equivalent → `maxTurns`
+ *   accepted and ignored (documented in the CLI docs page).
+ */
+import { exec } from "../../lib/exec.js";
+import { buildChildEnv } from "./child-env.js";
+import { notFoundError } from "./harnesses.js";
+/** Exported for unit tests (no live binary to test against). */
+export function parseCursorOutput(stdout) {
+    try {
+        const envelope = JSON.parse(stdout);
+        return {
+            text: String(envelope.result ?? ""),
+            sessionId: envelope.session_id,
+            isError: Boolean(envelope.is_error),
+        };
+    }
+    catch {
+        return { text: stdout, isError: false };
+    }
+}
+export const cursorSpawner = async (req) => {
+    const t0 = Date.now();
+    // --trust: headless cursor-agent refuses untrusted workspaces (exit 1,
+    // "Workspace Trust Required"). Workflow children run in the engine's cwd
+    // deliberately and may edit files — the same posture as the codex adapter's
+    // `--sandbox workspace-write` — so trusting that directory is implied.
+    const argv = ["cursor-agent", "-p", req.prompt, "--output-format", "json", "--trust"];
+    if (req.model)
+        argv.push("--model", req.model);
+    const r = await exec(argv, {
+        cwd: req.cwd,
+        env: buildChildEnv(req.runId, { subscriptionOnly: req.subscriptionOnly }),
+        timeout: req.timeoutMs,
+    });
+    const durationMs = Date.now() - t0;
+    if (r.exitCode === 127) {
+        return { ok: false, text: "", durationMs, error: notFoundError("cursor") };
+    }
+    if (r.exitCode !== 0) {
+        return {
+            ok: false,
+            text: "",
+            durationMs,
+            error: `cursor-agent exited ${r.exitCode}: ${(r.stderr || r.stdout).slice(0, 500)}`,
+        };
+    }
+    const parsed = parseCursorOutput(r.stdout);
+    if (parsed.isError) {
+        return {
+            ok: false,
+            text: parsed.text,
+            sessionId: parsed.sessionId,
+            durationMs,
+            error: `cursor-agent reported is_error: ${parsed.text.slice(0, 300)}`,
+        };
+    }
+    return { ok: true, text: parsed.text, sessionId: parsed.sessionId, durationMs };
+};

package/dist/core/workflow/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Workflow engine contracts. A workflow is a small throwaway JS script with
+ * bounded, schema-gated stages that fan work out to headless harness-CLI
+ * subagents; the SCRIPT (deterministic code), not any model, decides routing
+ * between stages, and the run always terminates when the script returns.
+ *
+ * Design record: decision 0015 (portable coordination-aware workflows).
+ */
+import type { BillingMode, BillingProber } from "./billing.js";
+/** JSON-schema *subset* accepted by stage gates (see validate.ts). */
+export interface StageSchema {
+    type: "object" | "array" | "string" | "number" | "boolean";
+    /** type=object */
+    properties?: Record<string, StageSchema>;
+    required?: string[];
+    /** type=array */
+    items?: StageSchema;
+    /** any type: closed value set (compared with ===) */
+    enum?: Array<string | number | boolean>;
+}
+export interface AgentOpts {
+    /** Stage gate: when present, the agent's reply must strict-parse as JSON and
+     * validate; the engine retries with the validation error appended, up to
+     * `maxAttempts`. Without it, `agent()` resolves to the raw reply text. */
+    schema?: StageSchema;
+    /** Model slug passed through to the harness CLI (default: the CLI's default). */
+    model?: string;
+    /** Attempt ceiling for the schema-retry loop (default 2). */
+    maxAttempts?: number;
+    /** Subprocess timeout ms (default 300_000). */
+    timeoutMs?: number;
+    /** Harness-turn ceiling for the child (default 25; use 1 for pure
+     * classification stages — cheaper and faster). */
+    maxTurns?: number;
+    /** Display label in the journal (default: prompt head). */
+    label?: string;
+    /** Which harness runs this agent (default: the run's default harness).
+     * Mixed-harness workflows are legal: triage on one CLI, deep work on
+     * another. */
+    harness?: HarnessName;
+}
+export type HarnessName = "claude-code" | "codex" | "cursor";
+/** What a spawn adapter returns for one subagent run. */
+export interface SpawnResult {
+    ok: boolean;
+    /** The model's final reply text (envelope-unwrapped). */
+    text: string;
+    /** Child harness session id when the envelope carries one. */
+    sessionId?: string;
+    costUsd?: number;
+    durationMs: number;
+    /** Populated when ok=false. */
+    error?: string;
+}
+export interface SpawnRequest {
+    prompt: string;
+    model?: string;
+    timeoutMs: number;
+    maxTurns: number;
+    cwd: string;
+    /** Run id, stamped into the child env (HARNERY_WORKFLOW_RUN_ID) so the
+     * coord layer can associate child sessions with their workflow run. */
+    runId?: string;
+    /** Scrub all API-key vars from the child env so it can only authenticate
+     * via its stored (subscription) login. See billing.ts. */
+    subscriptionOnly?: boolean;
+}
+/** One headless-subagent runner. The engine is adapter-agnostic; claude-code
+ * ships first, codex/cursor land behind the same signature (plan Phase 4). */
+export type Spawner = (req: SpawnRequest) => Promise<SpawnResult>;
+/** The API surface injected into a workflow script's default export. Explicit
+ * injection (no ambient globals): keeps scripts portable and unit-testable. */
+export interface WorkflowContext {
+    /** Spawn one subagent; resolves to validated JSON (schema) or reply text. */
+    agent: (prompt: string, opts?: AgentOpts) => Promise<unknown>;
+    /** Run thunks with bounded concurrency; a rejected thunk resolves to null. */
+    parallel: <T>(thunks: Array<() => Promise<T>>) => Promise<Array<T | null>>;
+    /** Declare the current stage (journal + progress grouping). */
+    stage: (title: string) => void;
+    /** Narrate progress (stderr + journal). */
+    log: (message: string) => void;
+}
+export interface WorkflowMeta {
+    name: string;
+    description?: string;
+}
+/** Loaded script shape: `export const meta` + `export default async (ctx) => …`. */
+export interface WorkflowModule {
+    meta?: WorkflowMeta;
+    default: (ctx: WorkflowContext) => Promise<unknown>;
+}
+export interface EngineOpts {
+    /** Repo root whose .harnery/ receives the run journal. */
+    coordRoot: string;
+    /** Spawner registry keyed by harness. A single-harness caller registers one
+     * entry and names it in `defaultHarness`. */
+    spawners: Partial<Record<HarnessName, Spawner>>;
+    /** Harness used when an agent() call doesn't name one (default "claude-code"). */
+    defaultHarness?: HarnessName;
+    /** Resume: run id of a prior run whose journal supplies cached results.
+     * agent() calls whose (stage, prompt, model, maxTurns, schema) key matches a
+     * completed prior agent return the journaled result without spawning. */
+    resumeFrom?: string;
+    /** Total-agent ceiling for the run (default 50): the runaway backstop. */
+    maxAgents?: number;
+    /** Concurrent-subagent cap for parallel() (default 4). */
+    concurrency?: number;
+    /** Working directory children spawn in (default: coordRoot). */
+    cwd?: string;
+    /** Progress sink (default: process.stderr). */
+    onLog?: (line: string) => void;
+    /** Guarantee subscription billing: API-key vars are scrubbed from every
+     * child env, and a harness whose stored login is provably absent fails
+     * loud before spawning. */
+    subscriptionOnly?: boolean;
+    /** Permit the api-key-override billing state (an exported API key silently
+     * shadowing a stored subscription login), which the engine otherwise
+     * refuses. Deliberate key-only hosts don't need this — only the
+     * both-present case does. */
+    allowApiBilling?: boolean;
+    /** Billing-probe override for tests (default: the real probeBilling). */
+    probeBilling?: BillingProber;
+}
+export interface RunReport {
+    runId: string;
+    name: string;
+    /** What the script's default export returned. */
+    result: unknown;
+    agentsSpawned: number;
+    /** agent() calls satisfied from the resumeFrom journal without spawning. */
+    agentsCached: number;
+    costUsd: number;
+    durationMs: number;
+    journalPath: string;
+    /** Estimated tokens of repo instructions (CLAUDE.md/AGENTS.md at the child
+     * cwd) that EVERY child cache-writes on spawn — the fixed per-child context
+     * overhead a fan-out multiplies. bytes/4 heuristic; 0 when no such file. */
+    contextTokensPerChildEstimate: number;
+    /** Billing mode per harness actually used this run (probed on first use). */
+    billing: Array<{
+        harness: HarnessName;
+        mode: BillingMode;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/workflow/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/types.ts"],"names":[],"mappings":"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"}

package/dist/core/workflow/types.js

@@ -0,0 +1,9 @@
+/**
+ * Workflow engine contracts. A workflow is a small throwaway JS script with
+ * bounded, schema-gated stages that fan work out to headless harness-CLI
+ * subagents; the SCRIPT (deterministic code), not any model, decides routing
+ * between stages, and the run always terminates when the script returns.
+ *
+ * Design record: decision 0015 (portable coordination-aware workflows).
+ */
+export {};

package/dist/core/workflow/validate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal validator for the StageSchema JSON-schema subset. Deliberately tiny:
+ * a full JSON Schema implementation would pull a dependency (ajv) for
+ * validation depth workflow gates don't need. Supported: type, properties,
+ * required, items, enum. Returns a list of human-readable problems (empty =
+ * valid) so the engine can feed failures back into the retry prompt verbatim.
+ */
+import type { StageSchema } from "./types.js";
+export declare function validateAgainstSchema(value: unknown, schema: StageSchema, path?: string): string[];
+/** Strip accidental markdown code fences, then strict-parse JSON. */
+export declare function parseStageOutput(text: string): {
+    value?: unknown;
+    error?: string;
+};
+//# sourceMappingURL=validate.d.ts.map

package/dist/core/workflow/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/validate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,SAAM,GAAG,MAAM,EAAE,CA8C/F;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAUlF"}

package/dist/core/workflow/validate.js

@@ -0,0 +1,70 @@
+/**
+ * Minimal validator for the StageSchema JSON-schema subset. Deliberately tiny:
+ * a full JSON Schema implementation would pull a dependency (ajv) for
+ * validation depth workflow gates don't need. Supported: type, properties,
+ * required, items, enum. Returns a list of human-readable problems (empty =
+ * valid) so the engine can feed failures back into the retry prompt verbatim.
+ */
+export function validateAgainstSchema(value, schema, path = "$") {
+    const problems = [];
+    if (schema.enum) {
+        if (!schema.enum.some((v) => v === value)) {
+            problems.push(`${path}: expected one of ${JSON.stringify(schema.enum)}, got ${short(value)}`);
+        }
+        return problems; // enum is exhaustive; type check is implied by membership
+    }
+    switch (schema.type) {
+        case "object": {
+            if (typeof value !== "object" || value === null || Array.isArray(value)) {
+                return [`${path}: expected object, got ${short(value)}`];
+            }
+            const obj = value;
+            for (const key of schema.required ?? []) {
+                if (!(key in obj))
+                    problems.push(`${path}.${key}: required property missing`);
+            }
+            for (const [key, sub] of Object.entries(schema.properties ?? {})) {
+                if (key in obj)
+                    problems.push(...validateAgainstSchema(obj[key], sub, `${path}.${key}`));
+            }
+            return problems;
+        }
+        case "array": {
+            if (!Array.isArray(value))
+                return [`${path}: expected array, got ${short(value)}`];
+            if (schema.items) {
+                for (const [i, item] of value.entries()) {
+                    problems.push(...validateAgainstSchema(item, schema.items, `${path}[${i}]`));
+                }
+            }
+            return problems;
+        }
+        case "string":
+        case "number":
+        case "boolean": {
+            if (typeof value !== schema.type) {
+                problems.push(`${path}: expected ${schema.type}, got ${short(value)}`);
+            }
+            return problems;
+        }
+        default:
+            return [`${path}: unsupported schema type ${String(schema.type)}`];
+    }
+}
+/** Strip accidental markdown code fences, then strict-parse JSON. */
+export function parseStageOutput(text) {
+    const stripped = text
+        .trim()
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/\s*```$/, "");
+    try {
+        return { value: JSON.parse(stripped) };
+    }
+    catch (err) {
+        return { error: `not valid JSON: ${err.message}` };
+    }
+}
+function short(value) {
+    const s = JSON.stringify(value);
+    return s === undefined ? String(value) : s.length > 60 ? `${s.slice(0, 60)}…` : s;
+}

package/dist/lib/tools/ripgrep.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Managed ripgrep provisioning for `grep --files` / content search.
+ *
+ * harnery can install a pinned, checksum-verified ripgrep into its own tools
+ * directory (`$XDG_DATA_HOME/harnery/tools`, default `~/.local/share/harnery/
+ * tools`) so `harn grep` gets the fast engine even on machines where nobody
+ * ever installed rg. The download is version-pinned and every artifact's
+ * sha256 is baked in below (cross-checked against the official release
+ * checksums), so the install is reproducible, never "whatever is latest."
+ *
+ * Consent model: the installer only runs automatically when the host project
+ * opts in via `.harnery/config.jsonc` `{ "tools": { "ripgrep": { "autoInstall":
+ * true } } }` — a repo commits that once and every clone self-heals. Without
+ * the opt-in, a missing rg produces a rate-limited stderr hint naming
+ * `harn doctor --fix` (explicit install). Environments that forbid downloads
+ * lose nothing: every failure path falls back to GNU grep.
+ */
+export declare const RG_VERSION = "14.1.1";
+/** True when a pinned artifact exists for this OS/arch (Windows: not yet). */
+export declare function rgInstallSupported(): boolean;
+/** Machine-level harnery tools dir (NOT the per-project .harnery/ state dir). */
+export declare function toolsDir(): string;
+/** Path the managed rg binary lives at once installed. */
+export declare function managedRgPath(): string;
+/**
+ * Locate a usable ripgrep. Precedence:
+ *   1. HARNERY_RG_PATH (explicit override)
+ *   2. the managed tools-dir install (works even when PATH doesn't carry it)
+ *   3. `rg` on PATH
+ * Returns the spawnable path/name, or null when none respond to --version.
+ */
+export declare function findRg(): string | null;
+/**
+ * Download + verify + install the pinned ripgrep into the tools dir.
+ * Atomic: extracts to a temp dir and renames the binary into place.
+ * Throws on unsupported platform, network failure, or checksum mismatch —
+ * callers are expected to fall back to grep and say why.
+ */
+export declare function installRg(log?: (line: string) => void): Promise<string>;
+export type SearchEngine = "rg" | "grep";
+/**
+ * Shared engine resolver for the ripgrep-backed search commands (`grep`,
+ * `callers`). Returns the engine plus the spawnable rg path.
+ *
+ * `HARNERY_GREP_ENGINE=rg|grep` forces one; otherwise findRg() probes
+ * HARNERY_RG_PATH → the managed tools-dir install → PATH. On a miss, the
+ * host's `.harnery/config.jsonc` `tools.ripgrep.autoInstall` consent triggers
+ * a pinned, checksum-verified install into the harnery tools dir (any failure
+ * falls back to grep with a stderr note); without consent, a rate-limited
+ * stderr hint (keyed per `hintKey`) names the explicit install command.
+ */
+export declare function resolveSearchEngine(hintKey?: string): Promise<{
+    engine: SearchEngine;
+    rgBin: string;
+}>;
+/**
+ * Emit `line` to stderr at most once per 24h (stamp file in the tools dir).
+ * Keeps the "rg missing" nudge from nagging on every single grep invocation.
+ */
+export declare function hintOncePerDay(line: string): void;
+//# sourceMappingURL=ripgrep.d.ts.map

package/dist/lib/tools/ripgrep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ripgrep.d.ts","sourceRoot":"","sources":["../../../src/lib/tools/ripgrep.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,UAAU,WAAW,CAAC;AA0BnC,8EAA8E;AAC9E,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,IAAI,MAAM,CAIjC;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAWD;;;;;;GAMG;AACH,wBAAgB,MAAM,IAAI,MAAM,GAAG,IAAI,CAStC;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAoD7E;AAkBD,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,MAAM,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,SAAS,GACf,OAAO,CAAC;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CA6BlD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAYjD"}

package/dist/lib/tools/ripgrep.js

@@ -0,0 +1,217 @@
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveBinName, ripgrepAutoInstall } from "../../core/config.js";
+import { coordEnv } from "../env.js";
+/**
+ * Managed ripgrep provisioning for `grep --files` / content search.
+ *
+ * harnery can install a pinned, checksum-verified ripgrep into its own tools
+ * directory (`$XDG_DATA_HOME/harnery/tools`, default `~/.local/share/harnery/
+ * tools`) so `harn grep` gets the fast engine even on machines where nobody
+ * ever installed rg. The download is version-pinned and every artifact's
+ * sha256 is baked in below (cross-checked against the official release
+ * checksums), so the install is reproducible, never "whatever is latest."
+ *
+ * Consent model: the installer only runs automatically when the host project
+ * opts in via `.harnery/config.jsonc` `{ "tools": { "ripgrep": { "autoInstall":
+ * true } } }` — a repo commits that once and every clone self-heals. Without
+ * the opt-in, a missing rg produces a rate-limited stderr hint naming
+ * `harn doctor --fix` (explicit install). Environments that forbid downloads
+ * lose nothing: every failure path falls back to GNU grep.
+ */
+export const RG_VERSION = "14.1.1";
+/** sha256 pins verified against the official ripgrep release .sha256 assets. */
+const ARTIFACTS = {
+    "linux-x64": {
+        name: `ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl.tar.gz`,
+        sha256: "4cf9f2741e6c465ffdb7c26f38056a59e2a2544b51f7cc128ef28337eeae4d8e",
+    },
+    "linux-arm64": {
+        name: `ripgrep-${RG_VERSION}-aarch64-unknown-linux-gnu.tar.gz`,
+        sha256: "c827481c4ff4ea10c9dc7a4022c8de5db34a5737cb74484d62eb94a95841ab2f",
+    },
+    "darwin-x64": {
+        name: `ripgrep-${RG_VERSION}-x86_64-apple-darwin.tar.gz`,
+        sha256: "fc87e78f7cb3fea12d69072e7ef3b21509754717b746368fd40d88963630e2b3",
+    },
+    "darwin-arm64": {
+        name: `ripgrep-${RG_VERSION}-aarch64-apple-darwin.tar.gz`,
+        sha256: "24ad76777745fbff131c8fbc466742b011f925bfa4fffa2ded6def23b5b937be",
+    },
+};
+function platformKey() {
+    return `${process.platform}-${process.arch}`;
+}
+/** True when a pinned artifact exists for this OS/arch (Windows: not yet). */
+export function rgInstallSupported() {
+    return platformKey() in ARTIFACTS;
+}
+/** Machine-level harnery tools dir (NOT the per-project .harnery/ state dir). */
+export function toolsDir() {
+    const xdg = process.env.XDG_DATA_HOME;
+    const base = xdg && xdg.trim() !== "" ? xdg : join(homedir(), ".local", "share");
+    return join(base, "harnery", "tools");
+}
+/** Path the managed rg binary lives at once installed. */
+export function managedRgPath() {
+    return join(toolsDir(), "rg");
+}
+function isExecutable(p) {
+    try {
+        const r = spawnSync(p, ["--version"], { stdio: "ignore" });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Locate a usable ripgrep. Precedence:
+ *   1. HARNERY_RG_PATH (explicit override)
+ *   2. the managed tools-dir install (works even when PATH doesn't carry it)
+ *   3. `rg` on PATH
+ * Returns the spawnable path/name, or null when none respond to --version.
+ */
+export function findRg() {
+    const override = coordEnv("RG_PATH");
+    if (override && override.trim() !== "") {
+        return isExecutable(override) ? override : null;
+    }
+    const managed = managedRgPath();
+    if (existsSync(managed) && isExecutable(managed))
+        return managed;
+    if (isExecutable("rg"))
+        return "rg";
+    return null;
+}
+/**
+ * Download + verify + install the pinned ripgrep into the tools dir.
+ * Atomic: extracts to a temp dir and renames the binary into place.
+ * Throws on unsupported platform, network failure, or checksum mismatch —
+ * callers are expected to fall back to grep and say why.
+ */
+export async function installRg(log) {
+    const key = platformKey();
+    const artifact = ARTIFACTS[key];
+    if (!artifact) {
+        throw new Error(`no pinned ripgrep artifact for ${key} — install ripgrep manually (https://github.com/BurntSushi/ripgrep#installation)`);
+    }
+    const url = `https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${artifact.name}`;
+    log?.(`downloading ${artifact.name} (pinned ${RG_VERSION})...`);
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`download failed: HTTP ${res.status} for ${url}`);
+    const bytes = Buffer.from(await res.arrayBuffer());
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== artifact.sha256) {
+        throw new Error(`sha256 mismatch for ${artifact.name}: expected ${artifact.sha256}, got ${digest} — refusing to install`);
+    }
+    const work = join(tmpdir(), `harnery-rg-${process.pid}`);
+    rmSync(work, { recursive: true, force: true });
+    mkdirSync(work, { recursive: true });
+    try {
+        const tarball = join(work, artifact.name);
+        writeFileSync(tarball, bytes);
+        await extractTar(tarball, work);
+        const extractedRg = join(work, artifact.name.replace(/\.tar\.gz$/, ""), "rg");
+        const rgStat = await stat(extractedRg);
+        if (!rgStat.isFile())
+            throw new Error(`extracted archive missing rg binary at ${extractedRg}`);
+        mkdirSync(toolsDir(), { recursive: true });
+        const dest = managedRgPath();
+        // rename() can't cross filesystems (tmp is often tmpfs); copy + rename
+        // within the destination dir keeps the final placement atomic.
+        const staged = `${dest}.tmp-${process.pid}`;
+        writeFileSync(staged, await readFile(extractedRg));
+        chmodSync(staged, 0o755);
+        renameSync(staged, dest);
+        if (!isExecutable(dest)) {
+            rmSync(dest, { force: true });
+            throw new Error(`installed rg at ${dest} but it failed to execute`);
+        }
+        log?.(`installed ripgrep ${RG_VERSION} -> ${dest}`);
+        return dest;
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}
+function extractTar(tarball, cwd) {
+    return new Promise((resolveP, reject) => {
+        const proc = spawn("tar", ["xzf", tarball], { cwd, stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        proc.stderr.setEncoding("utf8");
+        proc.stderr.on("data", (c) => {
+            stderr += c;
+        });
+        proc.on("error", reject);
+        proc.on("close", (code) => {
+            if (code === 0)
+                resolveP();
+            else
+                reject(new Error(`tar exited ${code}: ${stderr.trim()}`));
+        });
+    });
+}
+/**
+ * Shared engine resolver for the ripgrep-backed search commands (`grep`,
+ * `callers`). Returns the engine plus the spawnable rg path.
+ *
+ * `HARNERY_GREP_ENGINE=rg|grep` forces one; otherwise findRg() probes
+ * HARNERY_RG_PATH → the managed tools-dir install → PATH. On a miss, the
+ * host's `.harnery/config.jsonc` `tools.ripgrep.autoInstall` consent triggers
+ * a pinned, checksum-verified install into the harnery tools dir (any failure
+ * falls back to grep with a stderr note); without consent, a rate-limited
+ * stderr hint (keyed per `hintKey`) names the explicit install command.
+ */
+export async function resolveSearchEngine(hintKey = "grep") {
+    const forced = coordEnv("GREP_ENGINE");
+    if (forced === "grep")
+        return { engine: "grep", rgBin: "rg" };
+    const found = findRg();
+    if (found)
+        return { engine: "rg", rgBin: found };
+    if (forced === "rg") {
+        // Forced rg with none findable: let the spawn error surface loudly.
+        return { engine: "rg", rgBin: "rg" };
+    }
+    if (rgInstallSupported()) {
+        if (ripgrepAutoInstall()) {
+            try {
+                const installed = await installRg((line) => process.stderr.write(`harnery: ${line}\n`));
+                return { engine: "rg", rgBin: installed };
+            }
+            catch (err) {
+                process.stderr.write(`harnery: ripgrep auto-install failed (${err.message}); using grep fallback\n`);
+                return { engine: "grep", rgBin: "rg" };
+            }
+        }
+        const bin = resolveBinName();
+        hintOncePerDay(`${bin} ${hintKey}: ripgrep not found; using the slower GNU grep fallback. ` +
+            `Run \`${bin} doctor --fix\` to install it (pinned + checksum-verified), ` +
+            `or set { "tools": { "ripgrep": { "autoInstall": true } } } in .harnery/config.jsonc.`);
+    }
+    return { engine: "grep", rgBin: "rg" };
+}
+/**
+ * Emit `line` to stderr at most once per 24h (stamp file in the tools dir).
+ * Keeps the "rg missing" nudge from nagging on every single grep invocation.
+ */
+export function hintOncePerDay(line) {
+    try {
+        const stamp = join(toolsDir(), ".rg-hint-stamp");
+        if (existsSync(stamp) && Date.now() - statSync(stamp).mtimeMs < 24 * 60 * 60 * 1000) {
+            return;
+        }
+        mkdirSync(toolsDir(), { recursive: true });
+        writeFileSync(stamp, String(Date.now()));
+    }
+    catch {
+        // stamping failed; still emit the hint
+    }
+    process.stderr.write(`${line}\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",

package/src/commander.ts

@@ -49,6 +49,7 @@ import { registerSectionCommand, registerTocCommand } from "./commands/toc.ts";
 import { registerTokensCommand } from "./commands/tokens.ts";
 import { registerTunnelCommand } from "./commands/tunnel.ts";
 import { registerWebCommand } from "./commands/web.ts";
+import { registerWorkflowCommand } from "./commands/workflow.ts";
 
 export interface HarneryContextOpts {
   /**
@@ -120,6 +121,15 @@ export interface HarneryProgramContext {
    * carrying provider-specific checks. harn standalone ships none.
    */
   envSections?: Record<string, EnvSection>;
+  /**
+   * Extra directory names for `grep` to exclude by default — host-generated
+   * mirrors, vendored trees, and similar directories that only ever produce
+   * duplicate or noisy matches. Names match at any depth (same semantics as
+   * grep's `--exclude-dir`). Applied alongside the built-in skip list and
+   * disabled together with it by `--no-default-excludes`. harn standalone
+   * ships none.
+   */
+  grepExcludeDirs?: readonly string[];
   /**
    * Optional callback that returns extra HTTP headers to attach to outbound
    * `fetch` calls based on the target URL. Useful for consumers that need
@@ -268,6 +278,7 @@ export function createHarneryProgram(opts: HarneryContextOpts = {}): Command {
   registerDeinitCommand(program, emit, opts.binName);
   registerBackupCommand(program, emit);
   registerSyncCommand(program, emit);
+  registerWorkflowCommand(program, emit);
   if (include("web")) registerWebCommand(program, emit);
 
   return program;