harnery 0.34.1 → 0.35.0

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

@@ -0,0 +1,69 @@
+/** Read-only access to the generation-bound heartbeat cache. */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import type { AgentActivity, TaskState } from "./session-state.ts";
+
+export interface Heartbeat {
+  schema_version?: number;
+  instance_id: string;
+  name?: string;
+  kind?: string;
+  agent_id?: string;
+  session_id: string;
+  /** Native adapter session ID retained only in a generation-bound local projection. */
+  native_session_id?: string;
+  subagent_call_id?: string;
+  model?: string;
+  platform?: string;
+  started_at?: string;
+  last_heartbeat: string;
+  files_touched: string[];
+  task?: string;
+  task_updated_at?: string | null;
+  activity?: AgentActivity;
+  activity_updated_at?: string;
+  activity_source?: string;
+  task_state?: TaskState;
+  task_state_updated_at?: string;
+  task_state_reason?: string;
+  /** Session name built on the first non-empty set-task (never rebuilt). */
+  suggested_session_name?: string;
+  /** Stamped once the suggested name is seen in assistant reply text. */
+  session_name_seen_at?: string;
+  /** The specific suggested name proven present by the sighting stamp. */
+  session_name_seen_for?: string;
+  last_status_at?: string;
+  current_turn_id?: string;
+  parent_instance_id?: string;
+  workflow_run_id?: string;
+  workflow_agent_id?: string;
+  /** Disposable-cache bindings that prove a row belongs to the current V3 generation. */
+  v3_instance_id?: `inst_${string}`;
+  v3_generation_id?: `gen_${string}`;
+  v3_projection_event_id?: string;
+  v3_task_state?: "set" | "cleared";
+  [extra: string]: unknown;
+}
+
+export function heartbeatPath(coordRoot: string, instanceId: string): string {
+  if (!/^[A-Za-z0-9_-]{1,128}$/.test(instanceId)) {
+    throw new Error("instance_id must be 1-128 ASCII letters, digits, hyphens, or underscores");
+  }
+  const root = resolve(coordRoot, ".harnery", "active");
+  const candidate = resolve(root, `${instanceId}.json`);
+  if (!candidate.startsWith(`${root}${sep}`) || dirname(candidate) !== root) {
+    throw new Error("coordination filename must resolve directly beneath its root");
+  }
+  return candidate;
+}
+
+export function readHeartbeat(coordRoot: string, instanceId: string): Heartbeat | null {
+  const path = heartbeatPath(coordRoot, instanceId);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as Heartbeat;
+  } catch {
+    return null;
+  }
+}

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

@@ -23,65 +23,12 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { basename, dirname, join } from "node:path";
-import { assertSafeInstanceId, resolveContainedFile } from "../coord-client.ts";
-import type { AgentActivity, TaskState } from "./session-state.ts";
+import { dirname, join } from "node:path";
+import { canonicalClaimPath } from "../claim-path.ts";
+import { type Heartbeat, heartbeatPath, readHeartbeat } from "./heartbeat-reader.ts";
+import type { TaskState } from "./session-state.ts";
 
