harnery 0.32.0 → 0.34.0

package/src/core/agents/session-name-display.ts

@@ -0,0 +1,149 @@
+/**
+ * The suggested session name is a small display protocol, not ordinary prose.
+ * Keep its exact block and pending-state rules in one adapter-neutral module so
+ * prompt context, PostToolUse injection, and PreToolUse enforcement cannot
+ * drift apart.
+ */
+
+export interface SessionNameDisplayState {
+  suggested_session_name?: string;
+  session_name_seen_for?: string;
+}
+
+export const SESSION_NAME_DISPLAY_NOTE =
+  "Next, before any prose or another tool call, send suggested_session_name verbatim by itself in a fenced code block.";
+
+export function sessionNameDisplayPending(
+  row: SessionNameDisplayState | null | undefined,
+): string | null {
+  const name = row?.suggested_session_name;
+  if (!name || row?.session_name_seen_for === name) return null;
+  return name;
+}
+
+export function sessionNameDisplayBlock(name: string): string {
+  return `\`\`\`\n${name}\n\`\`\``;
+}
+
+export function sessionNameDisplayInstruction(name: string): string {
+  return [
+    "Session name display required.",
+    "Before any prose or another tool call, send this exact fenced block as your next assistant text:",
+    "",
+    sessionNameDisplayBlock(name),
+    "",
+    "Do not put commentary before the block. Harnery will reject tool calls until it is shown.",
+  ].join("\n");
+}
+
+/**
+ * A PostToolUse result should announce the display protocol only when that
+ * exact tool call minted the current suggestion. The coordination row keeps
+ * the suggestion pending until transcript evidence catches up, so checking
+ * the row alone would re-announce the same name after every later tool.
+ *
+ * Adapter responses vary between a direct command envelope and wrapper
+ * objects whose `output`/content field contains the JSON as one line. Walk
+ * both shapes, but require the command's explicit mint flag as well as the
+ * exact current name. Ordinary status output can carry the name without
+ * activating the display ritual.
+ */
+export function toolResponseMintedSessionName(response: unknown, name: string): boolean {
+  if (!name) return false;
+  return responseContainsSessionNameMint(response, name, new Set<object>(), 0);
+}
+
+function responseContainsSessionNameMint(
+  value: unknown,
+  name: string,
+  seen: Set<object>,
+  depth: number,
+): boolean {
+  if (depth > 8 || value === null || value === undefined) return false;
+
+  if (typeof value === "string") {
+    const candidates = [value.trim(), ...value.split(/\r?\n/).map((line) => line.trim())];
+    for (const candidate of candidates) {
+      if (!candidate.startsWith("{") && !candidate.startsWith("[")) continue;
+      try {
+        if (
+          responseContainsSessionNameMint(JSON.parse(candidate) as unknown, name, seen, depth + 1)
+        ) {
+          return true;
+        }
+      } catch {
+        // Wrapper prose and partial JSON are not authoritative mint evidence.
+      }
+    }
+    return false;
+  }
+
+  if (typeof value !== "object") return false;
+  if (seen.has(value)) return false;
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    return value.some((item) => responseContainsSessionNameMint(item, name, seen, depth + 1));
+  }
+
+  const row = value as Record<string, unknown>;
+  if (
+    row.suggested_session_name === name &&
+    (row.first_of_session === true || row.name_reminted === true)
+  ) {
+    return true;
+  }
+
+  return Object.values(row).some((item) =>
+    responseContainsSessionNameMint(item, name, seen, depth + 1),
+  );
+}
+
+/**
+ * Accept the exact unlabelled block Harnery requests. `text` and `plaintext`
+ * are tolerated for older prompts, but the code block may contain only the
+ * suggested name and must be the first non-whitespace user-facing content.
+ */
+export function assistantTextStartsWithSessionNameBlock(text: string, name: string): boolean {
+  if (!text || !name) return false;
+  const normalized = text.replace(/\r\n?/g, "\n").trimStart();
+  const match = /^```(?:text|plaintext)?[ \t]*\n([^\n]*)\n```(?:[ \t]*(?:\n|$))/.exec(normalized);
+  return match?.[1] === name;
+}
+
+/**
+ * A trailing stream redirect to `/dev/null` or another descriptor. Agents append
+ * these habitually when capturing output, and unlike a pipe or `&&` they cannot
+ * smuggle a second command, so they must not disable the remediation exemption
+ * below. Deliberately excludes redirects to a named file.
+ */
+const BENIGN_REDIRECT_SUFFIX = /\s*[012]?>>?\s*(?:&[012]|\/dev\/null)\s*$/;
+
+/**
+ * The display latch must not block the two coordination commands that can
+ * repair a turn or close it cleanly. Keep this intentionally narrower than
+ * "any harn command" and reject shell control syntax before matching.
+ */
+export function isSessionNameRemediationCommand(
+  command: string | undefined,
+  binName: string,
+): boolean {
+  if (!command || !binName) return false;
+  let body = command.replace(/^(?:[ \t]*#\s*intent:[^\n]*\n)+/i, "").trim();
+
+  // Strip benign trailing redirects before the control-syntax check. Without
+  // this, `<bin> agents status --end-turn 2>&1` fails the `&` test, which
+  // disables the one exemption that can close a latched turn and leaves the
+  // session unable to satisfy either the latch or the end-of-turn rule.
+  for (let next = body.replace(BENIGN_REDIRECT_SUFFIX, "").trim(); next !== body; ) {
+    body = next;
+    next = body.replace(BENIGN_REDIRECT_SUFFIX, "").trim();
+  }
+
+  if (!body || /[\n;&|<>`$]/.test(body)) return false;
+  const escapedBin = binName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(
+    `^(?:codex-wsl\\s+--\\s+)?${escapedBin}\\s+agents\\s+(?:set-task|status)(?:\\s+.*)?$`,
+  );
+  return pattern.test(body);
+}

package/src/core/agents/state/activity-log.ts

@@ -2,32 +2,24 @@
  * Display-name resolution for the coord layer.
  *
  * This module once housed `coordLog`, the writer for a human-readable
- * activity log. That log has been retired; the canonical
- * `.harnery/events.ndjson` stream is the single source of truth, and the
+ * activity log. That log has been retired; the canonical V3 ledger is the
+ * single source of truth, and the
  * per-event telemetry that had consumers (heals → health.*, councils →
  * council.*, shell-mutation candidates → decision.warn) is emitted there
  * directly. `coordLog` and its call sites are gone; only `resolveShortName`
  * remains (still used for display-name resolution).
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { readLiveCoordinationRow } from "./live-coordination-view.ts";
 
 /**
- * Resolve `agent-<name>` display string. Looks up the heartbeat's `name`
+ * Resolve `agent-<name>` display string. Looks up the V3 projection's `name`
  * field; falls back to `agent-<8-char-hex>` if name is empty (mirrors bash
  * coord_owner_short). Returns `agent-unknown` when instanceId is null.
  */
 export function resolveShortName(coordRoot: string, instanceId: string | null): string {
   if (!instanceId) return "agent-unknown";
-  const path = join(coordRoot, ".harnery", "active", `${instanceId}.json`);
-  if (existsSync(path)) {
-    try {
-      const hb = JSON.parse(readFileSync(path, "utf8")) as { name?: string };
-      if (hb.name && hb.name.length > 0) return `agent-${hb.name}`;
-    } catch {
-      /* fall through to short-id */
-    }
-  }
+  const row = readLiveCoordinationRow(coordRoot, instanceId);
+  if (row?.name) return `agent-${row.name}`;
   return `agent-${instanceId.slice(0, 8)}`;
 }

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

@@ -9,7 +9,8 @@
  * half-written intermediate. Concurrent writers serialize via the rename
  * (last write wins).
  *
- * Owner identity invariant: every action operates on `.harnery/active/<instance_id>.json`
+ * Cache identity invariant: every action operates on the generation-bound row at
+ * `.harnery/active/<instance_id>.json`; the canonical V3 ledger remains authoritative.
  * (the file IS the heartbeat). No mutations happen elsewhere.
  */
 
@@ -22,54 +23,9 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { dirname, join } from "node:path";
-import { emit } from "../events/emit.ts";
-
-/** Inline adapter normalizer (mirrors canonical-emit.normalizeAdapter), kept
- * local so the writer's only cross-module dep is the in-process emit(). */
-function adapterOf(platform: string | undefined): "claude-code" | "cursor" | "codex" {
-  if (platform === "cursor") return "cursor";
-  if (platform === "codex") return "codex";
-  return "claude-code";
-}
-
-/** Preserve the canonical adapter id in heartbeat state. Mirrors
- * heartbeat-projector.adapterToPlatform so a healed heartbeat carries the same
- * platform value projection would have written. */
-function adapterToPlatform(adapter: string | undefined): string {
-  if (adapter === "cursor") return "cursor";
-  if (adapter === "codex") return "codex";
-  return "claude-code";
-}
-
-/**
- * Emit a canonical `health.*` event for an actual self-heal write. This is the
- * single source of truth for heal telemetry across BOTH the live auto-heal
- * (the pre-tool-use hook → agent-coord heal-heartbeat) and the manual `harn agents
- * heal` path. Write-only by construction (callers only invoke it after a real
- * write), so an already-correct heal records nothing.
- * Best-effort: never throws into the heal path.
- */
-function emitHealthHeal(
-  coordRoot: string,
-  type: "health.pidmap_heal" | "health.heartbeat_heal",
-  instanceId: string,
-  hb: Heartbeat | null,
-  data: Record<string, unknown>,
-): void {
-  try {
-    emit(coordRoot, {
-      event_type: type,
-      instance_id: instanceId,
-      session_id: hb?.session_id ?? instanceId,
-      adapter: adapterOf(hb?.platform),
-      source: "agent-coord",
-      data,
-    });
-  } catch {
-    /* telemetry only, never break a heal */
-  }
-}
+import { basename, dirname, join } from "node:path";
+import { assertSafeInstanceId, resolveContainedFile } from "../coord-client.ts";
+import type { AgentActivity, TaskState } from "./session-state.ts";
 
 export interface Heartbeat {
   schema_version?: number;
@@ -78,6 +34,8 @@ export interface Heartbeat {
   kind?: string;
   agent_id?: string;
   session_id: string;
+  /** Native adapter session ID retained only in a generation-bound local projection. */
+  native_session_id?: string;
   subagent_call_id?: string;
   model?: string;
   platform?: string;
@@ -86,11 +44,17 @@ export interface Heartbeat {
   files_touched: string[];
   task?: string;
   task_updated_at?: string | null;
+  activity?: AgentActivity;
+  activity_updated_at?: string;
+  activity_source?: string;
+  task_state?: TaskState;
+  task_state_updated_at?: string;
+  task_state_reason?: string;
   /** Session name built on the first non-empty set-task (never rebuilt). Its
    * presence is the "this session has been named" signal the prompt-context
    * nudge and the Stop-hook naming rule key on. */
   suggested_session_name?: string;
-  /** Stamped by turn.stop once the suggested name is seen in assistant reply
+  /** Stamped by turn.completed once the suggested name is seen in assistant reply
    * text, ending the per-turn transcript scan. */
   session_name_seen_at?: string;
   /** WHICH name that sighting was for. The scan is skipped only while this
@@ -98,19 +62,25 @@ export interface Heartbeat {
    * again rather than being suppressed by the earlier sighting. */
   session_name_seen_for?: string;
   last_status_at?: string;
-  turn_summary?: string | null;
-  turn_summary_updated_at?: string | null;
-  last_tool?: string;
-  last_tool_target?: string;
-  last_tool_at?: string;
   current_turn_id?: string;
   parent_instance_id?: string;
   workflow_run_id?: string;
+  workflow_agent_id?: string;
+  /** Disposable-cache bindings that prove a row belongs to the current V3 generation. */
+  v3_instance_id?: `inst_${string}`;
+  v3_generation_id?: `gen_${string}`;
+  v3_projection_event_id?: string;
+  v3_task_state?: "set" | "cleared";
   [extra: string]: unknown;
 }
 
 function heartbeatPath(coordRoot: string, instanceId: string): string {
-  return join(coordRoot, ".harnery", "active", `${instanceId}.json`);
+  assertSafeInstanceId(instanceId);
+  const safeInstanceId = basename(instanceId);
+  if (safeInstanceId !== instanceId) {
+    throw new Error("instance_id must be a direct-child coordination basename");
+  }
+  return resolveContainedFile(join(coordRoot, ".harnery", "active"), `${safeInstanceId}.json`);
 }
 
 function nowIsoSeconds(): string {
@@ -134,6 +104,23 @@ export function readHeartbeat(coordRoot: string, instanceId: string): Heartbeat
   }
 }
 
+/** Persist operator-facing lifecycle prose in the generation-bound cache only. */
+export function setLifecycleCache(
+  coordRoot: string,
+  instanceId: string,
+  state: TaskState,
+  reason?: string,
+  suggestedSessionName?: string,
+): Heartbeat | null {
+  return mutate(coordRoot, instanceId, (heartbeat) => ({
+    ...heartbeat,
+    task_state: state,
+    task_state_updated_at: nowIsoSeconds(),
+    task_state_reason: state === "active" ? undefined : reason,
+    ...(suggestedSessionName ? { suggested_session_name: suggestedSessionName } : {}),
+  }));
+}
+
 function mutate(
   coordRoot: string,
   instanceId: string,
@@ -163,11 +150,27 @@ export function setTask(coordRoot: string, instanceId: string, task: string): He
       ...hb,
       task: cleared ? undefined : task,
       task_updated_at: nowIsoSeconds(),
+      ...(hb.schema_version === 2 ? { v3_task_state: cleared ? "cleared" : "set" } : {}),
       ...(built ? { suggested_session_name: built.suggestedName } : {}),
     };
   });
 }
 
+/** Update the disposable identity cache after a canonical V3 attestation. */
+export function setIdentityCache(
+  coordRoot: string,
+  instanceId: string,
+  name: string,
+  agentId: string,
+): Heartbeat | null {
+  const heartbeat = readHeartbeat(coordRoot, instanceId);
+  if (!heartbeat) return null;
+  heartbeat.name = name;
+  heartbeat.agent_id = agentId;
+  atomicWrite(heartbeatPath(coordRoot, instanceId), JSON.stringify(heartbeat, null, 2));
+  return heartbeat;
+}
+
 /**
  * Build the copy-pasteable session name from the coord identity + the agent's
  * description parts. Pure (no coord-state reads) so it's unit-testable; collapses
@@ -183,6 +186,19 @@ export function buildSuggestedName(
   return { suggestedName: `Agent ${name} - ${description}`, description };
 }
 
+/** Build the sole lifecycle-driven title: the terminal done projection. */
+export function buildLifecycleSuggestedName(
+  currentSessionName: string | undefined,
+  state: TaskState,
+): string | null {
+  if (state !== "done" || !currentSessionName?.trim()) return null;
+  const baseName = currentSessionName
+    .trim()
+    .replace(/^\[DONE\]\s+/, "")
+    .replace(/^\[BLOCKED\]\s*-\s*/, "");
+  return baseName ? `[DONE] ${baseName}` : null;
+}
+
 /** Stamp the sighting once the suggested name has been observed in assistant
  * reply text; later turns skip the transcript scan. Records WHICH name was seen,
  * because the skip is only valid for that one: if a later set-task mints a
@@ -200,33 +216,36 @@ export function stampSessionNameSeen(
   }));
 }
 
-export function setTurnSummary(
+export function releaseClaim(
   coordRoot: string,
   instanceId: string,
-  summary: string,
+  path: string,
 ): Heartbeat | null {
+  // files_touched can hold either absolute-under-coordRoot or canonical
+  // monorepo-relative entries; normalize both sides so release matches
+  // regardless of the form the caller passes (the old exact-string filter
+  // silently no-op'd on a form mismatch).
+  const norm = (p: string): string =>
+    p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p;
+  const target = norm(path);
   return mutate(coordRoot, instanceId, (hb) => ({
     ...hb,
-    turn_summary: summary,
-    turn_summary_updated_at: nowIsoSeconds(),
+    files_touched: (hb.files_touched ?? []).filter((p) => norm(p) !== target),
   }));
 }
 
-export function releaseClaim(
+/** Materialize one V3 write-claim authority transition into the heartbeat cache. */
+export function acquireClaim(
   coordRoot: string,
   instanceId: string,
   path: string,
 ): Heartbeat | null {
-  // files_touched can hold either absolute-under-coordRoot or canonical
-  // monorepo-relative entries; normalize both sides so release matches
-  // regardless of the form the caller passes (the old exact-string filter
-  // silently no-op'd on a form mismatch).
   const norm = (p: string): string =>
     p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p;
   const target = norm(path);
   return mutate(coordRoot, instanceId, (hb) => ({
     ...hb,
-    files_touched: (hb.files_touched ?? []).filter((p) => norm(p) !== target),
+    files_touched: [...new Set([...(hb.files_touched ?? []).map(norm), target])].sort(),
   }));
 }
 
@@ -243,7 +262,7 @@ export interface GroupUnclaimHit {
  * subagents inherit it) and removes the path from each one's files_touched.
  * 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
+ * durable `coord.claim_changed` release events; a file-only prune is silently reverted by
  * the next projector replay.
  *
  * Tool payloads and release calls can supply either absolute-under-coordRoot or
@@ -254,7 +273,11 @@ export interface GroupUnclaimHit {
  * 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): GroupUnclaimHit[] {
+export function findGroupClaims(
+  coordRoot: string,
+  groupId: string,
+  path: string,
+): GroupUnclaimHit[] {
   const hits: GroupUnclaimHit[] = [];
   if (!groupId || !path) return hits;
   const activeDir = join(coordRoot, ".harnery", "active");
@@ -275,26 +298,17 @@ 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) => 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 */
-    }
+    if (!files.some((candidate) => norm(candidate) === target)) continue;
+    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,
+    });
   }
   return hits;
 }
 
-export function killHeartbeat(coordRoot: string, instanceId: string): boolean {
+export function clearCoordinationCache(coordRoot: string, instanceId: string): boolean {
   const path = heartbeatPath(coordRoot, instanceId);
   if (!existsSync(path)) return false;
   try {
@@ -322,162 +336,4 @@ export function healPidmap(coordRoot: string, instanceId: string, pid: number):
   }
   if (existingOwner === instanceId) return;
   atomicWrite(pmPath, `${instanceId}\t${platform}`);
-  emitHealthHeal(coordRoot, "health.pidmap_heal", instanceId, hb, {
-    reason: existingOwner ? "stale" : "missing",
-    pid,
-    kind: "pidmap",
-    ...(existingOwner ? { prior: existingOwner.slice(0, 8) } : {}),
-  });
-}
-
-export function healHeartbeat(
-  coordRoot: string,
-  instanceId: string,
-  sessionId?: string,
-  model?: string,
-  adapter?: string,
-  opts?: { forkedFrom?: string },
-): Heartbeat | null {
-  const path = heartbeatPath(coordRoot, instanceId);
-  if (existsSync(path)) {
-    // Already alive, return it.
-    return readHeartbeat(coordRoot, instanceId);
-  }
-  const now = nowIsoSeconds();
-
-  // Recover name + kind from .name-history if present (idempotent across
-  // sweeps: same instance_id always gets the same name).
-  let name = "";
-  let kind = "session";
-  let agentId = "";
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const names = require("./names.ts") as typeof import("./names.ts");
-    const resolved = names.resolveName(coordRoot, instanceId, sessionId);
-    if (resolved) {
-      name = resolved.name;
-      kind = resolved.kind;
-      // An explicitly assumed session carries its durable persona UUID in
-      // name-history. Native subagents continue to use instance_id.
-      agentId = resolved.agent_id ?? (resolved.kind === "subagent" ? instanceId : "");
-    } else if (!sessionId || sessionId === instanceId) {
-      // A main session with NO history at all never fired session.start —
-      // the CC fork flow (SessionStart fires under the parent's id before
-      // the fork id is minted), or a partially-wired adapter. Mint its pool
-      // name here instead of leaving a nameless heartbeat, and stamp the
-      // detected fork lineage while we're at it. A sessionId that differs
-      // from instanceId is left alone: that shape is a subagent whose parent
-      // is also unknown, and guessing "session" would be wrong.
-      name = names.assignName(
-        coordRoot,
-        instanceId,
-        "session",
-        opts?.forkedFrom ? { forkedFrom: opts.forkedFrom } : undefined,
-      );
-    }
-  } catch {
-    /* names module unavailable, fall back to empty */
-  }
-
-  const hb: Heartbeat = {
-    schema_version: 1,
-    instance_id: instanceId,
-    session_id: sessionId ?? instanceId,
-    name,
-    kind,
-    agent_id: agentId,
-    model: model ?? "",
-    started_at: now,
-    last_heartbeat: now,
-    files_touched: [],
-    // Default to claude-code only when the caller can't tell us the adapter
-    // (e.g. manual `harn agents heal`). The live tool.pre_use heal threads the
-    // detected adapter so a pruned Cursor/Codex heartbeat is recreated with
-    // the correct platform instead of being mislabeled claude-code.
-    platform: adapterToPlatform(adapter),
-  };
-  atomicWrite(path, JSON.stringify(hb, null, 2));
-  // Write-only telemetry: only the actual-recreate branch reaches here (the
-  // already-alive case returned above), so this records exactly the heals that
-  // happened. Recorded fork lineage rides the event too, so derived readers
-  // rebuilding from the ledger converge with .name-history.
-  emitHealthHeal(coordRoot, "health.heartbeat_heal", instanceId, hb, {
-    reason: "missing",
-    kind: "heartbeat",
-    ...(opts?.forkedFrom ? { forked_from: opts.forkedFrom } : {}),
-  });
-  return hb;
-}
-
-/**
- * Register a workflow child in the coordination layer from the ENGINE side.
- *
- * Previously a spawned child was visible only if its adapter fired Harnery's
- * hooks, which made coordination visibility a property of the vendor CLI
- * rather than of the engine. Headless `codex exec` fires no hooks, so codex
- * children never appeared in `harn agents list` and rendered as "no live
- * session" on the run page while actively working — for the entire length of
- * a multi-minute stage.
- *
- * The engine already knows every fact a heartbeat needs at spawn time, so it
- * writes one itself. Hook-firing adapters keep enriching the same file
- * (last_tool, files_touched); non-hook adapters at least become visible and
- * attributable. Pair with `killHeartbeat` when the child ends.
- *
- * Idempotent: re-registering refreshes in place and preserves `started_at`
- * and any claims a hook already recorded.
- */
-export function registerWorkflowChild(
-  coordRoot: string,
-  opts: {
-    instanceId: string;
-    runId: string;
-    agentId: string;
-    sessionId?: string;
-    adapter?: string;
-    label?: string;
-    model?: string;
-  },
-): Heartbeat {
-  const now = nowIsoSeconds();
-  const prior = readHeartbeat(coordRoot, opts.instanceId);
-  const hb: Heartbeat = {
-    ...(prior ?? {}),
-    schema_version: 1,
-    instance_id: opts.instanceId,
-    // The reader keys children by session_id and skips any heartbeat missing
-    // one, so it must always be set even before the adapter mints a real id.
-    session_id: prior?.session_id ?? opts.sessionId ?? opts.instanceId,
-    name: opts.label || opts.agentId,
-    kind: "workflow-child",
-    agent_id: opts.agentId,
-    model: opts.model ?? prior?.model ?? "",
-    platform: adapterToPlatform(opts.adapter),
-    started_at: prior?.started_at ?? now,
-    last_heartbeat: now,
-    files_touched: prior?.files_touched ?? [],
-    task: opts.label ?? "",
-    workflow_run_id: opts.runId,
-    workflow_agent_id: opts.agentId,
-  };
-  atomicWrite(heartbeatPath(coordRoot, opts.instanceId), JSON.stringify(hb, null, 2));
-  return hb;
-}
-
-/**
- * Stamp the heartbeat with the most-recent tool name + target. Written from
- * the post-tool-use hook.
- */
-export function stampToolActivity(
-  coordRoot: string,
-  instanceId: string,
-  toolName: string,
-  target: string,
-): Heartbeat | null {
-  return mutate(coordRoot, instanceId, (hb) => ({
-    ...hb,
-    last_tool: toolName,
-    last_tool_target: target,
-    last_tool_at: nowIsoSeconds(),
-  }));
 }