harnery 0.7.1 → 0.9.0

package/src/commands/init.ts

@@ -120,6 +120,17 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
         if (stamp) actions.push(stamp);
       }
 
+      // ── 1c. workflow billing default ───────────────────────────────────────
+      // Every init'd project gets `workflow.subscriptionOnly: true`: workflow
+      // children ride the logged-in (subscription) harness auth, and the pin
+      // makes per-token API billing structurally impossible unless the project
+      // deliberately flips it. A committed `workflow` key of any shape is a
+      // deliberate choice and is never touched.
+      {
+        const stamp = stampWorkflowDefaults(resolve(coordDir, "config.jsonc"), dryRun);
+        if (stamp) actions.push(stamp);
+      }
+
       // ── 2. harness hooks ───────────────────────────────────────────────────
       const settingsPath = resolve(projectRoot, spec.settingsFile);
       const agentHook = relative(projectRoot, resolve(HARNERY_ROOT, "bin", "agent-hook"));
@@ -139,23 +150,23 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
       } else {
         settings = {};
       }
-      const { wired, already, removed } = wireHooks(settings, spec, agentHook, harness);
+      const { wired, already, removed, upgraded } = wireHooks(settings, spec, agentHook, harness);
 
-      if (wired === 0 && removed === 0) {
+      if (wired === 0 && removed === 0 && upgraded === 0) {
         actions.push(
           `· all ${spec.events.length} ${harness} hooks already wired in ${rel(projectRoot, settingsPath)}`,
         );
       } else if (dryRun) {
         actions.push(
-          `+ would wire ${wired} hook(s) and remove ${removed} legacy hook(s) in ` +
-            `${rel(projectRoot, settingsPath)} (${already} already present)`,
+          `+ would wire ${wired} hook(s), upgrade ${upgraded} stale command(s), and remove ` +
+            `${removed} legacy hook(s) in ${rel(projectRoot, settingsPath)} (${already} already present)`,
         );
       } else {
         mkdirSync(dirname(settingsPath), { recursive: true });
         writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
         actions.push(
-          `+ wired ${wired} hook(s) and removed ${removed} legacy hook(s) in ` +
-            `${rel(projectRoot, settingsPath)} (${already} already present)`,
+          `+ wired ${wired} hook(s), upgraded ${upgraded} stale command(s), and removed ` +
+            `${removed} legacy hook(s) in ${rel(projectRoot, settingsPath)} (${already} already present)`,
         );
       }
 
@@ -169,11 +180,12 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
 
 /**
  * Merge agent-hook entries into a harness settings object in place, idempotently.
- * Preserves every existing hook; skips events already wired to
- * `agent-hook <subcommand>`. Honors the harness's entry shape (Claude/Codex nest
- * under an inner `hooks` array; Cursor uses a flat `{ command }`) and ensures the
- * root `version` key when the harness requires one. Pure (no fs/git) so it's
- * unit-testable.
+ * Preserves every existing hook; rewrites events already wired to
+ * `agent-hook <subcommand>` when their command string is stale (e.g. an older
+ * harnery wired a bare relative path). Honors the harness's entry shape
+ * (Claude/Codex nest under an inner `hooks` array; Cursor uses a flat
+ * `{ command }`) and ensures the root `version` key when the harness requires
+ * one. Pure (no fs/git) so it's unit-testable.
  *
  * The trailing space in the match (`agent-hook ${subcommand} `) is load-bearing:
  * it keeps `stop` from matching `stop-failure`.
@@ -183,7 +195,7 @@ export function wireHooks(
   spec: HarnessSpec,
   agentHookPath: string,
   harness: HarnessId,
-): { wired: number; already: number; removed: number } {
+): { wired: number; already: number; removed: number; upgraded: number } {
   if (spec.rootVersion !== undefined && settings.version === undefined) {
     settings.version = spec.rootVersion;
   }
@@ -191,6 +203,7 @@ export function wireHooks(
   let wired = 0;
   let already = 0;
   let removed = 0;
+  let upgraded = 0;
   for (const { settingsKey, subcommand } of spec.legacyEvents ?? []) {
     const groups = settings.hooks[settingsKey] ?? [];
     const kept = groups.filter(
@@ -202,11 +215,14 @@ export function wireHooks(
     else settings.hooks[settingsKey] = kept;
   }
   for (const { settingsKey, subcommand } of spec.events) {
-    const command = `bash ${agentHookPath} ${subcommand} --harness ${harness}`;
+    const command = hookCommand(spec, agentHookPath, subcommand, harness);
     const groups = settings.hooks[settingsKey] ?? [];
-    const present = groups.some((g) =>
-      groupCommands(g).some((c) => commandWiresSubcommand(c, subcommand)),
-    );
+    let present = false;
+    for (const group of groups) {
+      upgraded += rewriteStaleCommands(group, subcommand, command, () => {
+        present = true;
+      });
+    }
     if (present) {
       already++;
       continue;
@@ -215,7 +231,62 @@ export function wireHooks(
     settings.hooks[settingsKey] = groups;
     wired++;
   }
-  return { wired, already, removed };
+  return { wired, already, removed, upgraded };
+}
+
+/**
+ * The canonical hook command for one event. When the harness exports a
+ * project-dir env var to hook processes (Claude Code's CLAUDE_PROJECT_DIR),
+ * anchor the agent-hook path on it: hook processes inherit the session
+ * shell's cwd, which follows `cd` away from the project root — a bare
+ * relative path silently fails to spawn from there (no events, no image
+ * capture, no guards). `:-.` keeps the command working on harness versions
+ * that don't set the var. Only the env expansion is quoted so the
+ * `agent-hook <subcommand> ` wiring match stays byte-identical.
+ */
+function hookCommand(
+  spec: HarnessSpec,
+  agentHookPath: string,
+  subcommand: string,
+  harness: HarnessId,
+): string {
+  const anchor = spec.projectDirEnv ? `"\${${spec.projectDirEnv}:-.}"/` : "";
+  return `bash ${anchor}${agentHookPath} ${subcommand} --harness ${harness}`;
+}
+
+/**
+ * Rewrite any harnery-owned command for `subcommand` inside one hook group to
+ * the canonical form, in place. Returns the number of commands rewritten and
+ * calls `onPresent` when the subcommand is wired in this group at all.
+ */
+function rewriteStaleCommands(
+  group: HookGroup,
+  subcommand: string,
+  canonical: string,
+  onPresent: () => void,
+): number {
+  let rewritten = 0;
+  if ("command" in group && typeof group.command === "string") {
+    if (commandWiresSubcommand(group.command, subcommand)) {
+      onPresent();
+      if (group.command !== canonical) {
+        group.command = canonical;
+        rewritten++;
+      }
+    }
+  }
+  if ("hooks" in group && Array.isArray(group.hooks)) {
+    for (const hook of group.hooks) {
+      if (typeof hook.command !== "string") continue;
+      if (!commandWiresSubcommand(hook.command, subcommand)) continue;
+      onPresent();
+      if (hook.command !== canonical) {
+        hook.command = canonical;
+        rewritten++;
+      }
+    }
+  }
+  return rewritten;
 }
 
 /**
@@ -311,6 +382,56 @@ export function stampBinName(configPath: string, binName: string, dryRun: boolea
   return `+ added binName "${binName}" to ${rel(configPath)}`;
 }
 
+/** The commented workflow-billing default block init stamps into config.jsonc. */
+const WORKFLOW_DEFAULT_BLOCK =
+  `  // Workflow children ride the logged-in (subscription) harness auth; this pin\n` +
+  `  // scrubs API-key vars from child envs so runs can never bill per-token rates.\n` +
+  `  // Key-only hosts (CI): set false, or HARNERY_WORKFLOW_SUBSCRIPTION_ONLY=0.\n` +
+  `  "workflow": { "subscriptionOnly": true }`;
+
+/**
+ * Idempotently pin `workflow.subscriptionOnly: true` in `.harnery/config.jsonc`
+ * (see `workflowSubscriptionOnly()` in core/config.ts and the `workflow run`
+ * billing safeguards). Same comment-preserving discipline as `stampBinName`.
+ * A `workflow` key of ANY shape (including `subscriptionOnly: false`) is a
+ * deliberate project choice and is left alone.
+ */
+export function stampWorkflowDefaults(configPath: string, dryRun: boolean): string | null {
+  const rel = (p: string) => relative(dirname(dirname(configPath)), p) || p;
+
+  if (!existsSync(configPath)) {
+    if (dryRun) return `+ would pin workflow.subscriptionOnly in ${rel(configPath)}`;
+    writeFileSync(configPath, `{\n${WORKFLOW_DEFAULT_BLOCK}\n}\n`);
+    return `+ pinned workflow.subscriptionOnly: true in ${rel(configPath)}`;
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(configPath, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: { workflow?: unknown } & Record<string, unknown>;
+  try {
+    parsed = (JSON.parse(stripJsonComments(raw)) as typeof parsed) ?? {};
+  } catch {
+    return `· ${rel(configPath)} isn't valid JSONC; skipped workflow.subscriptionOnly pin`;
+  }
+
+  if ("workflow" in parsed) return null; // deliberate config; never touch
+
+  const at = firstBraceIndex(raw);
+  if (at < 0) return `· ${rel(configPath)} has no object literal; skipped workflow pin`;
+  const keys = Object.keys(parsed);
+  const next =
+    keys.length === 0
+      ? `{\n${WORKFLOW_DEFAULT_BLOCK}\n}\n`
+      : `${raw.slice(0, at + 1)}\n${WORKFLOW_DEFAULT_BLOCK},${raw.slice(at + 1)}`;
+  if (dryRun) return `+ would pin workflow.subscriptionOnly in ${rel(configPath)}`;
+  writeFileSync(configPath, next);
+  return `+ pinned workflow.subscriptionOnly: true in ${rel(configPath)}`;
+}
+
 /** Index of the first structural `{`, skipping leading whitespace + comments. */
 function firstBraceIndex(raw: string): number {
   let i = 0;

package/src/commands/workflow.ts

@@ -0,0 +1,132 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import { workflowSubscriptionOnly } from "../core/config.ts";
+import { findCoordRoot } from "../core/hooks/resolve/coord-root.ts";
+
+/**
+ * `workflow run <script>`: execute a workflow script — bounded, schema-gated,
+ * conditionally-routed stages fanning out to headless harness-CLI subagents.
+ * The script (deterministic code), not a model, decides routing between
+ * stages, and the run terminates when the script returns.
+ *
+ * Phase 2 surface: `run` only, claude-code spawn adapter only. Design +
+ * phasing: decision 0015.
+ */
+
+interface WorkflowRunOpts {
+  maxAgents?: string;
+  concurrency?: string;
+  cwd?: string;
+  harness?: string;
+  resumeFrom?: string;
+  subscriptionOnly?: boolean;
+  allowApiBilling?: boolean;
+  json?: boolean;
+}
+
+const HARNESSES = ["claude-code", "codex", "cursor"] as const;
+
+export function registerWorkflowCommand(program: Command, emit: EmitContext): void {
+  const workflow = program
+    .command("workflow")
+    .description("Run bounded, schema-gated multi-subagent workflow scripts.");
+
+  workflow
+    .command("run <script>")
+    .description(
+      "Execute a workflow script (plain JS: `export default async ({agent, parallel, stage, log}) => …`). " +
+        "Subagents spawn as headless harness-CLI subprocesses, coordination-registered.",
+    )
+    .option("--max-agents <n>", "Total-agent ceiling for the run (default 50)")
+    .option("--concurrency <n>", "Concurrent-subagent cap (default 4)")
+    .option("--cwd <dir>", "Working directory children spawn in (default: coord root)")
+    .option(
+      "--harness <name>",
+      `Default harness for agent() calls: ${HARNESSES.join(" | ")} (default claude-code); scripts can override per agent via opts.harness`,
+    )
+    .option(
+      "--resume-from <run-id>",
+      "Reuse completed agent results from a prior run's journal; only changed/failed calls re-run",
+    )
+    .option(
+      "--subscription-only",
+      "Guarantee subscription billing: scrub API-key vars from child envs; fail loud when a " +
+        "harness has no stored login (repo default via config.jsonc workflow.subscriptionOnly)",
+    )
+    .option(
+      "--allow-api-billing",
+      "Permit an exported API key to override a stored subscription login (per-token billing); " +
+        "without this the engine refuses that silent-override state",
+    )
+    .option("--json", "Emit the full RunReport as JSON")
+    .action(async (script: string, opts: WorkflowRunOpts) => {
+      const coordRoot = findCoordRoot();
+      if (!coordRoot) {
+        emit.error({
+          code: "no_coord_root",
+          message: "no .harnery/ coordination root found; run `init` first",
+        });
+        process.exit(1);
+      }
+      if (opts.harness && !HARNESSES.includes(opts.harness as (typeof HARNESSES)[number])) {
+        emit.error({
+          code: "bad_harness",
+          message: `unknown harness "${opts.harness}" (expected: ${HARNESSES.join(" | ")})`,
+        });
+        process.exit(1);
+      }
+      // Flag beats config; the two flags contradict each other by design.
+      const subscriptionOnly = opts.subscriptionOnly || workflowSubscriptionOnly(coordRoot);
+      if (subscriptionOnly && opts.allowApiBilling) {
+        emit.error({
+          code: "billing_flags_conflict",
+          message:
+            "--allow-api-billing contradicts subscription-only mode " +
+            "(flag or config.jsonc workflow.subscriptionOnly); pick one",
+        });
+        process.exit(1);
+      }
+      try {
+        const [{ runWorkflow }, { claudeCodeSpawner }, { codexSpawner }, { cursorSpawner }] =
+          await Promise.all([
+            import("../core/workflow/engine.ts"),
+            import("../core/workflow/spawn-claude.ts"),
+            import("../core/workflow/spawn-codex.ts"),
+            import("../core/workflow/spawn-cursor.ts"),
+          ]);
+        const report = await runWorkflow(script, {
+          coordRoot,
+          spawners: {
+            "claude-code": claudeCodeSpawner,
+            codex: codexSpawner,
+            cursor: cursorSpawner,
+          },
+          defaultHarness: opts.harness as "claude-code" | "codex" | "cursor" | undefined,
+          resumeFrom: opts.resumeFrom,
+          subscriptionOnly,
+          allowApiBilling: opts.allowApiBilling,
+          maxAgents: opts.maxAgents ? Number.parseInt(opts.maxAgents, 10) : undefined,
+          concurrency: opts.concurrency ? Number.parseInt(opts.concurrency, 10) : undefined,
+          cwd: opts.cwd,
+        });
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(report);
+          return;
+        }
+        const cachedPart = report.agentsCached > 0 ? ` (+${report.agentsCached} cached)` : "";
+        const billingPart = report.billing.length
+          ? `billing: ${report.billing.map((b) => `${b.harness}=${b.mode}`).join(", ")}\n`
+          : "";
+        emit.text(
+          `run ${report.runId} (${report.name}) finished: ${report.agentsSpawned} agent(s)${cachedPart}, ` +
+            `$${report.costUsd.toFixed(4)}, ${Math.round(report.durationMs / 1000)}s\n${billingPart}` +
+            `journal: ${report.journalPath}\n` +
+            `result: ${typeof report.result === "string" ? report.result : JSON.stringify(report.result, null, 2)}\n`,
+        );
+      } catch (err) {
+        emit.error({ code: "workflow_failed", message: (err as Error).message });
+        process.exit(1);
+      }
+    });
+}

package/src/core/agents/cli.ts

@@ -176,7 +176,7 @@ async function emitClaimRelease(
   owner: string,
   hb: { session_id?: string; platform?: string },
   path: string,
-  reason: "explicit" | "heal",
+  reason: "explicit" | "heal" | "commit" | "checkout",
 ): Promise<void> {
   try {
     const { emit } = await import("./events/emit.ts");
@@ -475,11 +475,16 @@ async function handlePostCommit(root: string): Promise<number> {
   const { groupUnclaim } = await import("./state/heartbeat-writer.ts");
 
   // Session-group-wide unclaim. `owner` is the parent's session_id which is
-  // also the group key (parent + subagents share session_id).
+  // also the group key (parent + subagents share session_id). Each actual
+  // removal also emits a durable claim.release event — the projector rebuilds
+  // files_touched from the permanent Edit/Write events, so a file-only prune
+  // would resurrect on the next replay.
   if (req.owner && Array.isArray(req.prune)) {
     for (const path of req.prune) {
       try {
-        groupUnclaim(root, req.owner, path);
+        for (const hit of groupUnclaim(root, req.owner, path)) {
+          await emitClaimRelease(root, hit.instance_id, hit, path, "commit");
+        }
       } catch {
         /* best-effort */
       }
@@ -500,7 +505,9 @@ async function handlePostCheckout(root: string, _rest: string[]): Promise<number
   if (req.owner && Array.isArray(req.removed)) {
     for (const path of req.removed) {
       try {
-        groupUnclaim(root, req.owner, path);
+        for (const hit of groupUnclaim(root, req.owner, path)) {
+          await emitClaimRelease(root, hit.instance_id, hit, path, "checkout");
+        }
       } catch {
         /* best-effort */
       }

package/src/core/agents/rules/claim-conflict.ts

@@ -17,6 +17,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { emit } from "../events/emit.ts";
 
 const FRESHNESS_SECS = 600;
 
@@ -306,12 +307,36 @@ function pruneClaimFromPeer(coordRoot: string, instanceId: string, relPath: stri
   try {
     const body = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
     const files = (body.files_touched as string[] | undefined) ?? [];
-    const next = files.filter((p) => p !== relPath);
+    // Normalize both sides: files_touched can hold absolute-under-coordRoot
+    // entries (legacy projections) as well as canonical relative ones — an
+    // exact-string filter silently no-ops on the mixed-form case and the
+    // stale claim never heals.
+    const norm = (p: string): string =>
+      p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p;
+    const target = norm(relPath);
+    const next = files.filter((p) => norm(p) !== target);
     if (next.length === files.length) return;
     body.files_touched = next;
     const tmp = `${path}.tmp.${process.pid}`;
     writeFileSync(tmp, JSON.stringify(body, null, 2), "utf8");
     renameSync(tmp, path);
+    // Durable subtraction: the projector rebuilds files_touched from the
+    // permanent Edit/Write events, so a file-only prune resurrects on the
+    // next replay. Soft-fail — the heartbeat write already landed.
+    try {
+      const platform = body.platform as string | undefined;
+      emit(coordRoot, {
+        event_type: "claim.release",
+        instance_id: instanceId,
+        session_id: (body.session_id as string | undefined) ?? instanceId,
+        harness: platform === "cursor" ? "cursor" : platform === "codex" ? "codex" : "claude-code",
+        source: "agent-coord",
+        data: { path: target, reason: "heal" },
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      } as Parameters<typeof emit>[1]);
+    } catch {
+      /* soft-fail */
+    }
   } catch {
     /* silent */
   }

package/src/core/agents/rules/stop-hook.ts

@@ -49,6 +49,14 @@ export interface StopHookRequest {
   turn_window?: { start_ms: number; end_ms: number };
   /** Bypass switch: operator escape hatch identical to HARNERY_AGENT_COORD_BYPASS_STOP. */
   bypass?: boolean;
+  /** Headless child spawned by `harn workflow` (HARNERY_WORKFLOW_CHILD=1).
+   * The end-of-turn ritual exists to surface status to a HUMAN reader; a
+   * workflow child reports to the engine's journal instead, so the ritual is
+   * meaningless there — worse, blocking burns the child's turn budget on
+   * re-prompts (observed as error_max_turns in the Phase 1 spike). Exempting
+   * here, rather than disabling the child's hooks wholesale, keeps heartbeat +
+   * event capture on: the child stays visible to peers and the coord layer. */
+  workflow_child?: boolean;
 }
 
 /**
@@ -95,6 +103,15 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
     };
   }
 
+  if (req.workflow_child) {
+    return {
+      allow: true,
+      exit_code: 0,
+      rule: "stop-hook.workflow_child",
+      reason: "HARNERY_WORKFLOW_CHILD=1: headless workflow child; ritual not applicable",
+    };
+  }
+
   let events: CanonicalEvent[];
   try {
     events = readRecentEvents(coordRoot, RECENT_EVENT_WINDOW_LINES);

package/src/core/agents/state/heartbeat-projector.ts

@@ -24,6 +24,8 @@ export interface V2Heartbeat {
   platform?: string;
   subagent_call_id?: string;
   parent_session_id?: string;
+  /** Set iff this owner is a `workflow run` child (joins to the run journal). */
+  workflow_run_id?: string;
   started_at?: string;
   last_heartbeat: string;
   last_tool?: string;
@@ -184,6 +186,8 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
         if (subagentCallId) hb.subagent_call_id = subagentCallId;
         const parentSession = pickStr(d, "parent_session_id");
         if (parentSession) hb.parent_session_id = parentSession;
+        const workflowRunId = pickStr(d, "workflow_run_id");
+        if (workflowRunId) hb.workflow_run_id = workflowRunId;
         if (!hb.files_touched) hb.files_touched = [];
       }
       break;
@@ -248,8 +252,15 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
       if (toolName === "Edit" || toolName === "Write" || toolName === "NotebookEdit") {
         const target = extractFilePath(d);
         if (target) {
+          // Canonicalize to repo-relative before storing: the claim guard
+          // writes canonical paths directly, so an absolute entry here would
+          // double-count the same file (inflated "N files" display) and
+          // defeat exact-match pruning on commit.
+          const canonical = target.startsWith(`${coordRoot}/`)
+            ? target.slice(coordRoot.length + 1)
+            : target;
           if (!hb.files_touched) hb.files_touched = [];
-          if (!hb.files_touched.includes(target)) hb.files_touched.push(target);
+          if (!hb.files_touched.includes(canonical)) hb.files_touched.push(canonical);
         }
       }
       break;
@@ -437,6 +448,7 @@ function writeHeartbeat(coordRoot: string, instanceId: string, hb: V2Heartbeat):
     setIfDefined(merged, "kind", hb.kind);
     setIfDefined(merged, "agent_id", hb.agent_id);
     setIfDefined(merged, "subagent_call_id", hb.subagent_call_id);
+    setIfDefined(merged, "workflow_run_id", hb.workflow_run_id);
     setIfDefined(merged, "model", hb.model);
     setIfDefined(merged, "platform", hb.platform);
     setIfDefined(merged, "started_at", hb.started_at);

package/src/core/agents/state/heartbeat-writer.ts

@@ -184,20 +184,39 @@ export function releaseClaim(
   }));
 }
 
+/** A heartbeat that actually dropped a path during a group unclaim. */
+export interface GroupUnclaimHit {
+  instance_id: string;
+  session_id?: string;
+  platform?: string;
+}
+
 /**
  * Session-group-wide unclaim. Walks every heartbeat sharing `groupId`
  * (parent's session_id == group_id;
  * subagents inherit it) and removes the path from each one's files_touched.
- * Idempotent: heartbeats that don't hold the path are untouched.
+ * Idempotent: heartbeats that don't hold the path are untouched. Returns the
+ * heartbeats that actually dropped the path so the caller can emit the
+ * durable `claim.release` events — a file-only prune is silently reverted by
+ * the next projector replay.
+ *
+ * files_touched can hold either absolute-under-coordRoot or canonical
+ * repo-relative entries (legacy projections stored the raw tool_input path),
+ * so both sides are normalized before comparing — an exact-string match
+ * silently no-ops on the mixed-form case and the claim never releases.
  *
  * This is the Option B fix for post-commit's pid-map attribution hole: a
  * subagent-held claim that doesn't live on the parent's heartbeat still gets
  * pruned because the walk covers the whole group.
  */
-export function groupUnclaim(coordRoot: string, groupId: string, path: string): void {
-  if (!groupId || !path) return;
+export function groupUnclaim(coordRoot: string, groupId: string, path: string): GroupUnclaimHit[] {
+  const hits: GroupUnclaimHit[] = [];
+  if (!groupId || !path) return hits;
   const activeDir = join(coordRoot, ".harnery", "active");
-  if (!existsSync(activeDir)) return;
+  if (!existsSync(activeDir)) return hits;
+  const norm = (p: string): string =>
+    p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p;
+  const target = norm(path);
   for (const f of readdirSync(activeDir)) {
     if (!f.endsWith(".json")) continue;
     const hbPath = join(activeDir, f);
@@ -211,17 +230,23 @@ export function groupUnclaim(coordRoot: string, groupId: string, path: string):
       (body.session_id as string | undefined) ?? (body.instance_id as string | undefined);
     if (peerSession !== groupId) continue;
     const files = (body.files_touched as string[] | undefined) ?? [];
-    const next = files.filter((p) => p !== path);
+    const next = files.filter((p) => norm(p) !== target);
     if (next.length === files.length) continue;
     body.files_touched = next;
     try {
       const tmp = `${hbPath}.tmp.${process.pid}`;
       writeFileSync(tmp, JSON.stringify(body, null, 2), "utf8");
       renameSync(tmp, hbPath);
+      hits.push({
+        instance_id: (body.instance_id as string | undefined) ?? f.replace(/\.json$/, ""),
+        session_id: body.session_id as string | undefined,
+        platform: body.platform as string | undefined,
+      });
     } catch {
       /* silent */
     }
   }
+  return hits;
 }
 
 export function killHeartbeat(coordRoot: string, instanceId: string): boolean {

package/src/core/config.ts

@@ -33,6 +33,19 @@ interface HarneryConfig {
    * declares it here (e.g. "scripts/setup-hooks.sh"). Unset → a generic hint.
    */
   hooksSetupHint?: string;
+  /**
+   * Managed-tool provisioning consent. `{ ripgrep: { autoInstall: true } }`
+   * lets `grep` download the pinned, checksum-verified ripgrep into the
+   * harnery tools dir on first miss. Committed by a host repo once; absent →
+   * a missing rg only produces a rate-limited install hint.
+   */
+  tools?: { ripgrep?: { autoInstall?: boolean } };
+  /**
+   * Workflow-engine defaults. `{ subscriptionOnly: true }` pins every
+   * `workflow run` in this repo to subscription billing (API-key vars are
+   * scrubbed from child envs) without anyone having to remember the flag.
+   */
+  workflow?: { subscriptionOnly?: boolean };
   [k: string]: unknown;
 }
 
@@ -144,3 +157,37 @@ export function resolveHooksSetupHint(coordRoot?: string | null): string | null
   const hint = readConfig(root).hooksSetupHint;
   return typeof hint === "string" && hint.trim() ? hint.trim() : null;
 }
+
+/**
+ * Whether the host project consented to automatic ripgrep provisioning:
+ * `.harnery/config.jsonc` `{ "tools": { "ripgrep": { "autoInstall": true } } }`.
+ * A repo commits that once and every clone self-heals on first `grep`; without
+ * it, a missing rg only produces a rate-limited hint (`doctor --fix` installs
+ * explicitly). `HARNERY_TOOLS_AUTOINSTALL=1|0` overrides per process.
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export function ripgrepAutoInstall(coordRoot?: string | null): boolean {
+  const env = coordEnv("TOOLS_AUTOINSTALL");
+  if (env === "1") return true;
+  if (env === "0") return false;
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return false;
+  return readConfig(root).tools?.ripgrep?.autoInstall === true;
+}
+
+/**
+ * Whether this repo pins workflow runs to subscription billing:
+ * `.harnery/config.jsonc` `{ "workflow": { "subscriptionOnly": true } }`.
+ * The `workflow run --subscription-only` flag turns it on per invocation;
+ * `HARNERY_WORKFLOW_SUBSCRIPTION_ONLY=1|0` overrides per process (the `0`
+ * escape hatch exists for a key-only CI job inside a pinned repo).
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export function workflowSubscriptionOnly(coordRoot?: string | null): boolean {
+  const env = coordEnv("WORKFLOW_SUBSCRIPTION_ONLY");
+  if (env === "1") return true;
+  if (env === "0") return false;
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return false;
+  return readConfig(root).workflow?.subscriptionOnly === true;
+}