harnery 0.32.0 → 0.34.0

package/src/core/presence/blob.ts

@@ -6,9 +6,10 @@
  */
 
 import { createHash } from "node:crypto";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
 import { resolveMachineLabel } from "../../lib/machine.ts";
+import { readLiveCoordinationRows } from "../agents/state/live-coordination-view.ts";
+import type { AgentActivity, TaskState } from "../agents/state/session-state.ts";
+import { buildPresenceCodecDigests, type PresenceCodecDigest } from "./codec-digest.ts";
 
 /** Mirror of the local heartbeat freshness window (commands/agents.ts). */
 const FRESHNESS_SECS = 600;
@@ -24,11 +25,14 @@ export interface PresenceAgent {
   session_id?: string;
   platform?: string;
   task?: string;
-  turn_summary?: string;
+  activity: AgentActivity;
+  task_state: TaskState;
+  task_state_reason?: string;
   files_touched?: string[];
-  last_tool?: string;
   started_at?: string;
   last_heartbeat?: string;
+  /** Strict content-free activity evidence for remote Codec panels. */
+  codec?: PresenceCodecDigest;
 }
 
 export interface PresenceBlob {
@@ -47,7 +51,7 @@ export interface BuiltBlob {
 }
 
 /**
- * Build this machine's presence blob from `.harnery/active/` heartbeats.
+ * Build this machine's presence blob from the authority-safe V3 projection.
  * Includes live sessions + subagents; excludes kind=transient stubs (they are
  * fold-artifacts of the local claim model, not sessions) and anything past the
  * freshness window.
@@ -55,38 +59,32 @@ export interface BuiltBlob {
 export function buildPresenceBlob(coordRoot: string, now: Date = new Date()): BuiltBlob {
   const machine = resolveMachineLabel();
   const agents: PresenceAgent[] = [];
-  const activeDir = join(coordRoot, ".harnery", "active");
+  const codecDigests = buildPresenceCodecDigests(coordRoot);
   const cutoffMs = now.getTime() - FRESHNESS_SECS * 1000;
 
-  if (existsSync(activeDir)) {
-    for (const f of readdirSync(activeDir)) {
-      if (!f.endsWith(".json")) continue;
-      let hb: Record<string, unknown>;
-      try {
-        hb = JSON.parse(readFileSync(join(activeDir, f), "utf8")) as Record<string, unknown>;
-      } catch {
-        continue;
-      }
-      if (typeof hb.instance_id !== "string") continue;
-      if ((hb.kind as string | undefined) === "transient") continue;
-      const ts = Date.parse((hb.last_heartbeat as string | undefined) ?? "");
-      if (!Number.isFinite(ts) || ts < cutoffMs) continue;
-      agents.push({
-        instance_id: hb.instance_id,
-        name: strOr(hb.name),
-        kind: strOr(hb.kind),
-        session_id: strOr(hb.session_id),
-        platform: strOr(hb.platform),
-        task: strOr(hb.task),
-        turn_summary: clamp(strOr(hb.turn_summary), 160),
-        files_touched: Array.isArray(hb.files_touched)
-          ? (hb.files_touched as string[]).slice(0, MAX_FILES_PER_AGENT)
-          : undefined,
-        last_tool: strOr(hb.last_tool),
-        started_at: strOr(hb.started_at),
-        last_heartbeat: strOr(hb.last_heartbeat),
-      });
-    }
+  for (const row of readLiveCoordinationRows(coordRoot)) {
+    if (row.kind === "transient") continue;
+    const ts = Date.parse(row.last_heartbeat);
+    if (!Number.isFinite(ts) || ts < cutoffMs) continue;
+    agents.push({
+      instance_id: row.instance_id,
+      name: strOr(row.name),
+      kind: strOr(row.kind),
+      session_id: strOr(row.session_id),
+      platform: strOr(row.platform),
+      task: strOr(row.task),
+      activity: activityOrUnknown(row.activity),
+      task_state: taskStateOrActive(row.task_state),
+      task_state_reason: clamp(strOr(row.task_state_reason), 160),
+      files_touched: row.files_touched.slice(0, MAX_FILES_PER_AGENT),
+      started_at: strOr(row.started_at),
+      last_heartbeat: row.last_heartbeat,
+      codec:
+        codecDigests.get(row.instance_id) ??
+        codecDigests.get(
+          row.instance_id.startsWith("inst_") ? row.instance_id : `inst_${row.instance_id}`,
+        ),
+    });
   }
 
   agents.sort((a, b) => a.instance_id.localeCompare(b.instance_id));
@@ -100,15 +98,18 @@ export function buildPresenceBlob(coordRoot: string, now: Date = new Date()): Bu
   };
 
   // Basis: the fields whose change should trigger a re-publish. Timestamps
-  // and last_tool are excluded (pure churn); task/turn_summary/files are the
-  // signal peers actually read.
+  // Observation timestamps are excluded as pure churn; task/lifecycle/files
+  // are the signals peers actually read.
   const basis = capped.map((a) => ({
     i: a.instance_id,
     n: a.name ?? null,
     k: a.kind ?? null,
     t: a.task ?? null,
-    s: a.turn_summary ?? null,
+    a: a.activity,
+    l: a.task_state,
+    r: a.task_state_reason ?? null,
     f: [...(a.files_touched ?? [])].sort(),
+    c: codecBasis(a.codec),
   }));
   const basisHash = createHash("sha256").update(JSON.stringify(basis)).digest("hex").slice(0, 16);
 
@@ -119,7 +120,31 @@ function strOr(v: unknown): string | undefined {
   return typeof v === "string" && v.length > 0 ? v : undefined;
 }
 
+function activityOrUnknown(v: unknown): AgentActivity {
+  return v === "working" || v === "needs_input" || v === "idle" ? v : "unknown";
+}
+
+function taskStateOrActive(v: unknown): TaskState {
+  return v === "blocked" || v === "done" ? v : "active";
+}
+
 function clamp(v: string | undefined, max: number): string | undefined {
   if (!v) return undefined;
   return v.length > max ? v.slice(0, max) : v;
 }
+
+function codecBasis(codec: PresenceCodecDigest | undefined): unknown {
+  if (!codec) return null;
+  return {
+    o: codec.operation
+      ? { category: codec.operation.category, label: codec.operation.label }
+      : null,
+    c: codec.context
+      ? { used_percent: codec.context.used_percent, confidence: codec.context.confidence }
+      : null,
+    a: codec.recent_actions.map((action) => ({
+      category: action.category,
+      outcome: action.outcome,
+    })),
+  };
+}

package/src/core/presence/codec-digest.ts

@@ -0,0 +1,215 @@
+import type { EventV3 } from "../events/v3/contract.ts";
+import { readLedgerV3 } from "../events/v3/reader.ts";
+
+export type PresenceCodecCategory =
+  | "research"
+  | "diagnostic"
+  | "build"
+  | "edit"
+  | "test"
+  | "coordinate"
+  | "other";
+
+export interface PresenceCodecAction {
+  category: PresenceCodecCategory;
+  outcome: "ok" | "error" | "unknown";
+  event_id: string;
+  observed_at: string;
+}
+
+export interface PresenceCodecDigest {
+  schema_version: 1;
+  observed_at: string;
+  operation?: {
+    category: PresenceCodecCategory;
+    label: string;
+    event_id: string;
+    observed_at: string;
+  };
+  context?: {
+    used_percent: number;
+    confidence: "exact" | "reported" | "estimated";
+    event_id: string;
+    observed_at: string;
+  };
+  recent_actions: PresenceCodecAction[];
+}
+
+interface Slot {
+  observedAt?: string;
+  open: Map<string, NonNullable<PresenceCodecDigest["operation"]>>;
+  context?: PresenceCodecDigest["context"];
+  actions: PresenceCodecAction[];
+}
+
+const MAX_LEDGER_ROWS = 5_000;
+const MAX_ACTIONS = 3;
+
+/** Build a strict, content-free per-instance digest for encrypted presence. */
+export function buildPresenceCodecDigests(coordRoot: string): Map<string, PresenceCodecDigest> {
+  const read = readLedgerV3(coordRoot);
+  if (!read.complete) return new Map();
+  return projectPresenceCodecDigests(read.events.slice(-MAX_LEDGER_ROWS).map((row) => row.event));
+}
+
+export function projectPresenceCodecDigests(
+  events: readonly EventV3[],
+): Map<string, PresenceCodecDigest> {
+  const slots = new Map<string, Slot>();
+  const get = (instanceId: string) => {
+    let slot = slots.get(instanceId);
+    if (!slot) {
+      slot = { open: new Map(), actions: [] };
+      slots.set(instanceId, slot);
+    }
+    return slot;
+  };
+
+  for (const event of events) {
+    if (!("instance_id" in event.scope)) continue;
+    const slot = get(event.scope.instance_id);
+    slot.observedAt = event.time.observed_at;
+    const spanId = (event.links as { span_id?: string }).span_id;
+    switch (event.event_type) {
+      case "tool.requested":
+        if (spanId) {
+          slot.open.set(spanId, {
+            category: categorize(event.payload.tool.namespace, event.payload.tool.name),
+            label: operationLabel(event.payload.tool.namespace, event.payload.tool.name),
+            event_id: event.event_id,
+            observed_at: event.time.observed_at,
+          });
+        }
+        break;
+      case "command.started":
+        if (spanId) {
+          slot.open.set(spanId, {
+            category: "diagnostic",
+            label: "Running a command",
+            event_id: event.event_id,
+            observed_at: event.time.observed_at,
+          });
+        }
+        break;
+      case "wait.started":
+        slot.open.set(event.payload.wait_id, {
+          category: "coordinate",
+          label: "Waiting",
+          event_id: event.event_id,
+          observed_at: event.time.observed_at,
+        });
+        break;
+      case "tool.completed":
+      case "command.completed":
+        if (spanId) slot.open.delete(spanId);
+        pushAction(slot, {
+          category:
+            event.event_type === "tool.completed"
+              ? categorize(event.payload.tool.namespace, event.payload.tool.name)
+              : "diagnostic",
+          outcome: outcome(event.payload.outcome),
+          event_id: event.event_id,
+          observed_at: event.time.observed_at,
+        });
+        break;
+      case "wait.ended":
+        slot.open.delete(event.payload.wait_id);
+        pushAction(slot, {
+          category: "coordinate",
+          outcome: outcome(event.payload.outcome),
+          event_id: event.event_id,
+          observed_at: event.time.observed_at,
+        });
+        break;
+      case "progress.observed":
+        pushAction(slot, {
+          category: progressCategory(event.payload.kind),
+          outcome: "ok",
+          event_id: event.event_id,
+          observed_at: event.time.observed_at,
+        });
+        break;
+      case "context.observed": {
+        const measurement = event.payload.measurement;
+        if (measurement.state === "observed" && measurement.value.limit_tokens > 0) {
+          slot.context = {
+            used_percent: Math.min(
+              100,
+              Math.max(
+                0,
+                Math.round((measurement.value.used_tokens / measurement.value.limit_tokens) * 100),
+              ),
+            ),
+            confidence: measurement.confidence === "exact" ? "exact" : "reported",
+            event_id: event.event_id,
+            observed_at: event.time.observed_at,
+          };
+        }
+        break;
+      }
+      case "turn.completed":
+      case "session.ended":
+      case "agent.completed":
+        slot.open.clear();
+        break;
+      default:
+        break;
+    }
+  }
+
+  const digests = new Map<string, PresenceCodecDigest>();
+  for (const [instanceId, slot] of slots) {
+    if (!slot.observedAt) continue;
+    const operation = [...slot.open.values()].at(-1);
+    digests.set(instanceId, {
+      schema_version: 1,
+      observed_at: slot.observedAt,
+      ...(operation ? { operation } : {}),
+      ...(slot.context ? { context: slot.context } : {}),
+      recent_actions: slot.actions,
+    });
+  }
+  return digests;
+}
+
+function pushAction(slot: Slot, action: PresenceCodecAction): void {
+  slot.actions.push(action);
+  if (slot.actions.length > MAX_ACTIONS) slot.actions.shift();
+}
+
+function outcome(value: string): PresenceCodecAction["outcome"] {
+  return value === "succeeded" ? "ok" : value === "failed" ? "error" : "unknown";
+}
+
+function categorize(namespace: string, name: string): PresenceCodecCategory {
+  const key = `${namespace}/${name}`.toLowerCase();
+  if (/agent|message|plan|workflow|council|decide/.test(key)) return "coordinate";
+  if (/patch|edit|write|create/.test(key)) return "edit";
+  if (/test|playwright|vitest|jest/.test(key)) return "test";
+  if (/publish|deploy|image|document|spreadsheet|presentation/.test(key)) return "build";
+  if (/search|read|grep|glob|fetch|browser|view/.test(key)) return "research";
+  if (/exec|command|shell|bash|terminal/.test(key)) return "diagnostic";
+  return "other";
+}
+
+function operationLabel(namespace: string, name: string): string {
+  const category = categorize(namespace, name);
+  return {
+    research: "Researching",
+    diagnostic: "Running a command",
+    build: "Building",
+    edit: "Editing files",
+    test: "Testing",
+    coordinate: "Coordinating",
+    other: "Working",
+  }[category];
+}
+
+function progressCategory(kind: string): PresenceCodecCategory {
+  if (kind === "write") return "edit";
+  if (kind === "test") return "test";
+  if (kind === "commit" || kind === "deploy" || kind === "publication") return "build";
+  if (kind === "review") return "coordinate";
+  if (kind === "artifact") return "build";
+  return "other";
+}

package/src/core/presence/index.ts

@@ -263,7 +263,7 @@ export function readRemoteMachines(
         machine,
         published_at: blob.published_at,
         age_secs: ageSecs,
-        agents: blob.agents,
+        agents: blob.agents.map(normalizePresenceAgent),
       });
     }
     out.sort((a, b) => a.machine.localeCompare(b.machine));
