harnery 0.9.0 → 0.10.0

package/dist/core/presence/blob.js

@@ -0,0 +1,91 @@
+/**
+ * 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.js";
+/** 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;
+/**
+ * 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, now = new Date()) {
+    const machine = resolveMachineLabel();
+    const agents = [];
+    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;
+            try {
+                hb = JSON.parse(readFileSync(join(activeDir, f), "utf8"));
+            }
+            catch {
+                continue;
+            }
+            if (typeof hb.instance_id !== "string")
+                continue;
+            if (hb.kind === "transient")
+                continue;
+            const ts = Date.parse(hb.last_heartbeat ?? "");
+            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.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 = {
+        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) {
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function clamp(v, max) {
+    if (!v)
+        return undefined;
+    return v.length > max ? v.slice(0, max) : v;
+}

package/dist/core/presence/git.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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).
+ */
+/** The ref namespace. Hardcoded — never interpolated from config — so the
+ * publisher is structurally unable to touch refs/heads/* (ADR 0016). */
+export declare const PRESENCE_REF_PREFIX = "refs/harnery/presence/";
+/** Does the repo have an `origin` remote to rendezvous on? */
+export declare function hasOrigin(root: string): boolean;
+/** The origin remote URL, or null. Input to relay room derivation. */
+export declare function originUrl(root: string): string | 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 declare function rootCommitSha(root: string): string | 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 declare function sanitizeRefComponent(label: string): string;
+/** Build the parentless presence commit carrying `message` (the JSON blob).
+ * Returns the commit sha, or null on failure. Local-only, fast (~10ms). */
+export declare function writePresenceCommit(root: string, message: string): string | 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 declare function pushPresenceRef(root: string, machine: string, sha: string, opts?: {
+    sync?: boolean;
+}): {
+    ok: boolean;
+    error?: string;
+};
+/** Fetch every peer presence ref from origin into the local ref namespace. */
+export declare function fetchPresenceRefs(root: string, opts?: {
+    sync?: boolean;
+}): {
+    ok: boolean;
+    error?: string;
+};
+/** Read every locally-known presence ref → [{ref, machine, message}]. */
+export declare function readPresenceRefs(root: string): Array<{
+    machine: string;
+    message: string;
+}>;
+/**
+ * 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 declare function parseForEachRefOutput(out: string): Array<{
+    machine: string;
+    message: string;
+}>;
+//# sourceMappingURL=git.d.ts.map

package/dist/core/presence/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../../src/core/presence/git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;wEACwE;AACxE,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAwC5D,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIrD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASzD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS1D;AAED;2EAC2E;AAC3E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOhF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5B;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAcjC;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5B;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAcjC;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAQ1F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAe9F"}

package/dist/core/presence/git.js

@@ -0,0 +1,173 @@
+/**
+ * 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() {
+    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, args, input) {
+    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) {
+    return runGit(root, ["remote", "get-url", "origin"]).ok;
+}
+/** The origin remote URL, or null. Input to relay room derivation. */
+export function originUrl(root) {
+    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) {
+    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) {
+    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, message) {
+    // 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, machine, sha, opts = {}) {
+    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, opts = {}) {
+    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) {
+    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) {
+    const rows = [];
+    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/dist/core/presence/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 { type PresenceAgent } from "./blob.js";
+export type { PresenceAgent, PresenceBlob } from "./blob.js";
+export { buildPresenceBlob } from "./blob.js";
+export { PRESENCE_REF_PREFIX, parseForEachRefOutput, sanitizeRefComponent } from "./git.js";
+export { ensureRelayDaemon, relayDaemonStatus, runRelayDaemon } from "./relay-client.js";
+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;
+};
+/**
+ * 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 declare function publishPresence(coordRoot: string, opts?: {
+    force?: boolean;
+    sync?: boolean;
+}): PublishResult;
+/** Throttled fetch of peer presence refs from origin. */
+export declare function fetchPresence(coordRoot: string, opts?: {
+    force?: boolean;
+    sync?: boolean;
+}): FetchResult;
+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 declare function readRemoteMachines(coordRoot: string, opts?: {
+    includeSelf?: boolean;
+    includeStale?: boolean;
+}): RemoteMachine[];
+//# sourceMappingURL=index.d.ts.map

