@groundnuty/macf-core 0.2.44 → 0.2.46

package/dist/registry/types.d.ts

@@ -25,7 +25,8 @@ export type AgentInfo = z.infer<typeof AgentInfoSchema>;
  */
 export declare function agentInfoEquals(a: AgentInfo | null, b: AgentInfo | null): boolean;
 /**
- * Outcome of a conditional (compare-and-set) register (groundnuty/macf#439).
+ * Outcome of a conditional (compare-and-set) register (groundnuty/macf#439,
+ * reshaped by groundnuty/macf#702 — over-register).
  *
  * `ok: true`  — this instance now owns the slot; `current` is the value just
  *               written (=== the `info` passed in). Ownership strength is
@@ -36,11 +37,38 @@ export declare function agentInfoEquals(a: AgentInfo | null, b: AgentInfo | null
  *               API; see registry.ts `registerConditional`).
  * `ok: false` — a concurrent writer changed the slot between the collision
  *               check and this write; `current` is the conflicting value
- *               observed (null if the slot was emptied). The caller must NOT
- *               treat itself as the registered owner — abort or re-check.
+ *               observed (null if the slot was emptied). The caller decides
+ *               claim-vs-yield from `reason` (see below) — `ok:false` is NO
+ *               LONGER an unconditional abort signal (groundnuty/macf#702 fixed
+ *               the devops 8h-outage bug where it was).
+ *
+ * `reason` discriminates WHY the CAS resolved the way it did — this is the
+ * groundnuty/macf#702 fix. Before #702, `ok:false` was always treated as "lost
+ * a race, abort" (`RegisterRaceError`), which mis-fired when the write
+ * actually succeeded but the GitHub Variables API's read-after-write lag
+ * served a stale GET on the post-write read-back (the exact devops bug:
+ * `current == expected` — nothing changed — yet the read-back momentarily
+ * still showed the pre-write value, and the old code aborted anyway):
+ *
+ *  - `'claimed'`          — `ok:true`. The write landed and (when a read-back
+ *                           exists) is confirmed, OR the pre-write compare
+ *                           found the slot unchanged from `expected` and the
+ *                           write was issued — the CAS ALWAYS claims in this
+ *                           case, never aborts, even if a same-backend
+ *                           read-back lag means confirmation isn't
+ *                           immediately visible (groundnuty/macf#702 §1).
+ *  - `'lost-to-newer'`    — `ok:false`. The write-time re-read (or read-back)
+ *                           observed a DIFFERENT registration than `expected`
+ *                           — a genuine concurrent writer. The caller
+ *                           (server.ts) is responsible for classifying that
+ *                           `current` as newer-live (yield) vs stale/older
+ *                           (retry the takeover) — the registry layer only
+ *                           reports the conflicting value; it doesn't probe
+ *                           liveness (that's `collision.ts`'s job).
  */
 export interface RegisterResult {
     readonly ok: boolean;
+    readonly reason: 'claimed' | 'lost-to-newer';
     readonly current: AgentInfo | null;
 }
 /**
@@ -98,15 +126,32 @@ export interface HeartbeatResult {
 export interface Registry {
     readonly register: (name: string, info: AgentInfo) => Promise<void>;
     /**
-     * Compare-and-set register (groundnuty/macf#439): write `info` only if the
-     * slot still matches `expected` (the value observed during the collision
-     * check; `null` = expected-absent). Closes the TOCTOU window between the
-     * collision check's read and the registration write — a racing second
-     * writer can't silently clobber the first. Returns whether this instance
-     * won the slot. Backends differ in atomicity: the local registry is fully
-     * atomic under its file lock; the GitHub-Variables backend narrows the
-     * window with a pre-write compare + post-write read-back verify (no native
-     * CAS primitive exists on that API — see registry.ts).
+     * Compare-and-set register (groundnuty/macf#439; over-register semantics
+     * per groundnuty/macf#702): write `info` if the slot still matches
+     * `expected` (the value observed during the collision check; `null` =
+     * expected-absent). Closes the TOCTOU window between the collision check's
+     * read and the registration write — a racing second writer can't silently
+     * clobber the first. Backends differ in atomicity: the local registry is
+     * fully atomic under its file lock (no read-back needed); the
+     * GitHub-Variables backend narrows the window with a pre-write compare and
+     * best-effort-confirms via a post-write read-back (no native CAS primitive
+     * exists on that API — see registry.ts).
+     *
+     * **groundnuty/macf#702 (over-register):** `current == expected` — the slot
+     * is UNCHANGED, including the case where `expected` is itself a stale/dead
+     * entry the caller decided to take over — is ALWAYS a claim (`ok:true,
+     * reason:'claimed'`), never a failure. This holds even when a same-backend
+     * read-back can't yet observe the write (GitHub Variables API
+     * read-after-write lag) — a lagging read-back is a confirmation gap, not a
+     * lost race, and must not be reported as one (this was the devops 8h-outage
+     * bug: `current==expected==<stale>` incorrectly returned `ok:false`).
+     * `ok:false, reason:'lost-to-newer'` fires ONLY when the write-time re-read
+     * (or the read-back) observes a value that is a genuinely different
+     * registration than the caller's own `info` AND different from `expected`
+     * — a real concurrent writer. The registry layer reports the conflicting
+     * `current` but does not classify it as live/dead/newer/older — that
+     * liveness judgment is the caller's (server.ts + collision.ts), which
+     * decides claim-over-stale (retry) vs yield-to-newer-live.
      */
     readonly registerConditional: (name: string, info: AgentInfo, expected: AgentInfo | null) => Promise<RegisterResult>;
     /**

package/dist/registry/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/registry/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,eAAe;;;;;;;;;;iBAiB1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,SAAS,GAAG,IAAI,EAAE,CAAC,EAAE,SAAS,GAAG,IAAI,GAAG,OAAO,CASjF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;CAC9D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;CAC3D;AAID,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,mBAAmB,EAAE,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,SAAS,GAAG,IAAI,KACvB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,qBAAqB,EAAE,CAC9B,IAAI,EAAE,MAAM,EACZ,kBAAkB,EAAE,MAAM,KACvB,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,oBAAoB,EAAE,CAC7B,IAAI,EAAE,MAAM,EACZ,kBAAkB,EAAE,MAAM,EAC1B,GAAG,EAAE,MAAM,KACR,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC1D,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC,CAAC;IAC/G,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAID,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;iBAInC,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB;;;iBAGpC,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;mBAK/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAChE,QAAQ,CAAC,aAAa,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IACxG,QAAQ,CAAC,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/registry/types.ts"],"names":[],"mappings":"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"}

package/dist/registry/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/registry/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,4DAA4D;AAE5D,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACjC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACrC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB;;;;;;;;;OASG;IACH,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC,CAAC;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,CAAmB,EAAE,CAAmB;IACtE,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7C,OAAO,CACL,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QACjB,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QACjB,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QACjB,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAC/B,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,CACxB,CAAC;AACJ,CAAC;AAoJD,iCAAiC;AAEjC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACtB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACvB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IAC1B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACxB,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC;IAC1C,uBAAuB;IACvB,2BAA2B;IAC3B,wBAAwB;IACxB,yBAAyB;CAC1B,CAAC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/registry/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,4DAA4D;AAE5D,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACjC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACrC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB;;;;;;;;;OASG;IACH,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC,CAAC;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,CAAmB,EAAE,CAAmB;IACtE,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7C,OAAO,CACL,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QACjB,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QACjB,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QACjB,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAC/B,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,CACxB,CAAC;AACJ,CAAC;AAiMD,iCAAiC;AAEjC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACtB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACvB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IAC1B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACxB,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC;IAC1C,uBAAuB;IACvB,2BAA2B;IAC3B,wBAAwB;IACxB,yBAAyB;CAC1B,CAAC,CAAC"}

package/dist/stall-signatures.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Stall-signature allowlist — config schema, the pure pane-matcher, and the
+ * per-action fire-cap logic behind `macf fleet resume` (DR-037 / groundnuty/macf#686,
+ * porting `groundnuty/macf-devops-toolkit:fleet/resume.sh` + `stall-signatures.json`).
+ *
+ * SAFETY-CRITICAL. `macf fleet resume` acts on an IDLE agent — an idle agent is one
+ * of three things and only the pane tells them apart (operator, 2026-06-28):
+ *
+ *   - idle-CLEAN (no signature matched)      → legitimately idle/done → DO NOTHING.
+ *   - idle-STALLED (rate-limit / turn-abort) → `action: nudge` — resume the SAME
+ *     session (a nudge preserves in-progress work; a restart loses it + re-hits a
+ *     rate-limit). The gentlest recovery.
+ *   - idle-BLOCKED (permission / trust /     → `action: report` — a DURABLE operator
+ *     skill / memory prompt)                   alert, NEVER auto-answered (an
+ *                                              authorization decision needs a human;
+ *                                              DR-033 ceremony-not-authorization).
+ *
+ * The safety contract is the sibling of DR-033's: **allowlist-only, never a blind
+ * nudge.** We act ONLY on an idle agent whose recent pane matches a KNOWN, vetted
+ * signature. An unmatched idle pane is legitimately idle/done → never touched (no
+ * spam). An unknown-but-blocking prompt falls through to no-match → skip; the
+ * operator adds a `report` signature as the TUI evolves (the allowlist is DATA).
+ *
+ * This module holds the PURE logic — the config the operator curates in
+ * `.claude/.macf/stall-signatures.json`, the schema/validator the CLI runs at
+ * `macf init/update/rules refresh`, and the frame-matcher the `fleet resume`
+ * decision layer drives off. The tested reference is the devops `resume.sh` bash
+ * (which reimplements the same match-then-dispatch in bash + jq); the two MUST
+ * stay in lockstep.
+ */
+import { z } from 'zod';
+import { MacfError } from './errors.js';
+/** A matched stall's dispatched action: nudge a stalled agent, or report a blocked one. */
+export declare const STALL_ACTIONS: readonly ["nudge", "report"];
+export type StallAction = (typeof STALL_ACTIONS)[number];
+/**
+ * Per-action default fire cap when an entry omits `max_fires` — a nudge is a
+ * gentle repeatable resume (retry a few times, then escalate), a report is a
+ * one-shot durable alert per episode (re-alerting spams the operator). Mirrors
+ * the devops `resume.sh` defaults (`nudge`=3, `report`=1).
+ */
+export declare const DEFAULT_NUDGE_MAX_FIRES = 3;
+export declare const DEFAULT_REPORT_MAX_FIRES = 1;
+/** Thrown when the stall-signatures config fails schema / regex validation. */
+export declare class StallSignaturesError extends MacfError {
+    constructor(message: string);
+}
+/**
+ * A single stall-signature allowlist entry.
+ *
+ *   - `name` — the signature's stable identifier (rendered in the plan / the
+ *     alert title, so a fire-cap counter can key off it).
+ *   - `signature` — a regular-expression source matched CASE-INSENSITIVELY against
+ *     the captured idle pane (the ERE the devops bash greps with `grep -qiE`; the
+ *     seeds' alternation/`\?`/`\.` forms are JS-RegExp-compatible). Validated for
+ *     compilability at load — a malformed pattern is a LOUD config error, never a
+ *     silent non-match.
+ *   - `action` — `nudge` (resume a stalled agent) or `report` (durable alert for a
+ *     blocked agent; NEVER auto-answered). Defaults to `nudge`.
+ *   - `nudge` — the text sent into the TUI for `action: nudge` (default: a generic
+ *     "please continue").
+ *   - `report` — the operator-facing summary for `action: report` (default: a
+ *     generic "blocked on an operator-input prompt").
+ *   - `max_fires` — per-episode fire cap; omitted → the per-action default.
+ *   - `comment` — operator documentation (why this signature; caveats). Ignored by
+ *     the matcher; kept in the schema so the seed's `comment` fields validate.
+ *
+ * `.strict()` so an operator typo in a field name (e.g. `signatures`) is a loud
+ * validation error, not a silently-ignored field.
+ */
+export declare const StallSignatureEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    signature: z.ZodString;
+    action: z.ZodDefault<z.ZodEnum<{
+        nudge: "nudge";
+        report: "report";
+    }>>;
+    nudge: z.ZodOptional<z.ZodString>;
+    report: z.ZodOptional<z.ZodString>;
+    max_fires: z.ZodOptional<z.ZodNumber>;
+    comment: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type StallSignatureEntry = z.infer<typeof StallSignatureEntrySchema>;
+/**
+ * The whole config: a bare array of entries — the exact shape of the devops
+ * `fleet/stall-signatures.json` reference (so the two files are interchangeable).
+ */
+export declare const StallSignaturesConfigSchema: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    signature: z.ZodString;
+    action: z.ZodDefault<z.ZodEnum<{
+        nudge: "nudge";
+        report: "report";
+    }>>;
+    nudge: z.ZodOptional<z.ZodString>;
+    report: z.ZodOptional<z.ZodString>;
+    max_fires: z.ZodOptional<z.ZodNumber>;
+    comment: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export type StallSignaturesConfig = z.infer<typeof StallSignaturesConfigSchema>;
+/**
+ * Validate + regex-check a parsed config. Throws `StallSignaturesError` on a
+ * schema-invalid shape OR an uncompilable `signature` (loud — a malformed
+ * allowlist must never silently degrade to "matches nothing"). Returns the
+ * accepted entries.
+ */
+export declare function loadStallSignatures(raw: unknown): readonly StallSignatureEntry[];
+/**
+ * The per-episode fire cap for an entry — its explicit `max_fires`, else the
+ * per-action default (nudge 3 / report 1).
+ */
+export declare function resolveMaxFires(entry: StallSignatureEntry): number;
+/** Fire-cap guard: may this stall-signature fire again given its prior fire count? */
+export declare function canFireStall(entry: StallSignatureEntry, firedCount: number): boolean;
+/**
+ * First allowlist entry whose `signature` regex matches the captured pane
+ * (case-insensitive), or `null` when the pane matches nothing — the idle-CLEAN
+ * case the caller treats as "legitimately idle/done, never touched". Pure.
+ *
+ * A signature that fails to compile is skipped (defensively) rather than
+ * throwing here — `loadStallSignatures` is the fail-loud gate; the matcher stays
+ * total so a single bad entry never breaks a whole sweep.
+ */
+export declare function matchStallSignature(pane: string, entries: readonly StallSignatureEntry[]): StallSignatureEntry | null;
+/**
+ * The canonical seed `macf init` writes when no `stall-signatures.json` exists.
+ * Ported verbatim from `groundnuty/macf-devops-toolkit:fleet/stall-signatures.json`
+ * (the tested reference). Two `nudge` signatures (transient rate-limit / turn-abort
+ * — resume the same session) and three `report` signatures (permission / trust /
+ * skill-or-memory prompts — authorization decisions that must NEVER be
+ * auto-answered, only surfaced as a durable operator alert).
+ *
+ * Signature strings are best-effort across Claude Code versions — the allowlist is
+ * DATA; an operator tunes it against the real pane as the TUI evolves. An imperfect
+ * signature fails SAFE (falls through to no-match → the agent is left untouched,
+ * never a wrong action).
+ */
+export declare const STALL_SIGNATURES_SEED: StallSignaturesConfig;
+//# sourceMappingURL=stall-signatures.d.ts.map

