harnery 0.32.0 → 0.34.0

package/dist/core/agents/state/heartbeat-writer.js

@@ -9,56 +9,20 @@
  * 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.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
-import { dirname, join } from "node:path";
-import { emit } from "../events/emit.js";
-/** 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) {
-    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) {
-    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, type, instanceId, hb, data) {
-    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.js";
 function heartbeatPath(coordRoot, instanceId) {
-    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() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -80,6 +44,16 @@ export function readHeartbeat(coordRoot, instanceId) {
         return null;
     }
 }
+/** Persist operator-facing lifecycle prose in the generation-bound cache only. */
+export function setLifecycleCache(coordRoot, instanceId, state, reason, suggestedSessionName) {
+    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, instanceId, fn) {
     const hb = readHeartbeat(coordRoot, instanceId);
     if (!hb)
@@ -104,10 +78,21 @@ export function setTask(coordRoot, instanceId, task) {
             ...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, instanceId, name, agentId) {
+    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
@@ -120,6 +105,16 @@ export function buildSuggestedName(agentName, descriptionParts) {
     const name = agentName?.trim() || "unknown";
     return { suggestedName: `Agent ${name} - ${description}`, description };
 }
+/** Build the sole lifecycle-driven title: the terminal done projection. */
+export function buildLifecycleSuggestedName(currentSessionName, state) {
+    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
@@ -132,13 +127,6 @@ export function stampSessionNameSeen(coordRoot, instanceId, name) {
         ...(name ? { session_name_seen_for: name } : {}),
     }));
 }
-export function setTurnSummary(coordRoot, instanceId, summary) {
-    return mutate(coordRoot, instanceId, (hb) => ({
-        ...hb,
-        turn_summary: summary,
-        turn_summary_updated_at: nowIsoSeconds(),
-    }));
-}
 export function releaseClaim(coordRoot, instanceId, path) {
     // files_touched can hold either absolute-under-coordRoot or canonical
     // monorepo-relative entries; normalize both sides so release matches
@@ -151,13 +139,22 @@ export function releaseClaim(coordRoot, instanceId, path) {
         files_touched: (hb.files_touched ?? []).filter((p) => norm(p) !== target),
     }));
 }
+/** Materialize one V3 write-claim authority transition into the heartbeat cache. */
+export function acquireClaim(coordRoot, instanceId, path) {
+    const norm = (p) => p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p;
+    const target = norm(path);
+    return mutate(coordRoot, instanceId, (hb) => ({
+        ...hb,
+        files_touched: [...new Set([...(hb.files_touched ?? []).map(norm), target])].sort(),
+    }));
+}
 /**
  * Session-group-wide unclaim. Walks every heartbeat sharing `groupId`
  * (parent's session_id == group_id;
  * 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
@@ -168,7 +165,7 @@ export function releaseClaim(coordRoot, instanceId, path) {
  * 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, groupId, path) {
+export function findGroupClaims(coordRoot, groupId, path) {
     const hits = [];
     if (!groupId || !path)
         return hits;
@@ -192,27 +189,17 @@ export function groupUnclaim(coordRoot, groupId, path) {
         if (peerSession !== groupId)
             continue;
         const files = body.files_touched ?? [];
-        const next = files.filter((p) => norm(p) !== target);
-        if (next.length === files.length)
+        if (!files.some((candidate) => norm(candidate) === target))
             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 ?? f.replace(/\.json$/, ""),
-                session_id: body.session_id,
-                platform: body.platform,
-            });
-        }
-        catch {
-            /* silent */
-        }
+        hits.push({
+            instance_id: body.instance_id ?? f.replace(/\.json$/, ""),
+            session_id: body.session_id,
+            platform: body.platform,
+        });
     }
     return hits;
 }