package/dist/core/presence/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/presence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAgBH,OAAO,EAAqB,KAAK,aAAa,EAAqB,MAAM,WAAW,CAAC;AAUrF,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAYzF,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACrE;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,MAAM,MAAM,WAAW,GACnB;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAwCvC;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7C,aAAa,CA2Cf;AAED,yDAAyD;AACzD,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7C,WAAW,CAsCb;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3D,aAAa,EAAE,CAuDjB"}

package/dist/core/presence/index.js

@@ -0,0 +1,224 @@
+/**
+ * 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.js";
+import { resolveMachineLabel } from "../../lib/machine.js";
+import { presenceEnabled } from "../config.js";
+import { buildPresenceBlob } from "./blob.js";
+import { fetchPresenceRefs, hasOrigin, pushPresenceRef, readPresenceRefs, sanitizeRefComponent, writePresenceCommit, } from "./git.js";
+export { buildPresenceBlob } from "./blob.js";
+export { PRESENCE_REF_PREFIX, parseForEachRefOutput, sanitizeRefComponent } from "./git.js";
+export { ensureRelayDaemon, relayDaemonStatus, runRelayDaemon } from "./relay-client.js";
+/** 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;
+function presenceDir(coordRoot) {
+    return join(coordRoot, ".harnery", "presence");
+}
+function statePath(coordRoot) {
+    return join(presenceDir(coordRoot), "publish-state.json");
+}
+function fetchStampPath(coordRoot) {
+    return join(presenceDir(coordRoot), "fetch-stamp");
+}
+function readState(coordRoot) {
+    try {
+        return JSON.parse(readFileSync(statePath(coordRoot), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeState(coordRoot, state) {
+    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, opts = {}) {
+    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, opts = {}) {
+    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) };
+    }
+}
+/**
+ * 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, opts = {}) {
+    try {
+        if (!presenceEnabled(coordRoot))
+            return [];
+        const selfMachine = sanitizeRefComponent(resolveMachineLabel());
+        // Collect candidate blobs from both transports, freshest per machine.
+        const byMachine = new Map();
+        const consider = (machine, blob) => {
+            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));
+            }
+            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")));
+                }
+                catch {
+                    /* skip malformed */
+                }
+            }
+        }
+        const out = [];
+        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 [];
+    }
+}

package/dist/core/presence/relay-client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Relay client transport for cross-machine presence (ADR 0016, phase 2c).
+ *
+ * The hooks are short-lived processes, so a live WebSocket needs a home: a
+ * small per-repo-per-machine DAEMON that the hooks lazy-start
+ * (`ensureRelayDaemon`) and that exits itself when the machine goes idle.
+ * The daemon:
+ *
+ *   - derives the room credentials from the repo identity (root-commit SHA +
+ *     origin URL + optional committed `.harnery/presence-salt`)
+ *   - holds the socket open with auto-reconnect + jittered backoff
+ *   - watches `.harnery/active/` and publishes the encrypted presence blob on
+ *     change (debounced), plus a 60s keepalive so peers' staleness math works
+ *   - decrypts received peer frames and writes them to
+ *     `.harnery/presence/remote/<machine>.json`, where `readRemoteMachines`
+ *     merges them with the git-refs floor (freshest source per machine wins)
+ *   - exits after ~5 minutes with no live local sessions (hooks restart it
+ *     when sessions return), and exits if its pid file is superseded
+ *
+ * Everything fails silent; the git-refs transport is always the floor.
+ * Requires a global WebSocket (Bun, Node >= 21, Workers) — on older Nodes the
+ * daemon refuses to start and presence stays on git-refs.
+ */
+/**
+ * Lazy-start the relay daemon for this repo if a relay is configured and no
+ * live daemon already owns the pid file. Called from the hook path — must
+ * return fast and never throw.
+ */
+export declare function ensureRelayDaemon(coordRoot: string): void;
+/** Foreground daemon loop (spawned detached by ensureRelayDaemon). */
+export declare function runRelayDaemon(coordRoot: string): Promise<number>;
+/** Daemon status for `presence peers`/doctor surfaces. */
+export declare function relayDaemonStatus(coordRoot: string): {
+    running: boolean;
+    pid?: number;
+    url?: string;
+    started_at?: string;
+};
+//# sourceMappingURL=relay-client.d.ts.map