harnery 0.9.0 → 0.11.0

package/src/core/presence/blob.ts

@@ -0,0 +1,125 @@
+/**
+ * Presence blob: the per-machine payload published to
+ * `refs/harnery/presence/<machine>` (ADR 0016). One blob describes every live
+ * session on this machine; peers render it in their agents list / status box /
+ * peer table, labeled by machine.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveMachineLabel } from "../../lib/machine.ts";
+
+/** Mirror of the local heartbeat freshness window (commands/agents.ts). */
+const FRESHNESS_SECS = 600;
+
+/** Caps that bound the blob to ~1-2KB regardless of local state. */
+const MAX_AGENTS = 20;
+const MAX_FILES_PER_AGENT = 10;
+
+export interface PresenceAgent {
+  instance_id: string;
+  name?: string;
+  kind?: string;
+  session_id?: string;
+  platform?: string;
+  task?: string;
+  turn_summary?: string;
+  files_touched?: string[];
+  last_tool?: string;
+  started_at?: string;
+  last_heartbeat?: string;
+}
+
+export interface PresenceBlob {
+  v: 1;
+  machine: string;
+  published_at: string;
+  agents: PresenceAgent[];
+}
+
+export interface BuiltBlob {
+  blob: PresenceBlob;
+  /** Stable hash of the semantically-relevant projection — the change
+   * detector that decides whether a publish is worth a push. */
+  basisHash: string;
+  json: string;
+}
+
+/**
+ * Build this machine's presence blob from `.harnery/active/` heartbeats.
+ * Includes live sessions + subagents; excludes kind=transient stubs (they are
+ * fold-artifacts of the local claim model, not sessions) and anything past the
+ * freshness window.
+ */
+export function buildPresenceBlob(coordRoot: string, now: Date = new Date()): BuiltBlob {
+  const machine = resolveMachineLabel();
+  const agents: PresenceAgent[] = [];
+  const activeDir = join(coordRoot, ".harnery", "active");
+  const cutoffMs = now.getTime() - FRESHNESS_SECS * 1000;
+
+  if (existsSync(activeDir)) {
+    for (const f of readdirSync(activeDir)) {
+      if (!f.endsWith(".json")) continue;
+      let hb: Record<string, unknown>;
+      try {
+        hb = JSON.parse(readFileSync(join(activeDir, f), "utf8")) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      if (typeof hb.instance_id !== "string") continue;
+      if ((hb.kind as string | undefined) === "transient") continue;
+      const ts = Date.parse((hb.last_heartbeat as string | undefined) ?? "");
+      if (!Number.isFinite(ts) || ts < cutoffMs) continue;
+      agents.push({
+        instance_id: hb.instance_id,
+        name: strOr(hb.name),
+        kind: strOr(hb.kind),
+        session_id: strOr(hb.session_id),
+        platform: strOr(hb.platform),
+        task: strOr(hb.task),
+        turn_summary: clamp(strOr(hb.turn_summary), 160),
+        files_touched: Array.isArray(hb.files_touched)
+          ? (hb.files_touched as string[]).slice(0, MAX_FILES_PER_AGENT)
+          : undefined,
+        last_tool: strOr(hb.last_tool),
+        started_at: strOr(hb.started_at),
+        last_heartbeat: strOr(hb.last_heartbeat),
+      });
+    }
+  }
+
+  agents.sort((a, b) => a.instance_id.localeCompare(b.instance_id));
+  const capped = agents.slice(0, MAX_AGENTS);
+
+  const blob: PresenceBlob = {
+    v: 1,
+    machine,
+    published_at: now.toISOString().replace(/\.\d{3}Z$/, "Z"),
+    agents: capped,
+  };
+
+  // Basis: the fields whose change should trigger a re-publish. Timestamps
+  // and last_tool are excluded (pure churn); task/turn_summary/files are the
+  // signal peers actually read.
+  const basis = capped.map((a) => ({
+    i: a.instance_id,
+    n: a.name ?? null,
+    k: a.kind ?? null,
+    t: a.task ?? null,
+    s: a.turn_summary ?? null,
+    f: [...(a.files_touched ?? [])].sort(),
+  }));
+  const basisHash = createHash("sha256").update(JSON.stringify(basis)).digest("hex").slice(0, 16);
+
+  return { blob, basisHash, json: JSON.stringify(blob) };
+}
+
+function strOr(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function clamp(v: string | undefined, max: number): string | undefined {
+  if (!v) return undefined;
+  return v.length > max ? v.slice(0, max) : v;
+}

package/src/core/presence/git.ts

@@ -0,0 +1,191 @@
+/**
+ * Git plumbing for the cross-machine presence transport (ADR 0016).
+ *
+ * Presence blobs travel as parentless commits (empty tree, JSON message)
+ * force-pushed to `refs/harnery/presence/<machine>` on the host repo's own
+ * `origin`. Non-branch refs: invisible to branch tooling, safe to force-push,
+ * no history accumulation. The remote is the rendezvous every install already
+ * shares, and repo access is the ACL.
+ *
+ * Everything here is best-effort and fail-silent by design — presence must
+ * never break a hook or a render. Network operations (push/fetch) run either
+ * detached (hook path: never block a turn) or synchronously (CLI path: the
+ * user wants to see errors).
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+
+/** The ref namespace. Hardcoded — never interpolated from config — so the
+ * publisher is structurally unable to touch refs/heads/* (ADR 0016). */
+export const PRESENCE_REF_PREFIX = "refs/harnery/presence/";
+
+/** Well-known SHA of git's empty tree; `git mktree` below guarantees the
+ * object exists in the local odb before we build a commit on it. */
+const EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
+const GIT_TIMEOUT_MS = 8000;
+
+/** Non-interactive env for every presence git call: never prompt for creds
+ * (a hook must not hang on a password), and a fixed identity so commit-tree
+ * works on machines with no user.name/user.email configured. */
+function gitEnv(): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_AUTHOR_NAME: "harnery-presence",
+    GIT_AUTHOR_EMAIL: "presence@harnery.invalid",
+    GIT_COMMITTER_NAME: "harnery-presence",
+    GIT_COMMITTER_EMAIL: "presence@harnery.invalid",
+  };
+}
+
+function runGit(
+  root: string,
+  args: string[],
+  input?: string,
+): { ok: boolean; stdout: string; stderr: string } {
+  try {
+    const r = spawnSync("git", ["-C", root, ...args], {
+      encoding: "utf8",
+      timeout: GIT_TIMEOUT_MS,
+      env: gitEnv(),
+      ...(input !== undefined ? { input } : {}),
+    });
+    return { ok: r.status === 0, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+  } catch {
+    return { ok: false, stdout: "", stderr: "spawn failed" };
+  }
+}
+
+/** Does the repo have an `origin` remote to rendezvous on? */
+export function hasOrigin(root: string): boolean {
+  return runGit(root, ["remote", "get-url", "origin"]).ok;
+}
+
+/** The origin remote URL, or null. Input to relay room derivation. */
+export function originUrl(root: string): string | null {
+  const r = runGit(root, ["remote", "get-url", "origin"]);
+  const url = r.stdout.trim();
+  return r.ok && url ? url : null;
+}
+
+/**
+ * The repo's root-commit SHA — the stable repo-identity input to relay room
+ * derivation. Repos can have multiple roots (merged histories); the list is
+ * sorted so every clone picks the same one. Null when the repo has no commits.
+ */
+export function rootCommitSha(root: string): string | null {
+  const r = runGit(root, ["rev-list", "--max-parents=0", "HEAD"]);
+  if (!r.ok) return null;
+  const shas = r.stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .sort();
+  return shas[0] ?? null;
+}
+
+/**
+ * Sanitize a machine label into a valid single ref component: lowercase,
+ * [a-z0-9._-] only, no leading dot, no `.lock` suffix, never empty.
+ */
+export function sanitizeRefComponent(label: string): string {
+  let s = label
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/\.{2,}/g, ".")
+    .replace(/^[.-]+/, "")
+    .replace(/\.lock$/, "");
+  if (!s) s = "unknown";
+  return s;
+}
+
+/** Build the parentless presence commit carrying `message` (the JSON blob).
+ * Returns the commit sha, or null on failure. Local-only, fast (~10ms). */
+export function writePresenceCommit(root: string, message: string): string | null {
+  // Ensure the empty-tree object exists in this odb (mktree with empty stdin
+  // writes it idempotently).
+  const mk = runGit(root, ["mktree"], "");
+  const tree = mk.ok && mk.stdout.trim() ? mk.stdout.trim() : EMPTY_TREE_SHA;
+  const r = runGit(root, ["commit-tree", tree, "-m", message]);
+  return r.ok && r.stdout.trim() ? r.stdout.trim() : null;
+}
+
+/**
+ * Force-push a presence commit to `refs/harnery/presence/<machine>`.
+ * `sync: true` (CLI/tests) waits and reports; default is detached fire-and-
+ * forget (hook path — a slow or credential-less push must not block a turn).
+ */
+export function pushPresenceRef(
+  root: string,
+  machine: string,
+  sha: string,
+  opts: { sync?: boolean } = {},
+): { ok: boolean; error?: string } {
+  const refspec = `+${sha}:${PRESENCE_REF_PREFIX}${sanitizeRefComponent(machine)}`;
+  const args = ["-C", root, "push", "--quiet", "--no-verify", "origin", refspec];
+  if (opts.sync) {
+    const r = runGit(root, args.slice(2));
+    return r.ok ? { ok: true } : { ok: false, error: r.stderr.trim().slice(0, 300) };
+  }
+  try {
+    const child = spawn("git", args, { detached: true, stdio: "ignore", env: gitEnv() });
+    child.unref();
+    return { ok: true };
+  } catch {
+    return { ok: false, error: "spawn failed" };
+  }
+}
+
+/** Fetch every peer presence ref from origin into the local ref namespace. */
+export function fetchPresenceRefs(
+  root: string,
+  opts: { sync?: boolean } = {},
+): { ok: boolean; error?: string } {
+  const refspec = `+${PRESENCE_REF_PREFIX}*:${PRESENCE_REF_PREFIX}*`;
+  const args = ["-C", root, "fetch", "--quiet", "--no-tags", "origin", refspec];
+  if (opts.sync) {
+    const r = runGit(root, args.slice(2));
+    return r.ok ? { ok: true } : { ok: false, error: r.stderr.trim().slice(0, 300) };
+  }
+  try {
+    const child = spawn("git", args, { detached: true, stdio: "ignore", env: gitEnv() });
+    child.unref();
+    return { ok: true };
+  } catch {
+    return { ok: false, error: "spawn failed" };
+  }
+}
+
+/** Read every locally-known presence ref → [{ref, machine, message}]. */
+export function readPresenceRefs(root: string): Array<{ machine: string; message: string }> {
+  const r = runGit(root, [
+    "for-each-ref",
+    "--format=%(refname)%00%(contents)%01",
+    `${PRESENCE_REF_PREFIX}*`,
+  ]);
+  if (!r.ok) return [];
+  return parseForEachRefOutput(r.stdout);
+}
+
+/**
+ * Parse `for-each-ref --format='%(refname)%00%(contents)%01'` output.
+ * Records are %01-terminated (contents may contain newlines); refname and
+ * contents are %00-separated. Exported for unit tests.
+ */
+export function parseForEachRefOutput(out: string): Array<{ machine: string; message: string }> {
+  const rows: Array<{ machine: string; message: string }> = [];
+  for (const rec of out.split("\u0001")) {
+    const trimmed = rec.replace(/^\n+/, "");
+    if (!trimmed) continue;
+    const sep = trimmed.indexOf("\u0000");
+    if (sep === -1) continue;
+    const refname = trimmed.slice(0, sep).trim();
+    if (!refname.startsWith(PRESENCE_REF_PREFIX)) continue;
+    rows.push({
+      machine: refname.slice(PRESENCE_REF_PREFIX.length),
+      message: trimmed.slice(sep + 1).trim(),
+    });
+  }
+  return rows;
+}

