harnery 0.36.0 → 0.37.0

package/src/core/diagnostics/sanitize.ts

@@ -0,0 +1,97 @@
+const SENSITIVE_KEY =
+  /(?:authorization|cookie|credential|password|passwd|private[_-]?key|secret|session[_-]?token|access[_-]?token|refresh[_-]?token|api[_-]?key)/i;
+const OMITTED_CONTENT_KEY =
+  /(?:^|[_-])(?:environment|env|prompt|prompts|tool[_-]?payload|tool[_-]?result|transcript|transcripts)(?:$|[_-])/i;
+const HOME_PATH = /(?:[A-Za-z]:\\Users\\[^\\\s]+|\/home\/[^/\s]+|\/Users\/[^/\s]+)/g;
+const BEARER_VALUE = /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi;
+const URL_CREDENTIALS = /([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi;
+const PRIVATE_KEY = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
+const TOKENISH_VALUE = /\b(?:sk|pk|ghp|github_pat|xox[baprs])[-_][A-Za-z0-9_-]{16,}\b/g;
+const AWS_ACCESS_KEY = /\bAKIA[A-Z0-9]{16,}\b/g;
+const SENSITIVE_QUERY = /([?&](?:access_token|api_key|key|password|secret|token)=)[^&#\s]+/gi;
+const SENSITIVE_ENV = /(\b[A-Z0-9_]*(?:API_KEY|PASSWORD|SECRET|TOKEN)=)[^\s]+/g;
+const SENSITIVE_ARGUMENT = /(\B--?(?:access-token|api-key|password|secret|token)\s+)[^\s]+/gi;
+
+export interface SanitizationStats {
+  sanitized_value_count: number;
+  omitted_value_count: number;
+}
+
+export function sanitizeDiagnosticValue(value: unknown): {
+  value: unknown;
+  stats: SanitizationStats;
+} {
+  const stats: SanitizationStats = { sanitized_value_count: 0, omitted_value_count: 0 };
+  return { value: sanitize(value, stats, 0), stats };
+}
+
+function sanitize(value: unknown, stats: SanitizationStats, depth: number): unknown {
+  if (depth > 24) {
+    stats.omitted_value_count += 1;
+    return "[OMITTED:depth-limit]";
+  }
+  if (value === null || typeof value === "boolean" || typeof value === "number") return value;
+  if (typeof value === "string") return sanitizeString(value, stats);
+  if (Array.isArray(value)) {
+    const sliced = value.slice(0, 5_000);
+    const kept = sliced.map((item, index) => {
+      if (
+        typeof sliced[index - 1] === "string" &&
+        /^(?:--?)(?:access-token|api-key|password|secret|token)$/i.test(sliced[index - 1] as string)
+      ) {
+        stats.sanitized_value_count += 1;
+        return "[REDACTED:argument]";
+      }
+      return sanitize(item, stats, depth + 1);
+    });
+    if (kept.length !== value.length) stats.omitted_value_count += value.length - kept.length;
+    return kept;
+  }
+  if (!value || typeof value !== "object") return String(value);
+
+  const result: Record<string, unknown> = {};
+  const entries = Object.entries(value);
+  const namedSensitiveField = entries.some(
+    ([key, item]) => key === "name" && typeof item === "string" && SENSITIVE_KEY.test(item),
+  );
+  for (const [key, item] of entries) {
+    if (OMITTED_CONTENT_KEY.test(key)) {
+      result[key] = "[OMITTED:sensitive-content]";
+      stats.omitted_value_count += 1;
+      continue;
+    }
+    if (key === "value" && namedSensitiveField) {
+      result[key] = "[REDACTED:sensitive-field]";
+      stats.sanitized_value_count += 1;
+      continue;
+    }
+    if (SENSITIVE_KEY.test(key)) {
+      result[key] = "[REDACTED:sensitive-field]";
+      stats.sanitized_value_count += 1;
+      continue;
+    }
+    result[key] = sanitize(item, stats, depth + 1);
+  }
+  return result;
+}
+
+function sanitizeString(value: string, stats: SanitizationStats): string {
+  let next = value;
+  const replacements: Array<[RegExp, string | ((...args: string[]) => string)]> = [
+    [PRIVATE_KEY, "[REDACTED:private-key]"],
+    [BEARER_VALUE, "Bearer [REDACTED:token]"],
+    [TOKENISH_VALUE, "[REDACTED:token]"],
+    [AWS_ACCESS_KEY, "[REDACTED:access-key]"],
+    [SENSITIVE_QUERY, "$1[REDACTED]"],
+    [SENSITIVE_ENV, "$1[REDACTED]"],
+    [SENSITIVE_ARGUMENT, "$1[REDACTED]"],
+    [URL_CREDENTIALS, (_match, scheme: string) => `${scheme}[REDACTED]@`],
+    [HOME_PATH, "[REDACTED:home]"],
+  ];
+  for (const [pattern, replacement] of replacements) {
+    const replaced = next.replace(pattern, replacement as never);
+    if (replaced !== next) stats.sanitized_value_count += 1;
+    next = replaced;
+  }
+  return next;
+}

package/src/core/events/legacy-storage/compression.ts

@@ -0,0 +1,130 @@
+/** Verified in-place compression for sealed, non-terminal legacy V1 shards. */
+
+import { createReadStream, createWriteStream } from "node:fs";
+import { chmod, lstat, rename, rm } from "node:fs/promises";
+import { basename } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
+import { verifyLegacyV1HardFence } from "./fence.ts";
+import { inventoryLegacyV1Segments } from "./inventory.ts";
+import { streamLegacyV1Rows } from "./reader.ts";
+
+export interface LegacyV1CompressionEntry {
+  filename: string;
+  path: string;
+  bytes_before: number;
+  bytes_after: number | null;
+  action: "keep" | "would-compress" | "compressed";
+  reason: string;
+}
+
+export async function compressSealedLegacyV1Segments(
+  coordRoot: string,
+  opts: { yes?: boolean } = {},
+): Promise<LegacyV1CompressionEntry[]> {
+  const fence = await verifyLegacyV1HardFence(coordRoot);
+  const terminal = basename(fence.terminal_archive_path);
+  const inventory = await inventoryLegacyV1Segments(coordRoot);
+  const rows = inventory.map<LegacyV1CompressionEntry>((entry) => {
+    if (entry.filename === terminal) {
+      return {
+        filename: entry.filename,
+        path: entry.path,
+        bytes_before: entry.bytes,
+        bytes_after: null,
+        action: "keep",
+        reason: "terminal shard is bound by the V1 hard-fence digest",
+      };
+    }
+    if (entry.compressed) {
+      return {
+        filename: entry.filename,
+        path: entry.path,
+        bytes_before: entry.bytes,
+        bytes_after: entry.bytes,
+        action: "keep",
+        reason: "already compressed",
+      };
+    }
+    return {
+      filename: entry.filename,
+      path: entry.path,
+      bytes_before: entry.bytes,
+      bytes_after: null,
+      action: "would-compress",
+      reason: "sealed non-terminal V1 shard",
+    };
+  });
+  if (!opts.yes) return rows;
+
+  for (const row of rows) {
+    if (row.action !== "would-compress") continue;
+    const expected = inventory.find((entry) => entry.path === row.path)!;
+    const current = (await inventoryLegacyV1Segments(coordRoot)).find(
+      (entry) => entry.path === row.path,
+    );
+    if (
+      !current ||
+      current.bytes !== expected.bytes ||
+      current.digest !== expected.digest ||
+      current.compressed
+    ) {
+      throw new Error(`legacy_v1_segment_changed_before_compression:${row.filename}`);
+    }
+    const sourceStat = await lstat(row.path);
+    const destination = `${row.path}.gz`;
+    const temporary = `${row.path}.partial-${process.pid}.gz`;
+    try {
+      try {
+        await lstat(destination);
+        throw new Error(`legacy_v1_compressed_destination_exists:${row.filename}`);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
+      await pipeline(
+        createReadStream(row.path),
+        createGzip({ level: 9 }),
+        createWriteStream(temporary, { flags: "wx", mode: 0o600 }),
+      );
+      await proveRowParity(row.path, temporary);
+      const unchanged = (await inventoryLegacyV1Segments(coordRoot)).find(
+        (entry) => entry.path === row.path,
+      );
+      if (
+        !unchanged ||
+        unchanged.bytes !== expected.bytes ||
+        unchanged.digest !== expected.digest
+      ) {
+        throw new Error(`legacy_v1_segment_changed_during_compression:${row.filename}`);
+      }
+      await chmod(temporary, sourceStat.mode & 0o777);
+      await rename(temporary, destination);
+      await rm(row.path);
+      row.action = "compressed";
+      row.reason = "verified gzip replacement preserved every logical row";
+      row.bytes_after = (await lstat(destination)).size;
+      row.path = destination;
+      row.filename = basename(destination);
+    } catch (error) {
+      await rm(temporary, { force: true });
+      throw error;
+    }
+  }
+  return rows;
+}
+
+async function proveRowParity(loose: string, compressed: string): Promise<void> {
+  const left = streamLegacyV1Rows(loose)[Symbol.asyncIterator]();
+  const right = streamLegacyV1Rows(compressed)[Symbol.asyncIterator]();
+  while (true) {
+    const [looseRow, packedRow] = await Promise.all([left.next(), right.next()]);
+    if (looseRow.done || packedRow.done) {
+      if (looseRow.done !== packedRow.done)
+        throw new Error("legacy_v1_compression_row_count_mismatch");
+      return;
+    }
+    if (!looseRow.value.bytes.equals(packedRow.value.bytes)) {
+      throw new Error(`legacy_v1_compression_row_mismatch:${looseRow.value.row_number}`);
+    }
+  }
+}

package/src/core/events/legacy-storage/index.ts

@@ -1,4 +1,5 @@
 export * from "./canary.ts";
+export * from "./compression.ts";
 export * from "./fence.ts";
 export * from "./inventory.ts";
 export * from "./manifest.ts";

package/src/core/events/v3/archive-retention.ts

@@ -0,0 +1,251 @@
+/** Bounded retention for complete, closed Event Ledger V3 epochs. */
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import {
+  artifactAutoCleanIntervalHours,
+  type EventLedgerArchivePolicy,
+  eventLedgerArchivePolicy,
+} from "../../config.ts";
+
+export type EventV3ArchiveClassification =
+  | "retained"
+  | "expired"
+  | "over-budget"
+  | "protected-minimum"
+  | "unmanaged"
+  | "symlink"
+  | "unknown";
+
+export interface EventV3ArchiveEntry {
+  name: string;
+  path: string;
+  relative_path: string;
+  classification: EventV3ArchiveClassification;
+  reason: string;
+  action: "keep" | "would-delete" | "deleted";
+  bytes: number | null;
+  last_modified_at: string | null;
+}
+
+export interface EventV3ArchiveAutoCleanResult {
+  ran: boolean;
+  reason: "swept" | "disabled" | "fresh" | "no-root";
+  deleted: number;
+  bytes: number;
+}
+
+const ARCHIVE_PATTERN = /^epoch-[0-9]+(?:-[0-9]+)?$/;
+const AUTO_CLEAN_STAMP = ".harnery/event-v3-archive-auto-clean.json";
+
+export function eventV3ArchivesRoot(repoRoot: string): string {
+  return join(resolve(repoRoot), ".harnery", "ledgers", "v3-archives");
+}
+
+export function inventoryEventV3Archives(
+  repoRoot: string,
+  opts: { now?: Date; policy?: EventLedgerArchivePolicy } = {},
+): EventV3ArchiveEntry[] {
+  const root = eventV3ArchivesRoot(repoRoot);
+  if (!existsSync(root)) return [];
+  const now = opts.now ?? new Date();
+  const policy = opts.policy ?? eventLedgerArchivePolicy(repoRoot);
+  const rows = readdirSync(root)
+    .sort()
+    .map((name) => classifyArchive(repoRoot, join(root, name)));
+  const managed = rows.filter(
+    (row) => row.classification === "retained" && row.bytes !== null && row.last_modified_at,
+  );
+  const newestFirst = [...managed].sort((left, right) => right.name.localeCompare(left.name));
+  const protectedNames = new Set(newestFirst.slice(0, policy.keepMin).map((row) => row.name));
+  const cutoff = now.getTime() - policy.maxAgeDays * 24 * 60 * 60 * 1000;
+
+  for (const row of managed) {
+    if (protectedNames.has(row.name)) {
+      row.classification = "protected-minimum";
+      row.reason = `one of the newest ${policy.keepMin} complete epochs`;
+      continue;
+    }
+    if (Date.parse(row.last_modified_at!) <= cutoff) {
+      row.classification = "expired";
+      row.reason = `closed epoch is older than ${policy.maxAgeDays} days`;
+      row.action = "would-delete";
+    }
+  }
+
+  let retainedBytes = managed.reduce((sum, row) => sum + (row.bytes ?? 0), 0);
+  retainedBytes -= managed.reduce(
+    (sum, row) => sum + (row.action === "would-delete" ? (row.bytes ?? 0) : 0),
+    0,
+  );
+  const budgetCandidates = managed
+    .filter((row) => row.classification === "retained")
+    .sort((left, right) => left.name.localeCompare(right.name));
+  for (const row of budgetCandidates) {
+    if (retainedBytes <= policy.maxBytes) break;
+    row.classification = "over-budget";
+    row.reason = `closed-epoch budget is ${policy.maxBytes} bytes; oldest epochs are removed first`;
+    row.action = "would-delete";
+    retainedBytes -= row.bytes ?? 0;
+  }
+  return rows;
+}
+
+export function cleanEventV3Archives(
+  repoRoot: string,
+  opts: { yes?: boolean; now?: Date; policy?: EventLedgerArchivePolicy } = {},
+): EventV3ArchiveEntry[] {
+  const rows = inventoryEventV3Archives(repoRoot, opts);
+  if (!opts.yes) return rows;
+  return rows.map((entry) => {
+    if (entry.action !== "would-delete") return entry;
+    const current = inventoryEventV3Archives(repoRoot, opts).find((row) => row.path === entry.path);
+    if (!current) {
+      return { ...entry, classification: "unknown", reason: "entry disappeared", action: "keep" };
+    }
+    if (
+      current.action !== "would-delete" ||
+      current.bytes !== entry.bytes ||
+      current.last_modified_at !== entry.last_modified_at
+    ) {
+      return current;
+    }
+    try {
+      const stat = lstatSync(current.path);
+      if (!stat.isDirectory() || stat.isSymbolicLink() || !ARCHIVE_PATTERN.test(current.name)) {
+        return {
+          ...current,
+          classification: "unknown",
+          reason: "entry changed before deletion",
+          action: "keep",
+        };
+      }
+      rmSync(current.path, { recursive: true, force: false });
+      return { ...current, action: "deleted" };
+    } catch (error) {
+      return {
+        ...current,
+        classification: "unknown",
+        reason: `entry changed or could not be deleted: ${error instanceof Error ? error.message : String(error)}`,
+        action: "keep",
+      };
+    }
+  });
+}
+
+export function autoCleanEventV3Archives(
+  repoRoot: string,
+  opts: { now?: Date } = {},
+): EventV3ArchiveAutoCleanResult {
+  const now = opts.now ?? new Date();
+  const root = eventV3ArchivesRoot(repoRoot);
+  if (!existsSync(root)) return { ran: false, reason: "no-root", deleted: 0, bytes: 0 };
+  const policy = eventLedgerArchivePolicy(repoRoot);
+  if (!policy.autoClean) return { ran: false, reason: "disabled", deleted: 0, bytes: 0 };
+  const stampPath = join(resolve(repoRoot), AUTO_CLEAN_STAMP);
+  const intervalMs = artifactAutoCleanIntervalHours() * 60 * 60 * 1000;
+  try {
+    const stamp = JSON.parse(readFileSync(stampPath, "utf8")) as { last_run_at?: string };
+    const last = Date.parse(stamp.last_run_at ?? "");
+    if (Number.isFinite(last) && now.getTime() - last < intervalMs) {
+      return { ran: false, reason: "fresh", deleted: 0, bytes: 0 };
+    }
+  } catch {
+    // Missing or unreadable stamp: sweep now.
+  }
+  mkdirSync(join(resolve(repoRoot), ".harnery"), { recursive: true });
+  writeFileSync(stampPath, `${JSON.stringify({ last_run_at: now.toISOString() }, null, 2)}\n`);
+  const rows = cleanEventV3Archives(repoRoot, { yes: true, now, policy });
+  const deletedRows = rows.filter((row) => row.action === "deleted");
+  const result = {
+    ran: true as const,
+    reason: "swept" as const,
+    deleted: deletedRows.length,
+    bytes: deletedRows.reduce((sum, row) => sum + (row.bytes ?? 0), 0),
+  };
+  writeFileSync(
+    stampPath,
+    `${JSON.stringify({ last_run_at: now.toISOString(), ...result }, null, 2)}\n`,
+  );
+  return result;
+}
+
+function classifyArchive(repoRoot: string, path: string): EventV3ArchiveEntry {
+  const name = basename(path);
+  const base: EventV3ArchiveEntry = {
+    name,
+    path,
+    relative_path: relative(repoRoot, path),
+    classification: "retained",
+    reason: "closed epoch is inside the retention window",
+    action: "keep",
+    bytes: null,
+    last_modified_at: null,
+  };
+  try {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) {
+      return {
+        ...base,
+        classification: "symlink",
+        reason: "symlinks are never traversed or deleted",
+        bytes: stat.size,
+      };
+    }
+    if (!stat.isDirectory() || !ARCHIVE_PATTERN.test(name)) {
+      return {
+        ...base,
+        classification: "unmanaged",
+        reason: "entry is not a complete named epoch",
+      };
+    }
+    const measured = measureTree(path);
+    if (!measured) {
+      return {
+        ...base,
+        classification: "unknown",
+        reason: "one or more epoch paths are unreadable",
+      };
+    }
+    return {
+      ...base,
+      bytes: measured.bytes,
+      last_modified_at: new Date(measured.lastModifiedMs).toISOString(),
+    };
+  } catch (error) {
+    return {
+      ...base,
+      classification: "unknown",
+      reason: `cannot inspect archive: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+function measureTree(path: string): { bytes: number; lastModifiedMs: number } | null {
+  try {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink() || stat.isFile()) {
+      return { bytes: stat.size, lastModifiedMs: stat.mtimeMs };
+    }
+    if (!stat.isDirectory()) return { bytes: 0, lastModifiedMs: stat.mtimeMs };
+    let bytes = stat.size;
+    let lastModifiedMs = stat.mtimeMs;
+    for (const child of readdirSync(path)) {
+      const measured = measureTree(join(path, child));
+      if (!measured) return null;
+      bytes += measured.bytes;
+      lastModifiedMs = Math.max(lastModifiedMs, measured.lastModifiedMs);
+    }
+    return { bytes, lastModifiedMs };
+  } catch {
+    return null;
+  }
+}

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

@@ -35,6 +35,7 @@ export type BaseAdapterSignalV3 =
   | "prompt"
   | "turn_id"
   | "turn_completion"
+  | "assistant_reply_text"
   | "tool_request"
   | "tool_result"
   | "tool_failure"
@@ -66,6 +67,7 @@ const SHARED_SIGNAL_SUPPORT = {
   session_start: "native",
   prompt: "native",
   turn_completion: "native",
+  assistant_reply_text: "native",
   tool_request: "native",
   tool_result: "native",
   tool_failure: "native",

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

@@ -2,6 +2,15 @@ export {
   type SchemaAdvanceEligibilityV3,
   validateAdditiveSchemaAdvanceV3,
 } from "./advance.ts";
+export {
+  autoCleanEventV3Archives,
+  cleanEventV3Archives,
+  type EventV3ArchiveAutoCleanResult,
+  type EventV3ArchiveClassification,
+  type EventV3ArchiveEntry,
+  eventV3ArchivesRoot,
+  inventoryEventV3Archives,
+} from "./archive-retention.ts";
 export {
   type AuthorityMutationV3,
   type AuthorityReceiptV3,

package/src/core/events/v3/live-routing.ts

@@ -73,6 +73,7 @@ export function hookSignalV3(eventName: string): HookSignalV3 | undefined {
     case "session-start":
     case "session-end":
     case "user-prompt-submit":
+    case "after-agent-response":
     case "stop":
     case "stop-failure":
     case "pre-tool-use":

package/src/core/events/v3/producers/hook-base.ts

@@ -19,6 +19,7 @@ export type HookSignalV3Base =
   | "session-start"
   | "session-end"
   | "user-prompt-submit"
+  | "after-agent-response"
   | "stop"
   | "stop-failure"
   | "pre-tool-use"
@@ -249,6 +250,11 @@ export function normalizeHookEventV3Base(
         },
       }) as EventV3Base;
     }
+    case "after-agent-response":
+      // Cursor's completed-response hook contributes a privacy-safe ritual
+      // observation to producer state. The authoritative turn.completed event
+      // remains the later Stop signal, which consumes that observation.
+      return null;
     case "stop":
     case "stop-failure":
       return buildEventV3Base("turn.completed", {
@@ -446,9 +452,15 @@ function turnRitualObservation(
 ): TurnRitualObservationV3 {
   if (adapter === "cursor") {
     const unsupported = { state: "unsupported" as const, capability: "assistant_reply_text" };
+    const observed = <T>(value: T) => ({
+      state: "observed" as const,
+      value,
+      attestation: "derived" as const,
+      confidence: "exact" as const,
+    });
     return {
-      status_box_present: unsupported,
-      status_box_present_strict: unsupported,
+      status_box_present: observed(evidence.status_box_present),
+      status_box_present_strict: observed(evidence.status_box_present_strict),
       session_name: unsupported,
     };
   }

package/src/core/events/v3/producers/intake.ts

@@ -44,6 +44,7 @@ const HOOK_SIGNALS: ReadonlySet<string> = new Set([
   "session-start",
   "session-end",
   "user-prompt-submit",
+  "after-agent-response",
   "stop",
   "stop-failure",
   "pre-tool-use",