instar 1.3.693 → 1.3.694

package/dist/core/serveProgress.d.ts

@@ -0,0 +1,61 @@
+/**
+ * MESH-SELF-HEAL G1 — the serve-progress watermark (MESH-SELF-HEAL-SPEC §3.1).
+ *
+ * `serveProgressedMonoMs` is the THIRD liveness signal — stamped when a fetched
+ * update is dispatched/served/durably-enqueued (proves end-to-end progress, closes
+ * the "fetched-and-dropped" gap, finding Adv-F4). It CANNOT share the lifeline's
+ * `lifeline-poll-active.json` (that record is the lifeline PROCESS's, atomically
+ * rewritten on every poll-state change with no serve field — a second-process write
+ * would clobber it). So it lives in its OWN single-writer record `state/serve-progress.json`,
+ * written by the dispatch seam and read cross-process by the relinquish evaluator
+ * (round-2 Int2-D / round-3 Les3-F1 — net-new, deliberately-acknowledged plumbing).
+ *
+ * THE LOAD-BEARING SAFETY: a **boot-epoch fence** (round-4 Adv4-B). Because this is a
+ * persisted file (one process can't read another's memory), a stamp written by a
+ * PRIOR incarnation must NEVER read as fresh after a crash/restart — else a
+ * crash-stale stamp would mask a non-serving new process (re-creating the zombie).
+ * The record carries a `bootId`; the reader discards any stamp whose `bootId` ≠ the
+ * current incarnation (a boot-epoch fence — NOT a raw monotonic compare, which
+ * across incarnations would be an invalid cross-domain subtraction). Within ONE
+ * incarnation the monotonic stamps share a clock domain, so the freshness compare is
+ * valid. The field is a single machine-global monotonic-MAX watermark (NOT per-topic
+ * state) — concurrent dispatch-seam writers are benign because it only ever advances
+ * (round-4 Adv4-A).
+ *
+ * Threat model + write posture mirror `pollIntent.ts`: local same-uid IPC, atomic
+ * tmp+rename so the reader never sees a torn record.
+ */
+export interface ServeProgressRecord {
+    /** Monotonic stamp (writer's monotonic clock) at the last served/enqueued update. */
+    serveProgressedMonoMs: number;
+    /** Writer process incarnation marker — the boot-epoch fence. */
+    bootId: string;
+    /** Writer pid (parity with pollIntent; diagnostics only). */
+    serverPid: number;
+    /** Wall-clock of the write (diagnostics; freshness uses the monotonic stamp). */
+    ts: number;
+}
+export declare function serveProgressPath(stateDir: string): string;
+export declare function readServeProgress(stateDir: string): ServeProgressRecord | null;
+/**
+ * Stamp serve progress. Monotonic-MAX: only ever advances — a write with a
+ * `monoMs` not greater than the current record's (SAME incarnation) is dropped, so
+ * concurrent dispatch-seam writers never regress the watermark. A record from a
+ * different `bootId` is always overwritten (a new incarnation starts its own clock
+ * domain; the prior stamp must not survive as fresh — the boot-epoch fence).
+ */
+export declare function writeServeProgress(stateDir: string, args: {
+    bootId: string;
+    serverPid: number;
+    monoMs: number;
+}): void;
+/**
+ * Is serve progress FRESH (the relinquish evaluator's read)? Boot-epoch-fenced:
+ * a stamp from a different incarnation (`bootId` mismatch) is treated as "no
+ * progress yet" (false) — so a crash-stale on-disk stamp can never mask a
+ * non-serving new process. Within the current incarnation the monotonic compare is
+ * a valid same-clock-domain subtraction. `currentBootId` + `currentMonoMs` are
+ * injected (the reader's own incarnation + monotonic now) so this is pure + testable.
+ */
+export declare function serveProgressFresh(stateDir: string, currentBootId: string, currentMonoMs: number, thresholdMs: number): boolean;
+//# sourceMappingURL=serveProgress.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serveProgress.d.ts","sourceRoot":"","sources":["../../src/core/serveProgress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAOH,MAAM,WAAW,mBAAmB;IAClC,qFAAqF;IACrF,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAmB9E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1D,IAAI,CAcN;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAClB,OAAO,CAKT"}

