harnery 0.30.0 → 0.31.0

package/src/core/agents/cli.ts

@@ -182,13 +182,13 @@ async function emitClaimRelease(
     const { emit } = await import("./events/emit.ts");
     const canonical = path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
     const platform = hb.platform;
-    const harness =
+    const adapter =
       platform === "cursor" ? "cursor" : platform === "codex" ? "codex" : "claude-code";
     emit(root, {
       event_type: "claim.release",
       instance_id: owner,
       session_id: hb.session_id ?? owner,
-      harness,
+      adapter,
       source: "agent-coord",
       data: { path: canonical, reason },
     });
@@ -291,16 +291,16 @@ async function handleStateAction(root: string, action: string, rest: string[]):
       return 0;
     }
     case "heal-heartbeat": {
-      // harness arrives as a `--harness=<h>` flag (not positional) so the live
+      // adapter arrives as a `--adapter=<h>` flag (not positional) so the live
       // tool.pre_use heal and the manual `harn agents heal` path (which pass
       // different positional counts) can both supply it without arg-order
       // fragility. Positionals (sessionId, model) stay as-is once flags are
       // filtered out.
-      const harness = args.find((a) => a.startsWith("--harness="))?.slice("--harness=".length);
+      const adapter = args.find((a) => a.startsWith("--adapter="))?.slice("--adapter=".length);
       const positional = args.filter((a) => !a.startsWith("--"));
       const sessionId = positional[0];
       const model = positional[1];
-      const hb = writer.healHeartbeat(root, owner, sessionId, model, harness);
+      const hb = writer.healHeartbeat(root, owner, sessionId, model, adapter);
       process.stdout.write(`${JSON.stringify({ instance_id: owner, recreated: !!hb })}\n`);
       return hb ? 0 : 1;
     }
@@ -324,19 +324,19 @@ async function handleStateAction(root: string, action: string, rest: string[]):
   }
 }
 
