harnery 0.35.0 → 0.37.0

package/src/core/hooks/effects/image-capture.ts

@@ -94,10 +94,13 @@ export function recordImageArtifactsV3(
   coordRoot: string,
   sourceEvent: EventV3,
   artifacts: readonly CapturedImageArtifact[],
+  expectedGenesisId?: `gex_${string}`,
 ): void {
   if (!("generation_id" in sourceEvent.scope) || !sourceEvent.attestation_id) return;
   for (const artifact of artifacts) {
-    writeEventV3(coordRoot, buildImageArtifactEventV3(sourceEvent, artifact));
+    writeEventV3(coordRoot, buildImageArtifactEventV3(sourceEvent, artifact), {
+      ...(expectedGenesisId ? { expectedGenesisId } : {}),
+    });
   }
 }
 

package/src/core/hooks/health.ts

@@ -0,0 +1,146 @@
+import type { Adapter } from "../adapter.ts";
+import { processLogger } from "../storage/logger.ts";
+
+export const HOOK_HEALTH_EVENT = "agent_hook.completed" as const;
+export const HOOK_HEALTH_RECEIPT_VERSION = 1 as const;
+export const HOOK_HEALTH_ERROR_PHASE_LIMIT = 8;
+
+export type HookHealthOutcome = "completed" | "skipped" | "degraded" | "faulted";
+
+export interface HookHealthState {
+  readonly started_at_ms: number;
+  readonly started_rss_bytes: number;
+  readonly event_name: string | null;
+  readonly adapter: Adapter | null;
+  readonly payload_bytes: number;
+  coord_root: string | null;
+  owner_id?: string;
+  skipped_reason?: string;
+  v3_state?: string;
+  error_phases: string[];
+}
+
+export interface HookHealthReceipt {
+  receipt_version: typeof HOOK_HEALTH_RECEIPT_VERSION;
+  hook_name: string;
+  adapter: Adapter | "unknown";
+  outcome: HookHealthOutcome;
+  exit_contract: "always-zero";
+  exit_code: 0;
+  duration_ms: number;
+  payload_bytes: number;
+  pid: number;
+  rss_start_bytes: number;
+  rss_end_bytes: number;
+  rss_delta_bytes: number;
+  retry_worker: boolean;
+  error_count: number;
+  error_phases: readonly string[];
+  owner_id?: string;
+  skipped_reason?: string;
+  v3_state?: string;
+}
+
+export function beginHookHealth(input: {
+  started_at_ms: number;
+  started_rss_bytes: number;
+  event_name: string | null;
+  adapter: Adapter | null;
+  payload_bytes: number;
+}): HookHealthState {
+  return {
+    ...input,
+    coord_root: null,
+    error_phases: [],
+  };
+}
+
+export function observeHookDebug(
+  state: HookHealthState | undefined,
+  entry: Readonly<Record<string, unknown>>,
+): void {
+  if (!state) return;
+  const skipped = safeToken(entry.skipped);
+  if (skipped) state.skipped_reason = skipped;
+  const v3State = safeToken(entry.event_v3_state);
+  if (v3State) state.v3_state = v3State;
+}
+
+export function observeHookError(state: HookHealthState | undefined, phase: unknown): void {
+  if (!state || state.error_phases.length >= HOOK_HEALTH_ERROR_PHASE_LIMIT) return;
+  state.error_phases.push(safeToken(phase) ?? "unknown");
+}
+
+export function finalizeHookHealth(
+  state: HookHealthState,
+  input: {
+    finished_at_ms: number;
+    finished_rss_bytes: number;
+    pid: number;
+    faulted?: boolean;
+  },
+): HookHealthReceipt {
+  const duration = Math.max(0, Math.floor(input.finished_at_ms - state.started_at_ms));
+  const rssStart = boundedInteger(state.started_rss_bytes);
+  const rssEnd = boundedInteger(input.finished_rss_bytes);
+  const hookName = safeToken(state.event_name) ?? "unknown";
+  return {
+    receipt_version: HOOK_HEALTH_RECEIPT_VERSION,
+    hook_name: hookName,
+    adapter: state.adapter ?? "unknown",
+    outcome: input.faulted
+      ? "faulted"
+      : state.error_phases.length > 0
+        ? "degraded"
+        : state.skipped_reason
+          ? "skipped"
+          : "completed",
+    exit_contract: "always-zero",
+    exit_code: 0,
+    duration_ms: duration,
+    payload_bytes: boundedInteger(state.payload_bytes),
+    pid: boundedInteger(input.pid),
+    rss_start_bytes: rssStart,
+    rss_end_bytes: rssEnd,
+    rss_delta_bytes: rssEnd - rssStart,
+    retry_worker: hookName === "runtime-context-retry",
+    error_count: state.error_phases.length,
+    error_phases: [...state.error_phases],
+    ...(state.owner_id ? { owner_id: state.owner_id } : {}),
+    ...(state.skipped_reason ? { skipped_reason: state.skipped_reason } : {}),
+    ...(state.v3_state ? { v3_state: state.v3_state } : {}),
+  };
+}
+
+export function writeHookHealthCompletion(
+  state: HookHealthState | undefined,
+  input: {
+    finished_at_ms: number;
+    finished_rss_bytes: number;
+    pid: number;
+    faulted?: boolean;
+  },
+): HookHealthReceipt | undefined {
+  if (!state?.coord_root) return undefined;
+  const receipt = finalizeHookHealth(state, input);
+  try {
+    processLogger(state.coord_root, "agent-hook").info(HOOK_HEALTH_EVENT, { ...receipt });
+  } catch {
+    // Hook health is observer-only. Logging can never change adapter behavior.
+  }
+  return receipt;
+}
+
+function safeToken(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value
+    .trim()
+    .slice(0, 128)
+    .replace(/[^a-zA-Z0-9._:/+-]+/g, "-");
+  return /^[a-zA-Z0-9]/.test(normalized) ? normalized : undefined;
+}
+
+function boundedInteger(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(Number.MAX_SAFE_INTEGER, Math.floor(value)));
+}