package/dist/core/serveProgress.js

@@ -0,0 +1,89 @@
+/**
+ * MESH-SELF-HEAL G1 — the serve-progress watermark (MESH-SELF-HEAL-SPEC §3.1).
+ *
+ * `serveProgressedMonoMs` is the THIRD liveness signal — stamped when a fetched
+ * update is dispatched/served/durably-enqueued (proves end-to-end progress, closes
+ * the "fetched-and-dropped" gap, finding Adv-F4). It CANNOT share the lifeline's
+ * `lifeline-poll-active.json` (that record is the lifeline PROCESS's, atomically
+ * rewritten on every poll-state change with no serve field — a second-process write
+ * would clobber it). So it lives in its OWN single-writer record `state/serve-progress.json`,
+ * written by the dispatch seam and read cross-process by the relinquish evaluator
+ * (round-2 Int2-D / round-3 Les3-F1 — net-new, deliberately-acknowledged plumbing).
+ *
+ * THE LOAD-BEARING SAFETY: a **boot-epoch fence** (round-4 Adv4-B). Because this is a
+ * persisted file (one process can't read another's memory), a stamp written by a
+ * PRIOR incarnation must NEVER read as fresh after a crash/restart — else a
+ * crash-stale stamp would mask a non-serving new process (re-creating the zombie).
+ * The record carries a `bootId`; the reader discards any stamp whose `bootId` ≠ the
+ * current incarnation (a boot-epoch fence — NOT a raw monotonic compare, which
+ * across incarnations would be an invalid cross-domain subtraction). Within ONE
+ * incarnation the monotonic stamps share a clock domain, so the freshness compare is
+ * valid. The field is a single machine-global monotonic-MAX watermark (NOT per-topic
+ * state) — concurrent dispatch-seam writers are benign because it only ever advances
+ * (round-4 Adv4-A).
+ *
+ * Threat model + write posture mirror `pollIntent.ts`: local same-uid IPC, atomic
+ * tmp+rename so the reader never sees a torn record.
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const SERVE_PROGRESS_FILE = 'serve-progress.json';
+export function serveProgressPath(stateDir) {
+    return join(stateDir, SERVE_PROGRESS_FILE);
+}
+export function readServeProgress(stateDir) {
+    const p = serveProgressPath(stateDir);
+    if (!existsSync(p))
+        return null;
+    try {
+        const rec = JSON.parse(readFileSync(p, 'utf8'));
+        if (typeof rec?.serveProgressedMonoMs !== 'number' ||
+            typeof rec?.bootId !== 'string' ||
+            typeof rec?.ts !== 'number')
+            return null;
+        return rec;
+    }
+    catch {
+        // @silent-fallback-ok — a corrupt/unreadable serve-progress record reads as
+        // "no progress yet" (null → serveProgressFresh false), the SAFE direction: a
+        // holder that cannot read its own serve watermark is treated as possibly-non-
+        // serving (a relinquish candidate), NEVER masked as healthy. A DegradationReporter
+        // event per failed read of a best-effort liveness file would be noise.
+        return null;
+    }
+}
+/**
+ * Stamp serve progress. Monotonic-MAX: only ever advances — a write with a
+ * `monoMs` not greater than the current record's (SAME incarnation) is dropped, so
+ * concurrent dispatch-seam writers never regress the watermark. A record from a
+ * different `bootId` is always overwritten (a new incarnation starts its own clock
+ * domain; the prior stamp must not survive as fresh — the boot-epoch fence).
+ */
+export function writeServeProgress(stateDir, args) {
+    const { bootId, serverPid, monoMs } = args;
+    const existing = readServeProgress(stateDir);
+    if (existing && existing.bootId === bootId && existing.serveProgressedMonoMs >= monoMs) {
+        return; // monotonic-MAX within the same incarnation — never regress
+    }
+    const p = serveProgressPath(stateDir);
+    const tmp = `${p}.tmp.${process.pid}`;
+    writeFileSync(tmp, JSON.stringify({ serveProgressedMonoMs: monoMs, bootId, serverPid, ts: Date.now() }), 'utf8');
+    renameSync(tmp, p);
+}
+/**
+ * Is serve progress FRESH (the relinquish evaluator's read)? Boot-epoch-fenced:
+ * a stamp from a different incarnation (`bootId` mismatch) is treated as "no
+ * progress yet" (false) — so a crash-stale on-disk stamp can never mask a
+ * non-serving new process. Within the current incarnation the monotonic compare is
+ * a valid same-clock-domain subtraction. `currentBootId` + `currentMonoMs` are
+ * injected (the reader's own incarnation + monotonic now) so this is pure + testable.
+ */
+export function serveProgressFresh(stateDir, currentBootId, currentMonoMs, thresholdMs) {
+    const rec = readServeProgress(stateDir);
+    if (!rec)
+        return false;
+    if (rec.bootId !== currentBootId)
+        return false; // boot-epoch fence
+    return currentMonoMs - rec.serveProgressedMonoMs < thresholdMs;
+}
+//# sourceMappingURL=serveProgress.js.map

