harnery 0.33.0 → 0.34.0

package/src/lib/browser/tiling.ts

@@ -0,0 +1,164 @@
+// Content-aware band placement for the vision critique tiler.
+//
+// Fixed-height bands cut whatever sits at the boundary — half a heading, a
+// sliced table row, the middle of an image — and the critique rubric then has
+// to tell the model to ignore slice-edge clipping, which costs sensitivity on
+// every tile. This module snaps each cut into nearby content gaps instead:
+// the caller extracts "visual atoms" (text line boxes, replaced elements,
+// small bordered boxes) from the live page, and `snappedBandRects` places
+// each seam at the cheapest cut inside a bounded search window above the
+// fixed target. A clean seam (nothing straddles it) needs only a token
+// overlap; a dirty seam (unavoidable content, e.g. an element taller than
+// the band) keeps the caller's full overlap so the rubric mitigation still
+// applies there.
+//
+// Measured on a mixed fixture (prose, cards, 60-row table, an 1800px chart):
+// hard-atom slices per page dropped 9 → 1 on desktop and 4 → 2 on mobile at
+// an unchanged tile count, with every band height within [50%, 100%] of the
+// budget. The remaining slice was inside the over-tall chart, where no clean
+// cut exists — exactly the case the dirty-seam fallback covers.
+//
+// Pure math, no DOM access: atoms come in as plain rect spans so the module
+// stays testable and portable. Atom extraction lives on the browser client.
+
+export interface VisualAtom {
+  /** hard: cutting through it visibly breaks content. soft: looks untidy. */
+  kind: "text-line" | "replaced" | "box";
+  /** Document-space vertical span (CSS px scaled to image px by the caller). */
+  top: number;
+  bottom: number;
+}
+
+export interface SnapSeam {
+  /** Document-space y of the cut. */
+  y: number;
+  /** Weighted atoms the cut passes through; 0 = clean. */
+  cost: number;
+  /** Hard atoms (text lines, replaced elements) the cut passes through. */
+  hard: number;
+  clean: boolean;
+}
+
+export interface SnapOptions {
+  bandHeight: number;
+  /** Overlap applied below a dirty seam (the legacy constant, e.g. 120). */
+  overlap: number;
+  /** Overlap applied below a clean seam. Default 16. */
+  cleanOverlap?: number;
+  /** Fraction of bandHeight the seam may move up from its target. Default 0.3. */
+  slackRatio?: number;
+  /** Minimum band height as a fraction of bandHeight. Default 0.5. */
+  minBandRatio?: number;
+}
+
+const HARD_WEIGHT = 10;
+const SOFT_WEIGHT = 1;
+const EDGE_MARGIN = 4; // grazing an atom edge this closely counts as crossing
+const CANDIDATE_STEP = 2; // px between scored cut candidates
+
+/** Weighted cost of a horizontal cut at document-space y. */
+export function cutCost(atoms: VisualAtom[], y: number): { cost: number; hard: number } {
+  let cost = 0;
+  let hard = 0;
+  for (const a of atoms) {
+    if (y > a.top - EDGE_MARGIN && y < a.bottom + EDGE_MARGIN) {
+      if (a.kind === "box") {
+        cost += SOFT_WEIGHT;
+      } else {
+        cost += HARD_WEIGHT;
+        hard++;
+      }
+    }
+  }
+  return { cost, hard };
+}
+
+/**
+ * Cut the vertical span [top, bottom) into bands whose seams snap into
+ * content gaps. Seams only move UP from their fixed target (never down), so
+ * band height is bounded by `bandHeight` above and `minBandRatio` below.
+ * Returns full-width rects in the caller's coordinate space plus the seam
+ * record for logging/telemetry.
+ */
+export function snappedBandRects(
+  top: number,
+  bottom: number,
+  x: number,
+  width: number,
+  atoms: VisualAtom[],
+  opts: SnapOptions,
+): {
+  rects: Array<{ index: number; x: number; y: number; width: number; height: number }>;
+  seams: SnapSeam[];
+} {
+  const rects: Array<{ index: number; x: number; y: number; width: number; height: number }> = [];
+  const seams: SnapSeam[] = [];
+  const span = bottom - top;
+  if (span <= 0 || width <= 0) return { rects, seams };
+
+  const cleanOverlap = opts.cleanOverlap ?? 16;
+  const slack = Math.round(opts.bandHeight * (opts.slackRatio ?? 0.3));
+  const minBand = Math.round(opts.bandHeight * (opts.minBandRatio ?? 0.5));
+
+  let bandTop = top;
+  let index = 0;
+  while (bandTop + opts.bandHeight < bottom) {
+    const target = bandTop + opts.bandHeight;
+    const lo = Math.max(bandTop + minBand, target - slack);
+
+    // Score candidates, find the minimal cost in the window.
+    const costs: Array<{ y: number; cost: number; hard: number }> = [];
+    let minCost = Number.POSITIVE_INFINITY;
+    for (let y = lo; y <= target; y += CANDIDATE_STEP) {
+      const c = cutCost(atoms, y);
+      costs.push({ y, ...c });
+      if (c.cost < minCost) minCost = c.cost;
+    }
+
+    // Snap to the center of the widest minimal-cost run; ties resolve toward
+    // the target (later run wins on >=) so bands stay as tall as possible.
+    let runStart = -1;
+    let best = { start: 0, end: costs.length - 1, len: 0 };
+    for (let i = 0; i <= costs.length; i++) {
+      const inRun = i < costs.length && costs[i].cost === minCost;
+      if (inRun && runStart === -1) runStart = i;
+      if (!inRun && runStart !== -1) {
+        const len = i - runStart;
+        if (len >= best.len) best = { start: runStart, end: i - 1, len };
+        runStart = -1;
+      }
+    }
+    const pick = costs[Math.floor((best.start + best.end) / 2)];
+    const clean = pick.cost === 0;
+    seams.push({ y: pick.y, cost: pick.cost, hard: pick.hard, clean });
+    rects.push({ index, x, y: bandTop, width, height: pick.y - bandTop });
+    index++;
+    bandTop = pick.y - (clean ? cleanOverlap : opts.overlap);
+  }
+  rects.push({ index, x, y: bandTop, width, height: bottom - bandTop });
+  return { rects, seams };
+}
+
+/**
+ * Split one element rect into internally-banded sub-rects when it is taller
+ * than the band budget. Selector-mode tiles previously shipped over-tall
+ * elements as one giant tile that the vision provider downscales; banding
+ * inside the element keeps every sub-tile at full resolution. Elements within
+ * 1.25x of the budget stay whole — a slightly-over tile beats a degenerate
+ * split.
+ */
+export function bandOversizedRect(
+  rect: { label: string; x: number; y: number; width: number; height: number },
+  atoms: VisualAtom[],
+  opts: SnapOptions,
+): Array<{ label: string; x: number; y: number; width: number; height: number }> {
+  if (rect.height <= opts.bandHeight * 1.25) return [rect];
+  const { rects } = snappedBandRects(rect.y, rect.y + rect.height, rect.x, rect.width, atoms, opts);
+  return rects.map((r, i) => ({
+    label: `${rect.label} (${i + 1}/${rects.length})`,
+    x: r.x,
+    y: r.y,
+    width: r.width,
+    height: r.height,
+  }));
+}

