@sentropic/h2a 0.85.18 → 0.85.20

package/dist/runtime/loop/supervisor.js

@@ -0,0 +1,263 @@
+/**
+ * Durable objective-loop supervisor (L1 Lot 1b).
+ *
+ * THIS is the piece that makes an h2a objective loop auto-relaunch on its own,
+ * the way `/loop` does on Claude — but server-side and host-agnostic. Each beat
+ * it takes the loops that have OPTED IN (`policy.autoTick`, Lot 1a) and, for
+ * each one it can lease as the SINGLE writer (`acquireLoopExecutorLease`, Lot 0),
+ * runs exactly one `tick + execute` of the existing engine under that lease,
+ * then releases it. It reuses the engine — it does not re-implement ticking.
+ *
+ * Safety, per the double-opus B′ consensus (tmp/L1-decision-reconciled.md):
+ *  - OPT-IN ONLY: `listAutoTickLoops` already filters to opted-in, LIVE loops;
+ *    a global kill-switch (`H2A_LOOP_AUTOTICK_OFF`) freezes every beat.
+ *  - SINGLE-WRITER (bounded): a loop is ticked only while its per-loop lease is
+ *    held, AND each tick is bounded by a lease-safety timeout that is a fraction
+ *    of the lease TTL — so a cooperative tick always completes and releases
+ *    BEFORE its lease could become stealable, and the dozen `mcp-serve`
+ *    processes on a host cannot double-tick it. A pathological tick that overruns
+ *    the timeout is ABORTED (fail-closed): the engine stops firing new
+ *    non-idempotent actions and the beat moves on. Residual limits (a single
+ *    in-flight action cannot be un-fired, and the underlying lease-release has a
+ *    known TOCTOU on overrun) are tracked follow-ups — full effect-fencing
+ *    (thread the fencing token into the sink + re-check before each action, and
+ *    make adapters cancellable) is deferred, safe under the opt-in-off default.
+ *  - FAIL-CLOSED ISOLATION: one loop throwing or timing out never aborts the
+ *    beat or the supervisor; that loop simply goes un-ticked this beat and its
+ *    heartbeat goes stale, which `loopAttendance` surfaces as `unattended`.
+ *  - HONEST ATTENDANCE: each successful tick stamps an executor heartbeat;
+ *    `loopAttendance` is a pure read-side predicate ANY reader (status/doctor)
+ *    can evaluate — an opted-in loop with no fresh heartbeat reads `unattended`
+ *    (fail-closed: missing / stale / implausibly-future ⇒ unattended), so a down
+ *    supervisor is visible even under clock skew.
+ *  - DRAINABLE: `signal` is honored BETWEEN loops within a beat and threaded
+ *    into the tick, so a SIGTERM stops launching new work promptly instead of
+ *    draining every remaining eligible loop first.
+ *
+ * Golden rule: this module must NOT statically import `@sentropic/h2a-runtime`.
+ * It imports only the loop store, the executor lease, and the engine tick (which
+ * is itself adapters-gated). Imported constants are referenced at CALL time, not
+ * aliased at module-eval, to avoid any import-cycle temporal-dead-zone.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { localStorePaths, safePathSegment } from "../local-files/paths.js";
+import { autoTickGloballyDisabled, isLoopAutoTickEligible, listAutoTickLoops } from "./index.js";
+import { acquireLoopExecutorLease } from "./executor-lease.js";
+import { runTick } from "./engine/tick.js";
+/** Default supervisor beat interval. Each eligible loop is ticked every beat. */
+export const DEFAULT_SUPERVISOR_INTERVAL_MS = 30000;
+/**
+ * Executor-lease TTL the supervisor acquires with — deliberately LARGER than the
+ * per-loop-lease default (30s) so a normal tick (which may boot an agent) fits
+ * comfortably inside it. The lease-safety timeout below is a fraction of this, so
+ * a cooperative tick always releases before the lease could be stolen.
+ */
+export const DEFAULT_SUPERVISOR_LEASE_MS = 120000;
+/**
+ * Fraction of the executor lease after which an in-flight tick is aborted
+ * (fail-closed). 0.5 leaves a full half-TTL of margin between "we gave up on this
+ * tick and released" and "the lease becomes stealable", so a cooperative tick can
+ * never overlap a successor executor.
+ */
+export const TICK_TIMEOUT_FRACTION = 0.5;
+/**
+ * How many of a loop's own `tickMs` may elapse with no executor heartbeat before
+ * an opted-in loop is judged `unattended`. K=3 tolerates a couple of missed
+ * beats (a busy host, a lease held by a slow peer) before raising the flag.
+ */
+export const DEFAULT_UNATTENDED_TICKS = 3;
+/** Fallback per-loop cadence when a loop's policy carries no `tickMs`. */
+const FALLBACK_TICK_MS = 60000;
+/** Default heartbeat/lease holder label — host + pid, so racing writers differ. */
+function defaultHolder() {
+    return `${hostname()}:${process.pid}`;
+}
+/** Absolute path of a loop's executor heartbeat file. */
+export function loopExecutorHeartbeatPath(root, loopId) {
+    return join(localStorePaths(root).root, "loops", safePathSegment(loopId), "executor.heartbeat");
+}
+/**
+ * Record that an executor just ticked `loopId`. Written after a successful tick,
+ * inside the loop's own dir (created by the lease acquisition). Best-effort: a
+ * write failure must not crash the beat, so callers wrap it — but it throws
+ * nothing on the happy path.
+ */
+export function stampExecutorHeartbeat(root, loopId, entry) {
+    const hb = {
+        at: new Date(entry.at ?? Date.now()).toISOString(),
+        holder: entry.holder,
+        fencingToken: entry.fencingToken
+    };
+    writeFileSync(loopExecutorHeartbeatPath(root, loopId), JSON.stringify(hb));
+}
+/** Read a loop's executor heartbeat, or `null` if absent/unparseable. */
+export function readExecutorHeartbeat(root, loopId) {
+    let raw;
+    try {
+        raw = readFileSync(loopExecutorHeartbeatPath(root, loopId), "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const p = JSON.parse(raw);
+        if (typeof p.at === "string" && typeof p.holder === "string" && typeof p.fencingToken === "number") {
+            return { at: p.at, holder: p.holder, fencingToken: p.fencingToken };
+        }
+    }
+    catch {
+        /* malformed — treat as absent */
+    }
+    return null;
+}
+/**
+ * Read-side, fail-closed attendance of an opted-in loop. Any reader can call
+ * this without a supervisor running:
+ *  - `not-applicable`  — the loop is not auto-tick eligible (not opted-in,
+ *                        terminal, or the kill-switch is on): nothing should tick
+ *                        it, so attendance is moot.
+ *  - `unattended`      — eligible but NO fresh executor heartbeat (missing,
+ *                        malformed, or older than K×tickMs). This is the
+ *                        fail-closed default: absence of proof ⇒ unattended, so a
+ *                        down/absent supervisor is visible.
+ *  - `attended`        — eligible and a heartbeat exists within K×tickMs.
+ */
+export function loopAttendance(root, loop, env = process.env, now = Date.now(), k = DEFAULT_UNATTENDED_TICKS) {
+    if (!isLoopAutoTickEligible(loop, env))
+        return "not-applicable";
+    const hb = readExecutorHeartbeat(root, loop.id);
+    if (!hb)
+        return "unattended";
+    const at = Date.parse(hb.at);
+    if (Number.isNaN(at))
+        return "unattended";
+    const tickMs = loop.policy?.tickMs && loop.policy.tickMs > 0 ? loop.policy.tickMs : FALLBACK_TICK_MS;
+    const age = now - at;
+    // Fail-closed on an implausibly FUTURE heartbeat: a beat stamped by a skewed
+    // or lying holder (`at` far ahead of the reader's clock) must NOT read
+    // `attended` forever. One tick of skew tolerance, then unattended.
+    if (age < -tickMs)
+        return "unattended";
+    // Fail-closed on staleness.
+    return age > k * tickMs ? "unattended" : "attended";
+}
+function delay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            resolve();
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Run ONE supervisor beat: tick+execute every eligible loop we can lease, in
+ * isolation. Exposed so a caller (or a test) can drive a single beat without the
+ * timer loop. Never throws: a loop's failure is captured in `errored`.
+ */
+export async function runSupervisorBeat(root, options = {}) {
+    const env = options.env ?? process.env;
+    const nowFn = options.now ?? (() => Date.now());
+    const tick = options.runTickFn ?? runTick;
+    const holder = options.holder ?? defaultHolder();
+    const leaseMs = options.leaseMs ?? DEFAULT_SUPERVISOR_LEASE_MS;
+    const tickTimeoutMs = options.tickTimeoutMs ?? Math.floor(leaseMs * TICK_TIMEOUT_FRACTION);
+    const ticked = [];
+    const skippedLocked = [];
+    const errored = [];
+    // Kill-switch: freeze the entire beat, tick nothing. Checked here AND inside
+    // listAutoTickLoops (redundant-but-safe) so a race that flips the switch
+    // BEFORE the list call yields an empty set either way.
+    if (autoTickGloballyDisabled(env)) {
+        return { ticked, skippedLocked, errored, frozen: true };
+    }
+    for (const loop of listAutoTickLoops(root, env)) {
+        // DRAIN: honor a shutdown signal BETWEEN loops so SIGTERM stops launching new
+        // work promptly instead of ticking every remaining eligible loop first.
+        if (options.signal?.aborted)
+            break;
+        const lease = acquireLoopExecutorLease(root, loop.id, { leaseMs, holder });
+        if (!lease) {
+            skippedLocked.push(loop.id);
+            continue;
+        }
+        // Bound the tick: abort it once tickTimeoutMs elapses (fail-closed) OR the
+        // supervisor is shutting down. The engine stops firing new actions on abort.
+        const tickAc = new AbortController();
+        const onOuterAbort = () => tickAc.abort();
+        options.signal?.addEventListener("abort", onOuterAbort, { once: true });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            tickAc.abort();
+        }, tickTimeoutMs);
+        try {
+            // Race the tick against its own abort so a hung tick never wedges the beat:
+            // if it overruns / is cancelled, we stop waiting, mark it errored (no
+            // heartbeat → the loop reads `unattended`), and move on.
+            await Promise.race([
+                tick(root, loop.id, { execute: true, signal: tickAc.signal }),
+                new Promise((resolve) => {
+                    tickAc.signal.addEventListener("abort", () => resolve(), { once: true });
+                })
+            ]);
+            if (tickAc.signal.aborted) {
+                errored.push({
+                    loopId: loop.id,
+                    error: timedOut ? `tick exceeded ${tickTimeoutMs}ms lease-safety timeout` : "aborted"
+                });
+            }
+            else {
+                stampExecutorHeartbeat(root, loop.id, {
+                    holder,
+                    fencingToken: lease.token,
+                    at: nowFn()
+                });
+                ticked.push(loop.id);
+            }
+        }
+        catch (err) {
+            // FAIL-CLOSED ISOLATION: this loop is simply not attended this beat; its
+            // heartbeat stays stale → surfaced as `unattended`. The beat continues.
+            errored.push({ loopId: loop.id, error: err instanceof Error ? err.message : String(err) });
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onOuterAbort);
+            lease.release();
+        }
+    }
+    return { ticked, skippedLocked, errored, frozen: false };
+}
+/**
+ * Run the durable supervisor until `signal` aborts (or `max` beats elapse). This
+ * is what the systemd `--user` unit runs (Lot 1c). It is NEVER on any default
+ * code path — existing users see no change until they explicitly launch it.
+ */
+export async function runLoopSupervisor(root, options = {}) {
+    const intervalMs = options.intervalMs && options.intervalMs > 0
+        ? options.intervalMs
+        : DEFAULT_SUPERVISOR_INTERVAL_MS;
+    let beats = 0;
+    for (;;) {
+        const summary = await runSupervisorBeat(root, options);
+        await options.onBeat?.(summary);
+        beats += 1;
+        if (options.max !== undefined && beats >= options.max)
+            return beats;
+        if (options.signal?.aborted)
+            return beats;
+        await delay(intervalMs, options.signal);
+        if (options.signal?.aborted)
+            return beats;
+    }
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/runtime/loop/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../../src/runtime/loop/supervisor.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/h2a",
-  "version": "0.85.18",
+  "version": "0.85.20",
   "description": "h2a — the unified CLI + core for human-to-agent coordination.",
   "license": "MIT",
   "type": "module",
@@ -51,7 +51,7 @@
     "@hono/mcp": "^0.3.0",
     "@hono/node-server": "^2.0.4",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@sentropic/track": "^0.85.18",
+    "@sentropic/track": "^0.85.20",
     "hono": "^4.12.23"
   },
   "peerDependencies": {

package/skills/harness/using-harness/SKILL.md

@@ -70,6 +70,24 @@ established tracking flow; otherwise recommend it without recording it. Never cr
 duplicate follow-up work from speculation. A handoff closes the diagnosed blocking item; it does not
 satisfy or defer any remaining explicit objective.
 
+## Rebase, never cherry-pick
+
+To move committed work between branches, rebase — never cherry-pick. Cherry-pick copies a commit under a
+new SHA, so the same change now exists twice with different identities: history diverges, a later merge or
+rebase sees "different" commits, and the duplicate resurfaces in diffs, reviews, and merge-loss checks.
+
+- To retarget a branch onto an updated base, `git rebase <base>` (or `git rebase --onto <newbase> <upstream>`
+  to replay only a specific range). The commits keep their logical identity and the branch stays linear.
+- To isolate one feature's commits from an entangled branch, `git rebase --onto origin/main <commit>~1 <branch>`
+  replays exactly that range onto the base — a rebase, not a copy.
+- `git cherry-pick` is reserved for the narrow case of applying a change to a branch that will NEVER share
+  history with the source (e.g. a backport to a frozen release line). It is not a tool for normal
+  branch-to-branch movement, and never a substitute for rebasing a feature onto a fresh base.
+
+Rationale: this is the same non-duplication discipline the branch-lifecycle event-containment gate enforces
+for `.track` — a copied commit is a second identity for one change, and every downstream tool then has to
+reconcile two things that should have been one.
+
 ## Discipline first
 
 Process skills (`harness/brainstorm`, `harness/debug`) decide HOW to approach the task — invoke them