harnery 0.31.6 → 0.32.0

package/dist/core/agents/session-events.d.ts

@@ -1,21 +1,17 @@
 /**
  * Command/narration event emitter for the coordination layer.
  *
- * `writeSessionEvent` emits command + narration events straight to the
+ * `writeSessionEvent` emits command and narration events straight to the
  * **canonical** `.harnery/events.ndjson` (alongside the hook events), which the
- * `/live` web viewer reads. The exported surface (`writeSessionEvent`,
- * `newCmdId`, `clampField`, `readLastIntent`) is stable so the session-tee
- * middleware callers need no edits.
+ * `/live` web viewer reads.
  */
-/** Event types accepted by `writeSessionEvent`. Only the command stream +
- * narration are emitted canonically; the coord/state types are accepted for
- * call-site compatibility but are no-ops (the agents CLI emits those itself). */
-export type SessionEventType = "command_start" | "output" | "command_end" | "end_of_turn" | "hook_event" | "set_task" | "file_claim" | "file_release" | "peer_change" | "narration";
+/** Event types accepted by `writeSessionEvent`. */
+export type SessionEventType = "command_start" | "output" | "command_end" | "narration";
 /**
  * Resolved path of the ndjson sidecar file. Lives inside `.harnery/` so a
  * containerized reader can pick it up through a single bind mount.
  */
-export declare function sessionEventsPath(): string;
+export declare function canonicalEventsPath(): string;
 /** Random 8-char hex id for grouping output lines under a single command. */
 export declare function newCmdId(): string;
 /**
@@ -28,14 +24,10 @@ export declare function newCmdId(): string;
  */
 export declare function readLastIntent(instanceId?: string): string | null;
 /**
- * Emit a session event. Command + narration events
- * are written to the canonical `.harnery/events.ndjson`; the coord/state types
- * are accepted for call-site compatibility but are no-ops here (the agents CLI
- * emits those itself). Best-effort, never throws into the caller; a command
- * must never break or slow on telemetry. The `agentName` arg is retained for
- * the stable call signature (canonical events key on instance_id, not name).
+ * Emit a command or narration event to `.harnery/events.ndjson`. Best-effort,
+ * never throws into the caller; telemetry must not break or slow a command.
  */
-export declare function writeSessionEvent(type: SessionEventType, _agentName: string, fields?: Record<string, unknown>): void;
+export declare function writeSessionEvent(type: SessionEventType, fields?: Record<string, unknown>): void;
 /** Trim long values to keep individual events small. */
 export declare function clampField(v: string, max?: number): string;
 //# sourceMappingURL=session-events.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"session-events.d.ts","sourceRoot":"","sources":["../../../src/core/agents/session-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;iFAEiF;AACjF,MAAM,MAAM,gBAAgB,GACxB,eAAe,GACf,QAAQ,GACR,aAAa,GACb,aAAa,GACb,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,cAAc,GACd,aAAa,GACb,WAAW,CAAC;AAEhB;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAa1C;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBjE;AAsGD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,IAAI,CAEN;AAED,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,SAAO,GAAG,MAAM,CAGxD"}