package/src/lib/claude-desktop.ts

@@ -1,19 +1,6 @@
-import { randomUUID } from "node:crypto";
-import {
-  copyFileSync,
-  createReadStream,
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  renameSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
-import { createInterface } from "node:readline";
 
 /**
  * Claude desktop app session-index access.
@@ -80,49 +67,6 @@ export interface MirrorPlan {
   skippedArchived: number;
 }
 
-export type DesktopLifecycleState = "active" | "blocked" | "done";
-
-export interface DesktopLifecycleRecord {
-  state: DesktopLifecycleState;
-  updatedAt: string;
-  instanceId: string | null;
-  sessionId: string | null;
-  reason: string | null;
-}
-
-export type DesktopTidySource = "lifecycle" | "legacy-prefix";
-
-export interface DesktopTidyAction {
-  entry: DesktopSessionEntry;
-  source: DesktopTidySource;
-  lifecycle: DesktopLifecycleRecord | null;
-}
-
-export type DesktopTidySkipReason =
-  | "already_archived"
-  | "blocked_title"
-  | "lifecycle_active"
-  | "lifecycle_blocked"
-  | "unmatched";
-
-export interface DesktopTidySkip {
-  entry: DesktopSessionEntry;
-  reason: DesktopTidySkipReason;
-  lifecycle: DesktopLifecycleRecord | null;
-}
-
-export interface DesktopTidyPlan {
-  actions: DesktopTidyAction[];
-  skipped: DesktopTidySkip[];
-}
-
-export interface DesktopTidyOptions {
-  /** Restrict entries to accounts whose UUID starts with one of these prefixes. */
-  accounts?: string[];
-  /** Accept an unmatched historical `[DONE]` title as a compatibility fallback. */
-  includeLegacyPrefix?: boolean;
-}
-
 const SESSIONS_DIRNAME = "claude-code-sessions";
 
 function isWsl(): boolean {
@@ -350,178 +294,3 @@ export function applyMirror(plan: MirrorPlan): { copied: number } {
   }
   return { copied };
 }