package/dist/core/serveProgress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serveProgress.js","sourceRoot":"","sources":["../../src/core/serveProgress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAalD,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,OAAO,IAAI,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,CAAC,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAwB,CAAC;QACvE,IACE,OAAO,GAAG,EAAE,qBAAqB,KAAK,QAAQ;YAC9C,OAAO,GAAG,EAAE,MAAM,KAAK,QAAQ;YAC/B,OAAO,GAAG,EAAE,EAAE,KAAK,QAAQ;YAC3B,OAAO,IAAI,CAAC;QACd,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;QAC5E,6EAA6E;QAC7E,8EAA8E;QAC9E,mFAAmF;QACnF,uEAAuE;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,IAA2D;IAE3D,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3C,MAAM,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,MAAM,IAAI,QAAQ,CAAC,qBAAqB,IAAI,MAAM,EAAE,CAAC;QACvF,OAAO,CAAC,4DAA4D;IACtE,CAAC;IACD,MAAM,CAAC,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAC;IACtC,aAAa,CACX,GAAG,EACH,IAAI,CAAC,SAAS,CAAC,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAgC,CAAC,EAClH,MAAM,CACP,CAAC;IACF,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;AACrB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,aAAqB,EACrB,aAAqB,EACrB,WAAmB;IAEnB,MAAM,GAAG,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvB,IAAI,GAAG,CAAC,MAAM,KAAK,aAAa;QAAE,OAAO,KAAK,CAAC,CAAC,mBAAmB;IACnE,OAAO,aAAa,GAAG,GAAG,CAAC,qBAAqB,GAAG,WAAW,CAAC;AACjE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.693",
+  "version": "1.3.694",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-28T10:28:11.496Z",
-  "instarVersion": "1.3.693",
+  "generatedAt": "2026-06-28T10:37:09.930Z",
+  "instarVersion": "1.3.694",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.694.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Mesh Self-Heal **G1 — serve-progress watermark** (wiring increment A, MESH-SELF-HEAL-SPEC §3.1). Adds `src/core/serveProgress.ts`: the third liveness signal (`serveProgressedMonoMs` — proof a fetched update was actually served end-to-end, closing the "fetched-and-dropped" gap), in its own single-writer record `state/serve-progress.json`.
+
+The load-bearing safety is a **boot-epoch fence**: a stamp left on disk by a crashed/prior process incarnation always reads as NOT fresh, so a crash-stale stamp can never mask a non-serving new process (which would re-create the zombie). Monotonic-MAX (only ever advances → concurrent writers benign), atomic tmp+rename, local same-uid IPC — mirrors `pollIntent.ts`.
+
+Pure plumbing, NOT yet wired — zero runtime effect until increment B (the dispatch-seam write + the relinquish evaluator) consumes it. This watermark is also the prerequisite that lets the G2 take-over flip use a real serve/poll-health signal instead of a liveness approximation.
+
+## What to Tell Your User
+
+Nothing changes yet — this is inert internal plumbing for the deepest multi-machine self-heal piece (detecting a machine that holds the "in charge" badge but has stopped actually serving). No action needed.
+
+## Summary of New Capabilities
+
+- None user-facing. New internal record `state/serve-progress.json` + helpers (`src/core/serveProgress.ts`), consumed by a later wiring increment; no route, config, or runtime surface yet.
+
+## Evidence
+
+- `tests/unit/serveProgress.test.ts` — 6 unit tests: write/read roundtrip; missing→null/not-fresh; monotonic-MAX no-regress; new-incarnation overwrite; freshness within/past threshold; and the BOOT-EPOCH FENCE (a prior-incarnation stamp reads not-fresh even when recent). Typecheck clean.

