harnery 0.31.6 → 0.33.0

package/src/core/agents/rules/stop-hook.ts

@@ -11,6 +11,9 @@
  *            stop currently firing carries that field via the in-flight event
  *            agent-hook emits before the stop hook runs).
  * Rule 3/3: `state.task_set` event with matching turn boundary exists.
+ * Session-naming rule (at most once per session, CC semantics only): the turn
+ *            whose set-task produced `suggested_session_name` must carry an
+ *            in-window `turn.stop` with `session_name_present: true`.
  *
  * Pure-prose-turn exemption: when zero `tool.pre_use` events fire in
  * the current turn, rules 1/3 and 3/3 do not apply. Rule 2/3 still applies
@@ -25,7 +28,11 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { resolveBinName } from "../../config.ts";
+import {
+  agentsRequireGitFinalization,
+  endOfTurnStatusCommand,
+  resolveBinName,
+} from "../../config.ts";
 
 export type { VerdictResult } from "./verdict.ts";
 
@@ -106,18 +113,6 @@ const RECENT_EVENT_WINDOW_LINES = 5_000;
  */
 export const STOP_REMEDIATION_MARKER = "[harnery:stop-remediation";
 
-/**
- * The pre-marker message shape, still recognized on purpose.
- *
- * A followup already sitting in the stream was written by whichever build was
- * running when it fired. An agent whose session spans an upgrade would otherwise
- * keep alternating until the first new-format followup appeared, which is the
- * exact failure this change removes. Recognizing the older trailing form closes
- * that rollout window at no cost: it only ever appears in a `prompt_text`
- * because Harnery put it there.
- */
-const STOP_REMEDIATION_LEGACY_MARKER = "[agent-hook stop]: rule=";
-
 /** How far back the remediation walk may travel. Adapters cap their own
  * followup chains (Cursor's `loop_limit`), and each prompt can appear once per
  * observing adapter, so this only guards a pathological stream. */