-
-/**
- * Read the latest durable lifecycle declaration for every Harnery session.
- *
- * The canonical ledger rotates into `events-*.ndjson` archives. Stream each
- * file rather than loading the whole history into one string, then compare
- * event timestamps because adapter replay may append an older event later.
- * Records are indexed by both session_id and instance_id so a desktop
- * cliSessionId can match either identity shape used by older adapters.
- */
-export async function readDesktopLifecycleIndex(
-  coordRoot: string,
-): Promise<Map<string, DesktopLifecycleRecord>> {
-  const coordDir = join(coordRoot, ".harnery");
-  const archives = safeReaddir(coordDir)
-    .filter((name) => name.startsWith("events-") && name.endsWith(".ndjson"))
-    .sort();
-  const files = [...archives, "events.ndjson"]
-    .map((name) => join(coordDir, name))
-    .filter((path) => existsSync(path));
-
-  const records = new Map<string, DesktopLifecycleRecord>();
-  const timestamps = new Map<string, number>();
-
-  for (const file of files) {
-    let lines: ReturnType<typeof createInterface> | null = null;
-    try {
-      lines = createInterface({
-        input: createReadStream(file, { encoding: "utf8" }),
-        crlfDelay: Infinity,
-      });
-      for await (const line of lines) {
-        if (!line.trim()) continue;
-        let raw: unknown;
-        try {
-          raw = JSON.parse(line);
-        } catch {
-          continue;
-        }
-        if (!raw || typeof raw !== "object") continue;
-        const event = raw as Record<string, unknown>;
-        if (event.event_type !== "state.task_state" || typeof event.ts !== "string") continue;
-        const data = event.data;
-        if (!data || typeof data !== "object") continue;
-        const state = (data as Record<string, unknown>).state;
-        if (state !== "active" && state !== "blocked" && state !== "done") continue;
-
-        const instanceId = typeof event.instance_id === "string" ? event.instance_id : null;
-        const sessionId = typeof event.session_id === "string" ? event.session_id : null;
-        const reasonValue = (data as Record<string, unknown>).reason;
-        const record: DesktopLifecycleRecord = {
-          state,
-          updatedAt: event.ts,
-          instanceId,
-          sessionId,
-          reason: typeof reasonValue === "string" && reasonValue.length > 0 ? reasonValue : null,
-        };
-        const timestamp = Number.isFinite(Date.parse(event.ts)) ? Date.parse(event.ts) : 0;
-        for (const key of new Set(
-          [sessionId, instanceId].filter((value): value is string => !!value),
-        )) {
-          const priorTimestamp = timestamps.get(key);
-          if (priorTimestamp !== undefined && priorTimestamp > timestamp) continue;
-          timestamps.set(key, timestamp);
-          records.set(key, record);
-        }
-      }
-    } catch {
-      // A missing or concurrently rotated event file cannot make tidy unsafe:
-      // absent lifecycle evidence leaves entries unmatched and therefore skipped.
-    } finally {
-      lines?.close();
-    }
-  }
-
-  return records;
-}
-
-/** Select desktop entries whose durable lifecycle is done. */
-export function planTidy(
-  accounts: DesktopAccount[],
-  lifecycleBySession: ReadonlyMap<string, DesktopLifecycleRecord>,
-  opts: DesktopTidyOptions = {},
-): DesktopTidyPlan {
-  const selectedAccounts = accounts.filter(
-    (account) =>
-      !opts.accounts?.length ||
-      opts.accounts.some((prefix) => account.accountUuid.startsWith(prefix)),
-  );
-  const actions: DesktopTidyAction[] = [];
-  const skipped: DesktopTidySkip[] = [];
-
-  for (const account of selectedAccounts) {
-    for (const entry of account.entries) {
-      const lifecycle = lifecycleForEntry(entry, lifecycleBySession);
-      if (entry.isArchived) {
-        skipped.push({ entry, reason: "already_archived", lifecycle });
-        continue;
-      }
-      if (hasLifecyclePrefix(entry.title, "BLOCKED")) {
-        skipped.push({ entry, reason: "blocked_title", lifecycle });
-        continue;
-      }
-      if (lifecycle) {
-        if (lifecycle.state === "done") {
-          actions.push({ entry, source: "lifecycle", lifecycle });
-        } else {
-          skipped.push({ entry, reason: `lifecycle_${lifecycle.state}`, lifecycle });
-        }
-        continue;
-      }
-      if (opts.includeLegacyPrefix && hasLifecyclePrefix(entry.title, "DONE")) {
-        actions.push({ entry, source: "legacy-prefix", lifecycle: null });
-      } else {
-        skipped.push({ entry, reason: "unmatched", lifecycle: null });
-      }
-    }
-  }
-
-  return { actions, skipped };
-}
-
-/** Apply a tidy plan with same-directory temp files and atomic renames. */
-export function applyTidy(plan: DesktopTidyPlan): { archived: number; alreadyArchived: number } {
-  let archived = 0;
-  let alreadyArchived = 0;
-  for (const action of plan.actions) {
-    if (archiveEntry(action.entry.file)) archived++;
-    else alreadyArchived++;
-  }
-  return { archived, alreadyArchived };
-}
-
-function lifecycleForEntry(
-  entry: DesktopSessionEntry,
-  lifecycleBySession: ReadonlyMap<string, DesktopLifecycleRecord>,
-): DesktopLifecycleRecord | null {
-  if (entry.cliSessionId) {
-    const lifecycle = lifecycleBySession.get(entry.cliSessionId);
-    if (lifecycle) return lifecycle;
-  }
-  return entry.sessionId ? (lifecycleBySession.get(entry.sessionId) ?? null) : null;
-}
-
-function hasLifecyclePrefix(title: string | null, state: "BLOCKED" | "DONE"): boolean {
-  if (!title) return false;
-  return new RegExp(`^\\s*\\[${state}\\](?:\\s*-|\\s|$)`, "i").test(title);
-}
-
-function archiveEntry(file: string): boolean {
-  const text = readFileSync(file, "utf8");
-  const raw = JSON.parse(text) as unknown;
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error(`desktop entry is not a JSON object: ${file}`);
-  }
-  const entry = raw as Record<string, unknown>;
-  if (entry.isArchived === true) return false;
-  entry.isArchived = true;
-
-  const pretty = text.includes("\n");
-  const trailingNewline = text.endsWith("\n") ? "\n" : "";
-  const next = `${JSON.stringify(entry, null, pretty ? 2 : undefined)}${trailingNewline}`;
-  const temp = join(dirname(file), `.${basename(file)}.${process.pid}.${randomUUID()}.tmp`);
-  try {
-    writeFileSync(temp, next, { encoding: "utf8", mode: statSync(file).mode });
-    renameSync(temp, file);
-  } finally {
-    try {
-      unlinkSync(temp);
-    } catch {
-      // rename already consumed the temp file, or creation failed before it existed
-    }
-  }
-  return true;
-}