package/upgrades/side-effects/mesh-self-heal-g1-serve-progress.md

@@ -0,0 +1,32 @@
+# Side-Effects Review — Mesh Self-Heal G1 (serve-progress watermark)
+
+**Change:** The serve-progress watermark record (MESH-SELF-HEAL-SPEC §3.1) — `src/core/serveProgress.ts` (`writeServeProgress` / `readServeProgress` / `serveProgressFresh`) + 6 unit tests. The THIRD G1 liveness signal (`serveProgressedMonoMs` — end-to-end serve progress), in its OWN single-writer record `state/serve-progress.json` (it cannot share the lifeline's poll-active record without clobbering it). This is G1-wiring increment A: the watermark plumbing only. NOT YET CALLED by any writer or reader — ZERO runtime effect until increment B (the dispatch-seam write + the relinquish evaluator) consumes it. It is also the named **G2-enforce-enable prerequisite #1** (`localPollSucceededFresh` graduates from a liveness approximation to this real watermark).
+
+**Decision point?** No — pure file I/O (a watermark record). Safety hinges on the boot-epoch fence (Q1/Q7).
+
+## 1. Over-block
+N/A — no gating. `serveProgressFresh` biases SAFE: missing record → false; bootId mismatch → false; only a same-incarnation in-threshold stamp → true.
+
+## 2. Under-block
+The boot-epoch fence is the guard against under-blocking (a crash-stale stamp masking a non-serving process): a prior incarnation's stamp (`bootId` mismatch) always reads NOT fresh. Tested.
+
+## 3. Level-of-abstraction fit
+Mirrors `pollIntent.ts` exactly (atomic tmp+rename, local same-uid IPC, integrity fields). Correct layer — a cross-process record + a pure freshness reader; the dispatch-seam wiring + the evaluator are increment B.
+
+## 4. Signal vs authority compliance
+COMPLIANT — pure I/O, no authority. It produces a freshness SIGNAL the relinquish decision will read; it never gates or actuates.
+
+## 5. Interactions
+Single-writer, monotonic-MAX → concurrent dispatch-seam writers are benign (only advances). Distinct file from `lifeline-poll-active.json` → no clobber of the lifeline's record. No reader/writer yet.
+
+## 6. External surfaces
+New file `state/serve-progress.json` (local, same-uid, like pollIntent). No route, no config. Written/read only once increment B wires it.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+Machine-local, never replicated (Sca-F1) — read only by the owning machine for its OWN relinquish decision. The boot-epoch fence makes it survive-restart-safe (a prior incarnation's stamp can't mask the new one). No cross-machine surface.
+
+## 8. Rollback cost
+Trivial — revert the commit. Unreferenced; removing it cannot affect a running agent. The on-disk file (if ever written) is inert observability.
+
+## Second-pass review
+Not triggered (pure file-I/O building block, no live decision-point/authority/session-lifecycle touch). The Phase-5 second-pass IS required for increment B (it wires the dispatch-seam write + the relinquish evaluator into the lease holder branch + the F3 actuation).