harnery 0.31.6 → 0.33.0

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

@@ -9,6 +9,7 @@
  * through the canonical event stream) survive each projector run.
  */
 import type { CanonicalEvent } from "../events/consume.js";
+import { type AgentActivity, type TaskState } from "./session-state.js";
 export interface V2Heartbeat {
     instance_id: string;
     session_id: string;
@@ -17,6 +18,10 @@ export interface V2Heartbeat {
     name?: string;
     kind?: "session" | "subagent" | "transient";
     model?: string;
+    instruction_bundle_id?: string;
+    instruction_source_id?: string;
+    instruction_profile_root?: string;
+    instruction_component_count?: number;
     platform?: string;
     subagent_call_id?: string;
     parent_session_id?: string;
@@ -30,6 +35,15 @@ export interface V2Heartbeat {
     last_tool_at?: string;
     task?: string;
     task_updated_at?: string;
+    activity?: AgentActivity;
+    activity_updated_at?: string;
+    activity_source?: string;
+    task_state?: TaskState;
+    task_state_updated_at?: string;
+    task_state_reason?: 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":"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"}

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

@@ -10,6 +10,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { applySessionStateEvent } from "./session-state.js";
 export function projectHeartbeats(coordRoot, events) {
     const perOwner = {};
     // Events that must NOT seed a heartbeat for an owner with no live file.
@@ -122,6 +123,13 @@ function apply(hb, ev, coordRoot) {
     hb.v2_meta.last_projected = new Date().toISOString();
     if (ev.turn_id)
         hb.last_turn_id = ev.turn_id;
+    const sessionState = applySessionStateEvent(hb, ev);
+    hb.activity = sessionState.activity;
+    hb.activity_updated_at = sessionState.activity_updated_at;
+    hb.activity_source = sessionState.activity_source;
+    hb.task_state = sessionState.task_state;
+    hb.task_state_updated_at = sessionState.task_state_updated_at;
+    hb.task_state_reason = sessionState.task_state_reason;
     const d = ev.data;
     switch (ev.event_type) {
         case "session.start":
@@ -131,6 +139,19 @@ function apply(hb, ev, coordRoot) {
                 const model = pickStr(d, "model");
                 if (model)
                     hb.model = model;
+                const instructionBundleId = pickStr(d, "instruction_bundle_id");
+                if (instructionBundleId)
+                    hb.instruction_bundle_id = instructionBundleId;
+                const instructionSourceId = pickStr(d, "instruction_source_id");
+                if (instructionSourceId)
+                    hb.instruction_source_id = instructionSourceId;
+                const instructionProfileRoot = pickStr(d, "instruction_profile_root");
+                if (instructionProfileRoot)
+                    hb.instruction_profile_root = instructionProfileRoot;
+                const instructionComponentCount = pickNum(d, "instruction_component_count");
+                if (instructionComponentCount !== undefined) {
+                    hb.instruction_component_count = instructionComponentCount;
+                }
                 const platform = pickStr(d, "platform") ?? adapterToPlatform(ev.adapter);
                 hb.platform = platform;
                 const name = pickStr(d, "name");
@@ -197,6 +218,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 +287,25 @@ 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.task_state": {
+            const suggested = pickStr(d, "suggested_session_name");
+            if (suggested && suggested !== hb.suggested_session_name) {
+                // Older heartbeats predate session_name_seen_for. A lifecycle re-mint
+                // still needs a mismatch the prompt and Stop paths can enforce, so
+                // attribute the prior title before replacing it. Ordinary legacy
+                // heartbeats remain quiet until a real lifecycle event changes them.
+                if (!hb.session_name_seen_for && hb.suggested_session_name) {
+                    hb.session_name_seen_for = hb.suggested_session_name;
+                }
+                hb.suggested_session_name = suggested;
+            }
             break;
         }
         case "state.status_checked":
@@ -274,6 +326,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 +358,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")
@@ -433,6 +499,10 @@ function writeHeartbeat(coordRoot, instanceId, hb) {
         setIfDefined(merged, "workflow_run_id", hb.workflow_run_id);
         setIfDefined(merged, "workflow_agent_id", hb.workflow_agent_id);
         setIfDefined(merged, "model", hb.model);
+        setIfDefined(merged, "instruction_bundle_id", hb.instruction_bundle_id);
+        setIfDefined(merged, "instruction_source_id", hb.instruction_source_id);
+        setIfDefined(merged, "instruction_profile_root", hb.instruction_profile_root);
+        setIfDefined(merged, "instruction_component_count", hb.instruction_component_count);
         setIfDefined(merged, "platform", hb.platform);
         setIfDefined(merged, "started_at", hb.started_at);
         // files_touched is a required-array invariant for every reader
@@ -446,6 +516,29 @@ 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, "activity", hb.activity);
+        setIfDefined(merged, "activity_updated_at", hb.activity_updated_at);
+        setIfDefined(merged, "activity_source", hb.activity_source);
+        setIfDefined(merged, "task_state", hb.task_state);
+        setIfDefined(merged, "task_state_updated_at", hb.task_state_updated_at);
+        if (hb.task_state_reason) {
+            merged.task_state_reason = hb.task_state_reason;
+        }
+        else if (hb.task_state) {
+            delete merged.task_state_reason;
+        }
+        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);
@@ -482,3 +575,7 @@ function pickBool(o, k) {
     const v = o[k];
     return typeof v === "boolean" ? v : undefined;
 }
+function pickNum(o, k) {
+    const v = o[k];
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}

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

@@ -12,6 +12,7 @@
  * Owner identity invariant: every action operates on `.harnery/active/<instance_id>.json`
  * (the file IS the heartbeat). No mutations happen elsewhere.
  */
+import { type AgentActivity, type SessionStateEvidenceEvent, type TaskState } from "./session-state.js";
 export interface Heartbeat {
     schema_version?: number;
     instance_id: string;
@@ -27,6 +28,23 @@ export interface Heartbeat {
     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.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 +53,34 @@ 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;
+/** Apply one evidence event to the live state fields without draining the
+ * global event stream. This keeps permission prompts current while avoiding
+ * unrelated projector side effects before a tool authorization verdict. */
+export declare function stampSessionStateEvent(coordRoot: string, instanceId: string, event: Omit<SessionStateEvidenceEvent, "data"> & {
+    data: unknown;
+}): 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;
+/** Build the operator-facing title projected from an explicit task lifecycle. */
+export declare function buildLifecycleSuggestedName(agentName: string, task: string | undefined, state: TaskState): 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 +98,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 +109,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":"AAAA;;;;;;;;;;;;;GAaG;AA6DH,MAAM,WAAW,SAAS;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAiBD,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAQrF;AAeD,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAS7F;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKxF;AAED,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,SAAS,GAAG,IAAI,CAMlB;AAED,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,SAAS,GAAG,IAAI,CAYlB;AAED,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE,CAsChG;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAS5E;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAuBnF;AAED,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,GAAG,IAAI,CAsDlB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;IACJ,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACA,SAAS,CAwBX;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,SAAS,GAAG,IAAI,CAOlB"}
+{"version":3,"file":"heartbeat-writer.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/heartbeat-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAaH,OAAO,EACL,KAAK,aAAa,EAElB,KAAK,yBAAyB,EAC9B,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAC;AAgD5B,MAAM,WAAW,SAAS;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,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;IAC3B;;qDAEiD;IACjD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;oDACgD;IAChD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;qEAEiE;IACjE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAiBD,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAQrF;AAED;;2EAE2E;AAC3E,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,IAAI,CAAC,yBAAyB,EAAE,MAAM,CAAC,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjE,SAAS,GAAG,IAAI,CAiBlB;AAeD,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAmB7F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,EAAE,GACzB;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKvD;AAED,iFAAiF;AACjF,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,EAAE,SAAS,GACf,MAAM,GAAG,IAAI,CAMf;AAED;;;;4EAI4E;AAC5E,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,MAAM,GACZ,SAAS,GAAG,IAAI,CAMlB;AAED,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,SAAS,GAAG,IAAI,CAMlB;AAED,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,SAAS,GAAG,IAAI,CAYlB;AAED,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE,CAsChG;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAS5E;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAuBnF;AAED,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,SAAS,GAAG,IAAI,CAsElB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;IACJ,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACA,SAAS,CAwBX;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,SAAS,GAAG,IAAI,CAOlB"}

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

@@ -15,6 +15,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { emit } from "../events/emit.js";
+import { applySessionStateEvent, } from "./session-state.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) {
@@ -24,16 +25,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
@@ -81,6 +81,26 @@ export function readHeartbeat(coordRoot, instanceId) {
         return null;
     }
 }
+/** Apply one evidence event to the live state fields without draining the
+ * global event stream. This keeps permission prompts current while avoiding
+ * unrelated projector side effects before a tool authorization verdict. */
+export function stampSessionStateEvent(coordRoot, instanceId, event) {
+    return mutate(coordRoot, instanceId, (heartbeat) => {
+        const data = typeof event.data === "object" && event.data !== null && !Array.isArray(event.data)
+            ? event.data
+            : {};
+        const state = applySessionStateEvent(heartbeat, { ...event, data });
+        return {
+            ...heartbeat,
+            activity: state.activity,
+            activity_updated_at: state.activity_updated_at,
+            activity_source: state.activity_source,
+            task_state: state.task_state,
+            task_state_updated_at: state.task_state_updated_at,
+            task_state_reason: state.task_state_reason,
+        };
+    });
+}
 function mutate(coordRoot, instanceId, fn) {
     const hb = readHeartbeat(coordRoot, instanceId);
     if (!hb)
@@ -93,17 +113,55 @@ 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 };
+}
+/** Build the operator-facing title projected from an explicit task lifecycle. */
+export function buildLifecycleSuggestedName(agentName, task, state) {
+    const built = buildSuggestedName(agentName, task ? [task] : []);
+    if (!built)
+        return null;
+    if (state === "blocked")
+        return `[BLOCKED] - ${built.suggestedName}`;
+    if (state === "done")
+        return `[DONE] - ${built.suggestedName}`;
+    return built.suggestedName;
+}
+/** 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 +192,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 +260,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 +283,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 +297,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 +306,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 +331,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"}