harnery 0.31.6 → 0.33.0

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

@@ -24,6 +24,12 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { emit } from "../events/emit.ts";
+import {
+  type AgentActivity,
+  applySessionStateEvent,
+  type SessionStateEvidenceEvent,
+  type TaskState,
+} from "./session-state.ts";
 
 /** Inline adapter normalizer (mirrors canonical-emit.normalizeAdapter), kept
  * local so the writer's only cross-module dep is the in-process emit(). */
@@ -33,14 +39,13 @@ function adapterOf(platform: string | undefined): "claude-code" | "cursor" | "co
   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: string | undefined): string {
   if (adapter === "cursor") return "cursor";
   if (adapter === "codex") return "codex";
-  return "claude_code";
+  return "claude-code";
 }
 
 /**
@@ -87,6 +92,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;
@@ -95,6 +117,7 @@ export interface Heartbeat {
   last_tool_at?: string;
   current_turn_id?: string;
   parent_instance_id?: string;
+  workflow_run_id?: string;
   [extra: string]: unknown;
 }
 
@@ -123,6 +146,32 @@ export function readHeartbeat(coordRoot: string, instanceId: string): Heartbeat
   }
 }
 
+/** 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: string,
+  instanceId: string,
+  event: Omit<SessionStateEvidenceEvent, "data"> & { data: unknown },
+): Heartbeat | null {
+  return mutate(coordRoot, instanceId, (heartbeat) => {
+    const data =
+      typeof event.data === "object" && event.data !== null && !Array.isArray(event.data)
+        ? (event.data as Record<string, unknown>)
+        : {};
+    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: string,
   instanceId: string,
@@ -139,18 +188,66 @@ function mutate(
 export function setTask(coordRoot: string, instanceId: string, task: string): Heartbeat | null {
   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: 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 function buildSuggestedName(
+  agentName: string,
+  descriptionParts: string[],
+): { suggestedName: string; description: string } | null {
+  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: string,
+  task: string | undefined,
+  state: TaskState,
+): string | null {
+  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: string,
+  instanceId: string,
+  name?: string,
+): Heartbeat | null {
   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 } : {}),
   }));
 }
 
@@ -200,9 +297,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
@@ -264,7 +360,7 @@ export function healPidmap(coordRoot: string, instanceId: string, pid: number):
   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
@@ -291,6 +387,7 @@ export function healHeartbeat(
   sessionId?: string,
   model?: string,
   adapter?: string,
+  opts?: { forkedFrom?: string },
 ): Heartbeat | null {
   const path = heartbeatPath(coordRoot, instanceId);
   if (existsSync(path)) {
@@ -306,14 +403,28 @@ export function healHeartbeat(
   let agentId = "";
   try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { resolveName } = require("./names.ts") as typeof import("./names.ts");
-    const resolved = resolveName(coordRoot, instanceId, sessionId);
+    const names = require("./names.ts") as typeof import("./names.ts");
+    const resolved = names.resolveName(coordRoot, instanceId, sessionId);
     if (resolved) {
       name = resolved.name;
       kind = resolved.kind;
       // An explicitly assumed session carries its durable persona UUID in
       // 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 */