-export function killHeartbeat(coordRoot, instanceId) {
+export function clearCoordinationCache(coordRoot, instanceId) {
     const path = heartbeatPath(coordRoot, instanceId);
     if (!existsSync(path))
         return false;
@@ -244,131 +231,4 @@ export function healPidmap(coordRoot, instanceId, pid) {
     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, instanceId, sessionId, model, adapter, opts) {
-    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");
-        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 = {
-        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, opts) {
-    const now = nowIsoSeconds();
-    const prior = readHeartbeat(coordRoot, opts.instanceId);
-    const hb = {
-        ...(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, instanceId, toolName, target) {
-    return mutate(coordRoot, instanceId, (hb) => ({
-        ...hb,
-        last_tool: toolName,
-        last_tool_target: target,
-        last_tool_at: nowIsoSeconds(),
-    }));
 }

package/dist/core/agents/state/live-coordination-view.d.ts

@@ -0,0 +1,31 @@
+import type { Adapter } from "../../adapter.js";
+import { type Heartbeat } from "./heartbeat-writer.js";
+/**
+ * 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 declare function readLiveCoordinationRows(coordRoot: string): V3HeartbeatMaterialization[];
+/** Read one current row from the authority-safe V3 projection. */
+export declare function readLiveCoordinationRow(coordRoot: string, nativeInstanceId: string): V3HeartbeatMaterialization | 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 declare function liveCoordinationAdapterV3(coordRoot: string, nativeInstanceId: string): Adapter | null;
+/**
+ * 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 declare function ensureLiveCoordinationHeartbeat(coordRoot: string, nativeInstanceId: string, nativeSessionId: string, _adapter: Adapter, model?: string): Heartbeat | null;
+//# sourceMappingURL=live-coordination-view.d.ts.map

package/dist/core/agents/state/live-coordination-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-coordination-view.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/live-coordination-view.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAYhD,OAAO,EAAE,KAAK,SAAS,EAAiB,MAAM,uBAAuB,CAAC;AAGtE;;;GAGG;AACH,MAAM,WAAW,0BAA2B,SAAQ,SAAS;IAC3D,cAAc,EAAE,CAAC,CAAC;IAClB,cAAc,EAAE,QAAQ,MAAM,EAAE,CAAC;IACjC,gBAAgB,EAAE,OAAO,MAAM,EAAE,CAAC;IAClC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,aAAa,EAAE,KAAK,GAAG,SAAS,CAAC;CAClC;AAED,yEAAyE;AACzE,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,0BAA0B,EAAE,CA2BxF;AAED,kEAAkE;AAClE,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,GACvB,0BAA0B,GAAG,IAAI,CAuBnC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,GACvB,OAAO,GAAG,IAAI,CAWhB;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,EACxB,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,OAAO,EACjB,KAAK,CAAC,EAAE,MAAM,GACb,SAAS,GAAG,IAAI,CAgClB"}

package/dist/core/agents/state/live-coordination-view.js

@@ -0,0 +1,209 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { readCoordinationViewV3, requireAuthoritySafeCoordinationViewV3, } from "../../events/v3/coordination-view.js";
+import { liveInstanceIdV3, nativeInstanceIdV3, resolveLiveEventLedgerRouteV3, } from "../../events/v3/live-routing.js";
+import { readHeartbeat } from "./heartbeat-writer.js";
+import { resolveName } from "./names.js";
+/** Read the live coordination rows through the hard-cut ledger route. */
+export function readLiveCoordinationRows(coordRoot) {
+    const route = resolveLiveEventLedgerRouteV3(coordRoot);
+    if (route.state === "blocked")
+        return [];
+    let view;
+    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, nativeInstanceId) {
+    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, nativeInstanceId) {
+    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, nativeInstanceId, nativeSessionId, _adapter, model) {
+    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 = {
+        ...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,
+        v3_generation_id: generation.generation_id,
+        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) {
+    const dir = join(coordRoot, ".harnery", "active");
+    if (!existsSync(dir))
+        return [];
+    const rows = [];
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith(".json"))
+            continue;
+        try {
+            rows.push(JSON.parse(readFileSync(join(dir, file), "utf8")));
+        }
+        catch {
+            // A partial heartbeat is ignored exactly as before.
+        }
+    }
+    return rows;
+}
+function readV3Caches(coordRoot) {
+    return readCacheRows(coordRoot).filter((row) => row.schema_version === 2 && typeof row.v3_generation_id === "string");
+}
+function matchingCache(caches, generation) {
+    return caches.find((cache) => isCurrentCache(cache, generation));
+}
+function isCurrentCache(cache, generation) {
+    return (cache?.schema_version === 2 &&
+        cache.v3_instance_id === generation.instance_id &&
+        cache.v3_generation_id === generation.generation_id);
+}
+function projectHeartbeatV3(coordRoot, generation, cache, nativeInstanceId, parent) {
+    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,
+        v3_generation_id: generation.generation_id,
+        v3_projection_event_id: generation.last_event_id,
+        v3_task_state: taskIsSet ? "set" : "cleared",
+    };
+}
+function observedAdapter(generation) {
+    const observation = generation.runtime_attestation.adapter;
+    return observation.state === "observed" ? observation.value.id : undefined;
+}
+function isAdapter(value) {
+    return value === "claude-code" || value === "cursor" || value === "codex";
+}
+function observedModel(generation) {
+    const observation = generation.runtime_attestation.model;
+    return observation.state === "observed" ? observation.value.id : undefined;
+}
+function isLifecycleState(value) {
+    return value === "active" || value === "blocked" || value === "done";
+}
+function writeHeartbeatCache(coordRoot, instanceId, heartbeat) {
+    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/dist/core/agents/state/session-state.d.ts

@@ -0,0 +1,45 @@
+/** 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;
+}
+/**
+ * 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 declare function applySessionStateEvent(current: Readonly<SessionStateFields>, event: SessionStateEvidenceEvent): SessionStateFields;
+/**
+ * Rebuild both axes from canonical events after a heartbeat has disappeared.
+ * Events may be the whole ledger or an already-filtered session slice.
+ */
+export declare function foldSessionState(events: readonly SessionStateEvidenceEvent[], selector?: SessionStateSelector): SessionState;
+import type { EventTypeV3 } from "../../events/v3/contract.js";
+//# sourceMappingURL=session-state.d.ts.map

package/dist/core/agents/state/session-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-state.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/session-state.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,MAAM,CAAC;AAE3E,gFAAgF;AAChF,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAEtD,mGAAmG;AACnG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,+DAA+D;AAC/D,MAAM,WAAW,YAAa,SAAQ,kBAAkB;IACtD,QAAQ,EAAE,aAAa,CAAC;IACxB,UAAU,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,WAAW,CAAC;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAQD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACrC,KAAK,EAAE,yBAAyB,GAC/B,kBAAkB,CAwCpB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,yBAAyB,EAAE,EAC5C,QAAQ,GAAE,oBAAyB,GAClC,YAAY,CAcd;AA2BD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC"}