harnery 0.8.0 → 0.10.0

package/dist/core/agents/state/pidmap.js

@@ -1,5 +1,5 @@
 /**
- * Pid-map writer.
+ * Pid-map writer + liveness helpers.
  *
  * Per-harness pid-map at `.harnery/pid-map/<pid>` containing
  * `<instance_id>\t<platform>`. `harn agents whoami` walks ppid up 20 hops looking
@@ -7,7 +7,7 @@
  *
  * Atomic temp+rename. Idempotent: re-writing the same row is a no-op.
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 function atomicWrite(path, content) {
     mkdirSync(dirname(path), { recursive: true });
@@ -30,3 +30,59 @@ export function writePidmapRow(coordRoot, pid, instanceId, platform) {
     }
     atomicWrite(path, row);
 }
+/** True when any pid-map row for `instanceId` still belongs to a live process. */
+export function instanceHasLivePid(coordRoot, instanceId) {
+    const dir = join(coordRoot, ".harnery", "pid-map");
+    if (!existsSync(dir))
+        return false;
+    for (const f of readdirSync(dir)) {
+        let row = "";
+        try {
+            row = readFileSync(join(dir, f), "utf8").trim();
+        }
+        catch {
+            continue;
+        }
+        const owner = row.split("\t")[0]?.trim() ?? "";
+        if (owner !== instanceId)
+            continue;
+        const pid = Number.parseInt(f, 10);
+        if (!Number.isFinite(pid))
+            continue;
+        try {
+            process.kill(pid, 0); // signal 0 = liveness probe
+            return true;
+        }
+        catch {
+            // ESRCH (no such process): pid-map entry is stale, keep scanning
+        }
+    }
+    return false;
+}
+/** Drop every pid-map row owned by `instanceId`. Returns how many files were removed. */
+export function removePidmapRowsForInstance(coordRoot, instanceId) {
+    const dir = join(coordRoot, ".harnery", "pid-map");
+    if (!existsSync(dir))
+        return 0;
+    let removed = 0;
+    for (const f of readdirSync(dir)) {
+        let row = "";
+        try {
+            row = readFileSync(join(dir, f), "utf8").trim();
+        }
+        catch {
+            continue;
+        }
+        const owner = row.split("\t")[0]?.trim() ?? "";
+        if (owner !== instanceId)
+            continue;
+        try {
+            unlinkSync(join(dir, f));
+            removed += 1;
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+    }
+    return removed;
+}

package/dist/core/agents/state/stale-sweep.d.ts

@@ -5,8 +5,9 @@
  * Fires at session.start to clean up crashed-peer detritus before the new
  * session's UX layer reads peer state.
  *
- * Freshness threshold defaults to 600s; configurable via
- * HARNERY_AGENT_COORD_FRESHNESS env var.
+ * Freshness threshold defaults to 600s; configurable via the
+ * HARNERY_AGENT_COORD_FRESHNESS env var or `.harnery/config.jsonc`
+ * `coord.freshness_seconds` (see `coordFreshnessSeconds`).
  */
 export declare function staleSweep(coordRoot: string): {
     heartbeatsRemoved: string[];

package/dist/core/agents/state/stale-sweep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stale-sweep.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/stale-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAiDH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG;IAC7C,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CA+HA"}
+{"version":3,"file":"stale-sweep.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/stale-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA+CH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG;IAC7C,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CA2HA"}

package/dist/core/agents/state/stale-sweep.js

@@ -5,14 +5,14 @@
  * Fires at session.start to clean up crashed-peer detritus before the new
  * session's UX layer reads peer state.
  *
- * Freshness threshold defaults to 600s; configurable via
- * HARNERY_AGENT_COORD_FRESHNESS env var.
+ * Freshness threshold defaults to 600s; configurable via the
+ * HARNERY_AGENT_COORD_FRESHNESS env var or `.harnery/config.jsonc`
+ * `coord.freshness_seconds` (see `coordFreshnessSeconds`).
  */
 import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { coordEnv } from "../../../lib/env.js";
+import { coordFreshnessSeconds } from "../../config.js";
 import { emit } from "../events/emit.js";
-const DEFAULT_FRESHNESS_SECS = 600;
 /** platform → harness, for the swept-event envelope (mirrors heartbeat-writer's harnessOf). */
 function harnessFromPlatform(platform) {
     if (platform === "cursor")
@@ -51,9 +51,9 @@ export function staleSweep(coordRoot) {
     const heartbeatsRemoved = [];
     let pidmapsRemoved = 0;
     let peerHashesRemoved = 0;
-    const freshness = Number.parseInt(coordEnv("AGENT_COORD_FRESHNESS") ?? String(DEFAULT_FRESHNESS_SECS), 10);
+    const freshness = coordFreshnessSeconds(coordRoot);
     const nowSec = Math.floor(Date.now() / 1000);
-    const cutoff = nowSec - (Number.isFinite(freshness) && freshness > 0 ? freshness : DEFAULT_FRESHNESS_SECS);
+    const cutoff = nowSec - freshness;
     // 1. Prune stale heartbeats from the canonical `.harnery/active/` dir.
     //
     // Two deletion regimes, deliberately asymmetric:

package/dist/core/config.d.ts

@@ -1,20 +1,25 @@
 /**
- * `.harnery/config.jsonc` reader: the host-project config the coord/hook layer
- * consults when it can't see the consumer CLI's own process.
+ * Harnery config reader: the settings the coord/hook layer consults when it
+ * can't see the consumer CLI's own process.
  *
- * The single field this module owns today is `binName`: the host CLI's binary
- * name (e.g. `myapp`), used in user-facing strings the agent reads and runs:
- * council prompts, end-of-turn nudges, command help/errors. The coord binaries
- * (`agent-hook`, `agent-coord`) and the web UI run as harnery itself, so they
- * have no other way to learn the consumer's bin name; `harn init` stamps it here
- * for them to read back. The `files` deny/override section is parsed separately
- * by `web/lib/files.ts`.
+ * Two layers, project-over-user (project wins field-by-field):
+ *   1. `~/.config/harnery/config.jsonc` — user-global base (optional)
+ *   2. `<project-root>/.harnery/config.jsonc` — project override (authoritative)
  *
- * Dependency-free (no jsonc npm dep) so it runs on both Bun and Node, and so the
- * ADR-009 vendored copies stay portable.
+ * Fields owned here: `binName` (host CLI name for agent-facing strings),
+ * `hooksSetupHint`, `tools`, `workflow`, `skills`, `presence`, plus the tunable
+ * `coord` (heartbeat freshness), `backup` (restic repo/password/prune policy),
+ * and `sync` (rclone remote/prefix) sections. The `files` deny/override section
+ * is parsed separately by `web/lib/files.ts`.
+ *
+ * Env vars and CLI flags override any config value per invocation (each accessor
+ * documents its own precedence). Dependency-free (no jsonc npm dep) so it runs on
+ * both Bun and Node, and so the ADR-009 vendored copies stay portable.
  */
 /** The standalone CLI's bin name: the resolution floor when nothing else is set. */
 export declare const DEFAULT_BIN_NAME = "harn";
+/** Heartbeat-freshness default (seconds): the sweep window when nothing overrides it. */
+export declare const DEFAULT_FRESHNESS_SECS = 600;
 /** Strip `//` and `/* *​/` comments from JSONC, ignoring comment-like runs inside strings. */
 export declare function stripJsonComments(input: string): string;
 /**
@@ -52,4 +57,65 @@ export declare function resolveHooksSetupHint(coordRoot?: string | null): string
  * `coordRoot` is resolved via `findCoordRoot()` when not passed.
  */
 export declare function ripgrepAutoInstall(coordRoot?: string | null): boolean;
+/**
+ * Whether this repo pins workflow runs to subscription billing:
+ * `.harnery/config.jsonc` `{ "workflow": { "subscriptionOnly": true } }`.
+ * The `workflow run --subscription-only` flag turns it on per invocation;
+ * `HARNERY_WORKFLOW_SUBSCRIPTION_ONLY=1|0` overrides per process (the `0`
+ * escape hatch exists for a key-only CI job inside a pinned repo).
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export declare function workflowSubscriptionOnly(coordRoot?: string | null): boolean;
+/**
+ * Whether cross-machine presence (ADR 0016) is enabled for this repo.
+ * Default ON — the transport itself additionally gates on an origin remote
+ * existing and fails silent everywhere. Opt out via
+ * `.harnery/config.jsonc` `{ "presence": { "enabled": false } }`;
+ * `HARNERY_PRESENCE=1|0` overrides per process.
+ */
+export declare function presenceEnabled(coordRoot?: string | null): boolean;
+/**
+ * The presence relay URL for this repo, or null when the relay transport is
+ * not configured (git-refs only). `HARNERY_PRESENCE_RELAY` overrides per
+ * process (empty string or "0" disables). Requires `presenceEnabled()` to be
+ * true — a disabled presence section disables the relay too.
+ */
+export declare function presenceRelayUrl(coordRoot?: string | null): string | null;
+/**
+ * The heartbeat-freshness window (seconds): the age above which the sweeper
+ * prunes an agent, and the cutoff the `agents` surface uses to fold stale peers.
+ * Precedence:
+ *   1. `HARNERY_AGENT_COORD_FRESHNESS` env (canonical), or `HARNERY_AGENT_FRESHNESS` (legacy alias)
+ *   2. `.harnery/config.jsonc` `coord.freshness_seconds`
+ *   3. `600` (10 minutes)
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export declare function coordFreshnessSeconds(coordRoot?: string | null): number;
+/** Resolved `harn backup` defaults (restic repo/password + prune policy). */
+export interface BackupConfig {
+    repo: string;
+    passwordFile: string;
+    keepDaily: number;
+    keepWeekly: number;
+    keepMonthly: number;
+}
+/**
+ * `harn backup` (restic) defaults. Per field, precedence is env → config → built-in:
+ *   repo:          `HARNERY_RESTIC_REPO` → `backup.repo` → `~/.cache/harnery/restic-repo`
+ *   passwordFile:  `HARNERY_RESTIC_PASSWORD_FILE` → `backup.password_file` → `~/.config/harnery/restic-password`
+ *   keepDaily/Weekly/Monthly: `backup.keep_*` → 7 / 4 / 6
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export declare function backupConfig(coordRoot?: string | null): BackupConfig;
+/**
+ * `harn sync` (rclone) remote/prefix from `.harnery/config.jsonc` `sync`, or null
+ * when unset. This is the config-file layer only; `harn sync` consults env
+ * (`HARNERY_SYNC_REMOTE`/`_PREFIX`) first and the `~/.config/harnery/sync.json`
+ * file (written by `harn sync init`) as a lower-precedence fallback.
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export declare function syncJsoncConfig(coordRoot?: string | null): {
+    remote: string;
+    prefix: string;
+} | null;
 //# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAuBvC,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqCvD;AAyBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAShE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAK9E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAOrE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAQH,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAEvC,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAiE1C,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqCvD;AAwFD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAShE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAK9E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAOrE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAO3E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAOlE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAWzE;AAQD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CASvE;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,YAAY,CAmBpE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GACxB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAS3C"}

package/dist/core/config.js

@@ -1,24 +1,30 @@
 /**
- * `.harnery/config.jsonc` reader: the host-project config the coord/hook layer
- * consults when it can't see the consumer CLI's own process.
+ * Harnery config reader: the settings the coord/hook layer consults when it
+ * can't see the consumer CLI's own process.
  *
- * The single field this module owns today is `binName`: the host CLI's binary
- * name (e.g. `myapp`), used in user-facing strings the agent reads and runs:
- * council prompts, end-of-turn nudges, command help/errors. The coord binaries
- * (`agent-hook`, `agent-coord`) and the web UI run as harnery itself, so they
- * have no other way to learn the consumer's bin name; `harn init` stamps it here
- * for them to read back. The `files` deny/override section is parsed separately
- * by `web/lib/files.ts`.
+ * Two layers, project-over-user (project wins field-by-field):
+ *   1. `~/.config/harnery/config.jsonc` — user-global base (optional)
+ *   2. `<project-root>/.harnery/config.jsonc` — project override (authoritative)
  *
- * Dependency-free (no jsonc npm dep) so it runs on both Bun and Node, and so the
- * ADR-009 vendored copies stay portable.
+ * Fields owned here: `binName` (host CLI name for agent-facing strings),
+ * `hooksSetupHint`, `tools`, `workflow`, `skills`, `presence`, plus the tunable
+ * `coord` (heartbeat freshness), `backup` (restic repo/password/prune policy),
+ * and `sync` (rclone remote/prefix) sections. The `files` deny/override section
+ * is parsed separately by `web/lib/files.ts`.
+ *
+ * Env vars and CLI flags override any config value per invocation (each accessor
+ * documents its own precedence). Dependency-free (no jsonc npm dep) so it runs on
+ * both Bun and Node, and so the ADR-009 vendored copies stay portable.
  */
 import { readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { coordEnv } from "../lib/env.js";
 import { findCoordRoot } from "./hooks/resolve/coord-root.js";
 /** The standalone CLI's bin name: the resolution floor when nothing else is set. */
 export const DEFAULT_BIN_NAME = "harn";
+/** Heartbeat-freshness default (seconds): the sweep window when nothing overrides it. */
+export const DEFAULT_FRESHNESS_SECS = 600;
 /** Strip `//` and `/* *​/` comments from JSONC, ignoring comment-like runs inside strings. */
 export function stripJsonComments(input) {
     let out = "";
@@ -61,31 +67,85 @@ export function stripJsonComments(input) {
     }
     return out;
 }
-// mtime-keyed per-process cache: a stat is cheap, a parse on every render isn't.
-let cache = null;
-function readConfig(root) {
-    const p = join(root, ".harnery", "config.jsonc");
-    let mtimeMs = -1;
+/**
+ * The user-global config file, the lower-precedence base under the project file.
+ * Honors `XDG_CONFIG_HOME` (falling back to `~/.config`) per the XDG base-dir spec.
+ */
+function userConfigPath() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    const base = xdg?.trim() ? xdg : join(homedir(), ".config");
+    return join(base, "harnery", "config.jsonc");
+}
+/** File mtime in ms, or -1 when the file can't be stat'd (missing). */
+function statMtime(p) {
     try {
-        mtimeMs = statSync(p).mtimeMs;
+        return statSync(p).mtimeMs;
     }
     catch {
-        /* missing → -1; cache still valid until the file appears */
+        return -1;
     }
-    if (cache && cache.root === root && cache.mtimeMs === mtimeMs)
-        return cache.cfg;
-    let cfg = {};
+}
+/** Parse one JSONC config file to an object; missing/unparseable → `{}`. */
+function parseConfigFile(p) {
     try {
         const parsed = JSON.parse(stripJsonComments(readFileSync(p, "utf8")));
         if (parsed && typeof parsed === "object")
-            cfg = parsed;
+            return parsed;
     }
     catch {
-        /* missing or unparseable → defaults (the files-section resolver fails loud; bin name is non-critical) */
+        /* missing or unparseable → defaults (files-section resolver fails loud; the rest is non-critical) */
+    }
+    return {};
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Deep-merge `override` onto `base` (override wins), recursing into plain
+ * objects only so a project that sets just `web.port` doesn't wipe a
+ * user-global `web.bind`. Arrays + scalars replace wholesale.
+ */
+function mergeConfig(base, override) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(override)) {
+        const prev = out[k];
+        out[k] = isPlainObject(prev) && isPlainObject(v) ? mergeConfig(prev, v) : v;
+    }
+    return out;
+}
+// mtime-keyed per-process cache (both layers): a stat is cheap, a parse on every render isn't.
+let cache = null;
+/**
+ * The effective config for `root`: user-global (`~/.config/harnery/config.jsonc`)
+ * as the base, the project file (`<root>/.harnery/config.jsonc`) merged on top.
+ * Project values win field-by-field.
+ */
+function readConfig(root) {
+    const projPath = join(root, ".harnery", "config.jsonc");
+    const userPath = userConfigPath();
+    const projMtime = statMtime(projPath);
+    const userMtime = statMtime(userPath);
+    if (cache &&
+        cache.root === root &&
+        cache.projMtime === projMtime &&
+        cache.userMtime === userMtime) {
+        return cache.cfg;
     }
-    cache = { root, mtimeMs, cfg };
+    const user = userMtime === -1 ? {} : parseConfigFile(userPath);
+    const project = projMtime === -1 ? {} : parseConfigFile(projPath);
+    const cfg = mergeConfig(user, project);
+    cache = { root, projMtime, userMtime, cfg };
     return cfg;
 }
+/**
+ * The PROJECT config file only — no user-global merge. `pinnedBinName` uses this
+ * so a user-global `binName` can never masquerade as a deliberate project pin
+ * (the pin guards committed, public surfaces; see `pinnedBinName`).
+ */
+function readProjectConfig(root) {
+    const p = join(root, ".harnery", "config.jsonc");
+    return statMtime(p) === -1 ? {} : parseConfigFile(p);
+}
 /**
  * Resolve the host CLI's bin name for user-facing strings. Precedence:
  *   1. `HARNERY_BIN` env (explicit per-process override)
@@ -116,7 +176,7 @@ export function resolveBinName(coordRoot) {
  * CLI would otherwise stamp the host's name into public, committed surfaces).
  */
 export function pinnedBinName(projectRoot) {
-    const binName = readConfig(projectRoot).binName;
+    const binName = readProjectConfig(projectRoot).binName;
     return typeof binName === "string" && binName.trim() ? binName.trim() : null;
 }
 /**
@@ -151,3 +211,128 @@ export function ripgrepAutoInstall(coordRoot) {
         return false;
     return readConfig(root).tools?.ripgrep?.autoInstall === true;
 }
+/**
+ * Whether this repo pins workflow runs to subscription billing:
+ * `.harnery/config.jsonc` `{ "workflow": { "subscriptionOnly": true } }`.
+ * The `workflow run --subscription-only` flag turns it on per invocation;
+ * `HARNERY_WORKFLOW_SUBSCRIPTION_ONLY=1|0` overrides per process (the `0`
+ * escape hatch exists for a key-only CI job inside a pinned repo).
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export function workflowSubscriptionOnly(coordRoot) {
+    const env = coordEnv("WORKFLOW_SUBSCRIPTION_ONLY");
+    if (env === "1")
+        return true;
+    if (env === "0")
+        return false;
+    const root = coordRoot ?? findCoordRoot();
+    if (!root)
+        return false;
+    return readConfig(root).workflow?.subscriptionOnly === true;
+}
+/**
+ * Whether cross-machine presence (ADR 0016) is enabled for this repo.
+ * Default ON — the transport itself additionally gates on an origin remote
+ * existing and fails silent everywhere. Opt out via
+ * `.harnery/config.jsonc` `{ "presence": { "enabled": false } }`;
+ * `HARNERY_PRESENCE=1|0` overrides per process.
+ */
+export function presenceEnabled(coordRoot) {
+    const env = coordEnv("PRESENCE");
+    if (env === "1")
+        return true;
+    if (env === "0")
+        return false;
+    const root = coordRoot ?? findCoordRoot();
+    if (!root)
+        return false;
+    return readConfig(root).presence?.enabled !== false;
+}
+/**
+ * The presence relay URL for this repo, or null when the relay transport is
+ * not configured (git-refs only). `HARNERY_PRESENCE_RELAY` overrides per
+ * process (empty string or "0" disables). Requires `presenceEnabled()` to be
+ * true — a disabled presence section disables the relay too.
+ */
+export function presenceRelayUrl(coordRoot) {
+    const root = coordRoot ?? findCoordRoot();
+    if (!presenceEnabled(root))
+        return null;
+    const env = coordEnv("PRESENCE_RELAY");
+    if (env !== undefined && env !== null) {
+        const t = env.trim();
+        return t && t !== "0" ? t : null;
+    }
+    if (!root)
+        return null;
+    const relay = readConfig(root).presence?.relay;
+    return typeof relay === "string" && relay.trim() ? relay.trim() : null;
+}
+/** A positive integer from `v`, else `fallback`. Floors non-integer numbers. */
+function posIntOr(v, fallback) {
+    const n = typeof v === "number" ? v : Number.NaN;
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+/**
+ * The heartbeat-freshness window (seconds): the age above which the sweeper
+ * prunes an agent, and the cutoff the `agents` surface uses to fold stale peers.
+ * Precedence:
+ *   1. `HARNERY_AGENT_COORD_FRESHNESS` env (canonical), or `HARNERY_AGENT_FRESHNESS` (legacy alias)
+ *   2. `.harnery/config.jsonc` `coord.freshness_seconds`
+ *   3. `600` (10 minutes)
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export function coordFreshnessSeconds(coordRoot) {
+    const env = coordEnv("AGENT_COORD_FRESHNESS") ?? coordEnv("AGENT_FRESHNESS");
+    if (env !== undefined) {
+        const n = Number.parseInt(env, 10);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    const root = coordRoot ?? findCoordRoot();
+    if (root)
+        return posIntOr(readConfig(root).coord?.freshness_seconds, DEFAULT_FRESHNESS_SECS);
+    return DEFAULT_FRESHNESS_SECS;
+}
+/**
+ * `harn backup` (restic) defaults. Per field, precedence is env → config → built-in:
+ *   repo:          `HARNERY_RESTIC_REPO` → `backup.repo` → `~/.cache/harnery/restic-repo`
+ *   passwordFile:  `HARNERY_RESTIC_PASSWORD_FILE` → `backup.password_file` → `~/.config/harnery/restic-password`
+ *   keepDaily/Weekly/Monthly: `backup.keep_*` → 7 / 4 / 6
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export function backupConfig(coordRoot) {
+    const home = homedir();
+    const root = coordRoot ?? findCoordRoot();
+    const b = root ? (readConfig(root).backup ?? {}) : {};
+    const cfgStr = (v) => typeof v === "string" && v.trim() ? v.trim() : undefined;
+    const repo = coordEnv("RESTIC_REPO") ?? cfgStr(b.repo) ?? join(home, ".cache", "harnery", "restic-repo");
+    const passwordFile = coordEnv("RESTIC_PASSWORD_FILE") ??
+        cfgStr(b.password_file) ??
+        join(home, ".config", "harnery", "restic-password");
+    return {
+        repo,
+        passwordFile,
+        keepDaily: posIntOr(b.keep_daily, 7),
+        keepWeekly: posIntOr(b.keep_weekly, 4),
+        keepMonthly: posIntOr(b.keep_monthly, 6),
+    };
+}
+/**
+ * `harn sync` (rclone) remote/prefix from `.harnery/config.jsonc` `sync`, or null
+ * when unset. This is the config-file layer only; `harn sync` consults env
+ * (`HARNERY_SYNC_REMOTE`/`_PREFIX`) first and the `~/.config/harnery/sync.json`
+ * file (written by `harn sync init`) as a lower-precedence fallback.
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export function syncJsoncConfig(coordRoot) {
+    const root = coordRoot ?? findCoordRoot();
+    if (!root)
+        return null;
+    const s = readConfig(root).sync ?? {};
+    if (typeof s.remote === "string" && s.remote.trim()) {
+        const prefix = typeof s.prefix === "string" && s.prefix.trim() ? s.prefix.trim() : "harnery";
+        return { remote: s.remote.trim(), prefix };
+    }
+    return null;
+}

package/dist/core/context/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Context continuity: durable, structured state around native harness
+ * compaction. Harnery does not decide when a harness compacts. It records
+ * context telemetry when the harness exposes it, checkpoints external work
+ * state before compaction, and renders a verified recovery briefing after it.
+ */
+import type { Harness } from "../hooks/events/schema.js";
+export declare const CONTEXT_SCHEMA_VERSION: 1;
+export declare const MAX_CAPSULE_BYTES: number;
+export type ContextSampleSource = "hook" | "native_event" | "result" | "transcript" | "estimate";
+export type ContextSampleConfidence = "exact" | "reported" | "estimated";
+export type ContextPhase = "observing" | "checkpointed" | "recovered" | "degraded";
+export type CheckpointReason = "manual" | "pressure" | "pre_compact" | "session_end";
+export interface ContextSample {
+    session_id: string;
+    harness: Harness;
+    model?: string;
+    used_tokens?: number;
+    window_tokens?: number;
+    used_percent?: number;
+    source: ContextSampleSource;
+    confidence: ContextSampleConfidence;
+    observed_at: string;
+}
+export interface ContextContinuityState {
+    schema_version: typeof CONTEXT_SCHEMA_VERSION;
+    session_id: string;
+    instance_id: string;
+    phase: ContextPhase;
+    generation: number;
+    latest_capsule?: string;
+    latest_context?: ContextSample;
+    updated_at: string;
+    recovered_at?: string;
+    compaction_completed_at?: string;
+    degraded_reason?: string;
+}
+export interface RepoSnapshot {
+    cwd: string;
+    root?: string;
+    branch?: string;
+    head?: string;
+    dirty_paths: string[];
+    dirty_paths_truncated?: boolean;
+}
+export interface ContinuityCapsule {
+    schema_version: typeof CONTEXT_SCHEMA_VERSION;
+    capsule_id: string;
+    generation: number;
+    created_at: string;
+    reason: CheckpointReason;
+    session: {
+        session_id: string;
+        instance_id: string;
+        harness: Harness;
+        model?: string;
+    };
+    context?: ContextSample;
+    work: {
+        task?: string;
+        turn_summary?: string;
+        continuation_note?: string;
+        files_held: string[];
+        files_held_truncated?: boolean;
+        last_tool?: string;
+        last_tool_target?: string;
+    };
+    repo: RepoSnapshot;
+}
+export interface ExtractContextSampleOptions {
+    sessionId: string;
+    harness: Harness;
+    model?: string;
+    source?: ContextSampleSource;
+    confidence?: ContextSampleConfidence;
+    observedAt?: string;
+}
+export interface CheckpointContextInput {
+    sessionId: string;
+    instanceId: string;
+    harness: Harness;
+    cwd: string;
+    reason: CheckpointReason;
+    model?: string;
+    continuationNote?: string;
+}
+export interface CheckpointContextResult {
+    capsule: ContinuityCapsule;
+    path: string;
+    state: ContextContinuityState;
+    reused: boolean;
+}
+export interface RecoverContextResult {
+    state: ContextContinuityState;
+    capsule: ContinuityCapsule | null;
+    briefing: string;
+    recovered: boolean;
+}
+export interface PreparedContextRecovery {
+    state: ContextContinuityState;
+    capsule: ContinuityCapsule;
+    briefing: string;
+}
+/** Parse the context-window shapes exposed by current harness hook/status data. */
+export declare function extractContextSample(payload: Record<string, unknown>, options: ExtractContextSampleOptions): ContextSample | null;
+/** Persist a latest context sample. Identical measurements are a no-op. */
+export declare function recordContextSample(coordRoot: string, instanceId: string, sample: ContextSample): {
+    state: ContextContinuityState;
+    changed: boolean;
+};
+/**
+ * Snapshot external work state. Repeated PreCompact events reuse the existing
+ * checkpoint until a matching recovery completes; manual checkpoints always
+ * create a new generation.
+ */
+export declare function checkpointContext(coordRoot: string, input: CheckpointContextInput): CheckpointContextResult;
+/** Prepare a briefing without claiming that a harness has accepted it yet. */
+export declare function prepareContextRecovery(coordRoot: string, input: {
+    sessionId: string;
+    instanceId: string;
+    cwd: string;
+}): PreparedContextRecovery | null;
+/** Advance continuity only after the harness context channel accepted the briefing. */
+export declare function completeContextRecovery(coordRoot: string, input: {
+    sessionId: string;
+    instanceId: string;
+}): ContextContinuityState;
+/** Record that the harness, rather than Harnery, reported compaction complete. */
+export declare function markContextCompactionCompleted(coordRoot: string, input: {
+    sessionId: string;
+    instanceId: string;
+    observedAt?: string;
+}): ContextContinuityState;
+/** Convenience API for callers whose injection is synchronous and guaranteed. */
+export declare function recoverContext(coordRoot: string, input: {
+    sessionId: string;
+    instanceId: string;
+    cwd: string;
+}): RecoverContextResult;
+export declare function readContextState(coordRoot: string, sessionId: string): ContextContinuityState | null;
+export declare function readLatestCapsule(coordRoot: string, sessionId: string): ContinuityCapsule | null;
+export declare function renderRecoveryBriefing(capsule: ContinuityCapsule, liveRepo: RepoSnapshot): string;
+export declare function snapshotRepo(cwd: string): RepoSnapshot;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/context/index.ts"],"names":[],"mappings":"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"}