@@ -330,19 +441,21 @@ export function healHeartbeat(
     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/src/core/agents/state/names.ts

@@ -312,6 +312,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;
 }
 
 function atomicWrite(path: string, content: string): void {
@@ -433,8 +437,15 @@ export function recordNameAssumption(
  * 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: string, instanceId: string, kind: NameKind): string {
-  // Check 1: existing history row → original name.
+export function assignName(
+  coordRoot: string,
+  instanceId: string,
+  kind: NameKind,
+  opts?: { forkedFrom?: string },
+): string {
+  // 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;
 
@@ -447,12 +458,53 @@ export function assignName(coordRoot: string, instanceId: string, kind: NameKind
   }
   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: string,
+  instanceId: string,
+): { instance_id: string; name: string | null } | null {
+  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: string,
+  instanceId: string,
+): Array<{ instance_id: string; name: string | null }> {
+  const out: Array<{ instance_id: string; name: string | null }> = [];
+  const seen = new Set<string>([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;
+}

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

@@ -0,0 +1,131 @@
+/** What the agent is doing now. `unknown` is evidence-safe, not an error. */
+export type AgentActivity = "unknown" | "working" | "needs_input" | "idle";
+
+/** Whether the declared task remains open. Activity never changes this axis. */
+export type TaskState = "active" | "blocked" | "done";
+
+/** Raw fields stored in a live heartbeat and rebuilt from canonical events. */
+export interface SessionStateFields {
+  activity?: AgentActivity;
+  activity_updated_at?: string;
+  activity_source?: string;
+  task_state?: TaskState;
+  task_state_updated_at?: string;
+  task_state_reason?: string;
+}
+
+/** Reader-facing state with compatibility defaults applied. */
+export interface SessionState extends SessionStateFields {
+  activity: AgentActivity;
+  task_state: TaskState;
+}
+
+export interface SessionStateSelector {
+  instance_id?: string;
+  session_id?: string;
+}
+
+export interface SessionStateEvidenceEvent {
+  event_type: string;
+  ts: string;
+  data?: Record<string, unknown>;
+  instance_id?: string;
+  session_id?: string;
+}
+
+const TERMINAL_ACTIVITY_EVENTS = new Set(["session.end", "subagent.stop", "turn.stop"]);
+
+/**
+ * Apply one canonical event to the two independent state axes.
+ *
+ * The table is deliberately evidence-only. Output chunks, post-tool events,
+ * narration, coordination commands, and elapsed time cannot clear an observed
+ * input wait. A command start only counts as progress when the session was
+ * already inside an open turn (`working` or `needs_input`).
+ */
+export function applySessionStateEvent(
+  current: Readonly<SessionStateFields>,
+  event: SessionStateEvidenceEvent,
+): SessionStateFields {
+  const next: SessionStateFields = { ...current };
+
+  if (event.event_type === "session.start" || event.event_type === "subagent.start") {
+    setActivity(next, "idle", event);
+  } else if (event.event_type === "user_prompt.submit" || event.event_type === "tool.pre_use") {
+    setActivity(next, "working", event);
+  } else if (event.event_type === "interaction.input_requested") {
+    setActivity(next, "needs_input", event);
+  } else if (
+    event.event_type === "command.start" &&
+    (current.activity === "working" || current.activity === "needs_input")
+  ) {
+    setActivity(next, "working", event);
+  } else if (TERMINAL_ACTIVITY_EVENTS.has(event.event_type)) {
+    setActivity(next, "idle", event);
+  }
+
+  if (event.event_type === "state.task_state") {
+    const data = event.data ?? {};
+    const state = field(data, "state");
+    if (state === "active" || state === "blocked" || state === "done") {
+      next.task_state = state;
+      next.task_state_updated_at = event.ts;
+      const reason = field(data, "reason");
+      if (typeof reason === "string" && reason.length > 0) {
+        next.task_state_reason = reason;
+      } else {
+        delete next.task_state_reason;
+      }
+    }
+  }
+
+  return next;
+}
+
+/**
+ * Rebuild both axes from canonical events after a heartbeat has disappeared.
+ * Events may be the whole ledger or an already-filtered session slice.
+ */
+export function foldSessionState(
+  events: readonly SessionStateEvidenceEvent[],
+  selector: SessionStateSelector = {},
+): SessionState {
+  const ordered = events
+    .map((event, index) => ({ event, index }))
+    .filter(({ event }) => matches(event, selector))
+    .sort((a, b) => timestamp(a.event) - timestamp(b.event) || a.index - b.index);
+
+  let fields: SessionStateFields = {};
+  for (const { event } of ordered) fields = applySessionStateEvent(fields, event);
+
+  return {
+    ...fields,
+    activity: fields.activity ?? "unknown",
+    task_state: fields.task_state ?? "active",
+  };
+}
+
+function setActivity(
+  target: SessionStateFields,
+  activity: AgentActivity,
+  event: SessionStateEvidenceEvent,
+): void {
+  target.activity = activity;
+  target.activity_updated_at = event.ts;
+  target.activity_source = event.event_type;
+}
+
+function matches(event: SessionStateEvidenceEvent, selector: SessionStateSelector): boolean {
+  if (selector.instance_id && event.instance_id !== selector.instance_id) return false;
+  if (selector.session_id && event.session_id !== selector.session_id) return false;
+  return true;
+}
+
+function timestamp(event: SessionStateEvidenceEvent): number {
+  const parsed = Date.parse(event.ts);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function field(data: Record<string, unknown>, key: string): unknown {
+  return data[key];
+}

package/src/core/config.ts

@@ -7,7 +7,7 @@
  *   2. `<project-root>/.harnery/config.jsonc` — project override (authoritative)
  *
  * Fields owned here: `binName` (host CLI name for agent-facing strings),
- * `hooksSetupHint`, `tools`, `workflow`, `skills`, `presence`, plus the tunable
+ * `hooksSetupHint`, `agents`, `tools`, `workflow`, `skills`, `presence`, plus the tunable
  * `coord` (heartbeat freshness), `artifacts` (working-file retention),
  * `backup` (restic repo/password/prune policy), and `sync` (rclone
  * remote/prefix) sections. The `files` deny/override section
@@ -30,6 +30,13 @@ export const DEFAULT_BIN_NAME = "harn";
 /** Heartbeat-freshness default (seconds): the sweep window when nothing overrides it. */
 export const DEFAULT_FRESHNESS_SECS = 600;
 
+export type AgentFinalizationDisposition = "git" | "output";
+
+export interface AgentFinalizationRoot {
+  path: string;
+  disposition: AgentFinalizationDisposition;
+}
+
 interface HarneryConfig {
   /** Host CLI bin name, stamped by `harn init` for a consumer (e.g. "acme"). */
   binName?: string;
@@ -41,6 +48,15 @@ interface HarneryConfig {
    * declares it here (e.g. "scripts/setup-hooks.sh"). Unset → a generic hint.
    */
   hooksSetupHint?: string;
+  /**
+   * Agent-ritual policy owned by the host project. Git finalization is opt-in:
+   * standalone Harnery and embedding hosts keep the ordinary status ritual
+   * unless the project deliberately requires the guarded check.
+   */
+  agents?: {
+    requireGitFinalization?: boolean;
+    finalizationRoots?: AgentFinalizationRoot[];
+  };
   /**
    * Managed-tool provisioning consent. `{ ripgrep: { autoInstall: true } }`
    * lets `grep` download the pinned, checksum-verified ripgrep into the
@@ -157,6 +173,16 @@ function statMtime(p: string): number {
   }
 }
 
+/** Cache signature, or null when the file can't be stat'd (missing). */
+function statSignature(p: string): string | null {
+  try {
+    const stat = statSync(p);
+    return `${stat.mtimeMs}:${stat.ctimeMs}:${stat.size}`;
+  } catch {
+    return null;
+  }
+}
+
 /** Parse one JSONC config file to an object; missing/unparseable → `{}`. */
 function parseConfigFile(p: string): HarneryConfig {
   try {
@@ -186,8 +212,13 @@ function mergeConfig(base: HarneryConfig, override: HarneryConfig): HarneryConfi
   return out as HarneryConfig;
 }
 
-// mtime-keyed per-process cache (both layers): a stat is cheap, a parse on every render isn't.
-let cache: { root: string; projMtime: number; userMtime: number; cfg: HarneryConfig } | null = null;
+// Stat-signature-keyed per-process cache (both layers): a stat is cheap, a parse on every render isn't.
+let cache: {
+  root: string;
+  projSignature: string | null;
+  userSignature: string | null;
+  cfg: HarneryConfig;
+} | null = null;
 
 /**
  * The effective config for `root`: user-global (`~/.config/harnery/config.jsonc`)
@@ -197,20 +228,20 @@ let cache: { root: string; projMtime: number; userMtime: number; cfg: HarneryCon
 function readConfig(root: string): HarneryConfig {
   const projPath = join(root, ".harnery", "config.jsonc");
   const userPath = userConfigPath();
-  const projMtime = statMtime(projPath);
-  const userMtime = statMtime(userPath);
+  const projSignature = statSignature(projPath);
+  const userSignature = statSignature(userPath);
   if (
     cache &&
     cache.root === root &&
-    cache.projMtime === projMtime &&
-    cache.userMtime === userMtime
+    cache.projSignature === projSignature &&
+    cache.userSignature === userSignature
   ) {
     return cache.cfg;
   }
-  const user = userMtime === -1 ? {} : parseConfigFile(userPath);
-  const project = projMtime === -1 ? {} : parseConfigFile(projPath);
+  const user = userSignature === null ? {} : parseConfigFile(userPath);
+  const project = projSignature === null ? {} : parseConfigFile(projPath);
   const cfg = mergeConfig(user, project);
-  cache = { root, projMtime, userMtime, cfg };
+  cache = { root, projSignature, userSignature, cfg };
   return cfg;
 }
 
@@ -270,6 +301,55 @@ export function resolveHooksSetupHint(coordRoot?: string | null): string | null
   return typeof hint === "string" && hint.trim() ? hint.trim() : null;
 }
 
+/**
+ * Whether the host requires the guarded Git check at the end of tool-using
+ * turns. Default false: Harnery exposes `agents status --end-turn` as a capability
+ * but does not impose a commit-and-push policy on embedding projects.
+ *
+ * `.harnery/config.jsonc`:
+ * `{ "agents": { "requireGitFinalization": true } }`
+ *
+ * `HARNERY_AGENTS_REQUIRE_GIT_FINALIZATION=1|0` overrides per process.
+ */
+export function agentsRequireGitFinalization(coordRoot?: string | null): boolean {
+  const env = coordEnv("AGENTS_REQUIRE_GIT_FINALIZATION");
+  if (env === "1") return true;
+  if (env === "0") return false;
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return false;
+  return readConfig(root).agents?.requireGitFinalization === true;
+}
+
+/**
+ * Extra roots whose guarded writes have an explicit end-turn disposition.
+ *
+ * This trust boundary comes only from the project config. A user-global config
+ * may tune ordinary behavior, but it cannot grant one project filesystem
+ * authority outside its coordination root. Paths may be absolute or relative
+ * to the coordination root. Invalid entries are ignored here and fail closed
+ * when the finalization policy validates them.
+ */
+export function agentsFinalizationRoots(coordRoot?: string | null): AgentFinalizationRoot[] {
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return [];
+  const entries = readProjectConfig(root).agents?.finalizationRoots;
+  if (!Array.isArray(entries)) return [];
+  return entries.flatMap((entry) => {
+    if (!entry || typeof entry !== "object") return [];
+    const path = typeof entry.path === "string" ? entry.path.trim() : "";
+    const disposition = entry.disposition;
+    if (!path || (disposition !== "git" && disposition !== "output")) return [];
+    return [{ path, disposition }];
+  });
+}
+
+/** The status command automatic prompts and Stop remediation should request. */
+export function endOfTurnStatusCommand(coordRoot?: string | null): string {
+  const root = coordRoot ?? findCoordRoot();
+  const suffix = agentsRequireGitFinalization(root) ? " --end-turn" : "";
+  return `${resolveBinName(root)} agents status${suffix}`;
+}
+
 /**
  * Whether the host project consented to automatic ripgrep provisioning:
  * `.harnery/config.jsonc` `{ "tools": { "ripgrep": { "autoInstall": true } } }`.
@@ -349,13 +429,13 @@ function posIntOr(v: unknown, fallback: number): number {
  * The heartbeat-freshness window (seconds): the age above which the sweeper
  * prunes an agent, and the cutoff the `agents` surface uses to fold stale peers.
  * Precedence:
- *   1. `HARNERY_AGENT_COORD_FRESHNESS` env (canonical), or `HARNERY_AGENT_FRESHNESS` (legacy alias)
+ *   1. `HARNERY_AGENT_COORD_FRESHNESS` env
  *   2. `.harnery/config.jsonc` `coord.freshness_seconds`
  *   3. `600` (10 minutes)
  * `coordRoot` is resolved via `findCoordRoot()` when not passed.
  */
 export function coordFreshnessSeconds(coordRoot?: string | null): number {
-  const env = coordEnv("AGENT_COORD_FRESHNESS") ?? coordEnv("AGENT_FRESHNESS");
+  const env = coordEnv("AGENT_COORD_FRESHNESS");
   if (env !== undefined) {
     const n = Number.parseInt(env, 10);
     if (Number.isFinite(n) && n > 0) return n;