package/src/core/hooks/remediation-cap.ts

@@ -36,14 +36,20 @@ function counterPath(sessionId: string): string {
  *
  * Call only when the Stop verdict blocked. `continuation` is the adapter's
  * "this stop follows a stop-hook block" flag; false starts a fresh cycle.
- * Returns true when this cycle has already been blocked `cap` times, meaning
- * the caller should allow the stop instead of blocking again.
+ * Returns the retained block count and whether this cycle has already been
+ * blocked `cap` times, meaning the caller should allow the stop instead of
+ * blocking again.
  */
-export function remediationCapExceeded(
+export interface RemediationBlockRecord {
+  count: number;
+  exceeded: boolean;
+}
+
+export function recordRemediationBlock(
   sessionId: string,
   continuation: boolean,
   cap = DEFAULT_STOP_REMEDIATION_CAP,
-): boolean {
+): RemediationBlockRecord {
   const path = counterPath(sessionId);
   let count = 1;
   if (continuation) {
@@ -62,9 +68,9 @@ export function remediationCapExceeded(
     writeFileSync(path, String(count), "utf8");
   } catch {
     // Counter IO must never turn into a block or a crash; fail open (no cap).
-    return false;
+    return { count, exceeded: false };
   }
-  return count > cap;
+  return { count, exceeded: count > cap };
 }
 
 /** Clear the cycle counter after an allowed stop. */

package/src/core/hooks/resolve/coord-root.ts

@@ -1,14 +1,16 @@
-import { resolveCoordRoot } from "../../agents/coord-client.ts";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 
 /**
- * The hooks-side name for THE coordination-root resolution.
+ * Resolve the coordination root from path evidence only.
  *
- * Delegates to `resolveCoordRoot()` so the hooks and the CLI cannot resolve
- * different roots. They used to: this walked up from `CLAUDE_PROJECT_DIR` or
- * cwd while the CLI's `monorepoRoot()` asked git for the superproject first, so
- * with a shell inside a submodule that carries its own `.harnery/`, the CLI's
- * `coord.status_observed` landed in a stream this side never read and rule 1/3
- * blocked every turn.
+ * This path-only resolver deliberately does not inspect live producer state.
+ * Code that reads or writes coordination authority must use
+ * `resolveCoordRoot()` from `agents/coord-client.ts`, which disambiguates
+ * nested coordination roots through the registered session. Keeping the two
+ * responsibilities separate lets configuration and other path-only consumers
+ * avoid loading the event recorder and its contract graph.
  *
  * Resolution precedence (see `resolveCoordRoot` for the full rationale):
  *   1. HARNERY_COORD_ROOT_OVERRIDE — explicit pin (tests, git hooks).
@@ -17,9 +19,87 @@ import { resolveCoordRoot } from "../../agents/coord-client.ts";
  *      submodules that may carry a `.harnery/` of their own (or none at all,
  *      e.g. a journal dir under /tmp). The session's coordination home is the
  *      project the adapter opened, not wherever the shell happens to sit.
- *   3. The root that already holds this session's heartbeat.
- *   4. The nearest enclosing `.harnery/`, then a git-derived root.
+ *   3. The nearest enclosing `.harnery/`.
+ *   4. A git-derived root when no `.harnery/` exists yet.
  */
 export function findCoordRoot(start: string = process.cwd()): string | null {
-  return resolveCoordRoot(start);
+  const rootOverride = process.env.HARNERY_COORD_ROOT_OVERRIDE;
+  if (rootOverride) return rootOverride;
+
+  const projectDir = process.env.CLAUDE_PROJECT_DIR;
+  if (projectDir) {
+    const fromProject = nearestCoordRoot(projectDir);
+    if (fromProject) return fromProject;
+  }
+
+  const nearest = nearestCoordRoot(start);
+  if (nearest) return nearest;
+  return gitCoordRoots(start)[0] ?? gitToplevel(start);
 }
+
+/** Nearest enclosing directory carrying `.harnery/`, or null. */
+export function nearestCoordRoot(start: string): string | null {
+  return ancestorCoordRoots(start)[0] ?? null;
+}
+
+/** Every enclosing directory carrying `.harnery/`, nearest first. */
+export function ancestorCoordRoots(start: string): string[] {
+  const found: string[] = [];
+  let dir = resolve(start);
+  while (true) {
+    if (existsSync(join(dir, ".harnery"))) found.push(dir);
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return found;
+}
+
+/**
+ * Git-derived roots carrying `.harnery/`, in superproject-first order.
+ *
+ * Spawns use `start` as cwd so a call about another checkout cannot inherit
+ * this process's repository. The common-dir fallback recovers a superproject
+ * from a submodule worktree, where Git reports no direct superproject path.
+ */
+export function gitCoordRoots(start: string): string[] {
+  const roots: string[] = [];
+  const push = (value: string | null) => {
+    if (value && existsSync(join(value, ".harnery")) && !roots.includes(value)) roots.push(value);
+  };
+
+  push(gitRevParse(start, "--show-superproject-working-tree"));
+  const common = gitRevParse(start, "--git-common-dir");
+  if (common) {
+    const index = common.indexOf("/.git/modules/");
+    if (index !== -1) push(common.substring(0, index));
+  }
+  push(gitToplevel(start));
+  return roots;
+}
+
+export function gitToplevel(start: string): string | null {
+  return gitRevParse(start, "--show-toplevel");
+}
+
+function gitRevParse(start: string, flag: string): string | null {
+  const key = `${start}\0${flag}`;
+  const cached = gitRevParseCache.get(key);
+  if (cached !== undefined) return cached;
+  let value: string | null = null;
+  try {
+    // A stale adapter project directory may no longer exist. Treat spawn
+    // failure as no path evidence instead of turning discovery into an error.
+    const result = spawnSync("git", ["rev-parse", flag], {
+      cwd: start,
+      encoding: "utf8",
+    });
+    if (result.status === 0) value = result.stdout.trim() || null;
+  } catch {
+    value = null;
+  }
+  gitRevParseCache.set(key, value);
+  return value;
+}
+
+const gitRevParseCache = new Map<string, string | null>();

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

@@ -45,6 +45,10 @@ export function resolveOwner(opts: {
     };
     const childId = value("subagent_id") ?? value("agent_id");
     const sessionId = value("session_id") ?? value("conversation_id");
+    // A payload with one unambiguous session identity needs no projection
+    // lookup. Live-authority tie-breaking matters only when the adapter also
+    // supplies a child candidate that could be stale or belong to the parent.
+    if (sessionId && !childId) return { instance_id: sessionId, source: "payload" };
     const child = childId ? readLiveCoordinationRow(opts.coordRoot, childId) : null;
     const session = sessionId ? readLiveCoordinationRow(opts.coordRoot, sessionId) : null;
 

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

@@ -3,6 +3,8 @@ import { basename, dirname, join } from "node:path";
 
 import { toolResponseMintedSessionName } from "../../agents/session-name-display.ts";
 
+export const ASSISTANT_STATUS_BOX_PREFIX = "┌─ agent-";
+
 /**
  * Scan a CC-style JSONL transcript for the `┌─ agent-` status-box prefix in
  * the most-recent assistant turn. Used by `turn.completed` events to populate
@@ -76,6 +78,22 @@ export function scanAssistantTextIncludes(
   return false;
 }
 
+/**
+ * Strict status-box evidence shared by turn telemetry and the Stop-time
+ * continuation fallback. Both inputs are assistant-only surfaces: the JSONL
+ * scanner rejects tool_result rows, while lastAssistantMessage comes directly
+ * from the adapter's completed assistant response.
+ */
+export function scanAssistantStatusBoxPresent(
+  transcriptPath: string | undefined,
+  lastAssistantMessage: string | undefined,
+): boolean {
+  return (
+    scanAssistantTextIncludes(transcriptPath, ASSISTANT_STATUS_BOX_PREFIX) ||
+    lastAssistantMessage?.includes(ASSISTANT_STATUS_BOX_PREFIX) === true
+  );
+}
+
 /** Most recent user-visible assistant text across Claude Code and Codex JSONL. */
 export function scanLatestAssistantText(transcriptPath: string | undefined): string | undefined {
   const readablePath = resolveTranscriptPath(transcriptPath);

package/src/core/inbox/contract.ts

@@ -0,0 +1,81 @@
+export const HARNERY_INBOX_RECORD_SCHEMA = "harnery.inbox-record/v1" as const;
+export const HARNERY_INBOX_STATUS_SCHEMA = "harnery.inbox-status/v1" as const;
+
+export interface HarneryInboxLimits {
+  max_message_body_bytes: number;
+  max_pending_count: number;
+  max_pending_bytes: number;
+  max_history_bytes: number;
+  max_history_records: number;
+  warning_pressure_ratio: number;
+  max_surface_count: number;
+  max_surface_bytes: number;
+  max_surface_tokens: number;
+  surfaced_grace_ms: number;
+  terminal_grace_ms: number;
+}
+
+export interface HarneryInboxMessageRecordV1 {
+  schema: typeof HARNERY_INBOX_RECORD_SCHEMA;
+  kind: "message";
+  message_id: string;
+  sender_instance_id: string;
+  sender_display_name: string;
+  recipient_instance_id: string;
+  recipient_display_name: string;
+  created_at: string;
+  body: string;
+  body_bytes: number;
+}
+
+export interface HarneryInboxSurfacedRecordV1 {
+  schema: typeof HARNERY_INBOX_RECORD_SCHEMA;
+  kind: "surfaced";
+  message_id: string;
+  surfaced_at: string;
+}
+
+export type HarneryInboxRecordV1 = HarneryInboxMessageRecordV1 | HarneryInboxSurfacedRecordV1;
+
+export interface HarneryInboxStatusV1 {
+  schema: typeof HARNERY_INBOX_STATUS_SCHEMA;
+  recipient_instance_id: string;
+  pending_count: number;
+  pending_bytes: number;
+  total_history_bytes: number;
+  oldest_pending_at?: string;
+  pressure: "normal" | "warning" | "exhausted";
+  last_surface_at?: string;
+  last_compaction_at?: string;
+}
+
+export type HarneryInboxCapacityReason =
+  | "message_body_limit"
+  | "pending_count_limit"
+  | "pending_bytes_limit"
+  | "history_bytes_limit";
+
+export class HarneryInboxCapacityError extends Error {
+  constructor(
+    readonly reason_code: HarneryInboxCapacityReason,
+    readonly current: number,
+    readonly limit: number,
+  ) {
+    super(
+      `inbox capacity ${reason_code}: ${current}/${limit}; use a managed artifact for larger payloads`,
+    );
+  }
+}
+
+export interface HarneryInboxSurfaceBudget {
+  max_count: number;
+  max_bytes: number;
+  max_tokens: number;
+}
+
+export interface HarneryInboxSurfaceResult {
+  emitted: readonly HarneryInboxMessageRecordV1[];
+  remaining_pending_count: number;
+  remaining_pending_bytes: number;
+  repeated_after_crash_possible: true;
+}

package/src/core/inbox/index.ts

@@ -0,0 +1,4 @@
+export * from "./contract.ts";
+export * from "./lifecycle.ts";
+export * from "./service.ts";
+export * from "./watcher.ts";

package/src/core/inbox/lifecycle.ts

@@ -0,0 +1,104 @@
+import type { HarneryInboxLimits, HarneryInboxRecordV1 } from "./contract.ts";
+import { project } from "./service.ts";
+
+export const HARNERY_INBOX_COMPACTION_PLAN_SCHEMA = "harnery.inbox-compaction-plan/v1" as const;
+
+export type HarneryRecipientLifecycle = "active" | "resumable" | "terminal";
+
+export interface HarneryInboxCompactionPlan {
+  schema: typeof HARNERY_INBOX_COMPACTION_PLAN_SCHEMA;
+  recipient_instance_id: string;
+  action: "none" | "compact-surfaced" | "prune-terminal";
+  reason_code:
+    | "pending_protected"
+    | "active_recipient"
+    | "surfaced_grace"
+    | "terminal_grace"
+    | "eligible";
+  remove_record_count: number;
+  retained_record_count: number;
+  protected_pending_count: number;
+  dry_run: true;
+}
+
+export function planInboxCompaction(input: {
+  recipient_instance_id: string;
+  records: readonly HarneryInboxRecordV1[];
+  lifecycle: HarneryRecipientLifecycle;
+  terminal_at?: string;
+  now: Date;
+  limits: HarneryInboxLimits;
+}): HarneryInboxCompactionPlan {
+  const projection = project(input.records);
+  const surfacedAt = new Map<string, number>();
+  for (const record of input.records) {
+    if (record.kind === "surfaced")
+      surfacedAt.set(record.message_id, Date.parse(record.surfaced_at));
+  }
+  const compactableIds = new Set(
+    [...surfacedAt]
+      .filter(([, timestamp]) => input.now.getTime() - timestamp >= input.limits.surfaced_grace_ms)
+      .map(([id]) => id),
+  );
+  const compactableRecords = input.records.filter((record) =>
+    compactableIds.has(record.message_id),
+  ).length;
+  if (input.lifecycle === "terminal") {
+    if (projection.pending.length > 0) {
+      return plan(
+        input,
+        "none",
+        "pending_protected",
+        0,
+        input.records.length,
+        projection.pending.length,
+      );
+    }
+    const terminalAt = input.terminal_at ? Date.parse(input.terminal_at) : Number.NaN;
+    if (
+      !Number.isFinite(terminalAt) ||
+      input.now.getTime() - terminalAt < input.limits.terminal_grace_ms
+    ) {
+      return plan(input, "none", "terminal_grace", 0, input.records.length, 0);
+    }
+    return plan(input, "prune-terminal", "eligible", input.records.length, 0, 0);
+  }
+  if (compactableRecords === 0) {
+    return plan(
+      input,
+      "none",
+      surfacedAt.size > 0 ? "surfaced_grace" : "active_recipient",
+      0,
+      input.records.length,
+      projection.pending.length,
+    );
+  }
+  return plan(
+    input,
+    "compact-surfaced",
+    "eligible",
+    compactableRecords,
+    input.records.length - compactableRecords,
+    projection.pending.length,
+  );
+}
+
+function plan(
+  input: { recipient_instance_id: string },
+  action: HarneryInboxCompactionPlan["action"],
+  reason_code: HarneryInboxCompactionPlan["reason_code"],
+  remove_record_count: number,
+  retained_record_count: number,
+  protected_pending_count: number,
+): HarneryInboxCompactionPlan {
+  return {
+    schema: HARNERY_INBOX_COMPACTION_PLAN_SCHEMA,
+    recipient_instance_id: input.recipient_instance_id,
+    action,
+    reason_code,
+    remove_record_count,
+    retained_record_count,
+    protected_pending_count,
+    dry_run: true,
+  };
+}