@groundnuty/macf-core 0.2.44 → 0.2.46

package/dist/discovery.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The workspace-discovery record + its pure helpers (DR-037 Decision 4).
+ *
+ * This is the shared substrate the fleet operational-layer subcommands consume:
+ * `macf ps` (alive∪dead enumeration), `macf fleet upgrade` (group-by-registry →
+ * fleets), and the watchdog (desired-set reconcile) all read the same primitive.
+ *
+ * The record shape + the RUNTIME-and-CLI-independent helpers live HERE in
+ * macf-core (DR-037 OQ2 — pure/portable logic in macf-core); the VM-filesystem
+ * scan that PRODUCES the records is `discoverWorkspaces()` in `packages/macf`
+ * (it's `/proc`- and FS-topology-specific, so it stays driver-side).
+ *
+ * The host-operational plane is registry-FREE (DR-037 Decision 1/4): records are
+ * sourced by scanning the filesystem for the `.macf/` marker, NOT by querying any
+ * registry. This is a search-path *discovery*, not a fourth drift-prone source of
+ * truth (`check-before-propose §4`).
+ */
+import { z } from 'zod';
+import type { RegistryConfig } from './registry/types.js';
+/**
+ * One discovered agent workspace on a host — the unit of the host-operational
+ * plane. Registry-free; produced by the `.macf/`-marker filesystem scan.
+ */
+export declare const WorkspaceRecordSchema: z.ZodObject<{
+    agent: z.ZodString;
+    workspace: z.ZodString;
+    registry: z.ZodString;
+    versionPin: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type WorkspaceRecord = z.infer<typeof WorkspaceRecordSchema>;
+/**
+ * Render a `RegistryConfig` as its stable fleet-grouping identifier (a "fleet"
+ * == a registry — DR-037 Decision 1). Pure.
+ *
+ * - `repo`    → `owner/repo`
+ * - `org`     → the org name
+ * - `profile` → the profile user name (the substrate case: every `groundnuty`
+ *               profile-registry workspace groups into one fleet)
+ * - `local`   → `local` (DR-024)
+ *
+ * Org and profile scopes collapse to a bare name; a theoretical `org foo` vs
+ * `profile foo` collision is accepted for this grouping heuristic (they are not
+ * both used by one host in practice) and keeps the identifier human-legible.
+ */
+export declare function registryIdentifier(config: RegistryConfig): string;
+/**
+ * Split a `MACF_WORKSPACE_ROOT` env value into individual root paths. Pure.
+ * Colon-separated (PATH-style), trimmed, empties dropped. An unset / empty
+ * value yields `[]` so the caller can fall back to its sensible default.
+ */
+export declare function splitWorkspaceRoots(envValue: string | undefined | null): readonly string[];
+/**
+ * De-duplicate workspace records by their canonical `workspace` path, keeping
+ * first occurrence. Pure. Overlapping discovery roots (e.g. `$HOME/repos` and
+ * the parent-of-the-current-workspace) surface the same workspace twice; the
+ * records carry canonical paths so string-equality dedup is exact.
+ */
+export declare function dedupeWorkspaces(records: readonly WorkspaceRecord[]): readonly WorkspaceRecord[];
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;iBAuBhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAWjE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,MAAM,EAAE,CAM1F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,SAAS,eAAe,EAAE,CAS5B"}

package/dist/discovery.js

@@ -0,0 +1,103 @@
+/**
+ * The workspace-discovery record + its pure helpers (DR-037 Decision 4).
+ *
+ * This is the shared substrate the fleet operational-layer subcommands consume:
+ * `macf ps` (alive∪dead enumeration), `macf fleet upgrade` (group-by-registry →
+ * fleets), and the watchdog (desired-set reconcile) all read the same primitive.
+ *
+ * The record shape + the RUNTIME-and-CLI-independent helpers live HERE in
+ * macf-core (DR-037 OQ2 — pure/portable logic in macf-core); the VM-filesystem
+ * scan that PRODUCES the records is `discoverWorkspaces()` in `packages/macf`
+ * (it's `/proc`- and FS-topology-specific, so it stays driver-side).
+ *
+ * The host-operational plane is registry-FREE (DR-037 Decision 1/4): records are
+ * sourced by scanning the filesystem for the `.macf/` marker, NOT by querying any
+ * registry. This is a search-path *discovery*, not a fourth drift-prone source of
+ * truth (`check-before-propose §4`).
+ */
+import { z } from 'zod';
+/**
+ * One discovered agent workspace on a host — the unit of the host-operational
+ * plane. Registry-free; produced by the `.macf/`-marker filesystem scan.
+ */
+export const WorkspaceRecordSchema = z.object({
+    /** The agent's ROUTING label (registry key), e.g. `code-agent` (macf#545). */
+    agent: z.string(),
+    /**
+     * Absolute, symlink-CANONICAL path to the workspace directory (the dir that
+     * contains `.macf/`). Canonical so it can be matched against a running
+     * process's `readlink /proc/<pid>/cwd` even across a symlinked repo root.
+     */
+    workspace: z.string(),
+    /**
+     * The registry this workspace belongs to, as a stable GROUPING identifier —
+     * `owner/repo` (repo scope), the org / profile-user name (org / profile
+     * scope), or `local` (DR-024 local-registry mode). A "fleet" == a registry,
+     * so `fleet upgrade` groups by this field. Derive via `registryIdentifier`.
+     */
+    registry: z.string(),
+    /**
+     * The workspace's pinned framework version (`.macf/macf-agent.json`
+     * `versions.cli`), or `null` when the config carries no pin (legacy / pre-P6).
+     * This is the ON-DISK pin — legible with NO process running, so a DEAD agent
+     * still reports a version (DR-037 Decision 5, the pinned-vs-running split).
+     */
+    versionPin: z.string().nullable(),
+});
+/**
+ * Render a `RegistryConfig` as its stable fleet-grouping identifier (a "fleet"
+ * == a registry — DR-037 Decision 1). Pure.
+ *
+ * - `repo`    → `owner/repo`
+ * - `org`     → the org name
+ * - `profile` → the profile user name (the substrate case: every `groundnuty`
+ *               profile-registry workspace groups into one fleet)
+ * - `local`   → `local` (DR-024)
+ *
+ * Org and profile scopes collapse to a bare name; a theoretical `org foo` vs
+ * `profile foo` collision is accepted for this grouping heuristic (they are not
+ * both used by one host in practice) and keeps the identifier human-legible.
+ */
+export function registryIdentifier(config) {
+    switch (config.type) {
+        case 'repo':
+            return `${config.owner}/${config.repo}`;
+        case 'org':
+            return config.org;
+        case 'profile':
+            return config.user;
+        case 'local':
+            return 'local';
+    }
+}
+/**
+ * Split a `MACF_WORKSPACE_ROOT` env value into individual root paths. Pure.
+ * Colon-separated (PATH-style), trimmed, empties dropped. An unset / empty
+ * value yields `[]` so the caller can fall back to its sensible default.
+ */
+export function splitWorkspaceRoots(envValue) {
+    if (!envValue)
+        return [];
+    return envValue
+        .split(':')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * De-duplicate workspace records by their canonical `workspace` path, keeping
+ * first occurrence. Pure. Overlapping discovery roots (e.g. `$HOME/repos` and
+ * the parent-of-the-current-workspace) surface the same workspace twice; the
+ * records carry canonical paths so string-equality dedup is exact.
+ */
+export function dedupeWorkspaces(records) {
+    const seen = new Set();
+    const out = [];
+    for (const r of records) {
+        if (seen.has(r.workspace))
+            continue;
+        seen.add(r.workspace);
+        out.push(r);
+    }
+    return out;
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,8EAA8E;IAC9E,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB;;;;OAIG;IACH,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB;;;;;OAKG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAIH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAsB;IACvD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,MAAM;YACT,OAAO,GAAG,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAC1C,KAAK,KAAK;YACR,OAAO,MAAM,CAAC,GAAG,CAAC;QACpB,KAAK,SAAS;YACZ,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,KAAK,OAAO;YACV,OAAO,OAAO,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAmC;IACrE,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IACzB,OAAO,QAAQ;SACZ,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAmC;IAEnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;YAAE,SAAS;QACpC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACtB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/fleet-driver.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The `FleetDriver` interface — the decision/driver boundary (DR-037 Decision 3).
+ *
+ * The fleet operational-layer has TWO layers and ONLY the bottom is
+ * runtime-specific:
+ *
+ *   - **Decision layer** (runtime-agnostic): the reconcile HEAL ladder, the
+ *     rolling-upgrade sequencer + verify-green, the busy-gate DECISION, the
+ *     tier-3 `alert` (a `gh issue create` — runtime-agnostic, so it stays in the
+ *     decision layer, NOT on the driver). It NEVER touches `/proc`, tmux,
+ *     `capture-pane`, or the K8s API — it drives off `probe()` (the `/health`
+ *     self-report) and `discoverWorkspaces()`.
+ *   - **Driver layer** (this interface): the ONLY place a runtime leaks. The
+ *     decision layer branches on the reconcile tier and calls a driver verb —
+ *     gated-inject → `inject`; graceful-restart → `restart`; cold-start →
+ *     `launch`; roll → `upgrade`.
+ *
+ * **Hard rule (DR-037):** nothing runtime-specific leaks ABOVE the driver line.
+ * The `agent` argument is the portable identity — the agent's ROUTING LABEL
+ * (the registry key), stable across a VM tmux session, a macOS host, and a
+ * far-future K8s pod. A VM driver resolves that name → workspace + tmux session
+ * INTERNALLY (via `discoverWorkspaces()` + the workspace config); a K8s driver
+ * resolves it → pod. That resolution is the driver's job, never the decision
+ * layer's.
+ *
+ * The interface TYPE lives HERE in macf-core (DR-037 OQ2 — the runtime-and-CLI-
+ * independent contract; it references `WorkspaceRecord`, already here). The
+ * per-runtime driver BODIES live in `packages/macf` (the VM driver) or a future
+ * package (the K8s macf-operator).
+ */
+import { MacfError } from './errors.js';
+import type { WorkspaceRecord } from './discovery.js';
+import type { HealthResponse } from './types.js';
+/**
+ * One agent's routing-plane state as `probe()` sees it: its registry endpoint,
+ * reachability, self-reported framework version, and the raw `/health` body
+ * (which carries `state` idle/busy, `instance_id`, `cert_expiry`, …). Portable —
+ * a VM pin and a K8s pod image self-report identically through `/health`.
+ */
+export interface FleetAgentState {
+    /** The agent's routing label (registry key). */
+    readonly name: string;
+    /** Registry-advertised host. */
+    readonly host: string;
+    /** Registry-advertised port. */
+    readonly port: number;
+    /** `/health` reachable (mTLS 2xx JSON) at the registry endpoint. */
+    readonly online: boolean;
+    /**
+     * The agent's self-reported framework version (`/health.version`, macf#682),
+     * or `null` when offline or reporting a body that predates the field. The
+     * runtime-portable version source (DR-037 Decision 5) — NOT the VM-only pin.
+     */
+    readonly version: string | null;
+    /** Raw `/health` body (incl. `state`/`otel`/`last_processed`), or null when offline. */
+    readonly health: HealthResponse | null;
+}
+/**
+ * The fleet's routing-plane snapshot — the roster plus each member's `/health`
+ * self-report. Built by `FleetDriver.probe()`; consumed by the decision layer's
+ * reconcile ladder + rolling-upgrade sequencer. A plain aggregate (computed from
+ * live probes, not parsed from a wire), so it's a plain interface — not a Zod
+ * schema — mirroring `FleetAgentStatus` in the VM `fleet status` command.
+ */
+export interface FleetState {
+    readonly agents: readonly FleetAgentState[];
+}
+/**
+ * A pluggable fleet driver (DR-037 Decision 3). The runtime-agnostic decision
+ * layer calls these verbs; each concrete driver (VM, macOS, K8s) implements them
+ * with runtime primitives WITHOUT leaking any of that runtime above this line.
+ *
+ * `probe` + `discoverWorkspaces` are the two READ views (routing plane +
+ * host-operational plane, DR-037 Decision 1). The remaining verbs are the
+ * MUTATIONS the reconcile/upgrade decision layer drives; the tier-3 `alert`
+ * (a GH issue) is deliberately NOT here — it is runtime-agnostic and stays in
+ * the decision layer so no GitHub concern leaks into the driver.
+ */
+export interface FleetDriver {
+    /**
+     * The routing-plane snapshot: the registry roster + each agent's mTLS
+     * `/health` (version, idle/busy). Per-agent probe failures are isolated — a
+     * single unreachable peer degrades to `online: false`, never aborts the probe.
+     */
+    readonly probe: () => Promise<FleetState>;
+    /**
+     * The host-operational plane's source (DR-037 Decision 4): the host's agent
+     * workspaces, ALIVE ∪ DEAD, from the registry-free `.macf/`-marker filesystem
+     * scan. VM-filesystem-specific (a K8s driver reads namespaces/labels), so it's
+     * a driver method. Synchronous — a pure FS scan.
+     */
+    readonly discoverWorkspaces: () => readonly WorkspaceRecord[];
+    /**
+     * The aliveness/busy gate — `true` when the agent is actively working and MUST
+     * NOT be restarted. VM: a `capture-pane` content-diff over a short window
+     * (macf#128/#130; NOT `#{session_activity}`, which does not reliably advance on
+     * a busy agent — the 2026-06-28 silent-fallback Pattern-C correction). A
+     * DEAD/absent agent is not busy (safe to `launch`).
+     */
+    readonly isBusy: (agent: string) => Promise<boolean>;
+    /**
+     * Read the agent's current pane content for stall-signature matching
+     * (`macf fleet resume`, DR-037 / macf#686). VM: a single `tmux capture-pane`
+     * of the live session; K8s: recent pod logs. Returns `null` when the agent has
+     * NO live session / is unreadable (DEAD / gone — resume can't help it, so the
+     * caller skips it and leaves it to `reconcile`'s launch). Runtime-specific (a
+     * pane read), so it belongs on the driver — the decision layer stays pure by
+     * matching the returned string against the allowlist.
+     */
+    readonly capturePane: (agent: string) => Promise<string | null>;
+    /** Roll the agent's framework version. VM: `macf update` in its workspace. */
+    readonly upgrade: (agent: string) => Promise<void>;
+    /**
+     * Restart the agent. VM: `macf restart-self` when ALIVE (graceful — stash +
+     * detached relaunch), or `launch` when DEAD. K8s: cycle the pod.
+     */
+    readonly restart: (agent: string) => Promise<void>;
+    /**
+     * The tier-1 gated nudge — deliver `text` into the agent's live turn loop.
+     * VM: the canonical `tmux-send-to-claude` submit pattern. Runtime-specific.
+     */
+    readonly inject: (agent: string, text: string) => Promise<void>;
+    /** Cold-start a desired-but-down agent. VM: spawn its `./claude.sh`. */
+    readonly launch: (agent: string) => Promise<void>;
+}
+/**
+ * A fleet-driver operation failed against a resolvable target — most commonly an
+ * `agent` name that matches no discovered workspace on this host (so the driver
+ * cannot resolve its workspace / session). Runtime-agnostic (every driver shares
+ * it), so it lives in macf-core beside the interface.
+ */
+export declare class FleetDriverError extends MacfError {
+    constructor(message: string);
+}
+//# sourceMappingURL=fleet-driver.d.ts.map

package/dist/fleet-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-driver.d.ts","sourceRoot":"","sources":["../src/fleet-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;CACxC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CAC7C;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IAE1C;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,SAAS,eAAe,EAAE,CAAC;IAE9D;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAErD;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEhE,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,SAAS;gBACjC,OAAO,EAAE,MAAM;CAI5B"}

package/dist/fleet-driver.js

@@ -0,0 +1,44 @@
+/**
+ * The `FleetDriver` interface — the decision/driver boundary (DR-037 Decision 3).
+ *
+ * The fleet operational-layer has TWO layers and ONLY the bottom is
+ * runtime-specific:
+ *
+ *   - **Decision layer** (runtime-agnostic): the reconcile HEAL ladder, the
+ *     rolling-upgrade sequencer + verify-green, the busy-gate DECISION, the
+ *     tier-3 `alert` (a `gh issue create` — runtime-agnostic, so it stays in the
+ *     decision layer, NOT on the driver). It NEVER touches `/proc`, tmux,
+ *     `capture-pane`, or the K8s API — it drives off `probe()` (the `/health`
+ *     self-report) and `discoverWorkspaces()`.
+ *   - **Driver layer** (this interface): the ONLY place a runtime leaks. The
+ *     decision layer branches on the reconcile tier and calls a driver verb —
+ *     gated-inject → `inject`; graceful-restart → `restart`; cold-start →
+ *     `launch`; roll → `upgrade`.
+ *
+ * **Hard rule (DR-037):** nothing runtime-specific leaks ABOVE the driver line.
+ * The `agent` argument is the portable identity — the agent's ROUTING LABEL
+ * (the registry key), stable across a VM tmux session, a macOS host, and a
+ * far-future K8s pod. A VM driver resolves that name → workspace + tmux session
+ * INTERNALLY (via `discoverWorkspaces()` + the workspace config); a K8s driver
+ * resolves it → pod. That resolution is the driver's job, never the decision
+ * layer's.
+ *
+ * The interface TYPE lives HERE in macf-core (DR-037 OQ2 — the runtime-and-CLI-
+ * independent contract; it references `WorkspaceRecord`, already here). The
+ * per-runtime driver BODIES live in `packages/macf` (the VM driver) or a future
+ * package (the K8s macf-operator).
+ */
+import { MacfError } from './errors.js';
+/**
+ * A fleet-driver operation failed against a resolvable target — most commonly an
+ * `agent` name that matches no discovered workspace on this host (so the driver
+ * cannot resolve its workspace / session). Runtime-agnostic (every driver shares
+ * it), so it lives in macf-core beside the interface.
+ */
+export class FleetDriverError extends MacfError {
+    constructor(message) {
+        super('FLEET_DRIVER_ERROR', message);
+        this.name = 'FleetDriverError';
+    }
+}
+//# sourceMappingURL=fleet-driver.js.map

package/dist/fleet-driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-driver.js","sourceRoot":"","sources":["../src/fleet-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AA0GxC;;;;;GAKG;AACH,MAAM,OAAO,gBAAiB,SAAQ,SAAS;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}

package/dist/fleet-reconcile.d.ts

@@ -0,0 +1,180 @@
+/**
+ * The fleet desired-state reconciler — the DR-006 watchdog decision layer,
+ * runtime-agnostic (DR-037 Decision 3 / OQ2). Ports the behavior of the devops
+ * reference `fleet/reconcile.sh` (its 52-case test suite is the acceptance
+ * oracle), but drives everything through the injectable `FleetDriver` + a state
+ * store + a clock, so NOTHING runtime-specific (`/proc`, tmux, `capture-pane`,
+ * the K8s API) leaks above this line.
+ *
+ * The model is Kubernetes-on-a-VM: reconcile ACTUAL (`driver.probe()` +
+ * `driver.discoverWorkspaces()`) toward the operator-owned DESIRED set:
+ *   - desired & not-running       → LAUNCH   (cold-start / reboot-recovery)
+ *   - desired & running-but-deaf  → HEAL     (the tiered ladder)
+ *   - desired-down                → SKIP     (never resurrect — don't-fight-the-operator)
+ *       desired-down = an explicit `paused` sentinel OR `last-exit == 0` (the
+ *       operator typed `/exit`) — the two compose (DR-031 §A.3 unification).
+ *   - desired & reachable         → OK
+ *
+ * The HEAL ladder, per deaf agent, across sweeps (the cron gives the cross-sweep
+ * memory):
+ *   - sweep 1        → Tier-1 gated inject (`driver.inject` — the agent self-heals)
+ *   - sweep 2+       → escalate, under two GATES that both hold before any restart:
+ *       * aliveness-gate — NEVER restart a busy agent (`driver.isBusy`; the #642
+ *         mode: channel-server dead while the TUI is alive + working).
+ *       * restart-backoff — NEVER restart-storm a repeatedly-failing agent: after a
+ *         Tier-2 restart, an EXPONENTIAL backoff window must elapse before the next
+ *         one; a persistently-stuck agent (restarts exhausted) escalates to Tier-3.
+ *     Tier-2 graceful-restart (`driver.restart`) is held behind `allowRestart`;
+ *     Tier-3 `alert` (a `gh issue create`) is a DECISION-LAYER seam — deliberately
+ *     NOT a `FleetDriver` method, so no GitHub concern leaks into the driver.
+ *
+ * Plus launch-stagger (space cold-starts so N dead agents don't thundering-herd)
+ * and a self-heartbeat (the who-watches-the-watchdog signal). DRY-RUN BY DEFAULT
+ * — the report is built + printed and NOTHING is acted on or persisted unless
+ * `execute` is set.
+ */
+import type { FleetDriver, FleetState } from './fleet-driver.js';
+/** One agent the operator declares SHOULD run on this host (DR-006 §A.2). */
+export interface DesiredAgent {
+    /** The routing-label identity (matches `FleetState.agents[].name`). */
+    readonly agent: string;
+    /** Absolute workspace dir — surfaced in the LAUNCH detail (driver resolves it). */
+    readonly workspace: string;
+}
+/** The four reconcile verdicts (the report's DECISION column). */
+export type ReconcileDecision = 'OK' | 'LAUNCH' | 'SKIP' | 'HEAL';
+/**
+ * Per-agent state that persists ACROSS sweeps (the cron's cross-sweep memory).
+ * Read at the start of each agent's reconcile, written back only on `execute`.
+ */
+export interface ReconcileAgentState {
+    /** Consecutive HEAL (deaf) sweeps — drives Tier-1 → escalation. */
+    readonly deafSweeps: number;
+    /** Consecutive Tier-2 restarts — the EXPONENTIAL-backoff exponent + stuck gauge. */
+    readonly restartAttempts: number;
+    /** Epoch-ms before which a Tier-2 restart is suppressed (the backoff window). */
+    readonly backoffUntil: number;
+    /** Tier-3 alert dedup sentinel (one alert per failure episode). */
+    readonly alertOpen: boolean;
+    /** Last observed process exit code (exit-code intent; `null` = absent/never-ran). */
+    readonly lastExit: number | null;
+    /** Explicit operator `paused` sentinel → desired-down. */
+    readonly paused: boolean;
+}
+/** The zero state for an agent with no persisted history. */
+export declare const EMPTY_RECONCILE_STATE: ReconcileAgentState;
+/**
+ * Cross-sweep persisted state. Reads are pure lookups (defaulting to
+ * `EMPTY_RECONCILE_STATE`); writes/resets happen only when the engine is in
+ * `execute` mode (the caller gates them), so a dry-run is side-effect-free.
+ */
+export interface ReconcileStateStore {
+    /** Current persisted state for `agent` (never throws — unknown → empty). */
+    readonly read: (agent: string) => ReconcileAgentState;
+    /** Persist `state` for `agent`. Only called on `execute`. */
+    readonly write: (agent: string, state: ReconcileAgentState) => void;
+    /**
+     * Recovery reset — clear the escalation/backoff/alert counters (KEEP
+     * `lastExit`/`paused`), so a future deaf episode starts a fresh ladder. Only
+     * called on `execute`.
+     */
+    readonly reset: (agent: string) => void;
+}
+/** Tuning knobs for the ladder / backoff / stagger. */
+export interface ReconcileConfig {
+    /** Act (launch/inject/restart/alert/heartbeat/persist). `false` = dry-run (default). */
+    readonly execute: boolean;
+    /** Enable Tier-2 graceful-restart (operator sign-off). `false` → held. */
+    readonly allowRestart: boolean;
+    /** Deaf sweeps that stay on Tier-1 before escalating (default 1). */
+    readonly escalateAfterSweeps: number;
+    /** Base backoff (ms) — the first restart window (default 60_000). */
+    readonly backoffBaseMs: number;
+    /** Backoff ceiling (ms) — the exponential is clamped here (default 3_600_000). */
+    readonly backoffMaxMs: number;
+    /** Restart attempts beyond which a still-deaf agent is STUCK → Tier-3 (default 3). */
+    readonly stuckMax: number;
+    /** Delay (ms) inserted BETWEEN cold-start launches to avoid a thundering herd (default 15_000). */
+    readonly launchStaggerMs: number;
+    /** The Tier-1 self-diagnose nudge text delivered by `driver.inject`. */
+    readonly injectMessage: string;
+}
+/** Sensible defaults; a caller overrides selectively via `resolveConfig`. */
+export declare const DEFAULT_RECONCILE_CONFIG: ReconcileConfig;
+/** Merge partial overrides onto the defaults. */
+export declare function resolveReconcileConfig(overrides?: Partial<ReconcileConfig>): ReconcileConfig;
+/** Info recorded by the self-heartbeat (execute-only). */
+export interface ReconcileHeartbeat {
+    /** The sweep's exit code. */
+    readonly rc: number;
+    /** Wall-clock (epoch ms) the sweep completed. */
+    readonly at: number;
+    /** Whether Tier-2 restart was enabled this sweep. */
+    readonly restartEnabled: boolean;
+}
+/**
+ * The injectable seams the reconcile orchestrator drives — all runtime-agnostic.
+ * The tier-3 `alert` is HERE (a decision-layer seam), NOT on `driver`: it is a
+ * GitHub concern, runtime-agnostic, so per DR-037 it must never leak into a
+ * per-runtime driver.
+ */
+export interface ReconcileDeps {
+    /** The pluggable fleet driver (probe + the mutation verbs). */
+    readonly driver: FleetDriver;
+    /** Cross-sweep persisted state. */
+    readonly store: ReconcileStateStore;
+    /** Monotonic-ish clock (ms) — injected so tests drive backoff/stagger timing. */
+    readonly now: () => number;
+    /** Sleep `ms` — injected so tests don't wait on the launch-stagger. */
+    readonly sleep: (ms: number) => Promise<void>;
+    /** Tier-3 alert (a `gh issue create`) — decision-layer, dedup'd by the caller. */
+    readonly alert: (agent: string, reason: string) => Promise<void>;
+    /** Self-heartbeat — the who-watches-the-watchdog stamp (execute-only). */
+    readonly heartbeat: (info: ReconcileHeartbeat) => Promise<void>;
+    /** Emit one report line (the command wires it to stdout). */
+    readonly log: (line: string) => void;
+}
+/** One row of the reconcile report. */
+export interface ReconcileRow {
+    readonly agent: string;
+    readonly decision: ReconcileDecision;
+    readonly detail: string;
+}
+/**
+ * The sweep outcome. `rc` mirrors the reference exit contract:
+ *   - 0 = every desired agent OK / down (no action)
+ *   - 1 = action(s) taken or needed
+ *   - 2 = precondition/probe failure (bad manifest, probe threw)
+ */
+export interface ReconcileResult {
+    readonly rc: number;
+    readonly rows: readonly ReconcileRow[];
+}
+/**
+ * How the probe sees a desired agent (three-valued, mirroring the reference's
+ * empty/`true`/`false` `reachable` field):
+ *   - `absent`    — not in the registry roster at all (not running / never registered)
+ *   - `deaf`      — in the roster but `/health` did NOT answer (registered, channel down)
+ *   - `reachable` — in the roster + `/health` answered (mTLS 2xx)
+ */
+export declare function classifyReachability(state: FleetState, agent: string): 'absent' | 'deaf' | 'reachable';
+/**
+ * The EXPONENTIAL restart-backoff window after `attempts` consecutive restarts:
+ * `base * 2^(attempts-1)`, clamped to `maxMs`. `attempts <= 0` → no window (0).
+ */
+export declare function nextBackoffMs(attempts: number, config: ReconcileConfig): number;
+/**
+ * Minimal parser for the fixed `desired-agents.yaml` shape (no yaml dep — the
+ * cron-light awk parse's TS twin). Pairs each `- agent: <x>` with the FOLLOWING
+ * `workspace: <y>`; strips inline `# comments` + surrounding quotes; ignores the
+ * `agents:` header, blank lines, and standalone comments.
+ */
+export declare function parseDesiredAgents(text: string): DesiredAgent[];
+/**
+ * Run one reconcile sweep over the `desired` set. Probes ACTUAL state, decides +
+ * (on `execute`) acts per agent through the injected driver + seams, and returns
+ * the report + exit code. Dry-run (the default) prints the report and touches
+ * nothing (no driver mutations, no state writes, no heartbeat).
+ */
+export declare function reconcileFleet(desired: readonly DesiredAgent[], deps: ReconcileDeps, config: ReconcileConfig): Promise<ReconcileResult>;
+//# sourceMappingURL=fleet-reconcile.d.ts.map

package/dist/fleet-reconcile.d.ts.map

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