harnery 0.35.0 → 0.37.0

package/src/core/agents/state/live-coordination-writer.ts

@@ -0,0 +1,141 @@
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Adapter } from "../../adapter.ts";
+import {
+  readCoordinationViewV3,
+  requireAuthoritySafeCoordinationViewV3,
+} from "../../events/v3/coordination-view.ts";
+import { liveInstanceIdV3, resolveLiveEventLedgerRouteV3 } from "../../events/v3/live-routing.ts";
+import { type Heartbeat, readHeartbeat } from "./heartbeat-reader.ts";
+import {
+  isAdapterV3,
+  isCurrentV3HeartbeatCache,
+  observedAdapterV3,
+  projectHeartbeatV3,
+  type V3HeartbeatMaterialization,
+} from "./live-coordination-view.ts";
+import { resolveName } from "./names.ts";
+
+/**
+ * Ensure the current V3 generation has a mutation target. The resulting file
+ * is explicitly generation-bound and disposable: V3 remains the source of
+ * truth, while the cache gives the crash-safe authority outbox an atomic local
+ * state to reconcile.
+ */
+export function ensureLiveCoordinationHeartbeat(
+  coordRoot: string,
+  nativeInstanceId: string,
+  nativeSessionId: string,
+  _adapter: Adapter,
+  model?: string,
+): Heartbeat | null {
+  return materializeLiveCoordinationHeartbeat(
+    coordRoot,
+    nativeInstanceId,
+    nativeSessionId,
+    _adapter,
+    model,
+    false,
+  );
+}
+
+/** Rebuild a disposable cache from V3 even when its generation markers look current. */
+export function repairLiveCoordinationHeartbeat(
+  coordRoot: string,
+  nativeInstanceId: string,
+  nativeSessionId: string,
+  adapter: Adapter,
+  model?: string,
+): Heartbeat | null {
+  return materializeLiveCoordinationHeartbeat(
+    coordRoot,
+    nativeInstanceId,
+    nativeSessionId,
+    adapter,
+    model,
+    true,
+  );
+}
+
+function materializeLiveCoordinationHeartbeat(
+  coordRoot: string,
+  nativeInstanceId: string,
+  nativeSessionId: string,
+  _adapter: Adapter,
+  model: string | undefined,
+  force: boolean,
+): Heartbeat | null {
+  const route = resolveLiveEventLedgerRouteV3(coordRoot);
+  if (route.state === "blocked") throw new Error(`event_v3_coordination_view:${route.reason}`);
+  const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
+  const generation = view.instances[liveInstanceIdV3(nativeInstanceId)];
+  if (!generation?.authority_eligible) return null;
+  const generationAdapter = observedAdapterV3(generation);
+  if (!isAdapterV3(generationAdapter)) {
+    throw new Error("event_v3_coordination_view:adapter_not_observed");
+  }
+  const current = readHeartbeat(coordRoot, nativeInstanceId);
+  if (
+    !force &&
+    isCurrentV3HeartbeatCache(current, generation) &&
+    current.platform === generationAdapter
+  ) {
+    return current;
+  }
+
+  const resolved = resolveName(coordRoot, nativeInstanceId, nativeSessionId);
+  const projected = projectHeartbeatV3(coordRoot, generation, undefined, nativeInstanceId);
+  // A generation reopen (resume, mid-flight onboarding) discards the stale
+  // cache, but the adapter tab it names is unchanged: same native session,
+  // same agent identity. Rebuilding without the naming evidence re-mints a
+  // fresh suggested name on the next set-task, so a multi-day session
+  // accumulates titles it is asked to display over and over. Carry the
+  // naming evidence across generations; everything else re-projects from V3.
+  // Same native session id means the same adapter tab; drop the carry only
+  // when the durable identity observably changed (a reassumed name would make
+  // the old "Agent <name> - …" block wrong for the new owner).
+  const identityUnchanged = !resolved?.name || !current?.name || resolved.name === current.name;
+  const carriedNaming =
+    current && current.session_id === nativeSessionId && identityUnchanged
+      ? {
+          ...(current.suggested_session_name
+            ? { suggested_session_name: current.suggested_session_name }
+            : {}),
+          ...(current.session_name_seen_for
+            ? { session_name_seen_for: current.session_name_seen_for }
+            : {}),
+          ...(current.session_name_seen_at
+            ? { session_name_seen_at: current.session_name_seen_at }
+            : {}),
+        }
+      : {};
+  const materialized: V3HeartbeatMaterialization = {
+    ...projected,
+    ...carriedNaming,
+    schema_version: 2,
+    instance_id: nativeInstanceId,
+    session_id: nativeSessionId,
+    name: resolved?.name ?? "",
+    kind: resolved?.kind ?? projected.kind,
+    agent_id: resolved?.agent_id ?? (resolved?.kind === "subagent" ? nativeInstanceId : ""),
+    model: projected.model ?? model ?? "",
+    platform: generationAdapter,
+    v3_instance_id: generation.instance_id as `inst_${string}`,
+    v3_generation_id: generation.generation_id as `gen_${string}`,
+    v3_projection_event_id: generation.last_event_id,
+    v3_task_state: generation.task_state === "set" ? "set" : "cleared",
+  };
+  writeHeartbeatCache(coordRoot, nativeInstanceId, materialized);
+  return materialized;
+}
+
+function writeHeartbeatCache(coordRoot: string, instanceId: string, heartbeat: Heartbeat): void {
+  if (!/^[a-zA-Z0-9._-]{1,128}$/.test(instanceId)) {
+    throw new Error("instance_id is unsafe for heartbeat materialization");
+  }
+  const path = join(coordRoot, ".harnery", "active", `${instanceId}.json`);
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.tmp.${process.pid}`;
+  writeFileSync(temporary, JSON.stringify(heartbeat, null, 2), "utf8");
+  renameSync(temporary, path);
+}

package/src/core/artifacts/index.ts

@@ -23,7 +23,13 @@ import {
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
-import { artifactDefaultRetentionDays } from "../config.ts";
+import {
+  artifactAutoCleanEnabled,
+  artifactAutoCleanIntervalHours,
+  artifactDefaultRetentionDays,
+  artifactMaxBytes,
+  artifactMaxUnitBytes,
+} from "../config.ts";
 import { ARTIFACT_MANIFEST, ARTIFACT_SCHEMA_VERSION, ARTIFACTS_DIR } from "./constants.ts";
 
 export { ARTIFACT_MANIFEST, ARTIFACT_SCHEMA_VERSION, ARTIFACTS_DIR } from "./constants.ts";
@@ -48,12 +54,15 @@ export interface ArtifactManifestV1 {
   };
   released_at?: string;
   released_by?: ArtifactActor;
+  oversize_acknowledged?: boolean;
 }
 
 export type ArtifactClassification =
   | "managed-active"
   | "managed-current"
   | "managed-expired"
+  | "managed-oversize"
+  | "managed-over-budget"
   | "managed-tracked"
   | "invalid-manifest"
   | "unmanaged"
@@ -74,6 +83,7 @@ export interface ArtifactInventoryEntry {
   last_modified_at: string | null;
   expires_at: string | null;
   owner_instance_id: string | null;
+  oversize_acknowledged: boolean;
 }
 
 export interface ArtifactCreateInput {
@@ -83,6 +93,7 @@ export interface ArtifactCreateInput {
   actor?: ArtifactActor;
   now?: Date;
   id?: string;
+  big?: boolean;
 }
 
 export interface ArtifactMutationInput {
@@ -90,6 +101,15 @@ export interface ArtifactMutationInput {
   now?: Date;
 }
 
+export interface ArtifactAdoptionResult {
+  candidates: Array<{ path: string; name: string; bytes: number; kind: "file" | "directory" }>;
+  candidate_bytes: number;
+  requires_big: boolean;
+  adopted_artifact_id: string | null;
+  adopted_path: string | null;
+  adopted_directories: number;
+}
+
 interface ParsedManifest {
   ok: true;
   manifest: ArtifactManifestV1;
@@ -141,6 +161,7 @@ export function createArtifact(
     retention: {
       expires_at: addDays(now, retentionDays).toISOString(),
     },
+    ...(input.big ? { oversize_acknowledged: true } : {}),
   };
   atomicWriteManifest(path, manifest);
   return { path, manifest };
@@ -173,7 +194,7 @@ export function inventoryArtifacts(
   for (const name of names) {
     rows.push(classifyArtifactPath(repoRoot, join(root, name), now, freshnessSeconds));
   }
-  return rows;
+  return applyArtifactBudgets(repoRoot, rows);
 }
 
 export function showArtifact(
@@ -182,12 +203,8 @@ export function showArtifact(
   opts: { now?: Date; freshnessSeconds?: number } = {},
 ): { entry: ArtifactInventoryEntry; manifest: ArtifactManifestV1 } {
   const path = resolveArtifactRef(repoRoot, ref);
-  const entry = classifyArtifactPath(
-    repoRoot,
-    path,
-    opts.now ?? new Date(),
-    opts.freshnessSeconds ?? 600,
-  );
+  const entry = inventoryArtifacts(repoRoot, opts).find((row) => row.path === path);
+  if (!entry) throw new Error(`artifact "${ref}" was not found`);
   const parsed = readManifest(path);
   if (!parsed.ok) throw new Error(parsed.reason);
   return { entry, manifest: parsed.manifest };
@@ -239,6 +256,108 @@ export function releaseArtifact(
   return manifest;
 }
 
+/** Adopt untracked loose files and legacy directories without changing directory paths. */
+export function adoptUnmanagedArtifactFiles(
+  repoRoot: string,
+  input: {
+    yes?: boolean;
+    big?: boolean;
+    purpose: string;
+    retentionDays: number;
+    actor?: ArtifactActor;
+    now?: Date;
+  },
+): ArtifactAdoptionResult {
+  const now = input.now ?? new Date();
+  const candidates: ArtifactAdoptionResult["candidates"] = [];
+  for (const row of inventoryArtifacts(repoRoot, { now })) {
+    if (row.classification !== "unmanaged") continue;
+    try {
+      const stat = lstatSync(row.path);
+      if (stat.isSymbolicLink() || containsTrackedPath(repoRoot, row.path)) continue;
+      if (stat.isFile()) {
+        candidates.push({ path: row.path, name: row.name, bytes: stat.size, kind: "file" });
+        continue;
+      }
+      if (stat.isDirectory() && !existsSync(join(row.path, ARTIFACT_MANIFEST))) {
+        const bytes = safeTreeSize(row.path);
+        if (bytes !== null && normalizeSlug(row.name)) {
+          candidates.push({ path: row.path, name: row.name, bytes, kind: "directory" });
+        }
+      }
+    } catch {
+      // A racing or unreadable entry stays unmanaged.
+    }
+  }
+  const candidateBytes = candidates.reduce((sum, row) => sum + row.bytes, 0);
+  const fileBytes = candidates.reduce((sum, row) => sum + (row.kind === "file" ? row.bytes : 0), 0);
+  const maxUnitBytes = artifactMaxUnitBytes(repoRoot);
+  const requiresBig =
+    fileBytes > maxUnitBytes ||
+    candidates.some((row) => row.kind === "directory" && row.bytes > maxUnitBytes);
+  const preview: ArtifactAdoptionResult = {
+    candidates,
+    candidate_bytes: candidateBytes,
+    requires_big: requiresBig,
+    adopted_artifact_id: null,
+    adopted_path: null,
+    adopted_directories: 0,
+  };
+  if (!input.yes || candidates.length === 0) return preview;
+  if (requiresBig && !input.big) {
+    throw new Error("unmanaged adoption exceeds the per-bundle ceiling; repeat with --big");
+  }
+
+  // Revalidate every exact source before creating a destination. A changed,
+  // tracked, linked, or non-regular entry aborts the whole adoption.
+  for (const candidate of candidates) {
+    const stat = lstatSync(candidate.path);
+    const bytes = stat.isDirectory() ? safeTreeSize(candidate.path) : stat.size;
+    if (
+      stat.isSymbolicLink() ||
+      bytes !== candidate.bytes ||
+      containsTrackedPath(repoRoot, candidate.path)
+    ) {
+      throw new Error(`unmanaged entry changed before adoption: ${candidate.name}`);
+    }
+    if (candidate.kind === "file" ? !stat.isFile() : !stat.isDirectory()) {
+      throw new Error(`unmanaged entry changed before adoption: ${candidate.name}`);
+    }
+  }
+  const files = candidates.filter((candidate) => candidate.kind === "file");
+  const created = files.length
+    ? createArtifact(repoRoot, {
+        slug: "adopted-unmanaged",
+        purpose: input.purpose,
+        retentionDays: input.retentionDays,
+        actor: input.actor,
+        now,
+        big: input.big,
+      })
+    : null;
+  for (const candidate of files) renameSync(candidate.path, join(created!.path, candidate.name));
+  const retentionDays = positiveDays(input.retentionDays);
+  const directories = candidates.filter((candidate) => candidate.kind === "directory");
+  for (const candidate of directories) {
+    atomicWriteManifest(candidate.path, {
+      schema_version: ARTIFACT_SCHEMA_VERSION,
+      artifact_id: randomUUID(),
+      slug: normalizeSlug(candidate.name),
+      purpose: `${input.purpose}: ${candidate.name}`,
+      created_at: now.toISOString(),
+      created_by: input.actor,
+      retention: { expires_at: addDays(now, retentionDays).toISOString() },
+      ...(input.big ? { oversize_acknowledged: true } : {}),
+    });
+  }
+  return {
+    ...preview,
+    adopted_artifact_id: created?.manifest.artifact_id ?? null,
+    adopted_path: created?.path ?? null,
+    adopted_directories: directories.length,
+  };
+}
+
 export function cleanArtifacts(
   repoRoot: string,
   opts: { yes?: boolean; now?: Date; freshnessSeconds?: number } = {},
@@ -249,11 +368,24 @@ export function cleanArtifacts(
   if (!opts.yes) return rows;
 
   return rows.map((entry) => {
-    if (entry.classification !== "managed-expired") return entry;
+    if (entry.action !== "would-delete") return entry;
     // Reclassify immediately before removal. A renewal, release-state change,
     // heartbeat, symlink swap, or tracked file added since inventory must win.
-    const current = classifyArtifactPath(repoRoot, entry.path, now, freshnessSeconds);
-    if (current.classification !== "managed-expired") return current;
+    const current = inventoryArtifacts(repoRoot, { now, freshnessSeconds }).find(
+      (row) => row.path === entry.path,
+    );
+    if (!current) {
+      return { ...entry, classification: "unknown", reason: "entry disappeared", action: "keep" };
+    }
+    if (
+      current.action !== "would-delete" ||
+      current.artifact_id !== entry.artifact_id ||
+      current.bytes !== entry.bytes ||
+      current.last_modified_at !== entry.last_modified_at ||
+      current.expires_at !== entry.expires_at
+    ) {
+      return current;
+    }
     try {
       const top = lstatSync(current.path);
       if (!top.isDirectory() || top.isSymbolicLink()) {
@@ -277,6 +409,65 @@ export function cleanArtifacts(
   });
 }
 
+/** Sibling of the artifacts root so the stamp never appears in the inventory scan. */
+const AUTO_CLEAN_STAMP = ".harnery/artifacts-auto-clean.json";
+
+export interface ArtifactAutoCleanResult {
+  ran: boolean;
+  reason: "swept" | "disabled" | "fresh" | "no-root";
+  deleted: number;
+  bytes: number;
+}
+
+/**
+ * Throttled expired-artifact sweep, fired as a SessionStart effect.
+ *
+ * Retention was previously enforced only when someone remembered to run
+ * `artifacts clean --yes`, so expired workspaces accumulated indefinitely on
+ * busy hosts. This runs the exact same guarded deletion (only
+ * `managed-expired` entries, each re-classified immediately before removal;
+ * unmanaged and legacy directories are never touched) at most once per
+ * interval (default 24h), claim-first via a stamp file so concurrent session
+ * starts do not double-sweep. Disable with `artifacts.auto_clean: false` or
+ * `HARNERY_ARTIFACT_AUTO_CLEAN=0`.
+ */
+export function autoCleanArtifacts(
+  repoRoot: string,
+  opts: { now?: Date } = {},
+): ArtifactAutoCleanResult {
+  const now = opts.now ?? new Date();
+  assertValidDate(now, "now");
+  if (!existsSync(artifactsRoot(repoRoot))) {
+    return { ran: false, reason: "no-root", deleted: 0, bytes: 0 };
+  }
+  if (!artifactAutoCleanEnabled(repoRoot)) {
+    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 and write a fresh one.
+  }
+  // Claim first: a crash mid-sweep costs one skipped interval, while claiming
+  // after would let two concurrent session starts both walk the store.
+  writeFileSync(stampPath, `${JSON.stringify({ last_run_at: now.toISOString() }, null, 2)}\n`);
+  const rows = cleanArtifacts(repoRoot, { yes: true, now });
+  const deletedRows = rows.filter((row) => row.action === "deleted");
+  const deleted = deletedRows.length;
+  const bytes = deletedRows.reduce((sum, row) => sum + (row.bytes ?? 0), 0);
+  writeFileSync(
+    stampPath,
+    `${JSON.stringify({ last_run_at: now.toISOString(), deleted, bytes }, null, 2)}\n`,
+  );
+  return { ran: true, reason: "swept", deleted, bytes };
+}
+
 export function resolveArtifactRef(repoRoot: string, ref: string): string {
   const root = artifactsRoot(repoRoot);
   const candidate = isAbsolute(ref) ? resolve(ref) : resolve(root, ref);
@@ -341,6 +532,7 @@ function classifyArtifactPath(
     last_modified_at: new Date(effectiveLastModifiedMs).toISOString(),
     expires_at: effectiveExpiresAt,
     owner_instance_id: manifest.created_by?.instance_id ?? null,
+    oversize_acknowledged: manifest.oversize_acknowledged === true,
   });
 
   if (base.bytes === null || lastModifiedMs === null) {
@@ -387,6 +579,59 @@ function classifyArtifactPath(
   };
 }
 
+function applyArtifactBudgets(
+  repoRoot: string,
+  inputRows: ArtifactInventoryEntry[],
+): ArtifactInventoryEntry[] {
+  const maxUnitBytes = artifactMaxUnitBytes(repoRoot);
+  const maxBytes = artifactMaxBytes(repoRoot);
+  const rows = inputRows.map((row) => ({ ...row }));
+
+  for (const row of rows) {
+    if (
+      row.classification === "managed-current" &&
+      row.bytes !== null &&
+      row.bytes > maxUnitBytes &&
+      !row.oversize_acknowledged
+    ) {
+      row.classification = "managed-oversize";
+      row.reason = `bundle uses ${row.bytes} bytes, above the ${maxUnitBytes}-byte ceiling without --big`;
+      row.action = "would-delete";
+    }
+  }
+
+  const managedBytes = rows.reduce(
+    (sum, row) => sum + (row.artifact_id && row.bytes !== null ? row.bytes : 0),
+    0,
+  );
+  let retainedBytes =
+    managedBytes -
+    rows.reduce(
+      (sum, row) => sum + (row.action === "would-delete" && row.bytes !== null ? row.bytes : 0),
+      0,
+    );
+  if (retainedBytes <= maxBytes) return rows;
+
+  const candidates = rows
+    .filter(
+      (row) =>
+        row.classification === "managed-current" && row.action === "keep" && row.bytes !== null,
+    )
+    .sort((left, right) =>
+      `${left.expires_at ?? ""}\0${left.created_at ?? ""}\0${left.name}`.localeCompare(
+        `${right.expires_at ?? ""}\0${right.created_at ?? ""}\0${right.name}`,
+      ),
+    );
+  for (const row of candidates) {
+    if (retainedBytes <= maxBytes) break;
+    row.classification = "managed-over-budget";
+    row.reason = `repository artifact budget is ${maxBytes} bytes; earliest-expiring inactive bundles are removed first`;
+    row.action = "would-delete";
+    retainedBytes -= row.bytes ?? 0;
+  }
+  return rows;
+}
+
 function readManifest(path: string): ParsedManifest | ManifestError {
   const manifestPath = join(path, ARTIFACT_MANIFEST);
   if (!existsSync(manifestPath)) {
@@ -432,6 +677,9 @@ function readManifest(path: string): ParsedManifest | ManifestError {
   if (m.released_by !== undefined && !validActor(m.released_by)) {
     return { ok: false, reason: "invalid released_by" };
   }
+  if (m.oversize_acknowledged !== undefined && typeof m.oversize_acknowledged !== "boolean") {
+    return { ok: false, reason: "invalid oversize_acknowledged" };
+  }
   return { ok: true, manifest: m as ArtifactManifestV1 };
 }
 
@@ -541,6 +789,7 @@ function rowFor(
     last_modified_at: null,
     expires_at: null,
     owner_instance_id: null,
+    oversize_acknowledged: false,
   };
 }