package/dist/stall-signatures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stall-signatures.d.ts","sourceRoot":"","sources":["../src/stall-signatures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,2FAA2F;AAC3F,eAAO,MAAM,aAAa,8BAA+B,CAAC;AAC1D,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,+EAA+E;AAC/E,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;kBAU3B,CAAC;AACZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;mBAAqC,CAAC;AAC9E,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,mBAAmB,EAAE,CAsBhF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAGlE;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAEpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,mBAAmB,EAAE,GACtC,mBAAmB,GAAG,IAAI,CAW5B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,EAAE,qBA8DnC,CAAC"}

package/dist/stall-signatures.js

@@ -0,0 +1,219 @@
+/**
+ * Stall-signature allowlist — config schema, the pure pane-matcher, and the
+ * per-action fire-cap logic behind `macf fleet resume` (DR-037 / groundnuty/macf#686,
+ * porting `groundnuty/macf-devops-toolkit:fleet/resume.sh` + `stall-signatures.json`).
+ *
+ * SAFETY-CRITICAL. `macf fleet resume` acts on an IDLE agent — an idle agent is one
+ * of three things and only the pane tells them apart (operator, 2026-06-28):
+ *
+ *   - idle-CLEAN (no signature matched)      → legitimately idle/done → DO NOTHING.
+ *   - idle-STALLED (rate-limit / turn-abort) → `action: nudge` — resume the SAME
+ *     session (a nudge preserves in-progress work; a restart loses it + re-hits a
+ *     rate-limit). The gentlest recovery.
+ *   - idle-BLOCKED (permission / trust /     → `action: report` — a DURABLE operator
+ *     skill / memory prompt)                   alert, NEVER auto-answered (an
+ *                                              authorization decision needs a human;
+ *                                              DR-033 ceremony-not-authorization).
+ *
+ * The safety contract is the sibling of DR-033's: **allowlist-only, never a blind
+ * nudge.** We act ONLY on an idle agent whose recent pane matches a KNOWN, vetted
+ * signature. An unmatched idle pane is legitimately idle/done → never touched (no
+ * spam). An unknown-but-blocking prompt falls through to no-match → skip; the
+ * operator adds a `report` signature as the TUI evolves (the allowlist is DATA).
+ *
+ * This module holds the PURE logic — the config the operator curates in
+ * `.claude/.macf/stall-signatures.json`, the schema/validator the CLI runs at
+ * `macf init/update/rules refresh`, and the frame-matcher the `fleet resume`
+ * decision layer drives off. The tested reference is the devops `resume.sh` bash
+ * (which reimplements the same match-then-dispatch in bash + jq); the two MUST
+ * stay in lockstep.
+ */
+import { z } from 'zod';
+import { MacfError } from './errors.js';
+/** A matched stall's dispatched action: nudge a stalled agent, or report a blocked one. */
+export const STALL_ACTIONS = ['nudge', 'report'];
+/**
+ * Per-action default fire cap when an entry omits `max_fires` — a nudge is a
+ * gentle repeatable resume (retry a few times, then escalate), a report is a
+ * one-shot durable alert per episode (re-alerting spams the operator). Mirrors
+ * the devops `resume.sh` defaults (`nudge`=3, `report`=1).
+ */
+export const DEFAULT_NUDGE_MAX_FIRES = 3;
+export const DEFAULT_REPORT_MAX_FIRES = 1;
+/** Thrown when the stall-signatures config fails schema / regex validation. */
+export class StallSignaturesError extends MacfError {
+    constructor(message) {
+        super('STALL_SIGNATURES_ERROR', message);
+        this.name = 'StallSignaturesError';
+    }
+}
+/**
+ * A single stall-signature allowlist entry.
+ *
+ *   - `name` — the signature's stable identifier (rendered in the plan / the
+ *     alert title, so a fire-cap counter can key off it).
+ *   - `signature` — a regular-expression source matched CASE-INSENSITIVELY against
+ *     the captured idle pane (the ERE the devops bash greps with `grep -qiE`; the
+ *     seeds' alternation/`\?`/`\.` forms are JS-RegExp-compatible). Validated for
+ *     compilability at load — a malformed pattern is a LOUD config error, never a
+ *     silent non-match.
+ *   - `action` — `nudge` (resume a stalled agent) or `report` (durable alert for a
+ *     blocked agent; NEVER auto-answered). Defaults to `nudge`.
+ *   - `nudge` — the text sent into the TUI for `action: nudge` (default: a generic
+ *     "please continue").
+ *   - `report` — the operator-facing summary for `action: report` (default: a
+ *     generic "blocked on an operator-input prompt").
+ *   - `max_fires` — per-episode fire cap; omitted → the per-action default.
+ *   - `comment` — operator documentation (why this signature; caveats). Ignored by
+ *     the matcher; kept in the schema so the seed's `comment` fields validate.
+ *
+ * `.strict()` so an operator typo in a field name (e.g. `signatures`) is a loud
+ * validation error, not a silently-ignored field.
+ */
+export const StallSignatureEntrySchema = z
+    .object({
+    name: z.string().min(1),
+    signature: z.string().min(1),
+    action: z.enum(STALL_ACTIONS).default('nudge'),
+    nudge: z.string().min(1).optional(),
+    report: z.string().min(1).optional(),
+    max_fires: z.number().int().positive().optional(),
+    comment: z.string().optional(),
+})
+    .strict();
+/**
+ * The whole config: a bare array of entries — the exact shape of the devops
+ * `fleet/stall-signatures.json` reference (so the two files are interchangeable).
+ */
+export const StallSignaturesConfigSchema = z.array(StallSignatureEntrySchema);
+/**
+ * Validate + regex-check a parsed config. Throws `StallSignaturesError` on a
+ * schema-invalid shape OR an uncompilable `signature` (loud — a malformed
+ * allowlist must never silently degrade to "matches nothing"). Returns the
+ * accepted entries.
+ */
+export function loadStallSignatures(raw) {
+    const parsed = StallSignaturesConfigSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new StallSignaturesError(`stall-signatures config is invalid: ${parsed.error.issues
+            .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
+            .join('; ')}`);
+    }
+    for (const entry of parsed.data) {
+        try {
+            // Validate compilability up front (fail-loud). Case-insensitive to mirror
+            // the devops `grep -iE`.
+            new RegExp(entry.signature, 'i');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new StallSignaturesError(`stall-signatures entry "${entry.name}" has an invalid regex signature: ${msg}`);
+        }
+    }
+    return parsed.data;
+}
+/**
+ * The per-episode fire cap for an entry — its explicit `max_fires`, else the
+ * per-action default (nudge 3 / report 1).
+ */
+export function resolveMaxFires(entry) {
+    if (entry.max_fires !== undefined)
+        return entry.max_fires;
+    return entry.action === 'report' ? DEFAULT_REPORT_MAX_FIRES : DEFAULT_NUDGE_MAX_FIRES;
+}
+/** Fire-cap guard: may this stall-signature fire again given its prior fire count? */
+export function canFireStall(entry, firedCount) {
+    return firedCount < resolveMaxFires(entry);
+}
+/**
+ * First allowlist entry whose `signature` regex matches the captured pane
+ * (case-insensitive), or `null` when the pane matches nothing — the idle-CLEAN
+ * case the caller treats as "legitimately idle/done, never touched". Pure.
+ *
+ * A signature that fails to compile is skipped (defensively) rather than
+ * throwing here — `loadStallSignatures` is the fail-loud gate; the matcher stays
+ * total so a single bad entry never breaks a whole sweep.
+ */
+export function matchStallSignature(pane, entries) {
+    for (const entry of entries) {
+        let re;
+        try {
+            re = new RegExp(entry.signature, 'i');
+        }
+        catch {
+            continue;
+        }
+        if (re.test(pane))
+            return entry;
+    }
+    return null;
+}
+/**
+ * The canonical seed `macf init` writes when no `stall-signatures.json` exists.
+ * Ported verbatim from `groundnuty/macf-devops-toolkit:fleet/stall-signatures.json`
+ * (the tested reference). Two `nudge` signatures (transient rate-limit / turn-abort
+ * — resume the same session) and three `report` signatures (permission / trust /
+ * skill-or-memory prompts — authorization decisions that must NEVER be
+ * auto-answered, only surfaced as a durable operator alert).
+ *
+ * Signature strings are best-effort across Claude Code versions — the allowlist is
+ * DATA; an operator tunes it against the real pane as the TUI evolves. An imperfect
+ * signature fails SAFE (falls through to no-match → the agent is left untouched,
+ * never a wrong action).
+ */
+export const STALL_SIGNATURES_SEED = [
+    {
+        name: 'rate-limit',
+        signature: '(temporarily limiting requests|Rate limited|API Error.*limiting)',
+        action: 'nudge',
+        nudge: 'You appear to have stalled on a transient API rate-limit (server-side, not ' +
+            'your usage quota). The limit should have cleared — please continue your work ' +
+            'where you left off.',
+        max_fires: 4,
+        comment: 'Anthropic server-side capacity throttle (NOT the account quota). Leaves the ' +
+            'agent idle mid-flow. Nudge resumes the SAME session (preserves work); restart ' +
+            'would lose it + re-hit the limit. verify-resumed self-corrects a nudge into a ' +
+            'still-active throttle (back off + retry).',
+    },
+    {
+        name: 'turn-aborted',
+        signature: '(Request was aborted|aborted by user|API Error: Connection error)',
+        action: 'nudge',
+        nudge: 'Your last turn aborted before completing. Please continue your work where you left off.',
+        max_fires: 3,
+        comment: 'A turn that died on a transient connection/abort error, leaving the agent ' +
+            'idle. Same resume-not-restart logic.',
+    },
+    {
+        name: 'permission-prompt',
+        signature: '(Do you want to proceed\\?|Do you want to make this edit\\?|Do you want to create|Yes, and don.t ask again)',
+        action: 'report',
+        report: 'blocked on a tool-permission prompt ("Do you want to proceed?") — needs the ' +
+            'operator to approve/deny. Cannot be auto-answered (an authorization decision, ' +
+            'per DR-033 ceremony-not-authorization).',
+        max_fires: 1,
+        comment: 'Claude Code tool-permission dialog. action=report (NOT nudge/answer): ' +
+            'authorization prompts require human judgment, so the correct automation is to ' +
+            'make the silent block LOUD, never to answer it. macf-devops-toolkit#132.',
+    },
+    {
+        name: 'trust-folder-prompt',
+        signature: '(Do you trust the files in this folder\\?|trust the files in this)',
+        action: 'report',
+        report: 'blocked on a folder-trust prompt — needs the operator to confirm trust. ' +
+            'Authorization decision; cannot be auto-answered.',
+        max_fires: 1,
+        comment: "Claude Code 'trust this folder' dialog on a new/changed workspace. action=report. #132.",
+    },
+    {
+        name: 'skill-or-memory-prompt',
+        signature: '(Allow .* to run\\?|Save this to memory\\?|Add this to memory\\?|Allow this skill)',
+        action: 'report',
+        report: 'blocked on a skill-approval or memory-accept prompt — needs the operator\'s ' +
+            'decision. Cannot be auto-answered.',
+        max_fires: 1,
+        comment: 'Skill-approval / memory-accept dialogs. action=report. Signature strings are ' +
+            'best-effort across CC versions — the allowlist is DATA, tune as the TUI evolves. #132.',
+    },
+];
+//# sourceMappingURL=stall-signatures.js.map