@@ -272,3 +272,20 @@ export function readRemoteMachines(
     return [];
   }
 }
+
+function normalizePresenceAgent(agent: PresenceAgent): PresenceAgent {
+  const legacy = agent as Partial<PresenceAgent>;
+  return {
+    ...agent,
+    activity:
+      legacy.activity === "working" ||
+      legacy.activity === "needs_input" ||
+      legacy.activity === "idle"
+        ? legacy.activity
+        : "unknown",
+    task_state:
+      legacy.task_state === "blocked" || legacy.task_state === "done"
+        ? legacy.task_state
+        : "active",
+  };
+}

package/src/core/presence/relay-client.ts

@@ -9,7 +9,7 @@
  *   - derives the room credentials from the repo identity (root-commit SHA +
  *     origin URL + optional committed `.harnery/presence-salt`)
  *   - holds the socket open with auto-reconnect + jittered backoff
- *   - watches `.harnery/active/` and publishes the encrypted presence blob on
+ *   - watches the active V3 ledger and publishes the encrypted presence blob on
  *     change (debounced), plus a 60s keepalive so peers' staleness math works
  *   - decrypts received peer frames and writes them to
  *     `.harnery/presence/remote/<machine>.json`, where `readRemoteMachines`
@@ -36,6 +36,7 @@ import {
 import { join } from "node:path";
 import { resolveMachineLabel } from "../../lib/machine.ts";
 import { presenceRelayUrl } from "../config.ts";
+import { eventV3ActiveWatchPath } from "../events/v3/reader.ts";
 import { buildPresenceBlob, type PresenceBlob } from "./blob.ts";
 import { originUrl, rootCommitSha, sanitizeRefComponent } from "./git.ts";
 import {
@@ -259,12 +260,11 @@ export async function runRelayDaemon(coordRoot: string): Promise<number> {
 
   connect();
 
-  // Publish on heartbeat change (debounced).
+  // Publish on canonical V3 ledger change (debounced).
   let debounce: ReturnType<typeof setTimeout> | null = null;
-  const activeDir = join(coordRoot, ".harnery", "active");
-  mkdirSync(activeDir, { recursive: true });
+  const activeLedger = eventV3ActiveWatchPath(coordRoot);
   try {
-    watch(activeDir, () => {
+    watch(activeLedger, () => {
       if (debounce) clearTimeout(debounce);
       debounce = setTimeout(() => void publishNow(), WATCH_DEBOUNCE_MS);
     });

package/src/core/work/index.ts

@@ -6,6 +6,7 @@ export {
   cancelWorkItem,
   createWorkItem,
   listWorkItems,
+  listWorkItemsWithWarnings,
   newWorkId,
   openOperatorFindings,
   readWorkItem,
@@ -19,6 +20,8 @@ export {
   type WorkEvent,
   type WorkEventType,
   type WorkIntent,
+  type WorkListResult,
+  type WorkListWarning,
   type WorkNextAction,
   type WorkProjection,
   type WorkRecord,

package/src/core/work/read.ts

@@ -1,6 +1,7 @@
 export {
   assertWorkId,
   listWorkItems,
+  listWorkItemsWithWarnings,
   readWorkItem,
   WORK_EVENT_SCHEMA_VERSION,
   WORK_INTENT_SCHEMA_VERSION,
@@ -9,6 +10,8 @@ export {
   type WorkEvent,
   type WorkEventType,
   type WorkIntent,
+  type WorkListResult,
+  type WorkListWarning,
   type WorkNextAction,
   type WorkProjection,
   type WorkRecord,

package/src/core/work/runner.ts

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { runWorkflow } from "../workflow/engine.ts";
 import { readWorkflowProof } from "../workflow/proof.ts";
+import { readWorkflowRunManifest } from "../workflow/run-state.ts";
 import type {
   EngineOpts,
   RunReport,
@@ -80,10 +81,14 @@ export async function runWorkItem(input: RunWorkItemInput): Promise<RunReport> {
     const attempt = record.projection.attempts_used + 1;
     const trigger = input.retry ? "retry" : "initial";
     let prior: WorkflowAttemptContext["prior"];
+    let specialists = input.engine.specialists;
     if (trigger === "retry") {
       if (!latest) {
         throw new Error(`work item ${input.workId} has no prior attempt to retry`);
       }
+      if (specialists === undefined && latest.proof_path) {
+        specialists = readWorkflowRunManifest(coordRoot, latest.run_id).execution.specialists;
+      }
       prior = priorContext(coordRoot, latest);
     }
     const open = openOperatorFindings(coordRoot, input.workId);
@@ -110,6 +115,7 @@ export async function runWorkItem(input: RunWorkItemInput): Promise<RunReport> {
     });
     return await runWorkflow(record.intent.workflow.path, {
       ...input.engine,
+      specialists,
       coordRoot,
       runId,
       workItemId: input.workId,

package/src/core/work/state.ts

@@ -181,6 +181,16 @@ export interface WorkRecord {
   projection: WorkProjection;
 }
 
+export interface WorkListWarning {
+  work_id: string;
+  reason: string;
+}
+
+export interface WorkListResult {
+  records: WorkRecord[];
+  warnings: WorkListWarning[];
+}
+
 export interface CreateWorkItemInput {
   coordRoot: string;
   title: string;
@@ -271,14 +281,28 @@ export function readWorkItem(coordRoot: string, workId: string): WorkRecord {
 }
 
 export function listWorkItems(coordRoot: string): WorkRecord[] {
+  return listWorkItemsWithWarnings(coordRoot).records;
+}
+
+export function listWorkItemsWithWarnings(coordRoot: string): WorkListResult {
   const base = join(resolve(coordRoot), ".harnery", "work");
-  if (!existsSync(base)) return [];
+  if (!existsSync(base)) return { records: [], warnings: [] };
   const records: WorkRecord[] = [];
+  const warnings: WorkListWarning[] = [];
   for (const name of readdirSync(base)) {
     if (!WORK_ID.test(name) || !existsSync(join(base, name, "intent.json"))) continue;
-    records.push(readWorkItem(coordRoot, name));
+    try {
+      records.push(readWorkItem(coordRoot, name));
+    } catch (error) {
+      warnings.push({
+        work_id: name,
+        reason: error instanceof Error ? error.message : String(error),
+      });
+    }
   }
-  return records.sort((a, b) => b.intent.created_at.localeCompare(a.intent.created_at));
+  records.sort((a, b) => b.intent.created_at.localeCompare(a.intent.created_at));
+  warnings.sort((a, b) => a.work_id.localeCompare(b.work_id));
+  return { records, warnings };
 }
 
 export function reconcileWorkItem(coordRoot: string, workId: string, actor?: string): WorkRecord {

package/src/core/workflow/engine.ts

@@ -21,7 +21,6 @@ import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { killHeartbeat, registerWorkflowChild } from "../agents/state/heartbeat-writer.ts";
 import { snapshotRepo } from "../context/index.ts";
 import type {
   ExternalMutationRequest,
@@ -41,6 +40,7 @@ import { freezeWorkflowAttemptContext } from "./attempt-context.ts";
 import { type BillingProbe, probeBilling } from "./billing.ts";
 import { stableDigest } from "./durable-record.ts";
 import { evidencePreflightError } from "./evidence-preflight.ts";
+import { endWorkflowChildSessionV3, startWorkflowChildSessionV3 } from "./live-session-v3.ts";
 import {
   buildWorkflowProof,
   createEvidenceRecord,
@@ -947,23 +947,18 @@ async function executeWorkflow(
       });
       log(`[${name}] ${currentStage || "(no stage)"} → ${id} [${adapter}] ${label}`);
 
-      // Register the child ourselves rather than trusting its adapter to fire
-      // Harnery's hooks. Headless `codex exec` fires none, so codex children
-      // were invisible to `harn agents list` and the run page for the whole
-      // duration of a stage. The engine knows everything the heartbeat needs.
-      // Best-effort: coordination visibility must never fail a run.
-      try {
-        registerWorkflowChild(opts.coordRoot, {
-          instanceId: childInstanceId(runId, id),
-          runId,
-          agentId: id,
-          adapter,
-          label,
-          model: agentOpts.model,
-        });
-      } catch {
-        /* visibility is not worth failing a spawn over */
-      }
+      // Headless children do not reliably fire adapter hooks. The engine owns
+      // their canonical V3 start so every dispatched child has an auditable
+      // generation before it begins work.
+      startWorkflowChildSessionV3({
+        coordRoot: opts.coordRoot,
+        instanceId: childInstanceId(runId, id),
+        runId,
+        agentId: id,
+        adapter,
+        label,
+        model: agentOpts.model,
+      });
 
       let attemptPrompt = dispatchPrompt;
       let last: SpawnResult | null = null;
@@ -1077,13 +1072,18 @@ async function executeWorkflow(
       throw error;
     } finally {
       reservedCostUsd = Math.max(0, reservedCostUsd - reservedForDispatch);
-      // Deregister on every exit path, including throw. A child heartbeat that
-      // outlives its process reads as a live agent forever and blocks peers on
-      // its stale claims. The transcript remains the durable record.
+      // Record the canonical terminal before removing the disposable cache.
       try {
-        killHeartbeat(opts.coordRoot, childInstanceId(runId, id));
-      } catch {
-        /* already gone, or swept */
+        endWorkflowChildSessionV3({
+          coordRoot: opts.coordRoot,
+          instanceId: childInstanceId(runId, id),
+          runId,
+          agentId: id,
+          adapter,
+          cleanExit: agentProof.status === "succeeded",
+        });
+      } catch (error) {
+        log(`[${name}] V3 terminal recording failed: ${(error as Error).message}`);
       }
       release();
     }