package/src/lib/context/index.ts

@@ -1,11 +1,10 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { resolve } from "node:path";
+import { monorepoRoot, resolveOwner } from "../../core/agents/index.ts";
 import {
-  type Heartbeat,
-  monorepoRoot,
-  readHeartbeat,
-  resolveOwner,
-} from "../../core/agents/index.ts";
+  readLiveCoordinationRow,
+  readLiveCoordinationRows,
+} from "../../core/agents/state/live-coordination-view.ts";
 import { exec } from "../exec.ts";
 import { NO_DATA } from "../format.ts";
 
@@ -78,8 +77,6 @@ export interface SelfSection {
   instance_id: string;
   session_age_secs: number;
   task: string | null;
-  last_tool: string | null;
-  last_tool_target: string | null;
   files_held: string[];
 }
 
@@ -113,7 +110,6 @@ export interface PeersSection {
     instance_id_short: string;
     age_min: number;
     files: number;
-    last_tool: string | null;
     task: string | null;
   }[];
 }
@@ -155,19 +151,14 @@ export async function buildContext(opts: ContextOptions = {}): Promise<ContextRe
 function buildSelf(): SelfSection {
   const owner = resolveOwner();
   if (!owner) throw new Error("not in an agent session (no pid-map entry)");
-  const hb = readHeartbeat(owner);
-  // Full id, never abbreviated: this message exists to hand the reader an id to
-  // pass back (to `agents heal --owner`, say), and an 8-char prefix is not that
-  // id. Healing the truncated form writes `.harnery/active/<prefix>.json`, a
-  // heartbeat no reader ever resolves — so the session still looks unhealable
-  // and now has a junk file shadowing it. Same rule as `noHeartbeatMessage` in
-  // the agents command.
+  const root = monorepoRoot();
+  const hb = root ? readLiveCoordinationRow(root, owner) : null;
+  // Full id, never abbreviated: command surfaces pass this identity back to
+  // the authority-safe V3 coordination projection.
   if (!hb) {
-    throw new Error(
-      `pid-map resolved owner=${owner} but no heartbeat exists at .harnery/active/${owner}.json`,
-    );
+    throw new Error(`pid-map resolved owner=${owner} but no live V3 generation exists for it`);
   }
-  const startedMs = Date.parse(hb.started_at);
+  const startedMs = Date.parse(hb.started_at ?? "");
   const ageSecs = Number.isFinite(startedMs)
     ? Math.max(0, Math.floor((Date.now() - startedMs) / 1000))
     : 0;
@@ -176,8 +167,6 @@ function buildSelf(): SelfSection {
     instance_id: hb.instance_id,
     session_age_secs: ageSecs,
     task: hb.task ?? null,
-    last_tool: hb.last_tool ?? null,
-    last_tool_target: hb.last_tool_target ?? null,
     files_held: hb.files_touched ?? [],
   };
 }
