harnery 0.8.0 → 0.10.0

package/src/commands/sync.ts

@@ -25,6 +25,7 @@ import os from "node:os";
 import path from "node:path";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
+import { syncJsoncConfig } from "../core/config.ts";
 
 // What we sync. Anything matching one of these (relative to .harnery/) is
 // considered part of the sync set. Everything else stays local-only.
@@ -40,9 +41,12 @@ function configPath(): string {
 }
 
 function loadConfig(): SyncConfig | null {
+  // Precedence: env → .harnery/config.jsonc `sync` → ~/.config/harnery/sync.json.
   const envRemote = process.env.HARNERY_SYNC_REMOTE;
   const envPrefix = process.env.HARNERY_SYNC_PREFIX ?? "harnery";
   if (envRemote) return { remote: envRemote, prefix: envPrefix };
+  const jsonc = syncJsoncConfig();
+  if (jsonc) return jsonc;
   const p = configPath();
   if (!existsSync(p)) return null;
   try {

package/src/commands/workflow.ts

@@ -0,0 +1,123 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import { workflowSubscriptionOnly } from "../core/config.ts";
+import { createBuiltinHarnessRegistry } from "../core/harnesses/index.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;
+}
+
+export function registerWorkflowCommand(program: Command, emit: EmitContext): void {
+  const registry = createBuiltinHarnessRegistry();
+  const harnesses = registry.ids();
+  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 && !registry.get(opts.harness)) {
+        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 } = await import("../core/workflow/engine.ts");
+        const report = await runWorkflow(script, {
+          coordRoot,
+          spawners: registry.spawners(),
+          defaultHarness: opts.harness,
+          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/canonical-emit.ts

@@ -12,6 +12,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { monorepoRoot } from "./coord-client.ts";
 
 export interface CanonicalEmitInput {
   type: string;
@@ -24,8 +25,37 @@ export interface CanonicalEmitInput {
   parentTurnId?: string;
 }
 
+/**
+ * Resolve the coord root for a canonical emit.
+ *
+ * Order: explicit `HARNERY_COORD_ROOT_OVERRIDE` → git-superproject-aware
+ * `monorepoRoot()` (must actually carry `.harnery/`) → cwd walk (non-git
+ * hosts). The git-aware step is load-bearing: a shell cd'd into a nested
+ * directory that carries its own `.harnery/` (e.g. an embedded harnery
+ * checkout) made the old cwd-walk resolve the NESTED root, from which
+ * `<root>/harnery/bin/agent-coord` doesn't exist — so `agents status` /
+ * `set-task` emits silently vanished and the Stop-hook's rule 1/3
+ * (`state.status_checked` in-turn) blocked turns that had done the ritual.
+ * Same bug class as the coordHelperOpts root-pin fix; this closes the
+ * emitCanonical instance of it.
+ */
+export function resolveEmitRoot(start: string = process.cwd()): string | null {
+  const override = process.env.HARNERY_COORD_ROOT_OVERRIDE;
+  if (override) return override;
+  // Memoized per start-dir: the session-tee middleware resolves once per
+  // emitted event, and monorepoRoot() spawns git — cache so a streaming
+  // command doesn't pay 1-3 subprocess spawns per output line.
+  if (cachedRoot && cachedRoot.start === start) return cachedRoot.root;
+  const gitRoot = monorepoRoot();
+  const root = gitRoot && existsSync(join(gitRoot, ".harnery")) ? gitRoot : findRepoRoot(start);
+  cachedRoot = { start, root };
+  return root;
+}
+
+let cachedRoot: { start: string; root: string | null } | undefined;
+
 export function emitCanonical(input: CanonicalEmitInput): void {
-  const root = findRepoRoot();
+  const root = resolveEmitRoot();
   if (!root) return;
   const binary = resolve(root, "harnery", "bin", "agent-coord");
   if (!existsSync(binary)) return;
@@ -46,11 +76,19 @@ export function emitCanonical(input: CanonicalEmitInput): void {
     if (input.turnId) args.push("--turn-id", input.turnId);
     if (input.parentSessionId) args.push("--parent-session-id", input.parentSessionId);
     if (input.parentTurnId) args.push("--parent-turn-id", input.parentTurnId);
-    spawnSync(binary, args, {
+    // Pin cwd + HARNERY_COORD_ROOT_OVERRIDE so the child writes to the SAME
+    // stream we resolved, regardless of where the caller's shell is cd'd.
+    const result = spawnSync(binary, args, {
       encoding: "utf8",
       stdio: "ignore",
       timeout: 3000,
+      cwd: root,
+      env: { ...process.env, HARNERY_COORD_ROOT_OVERRIDE: root },
     });
+    if (result.error || result.status !== 0) {
+      const why = result.error ? result.error.message : `exit ${result.status}`;
+      process.stderr.write(`emitCanonical: ${input.type} emit failed (${why})\n`); // lint-ok-emission: soft-fail diagnostic promised by the module doc; silent drops cost blocked turns
+    }
   } catch {
     /* never break the caller */
   }
@@ -66,7 +104,7 @@ export function normalizeHarness(platform: string | undefined): "claude-code" |
   return "claude-code";
 }
 
-function findRepoRoot(start: string = process.cwd()): string | null {
+function findRepoRoot(start: string): string | null {
   let dir = resolve(start);
   while (true) {
     if (existsSync(join(dir, ".harnery"))) return dir;

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");
@@ -210,8 +210,10 @@ async function handleStateAction(root: string, action: string, rest: string[]):
       const task = args.join(" ");
       const hb = writer.setTask(root, owner, task);
       if (!hb) {
+        // Name the RESOLVED root: when a nested .harnery/ shadows the real
+        // coordination home, the full path is what makes that diagnosable.
         process.stderr.write(
-          `agent-coord set-task: no heartbeat at .harnery/active/${owner}.json\n`,
+          `agent-coord set-task: no heartbeat at ${root}/.harnery/active/${owner}.json\n`,
         );
         return 1;
       }
@@ -475,11 +477,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 +507,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 */
       }
@@ -709,7 +718,7 @@ async function handleResolveName(root: string, rest: string[]): Promise<number>
     return 0;
   }
   process.stdout.write(
-    `${JSON.stringify({ instance_id: owner, name: resolved.name, kind: resolved.kind })}\n`,
+    `${JSON.stringify({ instance_id: owner, name: resolved.name, kind: resolved.kind, agent_id: resolved.agent_id ?? null })}\n`,
   );
   return 0;
 }

package/src/core/agents/render/prompt-context.ts

@@ -36,6 +36,7 @@ import {
 import { join } from "node:path";
 
 import { coordEnv } from "../../../lib/env.ts";
+import { type RemoteMachine, readRemoteMachines } from "../../presence/index.ts";
 import { formatPendingCouncils } from "./session-context.ts";
 
 interface HeartbeatRow {
@@ -170,7 +171,10 @@ function computePeerTableIfChanged(
     if (!hb?.instance_id || hb.instance_id === selfInstanceId) continue;
     peers.push(hb);
   }
-  if (peers.length === 0) return "";
+  // Cross-machine presence (ADR 0016): sessions on other machines, from the
+  // locally-fetched presence refs. Advisory (no claim blocking in v1).
+  const remote = readRemoteMachinesSafe(coordRoot);
+  if (peers.length === 0 && remote.length === 0) return "";
 
   // Build hash basis: sorted-by-instance_id projection of semantically-relevant fields.
   const basis = peers
@@ -184,14 +188,27 @@ function computePeerTableIfChanged(
       platform: p.platform ?? null,
     }))
     .sort((a, b) => (a.instance_id ?? "").localeCompare(b.instance_id ?? ""));
-  const newHash = sha256Hex16(JSON.stringify(basis));
+  // Remote basis: machine + per-agent identity/task/files (published_at is
+  // excluded — a keepalive re-publish alone shouldn't re-emit the table).
+  const remoteBasis = remote.map((m) => ({
+    machine: m.machine,
+    agents: m.agents.map((a) => ({
+      instance_id: a.instance_id,
+      name: a.name ?? null,
+      task: a.task ?? null,
+      files_touched: Array.from(a.files_touched ?? []).sort(),
+    })),
+  }));
+  const newHash = sha256Hex16(JSON.stringify({ local: basis, remote: remoteBasis }));
 
   const hashFile = join(coordRoot, ".harnery", `.last-peer-hash.${selfInstanceId}`);
   const oldHash = safeRead(hashFile);
   if (oldHash && oldHash === newHash) return "";
 
   // Render peer table via the same formatter used at SessionStart.
-  const table = formatPeerTable(peers, mySessionId);
+  const local = formatPeerTable(peers, mySessionId);
+  const remoteTable = formatRemoteTable(remote);
+  const table = [local, remoteTable].filter(Boolean).join("\n\n");
   if (!table) return "";
 
   // Persist hash atomically (temp + rename, same convention as other coord writes).
@@ -199,6 +216,34 @@ function computePeerTableIfChanged(
   return table;
 }
 
+/** readRemoteMachines with a local failure guard (rendering must never throw). */
+function readRemoteMachinesSafe(coordRoot: string): RemoteMachine[] {
+  try {
+    return readRemoteMachines(coordRoot);
+  } catch {
+    return [];
+  }
+}
+
+/** Render sessions on other machines (presence transport) as a subtable. */
+function formatRemoteTable(remote: RemoteMachine[]): string {
+  if (remote.length === 0) return "";
+  const nowSec = Math.floor(Date.now() / 1000);
+  const lines: string[] = [];
+  for (const m of remote) {
+    for (const a of m.agents.slice(0, 10)) {
+      lines.push(
+        formatRow(
+          { ...a, display_files: Array.from(a.files_touched ?? []).sort() },
+          nowSec,
+        ).replace(/^ {2}- (agent-[^ ]+)/, `  - $1 @${m.machine}`),
+      );
+    }
+  }
+  if (lines.length === 0) return "";
+  return `Sessions on other machines (advisory, via presence refs):\n${lines.join("\n")}`;
+}
+
 function computeCouncilPendingIfChanged(
   coordRoot: string,
   selfInstanceId: string,

package/src/core/agents/render/session-context.ts

@@ -12,6 +12,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { resolveBinName, resolveHooksSetupHint } from "../../config.ts";
 import { harneryVersion, loadHarnessWiring } from "../../hooks/harness/wiring.ts";
+import { readRemoteMachines } from "../../presence/index.ts";
 
 interface HeartbeatRow {
   instance_id?: string;
@@ -48,7 +49,9 @@ export function renderSessionContext(opts: RenderOpts): string {
 
   // 1. Self-name line + peer table (folded if peers present)
   const peers = readActivePeers(coordRoot, instanceId);
-  const peerTable = formatPeerTable(peers, sessionId);
+  const localTable = formatPeerTable(peers, sessionId);
+  // Cross-machine presence (ADR 0016): sessions on other machines (advisory).
+  const peerTable = [localTable, formatRemoteMachines(coordRoot)].filter(Boolean).join("\n\n");
   if (agentName) {
     const suffix = platformLabel ? ` (${platformLabel})` : "";
     const selfLine = `You are agent-${agentName}${suffix}.`;
@@ -107,6 +110,29 @@ export function renderSessionContext(opts: RenderOpts): string {
   return messages.join("\n\n");
 }
 
+/** One-line-per-agent view of sessions on other machines (presence refs). */
+function formatRemoteMachines(coordRoot: string): string {
+  try {
+    const remote = readRemoteMachines(coordRoot);
+    if (remote.length === 0) return "";
+    const lines: string[] = [];
+    for (const m of remote) {
+      for (const a of m.agents.slice(0, 10)) {
+        const task = a.task ? ` "${a.task.slice(0, 60)}"` : "";
+        const files = a.files_touched?.length
+          ? `holds: ${a.files_touched.slice(0, 3).join(", ")}${a.files_touched.length > 3 ? `, +${a.files_touched.length - 3} more` : ""}`
+          : "nothing held";
+        lines.push(
+          `  - agent-${a.name ?? a.instance_id.slice(0, 8)} @${m.machine}${task} (${files})`,
+        );
+      }
+    }
+    return `Sessions on other machines (advisory, via presence refs):\n${lines.join("\n")}`;
+  } catch {
+    return "";
+  }
+}
+
 /** Read all peer heartbeats from .harnery/active/, excluding self. */
 function readActivePeers(coordRoot: string, selfInstanceId: string): HeartbeatRow[] {
   const out: HeartbeatRow[] = [];

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/commit-conflict.ts

@@ -23,9 +23,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { coordEnv } from "../../../lib/env.ts";
-
-const DEFAULT_FRESHNESS_SECS = 600;
+import { coordFreshnessSeconds } from "../../config.ts";
+import { instanceHasLivePid } from "../state/pidmap.ts";
 
 interface PeerHeartbeat {
   instance_id: string;
@@ -86,7 +85,7 @@ export function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): Co
   }
 
   const peers = readActivePeers(coordRoot);
-  const cutoffMs = Date.now() - freshnessSecs() * 1000;
+  const cutoffMs = Date.now() - coordFreshnessSeconds(coordRoot) * 1000;
   const stagedSet = new Set(req.staged_paths);
   const gitlinkSet = new Set(req.staged_gitlinks ?? []);
 
@@ -233,28 +232,7 @@ function isHolderSelfAttributed(
 }
 
 function holderHasLiveForeignPid(coordRoot: string, holderId: string): boolean {
-  const dir = join(coordRoot, ".harnery", "pid-map");
-  if (!existsSync(dir)) return false;
-  for (const f of readdirSync(dir)) {
-    let row = "";
-    try {
-      row = readFileSync(join(dir, f), "utf8").trim();
-    } catch {
-      continue;
-    }
-    const owner = row.split("\t")[0]?.trim() ?? "";
-    if (owner !== holderId) continue;
-    // Process still alive?
-    const pid = Number.parseInt(f, 10);
-    if (!Number.isFinite(pid)) continue;
-    try {
-      process.kill(pid, 0); // signal 0 = liveness probe
-      return true; // live foreign pid found
-    } catch {
-      // ESRCH (no such process): pid-map entry is stale, skip
-    }
-  }
-  return false;
+  return instanceHasLivePid(coordRoot, holderId);
 }
 
 function isPathCleanInHead(coordRoot: string, relPath: string): boolean {
@@ -290,13 +268,6 @@ function readActivePeers(coordRoot: string): PeerHeartbeat[] {
   return out;
 }
 
-function freshnessSecs(): number {
-  const raw = coordEnv("AGENT_FRESHNESS");
-  if (!raw) return DEFAULT_FRESHNESS_SECS;
-  const n = Number.parseInt(raw, 10);
-  return Number.isFinite(n) && n > 0 ? n : DEFAULT_FRESHNESS_SECS;
-}
-
 function shortName(peer: PeerHeartbeat): string {
   if (peer.name && peer.name.length > 0) return `agent-${peer.name}`;
   return `agent-${peer.instance_id.slice(0, 8)}`;

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/session-events.ts

@@ -9,10 +9,10 @@
  */
 
 import { randomBytes } from "node:crypto";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 // Kept dependency-light: vendored verbatim into a downstream consumer, so no coordEnv import.
-import { normalizeHarness } from "./canonical-emit.ts";
+import { normalizeHarness, resolveEmitRoot } from "./canonical-emit.ts";
 import { emit } from "./events/emit.ts";
 
 /** Event types accepted by `writeSessionEvent`. Only the command stream +
@@ -38,25 +38,14 @@ export function sessionEventsPath(): string {
   // Explicit override (tests + non-monorepo invocations).
   const explicit = process.env.HARNERY_OUTPUT_SESSION_EVENTS;
   if (explicit) return explicit;
-  // Walk up looking for an EXISTING .harnery/ directory; only match dirs
-  // (submodule .git is a file/gitlink, and CLAUDE.md / AGENTS.md can
-  // proliferate per-subdirectory in many monorepos, so neither is a safe
-  // anchor). Don't reintroduce CLAUDE.md / .git as anchors, which creates
+  // Superproject-aware root resolution (git first, cwd walk fallback) via
+  // resolveEmitRoot. A plain cwd walk here mis-anchored to a NESTED
+  // `.harnery/` when the shell sat inside a submodule carrying its own
+  // (e.g. an embedded harnery checkout), silently splitting the event
+  // stream. Don't reintroduce CLAUDE.md / .git as anchors, which creates
   // stray .harnery/ dirs under submodule subtrees.
-  let dir = process.cwd();
-  for (let i = 0; i < 10; i++) {
-    const candidate = resolve(dir, ".harnery");
-    try {
-      if (existsSync(candidate) && statSync(candidate).isDirectory()) {
-        return resolve(candidate, "session-events.ndjson");
-      }
-    } catch {
-      /* keep walking */
-    }
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
+  const root = resolveEmitRoot();
+  if (root) return resolve(root, ".harnery", "session-events.ndjson");
   return resolve(process.env.HOME || "/tmp", ".harnery", "session-events.ndjson");
 }
 
@@ -75,25 +64,12 @@ export function newCmdId(): string {
  */
 export function readLastIntent(instanceId?: string): string | null {
   if (!instanceId) return null;
-  // Walk up from cwd looking for .harnery/, same resolution as
-  // sessionEventsPath() (only match existing directories).
-  let dir = process.cwd();
-  let agentsDir: string | null = null;
-  for (let i = 0; i < 10; i++) {
-    const candidate = resolve(dir, ".harnery");
-    try {
-      if (existsSync(candidate) && statSync(candidate).isDirectory()) {
-        agentsDir = candidate;
-        break;
-      }
-    } catch {
-      /* keep walking */
-    }
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  if (!agentsDir) return null;
+  // Same superproject-aware root resolution as sessionEventsPath(): the
+  // intent stamp is written by the PreToolUse hook into the SUPERPROJECT's
+  // .harnery/, so a nested-`.harnery/` cwd must not redirect the read.
+  const root = resolveEmitRoot();
+  if (!root) return null;
+  const agentsDir = resolve(root, ".harnery");
   const intentPath = resolve(agentsDir, `.last-intent.${instanceId}`);
   if (!existsSync(intentPath)) return null;
   try {