harnery 0.8.0 → 0.10.0

package/dist/core/hooks/harness/events.js

@@ -20,6 +20,7 @@ export const CLAUDE_CODE_EVENTS = [
     { settingsKey: "PreToolUse", subcommand: "pre-tool-use" },
     { settingsKey: "PostToolUse", subcommand: "post-tool-use" },
     { settingsKey: "PostToolUseFailure", subcommand: "post-tool-use-failure" },
+    { settingsKey: "PreCompact", subcommand: "pre-compact" },
 ];
 /**
  * Cursor: `.cursor/hooks.json`. camelCase event keys; flat `{ command }` entries;
@@ -45,6 +46,8 @@ export const CODEX_EVENTS = [
     { settingsKey: "UserPromptSubmit", subcommand: "user-prompt-submit" },
     { settingsKey: "SubagentStart", subcommand: "sub-agent-start" },
     { settingsKey: "SubagentStop", subcommand: "sub-agent-stop" },
+    { settingsKey: "PreCompact", subcommand: "pre-compact" },
+    { settingsKey: "PostCompact", subcommand: "post-compact" },
     { settingsKey: "Stop", subcommand: "stop" },
 ];
 /** Entries written by harnery before Codex adopted a strict native hook schema. */
@@ -72,6 +75,7 @@ export const HARNESS_SPECS = {
         settingsFile: ".claude/settings.json",
         events: CLAUDE_CODE_EVENTS,
         entryShape: "claude",
+        projectDirEnv: "CLAUDE_PROJECT_DIR",
     },
     cursor: {
         settingsFile: ".cursor/hooks.json",

package/dist/core/hooks/harness/parse.d.ts

@@ -63,5 +63,5 @@ export declare function normalizeEventName(eventName: string): {
     event_type: NormalizedEventType;
     intra_turn: boolean;
 } | null;
-export type NormalizedEventType = "session.start" | "session.end" | "user_prompt.submit" | "turn.stop" | "subagent.start" | "subagent.stop" | "tool.pre_use" | "tool.post_use" | "tool.post_use_failure";
+export type NormalizedEventType = "session.start" | "session.end" | "user_prompt.submit" | "turn.stop" | "subagent.start" | "subagent.stop" | "tool.pre_use" | "tool.post_use" | "tool.post_use_failure" | "context.compaction.started" | "context.compaction.completed";
 //# sourceMappingURL=parse.d.ts.map

package/dist/core/hooks/harness/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/harness/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,WAAW,aAAa;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAkCjF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,EAAE,OAAO,GACjB,MAAM,GAAG,SAAS,CASpB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAO7E;AAmBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,GAChB;IAAE,UAAU,EAAE,mBAAmB,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA6BjE;AAED,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,aAAa,GACb,oBAAoB,GACpB,WAAW,GACX,gBAAgB,GAChB,eAAe,GACf,cAAc,GACd,eAAe,GACf,uBAAuB,CAAC"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/harness/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,WAAW,aAAa;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAkCjF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,EAAE,OAAO,GACjB,MAAM,GAAG,SAAS,CASpB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAO7E;AAmBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,GAChB;IAAE,UAAU,EAAE,mBAAmB,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAiCjE;AAED,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,aAAa,GACb,oBAAoB,GACpB,WAAW,GACX,gBAAgB,GAChB,eAAe,GACf,cAAc,GACd,eAAe,GACf,uBAAuB,GACvB,4BAA4B,GAC5B,8BAA8B,CAAC"}

package/dist/core/hooks/harness/parse.js

@@ -126,6 +126,10 @@ export function normalizeEventName(eventName) {
             return { event_type: "tool.post_use", intra_turn: true };
         case "post-tool-use-failure":
             return { event_type: "tool.post_use_failure", intra_turn: true };
+        case "pre-compact":
+            return { event_type: "context.compaction.started", intra_turn: false };
+        case "post-compact":
+            return { event_type: "context.compaction.completed", intra_turn: false };
         default:
             return null;
     }

package/dist/core/hooks/resolve/coord-root.d.ts

