harnery 0.31.6 → 0.32.0

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

@@ -34,6 +34,9 @@ export interface V2Heartbeat {
   last_tool_at?: string;
   task?: string;
   task_updated_at?: string;
+  suggested_session_name?: string;
+  session_name_seen_at?: string;
+  session_name_seen_for?: string;
   last_status_at?: string;
   presence?: "mobile" | "office";
   last_intent?: string;
@@ -245,6 +248,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 +316,11 @@ 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;
     }
 
@@ -322,6 +342,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 +374,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;
@@ -493,6 +526,17 @@ 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, "suggested_session_name", hb.suggested_session_name);
+    setIfDefined(merged, "session_name_seen_at", hb.session_name_seen_at);
+    if (hb.session_name_seen_for) {
+      merged.session_name_seen_for = hb.session_name_seen_for;
+    } else {
+      // Unlike most projected fields, an absent attribution is meaningful: a
+      // legacy sighting cannot prove which suggested name it covered. Remove a
+      // stale value inherited through the additive merge so the next stop
+      // scans the current name instead of treating it as already satisfied.
+      delete merged.session_name_seen_for;
+    }
     setIfDefined(merged, "last_status_at", hb.last_status_at);
     setIfDefined(merged, "turn_summary", hb.turn_summary);
     setIfDefined(merged, "turn_summary_updated_at", hb.turn_summary_updated_at);

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

@@ -33,14 +33,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 +86,17 @@ export interface Heartbeat {
   files_touched: string[];
   task?: string;
   task_updated_at?: string | null;
+  /** Session name built on the first non-empty set-task (never rebuilt). Its
+   * presence is the "this session has been named" signal the prompt-context
+   * nudge and the Stop-hook naming rule key on. */
+  suggested_session_name?: string;
+  /** Stamped by turn.stop once the suggested name is seen in assistant reply
+   * text, ending the per-turn transcript scan. */
+  session_name_seen_at?: string;
+  /** WHICH name that sighting was for. The scan is skipped only while this
+   * matches the current suggested name, so a re-minted name is detectable
+   * again rather than being suppressed by the earlier sighting. */
+  session_name_seen_for?: string;
   last_status_at?: string;
   turn_summary?: string | null;
   turn_summary_updated_at?: string | null;
@@ -95,6 +105,7 @@ export interface Heartbeat {
   last_tool_at?: string;
   current_turn_id?: string;
   parent_instance_id?: string;
+  workflow_run_id?: string;
   [extra: string]: unknown;
 }
 
@@ -139,18 +150,53 @@ 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 };
+}
+
+/** 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 +246,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 +309,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 +336,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 +352,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 +390,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/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;