harnery 0.32.0 → 0.34.0

package/src/core/agents/state/live-coordination-view.ts

@@ -0,0 +1,290 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import type { Adapter } from "../../adapter.ts";
+import {
+  type CoordinationGenerationViewV3,
+  type CoordinationViewV3,
+  readCoordinationViewV3,
+  requireAuthoritySafeCoordinationViewV3,
+} from "../../events/v3/coordination-view.ts";
+import {
+  liveInstanceIdV3,
+  nativeInstanceIdV3,
+  resolveLiveEventLedgerRouteV3,
+} from "../../events/v3/live-routing.ts";
+import { type Heartbeat, readHeartbeat } from "./heartbeat-writer.ts";
+import { resolveName } from "./names.ts";
+
+/**
+ * Heartbeat files are disposable V3 caches. These bindings prevent a stale
+ * row from a prior generation from being mistaken for current authority.
+ */
+export interface V3HeartbeatMaterialization extends Heartbeat {
+  schema_version: 2;
+  v3_instance_id: `inst_${string}`;
+  v3_generation_id: `gen_${string}`;
+  v3_projection_event_id: string;
+  v3_task_state: "set" | "cleared";
+}
+
+/** Read the live coordination rows through the hard-cut ledger route. */
+export function readLiveCoordinationRows(coordRoot: string): V3HeartbeatMaterialization[] {
+  const route = resolveLiveEventLedgerRouteV3(coordRoot);
+  if (route.state === "blocked") return [];
+  let view: CoordinationViewV3;
+  try {
+    view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
+  } catch {
+    return [];
+  }
+  const caches = readV3Caches(coordRoot);
+  const byGeneration = new Map(
+    Object.values(view.instances).map((generation) => [generation.generation_id, generation]),
+  );
+  return Object.values(view.instances)
+    .filter((generation) => generation.authority_eligible)
+    .map((generation) => {
+      const parent = generation.parent_generation_id
+        ? byGeneration.get(generation.parent_generation_id)
+        : undefined;
+      return projectHeartbeatV3(
+        coordRoot,
+        generation,
+        matchingCache(caches, generation),
+        undefined,
+        parent,
+      );
+    });
+}
+
+/** Read one current row from the authority-safe V3 projection. */
+export function readLiveCoordinationRow(
+  coordRoot: string,
+  nativeInstanceId: string,
+): V3HeartbeatMaterialization | null {
+  const route = resolveLiveEventLedgerRouteV3(coordRoot);
+  if (route.state === "blocked") return null;
+  try {
+    const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
+    const generation = view.instances[liveInstanceIdV3(nativeInstanceId)];
+    if (!generation?.authority_eligible) return null;
+    const cache = readHeartbeat(coordRoot, nativeInstanceId);
+    const parent = generation.parent_generation_id
+      ? Object.values(view.instances).find(
+          (candidate) => candidate.generation_id === generation.parent_generation_id,
+        )
+      : undefined;
+    return projectHeartbeatV3(
+      coordRoot,
+      generation,
+      isCurrentCache(cache, generation) ? cache : undefined,
+      nativeInstanceId,
+      parent,
+    );
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the adapter from the current authority-safe V3 generation. A live
+ * V3 generation is stronger evidence than a missing or stale heartbeat, so
+ * callers must never substitute another adapter when this function succeeds.
+ */
+export function liveCoordinationAdapterV3(
+  coordRoot: string,
+  nativeInstanceId: string,
+): Adapter | null {
+  const route = resolveLiveEventLedgerRouteV3(coordRoot);
+  if (route.state === "blocked") throw new Error(`event_v3_coordination_view:${route.reason}`);
+  const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
+  const generation = view.instances[liveInstanceIdV3(nativeInstanceId)];
+  if (!generation?.authority_eligible) return null;
+  const adapter = observedAdapter(generation);
+  if (!isAdapter(adapter)) {
+    throw new Error("event_v3_coordination_view:adapter_not_observed");
+  }
+  return adapter;
+}
+
+/**
+ * Ensure the current V3 generation has a mutation target. The resulting file
+ * is explicitly generation-bound and disposable: V3 remains the source of
+ * truth, while the cache gives the crash-safe authority outbox an atomic local
+ * state to reconcile.
+ */
+export function ensureLiveCoordinationHeartbeat(
+  coordRoot: string,
+  nativeInstanceId: string,
+  nativeSessionId: string,
+  _adapter: Adapter,
+  model?: string,
+): Heartbeat | null {
+  const route = resolveLiveEventLedgerRouteV3(coordRoot);
+  if (route.state === "blocked") throw new Error(`event_v3_coordination_view:${route.reason}`);
+  const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
+  const generation = view.instances[liveInstanceIdV3(nativeInstanceId)];
+  if (!generation?.authority_eligible) return null;
+  const generationAdapter = observedAdapter(generation);
+  if (!isAdapter(generationAdapter)) {
+    throw new Error("event_v3_coordination_view:adapter_not_observed");
+  }
+  const current = readHeartbeat(coordRoot, nativeInstanceId);
+  if (isCurrentCache(current, generation) && current.platform === generationAdapter) return current;
+
+  const resolved = resolveName(coordRoot, nativeInstanceId, nativeSessionId);
+  const projected = projectHeartbeatV3(coordRoot, generation, undefined, nativeInstanceId);
+  const materialized: V3HeartbeatMaterialization = {
+    ...projected,
+    schema_version: 2,
+    instance_id: nativeInstanceId,
+    session_id: nativeSessionId,
+    name: resolved?.name ?? "",
+    kind: resolved?.kind ?? projected.kind,
+    agent_id: resolved?.agent_id ?? (resolved?.kind === "subagent" ? nativeInstanceId : ""),
+    model: projected.model ?? model ?? "",
+    platform: generationAdapter,
+    v3_instance_id: generation.instance_id as `inst_${string}`,
+    v3_generation_id: generation.generation_id as `gen_${string}`,
+    v3_projection_event_id: generation.last_event_id,
+    v3_task_state: generation.task_state === "set" ? "set" : "cleared",
+  };
+  writeHeartbeatCache(coordRoot, nativeInstanceId, materialized);
+  return materialized;
+}
+
+function readCacheRows(coordRoot: string): Heartbeat[] {
+  const dir = join(coordRoot, ".harnery", "active");
+  if (!existsSync(dir)) return [];
+  const rows: Heartbeat[] = [];
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith(".json")) continue;
+    try {
+      rows.push(JSON.parse(readFileSync(join(dir, file), "utf8")) as Heartbeat);
+    } catch {
+      // A partial heartbeat is ignored exactly as before.
+    }
+  }
+  return rows;
+}
+
+function readV3Caches(coordRoot: string): Heartbeat[] {
+  return readCacheRows(coordRoot).filter(
+    (row) => row.schema_version === 2 && typeof row.v3_generation_id === "string",
+  );
+}
+
+function matchingCache(
+  caches: Heartbeat[],
+  generation: CoordinationGenerationViewV3,
+): Heartbeat | undefined {
+  return caches.find((cache) => isCurrentCache(cache, generation));
+}
+
+function isCurrentCache(
+  cache: Heartbeat | null | undefined,
+  generation: CoordinationGenerationViewV3,
+): cache is Heartbeat {
+  return (
+    cache?.schema_version === 2 &&
+    cache.v3_instance_id === generation.instance_id &&
+    cache.v3_generation_id === generation.generation_id
+  );
+}
+
+function projectHeartbeatV3(
+  coordRoot: string,
+  generation: CoordinationGenerationViewV3,
+  cache: Heartbeat | undefined,
+  nativeInstanceId: string | undefined,
+  parent?: CoordinationGenerationViewV3,
+): V3HeartbeatMaterialization {
+  const adapter = observedAdapter(generation) ?? cache?.platform ?? "unknown";
+  const model = observedModel(generation) ?? cache?.model ?? "";
+  const instanceId =
+    nativeInstanceId ?? cache?.instance_id ?? nativeInstanceIdV3(generation.instance_id);
+  const durableIdentity = resolveName(
+    coordRoot,
+    instanceId,
+    cache?.session_id ?? generation.session_id,
+  );
+  const taskIsSet = generation.task_state === "set";
+  const lifecycle = isLifecycleState(generation.lifecycle_state)
+    ? generation.lifecycle_state
+    : "active";
+  return {
+    schema_version: 2,
+    instance_id: instanceId,
+    session_id: parent?.session_id ?? generation.session_id,
+    native_session_id: cache?.session_id,
+    name: cache?.name || durableIdentity?.name,
+    kind:
+      cache?.kind ??
+      durableIdentity?.kind ??
+      (generation.parent_generation_id || generation.delegation_id
+        ? "subagent"
+        : generation.workflow_id
+          ? "workflow-child"
+          : "session"),
+    agent_id: cache?.agent_id ?? durableIdentity?.agent_id,
+    model,
+    platform: adapter,
+    started_at: generation.started_at,
+    last_heartbeat: generation.last_observed_at,
+    files_touched: generation.files_touched,
+    ...(taskIsSet && cache?.task ? { task: cache.task } : {}),
+    task_updated_at: taskIsSet ? cache?.task_updated_at : null,
+    activity: generation.activity === "terminal" ? "idle" : generation.activity,
+    activity_updated_at: generation.last_observed_at,
+    activity_source: "event-v3-coordination-view",
+    task_state: lifecycle,
+    task_state_updated_at: generation.lifecycle_state_updated_at,
+    task_state_reason: lifecycle === "blocked" ? cache?.task_state_reason : undefined,
+    suggested_session_name: cache?.suggested_session_name,
+    session_name_seen_at: cache?.session_name_seen_at,
+    session_name_seen_for: cache?.session_name_seen_for,
+    workflow_run_id: generation.run_id,
+    workflow_agent_id: generation.workflow_agent_id,
+    parent_instance_id: parent ? nativeInstanceIdV3(parent.instance_id) : undefined,
+    v3_instance_id: generation.instance_id as `inst_${string}`,
+    v3_generation_id: generation.generation_id as `gen_${string}`,
+    v3_projection_event_id: generation.last_event_id,
+    v3_task_state: taskIsSet ? "set" : "cleared",
+  };
+}
+
+function observedAdapter(generation: CoordinationGenerationViewV3): string | undefined {
+  const observation = generation.runtime_attestation.adapter;
+  return observation.state === "observed" ? observation.value.id : undefined;
+}
+
+function isAdapter(value: string | undefined): value is Adapter {
+  return value === "claude-code" || value === "cursor" || value === "codex";
+}
+
+function observedModel(generation: CoordinationGenerationViewV3): string | undefined {
+  const observation = generation.runtime_attestation.model;
+  return observation.state === "observed" ? observation.value.id : undefined;
+}
+
+function isLifecycleState(value: string | undefined): value is "active" | "blocked" | "done" {
+  return value === "active" || value === "blocked" || value === "done";
+}
+
+function writeHeartbeatCache(coordRoot: string, instanceId: string, heartbeat: Heartbeat): void {
+  if (!/^[a-zA-Z0-9._-]{1,128}$/.test(instanceId)) {
+    throw new Error("instance_id is unsafe for heartbeat materialization");
+  }
+  const path = join(coordRoot, ".harnery", "active", `${instanceId}.json`);
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.tmp.${process.pid}`;
+  writeFileSync(temporary, JSON.stringify(heartbeat, null, 2), "utf8");
+  renameSync(temporary, path);
+}

package/src/core/agents/state/session-state.ts

@@ -0,0 +1,143 @@
+/** What the agent is doing now. `unknown` is evidence-safe, not an error. */
+export type AgentActivity = "unknown" | "working" | "needs_input" | "idle";
+
+/** Whether the declared task remains open. Activity never changes this axis. */
+export type TaskState = "active" | "blocked" | "done";
+
+/** Raw fields stored in the disposable V3 coordination cache and rebuilt from canonical events. */
+export interface SessionStateFields {
+  activity?: AgentActivity;
+  activity_updated_at?: string;
+  activity_source?: string;
+  task_state?: TaskState;
+  task_state_updated_at?: string;
+  task_state_reason?: string;
+}
+
+/** Reader-facing state with compatibility defaults applied. */
+export interface SessionState extends SessionStateFields {
+  activity: AgentActivity;
+  task_state: TaskState;
+}
+
+export interface SessionStateSelector {
+  instance_id?: string;
+  session_id?: string;
+}
+
+export interface SessionStateEvidenceEvent {
+  event_type: EventTypeV3;
+  ts: string;
+  payload?: Record<string, unknown>;
+  instance_id?: string;
+  session_id?: string;
+}
+
+const TERMINAL_ACTIVITY_EVENTS: ReadonlySet<EventTypeV3> = new Set([
+  "session.ended",
+  "agent.completed",
+  "turn.completed",
+]);
+
+/**
+ * Apply one canonical event to the two independent state axes.
+ *
+ * The table is deliberately evidence-only. Output chunks, post-tool events,
+ * narration, coordination commands, and elapsed time cannot clear an observed
+ * input wait. A command start only counts as progress when the session was
+ * already inside an open turn (`working` or `needs_input`).
+ */
+export function applySessionStateEvent(
+  current: Readonly<SessionStateFields>,
+  event: SessionStateEvidenceEvent,
+): SessionStateFields {
+  const next: SessionStateFields = { ...current };
+
+  if (
+    event.event_type === "session.started" ||
+    event.event_type === "session.resumed" ||
+    event.event_type === "agent.started"
+  ) {
+    setActivity(next, "idle", event);
+  } else if (event.event_type === "turn.started" || event.event_type === "tool.requested") {
+    setActivity(next, "working", event);
+  } else if (event.event_type === "wait.started") {
+    setActivity(next, "needs_input", event);
+  } else if (event.event_type === "wait.ended") {
+    setActivity(next, "working", event);
+  } else if (
+    event.event_type === "command.started" &&
+    (current.activity === "working" || current.activity === "needs_input")
+  ) {
+    setActivity(next, "working", event);
+  } else if (TERMINAL_ACTIVITY_EVENTS.has(event.event_type)) {
+    setActivity(next, "idle", event);
+  }
+
+  if (event.event_type === "coord.lifecycle_changed") {
+    const payload = event.payload ?? {};
+    const state = field(payload, "new_state");
+    if (state === "active" || state === "blocked" || state === "done") {
+      next.task_state = state;
+      next.task_state_updated_at = event.ts;
+      const reason = field(payload, "reason");
+      if (typeof reason === "string" && reason.length > 0) {
+        next.task_state_reason = reason;
+      } else {
+        delete next.task_state_reason;
+      }
+    }
+  }
+
+  return next;
+}
+
+/**
+ * Rebuild both axes from canonical events after a heartbeat has disappeared.
+ * Events may be the whole ledger or an already-filtered session slice.
+ */
+export function foldSessionState(
+  events: readonly SessionStateEvidenceEvent[],
+  selector: SessionStateSelector = {},
+): SessionState {
+  const ordered = events
+    .map((event, index) => ({ event, index }))
+    .filter(({ event }) => matches(event, selector))
+    .sort((a, b) => timestamp(a.event) - timestamp(b.event) || a.index - b.index);
+
+  let fields: SessionStateFields = {};
+  for (const { event } of ordered) fields = applySessionStateEvent(fields, event);
+
+  return {
+    ...fields,
+    activity: fields.activity ?? "unknown",
+    task_state: fields.task_state ?? "active",
+  };
+}
+
+function setActivity(
+  target: SessionStateFields,
+  activity: AgentActivity,
+  event: SessionStateEvidenceEvent,
+): void {
+  target.activity = activity;
+  target.activity_updated_at = event.ts;
+  target.activity_source = event.event_type;
+}
+
+function matches(event: SessionStateEvidenceEvent, selector: SessionStateSelector): boolean {
+  if (selector.instance_id && event.instance_id !== selector.instance_id) return false;
+  if (selector.session_id && event.session_id !== selector.session_id) return false;
+  return true;
+}
+
+function timestamp(event: SessionStateEvidenceEvent): number {
+  const parsed = Date.parse(event.ts);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function field(data: Record<string, unknown>, key: string): unknown {
+  return data[key];
+}
+
+import type { EventTypeV3 } from "../../events/v3/contract.ts";

package/src/core/agents/state/stale-sweep.ts

@@ -2,7 +2,7 @@
  * Stale-sweep: prune dead heartbeats + orphaned pid-map + .last-peer-hash
  * files.
  *
- * Fires at session.start to clean up crashed-peer detritus before the new
+ * Runs after session.started to clean up crashed-peer detritus before the new
  * session's UX layer reads peer state.
  *
  * Freshness threshold defaults to 600s; configurable via the
@@ -13,7 +13,7 @@
 import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { coordFreshnessSeconds } from "../../config.ts";
-import { emit } from "../events/emit.ts";
+import { recordLiveSweepObservationV3 } from "../live-lifecycle-v3.ts";
 
 /** platform → adapter, for the swept-event envelope (mirrors heartbeat-writer's adapterOf). */
 function adapterFromPlatform(platform: unknown): "claude-code" | "cursor" | "codex" {
@@ -22,7 +22,7 @@ function adapterFromPlatform(platform: unknown): "claude-code" | "cursor" | "cod
   return "claude-code";
 }
 
-/** Emit a best-effort health.heartbeat_swept event. Telemetry only, never throws. */
+/** Record the sweep before deleting authority state. V3 ambiguity fails closed. */
 function emitSwept(
   coordRoot: string,
   instanceId: string,
@@ -30,19 +30,24 @@ function emitSwept(
   sessionId: string,
   reason: "stale" | "unparseable" | "missing_ts",
   ageSecs?: number,
-): void {
+): boolean {
   try {
-    emit(coordRoot, {
-      event_type: "health.heartbeat_swept",
-      instance_id: instanceId,
-      session_id: sessionId,
+    recordLiveSweepObservationV3({
+      coordRoot,
+      owner: instanceId,
+      nativeSessionId: sessionId,
       adapter,
-      source: "agent-coord",
-      data: { reason, ...(ageSecs !== undefined ? { age_secs: ageSecs } : {}) },
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    } as Parameters<typeof emit>[1]);
+      observation:
+        reason === "stale"
+          ? "stale_heartbeat"
+          : reason === "unparseable"
+            ? "unparseable_heartbeat"
+            : "missing_timestamp",
+      ageMs: Math.max(0, (ageSecs ?? 0) * 1_000),
+    });
+    return true;
   } catch {
-    /* telemetry only, never break the sweep */
+    return false;
   }
 }
 
@@ -68,7 +73,7 @@ export function staleSweep(coordRoot: string): {
   const nowSec = Math.floor(Date.now() / 1000);
   const cutoff = nowSec - freshness;
 
-  // 1. Prune stale heartbeats from the canonical `.harnery/active/` dir.
+  // 1. Prune stale rows from the disposable V3 coordination cache.
   //
   // Two deletion regimes, deliberately asymmetric:
   //   • Valid JSON with an OLD last_heartbeat → the legitimate dead/idle-agent
@@ -105,9 +110,14 @@ export function staleSweep(coordRoot: string): {
         // Unparseable: only reap if the file itself is mtime-old.
         if (mtimeSecs(path) < cutoff) {
           try {
+            const ageSecs = nowSec - mtimeSecs(path);
+            if (
+              !emitSwept(coordRoot, idFromFile, "claude-code", idFromFile, "unparseable", ageSecs)
+            ) {
+              continue;
+            }
             unlinkSync(path);
             heartbeatsRemoved.push(f);
-            emitSwept(coordRoot, idFromFile, "claude-code", idFromFile, "unparseable");
           } catch {
             /* swallow */
           }
@@ -125,9 +135,20 @@ export function staleSweep(coordRoot: string): {
       if (!parsed.last_heartbeat || !Number.isFinite(ts)) {
         // No / NaN last_heartbeat: can't trust content; gate on mtime.
         if (mtimeSecs(path) < cutoff) {
+          if (
+            !emitSwept(
+              coordRoot,
+              instanceId,
+              adapter,
+              sessionId,
+              "missing_ts",
+              nowSec - mtimeSecs(path),
+            )
+          ) {
+            continue;
+          }
           unlinkSync(path);
           heartbeatsRemoved.push(f);
-          emitSwept(coordRoot, instanceId, adapter, sessionId, "missing_ts");
         } else if (parsed.instance_id) {
           liveInstanceIds.add(parsed.instance_id);
         }
@@ -136,9 +157,11 @@ export function staleSweep(coordRoot: string): {
 
       if (ts < cutoff) {
         // Legitimate stale prune (valid timestamp, past the freshness cutoff).
+        if (!emitSwept(coordRoot, instanceId, adapter, sessionId, "stale", nowSec - ts)) {
+          continue;
+        }
         unlinkSync(path);
         heartbeatsRemoved.push(f);
-        emitSwept(coordRoot, instanceId, adapter, sessionId, "stale", nowSec - ts);
         continue;
       }
 

package/src/core/artifacts/index.ts

@@ -22,6 +22,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
 import { artifactDefaultRetentionDays } from "../config.ts";
 
 export const ARTIFACTS_DIR = join(".harnery", "artifacts");
@@ -437,12 +438,10 @@ function ownerLiveness(
   now: Date,
   freshnessSeconds: number,
 ): "live" | "stale" | "unknown" {
-  const path = join(repoRoot, ".harnery", "active", `${instanceId}.json`);
-  if (!existsSync(path)) return "stale";
   try {
-    const hb = JSON.parse(readFileSync(path, "utf8")) as { last_heartbeat?: unknown };
-    if (typeof hb.last_heartbeat !== "string") return "unknown";
-    const ts = Date.parse(hb.last_heartbeat);
+    const row = readLiveCoordinationRow(repoRoot, instanceId);
+    if (!row) return "stale";
+    const ts = Date.parse(row.last_heartbeat);
     if (!Number.isFinite(ts)) return "unknown";
     return now.getTime() - ts <= freshnessSeconds * 1000 ? "live" : "stale";
   } catch {