harnery 0.34.1 → 0.36.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/remediation-cap.ts

@@ -0,0 +1,83 @@
+/**
+ * Per-session cap on consecutive blocked Stop remediations.
+ *
+ * The Stop verdict re-blocks until the ledger shows the end-of-turn evidence,
+ * which assumes the agent CAN produce it. A session whose evidence can never
+ * land (e.g. a headless child whose status command resolves to a different
+ * owner) bounces forever: every retry replays the stop cycle until the budget
+ * or the operator kills it. This counter is the backstop: once a single stop
+ * cycle has been blocked `cap` times in a row, the verdict is allowed through
+ * so the session can terminate.
+ *
+ * A "stop cycle" is delimited by the adapter's continuation flag (Claude
+ * Code's `stop_hook_active`): a stop without the flag starts a fresh cycle and
+ * resets the count. Adapters that never set the flag (Cursor) reset on every
+ * stop, so the cap never engages there and behavior is unchanged.
+ *
+ * State is a tmpdir counter file keyed by session id — deliberately outside
+ * the ledger, because remediation stops do not land fresh `turn.completed`
+ * events (the turn span is already closed), so ledger evidence cannot count
+ * them.
+ */
+
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_STOP_REMEDIATION_CAP = 5;
+
+function counterPath(sessionId: string): string {
+  const key = (sessionId || "default").replace(/[^A-Za-z0-9_-]/g, "_");
+  return join(os.tmpdir(), `harnery-stop-remediation-${key}.count`);
+}
+
+/**
+ * Record one blocked stop and report whether the cap is exhausted.
+ *
+ * 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 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 interface RemediationBlockRecord {
+  count: number;
+  exceeded: boolean;
+}
+
+export function recordRemediationBlock(
+  sessionId: string,
+  continuation: boolean,
+  cap = DEFAULT_STOP_REMEDIATION_CAP,
+): RemediationBlockRecord {
+  const path = counterPath(sessionId);
+  let count = 1;
+  if (continuation) {
+    let prior = 0;
+    try {
+      prior = Number.parseInt(readFileSync(path, "utf8"), 10);
+    } catch {
+      // No counter yet (cycle started before the counter existed): treat the
+      // continuation itself as evidence of one earlier blocked stop, so an
+      // already-running loop still converges on the cap.
+      prior = 1;
+    }
+    count = Number.isFinite(prior) && prior >= 0 ? prior + 1 : 1;
+  }
+  try {
+    writeFileSync(path, String(count), "utf8");
+  } catch {
+    // Counter IO must never turn into a block or a crash; fail open (no cap).
+    return { count, exceeded: false };
+  }
+  return { count, exceeded: count > cap };
+}
+
+/** Clear the cycle counter after an allowed stop. */
+export function clearRemediationCount(sessionId: string): void {
+  try {
+    rmSync(counterPath(sessionId), { force: true });
+  } catch {
+    // best-effort
+  }
+}

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);
@@ -225,19 +243,38 @@ function textFromContent(content: unknown): string {
   return parts.join("\n");
 }
 
+/** Runtime identity read from one transcript row: the model plus the tuning
+ * values that row reported alongside it. */
+export interface TranscriptRuntimeScan {
+  model: string;
+  /** CC stamps the effective effort level on each assistant row; absent when
+   * the model has no effort dial (verified: haiku rows omit it entirely). */
+  effort?: string;
+  /** CC reports the response speed tier inside `message.usage`. */
+  speed?: string;
+}
+
 /**
- * Resolve the agent's model from a CC-style JSONL transcript by reading the
- * most-recent assistant message's `message.model`. Claude Code's SessionStart
- * payload omits `model` (Codex + Cursor supply it directly), so this is the
- * fallback that lets `session.started` / `turn.completed` populate the cache's
- * model field once the transcript has at least one assistant turn.
+ * Resolve the agent's runtime identity from a CC-style JSONL transcript by
+ * reading the most-recent assistant row. Claude Code's SessionStart payload
+ * omits `model` and `effort` (Codex + Cursor supply model directly), so this
+ * is the fallback that lets `session.started` / `turn.completed` populate
+ * model and tuning once the transcript has at least one assistant turn.
+ *
+ * Model, effort, and speed are read from the SAME row, never independently:
+ * effort varies with model inside one transcript (a mid-session model swap
+ * changes both), so pairing the newest model with a separately scanned newest
+ * effort can mislabel the session.
  *
  * Tail-reads the same 256KB window as the status-box scan and walks lines from
- * the end, returning the first real model id found. Synthetic placeholders
- * (`<synthetic>`) and empty values are skipped. Returns undefined when the
- * transcript is missing/empty (e.g. a fresh session's first SessionStart).
+ * the end, returning the first row with a real model id. Synthetic
+ * placeholders (`<synthetic>`) and empty values are skipped. Returns undefined
+ * when the transcript is missing/empty (e.g. a fresh session's first
+ * SessionStart).
  */
-export function scanTranscriptModel(transcriptPath: string | undefined): string | undefined {
+export function scanTranscriptRuntime(
+  transcriptPath: string | undefined,
+): TranscriptRuntimeScan | undefined {
   const readablePath = resolveTranscriptPath(transcriptPath);
   if (!readablePath) return undefined;
   const text = tailText(readablePath);
@@ -248,12 +285,19 @@ export function scanTranscriptModel(transcriptPath: string | undefined): string
     if (!line?.includes('"model"')) continue;
     try {
       const obj = JSON.parse(line) as {
-        message?: { model?: unknown };
+        effort?: unknown;
+        message?: { model?: unknown; usage?: { speed?: unknown } };
         model?: unknown;
       };
       const model = obj.message?.model ?? obj.model;
       if (typeof model === "string" && model.length > 0 && !model.startsWith("<")) {
-        return model;
+        const effort = obj.effort;
+        const speed = obj.message?.usage?.speed;
+        return {
+          model,
+          ...(typeof effort === "string" && effort.length > 0 ? { effort } : {}),
+          ...(typeof speed === "string" && speed.length > 0 ? { speed } : {}),
+        };
       }
     } catch {
       // Partial/truncated first line of the tail window; skip it.

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,
+  };
+}