-async function handleScratchAction(root: string, action: string, rest: string[]): Promise<number> {
-  const scratch = await import("./state/scratch.ts");
+async function handleJournalAction(root: string, action: string, rest: string[]): Promise<number> {
+  const journal = await import("./state/journal.ts");
 
-  if (action === "append-scratch") {
+  if (action === "append-journal") {
     const [owner, category, ...bodyParts] = rest;
     const body = bodyParts.join(" ");
     if (!owner || !category || !body) {
-      process.stderr.write("agent-coord append-scratch <instance_id> <category> <body>\n");
+      process.stderr.write("agent-coord append-journal <instance_id> <category> <body>\n");
       return 2;
     }
-    const result = scratch.appendScratch(root, owner, category, body);
+    const result = journal.appendJournal(root, owner, category, body);
     if (!result.ok) {
-      process.stderr.write(`agent-coord append-scratch: ${result.reason}\n`);
+      process.stderr.write(`agent-coord append-journal: ${result.reason}\n`);
       return 1;
     }
     process.stdout.write(
@@ -345,24 +345,22 @@ async function handleScratchAction(root: string, action: string, rest: string[])
     return 0;
   }
 
-  if (action === "edit-scratchpad") {
+  if (action === "edit-journal") {
     const [owner, newBodyFile, ...summaryParts] = rest;
     const summary = summaryParts.join(" ");
     if (!owner || !newBodyFile) {
-      process.stderr.write(
-        "agent-coord edit-scratchpad <instance_id> <new-body-file> [<summary>]\n",
-      );
+      process.stderr.write("agent-coord edit-journal <instance_id> <new-body-file> [<summary>]\n");
       return 2;
     }
     if (!existsSync(newBodyFile)) {
-      process.stderr.write(`agent-coord edit-scratchpad: file not found: ${newBodyFile}\n`);
+      process.stderr.write(`agent-coord edit-journal: file not found: ${newBodyFile}\n`);
       return 2;
     }
     const { readFileSync } = await import("node:fs");
     const newBody = readFileSync(newBodyFile, "utf8");
-    const result = scratch.editScratchpad(root, owner, newBody, summary);
+    const result = journal.editJournal(root, owner, newBody, summary);
     if (!result.ok) {
-      process.stderr.write(`agent-coord edit-scratchpad: ${result.reason}\n`);
+      process.stderr.write(`agent-coord edit-journal: ${result.reason}\n`);
       return 1;
     }
     process.stdout.write(
@@ -371,7 +369,7 @@ async function handleScratchAction(root: string, action: string, rest: string[])
     return 0;
   }
 
-  process.stderr.write(`agent-coord: unknown scratch action ${action}\n`);
+  process.stderr.write(`agent-coord: unknown journal action ${action}\n`);
   return 2;
 }
 
@@ -566,7 +564,7 @@ async function handleShellMutationClaimLog(root: string, rest: string[]): Promis
   // in a log file; now a canonical decision.warn so the
   // signal survives in events.ndjson. (The blocking claim-conflict path is
   // separate: claim.conflict / verdict, and unaffected.)
-  const harness = platform === "cursor" ? "cursor" : platform === "codex" ? "codex" : "claude-code";
+  const adapter = platform === "cursor" ? "cursor" : platform === "codex" ? "codex" : "claude-code";
   const hb = owner ? readHeartbeat(root, owner) : null;
   for (const p of paths) {
     try {
@@ -574,7 +572,7 @@ async function handleShellMutationClaimLog(root: string, rest: string[]): Promis
         event_type: "decision.warn",
         instance_id: owner ?? "unknown",
         session_id: hb?.session_id ?? owner ?? "unknown",
-        harness,
+        adapter,
         data: {
           rule: "shell_mutation_candidate",
           reason: `path=${p} cmd=${truncated} platform=${platform}`,
@@ -612,10 +610,12 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
   const instanceId = args.instance;
   const sessionId = args.session ?? instanceId;
   const agentName = args.name;
+  const sessionNameNudge = args["session-name-nudge"] === "true";
   const taskNudge = args["task-nudge"] === "true";
+  const statusFooterNudge = args["status-footer-nudge"] === "true";
   if (!instanceId) {
     process.stderr.write(
-      "agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--task-nudge]\n",
+      "agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--session-name-nudge] [--task-nudge] [--status-footer-nudge]\n",
     );
     return 2;
   }
@@ -625,7 +625,9 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
     instanceId,
     sessionId: sessionId!,
     agentName,
+    sessionNameNudge,
     taskNudge,
+    statusFooterNudge,
   });
   process.stdout.write(text);
   return 0;
@@ -743,12 +745,12 @@ async function handleEmitEvent(root: string, rest: string[]): Promise<number> {
   const eventType = args.type;
   const instanceId = args.owner;
   const sessionId = args.session;
-  const harness = args.harness as "claude-code" | "cursor" | "codex" | undefined;
+  const adapter = args.adapter as "claude-code" | "cursor" | "codex" | undefined;
   const dataJson = args["data-json"] ?? "{}";
 
-  if (!eventType || !instanceId || !sessionId || !harness) {
+  if (!eventType || !instanceId || !sessionId || !adapter) {
     process.stderr.write(
-      "agent-coord emit-event --type <T> --owner <id> --session <id> --harness <h> [--data-json '<json>']\n",
+      "agent-coord emit-event --type <T> --owner <id> --session <id> --adapter <h> [--data-json '<json>']\n",
     );
     return 2;
   }
@@ -774,7 +776,7 @@ async function handleEmitEvent(root: string, rest: string[]): Promise<number> {
       event_type: eventType,
       instance_id: instanceId,
       session_id: sessionId,
-      harness,
+      adapter,
       turn_id: args["turn-id"],
       parent_session_id: args["parent-session-id"],
       parent_turn_id: args["parent-turn-id"],
@@ -822,8 +824,8 @@ async function main(): Promise<number> {
     return handleStateAction(root, subcommand, rest);
   }
 
-  if (subcommand === "append-scratch" || subcommand === "edit-scratchpad") {
-    return handleScratchAction(root, subcommand, rest);
+  if (subcommand === "append-journal" || subcommand === "edit-journal") {
+    return handleJournalAction(root, subcommand, rest);
   }
 
   if (

package/src/core/agents/codex-replay.ts

@@ -4,7 +4,7 @@
  * Production codex sessions emit canonical events from each `harn` invocation
  * via the in-process session-tee middleware (which calls `agent-coord
  * emit-event` for state.task_set / state.status_checked). But the codex
- * harness itself doesn't wire agent-hook on preToolUse, so user_prompt.submit
+ * adapter itself doesn't wire agent-hook on preToolUse, so user_prompt.submit
  * + tool.pre_use + turn.stop aren't emitted live.
  *
  * This module parses the Codex JSONL transcript at stop time and emits the
@@ -71,7 +71,7 @@ export function replayCodexJsonl(opts: CodexReplayOpts): { emitted: number } {
         event_type: "user_prompt.submit",
         instance_id: instanceId,
         session_id: sessionId,
-        harness: "codex",
+        adapter: "codex",
         ts,
         data: {
           prompt_text: clamp(entry.payload.message ?? "", 4000),
@@ -97,7 +97,7 @@ export function replayCodexJsonl(opts: CodexReplayOpts): { emitted: number } {
         event_type: "tool.pre_use",
         instance_id: instanceId,
         session_id: sessionId,
-        harness: "codex",
+        adapter: "codex",
         ts,
         data: {
           tool_name: name === "exec_command" ? "Bash" : name,
@@ -117,7 +117,7 @@ export function replayCodexJsonl(opts: CodexReplayOpts): { emitted: number } {
           event_type: "state.status_checked",
           instance_id: instanceId,
           session_id: sessionId,
-          harness: "codex",
+          adapter: "codex",
           ts,
           data: { source: "codex-replay" },
         });
@@ -128,7 +128,7 @@ export function replayCodexJsonl(opts: CodexReplayOpts): { emitted: number } {
           event_type: "state.task_set",
           instance_id: instanceId,
           session_id: sessionId,
-          harness: "codex",
+          adapter: "codex",
           ts,
           data: { source: "codex-replay" },
         });
@@ -145,7 +145,7 @@ export function replayCodexJsonl(opts: CodexReplayOpts): { emitted: number } {
     event_type: "turn.stop",
     instance_id: instanceId,
     session_id: sessionId,
-    harness: "codex",
+    adapter: "codex",
     data: {
       status_box_present: boxPresent,
       tool_call_count: -1,

package/src/core/agents/coord-client.ts

@@ -73,7 +73,7 @@ export interface Heartbeat {
   last_tool_target?: string;
   /** Free-form task/intent string set via `harn agents set-task`. Phase 2. */
   task?: string;
-  /** UTC ISO-8601 timestamp when task was last set/cleared. Used by harnesses without Stop enforcement to compute staleness. 2026-05-24. */
+  /** UTC ISO-8601 timestamp when task was last set/cleared. Used by adapters without Stop enforcement to compute staleness. 2026-05-24. */
   task_updated_at?: string | null;
   /** Auto-generated per-turn summary written by the Stop hook via Haiku. 2026-05-23. */
   turn_summary?: string | null;
@@ -146,9 +146,93 @@ export function parsePidmapRowOwner(row: string): string {
 
 /** Parse platform from a pid-map row; legacy rows default to `claude_code`. */
 export function parsePidmapRowPlatform(row: string): string {
-  const trimmed = row.trim();
-  const tab = trimmed.indexOf("\t");
-  return tab >= 0 ? trimmed.slice(tab + 1).trim() : "claude_code";
+  const platform = row.trim().split("\t")[1]?.trim();
+  return platform || "claude_code";
+}
+
+/** Parse the start token from a pid-map row; rows written before it carry none. */
+export function parsePidmapRowStartToken(row: string): string | undefined {
+  return row.trim().split("\t")[2]?.trim() || undefined;
+}
+
+/**
+ * Is the process now holding `pid` the one this row was written for?
+ *
+ * A pid is a number the OS re-issues, and quickly: a `pid_max` of 99999 against
+ * ~100 new processes a second recycles the whole space about every quarter
+ * hour. Believing a row past that point resolves this session to whichever
+ * agent last held the number — which is what made `whoami` report a stranger's
+ * name and files. The start token settles it, since two processes may share a
+ * pid but never a pid and a start instant.
+ *
+ * Deliberately inlined rather than imported from `state/proc-start.ts`: this
+ * file is vendored verbatim into a downstream consumer and stays on node
+ * builtins only. The token is a wire format shared with that module and with
+ * the host's commit guard, so the copies must agree byte for byte; exported so
+ * a test can hold this one against `processStartToken` and fail on drift.
+ */
+export function pidStartToken(pid: number): string | null {
+  const forced = process.env.HARNERY_PID_PROBE;
+  const useProcfs = forced === "procfs" || (forced !== "ps" && existsSync("/proc/self/stat"));
+  // One machine, one probe. Falling back to the other on a read failure would
+  // answer in the wrong dialect and read as a recycled pid.
+  if (useProcfs) {
+    try {
+      const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+      const afterComm = stat.slice(stat.lastIndexOf(") ") + 2);
+      // Fields after comm, 0-based: 0 is state (field 3), starttime (22) is 19.
+      const ticks = afterComm.split(" ")[19];
+      if (!ticks || !/^\d+$/.test(ticks)) return null;
+      // Ticks count from boot, so they repeat across reboots; the boot id scopes
+      // them. Rows written before it carry ticks alone and still compare.
+      let boot = "";
+      try {
+        const raw = readFileSync("/proc/sys/kernel/random/boot_id", "utf8")
+          .trim()
+          .replace(/-/g, "");
+        if (/^[0-9a-f]{8,}$/.test(raw)) boot = `${raw.slice(0, 8)}.`;
+      } catch {
+        /* unnamed boot: fall back to the tick-only shape */
+      }
+      return `l${boot}${ticks}`;
+    } catch {
+      return null;
+    }
+  }
+  try {
+    // TZ and locale are pinned because `ps` renders the date through them, and
+    // two callers with different environments must not disagree about one
+    // process.
+    const out = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+      encoding: "utf8",
+      timeout: 2000,
+      env: { ...process.env, TZ: "UTC", LC_ALL: "C" },
+    });
+    if (out.status !== 0) return null;
+    const lstart = (out.stdout ?? "").split("\n")[0]?.trim().replace(/\s+/g, " ");
+    return lstart ? `p${lstart}` : null;
+  } catch {
+    return null;
+  }
+}
+
+function pidWasRecycled(pid: number, row: string): boolean {
+  const recorded = parsePidmapRowStartToken(row);
+  if (!recorded) return false; // pre-token row: unverifiable, behave as before
+  const current = pidStartToken(pid);
+  if (!current) return false;
+  if (current === recorded) return false;
+  // A row predating the boot segment recorded ticks alone; compare it on what
+  // it recorded rather than pruning every live row on the first upgraded run.
+  if (
+    recorded[0] === "l" &&
+    current[0] === "l" &&
+    recorded.includes(".") !== current.includes(".")
+  ) {
+    const ticks = (t: string) => (t.includes(".") ? t.slice(t.indexOf(".") + 1) : t.slice(1));
+    return ticks(recorded) !== ticks(current);
+  }
+  return true;
 }
 
 function readPidmapRow(pidmapDir: string, pid: number): string | null {
@@ -197,9 +281,14 @@ export function resolveOwnerWithSource(): {
   const root = monorepoRoot();
   if (!root) return { owner: null, source: "none" };
 
-  // Cursor's Glass/Agents UI can run several chats under one long-lived node
-  // process, so the pid-map row for that shared ancestor is last-writer-wins.
-  // Prefer the per-chat session id when Cursor exposes one in the tool env.
+  // Every supported adapter exports its session id into the env of the
+  // subprocess it spawns for a tool call, and each heartbeat records the
+  // session id it was minted under. Matching the two names us outright, even
+  // with many live agents, so it goes ahead of the ppid walk rather than
+  // catching what the walk drops. Cursor needed this first because its
+  // Glass/Agents UI runs several chats under one node ancestor, making that row
+  // last-writer-wins; pid recycling generalises the same hazard to every
+  // adapter.
   if (shouldPreferSessionEnv()) {
     const bySession = resolveOwnerBySessionEnv(root);
     if (bySession) {
@@ -217,7 +306,7 @@ export function resolveOwnerWithSource(): {
   for (let hop = 0; hop < 20; hop++) {
     if (pid === null) break;
     const row = readPidmapRow(pidmapDir, pid);
-    if (row) {
+    if (row && !pidWasRecycled(pid, row)) {
       const rowOwner = parsePidmapRowOwner(row);
       const rowPlat = parsePidmapRowPlatform(row);
       if (rowPlat === prefer) {
@@ -231,18 +320,6 @@ export function resolveOwnerWithSource(): {
     return { owner: fallbackOwner, source: "pidmap_fallback" };
   }
 
-  // The ppid walk found nothing (e.g. a Bash-tool subshell whose process tree
-  // doesn't climb back to the harness anchor). Before guessing, try the
-  // harness-provided session id from the environment: every supported harness
-  // exports its session id into the tool subprocess env, and each heartbeat
-  // records the `session_id` it was minted under. Matching the two resolves us
-  // unambiguously even with multiple live agents, which is the case the
-  // singleton fallback below cannot handle.
-  const bySession = resolveOwnerBySessionEnv(root);
-  if (bySession) {
-    return { owner: bySession, source: "session_env" };
-  }
-
   // Last resort: if exactly one agent is live in this coord root, it's
   // unambiguously us — resolve to it. This is what lets the bare `agents
   // status` / `set-task` the stop hook recommends work without a `--session-id`
@@ -257,8 +334,8 @@ export function resolveOwnerWithSource(): {
 }
 
 /**
- * Harness-exported session-id environment variables, in precedence order. Each
- * supported harness propagates its session id into the env of the subprocess it
+ * Adapter-exported session-id environment variables, in precedence order. Each
+ * supported adapter propagates its session id into the env of the subprocess it
  * spawns for a tool call (Claude Code's Bash tool, Cursor's terminal, Codex's
  * shell). A coord CLI invoked as such a tool can therefore recover its own
  * identity from the env even when the ppid walk misses.
@@ -274,7 +351,7 @@ const SESSION_ID_ENV_VARS = [
   "CODEX_SESSION_ID",
 ] as const;
 
-/** Read normalized candidates from the first non-empty harness session-id env var. */
+/** Read normalized candidates from the first non-empty adapter session-id env var. */
 function sessionIdsFromEnv(): string[] {
   for (const key of SESSION_ID_ENV_VARS) {
     const v = process.env[key]?.trim();
@@ -287,19 +364,33 @@ function sessionIdsFromEnv(): string[] {
   return [];
 }
 
-/** Read the first non-empty harness session-id env var, or null. */
+/** Read the first non-empty adapter session-id env var, or null. */
 function sessionIdFromEnv(): string | null {
   return sessionIdsFromEnv()[0] ?? null;
 }
 
+/**
+ * Should the adapter-exported session id be consulted before the ppid walk?
+ *
+ * Yes, whenever one is exported. The env var is the adapter stating its own
+ * identity; the walk is a guess over a namespace the OS recycles. On a box with
+ * `pid_max` of 99999 and ~100 pids allocated per second the whole pid space
+ * turns over about every quarter hour, so a row written before that can name a
+ * pid some unrelated process now holds. Pruning cannot save the walk here:
+ * it removes rows whose pid is dead, and a recycled pid is alive. Letting a
+ * guess outrank a statement of fact is what made `agents whoami` report another
+ * agent's name and file list.
+ *
+ * This only reorders the two. Session-env resolution still requires a live
+ * heartbeat carrying that session id, so when it does not match, the walk runs
+ * exactly as before.
+ */
 function shouldPreferSessionEnv(): boolean {
-  if (!sessionIdFromEnv()) return false;
-  const platform = process.env.HARNERY_AGENT_COORD_PLATFORM?.trim();
-  return process.env.CURSOR_AGENT === "1" || platform === "cursor";
+  return sessionIdFromEnv() !== null;
 }
 
 /**
- * Resolve the owner by matching the harness session-id env var against the
+ * Resolve the owner by matching the adapter session-id env var against the
  * `session_id` of a live heartbeat in this coord root. Returns the matching
  * `instance_id`, or null if there's no session-id env var or no live heartbeat
  * carries it. "Live" reuses the same 10-minute freshness window the singleton

package/src/core/agents/events/consume.ts

@@ -56,7 +56,7 @@ export interface CanonicalEvent {
   parent_session_id?: string;
   turn_id?: string;
   parent_turn_id?: string;
-  harness: string;
+  adapter: string;
   source: string;
   data: Record<string, unknown>;
 }

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

@@ -5,7 +5,7 @@
  * event/schema types).
  *
  * Phase 4: agent-coord uses this from CLI handlers (state.task_set,
- * state.status_checked, state.scratch_append, council.*, decision.*,
+ * state.status_checked, state.journal_append, council.*, decision.*,
  * presence.*).
  */
 
@@ -19,8 +19,9 @@ const STREAM_FILE = ".harnery/events.ndjson";
 const LOCK_FILE = ".harnery/events.ndjson.lock";
 const MAX_LINE_BYTES = 64 * 1024;
 
-export type Harness = "claude-code" | "cursor" | "codex";
-export type Source = "agent-hooks" | "agent-coord" | "user" | "system";
+export type { Adapter, Source } from "../../hooks/events/schema.ts";
+
+import type { Adapter, Source } from "../../hooks/events/schema.ts";
 
 export interface Envelope {
   schema_version: typeof SCHEMA_VERSION;
@@ -32,7 +33,7 @@ export interface Envelope {
   parent_session_id?: string;
   turn_id?: string;
   parent_turn_id?: string;
-  harness: Harness;
+  adapter: Adapter;
   source: Source;
   data: Record<string, unknown>;
 }
@@ -41,7 +42,7 @@ export interface EmitInput {
   event_type: string;
   instance_id: string;
   session_id: string;
-  harness: Harness;
+  adapter: Adapter;
   source?: Source;
   parent_session_id?: string;
   turn_id?: string;
@@ -61,7 +62,7 @@ export function buildEnvelope(input: EmitInput): Envelope {
     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-coord",
     data: input.data,
   };