harnery 0.36.0 → 0.38.0

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/resolve/transcript.ts

@@ -167,9 +167,16 @@ export function inspectSessionNameDisplayImmediately(
       awaitingReply = false;
     }
   }
-  return sawMintResult && awaitingReply
-    ? { state: "unavailable", reason: "transcript_not_ready" }
-    : { state: "absent" };
+  // Some adapter transcripts persist assistant messages and tool requests but
+  // omit tool-result rows entirely. A readable file with no mint result cannot
+  // establish the ordered verification boundary, so it is unavailable evidence
+  // rather than proof that the agent displayed the title incorrectly. Only a
+  // transcript that contains the mint followed by a non-matching assistant
+  // reply can safely deny the next tool.
+  if (!sawMintResult || awaitingReply) {
+    return { state: "unavailable", reason: "transcript_not_ready" };
+  }
+  return { state: "absent" };
 }
 
 /**

package/src/core/hooks/session-name-presence.ts

@@ -22,6 +22,7 @@
  * Never throws: coordination telemetry must not take down a hook.
  */
 
+import { sessionNameDisplayAcceptedNames } from "../agents/session-name-display.ts";
 import { stampSessionNameSeen } from "../agents/state/heartbeat-writer.ts";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
 
@@ -42,7 +43,11 @@ export function sessionNamePresence(
     if (row?.session_name_seen_for === name) {
       return { session_name_present: true, session_name_present_for: name };
     }
-    const present = scanAssistantText(name);
+    // A display of the title Harnery last asked for counts here too, so Stop
+    // and the PreToolUse gate cannot disagree about the same reply.
+    const present = sessionNameDisplayAcceptedNames(row).some((candidate) =>
+      scanAssistantText(candidate),
+    );
     if (present) stampSessionNameSeen(coordRoot, instanceId, name);
     return { session_name_present: present, session_name_present_for: name };
   } catch {

package/src/core/qa-artifacts.ts

@@ -0,0 +1,126 @@
+/**
+ * Managed output workspaces for page-QA commands.
+ *
+ * An implicit qa-run/qa-record output is working evidence, not project source.
+ * Keep it in the bounded artifact store. Callers that pass --out-dir retain
+ * full control of that explicit destination.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { HarneryProgramContext } from "../commander.ts";
+import { monorepoRoot } from "./agents/index.ts";
+import {
+  ARTIFACT_MANIFEST,
+  type ArtifactManifestV2,
+  artifactsRoot,
+  configuredArtifactRetentionDays,
+  createArtifact,
+  parseArtifactManifest,
+} from "./artifacts/index.ts";
+
+export type QaArtifactKind = "qa-run" | "qa-record" | "review-pack";
+
+export function resolveQaRepoRoot(context?: HarneryProgramContext): string {
+  return resolve(context?.repoRoot ?? monorepoRoot() ?? process.cwd());
+}
+
+export function createManagedQaOutParent(
+  repoRoot: string,
+  kind: QaArtifactKind,
+  opts: { retentionMinutes?: number } = {},
+): string {
+  return createArtifact(repoRoot, {
+    slug: kind,
+    purpose:
+      kind === "qa-run"
+        ? "Page QA run evidence"
+        : kind === "review-pack"
+          ? "Page review pack"
+          : "Hand-recorded page QA evidence",
+    retentionDays: configuredArtifactRetentionDays(repoRoot),
+    // A standalone review-pack workspace IS the pack, so the artifact store's
+    // own expiry follows the pack's (90 minutes by default, ruled 2026-09-02).
+    ...(opts.retentionMinutes !== undefined ? { retentionMinutes: opts.retentionMinutes } : {}),
+  }).path;
+}
+
+/**
+ * Find the newest run in a valid managed QA workspace. This keeps no-path
+ * `qa-status` useful even though every implicit invocation gets an isolated
+ * artifact workspace instead of sharing one root-level `.qa-run` directory.
+ */
+export function latestManagedQaRun(repoRoot: string): string | null {
+  const root = artifactsRoot(repoRoot);
+  if (!existsSync(root)) return null;
+
+  let workspaceNames: string[];
+  try {
+    workspaceNames = readdirSync(root).sort();
+  } catch {
+    return null;
+  }
+
+  let latest: { path: string; startedAtMs: number } | null = null;
+  for (const workspaceName of workspaceNames) {
+    const workspace = join(root, workspaceName);
+    const manifest = readQaManifest(join(workspace, ARTIFACT_MANIFEST));
+    if (!manifest) continue;
+
+    let runNames: string[];
+    try {
+      runNames = readdirSync(workspace)
+        .filter((name) => name.startsWith("run-"))
+        .sort();
+    } catch {
+      continue;
+    }
+    for (const runName of runNames) {
+      const runDir = join(workspace, runName);
+      const startedAtMs = readStartedAtMs(runDir);
+      if (startedAtMs === null) continue;
+      if (
+        latest === null ||
+        startedAtMs > latest.startedAtMs ||
+        (startedAtMs === latest.startedAtMs && runDir > latest.path)
+      ) {
+        latest = { path: runDir, startedAtMs };
+      }
+    }
+  }
+  return latest?.path ?? null;
+}
+
+function readQaManifest(path: string): ArtifactManifestV2 | null {
+  try {
+    const parsed = parseArtifactManifest(JSON.parse(readFileSync(path, "utf8")));
+    if (!parsed.ok) return null;
+    if (parsed.manifest.slug !== "qa-run" && parsed.manifest.slug !== "qa-record") return null;
+    return parsed.manifest;
+  } catch {
+    return null;
+  }
+}
+
+function readStartedAtMs(runDir: string): number | null {
+  for (const file of ["run-status.json", "page-qa-result.json"]) {
+    try {
+      const value = JSON.parse(readFileSync(join(runDir, file), "utf8")) as Record<string, unknown>;
+      const run = value.run;
+      const startedAt =
+        typeof value.started_at === "string"
+          ? value.started_at
+          : run &&
+              typeof run === "object" &&
+              typeof (run as Record<string, unknown>).started_at === "string"
+            ? ((run as Record<string, unknown>).started_at as string)
+            : null;
+      if (!startedAt) continue;
+      const parsed = Date.parse(startedAt);
+      if (!Number.isNaN(parsed)) return parsed;
+    } catch {
+      // Try the other authoritative run document.
+    }
+  }
+  return null;
+}

package/src/core/resources/contract.ts

@@ -0,0 +1,105 @@
+export const RESOURCE_SNAPSHOT_SCHEMA_VERSION = 1;
+export const RESOURCE_SERVICE_STATUS_SCHEMA_VERSION = 1;
+
+export type ResourceSupportState = "supported" | "partial" | "unsupported" | "error";
+
+export interface ResourceProcessSample {
+  pid: number;
+  ppid: number;
+  start_id: string;
+  state: string;
+  name: string;
+  command: string;
+  cpu_percent: number | null;
+  rss_bytes: number;
+  age_seconds: number;
+  owner_kind: "agent" | "service" | "unattributed";
+  owner_id: string | null;
+  owner_root_pid: number | null;
+  owner_source?: "pid-map" | "session-environment" | "service";
+}
+
+export interface ResourceProcessGroup {
+  kind: ResourceProcessSample["owner_kind"];
+  id: string;
+  process_count: number;
+  cpu_percent: number | null;
+  rss_bytes: number;
+  root_pids: number[];
+}
+
+export interface ResourceMachineSample {
+  cpu_percent: number | null;
+  cpu_logical_count: number;
+  load_average: [number, number, number] | null;
+  memory_total_bytes: number | null;
+  memory_available_bytes: number | null;
+  memory_used_bytes: number | null;
+  memory_percent: number | null;
+  swap_total_bytes: number | null;
+  swap_used_bytes: number | null;
+  process_count: number;
+}
+
+export interface ResourceSnapshot {
+  schema_version: typeof RESOURCE_SNAPSHOT_SCHEMA_VERSION;
+  sampled_at: string;
+  interval_ms: number | null;
+  sample_duration_ms: number;
+  collector_cpu_ms: number;
+  platform: NodeJS.Platform;
+  namespace: "host" | "wsl" | "unknown";
+  support: {
+    state: ResourceSupportState;
+    sampler: "procfs" | "unsupported";
+    reason?: string;
+  };
+  machine: ResourceMachineSample;
+  groups: ResourceProcessGroup[];
+  processes: ResourceProcessSample[];
+  visible_process_count: number;
+  omitted_process_count: number;
+  unattributed_process_count: number;
+}
+
+export interface ResourceServiceStatusRecord {
+  schema_version: typeof RESOURCE_SERVICE_STATUS_SCHEMA_VERSION;
+  pid: number;
+  start_token?: string;
+  host: string;
+  nonce: string;
+  state: "starting" | "running" | "stopping" | "stopped" | "error";
+  started_at: string;
+  heartbeat_at: string;
+  stopped_at?: string;
+  interval_ms: number;
+  sample_count: number;
+  last_sample_at?: string;
+  last_error_code?: string;
+}
+
+export interface ResourceServiceStatus {
+  running: boolean;
+  stale: boolean;
+  record?: ResourceServiceStatusRecord;
+  status_path: string;
+  snapshot_path: string;
+}
+
+export interface ResourceSamplerState {
+  sampled_at_ms: number;
+  cpu_total_ticks: number;
+  cpu_idle_ticks: number;
+  process_ticks: Map<string, number>;
+  process_owners: Map<string, ResourceProcessOwnerProof>;
+}
+
+export interface ResourceProcessOwnerProof {
+  session_id: string;
+  instance_id: string;
+}
+
+export interface ResourceSampleResult {
+  snapshot: ResourceSnapshot;
+  state?: ResourceSamplerState;
+}

package/src/core/resources/index.ts

@@ -0,0 +1,5 @@
+export * from "./contract.ts";
+export * from "./sampler.ts";
+export * from "./service.ts";
+export * from "./service-status.ts";
+export * from "./storage.ts";