harnery 0.30.0 → 0.31.0

package/src/core/hooks/effects/image-capture.ts

@@ -9,7 +9,7 @@
  * the canonical stream. The web image feed (`/images`) groups those events by
  * hash and streams them live over the existing SSE infra.
  *
- * Why this lives at the hook layer: it's the single harness-agnostic chokepoint
+ * Why this lives at the hook layer: it's the single adapter-agnostic chokepoint
  * that sees every tool call across Claude Code / Cursor / Codex with the full
  * `tool_input` (file paths) and `tool_response`. No per-command code needed.
  *
@@ -29,9 +29,9 @@ import {
   writeFileSync,
 } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
+import type { ParsedPayload } from "../adapter/parse.ts";
 import { emit } from "../events/emit.ts";
-import type { Harness } from "../events/schema.ts";
-import type { ParsedPayload } from "../harness/parse.ts";
+import type { Adapter } from "../events/schema.ts";
 
 /** Raster + vector image extensions the feed accepts. PDF is intentionally
  * excluded: book renders aren't an "image feed" and don't thumbnail inline. */
@@ -59,7 +59,7 @@ export interface CaptureContext {
   payload: ParsedPayload | null;
   instanceId: string;
   sessionId: string;
-  harness: Harness;
+  adapter: Adapter;
 }
 
 interface Candidate {
@@ -95,7 +95,7 @@ export function captureImages(coordRoot: string, ctx: CaptureContext): void {
       event_type: "image.captured",
       instance_id: ctx.instanceId,
       session_id: ctx.sessionId,
-      harness: ctx.harness,
+      adapter: ctx.adapter,
       data: {
         hash: captured.hash,
         ext: captured.ext,
@@ -204,7 +204,7 @@ function captureOne(imagesDir: string, cand: Candidate): CapturedBlob | null {
 /**
  * Prune `.harnery/images/` past a size cap (default 2 GB) and an age cap
  * (default 30 days), oldest-mtime-first. Fired on session.start next to
- * scratchJanitor. Pure-fs, fail-soft. Orphaned `image.captured` events whose
+ * journalJanitor. Pure-fs, fail-soft. Orphaned `image.captured` events whose
  * blob was pruned render as an "expired" placeholder in the gallery.
  */
 export function imageJanitor(coordRoot: string): void {

package/src/core/hooks/effects/index.ts

@@ -1,11 +1,11 @@
 /**
  * Non-coordination side effects fired from the normalized `agent-hook` handlers.
  *
- * These are DELIBERATELY outside the agent-coord path: sounds, scratch
+ * These are DELIBERATELY outside the agent-coord path: sounds, journal
  * lifecycle, session telemetry, presence detection. They used to live in
- * per-harness bash adapters. Per the directive ("use the normalized hooks; if
+ * per-adapter bash adapters. Per the directive ("use the normalized hooks; if
  * they aren't coordination, implement them outside of coordination") they move
- * here so the harness configs reference only `agent-hook`, while staying a
+ * here so the adapter configs reference only `agent-hook`, while staying a
  * distinct concern from the coordination logic in cli.ts / agent-coord.
  *
  * Everything here is best-effort: it never throws and never blocks the hook on a
@@ -66,12 +66,12 @@ function harnBin(repoRoot: string): string | null {
   return existsSync(bin) ? bin : null;
 }
 
-/** Prune stale scratch archives + sweep orphans (global, fast). Fire-and-forget. */
-export function scratchJanitor(repoRoot: string): void {
+/** Prune stale journal archives + sweep orphans (global, fast). Fire-and-forget. */
+export function journalJanitor(repoRoot: string): void {
   try {
     const bin = harnBin(repoRoot);
     if (!bin) return;
-    spawnSync("bash", [bin, "scratch", "janitor", "--quiet"], {
+    spawnSync("bash", [bin, "journal", "janitor", "--quiet"], {
       env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
       timeout: 5000,
       stdio: "ignore",
@@ -82,15 +82,15 @@ export function scratchJanitor(repoRoot: string): void {
 }
 
 /**
- * Return the one-line scratch recovery cue for SessionStart, or "" if none.
+ * Return the one-line journal recovery cue for SessionStart, or "" if none.
  * The caller merges it into the session-start additionalContext (it used to be
- * a standalone additionalContext emission from the previous scratch-on-start adapter).
+ * a standalone additionalContext emission from the previous journal-on-start adapter).
  */
-export function scratchRecoveryCue(repoRoot: string): string {
+export function journalRecoveryCue(repoRoot: string): string {
   try {
     const bin = harnBin(repoRoot);
     if (!bin) return "";
-    const r = spawnSync("bash", [bin, "scratch", "recovery-cue"], {
+    const r = spawnSync("bash", [bin, "journal", "recovery-cue"], {
       env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
       timeout: 5000,
       encoding: "utf8",
@@ -101,12 +101,12 @@ export function scratchRecoveryCue(repoRoot: string): string {
   }
 }
 
-/** Archive the ending agent's scratchpad. Fire-and-forget. */
-export function scratchArchive(repoRoot: string, owner: string): void {
+/** Archive the ending agent's journal. Fire-and-forget. */
+export function journalArchive(repoRoot: string, owner: string): void {
   try {
     const bin = harnBin(repoRoot);
     if (!bin || !owner) return;
-    spawnSync("bash", [bin, "scratch", "archive", "--owner", owner], {
+    spawnSync("bash", [bin, "journal", "archive", "--owner", owner], {
       env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
       timeout: 5000,
       stdio: "ignore",
@@ -120,13 +120,13 @@ export function scratchArchive(repoRoot: string, owner: string): void {
  * Fire the optional host session-sync extension on turn stop / session end.
  * harnery core has no session-telemetry sink of its own; a host that wants one
  * drops an executable at
- * `scripts/hooks/harness/claude_code/extensions/session-sync.sh` under the coord
+ * `scripts/hooks/adapter/claude_code/extensions/session-sync.sh` under the coord
  * root, and core runs it detached + unref'd so a slow sink never blocks the
  * hook. `force` arrives as argv $1 ("1" on session end, "0" on turn stop) so the
  * host can rate-limit the stop path and force-flush on end. No-op when the
  * script is absent, so a plain public install spawns nothing. Mirrors
  * `runTurnSummary`'s extension-script pattern. Caller gates to the claude-code
- * harness.
+ * adapter.
  */
 export function runSessionSyncExtension(repoRoot: string, force: boolean): void {
   try {
@@ -134,7 +134,7 @@ export function runSessionSyncExtension(repoRoot: string, force: boolean): void
       repoRoot,
       "scripts",
       "hooks",
-      "harness",
+      "adapter",
       "claude_code",
       "extensions",
       "session-sync.sh",
@@ -169,7 +169,7 @@ export function runTurnSummary(
       repoRoot,
       "scripts",
       "hooks",
-      "harness",
+      "adapter",
       "claude_code",
       "extensions",
       "turn-summary.sh",

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

@@ -2,9 +2,9 @@ import { appendFileSync, closeSync, mkdirSync, openSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { maybeRotateEventStream } from "./rotate.ts";
 import {
+  type Adapter,
   type EventEnvelope,
   type EventType,
-  type Harness,
   SCHEMA_VERSION,
   type Source,
 } from "./schema.ts";
@@ -19,7 +19,7 @@ export interface EmitInput<TType extends EventType, TData> {
   event_type: TType;
   instance_id: string;
   session_id: string;
-  harness: Harness;
+  adapter: Adapter;
   source?: Source;
   parent_session_id?: string;
   turn_id?: string;
@@ -45,7 +45,7 @@ export function buildEnvelope<TType extends EventType, TData>(
     parent_session_id: input.parent_session_id,
     turn_id: input.turn_id,
     parent_turn_id: input.parent_turn_id,
-    harness: input.harness,
+    adapter: input.adapter,
     source: input.source ?? "agent-hooks",
     data: input.data,
   };

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

@@ -63,7 +63,7 @@ function resolveRollBytes(): number {
 }
 
 /** `YYYY-MM-DD` (UTC) from a millisecond timestamp. Uses the file's own mtime
- * rather than `Date.now()` so it's deterministic and independent of the harness
+ * rather than `Date.now()` so it's deterministic and independent of the adapter
  * runtime's clock surface. */
 function utcDateStamp(mtimeMs: number): string {
   const d = new Date(mtimeMs);

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

@@ -12,7 +12,11 @@
 
 export const SCHEMA_VERSION = 1 as const;
 
-export type Harness = "claude-code" | "cursor" | "codex";
+/** The adapters harnery ships first-party hook wiring for. The registry's open
+ * `AdapterId` covers any adapter a host registers; this is the closed set, and
+ * it is declared exactly once. Re-exported by the two event modules that used
+ * to keep their own byte-identical copy. */
+export type Adapter = "claude-code" | "cursor" | "codex";
 
 export type Source = "agent-hooks" | "agent-coord" | "user" | "system";
 
@@ -28,11 +32,11 @@ export interface EventEnvelope<TType extends string, TData> {
   event_type: TType;
   ts: string; // ISO-8601 with milliseconds
   instance_id: string; // resolved by agent-hooks
-  session_id: string; // harness-level session
+  session_id: string; // adapter-level session
   parent_session_id?: string; // present iff event is from a subagent
   turn_id?: string; // present when event is bound to an assistant turn
   parent_turn_id?: string; // present iff this turn is nested under another
-  harness: Harness;
+  adapter: Adapter;
   source: Source;
   data: TData;
 }
@@ -48,9 +52,13 @@ export type SessionStart = EventEnvelope<
     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
+     * transcript owns it (child env HARNERY_WORKFLOW_RUN_ID). Optional-field
      * addition per the schema evolution rules (minor bump). */
     workflow_run_id?: string;
+    /** Which agent row of that run this session is running (`a1`, `a2`, …), from
+     * child env HARNERY_WORKFLOW_AGENT_ID. Lets a dashboard attribute in-flight
+     * child activity to one agent instead of only to the run. */
+    workflow_agent_id?: string;
   }
 >;
 
@@ -288,8 +296,8 @@ export type StateStatusChecked = EventEnvelope<
   }
 >;
 
-export type StateScratchAppend = EventEnvelope<
-  "state.scratch_append",
+export type StateJournalAppend = EventEnvelope<
+  "state.journal_append",
   {
     category: "note" | "plan" | "decision" | "blocker" | "question" | "done" | "handoff";
     body_summary: string;
@@ -470,7 +478,7 @@ export type Event =
   | ClaimConflict
   | StateTaskSet
   | StateStatusChecked
-  | StateScratchAppend
+  | StateJournalAppend
   | StatePresenceChange
   | StateHeartbeat
   | IdentityAssumed

package/src/core/hooks/guard-path.ts

@@ -2,7 +2,7 @@
  * Canonicalize a write-tool target path for the claim guard.
  *
  * Returns the monorepo-relative path, or `null` when the target lies OUTSIDE the
- * repo (an absolute path not under coordRoot, e.g. a `/tmp` scratchpad or other
+ * repo (an absolute path not under coordRoot, e.g. a `/tmp` journal or other
  * session-temp file).
  *
  * The claim system is intentionally repo-scoped: it coordinates monorepo files,
@@ -10,7 +10,7 @@
  * them is right on two counts. First, it keeps non-repo paths out of a
  * heartbeat's `files_touched`. Second, the ordering rule compares raw path
  * strings, and an absolute `/tmp/…` sorts before every repo-relative path
- * (`/` = 0x2F < any letter), so without this a scratchpad write would spuriously
+ * (`/` = 0x2F < any letter), so without this a journal write would spuriously
  * "block" a legitimately-held repo file. Returning null keeps such paths out of
  * the claim system entirely.
  *

package/src/core/hooks/index.ts

@@ -6,10 +6,10 @@
  */
 
 export {
+  type Adapter,
   type Event,
   type EventEnvelope,
   type EventType,
-  type Harness,
   type RedactionMarker,
   SCHEMA_VERSION,
   type Source,

package/src/core/hooks/resolve/anchor.ts

@@ -3,7 +3,7 @@
  * the heartbeat pid-map row should be keyed to, so the agent's later shell
  * tool calls (which ppid-walk up to find it) resolve their own identity.
  *
- * Split out of cli.ts's `findHarnessAnchorPid` so the comm-matching logic is
+ * Split out of cli.ts's `findAdapterAnchorPid` so the comm-matching logic is
  * unit-testable against the real Phase 0 Cursor probe chains without needing a
  * live /proc tree.
  *
@@ -14,7 +14,7 @@
  * calls a reachable, stable pid-map row. This faithfully restores the previous
  * cursor anchor behavior (match `cursor` first, then fall back to `node`) that
  * was dropped in the Phase 4-6 TS refactor, the same regression class as the
- * heartbeat-platform + pidmap-self-heal losses. Scoped to `harness === "cursor"`
+ * heartbeat-platform + pidmap-self-heal losses. Scoped to `adapter === "cursor"`
  * so Claude Code / Codex never
  * mis-anchor on an unrelated `node` ancestor (they match their own comm token
  * directly).
@@ -25,24 +25,79 @@
  * concurrent same-window chats disambiguate via `--session-id`.
  */
 
-/** Harness-binary comm names. CC's tool calls descend from `claude`, Codex's
+/** Adapter-binary comm names. CC's tool calls descend from `claude`, Codex's
  * from `codex`; matched directly so neither needs the `node` fallback. */
 const PRIMARY_COMM_TOKENS = new Set(["claude", "claude-code", "cursor", "codex"]);
 
+/**
+ * Adapter-exported pid environment variables, in precedence order.
+ *
+ * A adapter that names its own process spares us the guessing entirely, and the
+ * guess is the part that breaks: comm matching only recognises a binary called
+ * by its adapter name, and at least one Claude Code build installs its CLI
+ * under a version-numbered filename, whose comm is a bare version string. The
+ * walk then finds nothing, falls back to the ephemeral hook shell, and writes a
+ * row that is dead within seconds.
+ *
+ * Only Claude Code is known to export one today. Absent variables cost a lookup.
+ */
+const ADAPTER_PID_ENV_VARS = ["CLAUDE_PID"] as const;
+
+/**
+ * The adapter pid as stated by the adapter itself, or undefined.
+ *
+ * Sanity-checked against our own pid: a variable naming this process would
+ * anchor the row to whatever short-lived thing is running the hook, which is
+ * the failure it exists to avoid.
+ */
+export function adapterPidFromEnv(): number | undefined {
+  for (const key of ADAPTER_PID_ENV_VARS) {
+    const raw = process.env[key]?.trim();
+    if (!raw) continue;
+    const pid = Number(raw);
+    if (!Number.isInteger(pid) || pid <= 1 || pid === process.pid) continue;
+    return pid;
+  }
+  return undefined;
+}
+
+/**
+ * Does an executable path belong to a adapter?
+ *
+ * Read as path segments rather than substrings, so a token has to be a whole
+ * directory or file name. The leading dot is optional because adapters install
+ * under a dotted home directory, and that directory is what identifies the
+ * binary when the binary's own name is a version number.
+ */
+function pathNamesAAdapter(exePath: string | undefined): boolean {
+  if (!exePath) return false;
+  for (const raw of exePath.split("/")) {
+    const segment = raw.startsWith(".") ? raw.slice(1) : raw;
+    if (PRIMARY_COMM_TOKENS.has(segment)) return true;
+  }
+  return false;
+}
+
 /**
  * Pick the anchor PID from a ppid chain ordered nearest-first (the resolving
  * process at index 0, walking up toward init). Returns the first ancestor
- * matching a harness comm token; for cursor, falls back to the first `node`
+ * matching a adapter comm token; for cursor, falls back to the first `node`
  * ancestor; otherwise undefined (caller falls back to process.ppid).
  */
 export function selectAnchorPid(
-  chain: ReadonlyArray<{ pid: number; comm: string }>,
-  harness?: string,
+  chain: ReadonlyArray<{ pid: number; comm: string; exe?: string }>,
+  adapter?: string,
 ): number | undefined {
   for (const hop of chain) {
     if (PRIMARY_COMM_TOKENS.has(hop.comm)) return hop.pid;
   }
-  if (harness === "cursor") {
+  // Second pass on the executable path, for a adapter whose binary is not named
+  // after itself. Kept behind the comm pass so an exactly-named ancestor still
+  // wins, and so this only ever adds matches.
+  for (const hop of chain) {
+    if (pathNamesAAdapter(hop.exe)) return hop.pid;
+  }
+  if (adapter === "cursor") {
     for (const hop of chain) {
       if (hop.comm === "node") return hop.pid;
     }
@@ -55,7 +110,7 @@ export function selectAnchorPid(
  * shape the `/proc` fast path produces, for the macOS/BSD branch of the anchor
  * walk. `ps` prints `comm` as a full executable path (and some Apple helper
  * names contain spaces, e.g. `Code Helper (Plugin)`), so the comm is reduced to
- * its basename to match the harness comm tokens the way Linux's `/proc/<pid>/comm`
+ * its basename to match the adapter comm tokens the way Linux's `/proc/<pid>/comm`
  * basename does. Returns null when the line has no leading numeric ppid.
  *
  * Pure (no I/O) so the parsing — the error-prone part — is unit-testable

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

@@ -8,11 +8,11 @@ import { coordEnv } from "../../../lib/env.ts";
  *
  * Resolution precedence:
  *   1. HARNERY_COORD_ROOT_OVERRIDE — explicit pin (tests, git hooks).
- *   2. The harness's project dir (CLAUDE_PROJECT_DIR) — hook processes
+ *   2. The adapter'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
+ *      (or none at all, e.g. a journal dir under /tmp). The session's
+ *      coordination home is the project the adapter 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).
@@ -27,7 +27,7 @@ export function findCoordRoot(start: string = process.cwd()): string | null {
   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.
+  // adapters 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);

package/src/core/hooks/resolve/intent.ts

@@ -26,7 +26,7 @@ export function resolveIntent(opts: {
 }): { intent: string; source: "command-comment" | "description" | "stamp" | "none" } {
   const stampPath = join(opts.coordRoot, ".harnery", `.last-intent.${opts.instanceId}`);
 
-  // 1. Fresh from the command itself (most reliable, cross-harness).
+  // 1. Fresh from the command itself (most reliable, cross-adapter).
   if (opts.commandIntentComment) {
     const cleaned = clamp(opts.commandIntentComment);
     if (cleaned) {

package/src/core/hooks/resolve/owner.ts

@@ -2,13 +2,14 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { coordEnv } from "../../../lib/env.ts";
+import { checkPidToken } from "../../agents/state/proc-start.ts";
 
 /**
  * Resolve the canonical `instance_id` for the current hook invocation.
  *
  * Precedence:
  *
- *   1. `HARNERY_AGENT_COORD_OWNER` env var. Set by harness adapters when they know
+ *   1. `HARNERY_AGENT_COORD_OWNER` env var. Set by adapter adapters when they know
  *      the owner identity at spawn time (Codex's apply_patch tool path uses
  *      this).
  *   2. Hook payload fields, in order: `agent_id` → `subagent_id` →
@@ -40,7 +41,7 @@ export function resolveOwner(opts: {
   }
 
   // Pid-map ancestor walk. Start at own pid (the bash wrapper's bun child),
-  // walk up through ppids. The pid-map is stamped keyed by the harness PID, so
+  // walk up through ppids. The pid-map is stamped keyed by the adapter PID, so
   // we'll usually find it 1-3 hops up.
   const pidmap = join(opts.coordRoot, ".harnery", "pid-map");
   if (existsSync(pidmap)) {
@@ -51,9 +52,14 @@ export function resolveOwner(opts: {
       if (existsSync(file)) {
         try {
           const row = readFileSync(file, "utf8").trim();
-          // Row shape: "<instance_id>" or "<instance_id>\t<platform>"
-          const owner = row.split("\t")[0];
-          if (owner && owner.length > 0) {
+          // Row shape: "<instance_id>", "<instance_id>\t<platform>", or
+          // "<instance_id>\t<platform>\t<start_token>".
+          const [owner, , startToken] = row.split("\t");
+          // A row whose start token disagrees with the process now holding this
+          // pid is about a different, earlier process. Believing it hands this
+          // session another agent's identity, so walk past it.
+          const recycled = checkPidToken(pid, startToken || undefined) === "mismatch";
+          if (owner && owner.length > 0 && !recycled) {
             return {
               instance_id: owner,
               source: hops === 0 ? "pidmap-self" : "pidmap-ancestor",