harnery 0.38.0 → 0.40.0

package/src/core/agents/cli.ts

@@ -260,7 +260,10 @@ async function handleStateAction(root: string, action: string, rest: string[]):
         // same durable, idempotent pool path used by normal SessionStart.
         if (task && before && humanFacing && !before.name?.trim()) {
           const { assignName } = await import("./state/names.ts");
-          const name = assignName(root, owner, "session");
+          const { coordFreshnessSeconds } = await import("../config.ts");
+          const name = assignName(root, owner, "session", {
+            freshnessSecs: coordFreshnessSeconds(root),
+          });
           before = writer.setAssignedNameCache(root, owner, name, "session");
           if (!before) {
             process.stderr.write(
@@ -302,7 +305,10 @@ async function handleStateAction(root: string, action: string, rest: string[]):
             (!hb.name?.trim() || /^Agent unknown - /.test(hb.suggested_session_name ?? ""))
           ) {
             const { assignName } = await import("./state/names.ts");
-            const name = hb.name?.trim() || assignName(root, owner, "session");
+            const { coordFreshnessSeconds } = await import("../config.ts");
+            const name =
+              hb.name?.trim() ||
+              assignName(root, owner, "session", { freshnessSecs: coordFreshnessSeconds(root) });
             hb = writer.setAssignedNameCache(root, owner, name, "session");
           }
         } catch (error) {
@@ -640,7 +646,11 @@ async function handleAssignName(root: string, rest: string[]): Promise<number> {
     process.stderr.write(`agent-coord assign-name: invalid kind ${kindArg}\n`);
     return 2;
   }
-  const name = assignName(root, owner, kindArg, forkedFrom ? { forkedFrom } : undefined);
+  const { coordFreshnessSeconds } = await import("../config.ts");
+  const name = assignName(root, owner, kindArg, {
+    freshnessSecs: coordFreshnessSeconds(root),
+    ...(forkedFrom ? { forkedFrom } : {}),
+  });
   process.stdout.write(
     `${JSON.stringify({
       instance_id: owner,
@@ -761,7 +771,6 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
   const instanceId = args.instance;
   const sessionId = args.session ?? instanceId;
   const agentName = args.name;
-  const adapter = args.adapter;
   const sessionNameNudge = args["session-name-nudge"] === "true";
   const taskNudge = args["task-nudge"] === "true";
   const hostPromptReminder = args["host-prompt-reminder"] === "true";
@@ -772,7 +781,7 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
     args["turn-ritual-nudge"] === "true" ? "generic" : args["turn-ritual-nudge"];
   if (!instanceId) {
     process.stderr.write(
-      "agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--adapter <id>] [--session-name-nudge] [--task-nudge] [--host-prompt-reminder] [--status-footer-nudge] [--turn-ritual-nudge <adapter>]\n",
+      "agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--session-name-nudge] [--task-nudge] [--host-prompt-reminder] [--status-footer-nudge] [--turn-ritual-nudge <adapter>]\n",
     );
     return 2;
   }
@@ -787,7 +796,6 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
     hostPromptReminder,
     statusFooterNudge,
     turnRitualNudge,
-    adapter,
   });
   process.stdout.write(text);
   return 0;

package/src/core/agents/live-authority-v3.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { Adapter } from "../adapter.ts";
+import { EVENT_ADAPTER_IDS_V3 } from "../events/v3/adapter-id.ts";
 import type { AuthorityMutationV3 } from "../events/v3/authority-outbox.ts";
 import { canonicalJsonV3, normalizeNativeIdV3, sha256V3 } from "../events/v3/canonical.ts";
 import { type EventV3WriteMode, readEventV3ControlState } from "../events/v3/control.ts";
@@ -246,9 +247,9 @@ function readSessionProducerStatesForBootstrap(
   nativeSessionId: string,
 ): HookProducerStateV3[] {
   try {
-    return (["claude-code", "codex", "cursor"] as const)
-      .map((adapter) => readHookProducerStateV3(coordRoot, adapter, nativeSessionId))
-      .filter((state): state is HookProducerStateV3 => state !== undefined);
+    return EVENT_ADAPTER_IDS_V3.map((adapter) =>
+      readHookProducerStateV3(coordRoot, adapter, nativeSessionId),
+    ).filter((state): state is HookProducerStateV3 => state !== undefined);
   } catch {
     throw new LiveCoordinationAuthorityV3Error("producer_state_unsafe");
   }
@@ -424,6 +425,9 @@ export function reopenLiveCoordinationGenerationV3(input: {
   if (!terminalView || terminalView.instance_id !== instanceId) {
     throw new LiveCoordinationAuthorityV3Error("terminal_generation_authority_missing");
   }
+  if (terminal.adapter === "openclaw") {
+    throw new LiveCoordinationAuthorityV3Error("lifecycle_not_human_facing");
+  }
   if (terminalView.parent_generation_id || terminalView.delegation_id || terminalView.workflow_id) {
     throw new LiveCoordinationAuthorityV3Error("lifecycle_not_human_facing");
   }

package/src/core/agents/live-lifecycle-v3.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import type { Adapter } from "../adapter.ts";
+import type { EventAdapterIdV3 } from "../events/v3/adapter-id.ts";
 import { buildEventV3 } from "../events/v3/builder.ts";
 import { normalizeNativeIdV3 } from "../events/v3/canonical.ts";
 import type { EventV3 } from "../events/v3/contract.ts";
@@ -21,7 +21,7 @@ interface LiveLifecycleObservationBaseV3 {
   coordRoot: string;
   owner: string;
   nativeSessionId: string;
-  adapter: Adapter;
+  adapter: EventAdapterIdV3;
   observedAt?: string;
 }
 

package/src/core/agents/render/prompt-context.ts

@@ -46,12 +46,13 @@ import {
 import { join } from "node:path";
 
 import { coordEnv } from "../../../lib/env.ts";
-import type { Adapter } from "../../adapter.ts";
 import { endOfTurnStatusCommand, hostPromptReminder, resolveBinName } from "../../config.ts";
-import { canReceiveContext } from "../../hooks/adapter/output.ts";
+import type { PressureWorkloadClass } from "../../diagnostics/contract.ts";
 import { type RemoteMachine, readRemoteMachines } from "../../presence/index.ts";
+import { readResourceStatus } from "../../resources/status.ts";
 import { drainMailbox, formatMailboxDelivery } from "../mailbox.ts";
 import { sessionNameDisplayBlock, sessionNameDisplayPending } from "../session-name-display.ts";
+import { heartbeatPath } from "../state/heartbeat-reader.ts";
 import {
   readLiveCoordinationRow,
   readLiveCoordinationRows,
@@ -95,11 +96,6 @@ export interface PromptContextOpts {
   /** When true, append the non-deduplicated Codex status-footer reminder.
    * The caller enables this only for human-facing Codex sessions. */
   statusFooterNudge?: boolean;
-  /** Adapter id this prompt is being rendered for. Gates the mailbox drain:
-   * an adapter that cannot receive UserPromptSubmit context must not consume
-   * messages here, or they are removed from the queue and never shown. When
-   * omitted, delivery is attempted (the default route can receive). */
-  adapter?: string;
   /** Adapter id whose Stop hook ENFORCES the end-of-turn ritual (task_set +
    * status check). When set, append a fresh per-prompt reminder of that
    * contract so the model satisfies it before ending the turn instead of
@@ -127,7 +123,6 @@ export function renderPromptContext(opts: PromptContextOpts): string {
     hostPromptReminder: promptReminderEnabled,
     statusFooterNudge,
     turnRitualNudge,
-    adapter,
   } = opts;
   const sections: string[] = [];
 
@@ -140,12 +135,7 @@ export function renderPromptContext(opts: PromptContextOpts): string {
   // exactly once, and it is the one section here that carries new information
   // from another agent rather than a reminder.
   //
-  // Draining is gated on the adapter being able to receive this event's
-  // context. Cursor cannot, so draining there would empty the queue into output
-  // that is discarded; those sessions get their messages at SessionStart, which
-  // Cursor does deliver.
-  const canDeliverHere = !adapter || canReceiveContext(adapter as Adapter, "UserPromptSubmit");
-  if (resolvedName && canDeliverHere) {
+  if (resolvedName) {
     const delivered = drainMailbox(coordRoot, resolvedName);
     if (delivered.length > 0) {
       recordDeliveredMessages(instanceId, delivered);
@@ -157,6 +147,9 @@ export function renderPromptContext(opts: PromptContextOpts): string {
   const peerTable = computePeerTableIfChanged(coordRoot, instanceId, sessionId);
   if (peerTable) sections.push(peerTable);
 
+  const resources = resourceWarningIfChanged(coordRoot, instanceId);
+  if (resources) sections.push(resources);
+
   // 3. Council pending with hash dedup.
   if (resolvedName) {
     const councilMsg = computeCouncilPendingIfChanged(coordRoot, instanceId, resolvedName);
@@ -203,6 +196,67 @@ export function renderPromptContext(opts: PromptContextOpts): string {
   return sections.join("\n\n");
 }
 
+/**
+ * Prompts receive the published assessment, and only when it changes in a way
+ * that changes what an agent should do. The dedupe key is scope, state, and
+ * recommended action, so a moving number or a different contributor does not
+ * re-emit the same advice.
+ */
+export function resourceWarningIfChanged(coordRoot: string, instanceId: string): string {
+  try {
+    heartbeatPath(coordRoot, instanceId);
+    const status = readResourceStatus(coordRoot);
+    const assessment = status.assessment;
+    const hashFile = join(coordRoot, ".harnery", `.last-resource-hash.${instanceId}`);
+    const previous = safeRead(hashFile);
+    // Existing users without an observer should retain ordinary coordination.
+    if (status.assessment_capability.reason_code === "pressure_record_missing" && !previous) {
+      return "";
+    }
+    const key = `${assessment.scope}:${assessment.state}:${assessment.recommended_action}`;
+    if (previous === key) return "";
+    writeHashFile(hashFile, key);
+    const warning = assessment.state === "elevated" || assessment.state === "critical";
+    const wasWarning =
+      !!previous && (previous.includes(":elevated:") || previous.includes(":critical:"));
+    if (!warning && !wasWarning) return "";
+    const lines = [`Resource update: ${assessment.summary}`];
+    if (assessment.state === "unknown") {
+      lines.push(
+        "Resource headroom cannot be measured right now, so continue normal coordination and judge heavy work yourself.",
+      );
+    } else if (!warning && wasWarning) {
+      lines.push("The previously reported resource warning has cleared.");
+    }
+    for (const item of assessment.guidance) {
+      lines.push(`${WORKLOAD_LABEL[item.workload_class]}: ${item.summary}`);
+    }
+    const owners = assessment.contributors
+      .filter((row) => row.attribution_confidence === "exact" && row.owner_id)
+      .slice(0, 3)
+      .map((row) => `${row.owner_kind ?? "owner"} ${row.owner_id}`);
+    if (owners.length) {
+      lines.push(
+        `Measured owners of the contended resource: ${owners.join(", ")}. That says who is holding it, not what the machine as a whole can take.`,
+      );
+    }
+    lines.push(
+      `Read \`${resolveBinName(coordRoot)} resources status --json\` for the evidence behind this.`,
+    );
+    return lines.join("\n");
+  } catch {
+    return "";
+  }
+}
+
+/** How an agent recognizes the work each guidance entry is about. */
+const WORKLOAD_LABEL: Readonly<Record<PressureWorkloadClass, string>> = {
+  lightweight: "Reads and small edits",
+  "cpu-heavy": "Builds and test runs",
+  "memory-heavy": "Browser captures and page QA",
+  "storage-heavy": "Large writes and exports",
+};
+
 function renderHostPromptReminder(coordRoot: string, selfInstanceId: string): string {
   const hb = readLiveCoordinationRow(coordRoot, selfInstanceId);
   if (!hb || hb.kind === "subagent" || hb.kind === "transient" || hb.workflow_run_id) return "";

package/src/core/agents/session-finalizer-v3.ts

@@ -12,8 +12,8 @@ import {
 } from "node:fs";
 import { hostname } from "node:os";
 import { join, resolve } from "node:path";
-import type { Adapter } from "../adapter.ts";
 import { sessionFinalizationConfig } from "../config.ts";
+import type { EventAdapterIdV3 } from "../events/v3/adapter-id.ts";
 import { buildEventV3 } from "../events/v3/builder.ts";
 import { normalizeNativeIdV3 } from "../events/v3/canonical.ts";
 import type { EventV3 } from "../events/v3/contract.ts";
@@ -55,7 +55,7 @@ export {
 const EXPLICIT_END_PENDING_EXPIRY_MS = 24 * 60 * 60 * 1000;
 
 export interface SessionArchiveObservationV3 {
-  adapter: Adapter;
+  adapter: EventAdapterIdV3;
   native_session_id: string;
   archived: boolean;
   observed_at: string;

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

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { Adapter } from "../../adapter.ts";
+import { EVENT_ADAPTER_IDS_V3, type EventAdapterIdV3 } from "../../events/v3/adapter-id.ts";
 import {
   type CoordinationGenerationViewV3,
   type CoordinationViewV3,
@@ -94,7 +94,7 @@ export function readLiveCoordinationRow(
 export function liveCoordinationAdapterV3(
   coordRoot: string,
   nativeInstanceId: string,
-): Adapter | null {
+): EventAdapterIdV3 | null {
   const route = observeLiveEventLedgerRouteV3(coordRoot);
   if (route.state === "blocked") throw new Error(`event_v3_coordination_view:${route.reason}`);
   const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
@@ -213,8 +213,8 @@ export function observedAdapterV3(generation: CoordinationGenerationViewV3): str
   return observation.state === "observed" ? observation.value.id : undefined;
 }
 
-export function isAdapterV3(value: string | undefined): value is Adapter {
-  return value === "claude-code" || value === "cursor" || value === "codex";
+export function isAdapterV3(value: string | undefined): value is EventAdapterIdV3 {
+  return (EVENT_ADAPTER_IDS_V3 as readonly string[]).includes(value ?? "");
 }
 
 function observedModel(generation: CoordinationGenerationViewV3): string | undefined {

package/src/core/agents/state/names.ts

@@ -25,9 +25,23 @@
  * new binding instead of rewriting history; readers therefore resolve from the
  * end of the file. Older one-row histories retain their original behavior.
  *   3. Else: new assignment, consume a counter slot.
+ *
+ * Live-name skip: the pool holds 260 names and a busy repo consumes ~100 a
+ * day, so the counter wraps roughly every three days while sessions that
+ * resume under a stable instance_id keep a name for far longer. A counter-only
+ * pick therefore hands a live agent's name to a new one (observed 2026-09-06:
+ * two concurrent "Maya" agents, their pool slots exactly 520 apart). Assignment
+ * now probes forward past any name a fresh heartbeat still holds.
  */
 
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join } from "node:path";
 
 /** All 260 names. */
@@ -308,7 +322,7 @@ if (COORD_NAMES.length !== 260) {
   throw new Error(`COORD_NAMES table corrupt: expected 260 entries, got ${COORD_NAMES.length}`);
 }
 
-export type NameKind = "session" | "subagent" | "transient";
+export type NameKind = "session" | "subagent" | "transient" | "workflow-child";
 
 export interface NameHistoryRow {
   instance_id: string;
@@ -441,15 +455,68 @@ export function recordNameAssumption(
   return { changed: true, previous, current };
 }
 
+/**
+ * Names a live agent currently holds, read from the generation-bound heartbeat
+ * cache (`.harnery/active/<instance>.json`).
+ *
+ * Deliberately reads the cache directly rather than the V3 coordination view:
+ * that view imports `resolveName` from this module, so depending on it here
+ * would build an import cycle. The cache is the same set the view materializes
+ * from and is pruned as sessions end, so it answers "is this name taken right
+ * now" without one.
+ *
+ * Both error directions are safe for the caller. A stale row that slips past
+ * the freshness window costs one skipped pool slot; a live agent missing from
+ * the cache just restores the old counter-only behavior for that assignment.
+ */
+export function readLiveNames(
+  coordRoot: string,
+  opts: { freshnessSecs: number; nowMs?: number },
+): Set<string> {
+  const live = new Set<string>();
+  const dir = join(coordRoot, ".harnery", "active");
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return live; // No cache yet (fresh checkout) → nothing is live.
+  }
+
+  const nowMs = opts.nowMs ?? Date.now();
+  const cutoffMs = nowMs - opts.freshnessSecs * 1000;
+
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    let row: { name?: unknown; last_heartbeat?: unknown };
+    try {
+      row = JSON.parse(readFileSync(join(dir, entry), "utf8"));
+    } catch {
+      continue; // A torn or half-written row cannot prove a name is held.
+    }
+    if (typeof row.name !== "string" || row.name.length === 0) continue;
+    if (typeof row.last_heartbeat !== "string") continue;
+    const beatMs = Date.parse(row.last_heartbeat);
+    if (!Number.isFinite(beatMs) || beatMs < cutoffMs) continue;
+    live.add(row.name);
+  }
+  return live;
+}
+
 /**
  * Assign a name to <instanceId> with the given <kind>. Counter-consuming when
  * the owner is new. Idempotent: returns existing name on resume.
+ *
+ * Slot choice probes forward from the counter and takes the first name no live
+ * agent holds, then advances the counter past every slot it skipped so the skip
+ * is durable rather than re-probed on the next assignment. A full lap without a
+ * free name means all 260 are genuinely live, so the raw counter slot is used:
+ * a duplicate name beats refusing to name an agent at all.
  */
 export function assignName(
   coordRoot: string,
   instanceId: string,
   kind: NameKind,
-  opts?: { forkedFrom?: string },
+  opts: { freshnessSecs: number; forkedFrom?: string; nowMs?: number },
 ): string {
   // Check 1: existing history row → original name. A resume re-enters here,
   // which also makes fork stamping naturally idempotent: lineage lands only on
@@ -457,16 +524,34 @@ export function assignName(
   const existing = resolveName(coordRoot, instanceId);
   if (existing) return existing.name;
 
-  // New owner: consume a counter slot.
+  // New owner: consume a counter slot. The live set is gathered BEFORE the
+  // counter read on purpose. Counter read-modify-write is already unlocked, so
+  // concurrent assignments can collide on one slot; doing the directory scan
+  // first keeps that window exactly as narrow as it was before the skip existed.
+  const live = readLiveNames(coordRoot, {
+    freshnessSecs: opts.freshnessSecs,
+    ...(opts.nowMs !== undefined ? { nowMs: opts.nowMs } : {}),
+  });
+
   const cPath = counterPath(coordRoot);
   let counter = 0;
   if (existsSync(cPath)) {
     const raw = readFileSync(cPath, "utf8").trim();
     if (/^\d+$/.test(raw)) counter = Number.parseInt(raw, 10);
   }
-  const name = COORD_NAMES[counter % 260]!;
-  atomicWrite(cPath, String(counter + 1));
-  const forkedFrom = opts?.forkedFrom;
+
+  let chosen = counter;
+  for (let probe = 0; probe < 260; probe++) {
+    const candidate = COORD_NAMES[(counter + probe) % 260]!;
+    if (!live.has(candidate)) {
+      chosen = counter + probe;
+      break;
+    }
+  }
+
+  const name = COORD_NAMES[chosen % 260]!;
+  atomicWrite(cPath, String(chosen + 1));
+  const forkedFrom = opts.forkedFrom;
   appendHistory(coordRoot, {
     instance_id: instanceId,
     name,

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

@@ -1,5 +1,5 @@
 /**
- * Stale-sweep: prune dead heartbeats + orphaned pid-map + .last-peer-hash
+ * Stale-sweep: prune dead heartbeats + orphaned pid-map + prompt hash
  * files.
  *
  * Runs after session.started to clean up crashed-peer detritus before the new
@@ -13,13 +13,15 @@
 import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { coordFreshnessSeconds } from "../../config.ts";
+import type { EventAdapterIdV3 } from "../../events/v3/adapter-id.ts";
 import { writeProducerDiagnosticV3 } from "../../events/v3/producers/intake.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" {
+function adapterFromPlatform(platform: unknown): EventAdapterIdV3 {
   if (platform === "cursor") return "cursor";
   if (platform === "codex") return "codex";
+  if (platform === "openclaw") return "openclaw";
   return "claude-code";
 }
 
@@ -35,7 +37,7 @@ function adapterFromPlatform(platform: unknown): "claude-code" | "cursor" | "cod
 function emitSwept(
   coordRoot: string,
   instanceId: string,
-  adapter: "claude-code" | "cursor" | "codex",
+  adapter: EventAdapterIdV3,
   sessionId: string,
   reason: "stale" | "unparseable" | "missing_ts",
   ageSecs?: number,
@@ -83,10 +85,12 @@ export function staleSweep(coordRoot: string): {
   heartbeatsRemoved: string[];
   pidmapsRemoved: number;
   peerHashesRemoved: number;
+  resourceHashesRemoved: number;
 } {
   const heartbeatsRemoved: string[] = [];
   let pidmapsRemoved = 0;
   let peerHashesRemoved = 0;
+  let resourceHashesRemoved = 0;
 
   const freshness = coordFreshnessSeconds(coordRoot);
   const nowSec = Math.floor(Date.now() / 1000);
@@ -207,16 +211,26 @@ export function staleSweep(coordRoot: string): {
     }
   }
 
-  // 3. Prune .last-peer-hash files for dead owners.
+  // 3. Prune prompt hashes for dead owners. Resource hashes retain their own
+  // count so existing peer-hash telemetry keeps its original meaning.
   const agentsDir = join(coordRoot, ".harnery");
   if (existsSync(agentsDir)) {
     for (const f of readdirSync(agentsDir)) {
-      if (!f.startsWith(".last-peer-hash.")) continue;
-      const owner = f.slice(".last-peer-hash.".length);
+      const resourceHash = f.startsWith(".last-resource-hash.");
+      const prefix = resourceHash ? ".last-resource-hash." : ".last-peer-hash.";
+      if (!f.startsWith(prefix)) continue;
+      const owner = f.slice(prefix.length);
+      if (resourceHash) {
+        // Ignore atomic-write temporary files and preserve hashes when a
+        // retained heartbeat's liveness could not be determined safely.
+        if (!/^[A-Za-z0-9_-]{1,128}$/.test(owner)) continue;
+        if (existsSync(join(d, `${owner}.json`))) continue;
+      }
       if (!liveInstanceIds.has(owner)) {
         try {
           unlinkSync(join(agentsDir, f));
-          peerHashesRemoved += 1;
+          if (resourceHash) resourceHashesRemoved += 1;
+          else peerHashesRemoved += 1;
         } catch {
           /* swallow */
         }
@@ -224,5 +238,5 @@ export function staleSweep(coordRoot: string): {
     }
   }
 
-  return { heartbeatsRemoved, pidmapsRemoved, peerHashesRemoved };
+  return { heartbeatsRemoved, pidmapsRemoved, peerHashesRemoved, resourceHashesRemoved };
 }

package/src/core/agents/turn-elapsed.ts

@@ -0,0 +1,135 @@
+/**
+ * How long the current turn has been running, for the closing status box.
+ *
+ * The box already reports `session`, which is cumulative and says nothing
+ * about the work just done: a 9-minute session hides whether this turn took
+ * twelve seconds or eight minutes. `turn` measures from the operator's prompt
+ * (`turn.started`) to the moment the box renders, so the operator reads the
+ * cost of the turn they are about to be handed.
+ *
+ * Every read here is best-effort by contract. A missing ledger, an
+ * unvalidated one, or no `turn.started` for this owner renders no row rather
+ * than failing the status command.
+ */
+import type { EventV3 } from "../events/v3/contract.ts";
+import { liveInstanceIdV3 } from "../events/v3/live-routing.ts";
+import { readLedgerV3 } from "../events/v3/reader.ts";
+
+/** Stop-hook remediation restarts to walk back through before giving up. */
+const MAX_REMEDIATION_WALK_BACK = 8;
+
+export interface TurnElapsed {
+  /** Seconds from the turn's start to its terminal, or to `now` while open. */
+  secs: number;
+  /** True once a `turn.completed` closed the turn this measures. */
+  complete: boolean;
+  /** Stop-hook restarts folded into this measurement. */
+  remediation_restarts: number;
+}
+
+function timeMs(event: EventV3 | undefined): number {
+  if (!event) return Number.NaN;
+  return Date.parse(event.time.observed_at);
+}
+
+function generationOf(event: EventV3): string | undefined {
+  return "generation_id" in event.scope ? event.scope.generation_id : undefined;
+}
+
+/**
+ * Measure the newest turn for `instanceId` from an already-read event stream.
+ *
+ * A Stop-hook bounce ends one `turn.started` and opens another carrying
+ * `stop_remediation`. The operator experiences those as one turn, so the walk
+ * back over remediation restarts reports elapsed time since their prompt, not
+ * since the last retry. The walk stays inside one generation: a resumed
+ * session must not absorb the previous generation's turn into its own.
+ */
+export function resolveTurnElapsed(
+  events: readonly EventV3[],
+  instanceId: string,
+  now: number = Date.now(),
+): TurnElapsed | null {
+  const owner = liveInstanceIdV3(instanceId);
+  const ownerEvents = events.filter((event) => event.scope.instance_id === owner);
+  const starts = ownerEvents.filter(
+    (event): event is Extract<EventV3, { event_type: "turn.started" }> =>
+      event.event_type === "turn.started" && timeMs(event) <= now,
+  );
+  if (starts.length === 0) return null;
+
+  let index = starts.length - 1;
+  const generation = generationOf(starts[index]!);
+  let restarts = 0;
+  while (index > 0 && restarts < MAX_REMEDIATION_WALK_BACK) {
+    const turn = starts[index];
+    if (turn?.payload.stop_remediation !== true) break;
+    const previous = starts[index - 1];
+    if (!previous || generationOf(previous) !== generation) break;
+    index -= 1;
+    restarts += 1;
+  }
+
+  const startMs = timeMs(starts[index]);
+  if (!Number.isFinite(startMs)) return null;
+
+  // A terminal only closes the measurement when nothing restarted the turn
+  // after it, so match against the newest start rather than the walked-back
+  // one. Otherwise the `turn.completed` that a Stop-hook bounce produced would
+  // end the measurement mid-remediation.
+  const newestStartMs = timeMs(starts[starts.length - 1]);
+  const terminal = ownerEvents.find(
+    (event) =>
+      event.event_type === "turn.completed" &&
+      generationOf(event) === generation &&
+      timeMs(event) >= newestStartMs,
+  );
+  const terminalMs = timeMs(terminal);
+  const endMs = Number.isFinite(terminalMs) ? terminalMs : now;
+  return {
+    secs: Math.max(0, Math.floor((endMs - startMs) / 1000)),
+    complete: Number.isFinite(terminalMs),
+    remediation_restarts: restarts,
+  };
+}
+
+/**
+ * Render a turn duration for the box. Seconds stay visible below an hour
+ * because most turns land there and a bare `4m` cannot be compared with the
+ * turn before it.
+ */
+export function formatTurnElapsed(secs: number): string {
+  if (secs < 60) return `${secs}s`;
+  if (secs < 3600) return `${Math.floor(secs / 60)}m ${secs % 60}s`;
+  const hours = Math.floor(secs / 3600);
+  const minutes = Math.floor((secs % 3600) / 60);
+  return `${hours}h ${minutes}m`;
+}
+
+export interface TurnElapsedTarget {
+  coordRoot: string;
+  instanceId: string;
+}
+
+/**
+ * The whole status-box contribution in one best-effort call: read the ledger
+ * and render this session's `turn` row. Null means render no row.
+ */
+export function turnElapsedStatusRow(
+  target: TurnElapsedTarget,
+  now: number = Date.now(),
+): { value: string; elapsed: TurnElapsed } | null {
+  try {
+    const ledger = readLedgerV3(target.coordRoot);
+    if (!ledger.complete) return null;
+    const elapsed = resolveTurnElapsed(
+      ledger.events.map((positioned) => positioned.event),
+      target.instanceId,
+      now,
+    );
+    if (!elapsed) return null;
+    return { value: formatTurnElapsed(elapsed.secs), elapsed };
+  } catch {
+    return null;
+  }
+}