harnery 0.45.2 → 0.46.1

package/src/core/hooks/cli.ts

@@ -69,6 +69,7 @@ import {
   agentsRequireGitFinalization,
   coordFreshnessSeconds,
   hostPromptContextConfig,
+  readAdmissionConfig,
   resolveBinName,
 } from "../config.ts";
 import {
@@ -92,6 +93,7 @@ import {
 import type { TurnRitualEvidenceV3 } from "../events/v3/producers/hook-base.ts";
 import { captureSpanClockV3 } from "../events/v3/span-state.ts";
 import { ensureRelayDaemon, fetchPresence, publishPresence } from "../presence/index.ts";
+import { importMail, publishMail } from "../presence/mail.ts";
 import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.ts";
 import { stableScopeId } from "../workflow/scope-id.ts";
 import { type AdapterBehavior, adapterBehavior } from "./adapter/behaviors/index.ts";
@@ -137,11 +139,13 @@ import type { SessionNameDisplayInspection } from "./resolve/transcript.ts";
 import {
   inspectSessionNameDisplayImmediately,
   scanAssistantStatusBoxPresent,
+  scanPendingBackgroundHandoffs,
   scanStatusBoxPresent,
   scanTranscriptRuntime,
 } from "./resolve/transcript.ts";
 import { clearHookRunMarker, writeHookRunMarker } from "./run-markers.ts";
 import { sessionNamePresence } from "./session-name-presence.ts";
+import { shellCommitTreeReason } from "./shell-commit-tree.ts";
 import { shellRmReason } from "./shell-rm.ts";
 import { shellWaiterReason } from "./shell-waiter.ts";
 
@@ -343,8 +347,17 @@ function ensureSessionDisplayName(
   payload: ParsedPayload | null,
 ): void {
   if (coordEnv("WORKFLOW_CHILD") === "1") return;
-  const row =
-    readLiveCoordinationRow(coordRoot, instanceId) ?? readHeartbeat(coordRoot, instanceId);
+  // This runs on every tool call. The heartbeat cache is the surface this
+  // function stamps, so a cache that already carries a name, or marks a
+  // session that never takes one, means there is nothing to do. Only a cache
+  // that cannot answer pays for the authoritative read, which re-validates the
+  // whole active ledger and cost about half a second per call at 22 MB.
+  const cached = readHeartbeat(coordRoot, instanceId);
+  if (cached?.kind === "subagent" || cached?.kind === "transient" || cached?.workflow_run_id) {
+    return;
+  }
+  if (cached?.name?.trim()) return;
+  const row = readLiveCoordinationRow(coordRoot, instanceId) ?? cached;
   if (row?.kind === "subagent" || row?.kind === "transient" || row?.workflow_run_id) return;
   if (row?.name?.trim()) return;
   const assigned = assignSessionNameInProcess(coordRoot, instanceId, payload, adapter);
@@ -1276,8 +1289,23 @@ function recordContextTelemetry(run: HookRun): void {
   }
 }
 
+/** Cross-machine peer messages (ADR 0222) ride the presence fetch: import
+ * whatever mail refs are already local. Reads local refs only, at most once
+ * per import interval; never blocks on the network. */
+async function receiveRemoteMail(coordRoot: string): Promise<void> {
+  const { peerInbox } = await import("../inbox/peer-messages.ts");
+  importMail(coordRoot, peerInbox(coordRoot), { throttle: true });
+}
+
 async function handleSessionStarted(run: HookRun): Promise<void> {
   const { coordRoot, adapter, payload, owner, sessionId, data } = run;
+  // Import mail from refs fetched earlier, so a message sent from another
+  // machine while this task was away is in the inbox this context renders.
+  try {
+    await receiveRemoteMail(coordRoot);
+  } catch (err) {
+    logError(coordRoot, err, { phase: "session-start-mail" });
+  }
   // A configured backup runs out of process and is freshness-gated per host.
   // Startup never waits for restic or a remote provider; the child owns no
   // hook stdio, so the harness is not held open until it finishes. A failed
@@ -1402,6 +1430,7 @@ async function handleTurnStarted(run: HookRun): Promise<void> {
   // interval; the systemMessage below reads whatever is locally known).
   try {
     fetchPresence(coordRoot);
+    await receiveRemoteMail(coordRoot);
   } catch (err) {
     logError(coordRoot, err, { phase: "user-prompt-submit-presence" });
   }
@@ -1472,11 +1501,24 @@ async function handleStop(run: HookRun): Promise<number | undefined> {
   // its daemon intentionally exits when a machine has no live sessions.
   try {
     publishPresence(coordRoot);
+    publishMail(coordRoot);
     ensureRelayDaemon(coordRoot);
   } catch (err) {
     logError(coordRoot, err, { phase: "stop-presence" });
   }
 
+  // Claude Code may move a running foreground command (often the agent's own
+  // commit and push) into the background to deliver a user message. Until it
+  // reports back, finalization cannot pass, so the verdict defers the status
+  // demands instead of bouncing the agent in a loop.
+  const pendingBackgroundHandoffs =
+    adapter === "claude-code"
+      ? scanPendingBackgroundHandoffs(
+          payload?.transcript_path ??
+            behavior.discoverTranscript?.(payload?.session_id ?? sessionId),
+        )
+      : [];
+
   // Stop verdict (V3 ritual + task/status gate). Direct in-process call: the
   // rule lives in Harnery. agent-hook already emitted this turn.completed
   // with privacy-safe ritual observations, so the evidence is in the stream.
@@ -1490,7 +1532,15 @@ async function handleStop(run: HookRun): Promise<number | undefined> {
     session_name_observation_unavailable: typeof data.session_name_unavailable_reason === "string",
     bypass: coordEnv("AGENT_COORD_BYPASS_STOP") === "1",
     workflow_child: coordEnv("WORKFLOW_CHILD") === "1",
+    pending_background_handoff: pendingBackgroundHandoffs.length > 0,
   });
+  if (verdict.rule === "stop-hook.background_handoff_deferred") {
+    appendDebug(coordRoot, {
+      ...debugBase,
+      effect: "stop-deferred-background-handoff",
+      background_task_ids: pendingBackgroundHandoffs,
+    });
+  }
   if (!verdict.allow) {
     // Backstop for sessions whose evidence can never land (e.g. a headless
     // child whose status command resolves to a different owner): after
@@ -1524,6 +1574,12 @@ async function handleStop(run: HookRun): Promise<number | undefined> {
   // until the adapter has committed turn.completed above. Reconcile only
   // when such a request exists; any later real work cancels it in the
   // finalizer instead of being terminated underneath the agent.
+  // A deferred stop proves nothing about finalization; an explicit end must
+  // wait for the turn that reports the background task's result.
+  if (verdict.rule === "stop-hook.background_handoff_deferred") {
+    if (behavior.runtimeContextRetry) scheduleRuntimeContextRetry(coordRoot, adapter, sessionId);
+    return undefined;
+  }
   try {
     const { hasPendingExplicitSessionEndV3, reconcileSessionFinalizationV3 } = await import(
       "../agents/session-finalizer-v3.ts"
@@ -1609,6 +1665,17 @@ async function handleToolRequested(run: HookRun): Promise<number | undefined> {
     return 0;
   }
 
+  const commitTreeReason = shellCommitTreeReason(
+    payload?.tool_name,
+    payload?.tool_input,
+    resolveBinName(coordRoot),
+  );
+  if (commitTreeReason) {
+    const { emitDeny } = await import("./adapter/output.ts");
+    emitDeny(adapter, commitTreeReason);
+    return 0;
+  }
+
   // G-guard for ALL adapters. Claude Code previously ran this via a
   // pre-tool-use bash adapter (which called `agent-coord verdict --rule=claim`);
   // that adapter is now deleted, so agent-hook owns the deny for every adapter.
@@ -1624,9 +1691,41 @@ async function handleToolRequested(run: HookRun): Promise<number | undefined> {
     logError(coordRoot, err, { phase: "pre-tool-use-guard" });
   }
   if (!guardAllowed) return 0;
+
+  // Heavy shell checks queue for a machine-wide admission slot when the
+  // project configures one. Fails open: any error runs the command as written.
+  try {
+    if (await emitAdmissionRewrite(coordRoot, adapter, payload)) return 0;
+  } catch (err) {
+    logError(coordRoot, err, { phase: "pre-tool-use-admission" });
+  }
   return undefined;
 }
 
+async function emitAdmissionRewrite(
+  coordRoot: string,
+  adapter: Adapter,
+  payload: HookRun["payload"],
+): Promise<boolean> {
+  const resource = readAdmissionConfig(coordRoot)?.guard?.resource;
+  if (!resource) return false;
+  const { admissionHookOutput } = await import("./shell-admission.ts");
+  const output = admissionHookOutput({
+    adapter,
+    resource,
+    bin: resolveBinName(coordRoot),
+    projectRoot: coordRoot,
+    toolName: payload?.tool_name,
+    toolInput: payload?.tool_input,
+    cwd: payload?.cwd,
+    skip: coordEnv("ADMISSION_SKIP") === "1" || Boolean(coordEnv("ADMISSION_HELD")),
+    platform: process.platform,
+  });
+  if (!output) return false;
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+  return true;
+}
+
 async function handlePostToolUse(run: HookRun): Promise<void> {
   const { coordRoot, adapter, eventName, payload, owner } = run;
   // Inject the full instruction only at the successful tool boundary that
@@ -1646,9 +1745,16 @@ async function handlePostToolUse(run: HookRun): Promise<void> {
   // retry response already carries the full instruction and an end-turn
   // status is the wrong place to ask.
   try {
-    const row = readLiveCoordinationRow(coordRoot, owner.instance_id);
     // A workflow child has no user-visible title to set.
-    const name = coordEnv("WORKFLOW_CHILD") === "1" ? undefined : sessionNameDisplayPending(row);
+    if (coordEnv("WORKFLOW_CHILD") === "1") return;
+    // The live row copies every name-display field from a current heartbeat
+    // cache and leaves them unset otherwise, so a raw cache with nothing
+    // pending proves the row has nothing pending either. That skips a full
+    // ledger read on almost every tool call; only a pending title pays for
+    // the authoritative check below.
+    if (!sessionNameDisplayPending(readHeartbeat(coordRoot, owner.instance_id))) return;
+    const row = readLiveCoordinationRow(coordRoot, owner.instance_id);
+    const name = sessionNameDisplayPending(row);
     if (name && toolResponseMintedSessionName(payload?.tool_response, name)) {
       // Record the title before asking for it. The suggestion can still
       // change afterwards (an assigned-name rewrite, a lifecycle re-mint, a

package/src/core/hooks/resolve/owner.ts

@@ -144,29 +144,6 @@ function readPpid(pid: number): number | null {
   return null;
 }
 
-/**
- * Find the parent owner for a subagent invocation. The per-shell marker at
- * `.harnery/shells/<pid>` is set by `sub-agent-start` and removed by
- * `sub-agent-stop`.
- *
- * Phase 2 stub: the marker file isn't written yet, so we return null in most
- * cases. Phase 2 callers can pass through.
- */
-export function readShellMarker(coordRoot: string, pid: number): string | null {
-  const path = join(coordRoot, ".harnery", "shells", String(pid));
-  if (!existsSync(path)) return null;
-  try {
-    return readFileSync(path, "utf8").trim() || null;
-  } catch {
-    return null;
-  }
-}
-
-/** Read the V3-projected `agent_id` for an owner if it exists. */
-export function readAgentIdForOwner(coordRoot: string, instanceId: string): string | null {
-  return readLiveCoordinationRow(coordRoot, instanceId)?.agent_id ?? null;
-}
-
 /** Diagnostic: list of pid-map entries (for debugging). */
 export function listPidmap(coordRoot: string): Array<{ pid: number; owner: string }> {
   const dir = join(coordRoot, ".harnery", "pid-map");

package/src/core/hooks/resolve/transcript.ts

@@ -94,6 +94,67 @@ export function scanAssistantStatusBoxPresent(
   );
 }
 
+/** A handoff older than this no longer defers Stop, so a lost notification cannot disable the ritual. */
+export const BACKGROUND_HANDOFF_MAX_AGE_MS = 30 * 60 * 1000;
+
+/**
+ * Claude Code interleaves request-capture rows of several hundred KB each, so
+ * the 256KB status-box window can lose a handoff written a minute earlier.
+ */
+const BACKGROUND_HANDOFF_TAIL_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Claude Code background tasks it moved off the foreground on its own (to
+ * deliver a mid-command user message) that have not yet posted a
+ * `<task-notification>`. Only the structured `toolUseResult` fields written by
+ * Claude Code open a handoff; the agent cannot forge them through tool output.
+ * Any later notification text naming the task closes it, so a spoofed
+ * notification can only make Stop stricter. A command the agent chose to
+ * background (`run_in_background`) or a Monitor opens nothing.
+ */
+export function scanPendingBackgroundHandoffs(
+  transcriptPath: string | undefined,
+  nowMs: number = Date.now(),
+): string[] {
+  const readablePath = resolveTranscriptPath(transcriptPath);
+  if (!readablePath) return [];
+  let size: number;
+  try {
+    size = statSync(readablePath).size;
+  } catch {
+    return [];
+  }
+  const text = readRange(readablePath, Math.max(0, size - BACKGROUND_HANDOFF_TAIL_BYTES), size);
+  if (!text) return [];
+  const opened = new Map<string, number>();
+  for (const line of text.split("\n")) {
+    // Request-capture rows echo the same text; the row-type check below keeps
+    // only Claude Code's own top-level tool-result rows.
+    if (line.includes("backgroundedToDeliverMessage")) {
+      const row = parseTranscriptRow(line);
+      const result = row?.toolUseResult as
+        | { backgroundTaskId?: unknown; backgroundedToDeliverMessage?: unknown }
+        | undefined;
+      if (
+        row?.type === "user" &&
+        result?.backgroundedToDeliverMessage === true &&
+        typeof result.backgroundTaskId === "string" &&
+        result.backgroundTaskId
+      ) {
+        opened.set(result.backgroundTaskId, Date.parse(String(row.timestamp)));
+      }
+    }
+    if (line.includes("task-notification")) {
+      for (const match of line.matchAll(/<task-id>([^<]+)<\/task-id>/g)) {
+        opened.delete(match[1]!);
+      }
+    }
+  }
+  return [...opened]
+    .filter(([, at]) => Number.isFinite(at) && nowMs - at <= BACKGROUND_HANDOFF_MAX_AGE_MS)
+    .map(([id]) => id);
+}
+
 /** Most recent user-visible assistant text across Claude Code and Codex JSONL. */
 export function scanLatestAssistantText(transcriptPath: string | undefined): string | undefined {
   const readablePath = resolveTranscriptPath(transcriptPath);