@@ -126,7 +121,7 @@ const MAX_REMEDIATION_WALK_BACK = 16;
 function isStopRemediationPrompt(event: CanonicalEvent): boolean {
   const text = event.data.prompt_text;
   if (typeof text !== "string") return false;
-  return text.includes(STOP_REMEDIATION_MARKER) || text.includes(STOP_REMEDIATION_LEGACY_MARKER);
+  return text.includes(STOP_REMEDIATION_MARKER);
 }
 
 /**
@@ -233,7 +228,7 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
       allow: true,
       exit_code: 0,
       rule: "stop-hook.no_history",
-      reason: "no canonical events for this owner; defer to legacy or skip",
+      reason: "no canonical events for this owner; nothing to evaluate",
     };
   }
 
@@ -255,7 +250,11 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
   });
 
   const toolPreUseInTurn = inTurn.some((e) => e.event_type === "tool.pre_use");
-  const statusChecked = inTurn.some((e) => e.event_type === "state.status_checked");
+  const statusEvents = inTurn.filter((e) => e.event_type === "state.status_checked");
+  const statusChecked = statusEvents.length > 0;
+  const requiredStatusChecked = agentsRequireGitFinalization(coordRoot)
+    ? statusEvents.some((e) => e.data.git_finalization_checked === true)
+    : statusChecked;
   const taskSet = inTurn.some((e) => e.event_type === "state.task_set");
 
   // Rule 2/3: status_box_present on the most recent turn.stop for this owner.
@@ -270,8 +269,14 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
   // on Claude Code / Codex it's the transcript-scanned `status_box_present`.
   // The matching block helper carries the right "how to fix" message.
   const ackSignal = ackSignalFor(req.adapter);
-  const ackPresent = ackSignal === "status_checked" ? statusChecked : boxPresent;
-  const ackBlock = ackSignal === "status_checked" ? rule13Block : rule23Block;
+  const ackPresent =
+    ackSignal === "status_checked"
+      ? toolPreUseInTurn
+        ? requiredStatusChecked
+        : statusChecked
+      : boxPresent;
+  const ackBlock =
+    ackSignal === "status_checked" ? () => rule13Block(coordRoot) : () => rule23Block(coordRoot);
 
   // Pure-prose-turn exemption: only the ack signal applies. Parity
   // across adapters: CC requires the box; Cursor requires status_checked.
@@ -287,12 +292,43 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
     };
   }
 
-  if (!statusChecked) return rule13Block();
+  if (!requiredStatusChecked) return rule13Block(coordRoot);
   // On Cursor `ackPresent === statusChecked` (already true here), so this is a
   // no-op and rule 2/3 is not enforced; on CC/Codex it's the box-paste check.
   if (!ackPresent) return ackBlock();
   if (!taskSet) return rule33Block();
 
+  // Session-naming rule (at most once per session, evaluated last so
+  // remediation stays monotonic in the established order): the turn whose
+  // set-task produced the suggested session name must show that name in the
+  // reply. Claude Code semantics only — Cursor's Stop payload carries neither
+  // a transcript nor the assistant message, so the fence is undetectable there
+  // (the same reason rule 2/3 collapses into 1/3 on Cursor), and Codex
+  // returned observe-only above. Detection rides `turn.stop`'s
+  // `session_name_present` (assistant-text-only transcript scan), mirroring
+  // how rule 2/3 rides `status_box_present`.
+  if (ackSignal === "status_box_present") {
+    const namingEvent = inTurn.find(
+      (e) =>
+        ((e.event_type === "state.task_set" && e.data.first_of_session === true) ||
+          (e.event_type === "state.task_state" && e.data.name_reminted === true)) &&
+        typeof e.data.suggested_session_name === "string" &&
+        e.data.suggested_session_name.length > 0,
+    );
+    if (namingEvent) {
+      // ANY in-window turn.stop with the flag satisfies the rule, not just the
+      // latest: once seen, `session_name_seen_at` is stamped and later
+      // turn.stops OMIT the field, so a later block on a different rule (whose
+      // repair fires a fresh turn.stop) must not un-satisfy this one.
+      const namePresent = inTurn.some(
+        (e) => e.event_type === "turn.stop" && e.data.session_name_present === true,
+      );
+      if (!namePresent) {
+        return sessionNameBlock(String(namingEvent.data.suggested_session_name));
+      }
+    }
+  }
+
   return {
     allow: true,
     exit_code: 0,
@@ -300,21 +336,33 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
   };
 }
 
-function rule13Block(): VerdictResult {
+function rule13Block(coordRoot?: string): VerdictResult {
+  const missingEvidence = agentsRequireGitFinalization(coordRoot)
+    ? "no Git-finalized state.status_checked event found in this turn"
+    : "no state.status_checked event found in this turn";
   return {
     allow: false,
     exit_code: 2,
     rule: "stop-hook.rule_1_3",
-    reason: `End-of-turn rule (1/3): no state.status_checked event found in this turn; run \`${resolveBinName()} agents status\` as your last tool call.`,
+    reason: `End-of-turn rule (1/3): ${missingEvidence}; run \`${endOfTurnStatusCommand(coordRoot)}\` as your last tool call.`,
   };
 }
 
-function rule23Block(): VerdictResult {
+function rule23Block(coordRoot?: string): VerdictResult {
   return {
     allow: false,
     exit_code: 2,
     rule: "stop-hook.rule_2_3",
-    reason: `End-of-turn rule (2/3): turn.stop did not see the agent-status box in your reply text. Paste the \`${resolveBinName()} agents status\` output verbatim as a fenced code block (the \`┌─ agent-\` prefix is the detection signal).`,
+    reason: `End-of-turn rule (2/3): turn.stop did not see the agent-status box in your reply text. Paste the \`${endOfTurnStatusCommand(coordRoot)}\` output verbatim as a fenced code block (the \`┌─ agent-\` prefix is the detection signal).`,
+  };
+}
+
+function sessionNameBlock(name: string): VerdictResult {
+  return {
+    allow: false,
+    exit_code: 2,
+    rule: "stop-hook.session_name",
+    reason: `Session-naming rule: this turn's set-task produced the session name, but your reply doesn't show it. Reproduce it by itself in a fenced code block so the operator can one-click-copy it as the session/tab title: ${name}`,
   };
 }
 

package/src/core/agents/session-events.ts

@@ -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";
@@ -15,28 +13,16 @@ import { dirname, resolve } from "node:path";
 import { normalizeAdapter, resolveEmitRoot } from "./canonical-emit.ts";
 import { emit } from "./events/emit.ts";
 
-/** 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 function sessionEventsPath(): string {
+export function canonicalEventsPath(): string {
   // 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
   // resolveEmitRoot. A plain cwd walk here mis-anchored to a NESTED
@@ -64,7 +50,7 @@ export function newCmdId(): string {
  */
 export function readLastIntent(instanceId?: string): string | null {
   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();
@@ -81,15 +67,7 @@ export function readLastIntent(instanceId?: string): string | 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: Partial<Record<SessionEventType, string>> = {
+const CANONICAL_TYPE: Record<SessionEventType, string> = {
   command_start: "command.start",
   output: "command.output",
   command_end: "command.end",
@@ -131,7 +109,7 @@ function enrichFromHeartbeat(coordRoot: string, instanceId: string): HeartbeatEn
   }
 }
 
-/** 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: SessionEventType,
@@ -158,15 +136,15 @@ function canonicalData(
 
 /** 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: SessionEventType, fields: Record<string, unknown>): void {
   const eventType = CANONICAL_TYPE[type];
   if (!eventType) return;
   const instanceId = typeof fields.instance_id === "string" ? fields.instance_id : undefined;
   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;
     emit(coordRoot, {
@@ -182,16 +160,11 @@ function emitCanonicalCommand(type: SessionEventType, fields: Record<string, unk
 }
 
 /**
- * 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: SessionEventType,
-  _agentName: string,
   fields: Record<string, unknown> = {},
 ): void {
   emitCanonicalCommand(type, fields);

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

@@ -12,6 +12,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type { CanonicalEvent } from "../events/consume.ts";
+import { type AgentActivity, applySessionStateEvent, type TaskState } from "./session-state.ts";
 
 export interface V2Heartbeat {
   instance_id: string;
@@ -21,6 +22,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;
@@ -34,6 +39,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;
@@ -177,6 +191,14 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
   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":
@@ -185,6 +207,16 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
       {
         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");
@@ -245,6 +277,18 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
     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) {
@@ -301,6 +345,26 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
         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;
     }
 
@@ -322,6 +386,19 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
       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) {
@@ -341,7 +418,7 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
 }
 
 function adapterToPlatform(adapter: string): string {
-  if (adapter === "claude-code") return "claude_code";
+  if (adapter === "claude-code") return "claude-code";
   if (adapter === "cursor") return "cursor";
   if (adapter === "codex") return "codex";
   return adapter;
@@ -480,6 +557,10 @@ function writeHeartbeat(coordRoot: string, instanceId: string, hb: V2Heartbeat):
     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
@@ -493,6 +574,27 @@ function writeHeartbeat(coordRoot: string, instanceId: string, hb: V2Heartbeat):
     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);
@@ -536,3 +638,8 @@ function pickBool(o: Record<string, unknown>, k: string): boolean | undefined {
   const v = o[k];
   return typeof v === "boolean" ? v : undefined;
 }
+
+function pickNum(o: Record<string, unknown>, k: string): number | undefined {
+  const v = o[k];
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}