-export interface Heartbeat {
-  schema_version?: number;
-  instance_id: string;
-  name?: string;
-  kind?: string;
-  agent_id?: string;
-  session_id: string;
-  /** Native adapter session ID retained only in a generation-bound local projection. */
-  native_session_id?: string;
-  subagent_call_id?: string;
-  model?: string;
-  platform?: string;
-  started_at?: string;
-  last_heartbeat: string;
-  files_touched: string[];
-  task?: string;
-  task_updated_at?: string | null;
-  activity?: AgentActivity;
-  activity_updated_at?: string;
-  activity_source?: string;
-  task_state?: TaskState;
-  task_state_updated_at?: string;
-  task_state_reason?: string;
-  /** Session name built on the first non-empty set-task (never rebuilt). Its
-   * presence is the "this session has been named" signal the prompt-context
-   * nudge and the Stop-hook naming rule key on. */
-  suggested_session_name?: string;
-  /** Stamped by turn.completed once the suggested name is seen in assistant reply
-   * text, ending the per-turn transcript scan. */
-  session_name_seen_at?: string;
-  /** WHICH name that sighting was for. The scan is skipped only while this
-   * matches the current suggested name, so a re-minted name is detectable
-   * again rather than being suppressed by the earlier sighting. */
-  session_name_seen_for?: string;
-  last_status_at?: string;
-  current_turn_id?: string;
-  parent_instance_id?: string;
-  workflow_run_id?: string;
-  workflow_agent_id?: string;
-  /** Disposable-cache bindings that prove a row belongs to the current V3 generation. */
-  v3_instance_id?: `inst_${string}`;
-  v3_generation_id?: `gen_${string}`;
-  v3_projection_event_id?: string;
-  v3_task_state?: "set" | "cleared";
-  [extra: string]: unknown;
-}
-
-function heartbeatPath(coordRoot: string, instanceId: string): string {
-  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`);
-}
+export { type Heartbeat, readHeartbeat } from "./heartbeat-reader.ts";
 
 function nowIsoSeconds(): string {
   return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -94,16 +41,6 @@ function atomicWrite(path: string, content: string): void {
   renameSync(tmp, path);
 }
 
-export function readHeartbeat(coordRoot: string, instanceId: string): Heartbeat | null {
-  const path = heartbeatPath(coordRoot, instanceId);
-  if (!existsSync(path)) return null;
-  try {
-    return JSON.parse(readFileSync(path, "utf8")) as Heartbeat;
-  } catch {
-    return null;
-  }
-}
-
 /** Persist operator-facing lifecycle prose in the generation-bound cache only. */
 export function setLifecycleCache(
   coordRoot: string,
@@ -221,16 +158,12 @@ export function releaseClaim(
   instanceId: string,
   path: string,
 ): Heartbeat | null {
-  // files_touched can hold either absolute-under-coordRoot or canonical
-  // monorepo-relative entries; normalize both sides so release matches
-  // regardless of the form the caller passes (the old exact-string filter
-  // silently no-op'd on a form mismatch).
-  const norm = (p: string): string =>
-    p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p;
-  const target = norm(path);
+  const target = canonicalClaimPath(coordRoot, path);
   return mutate(coordRoot, instanceId, (hb) => ({
     ...hb,
-    files_touched: (hb.files_touched ?? []).filter((p) => norm(p) !== target),
+    files_touched: (hb.files_touched ?? []).filter(
+      (candidate) => canonicalClaimPath(coordRoot, candidate) !== target,
+    ),
   }));
 }
 
@@ -240,12 +173,15 @@ export function acquireClaim(
   instanceId: string,
   path: string,
 ): Heartbeat | null {
-  const norm = (p: string): string =>
-    p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p;
-  const target = norm(path);
+  const target = canonicalClaimPath(coordRoot, path);
   return mutate(coordRoot, instanceId, (hb) => ({
     ...hb,
-    files_touched: [...new Set([...(hb.files_touched ?? []).map(norm), target])].sort(),
+    files_touched: [
+      ...new Set([
+        ...(hb.files_touched ?? []).map((candidate) => canonicalClaimPath(coordRoot, candidate)),
+        target,
+      ]),
+    ].sort(),
   }));
 }
 
@@ -282,9 +218,7 @@ export function findGroupClaims(
   if (!groupId || !path) return hits;
   const activeDir = join(coordRoot, ".harnery", "active");
   if (!existsSync(activeDir)) return hits;
-  const norm = (p: string): string =>
-    p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p;
-  const target = norm(path);
+  const target = canonicalClaimPath(coordRoot, path);
   for (const f of readdirSync(activeDir)) {
     if (!f.endsWith(".json")) continue;
     const hbPath = join(activeDir, f);
@@ -298,7 +232,9 @@ export function findGroupClaims(
       (body.session_id as string | undefined) ?? (body.instance_id as string | undefined);
     if (peerSession !== groupId) continue;
     const files = (body.files_touched as string[] | undefined) ?? [];
-    if (!files.some((candidate) => norm(candidate) === target)) continue;
+    if (!files.some((candidate) => canonicalClaimPath(coordRoot, candidate) === target)) {
+      continue;
+    }
     hits.push({
       instance_id: (body.instance_id as string | undefined) ?? f.replace(/\.json$/, ""),
       session_id: body.session_id as string | undefined,

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

@@ -19,7 +19,7 @@ import {
   nativeInstanceIdV3,
   resolveLiveEventLedgerRouteV3,
 } from "../../events/v3/live-routing.ts";
-import { type Heartbeat, readHeartbeat } from "./heartbeat-writer.ts";
+import { type Heartbeat, readHeartbeat } from "./heartbeat-reader.ts";
 import { resolveName } from "./names.ts";
 
 /**
@@ -141,8 +141,33 @@ export function ensureLiveCoordinationHeartbeat(
 
   const resolved = resolveName(coordRoot, nativeInstanceId, nativeSessionId);
   const projected = projectHeartbeatV3(coordRoot, generation, undefined, nativeInstanceId);
+  // A generation reopen (resume, mid-flight onboarding) discards the stale
+  // cache, but the adapter tab it names is unchanged: same native session,
+  // same agent identity. Rebuilding without the naming evidence re-mints a
+  // fresh suggested name on the next set-task, so a multi-day session
+  // accumulates titles it is asked to display over and over. Carry the
+  // naming evidence across generations; everything else re-projects from V3.
+  // Same native session id means the same adapter tab; drop the carry only
+  // when the durable identity observably changed (a reassumed name would make
+  // the old "Agent <name> - …" block wrong for the new owner).
+  const identityUnchanged = !resolved?.name || !current?.name || resolved.name === current.name;
+  const carriedNaming =
+    current && current.session_id === nativeSessionId && identityUnchanged
+      ? {
+          ...(current.suggested_session_name
+            ? { suggested_session_name: current.suggested_session_name }
+            : {}),
+          ...(current.session_name_seen_for
+            ? { session_name_seen_for: current.session_name_seen_for }
+            : {}),
+          ...(current.session_name_seen_at
+            ? { session_name_seen_at: current.session_name_seen_at }
+            : {}),
+        }
+      : {};
   const materialized: V3HeartbeatMaterialization = {
     ...projected,
+    ...carriedNaming,
     schema_version: 2,
     instance_id: nativeInstanceId,
     session_id: nativeSessionId,