package/dist/stall-signatures.js.map

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

package/dist/verify-green.d.ts

@@ -0,0 +1,62 @@
+import type { HealthResponse } from './types.js';
+/** Default poll interval between `probe` attempts (ms). */
+export declare const DEFAULT_VERIFY_GREEN_INTERVAL_MS = 2000;
+/** Inputs to `verifyGreen`. */
+export interface VerifyGreenOptions {
+    /** The agent (routing label) to verify — passed straight to `probe`. */
+    readonly agent: string;
+    /** The version the agent must self-report to be considered green. */
+    readonly targetVersion: string;
+    /** Total wall-time budget before giving up (ms). */
+    readonly timeoutMs: number;
+    /** Poll interval between attempts (ms; default `DEFAULT_VERIFY_GREEN_INTERVAL_MS`). */
+    readonly intervalMs?: number;
+}
+/**
+ * Injectable seams for `verifyGreen` — keeps it a pure function of its inputs
+ * (no clock, no network, no timers baked in), so it's unit-testable with a fake
+ * probe sequence + a virtual clock.
+ */
+export interface VerifyGreenDeps {
+    /**
+     * Re-resolve the agent's CURRENT registry endpoint and probe its `/health`.
+     * Returns the parsed body, or `null` when unreachable (offline / mid-restart /
+     * endpoint not yet re-advertised). MUST re-read the registry each call so a
+     * restart-self port churn is picked up (DR-037 Decision 5).
+     */
+    readonly probe: (agent: string) => Promise<HealthResponse | null>;
+    /** Sleep `ms` between poll attempts (injected so tests don't wait). */
+    readonly sleep: (ms: number) => Promise<void>;
+    /** Monotonic-ish clock in ms (injected so tests drive the timeout). */
+    readonly now: () => number;
+}
+/**
+ * The terminal outcome of a `verifyGreen` poll.
+ *
+ * - `ok: true`  — the agent self-reported the target version; `version` echoes it.
+ * - `ok: false` + `reason: 'wrong-version'` — the agent was REACHABLE within the
+ *   budget but never at the target (`lastVersion` is the last version seen, or
+ *   `null` if a reachable body carried no version). The common mid-restart case
+ *   that never converges (bad pin / stuck old process).
+ * - `ok: false` + `reason: 'unreachable'` — the agent was NEVER reachable within
+ *   the budget (every probe returned `null`). The dead / never-relaunched case.
+ */
+export type VerifyGreenResult = {
+    readonly ok: true;
+    readonly version: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'wrong-version' | 'unreachable';
+    readonly lastVersion: string | null;
+};
+/**
+ * Poll `deps.probe(agent)` until the agent self-reports `targetVersion`
+ * (via `compareSemver === 0`) or the `timeoutMs` budget is exhausted.
+ *
+ * Guarantees at least one probe (even with `timeoutMs === 0`), then checks the
+ * elapsed budget BEFORE each `sleep`, so the loop always terminates. The
+ * version comparison uses `compareSemver` (macf-core, macf#424) so a leading
+ * `v` / normalization is handled consistently with the rest of the fleet.
+ */
+export declare function verifyGreen(opts: VerifyGreenOptions, deps: VerifyGreenDeps): Promise<VerifyGreenResult>;
+//# sourceMappingURL=verify-green.d.ts.map

