harnery 0.45.2 → 0.46.1

package/src/core/agents/state/parent-reference.ts

@@ -0,0 +1,179 @@
+import type {
+  CoordinationGenerationViewV3,
+  CoordinationViewV3,
+} from "../../events/v3/coordination-view.ts";
+import { readCoordinationViewV3 } from "../../events/v3/coordination-view.ts";
+import { liveInstanceIdV3, nativeInstanceIdV3 } from "../../events/v3/live-route-observer.ts";
+import {
+  type NativeParentObservation,
+  type NativeParentRequest,
+  readNativeParentReference,
+} from "../../hooks/adapter/native-parent.ts";
+import { resolveName } from "./names.ts";
+import type { AgentParentReference } from "./parent-reference-contract.ts";
+
+export type { AgentParentReference } from "./parent-reference-contract.ts";
+
+export interface AgentParentSubject {
+  instance_id: string;
+  generation_id?: string;
+  v3_generation_id?: string;
+  platform?: string;
+  native_session_id?: string;
+}
+
+export interface AgentParentReferenceOptions {
+  view?: CoordinationViewV3;
+  readNativeParent?: (request: NativeParentRequest) => NativeParentObservation;
+}
+
+/** Display/recipient evidence only. Never use native evidence as a claim or lifecycle waiver. */
+export function resolveAgentParentReference(
+  coordRoot: string,
+  child: AgentParentSubject,
+  options: AgentParentReferenceOptions = {},
+): AgentParentReference {
+  try {
+    const view = options.view ?? readCoordinationViewV3(coordRoot);
+    if (!view.source_complete || !view.authority_safe) return unknown("parent_authority_unsafe");
+    if (
+      child.generation_id &&
+      child.v3_generation_id &&
+      child.generation_id !== child.v3_generation_id
+    ) {
+      return unknown("child_generation_mismatch");
+    }
+    const instance = liveInstanceIdV3(child.instance_id);
+    const generationId = child.generation_id ?? child.v3_generation_id;
+    const generations = [
+      ...Object.values(view.instances),
+      ...Object.values(view.terminal_generations),
+    ];
+    const generation = generationId
+      ? generations.find(
+          (row) => row.generation_id === generationId && row.instance_id === instance,
+        )
+      : view.instances[instance];
+    if (!generation) return unknown("child_generation_unavailable");
+    if (!safe(view, generation)) return unknown("child_authority_unsafe");
+    const canonical = generation.parent_generation_id
+      ? generations.find((row) => row.generation_id === generation.parent_generation_id)
+      : undefined;
+    if (generation.parent_generation_id && !canonical)
+      return unknown("parent_generation_unavailable");
+    if (canonical && cyclic(generations, generation)) {
+      return { state: "conflict", reason: "parent_lineage_cycle" };
+    }
+    const adapter = generation.runtime_attestation.adapter;
+    const platform = adapter.state === "observed" ? adapter.value.id : child.platform;
+    const nativeId = child.native_session_id ?? nativeInstanceIdV3(instance);
+    const native =
+      platform === "codex" && liveInstanceIdV3(nativeId) === instance
+        ? (options.readNativeParent ?? readNativeParentReference)({
+            adapter: platform,
+            native_session_id: nativeId,
+          })
+        : ({ state: "unknown", reason: "native_child_identity_unavailable" } as const);
+    if (canonical) {
+      if (
+        native.state === "none" ||
+        (native.state === "observed" &&
+          liveInstanceIdV3(native.parent_session_id) !== canonical.instance_id)
+      ) {
+        return { state: "conflict", reason: "parent_sources_disagree" };
+      }
+      return reference(coordRoot, view, canonical.instance_id, canonical, "v3-session-link");
+    }
+    if (native.state === "observed") {
+      const parentInstance = liveInstanceIdV3(native.parent_session_id);
+      if (parentInstance === instance)
+        return { state: "conflict", reason: "parent_self_reference" };
+      const parent = recipientGeneration(view, parentInstance);
+      if (parent && cyclic(generations, generation, parent)) {
+        return { state: "conflict", reason: "parent_lineage_cycle" };
+      }
+      return reference(
+        coordRoot,
+        view,
+        parentInstance,
+        parent,
+        "native-session-metadata",
+        native.source_witness,
+      );
+    }
+    return { state: native.state, reason: native.reason };
+  } catch {
+    return unknown("parent_reference_unavailable");
+  }
+}
+
+function reference(
+  root: string,
+  view: CoordinationViewV3,
+  instance: string,
+  parent: CoordinationGenerationViewV3 | undefined,
+  source: "v3-session-link" | "native-session-metadata",
+  witness?: string,
+): AgentParentReference {
+  const native = nativeInstanceIdV3(instance);
+  const name = resolveName(root, native)?.name ?? null;
+  const recipient = recipientGeneration(view, instance);
+  return {
+    state: "verified",
+    relationship: source === "v3-session-link" ? "delegated-child" : "native-child",
+    parent_instance_id: native,
+    parent_v3_instance_id: instance,
+    parent_generation_id: parent?.generation_id ?? null,
+    parent_session_id: parent?.session_id ?? null,
+    parent_name: name,
+    source,
+    ...(witness ? { source_witness: witness } : {}),
+    addressable: Boolean(
+      parent && recipient?.generation_id === parent.generation_id && safe(view, parent) && name,
+    ),
+  };
+}
+
+function recipientGeneration(view: CoordinationViewV3, instance: string) {
+  return (
+    view.instances[instance] ??
+    Object.values(view.terminal_generations)
+      .filter((row) => row.instance_id === instance)
+      .sort(
+        (a, b) =>
+          b.source_position.segment_ordinal - a.source_position.segment_ordinal ||
+          b.source_position.byte_offset - a.source_position.byte_offset,
+      )[0]
+  );
+}
+
+function safe(view: CoordinationViewV3, generation: CoordinationGenerationViewV3): boolean {
+  return !(view.diagnostics_by_generation[generation.generation_id] ?? []).some(
+    (d) => d.authority_blocking,
+  );
+}
+
+function cyclic(
+  generations: CoordinationGenerationViewV3[],
+  child: CoordinationGenerationViewV3,
+  first?: CoordinationGenerationViewV3,
+): boolean {
+  const seen = new Set([child.generation_id]);
+  let cursor = first ?? child;
+  for (let depth = 0; depth <= generations.length; depth++) {
+    if (cursor !== child) {
+      if (seen.has(cursor.generation_id) || cursor.instance_id === child.instance_id) return true;
+      seen.add(cursor.generation_id);
+    }
+    if (!cursor.parent_generation_id) return false;
+    const next = generations.find((g) => g.generation_id === cursor.parent_generation_id);
+    if (!next) return false;
+    if (seen.has(next.generation_id)) return true;
+    cursor = next;
+  }
+  return true;
+}
+
+function unknown(reason: string): AgentParentReference {
+  return { state: "unknown", reason };
+}

