@claude-flow/plugin-agent-federation 1.0.0-alpha.5 → 1.0.0-alpha.7

package/dist/domain/value-objects/federation-budget.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Federation budget + hop counter (ADR-097 Phase 1).
+ *
+ * Carried in {@link FederationEnvelope} alongside the existing
+ * sourceNodeId/targetNodeId/payload. Sender supplies the original limits;
+ * each outbound hop increments hopCount and decrements remaining budget.
+ *
+ * Phase 1 enforces at the *send* side because there is no inbound
+ * dispatcher today (sendToNode is a stub — see researcher report).
+ * Phase 2 will move the decrement to receive once the inbound path lands.
+ *
+ * Security invariants pinned by the reviewer (audit_1776853149979 follow-up):
+ *
+ *   1. validateBudget rejects NaN, ±Infinity, negative numbers, and
+ *      non-integer hop counts. Returns a discriminated result so callers
+ *      cannot accidentally use a bad budget unchecked.
+ *   2. enforceBudget runs check-then-decrement in a single synchronous
+ *      function with no awaits inside — two concurrent send calls cannot
+ *      both pass the pre-check.
+ *   3. Errors return constant strings ("HOP_LIMIT_EXCEEDED" /
+ *      "BUDGET_EXCEEDED") with no remaining-budget echo so a caller can't
+ *      use the error response as an oracle for the threshold.
+ */
+/** Maximum hops a federation message may travel before the breaker opens. */
+export declare const DEFAULT_MAX_HOPS = 8;
+/**
+ * Caller-supplied budget. All fields are optional; omitted fields are
+ * treated as Infinity for the corresponding axis. Created via validateBudget;
+ * never construct directly.
+ */
+export interface Budget {
+    readonly maxHops: number;
+    readonly maxTokens: number;
+    readonly maxUsd: number;
+}
+/** Discriminated result of validating raw user input into a Budget. */
+export type BudgetValidationResult = {
+    ok: true;
+    budget: Budget;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validate a raw budget object. Pure, no side effects. Caller obtains either
+ * a guaranteed-safe Budget or a structured error suitable for logging.
+ *
+ * Accepts undefined/null and returns a default unbounded budget (maxHops =
+ * DEFAULT_MAX_HOPS, tokens/usd = Infinity). This preserves backward
+ * compatibility for callers that don't pass a budget at all.
+ */
+export declare function validateBudget(raw: unknown, overrideMaxHops?: unknown): BudgetValidationResult;
+/**
+ * Enforcement decision returned by enforceBudget. Discriminated so the
+ * caller can map directly to a constant-string error — no remaining-budget
+ * echo on the failure side (anti-oracle).
+ */
+export type BudgetEnforcement = {
+    ok: true;
+    nextHopCount: number;
+    remaining: Budget;
+} | {
+    ok: false;
+    reason: 'HOP_LIMIT_EXCEEDED' | 'BUDGET_EXCEEDED';
+};
+/**
+ * Atomic (single synchronous function, no internal awaits) hop check.
+ *
+ * Returns the hopCount value the OUTBOUND envelope should carry plus the
+ * remaining budget that downstream peers will see. Callers must use the
+ * returned values; mutating the input Budget is forbidden (it's readonly).
+ *
+ * Contract:
+ *   - hopCount represents how many hops the message has already taken.
+ *   - The next outbound hop increments it: nextHopCount = hopCount + 1.
+ *   - The check fires AFTER increment: nextHopCount must be <= maxHops.
+ *   - This means maxHops=0 refuses to forward at all, which matches the
+ *     ADR's "no remote delegation allowed" semantic.
+ *
+ * tokensSpent / usdSpent are caller-reported actuals from the immediately
+ * preceding leg (or 0 on the originator). The check fires on the
+ * *post-spend* totals so a leg that overshoots is caught before the next
+ * outbound dispatch.
+ */
+export declare function enforceBudget(budget: Budget, hopCount: number, spent?: {
+    tokens: number;
+    usd: number;
+}): BudgetEnforcement;
+//# sourceMappingURL=federation-budget.d.ts.map

package/dist/domain/value-objects/federation-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation-budget.d.ts","sourceRoot":"","sources":["../../../src/domain/value-objects/federation-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAQlC;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,uEAAuE;AACvE,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,eAAe,CAAC,EAAE,OAAO,GACxB,sBAAsB,CA6DxB;AAkCD;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,oBAAoB,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAEpE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAA0B,GAC7D,iBAAiB,CAuBnB"}

package/dist/domain/value-objects/federation-budget.js

@@ -0,0 +1,165 @@
+/**
+ * Federation budget + hop counter (ADR-097 Phase 1).
+ *
+ * Carried in {@link FederationEnvelope} alongside the existing
+ * sourceNodeId/targetNodeId/payload. Sender supplies the original limits;
+ * each outbound hop increments hopCount and decrements remaining budget.
+ *
+ * Phase 1 enforces at the *send* side because there is no inbound
+ * dispatcher today (sendToNode is a stub — see researcher report).
+ * Phase 2 will move the decrement to receive once the inbound path lands.
+ *
+ * Security invariants pinned by the reviewer (audit_1776853149979 follow-up):
+ *
+ *   1. validateBudget rejects NaN, ±Infinity, negative numbers, and
+ *      non-integer hop counts. Returns a discriminated result so callers
+ *      cannot accidentally use a bad budget unchecked.
+ *   2. enforceBudget runs check-then-decrement in a single synchronous
+ *      function with no awaits inside — two concurrent send calls cannot
+ *      both pass the pre-check.
+ *   3. Errors return constant strings ("HOP_LIMIT_EXCEEDED" /
+ *      "BUDGET_EXCEEDED") with no remaining-budget echo so a caller can't
+ *      use the error response as an oracle for the threshold.
+ */
+/** Maximum hops a federation message may travel before the breaker opens. */
+export const DEFAULT_MAX_HOPS = 8;
+/** Hard ceiling on caller-supplied maxUsd to prevent absurd integer math. */
+const MAX_USD_CEILING = 1_000_000;
+/** Hard ceiling on caller-supplied maxTokens. 1B tokens is more than any real session. */
+const MAX_TOKENS_CEILING = 1_000_000_000;
+/** Hard ceiling on hop count. */
+const MAX_HOPS_CEILING = 64;
+/**
+ * Validate a raw budget object. Pure, no side effects. Caller obtains either
+ * a guaranteed-safe Budget or a structured error suitable for logging.
+ *
+ * Accepts undefined/null and returns a default unbounded budget (maxHops =
+ * DEFAULT_MAX_HOPS, tokens/usd = Infinity). This preserves backward
+ * compatibility for callers that don't pass a budget at all.
+ */
+export function validateBudget(raw, overrideMaxHops) {
+    // Default unbounded budget when caller passes nothing.
+    if (raw == null && overrideMaxHops == null) {
+        return {
+            ok: true,
+            budget: {
+                maxHops: DEFAULT_MAX_HOPS,
+                maxTokens: Number.POSITIVE_INFINITY,
+                maxUsd: Number.POSITIVE_INFINITY,
+            },
+        };
+    }
+    // Caller passed a bare maxHops without a budget object — accept it as a
+    // hop-only budget. Useful for "no remote delegation allowed" via
+    // maxHops: 0.
+    if (raw == null && overrideMaxHops != null) {
+        const hopCheck = checkHops(overrideMaxHops);
+        if (!hopCheck.ok)
+            return hopCheck;
+        return {
+            ok: true,
+            budget: {
+                maxHops: hopCheck.value,
+                maxTokens: Number.POSITIVE_INFINITY,
+                maxUsd: Number.POSITIVE_INFINITY,
+            },
+        };
+    }
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, error: 'budget must be an object' };
+    }
+    const obj = raw;
+    const hopsRaw = overrideMaxHops ?? obj.maxHops;
+    const hopCheck = hopsRaw == null
+        ? { ok: true, value: DEFAULT_MAX_HOPS }
+        : checkHops(hopsRaw);
+    if (!hopCheck.ok)
+        return hopCheck;
+    const tokensCheck = obj.maxTokens == null
+        ? { ok: true, value: Number.POSITIVE_INFINITY }
+        : checkBound(obj.maxTokens, MAX_TOKENS_CEILING, 'maxTokens', true);
+    if (!tokensCheck.ok)
+        return tokensCheck;
+    const usdCheck = obj.maxUsd == null
+        ? { ok: true, value: Number.POSITIVE_INFINITY }
+        : checkBound(obj.maxUsd, MAX_USD_CEILING, 'maxUsd', false);
+    if (!usdCheck.ok)
+        return usdCheck;
+    return {
+        ok: true,
+        budget: {
+            maxHops: hopCheck.value,
+            maxTokens: tokensCheck.value,
+            maxUsd: usdCheck.value,
+        },
+    };
+}
+function checkHops(v) {
+    if (typeof v !== 'number' || !Number.isFinite(v) || !Number.isInteger(v)) {
+        return { ok: false, error: 'maxHops must be a finite integer' };
+    }
+    if (v < 0)
+        return { ok: false, error: 'maxHops must be >= 0' };
+    if (v > MAX_HOPS_CEILING) {
+        return { ok: false, error: `maxHops exceeds ceiling (${MAX_HOPS_CEILING})` };
+    }
+    return { ok: true, value: v };
+}
+function checkBound(v, ceiling, label, requireInteger) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+        return { ok: false, error: `${label} must be a finite number` };
+    }
+    if (requireInteger && !Number.isInteger(v)) {
+        return { ok: false, error: `${label} must be an integer` };
+    }
+    if (v < 0)
+        return { ok: false, error: `${label} must be >= 0` };
+    if (v > ceiling) {
+        return { ok: false, error: `${label} exceeds ceiling (${ceiling})` };
+    }
+    return { ok: true, value: v };
+}
+/**
+ * Atomic (single synchronous function, no internal awaits) hop check.
+ *
+ * Returns the hopCount value the OUTBOUND envelope should carry plus the
+ * remaining budget that downstream peers will see. Callers must use the
+ * returned values; mutating the input Budget is forbidden (it's readonly).
+ *
+ * Contract:
+ *   - hopCount represents how many hops the message has already taken.
+ *   - The next outbound hop increments it: nextHopCount = hopCount + 1.
+ *   - The check fires AFTER increment: nextHopCount must be <= maxHops.
+ *   - This means maxHops=0 refuses to forward at all, which matches the
+ *     ADR's "no remote delegation allowed" semantic.
+ *
+ * tokensSpent / usdSpent are caller-reported actuals from the immediately
+ * preceding leg (or 0 on the originator). The check fires on the
+ * *post-spend* totals so a leg that overshoots is caught before the next
+ * outbound dispatch.
+ */
+export function enforceBudget(budget, hopCount, spent = { tokens: 0, usd: 0 }) {
+    const nextHopCount = hopCount + 1;
+    if (nextHopCount > budget.maxHops) {
+        return { ok: false, reason: 'HOP_LIMIT_EXCEEDED' };
+    }
+    // Negative spend is a programming error; treat as 0 rather than refunding
+    // the budget (which would let a malicious caller inflate remaining).
+    const ts = Math.max(0, spent.tokens);
+    const us = Math.max(0, spent.usd);
+    const remainingTokens = budget.maxTokens - ts;
+    const remainingUsd = budget.maxUsd - us;
+    if (remainingTokens < 0 || remainingUsd < 0) {
+        return { ok: false, reason: 'BUDGET_EXCEEDED' };
+    }
+    return {
+        ok: true,
+        nextHopCount,
+        remaining: {
+            maxHops: budget.maxHops,
+            maxTokens: remainingTokens,
+            maxUsd: remainingUsd,
+        },
+    };
+}
+//# sourceMappingURL=federation-budget.js.map