package/dist/verify-green.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-green.d.ts","sourceRoot":"","sources":["../src/verify-green.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,2DAA2D;AAC3D,eAAO,MAAM,gCAAgC,OAAO,CAAC;AAErD,+BAA+B;AAC/B,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uFAAuF;IACvF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAClE,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/C;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC,CAAC;AAEN;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAyB5B"}

package/dist/verify-green.js

@@ -0,0 +1,53 @@
+/**
+ * `verifyGreen` — the shared post-restart health-and-version gate (DR-037
+ * Decision 5). Both the rolling-upgrade sequencer and the reconcile loop need it:
+ * after a `driver.restart(agent)`, confirm the agent came back REACHABLE at the
+ * TARGET version before proceeding to the next agent (upgrade) or clearing the
+ * heal (reconcile).
+ *
+ * Pure + runtime-agnostic (macf-core, DR-037 OQ2). It takes an injectable
+ * "re-resolve + probe" callback and polls-with-timeout. The **re-resolve is the
+ * caller's job, inside `probe`** — `restart-self` relaunches with a NEW port +
+ * instance_id (DR-037 Decision 5), so a correct `probe(agent)` MUST re-read the
+ * registry for the FRESH endpoint on each call and never reuse the dead
+ * pre-restart `host:port` (a silent-fallback trap: a stale endpoint returns
+ * `null` forever → a false "not-green"). `verifyGreen` itself only polls that
+ * callback + applies the version check via macf-core's `compareSemver`.
+ */
+import { compareSemver } from './semver.js';
+/** Default poll interval between `probe` attempts (ms). */
+export const DEFAULT_VERIFY_GREEN_INTERVAL_MS = 2000;
+/**
+ * Poll `deps.probe(agent)` until the agent self-reports `targetVersion`
+ * (via `compareSemver === 0`) or the `timeoutMs` budget is exhausted.
+ *
+ * Guarantees at least one probe (even with `timeoutMs === 0`), then checks the
+ * elapsed budget BEFORE each `sleep`, so the loop always terminates. The
+ * version comparison uses `compareSemver` (macf-core, macf#424) so a leading
+ * `v` / normalization is handled consistently with the rest of the fleet.
+ */
+export async function verifyGreen(opts, deps) {
+    const intervalMs = opts.intervalMs ?? DEFAULT_VERIFY_GREEN_INTERVAL_MS;
+    const start = deps.now();
+    let reachedOnce = false;
+    let lastVersion = null;
+    for (;;) {
+        const health = await deps.probe(opts.agent);
+        if (health) {
+            reachedOnce = true;
+            lastVersion = health.version ?? null;
+            if (lastVersion !== null && compareSemver(lastVersion, opts.targetVersion) === 0) {
+                return { ok: true, version: lastVersion };
+            }
+        }
+        if (deps.now() - start >= opts.timeoutMs) {
+            return {
+                ok: false,
+                reason: reachedOnce ? 'wrong-version' : 'unreachable',
+                lastVersion,
+            };
+        }
+        await deps.sleep(intervalMs);
+    }
+}
+//# sourceMappingURL=verify-green.js.map

package/dist/verify-green.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-green.js","sourceRoot":"","sources":["../src/verify-green.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,2DAA2D;AAC3D,MAAM,CAAC,MAAM,gCAAgC,GAAG,IAAI,CAAC;AAoDrD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAwB,EACxB,IAAqB;IAErB,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,gCAAgC,CAAC;IACvE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,WAAW,GAAkB,IAAI,CAAC;IAEtC,SAAS,CAAC;QACR,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,MAAM,EAAE,CAAC;YACX,WAAW,GAAG,IAAI,CAAC;YACnB,WAAW,GAAG,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC;YACrC,IAAI,WAAW,KAAK,IAAI,IAAI,aAAa,CAAC,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;YAC5C,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACzC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,aAAa;gBACrD,WAAW;aACZ,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundnuty/macf-core",
-  "version": "0.2.44",
+  "version": "0.2.46",
   "description": "Shared internals consumed by the MACF CLI and channel-server packages. Not intended for direct external use — will be marked deprecated-internal on first npm publish per DR-022 Amendment A.",
   "type": "module",
   "main": "dist/index.js",