@@ -1,6 +1,17 @@
 /**
  * Walk up from `start` looking for a directory containing `.harnery/`. The
  * single coord-root resolution so every adapter agrees on the same root.
+ *
+ * Resolution precedence:
+ *   1. HARNERY_COORD_ROOT_OVERRIDE — explicit pin (tests, git hooks).
+ *   2. The harness's project dir (CLAUDE_PROJECT_DIR) — hook processes
+ *      inherit the session's *shell* cwd, which follows `cd` into
+ *      subdirectories/submodules that may carry a `.harnery/` of their own
+ *      (or none at all, e.g. a scratch dir under /tmp). The session's
+ *      coordination home is the project the harness opened, not wherever the
+ *      shell happens to sit, so a project dir that resolves to a coord root
+ *      wins over the cwd walk.
+ *   3. Walk up from `start` (default cwd).
  */
 export declare function findCoordRoot(start?: string): string | null;
 //# sourceMappingURL=coord-root.d.ts.map

package/dist/core/hooks/resolve/coord-root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coord-root.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/coord-root.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAgB1E"}
+{"version":3,"file":"coord-root.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/coord-root.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAiB1E"}

package/dist/core/hooks/resolve/coord-root.js

@@ -4,17 +4,39 @@ import { coordEnv } from "../../../lib/env.js";
 /**
  * Walk up from `start` looking for a directory containing `.harnery/`. The
  * single coord-root resolution so every adapter agrees on the same root.
+ *
+ * Resolution precedence:
+ *   1. HARNERY_COORD_ROOT_OVERRIDE — explicit pin (tests, git hooks).
+ *   2. The harness's project dir (CLAUDE_PROJECT_DIR) — hook processes
+ *      inherit the session's *shell* cwd, which follows `cd` into
+ *      subdirectories/submodules that may carry a `.harnery/` of their own
+ *      (or none at all, e.g. a scratch dir under /tmp). The session's
+ *      coordination home is the project the harness opened, not wherever the
+ *      shell happens to sit, so a project dir that resolves to a coord root
+ *      wins over the cwd walk.
+ *   3. Walk up from `start` (default cwd).
  */
 export function findCoordRoot(start = process.cwd()) {
-    // HARNERY_COORD_ROOT_OVERRIDE: test-mode escape hatch matched by agent-coord
-    // and the bash side. Lets the sandboxed coord-test suite run against a
-    // temp directory rather than the real monorepo root. agent-hook's
-    // session.start handler may be the FIRST thing to create .harnery/ in a
-    // fresh sandbox, so the override is honored unconditionally (we don't
-    // require .harnery/ to pre-exist).
+    // HARNERY_COORD_ROOT_OVERRIDE: explicit pin matched by agent-coord and the
+    // bash side. Lets the sandboxed coord-test suite run against a temp
+    // directory rather than the real monorepo root. agent-hook's session.start
+    // handler may be the FIRST thing to create .harnery/ in a fresh sandbox,
+    // so the override is honored unconditionally (we don't require .harnery/
+    // to pre-exist).
     const override = coordEnv("COORD_ROOT_OVERRIDE");
     if (override)
         return override;
+    // Claude Code exports CLAUDE_PROJECT_DIR to every hook process; other
+    // harnesses don't set it, so this is inert outside claude-code hooks.
+    const projectDir = process.env.CLAUDE_PROJECT_DIR;
+    if (projectDir) {
+        const fromProject = walkUp(projectDir);
+        if (fromProject)
+            return fromProject;
+    }
+    return walkUp(start);
+}
+function walkUp(start) {
     let dir = resolve(start);
     while (true) {
         if (existsSync(join(dir, ".harnery")))

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

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+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 declare function buildPresenceBlob(coordRoot: string, now?: Date): BuiltBlob;
+//# sourceMappingURL=blob.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"blob.d.ts","sourceRoot":"","sources":["../../../src/core/presence/blob.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,CAAC,CAAC;IACL,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,YAAY,CAAC;IACnB;kEAC8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,SAAS,CA6DtF"}

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"}