package/dist/domain/value-objects/federation-budget.js.map

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

package/dist/domain/value-objects/federation-node-state.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Federation peer state machine (ADR-097 Phase 2).
+ *
+ * Phase 1 shipped the budget envelope + enforcer that travels with every
+ * outbound message. Phase 2 adds the per-peer breaker: when a peer crosses a
+ * cost or failure threshold, transition it to SUSPENDED so subsequent
+ * `federation_send` calls short-circuit. After a cooldown the peer can
+ * recover; if it stays bad the breaker escalates to EVICTED.
+ *
+ * This module is the *value object* layer — pure, no I/O. The breaker
+ * service (Phase 2.b, separate file) reads cost-tracker telemetry, evaluates
+ * thresholds, and calls `transition` on the FederationNode entity. Decoupling
+ * the state machine from the policy lets tests pin transitions without
+ * standing up the cost bus.
+ *
+ * Security invariants pinned by the spec:
+ *
+ *   1. EVICTED is terminal under normal flow. The only way out is an
+ *      explicit `reactivate` call (operator-initiated). This prevents a
+ *      misbehaving peer from auto-recovering through the cooldown.
+ *   2. canTransition is the single source of truth for legality. Any path
+ *      that mutates state MUST consult it; direct field writes are not
+ *      permitted (entity getter/setter shape enforces this).
+ *   3. Reasons are constant strings, no remaining-budget echo on failure
+ *      (matches Phase 1's anti-oracle posture).
+ *   4. Default cooldown is conservative (30 min) so a transient spike
+ *      cannot ping-pong a peer ACTIVE↔SUSPENDED at high frequency.
+ */
+/** Lifecycle state of a federation peer. */
+export declare enum FederationNodeState {
+    /** Default; healthy. `federation_send` accepts deliveries. */
+    ACTIVE = "ACTIVE",
+    /** Breaker tripped. Sends short-circuit with PEER_SUSPENDED. */
+    SUSPENDED = "SUSPENDED",
+    /** Removed from active rotation. Sends short-circuit with PEER_EVICTED. */
+    EVICTED = "EVICTED"
+}
+/** Reason a peer was suspended/evicted. Constant strings — no echo of caps. */
+export type SuspensionReason = 'COST_THRESHOLD_EXCEEDED' | 'FAILURE_RATIO_EXCEEDED' | 'MANUAL_SUSPEND' | 'GRACE_PERIOD_EXPIRED' | 'MANUAL_EVICT';
+/**
+ * Default cooldown a SUSPENDED peer must wait before being eligible for
+ * SUSPENDED → ACTIVE. 30 minutes matches the ADR-097 Part 2 spec and is
+ * intentionally well past the prompt-cache window so a recovery probe is
+ * cheap to amortize.
+ */
+export declare const DEFAULT_SUSPENSION_COOLDOWN_MS: number;
+/**
+ * Default age at which a continuously-SUSPENDED peer is auto-escalated to
+ * EVICTED. 24 hours per spec — long enough to ride out a cost-tracker
+ * outage without false eviction, short enough that a genuinely-broken peer
+ * doesn't linger forever.
+ */
+export declare const DEFAULT_AUTO_EVICTION_AGE_MS: number;
+/** A successful transition's reason payload (for the audit trail). */
+export interface TransitionReason {
+    readonly reason: SuspensionReason;
+    /** Optional opaque correlation key — task ID, breaker run ID, etc. */
+    readonly correlationId?: string;
+}
+/**
+ * Static legality table for state transitions. Returns true iff the
+ * `from -> to` edge is in the allowed set. Used by the entity to reject
+ * illegal mutations before applying them.
+ *
+ * Allowed edges:
+ *   ACTIVE    → SUSPENDED  (breaker trips)
+ *   SUSPENDED → ACTIVE     (cooldown + probe success)
+ *   SUSPENDED → EVICTED    (grace expired, or manual evict)
+ *   ACTIVE    → EVICTED    (manual evict only — skips suspend)
+ *   EVICTED   → ACTIVE     (manual reactivate only)
+ *
+ * Disallowed (anything else, including self-loops, is a no-op error).
+ */
+export declare function canTransition(from: FederationNodeState, to: FederationNodeState): boolean;
+/**
+ * Should a SUSPENDED peer be eligible for SUSPENDED → ACTIVE based purely
+ * on elapsed time? The breaker still has to confirm health via probe before
+ * it actually calls reactivate; this just answers "is the cooldown done?"
+ *
+ * Pure function of (suspendedAt, now, cooldownMs) so it's trivially
+ * deterministic in tests.
+ */
+export declare function isCooldownElapsed(suspendedAt: Date, now: Date, cooldownMs?: number): boolean;
+/**
+ * Should a SUSPENDED peer be auto-escalated to EVICTED based on the age of
+ * its suspension? Returns true once the peer has been continuously
+ * SUSPENDED past the configured limit (default 24h). The breaker calls
+ * this on each tick and, if true, issues the SUSPENDED → EVICTED
+ * transition with reason GRACE_PERIOD_EXPIRED.
+ */
+export declare function shouldAutoEvict(suspendedAt: Date, now: Date, ageLimitMs?: number): boolean;
+//# sourceMappingURL=federation-node-state.d.ts.map

package/dist/domain/value-objects/federation-node-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation-node-state.d.ts","sourceRoot":"","sources":["../../../src/domain/value-objects/federation-node-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,4CAA4C;AAC5C,oBAAY,mBAAmB;IAC7B,8DAA8D;IAC9D,MAAM,WAAW;IACjB,gEAAgE;IAChE,SAAS,cAAc;IACvB,2EAA2E;IAC3E,OAAO,YAAY;CACpB;AAED,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GACxB,yBAAyB,GACzB,wBAAwB,GACxB,gBAAgB,GAChB,sBAAsB,GACtB,cAAc,CAAC;AAEnB;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,QAAiB,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,QAAsB,CAAC;AAEhE,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,mBAAmB,EACzB,EAAE,EAAE,mBAAmB,GACtB,OAAO,CAUT;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,IAAI,EACjB,GAAG,EAAE,IAAI,EACT,UAAU,GAAE,MAAuC,GAClD,OAAO,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,IAAI,EACjB,GAAG,EAAE,IAAI,EACT,UAAU,GAAE,MAAqC,GAChD,OAAO,CAET"}

package/dist/domain/value-objects/federation-node-state.js

@@ -0,0 +1,100 @@
+/**
+ * Federation peer state machine (ADR-097 Phase 2).
+ *
+ * Phase 1 shipped the budget envelope + enforcer that travels with every
+ * outbound message. Phase 2 adds the per-peer breaker: when a peer crosses a
+ * cost or failure threshold, transition it to SUSPENDED so subsequent
+ * `federation_send` calls short-circuit. After a cooldown the peer can
+ * recover; if it stays bad the breaker escalates to EVICTED.
+ *
+ * This module is the *value object* layer — pure, no I/O. The breaker
+ * service (Phase 2.b, separate file) reads cost-tracker telemetry, evaluates
+ * thresholds, and calls `transition` on the FederationNode entity. Decoupling
+ * the state machine from the policy lets tests pin transitions without
+ * standing up the cost bus.
+ *
+ * Security invariants pinned by the spec:
+ *
+ *   1. EVICTED is terminal under normal flow. The only way out is an
+ *      explicit `reactivate` call (operator-initiated). This prevents a
+ *      misbehaving peer from auto-recovering through the cooldown.
+ *   2. canTransition is the single source of truth for legality. Any path
+ *      that mutates state MUST consult it; direct field writes are not
+ *      permitted (entity getter/setter shape enforces this).
+ *   3. Reasons are constant strings, no remaining-budget echo on failure
+ *      (matches Phase 1's anti-oracle posture).
+ *   4. Default cooldown is conservative (30 min) so a transient spike
+ *      cannot ping-pong a peer ACTIVE↔SUSPENDED at high frequency.
+ */
+/** Lifecycle state of a federation peer. */
+export var FederationNodeState;
+(function (FederationNodeState) {
+    /** Default; healthy. `federation_send` accepts deliveries. */
+    FederationNodeState["ACTIVE"] = "ACTIVE";
+    /** Breaker tripped. Sends short-circuit with PEER_SUSPENDED. */
+    FederationNodeState["SUSPENDED"] = "SUSPENDED";
+    /** Removed from active rotation. Sends short-circuit with PEER_EVICTED. */
+    FederationNodeState["EVICTED"] = "EVICTED";
+})(FederationNodeState || (FederationNodeState = {}));
+/**
+ * Default cooldown a SUSPENDED peer must wait before being eligible for
+ * SUSPENDED → ACTIVE. 30 minutes matches the ADR-097 Part 2 spec and is
+ * intentionally well past the prompt-cache window so a recovery probe is
+ * cheap to amortize.
+ */
+export const DEFAULT_SUSPENSION_COOLDOWN_MS = 30 * 60 * 1000;
+/**
+ * Default age at which a continuously-SUSPENDED peer is auto-escalated to
+ * EVICTED. 24 hours per spec — long enough to ride out a cost-tracker
+ * outage without false eviction, short enough that a genuinely-broken peer
+ * doesn't linger forever.
+ */
+export const DEFAULT_AUTO_EVICTION_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Static legality table for state transitions. Returns true iff the
+ * `from -> to` edge is in the allowed set. Used by the entity to reject
+ * illegal mutations before applying them.
+ *
+ * Allowed edges:
+ *   ACTIVE    → SUSPENDED  (breaker trips)
+ *   SUSPENDED → ACTIVE     (cooldown + probe success)
+ *   SUSPENDED → EVICTED    (grace expired, or manual evict)
+ *   ACTIVE    → EVICTED    (manual evict only — skips suspend)
+ *   EVICTED   → ACTIVE     (manual reactivate only)
+ *
+ * Disallowed (anything else, including self-loops, is a no-op error).
+ */
+export function canTransition(from, to) {
+    if (from === to)
+        return false;
+    if (from === FederationNodeState.ACTIVE) {
+        return to === FederationNodeState.SUSPENDED || to === FederationNodeState.EVICTED;
+    }
+    if (from === FederationNodeState.SUSPENDED) {
+        return to === FederationNodeState.ACTIVE || to === FederationNodeState.EVICTED;
+    }
+    // EVICTED is terminal except for explicit operator reactivate.
+    return to === FederationNodeState.ACTIVE;
+}
+/**
+ * Should a SUSPENDED peer be eligible for SUSPENDED → ACTIVE based purely
+ * on elapsed time? The breaker still has to confirm health via probe before
+ * it actually calls reactivate; this just answers "is the cooldown done?"
+ *
+ * Pure function of (suspendedAt, now, cooldownMs) so it's trivially
+ * deterministic in tests.
+ */
+export function isCooldownElapsed(suspendedAt, now, cooldownMs = DEFAULT_SUSPENSION_COOLDOWN_MS) {
+    return now.getTime() - suspendedAt.getTime() >= cooldownMs;
+}
+/**
+ * Should a SUSPENDED peer be auto-escalated to EVICTED based on the age of
+ * its suspension? Returns true once the peer has been continuously
+ * SUSPENDED past the configured limit (default 24h). The breaker calls
+ * this on each tick and, if true, issues the SUSPENDED → EVICTED
+ * transition with reason GRACE_PERIOD_EXPIRED.
+ */
+export function shouldAutoEvict(suspendedAt, now, ageLimitMs = DEFAULT_AUTO_EVICTION_AGE_MS) {
+    return now.getTime() - suspendedAt.getTime() >= ageLimitMs;
+}
+//# sourceMappingURL=federation-node-state.js.map

package/dist/domain/value-objects/federation-node-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation-node-state.js","sourceRoot":"","sources":["../../../src/domain/value-objects/federation-node-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,4CAA4C;AAC5C,MAAM,CAAN,IAAY,mBAOX;AAPD,WAAY,mBAAmB;IAC7B,8DAA8D;IAC9D,wCAAiB,CAAA;IACjB,gEAAgE;IAChE,8CAAuB,CAAA;IACvB,2EAA2E;IAC3E,0CAAmB,CAAA;AACrB,CAAC,EAPW,mBAAmB,KAAnB,mBAAmB,QAO9B;AAUD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAShE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAyB,EACzB,EAAuB;IAEvB,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC9B,IAAI,IAAI,KAAK,mBAAmB,CAAC,MAAM,EAAE,CAAC;QACxC,OAAO,EAAE,KAAK,mBAAmB,CAAC,SAAS,IAAI,EAAE,KAAK,mBAAmB,CAAC,OAAO,CAAC;IACpF,CAAC;IACD,IAAI,IAAI,KAAK,mBAAmB,CAAC,SAAS,EAAE,CAAC;QAC3C,OAAO,EAAE,KAAK,mBAAmB,CAAC,MAAM,IAAI,EAAE,KAAK,mBAAmB,CAAC,OAAO,CAAC;IACjF,CAAC;IACD,+DAA+D;IAC/D,OAAO,EAAE,KAAK,mBAAmB,CAAC,MAAM,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,WAAiB,EACjB,GAAS,EACT,aAAqB,8BAA8B;IAEnD,OAAO,GAAG,CAAC,OAAO,EAAE,GAAG,WAAW,CAAC,OAAO,EAAE,IAAI,UAAU,CAAC;AAC7D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,WAAiB,EACjB,GAAS,EACT,aAAqB,4BAA4B;IAEjD,OAAO,GAAG,CAAC,OAAO,EAAE,GAAG,WAAW,CAAC,OAAO,EAAE,IAAI,UAAU,CAAC;AAC7D,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { AgentFederationPlugin } from './plugin.js';
-export { FederationNode, type FederationNodeProps, type FederationNodeCapabilities, type FederationNodeMetadata } from './domain/entities/federation-node.js';
+export { FederationNode, type FederationNodeProps, type FederationNodeCapabilities, type FederationNodeMetadata, type FederationNodeStateRecord } from './domain/entities/federation-node.js';
+export { FederationNodeState, type SuspensionReason, type TransitionReason, canTransition, isCooldownElapsed, shouldAutoEvict, DEFAULT_SUSPENSION_COOLDOWN_MS, DEFAULT_AUTO_EVICTION_AGE_MS, } from './domain/value-objects/federation-node-state.js';
+export { FederationBreakerService, evaluatePolicy, DEFAULT_BREAKER_POLICY, DEFAULT_MAX_SAMPLES_PER_PEER, type BreakerPolicy, type BreakerDecision, type SendOutcome, } from './application/federation-breaker-service.js';
 export { FederationSession, type FederationSessionProps, type SessionMetrics } from './domain/entities/federation-session.js';
 export { FederationEnvelope, type FederationEnvelopeProps, type FederationMessageType, type PIIScanResult, type PIIScanDetection, type PIIScanAction, CONSENSUS_REQUIRED_TYPES, } from './domain/entities/federation-envelope.js';
 export { TrustLevel, TRUST_TRANSITION_THRESHOLDS, CAPABILITY_GATES, isOperationAllowed, getTrustLevelLabel, type TrustTransitionThreshold, } from './domain/entities/trust-level.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,KAAK,0BAA0B,EAAE,KAAK,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9J,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,KAAK,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9H,OAAO,EACL,kBAAkB,EAClB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,wBAAwB,GACzB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EACL,UAAU,EACV,2BAA2B,EAC3B,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,wBAAwB,GAC9B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,kBAAkB,EAClB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,GAC5B,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,YAAY,EACZ,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,GACxB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,qBAAqB,EACrB,KAAK,2BAA2B,EAChC,KAAK,gBAAgB,GACtB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACtB,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,KAAK,0BAA0B,EAAE,KAAK,sBAAsB,EAAE,KAAK,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AAC9L,OAAO,EACL,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,8BAA8B,EAC9B,4BAA4B,GAC7B,MAAM,iDAAiD,CAAC;AACzD,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,sBAAsB,EACtB,4BAA4B,EAC5B,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,KAAK,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9H,OAAO,EACL,kBAAkB,EAClB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,wBAAwB,GACzB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EACL,UAAU,EACV,2BAA2B,EAC3B,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,wBAAwB,GAC9B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,kBAAkB,EAClB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,GAC5B,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,YAAY,EACZ,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,GACxB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,qBAAqB,EACrB,KAAK,2BAA2B,EAChC,KAAK,gBAAgB,GACtB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACtB,MAAM,gCAAgC,CAAC"}

package/dist/index.js

@@ -1,5 +1,7 @@
 export { AgentFederationPlugin } from './plugin.js';
 export { FederationNode } from './domain/entities/federation-node.js';
+export { FederationNodeState, canTransition, isCooldownElapsed, shouldAutoEvict, DEFAULT_SUSPENSION_COOLDOWN_MS, DEFAULT_AUTO_EVICTION_AGE_MS, } from './domain/value-objects/federation-node-state.js';
+export { FederationBreakerService, evaluatePolicy, DEFAULT_BREAKER_POLICY, DEFAULT_MAX_SAMPLES_PER_PEER, } from './application/federation-breaker-service.js';
 export { FederationSession } from './domain/entities/federation-session.js';
 export { FederationEnvelope, CONSENSUS_REQUIRED_TYPES, } from './domain/entities/federation-envelope.js';
 export { TrustLevel, TRUST_TRANSITION_THRESHOLDS, CAPABILITY_GATES, isOperationAllowed, getTrustLevelLabel, } from './domain/entities/trust-level.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,cAAc,EAA0F,MAAM,sCAAsC,CAAC;AAC9J,OAAO,EAAE,iBAAiB,EAAoD,MAAM,yCAAyC,CAAC;AAC9H,OAAO,EACL,kBAAkB,EAMlB,wBAAwB,GACzB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EACL,UAAU,EACV,2BAA2B,EAC3B,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GAEnB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,kBAAkB,GASnB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,gBAAgB,GAKjB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,gBAAgB,GAMjB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,cAAc,GAKf,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,YAAY,GAUb,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,cAAc,GAKf,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,qBAAqB,GAGtB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,YAAY,GAKb,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,cAAc,EAA0H,MAAM,sCAAsC,CAAC;AAC9L,OAAO,EACL,mBAAmB,EAGnB,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,8BAA8B,EAC9B,4BAA4B,GAC7B,MAAM,iDAAiD,CAAC;AACzD,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,sBAAsB,EACtB,4BAA4B,GAI7B,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAoD,MAAM,yCAAyC,CAAC;AAC9H,OAAO,EACL,kBAAkB,EAMlB,wBAAwB,GACzB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EACL,UAAU,EACV,2BAA2B,EAC3B,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GAEnB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,kBAAkB,GASnB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,gBAAgB,GAKjB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,gBAAgB,GAMjB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,cAAc,GAKf,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,YAAY,GAUb,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,cAAc,GAKf,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,qBAAqB,GAGtB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,YAAY,GAKb,MAAM,gCAAgC,CAAC"}

package/dist/mcp-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-tools.d.ts","sourceRoot":"","sources":["../src/mcp-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AAGrF,KAAK,iBAAiB,GAAG,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAC5D,KAAK,aAAa,GAAG,MAAM,aAAa,GAAG,IAAI,CAAC;AAMhD,wBAAgB,cAAc,CAC5B,cAAc,EAAE,iBAAiB,EACjC,UAAU,EAAE,aAAa,GACxB,iBAAiB,EAAE,CA8NrB"}
+{"version":3,"file":"mcp-tools.d.ts","sourceRoot":"","sources":["../src/mcp-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AAGrF,KAAK,iBAAiB,GAAG,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAC5D,KAAK,aAAa,GAAG,MAAM,aAAa,GAAG,IAAI,CAAC;AAMhD,wBAAgB,cAAc,CAC5B,cAAc,EAAE,iBAAiB,EACjC,UAAU,EAAE,aAAa,GACxB,iBAAiB,EAAE,CAsUrB"}

package/dist/mcp-tools.js

@@ -77,7 +77,7 @@ export function createMcpTools(getCoordinator, getContext) {
         },
         {
             name: 'federation_send',
-            description: 'Send a message to a federated peer through the PII pipeline and security gates',
+            description: 'Send a message to a federated peer through the PII pipeline and security gates. Optional budget controls (ADR-097): maxHops defaults to 8 to prevent recursive delegation; maxTokens/maxUsd cap cumulative spend across the hop chain.',
             pluginName: '@claude-flow/plugin-agent-federation',
             version: '1.0.0-alpha.1',
             inputSchema: {
@@ -86,12 +86,44 @@ export function createMcpTools(getCoordinator, getContext) {
                     targetNodeId: { type: 'string', description: 'Target node ID' },
                     messageType: { type: 'string', description: 'Message type (task-assignment, memory-query, context-share, etc.)' },
                     payload: { type: 'object', description: 'Message payload' },
+                    // ADR-097 Phase 1: optional budget envelope. Backward compatible —
+                    // omitting these preserves the legacy unbounded-tokens/USD path,
+                    // with maxHops still defaulting to 8 to defang recursion loops.
+                    budget: {
+                        type: 'object',
+                        description: 'Optional cumulative spend budget for this delegation chain',
+                        properties: {
+                            maxTokens: { type: 'number', description: 'Hard cap on Σ tokens across hops' },
+                            maxUsd: { type: 'number', description: 'Hard cap on Σ USD spent' },
+                        },
+                    },
+                    maxHops: {
+                        type: 'number',
+                        description: 'Maximum hops this message may travel (default 8, 0 disallows remote delegation)',
+                    },
+                    hopCount: {
+                        type: 'number',
+                        description: 'How many hops this message has already taken (0 on the originator)',
+                    },
+                    spent: {
+                        type: 'object',
+                        description: 'Caller-reported usage from previous legs (cumulative)',
+                        properties: {
+                            tokens: { type: 'number' },
+                            usd: { type: 'number' },
+                        },
+                    },
                 },
                 required: ['targetNodeId', 'messageType', 'payload'],
             },
             handler: async (params) => {
                 const coordinator = requireCoordinator();
-                const result = await coordinator.sendMessage(params['targetNodeId'], params['messageType'], params['payload']);
+                const result = await coordinator.sendMessage(params['targetNodeId'], params['messageType'], params['payload'], {
+                    budget: params['budget'],
+                    maxHops: params['maxHops'],
+                    hopCount: params['hopCount'],
+                    spent: params['spent'],
+                });
                 return textResult(JSON.stringify(result, null, 2), !result.success);
             },
         },
@@ -182,6 +214,70 @@ export function createMcpTools(getCoordinator, getContext) {
                 return textResult(JSON.stringify(events, null, 2));
             },
         },
+        {
+            name: 'federation_breaker_status',
+            description: 'ADR-097 Phase 4: per-peer circuit-breaker state snapshot. Returns each known peer with its lifecycle state (ACTIVE/SUSPENDED/EVICTED), when it changed, and why. Combine with federation_evict / federation_reactivate to operate the breaker manually.',
+            pluginName: '@claude-flow/plugin-agent-federation',
+            version: '1.0.0-alpha.1',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    nodeId: { type: 'string', description: 'Optional: filter to a single peer' },
+                },
+            },
+            handler: async (params) => {
+                const coordinator = requireCoordinator();
+                const states = coordinator.getPeerStates();
+                const filter = params['nodeId'];
+                const filtered = filter ? states.filter((s) => s.nodeId === filter) : states;
+                const counts = coordinator.getPeerStateCounts();
+                return textResult(JSON.stringify({ counts, peers: filtered }, null, 2));
+            },
+        },
+        {
+            name: 'federation_evict',
+            description: 'ADR-097 Phase 4: operator-initiated evict for a peer. Marks the peer EVICTED so subsequent federation_send calls short-circuit with PEER_EVICTED. Reversible only via federation_reactivate (operator override).',
+            pluginName: '@claude-flow/plugin-agent-federation',
+            version: '1.0.0-alpha.1',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    nodeId: { type: 'string', description: 'Target peer to evict' },
+                    correlationId: { type: 'string', description: 'Optional audit-trail correlation key (operator ticket, etc.)' },
+                },
+                required: ['nodeId'],
+            },
+            handler: async (params) => {
+                const coordinator = requireCoordinator();
+                const ok = await coordinator.evictPeer(params['nodeId'], 'MANUAL_EVICT', params['correlationId']);
+                const msg = ok
+                    ? `Evicted peer ${params['nodeId']}`
+                    : `No transition (peer unknown or already EVICTED): ${params['nodeId']}`;
+                return textResult(msg, !ok);
+            },
+        },
+        {
+            name: 'federation_reactivate',
+            description: 'ADR-097 Phase 4: operator-initiated reactivate for a SUSPENDED or EVICTED peer. Used after a health probe confirms recovery, or as an operator override on a manual evict. The breaker does NOT auto-reactivate; this MCP tool is the explicit lever.',
+            pluginName: '@claude-flow/plugin-agent-federation',
+            version: '1.0.0-alpha.1',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    nodeId: { type: 'string', description: 'Target peer to reactivate' },
+                    correlationId: { type: 'string', description: 'Optional audit-trail correlation key (probe ID, ticket, etc.)' },
+                },
+                required: ['nodeId'],
+            },
+            handler: async (params) => {
+                const coordinator = requireCoordinator();
+                const ok = await coordinator.reactivatePeer(params['nodeId'], params['correlationId']);
+                const msg = ok
+                    ? `Reactivated peer ${params['nodeId']}`
+                    : `No transition (peer unknown or already ACTIVE): ${params['nodeId']}`;
+                return textResult(msg, !ok);
+            },
+        },
         {
             name: 'federation_consensus',
             description: 'Propose a federated consensus operation across all active peers',