harnery 0.8.0 → 0.9.0

package/src/core/hooks/cli.ts

@@ -94,6 +94,17 @@ async function readStdin(): Promise<string> {
   }
 }
 
+/**
+ * Env for child agent-coord spawns, with the coord root pinned. The hook
+ * process may be running with the session shell's cwd (inside a submodule or
+ * scratch dir), and agent-coord resolves its root from cwd unless overridden —
+ * without the pin a child could write state to a different .harnery than the
+ * one this hook resolved.
+ */
+function childEnv(coordRoot: string): NodeJS.ProcessEnv {
+  return { ...process.env, HARNERY_COORD_ROOT_OVERRIDE: coordRoot };
+}
+
 function appendDebug(coordRoot: string, entry: Record<string, unknown>): void {
   const path = join(coordRoot, ".harnery", "debug", "agent-hook.ndjson");
   try {
@@ -143,6 +154,7 @@ function assignNameViaAgentCoord(
     const result = spawnSync(binary, ["assign-name", instanceId, kind], {
       encoding: "utf8",
       timeout: 2000,
+      env: childEnv(coordRoot),
     });
     if (result.status !== 0 || !result.stdout) return null;
     const parsed = JSON.parse(result.stdout.trim()) as {
@@ -254,6 +266,12 @@ function buildEventData(
         name: assigned?.name,
         kind: "session",
         agent_id: ctx.instanceId,
+        // Workflow-child linkage: `workflow run` children carry the run id in
+        // env (spawn adapters set it via buildChildEnv), so their sessions and
+        // heartbeats join back to the run journal + /workflows web view.
+        ...(coordEnv("WORKFLOW_CHILD") === "1" && coordEnv("WORKFLOW_RUN_ID")
+          ? { workflow_run_id: coordEnv("WORKFLOW_RUN_ID") }
+          : {}),
       };
     }
 
@@ -519,7 +537,11 @@ async function main(): Promise<number> {
     try {
       const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
       if (existsSync(agentCoordBin)) {
-        spawnSync(agentCoordBin, ["project"], { encoding: "utf8", timeout: 3000 });
+        spawnSync(agentCoordBin, ["project"], {
+          encoding: "utf8",
+          timeout: 3000,
+          env: childEnv(coordRoot),
+        });
         spawnSync(
           agentCoordBin,
           [
@@ -528,7 +550,7 @@ async function main(): Promise<number> {
             "--instance",
             owner.instance_id,
           ],
-          { encoding: "utf8", timeout: 2000 },
+          { encoding: "utf8", timeout: 2000, env: childEnv(coordRoot) },
         );
       }
       emitSubagentStartContext(coordRoot, owner.instance_id, sessionId, data, harness);
@@ -551,7 +573,7 @@ async function main(): Promise<number> {
             "--instance",
             owner.instance_id,
           ],
-          { encoding: "utf8", timeout: 2000 },
+          { encoding: "utf8", timeout: 2000, env: childEnv(coordRoot) },
         );
       }
     } catch (err) {
@@ -632,6 +654,7 @@ async function main(): Promise<number> {
       session_id: sessionId,
       harness,
       bypass: coordEnv("AGENT_COORD_BYPASS_STOP") === "1",
+      workflow_child: coordEnv("WORKFLOW_CHILD") === "1",
     });
     if (!verdict.allow) {
       // Harness-aware enforcement channel: Claude Code / Codex honor exit-2 +
@@ -796,6 +819,7 @@ async function runPreToolUseGuard(
       input: verdictReq,
       encoding: "utf8",
       timeout: 3000,
+      env: childEnv(coordRoot),
     });
     if (result.status !== 0 || !result.stdout) continue;
     let parsed: { allow?: boolean; reason?: string } = {};
@@ -893,6 +917,7 @@ function healHeartbeatViaCli(
   spawnSync(agentCoordBin, ["heal-heartbeat", instanceId, sessionId, `--harness=${harness}`], {
     encoding: "utf8",
     timeout: 2000,
+    env: childEnv(coordRoot),
   });
 }
 
@@ -1000,6 +1025,7 @@ function stampToolActivity(
   spawnSync(agentCoordBin, ["stamp-tool-activity", instanceId, toolName, target], {
     encoding: "utf8",
     timeout: 2000,
+    env: childEnv(coordRoot),
   });
 }
 
@@ -1051,6 +1077,7 @@ function releaseClaimOnFailure(
   spawnSync(agentCoordBin, ["release-claim", instanceId, canonical], {
     encoding: "utf8",
     timeout: 2000,
+    env: childEnv(coordRoot),
   });
 }
 

package/src/core/hooks/events/schema.ts

@@ -47,6 +47,10 @@ export type SessionStart = EventEnvelope<
     cwd: string;
     model?: string;
     pid: number;
+    /** Present iff this session is a `workflow run` child: the run id whose
+     * journal owns it (child env HARNERY_WORKFLOW_RUN_ID). Optional-field
+     * addition per the schema evolution rules (minor bump). */
+    workflow_run_id?: string;
   }
 >;
 

package/src/core/hooks/harness/events.ts

@@ -40,6 +40,13 @@ export interface HarnessSpec {
   allowedTopLevelKeys?: string[];
   /** Strict hook event keys accepted by this harness, including events harnery does not wire. */
   allowedEventKeys?: string[];
+  /**
+   * Env var the harness exports to hook processes carrying the project root
+   * (e.g. Claude Code's CLAUDE_PROJECT_DIR). When set, `init` anchors the
+   * agent-hook path on it so the hook still spawns when the process cwd has
+   * wandered (the session shell `cd`ing into a subdirectory or off-repo).
+   */
+  projectDirEnv?: string;
 }
 
 /** Claude Code: `.claude/settings.json`. */
@@ -111,6 +118,7 @@ export const HARNESS_SPECS: Record<HarnessId, HarnessSpec> = {
     settingsFile: ".claude/settings.json",
     events: CLAUDE_CODE_EVENTS,
     entryShape: "claude",
+    projectDirEnv: "CLAUDE_PROJECT_DIR",
   },
   cursor: {
     settingsFile: ".cursor/hooks.json",

package/src/core/hooks/resolve/coord-root.ts

@@ -5,16 +5,38 @@ import { coordEnv } from "../../../lib/env.ts";
 /**
  * Walk up from `start` looking for a directory containing `.harnery/`. The
  * single coord-root resolution so every adapter agrees on the same root.
+ *
+ * Resolution precedence:
+ *   1. HARNERY_COORD_ROOT_OVERRIDE — explicit pin (tests, git hooks).
+ *   2. The harness's project dir (CLAUDE_PROJECT_DIR) — hook processes
+ *      inherit the session's *shell* cwd, which follows `cd` into
+ *      subdirectories/submodules that may carry a `.harnery/` of their own
+ *      (or none at all, e.g. a scratch dir under /tmp). The session's
+ *      coordination home is the project the harness opened, not wherever the
+ *      shell happens to sit, so a project dir that resolves to a coord root
+ *      wins over the cwd walk.
+ *   3. Walk up from `start` (default cwd).
  */
 export function findCoordRoot(start: string = process.cwd()): string | null {
-  // HARNERY_COORD_ROOT_OVERRIDE: test-mode escape hatch matched by agent-coord
-  // and the bash side. Lets the sandboxed coord-test suite run against a
-  // temp directory rather than the real monorepo root. agent-hook's
-  // session.start handler may be the FIRST thing to create .harnery/ in a
-  // fresh sandbox, so the override is honored unconditionally (we don't
-  // require .harnery/ to pre-exist).
+  // HARNERY_COORD_ROOT_OVERRIDE: explicit pin matched by agent-coord and the
+  // bash side. Lets the sandboxed coord-test suite run against a temp
+  // directory rather than the real monorepo root. agent-hook's session.start
+  // handler may be the FIRST thing to create .harnery/ in a fresh sandbox,
+  // so the override is honored unconditionally (we don't require .harnery/
+  // to pre-exist).
   const override = coordEnv("COORD_ROOT_OVERRIDE");
   if (override) return override;
+  // Claude Code exports CLAUDE_PROJECT_DIR to every hook process; other
+  // harnesses don't set it, so this is inert outside claude-code hooks.
+  const projectDir = process.env.CLAUDE_PROJECT_DIR;
+  if (projectDir) {
+    const fromProject = walkUp(projectDir);
+    if (fromProject) return fromProject;
+  }
+  return walkUp(start);
+}
+
+function walkUp(start: string): string | null {
   let dir = resolve(start);
   while (true) {
     if (existsSync(join(dir, ".harnery"))) return dir;

package/src/core/workflow/billing.ts

@@ -0,0 +1,146 @@
+/**
+ * Billing-mode probe: which auth a headless harness child will actually use.
+ *
+ * The engine never handles credentials — children are plain harness CLIs and
+ * authenticate however that CLI does. But the CLIs prefer an exported API key
+ * over a stored (subscription) login when both are present, and that override
+ * is almost always an accident: a sourced .env or a leftover export silently
+ * moves the run from subsidized subscription billing to per-token API billing.
+ * This probe classifies the state per harness so the engine can refuse the
+ * silent-override case (see decision 0015 addendum) while leaving deliberate
+ * key-only hosts (CI boxes with no login) working.
+ *
+ * Detection is a heuristic over well-known credential locations; when a
+ * location can't prove presence or absence (e.g. Claude Code stores its OAuth
+ * token in the macOS keychain, not a file), the state is "unknown" and the
+ * engine never hard-fails on it — the harness CLI itself is the final
+ * authority and will error loudly if truly unauthenticated.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { HarnessName } from "./types.ts";
+
+/** The env var each harness CLI reads as an API key (preferred over a stored
+ * login when set). Shared with the child-env builder's subscription-only
+ * scrub. */
+export const API_KEY_VARS: Record<HarnessName, string> = {
+  "claude-code": "ANTHROPIC_API_KEY",
+  codex: "OPENAI_API_KEY",
+  cursor: "CURSOR_API_KEY",
+};
+
+export type LoginState = "present" | "absent" | "unknown";
+
+export type BillingMode =
+  /** No API key exported; the child rides the stored (subscription) login. */
+  | "subscription"
+  /** API key present, no stored login detected: a deliberate key-only host. */
+  | "api-key"
+  /** API key present AND a stored login exists: the key silently overrides
+   * subsidized auth. The engine refuses this unless explicitly allowed. */
+  | "api-key-override";
+
+export interface BillingProbe {
+  harness: HarnessName;
+  /** The env var checked (from API_KEY_VARS), or a note when the key was
+   * found in a credential file instead of the environment. */
+  apiKeySource: string | null;
+  apiKeyPresent: boolean;
+  login: LoginState;
+  mode: BillingMode;
+}
+
+export interface ProbeIo {
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+}
+
+export type BillingProber = (harness: HarnessName) => BillingProbe;
+
+export function probeBilling(harness: HarnessName, io: ProbeIo = {}): BillingProbe {
+  const env = io.env ?? process.env;
+  const home = io.home ?? homedir();
+  const keyVar = API_KEY_VARS[harness];
+  const envKey = Boolean(env[keyVar]?.trim());
+
+  let login: LoginState;
+  let apiKeyPresent = envKey;
+  let apiKeySource: string | null = envKey ? keyVar : null;
+
+  switch (harness) {
+    case "claude-code":
+      login = probeClaudeLogin(home);
+      break;
+    case "codex": {
+      const codex = probeCodexAuth(env, home);
+      login = codex.login;
+      // `codex login --api-key` stores the key in auth.json rather than the
+      // env; that is still API-key billing and should surface as such.
+      if (!envKey && codex.storedApiKey) {
+        apiKeyPresent = true;
+        apiKeySource = codex.storedApiKeyNote;
+      }
+      break;
+    }
+    case "cursor":
+      // cursor-agent's stored-login location is not yet verified against a
+      // live install (adapter itself is pending verification); never claim
+      // presence or absence we can't prove.
+      login = "unknown";
+      break;
+  }
+
+  const mode: BillingMode =
+    apiKeyPresent && login === "present"
+      ? "api-key-override"
+      : apiKeyPresent
+        ? "api-key"
+        : "subscription";
+
+  return { harness, apiKeySource, apiKeyPresent, login, mode };
+}
+
+/** Claude Code: OAuth login lives at ~/.claude/.credentials.json on Linux;
+ * macOS stores it in the keychain (dir exists, file doesn't → unknown). */
+function probeClaudeLogin(home: string): LoginState {
+  const dir = join(home, ".claude");
+  const credFile = join(dir, ".credentials.json");
+  if (existsSync(credFile)) {
+    try {
+      const parsed = JSON.parse(readFileSync(credFile, "utf8")) as {
+        claudeAiOauth?: { accessToken?: string };
+      };
+      return parsed.claudeAiOauth?.accessToken ? "present" : "absent";
+    } catch {
+      return "unknown";
+    }
+  }
+  return existsSync(dir) ? "unknown" : "absent";
+}
+
+/** codex: auth lives at $CODEX_HOME/auth.json (default ~/.codex). A `tokens`
+ * object means a ChatGPT (subscription) login; an OPENAI_API_KEY field means
+ * a stored API key (`codex login --api-key`). */
+function probeCodexAuth(
+  env: NodeJS.ProcessEnv,
+  home: string,
+): { login: LoginState; storedApiKey: boolean; storedApiKeyNote: string } {
+  const authPath = join(env.CODEX_HOME?.trim() || join(home, ".codex"), "auth.json");
+  const storedApiKeyNote = `${authPath} (stored key)`;
+  if (!existsSync(authPath)) return { login: "absent", storedApiKey: false, storedApiKeyNote };
+  try {
+    const parsed = JSON.parse(readFileSync(authPath, "utf8")) as {
+      tokens?: unknown;
+      OPENAI_API_KEY?: string | null;
+    };
+    return {
+      login: parsed.tokens ? "present" : "absent",
+      storedApiKey: !parsed.tokens && Boolean(parsed.OPENAI_API_KEY),
+      storedApiKeyNote,
+    };
+  } catch {
+    return { login: "unknown", storedApiKey: false, storedApiKeyNote };
+  }
+}

package/src/core/workflow/child-env.ts

@@ -0,0 +1,47 @@
+/**
+ * Child-process environment builder shared by every spawn adapter.
+ *
+ * Rules (the first is a hard-won Phase 1 spike finding):
+ * 1. **Delete inherited harness-session vars, never blank them.** A nested
+ *    harness CLI under a live session inherits vars that make it exit 1 with
+ *    empty output; an empty-string var still reads as set. Scrub all three
+ *    families (CLAUDE*, CODEX*, CURSOR*) regardless of which adapter spawns —
+ *    a codex child launched from inside a Claude Code session must not
+ *    inherit CLAUDE* either.
+ * 2. **The scrub targets SESSION vars, not credentials.** CURSOR_API_KEY
+ *    matches the CURSOR* prefix but is an auth credential, so it is carved
+ *    out and re-added — a key-only cursor host must keep working. (The other
+ *    two key vars, ANTHROPIC_API_KEY and OPENAI_API_KEY, don't collide with
+ *    the scrub prefixes.)
+ * 3. **subscriptionOnly deletes every API-key var** (see billing.ts) so the
+ *    child can only authenticate via its stored subscription login — the
+ *    guarantee behind `workflow run --subscription-only`.
+ * 4. **Mark the child as a workflow child** (HARNERY_WORKFLOW_CHILD=1): the
+ *    stop-hook rule exempts it from the human-facing end-of-turn ritual while
+ *    hooks stay on, keeping heartbeat + event capture.
+ * 5. **Stamp the run id** (HARNERY_WORKFLOW_RUN_ID) so the coord layer and
+ *    web UI can associate child sessions with their workflow run.
+ */
+
+import { API_KEY_VARS } from "./billing.ts";
+
+const SCRUB_PREFIXES = ["CLAUDE", "CODEX", "CURSOR"];
+
+export interface ChildEnvOpts {
+  /** Delete all API-key vars so children can only use stored logins. */
+  subscriptionOnly?: boolean;
+}
+
+export function buildChildEnv(runId?: string, opts: ChildEnvOpts = {}): Record<string, string> {
+  const env: Record<string, string> = {};
+  const keyVars = new Set<string>(Object.values(API_KEY_VARS));
+  for (const [k, v] of Object.entries(process.env)) {
+    if (v === undefined) continue;
+    if (opts.subscriptionOnly && keyVars.has(k)) continue;
+    if (SCRUB_PREFIXES.some((p) => k.startsWith(p)) && !keyVars.has(k)) continue;
+    env[k] = v;
+  }
+  env.HARNERY_WORKFLOW_CHILD = "1";
+  if (runId) env.HARNERY_WORKFLOW_RUN_ID = runId;
+  return env;
+}