package/src/core/config.ts

@@ -92,6 +92,8 @@ interface HarneryConfig {
     requireGitFinalization?: boolean;
     finalizationRoots?: AgentFinalizationRoot[];
   };
+  /** Admission resource defaults and the heavy-command guard. Project config only. */
+  admission?: unknown;
   /** Host-owned agent instruction settings. */
   instructions?: {
     hostAddendumFile?: unknown;
@@ -633,6 +635,89 @@ export function ripgrepAutoInstall(coordRoot?: string | null): boolean {
   return readConfig(root).tools?.ripgrep?.autoInstall === true;
 }
 
+/** Wait before queueing while Linux memory pressure is high (PSI `full avg10`). */
+export interface AdmissionPressureConfig {
+  psi_full_avg10: number;
+  max_wait_seconds: number;
+}
+
+/** Per-resource defaults for `admission run`; command-line flags win. */
+export interface AdmissionResourceConfig {
+  capacity?: number;
+  timeout_minutes?: number;
+  defer_on_pressure?: AdmissionPressureConfig;
+}
+
+export interface AdmissionProjectConfig {
+  resources: Record<string, AdmissionResourceConfig>;
+  /** Present when the agent hook should wrap heavy shell commands in a slot. */
+  guard?: { resource: string };
+}
+
+function positiveNumber(value: unknown, max: number): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= max
+    ? value
+    : undefined;
+}
+
+/**
+ * Admission settings from `.harnery/config.jsonc`:
+ *
+ * ```jsonc
+ * "admission": {
+ *   "resources": {
+ *     "build": {
+ *       "capacity": 2,
+ *       "timeout_minutes": 30,
+ *       "defer_on_pressure": { "psi_full_avg10": 40, "max_wait_seconds": 300 }
+ *     }
+ *   },
+ *   "guard": { "resource": "build" }
+ * }
+ * ```
+ *
+ * Project config only, like other machine-shaping policy. Malformed values are
+ * dropped one by one rather than rejecting the whole block. Undefined when the
+ * project declares no admission settings.
+ */
+export function readAdmissionConfig(coordRoot?: string | null): AdmissionProjectConfig | undefined {
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return undefined;
+  const raw = readProjectConfig(root).admission;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const record = raw as { resources?: unknown; guard?: unknown };
+  const resources: Record<string, AdmissionResourceConfig> = {};
+  if (
+    record.resources &&
+    typeof record.resources === "object" &&
+    !Array.isArray(record.resources)
+  ) {
+    for (const [name, value] of Object.entries(record.resources as Record<string, unknown>)) {
+      if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+      const entry = value as Record<string, unknown>;
+      const capacity = positiveNumber(entry.capacity, 32);
+      const timeout = positiveNumber(entry.timeout_minutes, 1440);
+      const pressure = entry.defer_on_pressure as Record<string, unknown> | undefined;
+      const threshold = positiveNumber(pressure?.psi_full_avg10, 100);
+      const maxWait = positiveNumber(pressure?.max_wait_seconds, 86_400);
+      resources[name] = {
+        ...(capacity !== undefined && Number.isInteger(capacity) ? { capacity } : {}),
+        ...(timeout !== undefined && Number.isInteger(timeout) ? { timeout_minutes: timeout } : {}),
+        ...(threshold !== undefined && maxWait !== undefined
+          ? { defer_on_pressure: { psi_full_avg10: threshold, max_wait_seconds: maxWait } }
+          : {}),
+      };
+    }
+  }
+  const guard = record.guard as { resource?: unknown } | undefined;
+  return {
+    resources,
+    ...(guard && typeof guard.resource === "string" && guard.resource
+      ? { guard: { resource: guard.resource } }
+      : {}),
+  };
+}
+
 /**
  * Whether this repo pins workflow runs to subscription billing:
  * `.harnery/config.jsonc` `{ "workflow": { "subscriptionOnly": true } }`.

package/src/core/diagnostics/path-identity.ts

@@ -1,15 +1,61 @@
-import { createHash } from "node:crypto";
+import { createHmac, randomBytes } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { PERSONAL_DIR_MODE, PERSONAL_FILE_MODE } from "../storage/modes.ts";
 
 const HOME_PATH =
   /(?:[A-Za-z]:[\\/]Users[\\/](?:[^\\/\r\n\0:"<>|]+(?=[\\/])|[^\\/\s\0:]+)|\/home\/[^/\s\0:]+|\/Users\/[^/\s\0:]+)/g;
 
-/** One stable representation for private home paths in values and identity inputs. */
+const KEY_PATTERN = /^[0-9a-f]{64}$/;
+let cachedKey: Buffer | undefined;
+
+/**
+ * Per-install secret for home-path pseudonyms. An unkeyed digest would let
+ * anyone holding a bundle recover the user name by hashing guesses, so the
+ * key stays in local state and never enters a bundle. Sanitized values carry
+ * the pseudonym itself, so replay elsewhere needs no key.
+ */
+function identityKeyPath(): string {
+  const xdg = process.env.XDG_STATE_HOME;
+  const base = xdg?.trim() ? xdg : join(homedir(), ".local", "state");
+  return join(base, "harnery", "diagnostic-identity.key");
+}
+
+function readKey(path: string): Buffer | undefined {
+  try {
+    const text = readFileSync(path, "utf8").trim();
+    return KEY_PATTERN.test(text) ? Buffer.from(text, "hex") : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function identityKey(): Buffer {
+  if (cachedKey) return cachedKey;
+  const path = identityKeyPath();
+  let key = readKey(path);
+  if (!key) {
+    const fresh = randomBytes(32);
+    try {
+      mkdirSync(dirname(path), { recursive: true, mode: PERSONAL_DIR_MODE });
+      writeFileSync(path, `${fresh.toString("hex")}\n`, { flag: "wx", mode: PERSONAL_FILE_MODE });
+      chmodSync(path, PERSONAL_FILE_MODE);
+      key = fresh;
+    } catch {
+      // A concurrent writer won the race, or state is unwritable. Prefer the
+      // stored key; otherwise stay private with a process-local key.
+      key = readKey(path) ?? fresh;
+    }
+  }
+  cachedKey = key;
+  return key;
+}
+
+/** One stable, non-reversible representation for private home paths in values and identity inputs. */
 export function canonicalizeDiagnosticIdentity(value: string): string {
   return value.replace(HOME_PATH, (home) => {
-    const digest = createHash("sha256")
-      .update("harnery-diagnostic-home-v1\0")
-      .update(home)
-      .digest("hex");
+    const digest = createHmac("sha256", identityKey()).update(home).digest("hex");
     return `[REDACTED:home:${digest}]`;
   });
 }

package/src/core/events/v3/canonical.ts

@@ -104,10 +104,19 @@ export function normalizeNativeIdV3(
   return `hid_${digest}`;
 }
 
+/**
+ * NFC leaves ASCII unchanged, so ASCII strings and key sets skip normalization
+ * and the collision map. Every reader re-serializes each ledger frame to prove
+ * it is canonical, which makes this the hottest function on a cold read.
+ */
+const NON_ASCII = /[\u0080-\uffff]/;
+
 function serialize(value: unknown, ancestors: Set<object>): string {
   if (value === null) return "null";
   if (typeof value === "boolean") return value ? "true" : "false";
-  if (typeof value === "string") return JSON.stringify(value.normalize("NFC"));
+  if (typeof value === "string") {
+    return JSON.stringify(NON_ASCII.test(value) ? value.normalize("NFC") : value);
+  }
   if (typeof value === "number") {
     if (!Number.isFinite(value)) throw new Error("canonical JSON rejects non-finite numbers");
     return JSON.stringify(Object.is(value, -0) ? 0 : value);
@@ -119,29 +128,53 @@ function serialize(value: unknown, ancestors: Set<object>): string {
   ancestors.add(value);
   try {
     if (Array.isArray(value)) {
-      return `[${value.map((item) => serialize(item, ancestors)).join(",")}]`;
+      let out = "[";
+      for (let index = 0; index < value.length; index++) {
+        if (index > 0) out += ",";
+        out += serialize(value[index], ancestors);
+      }
+      return `${out}]`;
     }
     const prototype = Object.getPrototypeOf(value);
     if (prototype !== Object.prototype && prototype !== null) {
       throw new Error("canonical JSON accepts only plain objects");
     }
-    const normalized = new Map<string, unknown>();
-    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
-      const normalizedKey = key.normalize("NFC");
-      if (normalized.has(normalizedKey)) {
-        throw new Error("canonical JSON key collision after Unicode normalization");
-      }
-      normalized.set(normalizedKey, item);
+    const object = value as Record<string, unknown>;
+    const keys = Object.keys(object);
+    if (keys.some((key) => NON_ASCII.test(key))) {
+      return serializeNormalizedObject(object, ancestors);
     }
-    const keys = [...normalized.keys()].sort(compareUtf16);
-    return `{${keys
-      .map((key) => `${JSON.stringify(key)}:${serialize(normalized.get(key), ancestors)}`)
-      .join(",")}}`;
+    keys.sort(compareUtf16);
+    let out = "{";
+    for (let index = 0; index < keys.length; index++) {
+      const key = keys[index] as string;
+      if (index > 0) out += ",";
+      out += `${JSON.stringify(key)}:${serialize(object[key], ancestors)}`;
+    }
+    return `${out}}`;
   } finally {
     ancestors.delete(value);
   }
 }
 
+function serializeNormalizedObject(
+  object: Record<string, unknown>,
+  ancestors: Set<object>,
+): string {
+  const normalized = new Map<string, unknown>();
+  for (const [key, item] of Object.entries(object)) {
+    const normalizedKey = key.normalize("NFC");
+    if (normalized.has(normalizedKey)) {
+      throw new Error("canonical JSON key collision after Unicode normalization");
+    }
+    normalized.set(normalizedKey, item);
+  }
+  const keys = [...normalized.keys()].sort(compareUtf16);
+  return `{${keys
+    .map((key) => `${JSON.stringify(key)}:${serialize(normalized.get(key), ancestors)}`)
+    .join(",")}}`;
+}
+
 function compareUtf16(left: string, right: string): number {
   return left < right ? -1 : left > right ? 1 : 0;
 }

package/src/core/events/v3/index.ts

@@ -247,7 +247,9 @@ export {
   type DrainHookIntakeSpoolV3Result,
   drainHookIntakeSpoolV3,
   type HookProducerStateRecordV3,
+  type HookProducerStateScanV3,
   type HookProducerStateV3,
+  type InvalidHookProducerStateFileV3,
   listHookProducerStateRecordsV3,
   type RecordApprovedSessionEndV3Input,
   type RecordApprovedSessionEndV3Result,
@@ -256,6 +258,7 @@ export {
   readHookProducerStateV3,
   recordApprovedSessionEndV3,
   recordHookSignalV3,
+  scanHookProducerStateRecordsV3,
 } from "./producers/recorder.ts";
 export {
   type ClaimProjectionV3,