+{"version":3,"file":"session-events.d.ts","sourceRoot":"","sources":["../../../src/core/agents/session-events.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,mDAAmD;AACnD,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,CAAC;AAExF;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAa5C;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBjE;AA8FD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,EACtB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,IAAI,CAEN;AAED,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,SAAO,GAAG,MAAM,CAGxD"}

package/dist/core/agents/session-events.js

@@ -1,11 +1,9 @@
 /**
  * Command/narration event emitter for the coordination layer.
  *
- * `writeSessionEvent` emits command + narration events straight to the
+ * `writeSessionEvent` emits command and narration events straight to the
  * **canonical** `.harnery/events.ndjson` (alongside the hook events), which the
- * `/live` web viewer reads. The exported surface (`writeSessionEvent`,
- * `newCmdId`, `clampField`, `readLastIntent`) is stable so the session-tee
- * middleware callers need no edits.
+ * `/live` web viewer reads.
  */
 import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
@@ -17,9 +15,9 @@ import { emit } from "./events/emit.js";
  * Resolved path of the ndjson sidecar file. Lives inside `.harnery/` so a
  * containerized reader can pick it up through a single bind mount.
  */
-export function sessionEventsPath() {
+export function canonicalEventsPath() {
     // Explicit override (tests + non-monorepo invocations).
-    const explicit = process.env.HARNERY_OUTPUT_SESSION_EVENTS;
+    const explicit = process.env.HARNERY_EVENTS_PATH;
     if (explicit)
         return explicit;
     // Superproject-aware root resolution (git first, cwd walk fallback) via
@@ -48,7 +46,7 @@ export function newCmdId() {
 export function readLastIntent(instanceId) {
     if (!instanceId)
         return null;
-    // Same superproject-aware root resolution as sessionEventsPath(): the
+    // Same superproject-aware root resolution as canonicalEventsPath(): the
     // intent stamp is written by the PreToolUse hook into the SUPERPROJECT's
     // .harnery/, so a nested-`.harnery/` cwd must not redirect the read.
     const root = resolveEmitRoot();
@@ -68,14 +66,6 @@ export function readLastIntent(instanceId) {
         return null;
     }
 }
-/**
- * Dual-write: mirror command/narration session-events
- * into the canonical `.harnery/events.ndjson` stream so the legacy
- * session-events.ndjson writer + its web consumers can be retired.
- * Only the command-stream + narration types migrate; the coord/state types
- * (`set_task`, `file_claim`, `peer_change`, …) are already emitted canonically
- * by the agents CLI, so re-emitting them here would double-count.
- */
 const CANONICAL_TYPE = {
     command_start: "command.start",
     output: "command.output",
@@ -110,7 +100,7 @@ function enrichFromHeartbeat(coordRoot, instanceId) {
         return null;
     }
 }
-/** Project the flat legacy `fields` into the canonical event's `data` shape.
+/** Project the flat middleware `fields` into the canonical event's `data` shape.
  * Unknown types never reach here, guarded by CANONICAL_TYPE. */
 function canonicalData(type, fields) {
     switch (type) {
@@ -133,7 +123,7 @@ function canonicalData(type, fields) {
 }
 /** Emit a command/narration event to the canonical stream. Swallows every
  * error and skips when identity can't be resolved: telemetry must never break
- * (or slow down) a command. Non-command types return early. */
+ * or slow down a command. */
 function emitCanonicalCommand(type, fields) {
     const eventType = CANONICAL_TYPE[type];
     if (!eventType)
@@ -142,8 +132,8 @@ function emitCanonicalCommand(type, fields) {
     if (!instanceId)
         return;
     try {
-        // coordRoot = the dir containing `.harnery/`; sessionEventsPath() anchors it.
-        const coordRoot = dirname(dirname(sessionEventsPath()));
+        // coordRoot = the dir containing `.harnery/`; canonicalEventsPath() anchors it.
+        const coordRoot = dirname(dirname(canonicalEventsPath()));
         const enrich = enrichFromHeartbeat(coordRoot, instanceId);
         if (!enrich)
             return;
@@ -160,14 +150,10 @@ function emitCanonicalCommand(type, fields) {
     }
 }
 /**
- * Emit a session event. Command + narration events
- * are written to the canonical `.harnery/events.ndjson`; the coord/state types
- * are accepted for call-site compatibility but are no-ops here (the agents CLI
- * emits those itself). Best-effort, never throws into the caller; a command
- * must never break or slow on telemetry. The `agentName` arg is retained for
- * the stable call signature (canonical events key on instance_id, not name).
+ * Emit a command or narration event to `.harnery/events.ndjson`. Best-effort,
+ * never throws into the caller; telemetry must not break or slow a command.
  */
-export function writeSessionEvent(type, _agentName, fields = {}) {
+export function writeSessionEvent(type, fields = {}) {
     emitCanonicalCommand(type, fields);
 }
 /** Trim long values to keep individual events small. */

package/dist/core/agents/state/heartbeat-projector.d.ts

@@ -30,6 +30,9 @@ export interface V2Heartbeat {
     last_tool_at?: string;
     task?: string;
     task_updated_at?: string;
+    suggested_session_name?: string;
+    session_name_seen_at?: string;
+    session_name_seen_for?: string;
     last_status_at?: string;
     presence?: "mobile" | "office";
     last_intent?: string;

package/dist/core/agents/state/heartbeat-projector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heartbeat-projector.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/heartbeat-projector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,OAAO,EAAE;QACP,cAAc,EAAE,CAAC,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,SAAS,cAAc,EAAE,GAChC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CAAE,CAoD9D;AA6YD,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3E"}
+{"version":3,"file":"heartbeat-projector.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/heartbeat-projector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,OAAO,EAAE;QACP,cAAc,EAAE,CAAC,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,SAAS,cAAc,EAAE,GAChC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CAAE,CAoD9D;AAsbD,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3E"}

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

@@ -197,6 +197,18 @@ function apply(hb, ev, coordRoot) {
         case "turn.stop":
             hb.last_turn_stop_at = ev.ts;
             hb.last_turn_status_box_present = pickBool(d, "status_box_present");
+            // Rebuild fidelity for the naming ritual: the live stamp is written by
+            // the Stop hook (stampSessionNameSeen); reproduce it from the event so a
+            // full projector rebuild doesn't re-open a satisfied naming window.
+            if (d.session_name_present === true) {
+                hb.session_name_seen_at ??= ev.ts;
+                // Attribute the sighting to the name the scan actually covered. Reading
+                // the name current at this point in the replay instead re-attributed an
+                // old sighting to a re-minted name, which faked "already seen" for a
+                // name no reply had shown. An event without the field predates it, so
+                // leave the attribution unset and let the next stop re-scan.
+                hb.session_name_seen_for = pickStr(d, "session_name_present_for");
+            }
             {
                 const summary = pickStr(d, "turn_summary");
                 if (summary) {
@@ -254,6 +266,11 @@ function apply(hb, ev, coordRoot) {
                 hb.task = task;
             }
             hb.task_updated_at = ev.ts;
+            // Rebuild fidelity: the naming call carries the name it produced.
+            const suggested = pickStr(d, "suggested_session_name");
+            if (suggested && !hb.suggested_session_name) {
+                hb.suggested_session_name = suggested;
+            }
             break;
         }
         case "state.status_checked":
@@ -274,6 +291,20 @@ function apply(hb, ev, coordRoot) {
                 hb.presence = to;
             break;
         }
+        case "claim.acquire": {
+            const path = pickStr(d, "path");
+            const mode = pickStr(d, "mode");
+            if (path && mode === "write") {
+                const canonical = path.startsWith(`${coordRoot}/`)
+                    ? path.slice(coordRoot.length + 1)
+                    : path;
+                if (!hb.files_touched)
+                    hb.files_touched = [];
+                if (!hb.files_touched.includes(canonical))
+                    hb.files_touched.push(canonical);
+            }
+            break;
+        }
         case "claim.release": {
             const path = pickStr(d, "path");
             if (path && hb.files_touched) {
@@ -292,7 +323,7 @@ function apply(hb, ev, coordRoot) {
 }
 function adapterToPlatform(adapter) {
     if (adapter === "claude-code")
-        return "claude_code";
+        return "claude-code";
     if (adapter === "cursor")
         return "cursor";
     if (adapter === "codex")
@@ -446,6 +477,18 @@ function writeHeartbeat(coordRoot, instanceId, hb) {
         setIfDefined(merged, "last_tool_at", hb.last_tool_at);
         setIfDefined(merged, "task", hb.task);
         setIfDefined(merged, "task_updated_at", hb.task_updated_at);
+        setIfDefined(merged, "suggested_session_name", hb.suggested_session_name);
+        setIfDefined(merged, "session_name_seen_at", hb.session_name_seen_at);
+        if (hb.session_name_seen_for) {
+            merged.session_name_seen_for = hb.session_name_seen_for;
+        }
+        else {
+            // Unlike most projected fields, an absent attribution is meaningful: a
+            // legacy sighting cannot prove which suggested name it covered. Remove a
+            // stale value inherited through the additive merge so the next stop
+            // scans the current name instead of treating it as already satisfied.
+            delete merged.session_name_seen_for;
+        }
         setIfDefined(merged, "last_status_at", hb.last_status_at);
         setIfDefined(merged, "turn_summary", hb.turn_summary);
         setIfDefined(merged, "turn_summary_updated_at", hb.turn_summary_updated_at);

package/dist/core/agents/state/heartbeat-writer.d.ts

@@ -27,6 +27,17 @@ export interface Heartbeat {
     files_touched: string[];
     task?: string;
     task_updated_at?: string | null;
+    /** 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.stop 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;
     turn_summary?: string | null;
     turn_summary_updated_at?: string | null;
@@ -35,11 +46,26 @@ export interface Heartbeat {
     last_tool_at?: string;
     current_turn_id?: string;
     parent_instance_id?: string;
+    workflow_run_id?: string;
     [extra: string]: unknown;
 }
 export declare function readHeartbeat(coordRoot: string, instanceId: string): Heartbeat | null;
 export declare function setTask(coordRoot: string, instanceId: string, task: string): Heartbeat | null;
-export declare function stampStatusCheck(coordRoot: string, instanceId: string): Heartbeat | null;
+/**
+ * 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
+ * internal whitespace and trims. Returns null when the description is empty.
+ */
+export declare function buildSuggestedName(agentName: string, descriptionParts: string[]): {
+    suggestedName: string;
+    description: string;
+} | 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
+ * different suggested name, a bare "already seen" stamp would suppress the scan
+ * forever and leave the Stop-hook naming rule permanently unsatisfiable. */
+export declare function stampSessionNameSeen(coordRoot: string, instanceId: string, name?: string): Heartbeat | null;
 export declare function setTurnSummary(coordRoot: string, instanceId: string, summary: string): Heartbeat | null;
 export declare function releaseClaim(coordRoot: string, instanceId: string, path: string): Heartbeat | null;
 /** A heartbeat that actually dropped a path during a group unclaim. */
@@ -57,9 +83,8 @@ export interface GroupUnclaimHit {
  * durable `claim.release` events — a file-only prune is silently reverted by
  * the next projector replay.
  *
- * files_touched can hold either absolute-under-coordRoot or canonical
- * repo-relative entries (legacy projections stored the raw tool_input path),
- * so both sides are normalized before comparing — an exact-string match
+ * Tool payloads and release calls can supply either absolute-under-coordRoot or
+ * canonical repo-relative entries, so both sides are normalized before comparing. An exact-string match
  * silently no-ops on the mixed-form case and the claim never releases.
  *
  * This is the Option B fix for post-commit's pid-map attribution hole: a
@@ -69,7 +94,9 @@ export interface GroupUnclaimHit {
 export declare function groupUnclaim(coordRoot: string, groupId: string, path: string): GroupUnclaimHit[];
 export declare function killHeartbeat(coordRoot: string, instanceId: string): boolean;
 export declare function healPidmap(coordRoot: string, instanceId: string, pid: number): void;
-export declare function healHeartbeat(coordRoot: string, instanceId: string, sessionId?: string, model?: string, adapter?: string): Heartbeat | null;
+export declare function healHeartbeat(coordRoot: string, instanceId: string, sessionId?: string, model?: string, adapter?: string, opts?: {
+    forkedFrom?: string;
+}): Heartbeat | null;
 /**
  * Register a workflow child in the coordination layer from the ENGINE side.
  *

package/dist/core/agents/state/heartbeat-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heartbeat-writer.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/heartbeat-writer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"heartbeat-writer.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/heartbeat-writer.ts"],"names":[],"mappings":"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"}

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

@@ -24,16 +24,15 @@ function adapterOf(platform) {
         return "codex";
     return "claude-code";
 }
-/** Inverse of adapterOf: maps the canonical adapter ("claude-code"/"cursor"/
- * "codex") to the legacy underscore platform label stored on the heartbeat.
- * Mirrors heartbeat-projector.adapterToPlatform so a healed heartbeat carries
- * the same platform value projection would have written. */
+/** 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";
+    return "claude-code";
 }
 /**
  * Emit a canonical `health.*` event for an actual self-heal write. This is the
@@ -93,17 +92,44 @@ function mutate(coordRoot, instanceId, fn) {
 export function setTask(coordRoot, instanceId, task) {
     return mutate(coordRoot, instanceId, (hb) => {
         const cleared = !task || task.length === 0;
+        // Name the session on its first NON-EMPTY declaration. Keyed on the
+        // suggested_session_name stamp, not task_updated_at, so a bare clear as
+        // the first call never burns the naming window. Subagents and workflow
+        // children have no human-owned tab to rename, so they are never named.
+        const humanFacing = hb.kind !== "subagent" && hb.kind !== "transient" && !hb.workflow_run_id;
+        const built = !cleared && !hb.suggested_session_name && humanFacing
+            ? buildSuggestedName(hb.name ?? "unknown", [task])
+            : null;
         return {
             ...hb,
             task: cleared ? undefined : task,
             task_updated_at: nowIsoSeconds(),
+            ...(built ? { suggested_session_name: built.suggestedName } : {}),
         };
     });
 }
-export function stampStatusCheck(coordRoot, instanceId) {
+/**
+ * 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
+ * internal whitespace and trims. Returns null when the description is empty.
+ */
+export function buildSuggestedName(agentName, descriptionParts) {
+    const description = descriptionParts.join(" ").replace(/\s+/g, " ").trim();
+    if (!description)
+        return null;
+    const name = agentName?.trim() || "unknown";
+    return { suggestedName: `Agent ${name} - ${description}`, description };
+}
+/** 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
+ * different suggested name, a bare "already seen" stamp would suppress the scan
+ * forever and leave the Stop-hook naming rule permanently unsatisfiable. */
+export function stampSessionNameSeen(coordRoot, instanceId, name) {
     return mutate(coordRoot, instanceId, (hb) => ({
         ...hb,
-        last_status_at: nowIsoSeconds(),
+        session_name_seen_at: hb.session_name_seen_at ?? nowIsoSeconds(),
+        ...(name ? { session_name_seen_for: name } : {}),
     }));
 }
 export function setTurnSummary(coordRoot, instanceId, summary) {
@@ -134,9 +160,8 @@ export function releaseClaim(coordRoot, instanceId, path) {
  * durable `claim.release` events — a file-only prune is silently reverted by
  * the next projector replay.
  *
- * files_touched can hold either absolute-under-coordRoot or canonical
- * repo-relative entries (legacy projections stored the raw tool_input path),
- * so both sides are normalized before comparing — an exact-string match
+ * Tool payloads and release calls can supply either absolute-under-coordRoot or
+ * canonical repo-relative entries, so both sides are normalized before comparing. An exact-string match
  * silently no-ops on the mixed-form case and the claim never releases.
  *
  * This is the Option B fix for post-commit's pid-map attribution hole: a
@@ -203,7 +228,7 @@ export function healPidmap(coordRoot, instanceId, pid) {
     const dir = join(coordRoot, ".harnery", "pid-map");
     mkdirSync(dir, { recursive: true });
     const hb = readHeartbeat(coordRoot, instanceId);
-    const platform = hb?.platform ?? "claude_code";
+    const platform = hb?.platform ?? "claude-code";
     const pmPath = join(dir, String(pid));
     // Drift guard: only write + emit telemetry when the entry is missing or
     // points at a different owner. Without this, a per-tool-call heal would
@@ -226,7 +251,7 @@ export function healPidmap(coordRoot, instanceId, pid) {
         ...(existingOwner ? { prior: existingOwner.slice(0, 8) } : {}),
     });
 }
-export function healHeartbeat(coordRoot, instanceId, sessionId, model, adapter) {
+export function healHeartbeat(coordRoot, instanceId, sessionId, model, adapter, opts) {
     const path = heartbeatPath(coordRoot, instanceId);
     if (existsSync(path)) {
         // Already alive, return it.
@@ -240,8 +265,8 @@ export function healHeartbeat(coordRoot, instanceId, sessionId, model, adapter)
     let agentId = "";
     try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { resolveName } = require("./names.ts");
-        const resolved = resolveName(coordRoot, instanceId, sessionId);
+        const names = require("./names.ts");
+        const resolved = names.resolveName(coordRoot, instanceId, sessionId);
         if (resolved) {
             name = resolved.name;
             kind = resolved.kind;
@@ -249,6 +274,16 @@ export function healHeartbeat(coordRoot, instanceId, sessionId, model, adapter)
             // 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 */
@@ -264,19 +299,21 @@ export function healHeartbeat(coordRoot, instanceId, sessionId, model, adapter)
         started_at: now,
         last_heartbeat: now,
         files_touched: [],
-        // Default to claude_code only when the caller can't tell us the adapter
+        // 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.
+        // 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.
+    // 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;
 }

package/dist/core/agents/state/names.d.ts

@@ -31,6 +31,10 @@ export interface NameHistoryRow {
     /** Audit marker distinguishing an explicit role adoption from pool assignment. */
     source?: "pool" | "identity.assume";
     previous_name?: string;
+    /** Instance this session was forked/branched from (recorded fork lineage).
+     * Stamped only on the row that first assigns this instance, when the adapter
+     * layer detected or supplied a parent conversation. */
+    forked_from?: string;
 }
 /**
  * Resolve (name, kind) for an existing owner without consuming a counter
@@ -66,5 +70,22 @@ export declare function recordNameAssumption(coordRoot: string, instanceId: stri
  * Assign a name to <instanceId> with the given <kind>. Counter-consuming when
  * the owner is new. Idempotent: returns existing name on resume.
  */
-export declare function assignName(coordRoot: string, instanceId: string, kind: NameKind): string;
+export declare function assignName(coordRoot: string, instanceId: string, kind: NameKind, opts?: {
+    forkedFrom?: string;
+}): string;
+/** One step of recorded fork lineage: the latest row for <instanceId> that
+ * carries `forked_from` (latest-row-wins, matching resolveName). */
+export declare function readForkParent(coordRoot: string, instanceId: string): {
+    instance_id: string;
+    name: string | null;
+} | null;
+/**
+ * Full recorded fork ancestry for <instanceId>, nearest ancestor first, each
+ * with its latest resolved name. Depth-capped and cycle-guarded: lineage is
+ * append-only operational data, not something to trust unboundedly.
+ */
+export declare function resolveForkAncestry(coordRoot: string, instanceId: string): Array<{
+    instance_id: string;
+    name: string | null;
+}>;
 //# sourceMappingURL=names.d.ts.map

package/dist/core/agents/state/names.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,qBAAqB;AACrB,eAAO,MAAM,WAAW,y5EA+Qd,CAAC;AAMX,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAsCD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA4B5D;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACrE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,QAAoB,GACzB,oBAAoB,CAoBtB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAsBxF"}
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,qBAAqB;AACrB,eAAO,MAAM,WAAW,y5EA+Qd,CAAC;AAMX,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;2DAEuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAsCD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA4B5D;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACrE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,QAAoB,GACzB,oBAAoB,CAoBtB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,QAAQ,EACd,IAAI,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,MAAM,CA0BR;AAED;oEACoE;AACpE,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAUrD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,KAAK,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAYrD"}

package/dist/core/agents/state/names.js

@@ -389,8 +389,10 @@ export function recordNameAssumption(coordRoot, instanceId, name, agentId, kind
  * Assign a name to <instanceId> with the given <kind>. Counter-consuming when
  * the owner is new. Idempotent: returns existing name on resume.
  */
-export function assignName(coordRoot, instanceId, kind) {
-    // Check 1: existing history row → original name.
+export function assignName(coordRoot, instanceId, kind, opts) {
+    // Check 1: existing history row → original name. A resume re-enters here,
+    // which also makes fork stamping naturally idempotent: lineage lands only on
+    // the row that first assigns the instance.
     const existing = resolveName(coordRoot, instanceId);
     if (existing)
         return existing.name;
@@ -404,12 +406,48 @@ export function assignName(coordRoot, instanceId, kind) {
     }
     const name = COORD_NAMES[counter % 260];
     atomicWrite(cPath, String(counter + 1));
+    const forkedFrom = opts?.forkedFrom;
     appendHistory(coordRoot, {
         instance_id: instanceId,
         name,
         kind,
         source: "pool",
+        ...(forkedFrom && forkedFrom !== instanceId ? { forked_from: forkedFrom } : {}),
         ts: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
     });
     return name;
 }
+/** One step of recorded fork lineage: the latest row for <instanceId> that
+ * carries `forked_from` (latest-row-wins, matching resolveName). */
+export function readForkParent(coordRoot, instanceId) {
+    const history = readHistory(coordRoot);
+    for (let i = history.length - 1; i >= 0; i--) {
+        const row = history[i];
+        if (row.instance_id !== instanceId)
+            continue;
+        if (!row.forked_from)
+            return null;
+        const parent = resolveName(coordRoot, row.forked_from);
+        return { instance_id: row.forked_from, name: parent?.name ?? null };
+    }
+    return null;
+}
+/**
+ * Full recorded fork ancestry for <instanceId>, nearest ancestor first, each
+ * with its latest resolved name. Depth-capped and cycle-guarded: lineage is
+ * append-only operational data, not something to trust unboundedly.
+ */
+export function resolveForkAncestry(coordRoot, instanceId) {
+    const out = [];
+    const seen = new Set([instanceId]);
+    let cursor = instanceId;
+    for (let depth = 0; depth < 20; depth++) {
+        const parent = readForkParent(coordRoot, cursor);
+        if (!parent || seen.has(parent.instance_id))
+            break;
+        out.push(parent);
+        seen.add(parent.instance_id);
+        cursor = parent.instance_id;
+    }
+    return out;
+}