@@ -296,32 +285,19 @@ async function statusFor(name: string, cwd: string): Promise<SubmoduleStatus> {
 function buildPeers(): PeersSection {
   const root = monorepoRoot();
   if (!root) throw new Error("coord_root() returned null");
-  const activeDir = resolve(root, ".harnery", "active");
-  if (!existsSync(activeDir)) return { rows: [] };
   const myOwner = resolveOwner();
-  // No freshness filter; matches the SessionStart/UserPromptSubmit snapshot.
-  // Stale entries get swept by the SessionStart janitor on the next session start.
   const rows: PeersSection["rows"] = [];
-  for (const f of readdirSync(activeDir)) {
-    if (!f.endsWith(".json")) continue;
-    try {
-      const hb = JSON.parse(readFileSync(resolve(activeDir, f), "utf8")) as Heartbeat;
-      if (!hb || typeof hb.instance_id !== "string") continue;
-      if (hb.instance_id === myOwner) continue;
-      if ((hb.kind ?? "") === "transient") continue;
-      const startedMs = Date.parse(hb.started_at);
-      const ageMin = Number.isFinite(startedMs) ? Math.floor((Date.now() - startedMs) / 60000) : 0;
-      rows.push({
-        name: hb.name ?? "unknown",
-        instance_id_short: hb.instance_id.slice(0, 8),
-        age_min: ageMin,
-        files: hb.files_touched?.length ?? 0,
-        last_tool: hb.last_tool ?? null,
-        task: hb.task ?? null,
-      });
-    } catch {
-      // skip
-    }
+  for (const row of readLiveCoordinationRows(root)) {
+    if (row.instance_id === myOwner || row.kind === "transient") continue;
+    const startedMs = Date.parse(row.started_at ?? row.last_heartbeat);
+    const ageMin = Number.isFinite(startedMs) ? Math.floor((Date.now() - startedMs) / 60000) : 0;
+    rows.push({
+      name: row.name ?? "unknown",
+      instance_id_short: row.instance_id.slice(0, 8),
+      age_min: ageMin,
+      files: row.files_touched.length,
+      task: row.task ?? null,
+    });
   }
   // Sort: file-holders first (more activity), then by recency (younger age first).
   rows.sort((a, b) => b.files - a.files || a.age_min - b.age_min);

package/src/lib/council/index.ts

@@ -19,6 +19,7 @@ import {
 import { basename, resolve } from "node:path";
 
 import { monorepoRoot } from "../../core/agents/index.ts";
+import { readLiveCoordinationRows } from "../../core/agents/state/live-coordination-view.ts";
 import { resolveBinName } from "../../core/config.ts";
 import { ensureIdentity, lookupById as lookupIdentityById } from "../identities/index.js";
 
@@ -241,7 +242,7 @@ export function setCouncilSteward(councilId: string, steward: string | null): Co
 export interface KnownAgent {
   /** `agent-<Name>` canonical handle. */
   name: string;
-  /** `active` = currently has a heartbeat in `.harnery/active/`. `stale` =
+  /** `active` = currently has an authority-eligible V3 generation. `stale` =
    * recently ended (journal archived within the lookback window). */
   state: "active" | "stale";
   /** ISO timestamp of the most-recent signal. */
@@ -253,35 +254,22 @@ export interface KnownAgent {
 const KNOWN_AGENT_STALE_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
 
 /**
- * Active heartbeats + recently-archived journals, deduped by name.
+ * Active V3 generations + recently-archived journals, deduped by name.
  * Used by `agents council set-steward` to refuse arbitrary names;
  * pass `--allow-unknown` to bypass when bootstrapping a new agent.
  */
 export function listKnownAgents(): KnownAgent[] {
   const root = monorepoRoot();
   if (!root) return [];
-  const activeDir = resolve(root, ".harnery", "active");
   const archiveDir = resolve(root, ".harnery", "journal", "archived");
   const byName = new Map<string, KnownAgent>();
 
-  if (existsSync(activeDir)) {
-    for (const f of readdirSync(activeDir)) {
-      if (!f.endsWith(".json")) continue;
-      try {
-        const hb = JSON.parse(readFileSync(resolve(activeDir, f), "utf8")) as {
-          name?: string;
-          last_heartbeat?: string;
-        };
-        if (!hb.name) continue;
-        const name = hb.name.startsWith("agent-") ? hb.name : `agent-${hb.name}`;
-        const last_seen = hb.last_heartbeat ?? new Date().toISOString();
-        const existing = byName.get(name);
-        if (existing?.state !== "active") {
-          byName.set(name, { name, state: "active", last_seen });
-        }
-      } catch {
-        /* skip unreadable */
-      }
+  for (const row of readLiveCoordinationRows(root)) {
+    if (!row.name) continue;
+    const name = row.name.startsWith("agent-") ? row.name : `agent-${row.name}`;
+    const existing = byName.get(name);
+    if (existing?.state !== "active") {
+      byName.set(name, { name, state: "active", last_seen: row.last_heartbeat });
     }
   }