package/src/core/presence/index.ts

@@ -0,0 +1,274 @@
+/**
+ * Cross-machine presence (ADR 0016), phase 1: the git-refs transport.
+ *
+ * publishPresence(): serialize this machine's live sessions into a presence
+ * blob and force-push it to `refs/harnery/presence/<machine>` on origin —
+ * change-batched (only when the blob materially changed) with a keepalive
+ * (~5 min) so peers can distinguish "no change" from "machine gone".
+ *
+ * fetchPresence(): throttled fetch of every peer machine's presence ref.
+ *
+ * readRemoteMachines(): parse the locally-known refs into render-ready rows
+ * (self machine excluded, stale blobs dropped).
+ *
+ * All entry points are fail-silent and gated on `presenceEnabled()` — presence
+ * must never break a hook, a render, or a repo with no origin.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { coordEnv } from "../../lib/env.ts";
+import { resolveMachineLabel } from "../../lib/machine.ts";
+import { presenceEnabled } from "../config.ts";
+import { buildPresenceBlob, type PresenceAgent, type PresenceBlob } from "./blob.ts";
+import {
+  fetchPresenceRefs,
+  hasOrigin,
+  pushPresenceRef,
+  readPresenceRefs,
+  sanitizeRefComponent,
+  writePresenceCommit,
+} from "./git.ts";
+
+export type { PresenceAgent, PresenceBlob } from "./blob.ts";
+export { buildPresenceBlob } from "./blob.ts";
+export { PRESENCE_REF_PREFIX, parseForEachRefOutput, sanitizeRefComponent } from "./git.ts";
+export { ensureRelayDaemon, relayDaemonStatus, runRelayDaemon } from "./relay-client.ts";
+
+/** Re-push at least this often while sessions are live, so peers can treat a
+ * blob older than ~3x this as "machine offline" rather than "no change". */
+const KEEPALIVE_SECS = 300;
+/** Never push more often than this, however chatty the triggers. */
+const MIN_PUSH_INTERVAL_SECS = 15;
+/** Default fetch throttle (hook cadence fires far more often than this). */
+const FETCH_INTERVAL_SECS = 60;
+/** A blob whose published_at is older than this is rendered as gone. */
+const REMOTE_STALE_SECS = 900;
+
+export type PublishResult =
+  | { status: "published"; machine: string; agents: number; sha: string }
+  | { status: "skipped"; reason: string }
+  | { status: "error"; error: string };
+
+export type FetchResult =
+  | { status: "fetched" }
+  | { status: "skipped"; reason: string }
+  | { status: "error"; error: string };
+
+interface PublishState {
+  basis_hash?: string;
+  pushed_at?: string;
+  agents?: number;
+}
+
+function presenceDir(coordRoot: string): string {
+  return join(coordRoot, ".harnery", "presence");
+}
+
+function statePath(coordRoot: string): string {
+  return join(presenceDir(coordRoot), "publish-state.json");
+}
+
+function fetchStampPath(coordRoot: string): string {
+  return join(presenceDir(coordRoot), "fetch-stamp");
+}
+
+function readState(coordRoot: string): PublishState {
+  try {
+    return JSON.parse(readFileSync(statePath(coordRoot), "utf8")) as PublishState;
+  } catch {
+    return {};
+  }
+}
+
+function writeState(coordRoot: string, state: PublishState): void {
+  try {
+    const p = statePath(coordRoot);
+    mkdirSync(presenceDir(coordRoot), { recursive: true });
+    const tmp = `${p}.tmp.${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(state), "utf8");
+    renameSync(tmp, p);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Publish this machine's presence blob to origin if it changed (or the
+ * keepalive elapsed). `sync: true` pushes in-process and reports errors (CLI
+ * path); default spawns the push detached (hook path).
+ */
+export function publishPresence(
+  coordRoot: string,
+  opts: { force?: boolean; sync?: boolean } = {},
+): PublishResult {
+  try {
+    if (!presenceEnabled(coordRoot)) return { status: "skipped", reason: "disabled" };
+    if (!hasOrigin(coordRoot)) return { status: "skipped", reason: "no origin remote" };
+
+    const { blob, basisHash, json } = buildPresenceBlob(coordRoot);
+    const state = readState(coordRoot);
+    const pushedAtMs = Date.parse(state.pushed_at ?? "");
+    const sincePush = Number.isFinite(pushedAtMs)
+      ? (Date.now() - pushedAtMs) / 1000
+      : Number.POSITIVE_INFINITY;
+
+    if (!opts.force) {
+      // Nothing live and the last publish already said so → stay quiet.
+      if (blob.agents.length === 0 && (state.agents ?? 0) === 0) {
+        return { status: "skipped", reason: "no live sessions" };
+      }
+      const unchanged = state.basis_hash === basisHash;
+      if (unchanged && sincePush < KEEPALIVE_SECS) {
+        return { status: "skipped", reason: "unchanged (within keepalive)" };
+      }
+      if (!unchanged && sincePush < MIN_PUSH_INTERVAL_SECS) {
+        return { status: "skipped", reason: "min push interval" };
+      }
+    }
+
+    const sha = writePresenceCommit(coordRoot, json);
+    if (!sha) return { status: "error", error: "commit-tree failed" };
+
+    const push = pushPresenceRef(coordRoot, blob.machine, sha, { sync: opts.sync });
+    if (!push.ok) return { status: "error", error: push.error ?? "push failed" };
+
+    // Optimistic on the detached path: a failed background push self-heals at
+    // the next keepalive re-push.
+    writeState(coordRoot, {
+      basis_hash: basisHash,
+      pushed_at: new Date().toISOString(),
+      agents: blob.agents.length,
+    });
+    return { status: "published", machine: blob.machine, agents: blob.agents.length, sha };
+  } catch (e) {
+    return { status: "error", error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/** Throttled fetch of peer presence refs from origin. */
+export function fetchPresence(
+  coordRoot: string,
+  opts: { force?: boolean; sync?: boolean } = {},
+): FetchResult {
+  try {
+    if (!presenceEnabled(coordRoot)) return { status: "skipped", reason: "disabled" };
+    if (!hasOrigin(coordRoot)) return { status: "skipped", reason: "no origin remote" };
+
+    const stamp = fetchStampPath(coordRoot);
+    if (!opts.force) {
+      const interval = Number.parseInt(
+        coordEnv("PRESENCE_FETCH_INTERVAL") ?? String(FETCH_INTERVAL_SECS),
+        10,
+      );
+      try {
+        const age = (Date.now() - statSync(stamp).mtimeMs) / 1000;
+        if (age < interval) return { status: "skipped", reason: "within fetch interval" };
+      } catch {
+        /* no stamp yet → fetch */
+      }
+    }
+
+    // Touch the stamp BEFORE spawning so concurrent hooks don't stampede.
+    try {
+      mkdirSync(presenceDir(coordRoot), { recursive: true });
+      if (existsSync(stamp)) {
+        const now = new Date();
+        utimesSync(stamp, now, now);
+      } else {
+        writeFileSync(stamp, "", "utf8");
+      }
+    } catch {
+      /* best-effort */
+    }
+
+    const r = fetchPresenceRefs(coordRoot, { sync: opts.sync });
+    if (!r.ok) return { status: "error", error: r.error ?? "fetch failed" };
+    return { status: "fetched" };
+  } catch (e) {
+    return { status: "error", error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+export interface RemoteMachine {
+  machine: string;
+  published_at: string;
+  age_secs: number;
+  agents: PresenceAgent[];
+}
+
+/**
+ * Render-ready view of every OTHER machine's presence, merged from BOTH
+ * transports: the locally-fetched git refs (the floor) and the relay
+ * daemon's cache files at `.harnery/presence/remote/` (the live upgrade).
+ * Freshest source per machine wins. Self machine excluded; blobs older than
+ * the stale window or with zero agents dropped.
+ */
+export function readRemoteMachines(
+  coordRoot: string,
+  opts: { includeSelf?: boolean; includeStale?: boolean } = {},
+): RemoteMachine[] {
+  try {
+    if (!presenceEnabled(coordRoot)) return [];
+    const selfMachine = sanitizeRefComponent(resolveMachineLabel());
+
+    // Collect candidate blobs from both transports, freshest per machine.
+    const byMachine = new Map<string, PresenceBlob>();
+    const consider = (machine: string, blob: PresenceBlob | null): void => {
+      if (blob?.v !== 1 || !Array.isArray(blob.agents)) return;
+      const publishedMs = Date.parse(blob.published_at ?? "");
+      if (!Number.isFinite(publishedMs)) return;
+      const prev = byMachine.get(machine);
+      if (prev && Date.parse(prev.published_at) >= publishedMs) return;
+      byMachine.set(machine, blob);
+    };
+    for (const { machine, message } of readPresenceRefs(coordRoot)) {
+      try {
+        consider(machine, JSON.parse(message) as PresenceBlob);
+      } catch {
+        /* skip malformed */
+      }
+    }
+    const relayDir = join(coordRoot, ".harnery", "presence", "remote");
+    if (existsSync(relayDir)) {
+      for (const f of readdirSync(relayDir)) {
+        if (!f.endsWith(".json")) continue;
+        try {
+          consider(
+            f.replace(/\.json$/, ""),
+            JSON.parse(readFileSync(join(relayDir, f), "utf8")) as PresenceBlob,
+          );
+        } catch {
+          /* skip malformed */
+        }
+      }
+    }
+
+    const out: RemoteMachine[] = [];
+    for (const [machine, blob] of byMachine) {
+      if (!opts.includeSelf && machine === selfMachine) continue;
+      const ageSecs = Math.max(0, Math.floor((Date.now() - Date.parse(blob.published_at)) / 1000));
+      if (!opts.includeStale && ageSecs > REMOTE_STALE_SECS) continue;
+      if (blob.agents.length === 0) continue;
+      out.push({
+        machine,
+        published_at: blob.published_at,
+        age_secs: ageSecs,
+        agents: blob.agents,
+      });
+    }
+    out.sort((a, b) => a.machine.localeCompare(b.machine));
+    return out;
+  } catch {
+    return [];
+  }
+}