p2p-fret 1.1.0 → 1.2.1

package/dist/src/index.d.ts

@@ -48,6 +48,22 @@ export interface FretConfig {
      * Must be a positive finite number; the constructor throws otherwise.
      */
     maxPassiveIntervalMs?: number;
+    /**
+     * The longest grace, in milliseconds, a peer this node has watched stay up for a long time is
+     * given to come back before it is marked `dead` (default 300 000 ms — 5 minutes).
+     *
+     * A peer is normally marked dead after `deadAfterFailures` spaced failed contacts — a few
+     * seconds. A peer with long *proven tenure* (how long this node itself has watched it stay up)
+     * is instead marked dead only once its failure run has also lasted `tenure / 12`, capped here:
+     * nothing below 10 minutes of tenure, 50 s at 10 minutes, 2.5 minutes at 30, the full cap from
+     * an hour on. So a long-running server down for a few minutes of maintenance keeps its place in
+     * the ring rather than having the ring re-form around it twice. While in grace the peer is still
+     * a live member — routing steers around it by its probe backoff, and cohorts keep it as a
+     * member that is merely unavailable. `0` disables grace for every peer. Must be a finite number
+     * between 0 and 15 minutes (the tenure gap tolerance — a longer grace could keep a peer "alive"
+     * across a silence long enough to restart its session); the constructor throws otherwise.
+     */
+    maxDeadGraceMs?: number;
     /**
      * This node's libp2p private key — the key `node.peerId` was derived from.
      *
@@ -174,6 +190,13 @@ export interface FretService {
         id: string;
         metadata?: Record<string, unknown>;
     }>;
+    /**
+     * How long, in ms, this node has itself watched `peerId` stay continuously up — measured from
+     * proof of life only, never gossiped (see *Tenure* in docs/fret.md). 0 for a peer the table
+     * holds but has never proven alive; `undefined` for one it does not hold. Cohort order does not
+     * use it — a higher layer may, e.g. to choose which cohort members to ask first.
+     */
+    getPeerTenure(peerId: string): number | undefined;
     reportNetworkSize(estimate: number, confidence: number, source?: string): void;
     getNetworkSizeEstimate(): {
         size_estimate: number;

package/dist/src/service/fret-service.d.ts

@@ -389,7 +389,7 @@ export declare class FretService implements IFretService, Startable {
      *
      * **Scoring never creates** — a peer we hold no entry for is not scored, and the call returns
      * before the `selfCoord()` await. See {@link applyTouch} for why, and for where creation does
-     * belong. The trailing `applyMembershipSignal` / `noteProofOfLife` land inside that guard and
+     * belong. The `applyMembershipSignal` / `noteProofOfLife` land inside that guard and
      * so stop running for a missing peer, which loses nothing: both already no-op on one.
      *
      * `latencyMs` is optional and must be supplied **only** when the caller timed a round trip
@@ -428,7 +428,16 @@ export declare class FretService implements IFretService, Startable {
      */
     private applyContactFailure;
     /**
-     * Count one failed contact against `id`, marking it `dead` once the run completes.
+     * Count one failed contact against `id`, marking it `dead` once the run completes — and, for a
+     * peer with long proven tenure, has also lasted that peer's grace.
+     *
+     * **The grace** (`deadGraceMs` in `store/tenure.ts`, capped by `maxDeadGraceMs`) is time, not
+     * strikes: strikes arrive at the pass rate, so a larger count would stretch seconds, never the
+     * minutes a server's maintenance takes. A peer under 10 minutes of tenure has none and is judged
+     * exactly as before. Tenure is frozen during the outage (no proof of life arrives), so the grace
+     * is stable across the run without being snapshotted at its start. A peer held in grace is still
+     * a live member: routing steers around it by its probe backoff, and cohorts keep it as a member
+     * that is merely unavailable.
      *
      * **Synchronous by construction.** `applySuccess` / `applyFailure` read an entry, await the
      * self coordinate, then write a value derived before the await — so two concurrent chains
@@ -446,7 +455,7 @@ export declare class FretService implements IFretService, Startable {
     private applyContactStrike;
     /**
      * Record that `id` is demonstrably alive: clear its contact-failure run and, if it was marked
-     * `dead`, restore it to a live state.
+     * `dead`, restore it to a live state — and advance its session tenure (`store/tenure.ts`).
      *
      * Called from every site that proves liveness: the RPC sites through {@link noteRpcEvidence},
      * and a fresh transport connection (`peer:connect`) directly. The counter reset is the
@@ -456,8 +465,15 @@ export declare class FretService implements IFretService, Startable {
      *
      * Relevance is deliberately *not* reset to a baseline. `scoreSuccess` already up-ranks on
      * success, and wiping the health counters would erase the record of a peer that flaps.
+     *
+     * This is the **only** place tenure advances, so it counts proof of life and nothing else:
+     * hearsay (`noteDiscovered`, address hints, the peerStore listeners) never reaches it. The
+     * stamp rides the same write as the liveness patch, and a stamp alone is **not** a change —
+     * otherwise every RPC from a settled neighbour would snap the idle backoff back to its base.
      */
     private noteProofOfLife;
+    /** What proof of life changes about `e`'s liveness bookkeeping — empty when already settled. */
+    private livenessPatch;
     /**
      * The remote *answered on this network's namespaced protocol* — a framed reply came back,
      * whatever it said: `ok: false`, `busy`, or bytes that would not decode.
@@ -622,7 +638,9 @@ export declare class FretService implements IFretService, Startable {
      * Classify `id` from a libp2p-reported protocol list (available once identify has
      * run). Member if any of our namespaced protocols appears; foreign if the list is
      * non-empty but contains none of them; left unknown if empty (identify pending).
-     * The demotion arm is deliberately weak — see `applyMembershipSignal`.
+     * The demotion arm is deliberately weak — see `applyMembershipSignal`. A non-empty list also
+     * records whether it named ours (`PeerEntry.advertisedForeign`), which the label alone cannot
+     * say for a member — see {@link noteAdvertisedProtocols}.
      *
      * NOTE: the positive arm resets the negotiate-failure run (identify listing one of our protocols
      * is strong evidence), so a stale-positive list re-applied often enough would keep a peer that
@@ -640,6 +658,16 @@ export declare class FretService implements IFretService, Startable {
      * service-only-outage block still runs on identify nodes, the realistic rig.
      */
     private classifyByProtocols;
+    /**
+     * Record on `id`'s entry whether its latest non-empty advertised protocol list named ours
+     * (`PeerEntry.advertisedForeign`) — whatever its label, which the evidence-strength ordering
+     * settles separately: a confirmed member stays `member` on a list lacking ours, but the flag
+     * still says what it now advertises. Never a change on its own: clearing it coincides with the
+     * `identify-member` promotion, which counts for itself, and setting it on a member moves nothing
+     * a pass acts on — the flag only helps keep an *off-ring* peer out of the re-probe arms (see
+     * {@link isSettledForeign}).
+     */
+    private noteAdvertisedProtocols;
     /**
      * Admit a peer libp2p's peerStore told us about, then classify it off `protocols` — the shared
      * step of the `peer:update` / `peer:identify` listeners and the start walk.
@@ -1384,6 +1412,9 @@ export declare class FretService implements IFretService, Startable {
      *
      * The gate lives here rather than inside the selectors so a bare selector call (from a test)
      * still exercises the real selection logic against the live table.
+     *
+     * The two selections come back apart ({@link PhaseTwoTargets}) because only the classify arm
+     * holds the idle backoff at its base; the tick pools them together.
      */
     private phaseTwoTargets;
     /**
@@ -1422,9 +1453,12 @@ export declare class FretService implements IFretService, Startable {
      * - **`foreign`** — a same-network peer *mislabeled* foreign (e.g. identify completed before
      *   it registered our protocol handlers) is re-admitted by a successful namespaced ping.
      *   Before ring-membership gating this self-healed for free (`probeNeighborLatency` pinged
-     *   near ring peers regardless of label); gating closed that path. The `peer:update` identify
-     *   path also re-admits, but only if the remote pushes an update, so this is the dependable
-     *   backstop.
+     *   near ring peers regardless of label); gating closed that path. For a peer demoted by
+     *   negotiate strikes whose latest advertised list still names ours (a same-network peer
+     *   mid-restart on a host without `identifyPush`) this is the dependable backstop. A peer whose
+     *   latest list names none of ours is re-probed only until it has refused a full negotiate run
+     *   (see {@link isSettledForeign}); after that it comes back through identify delivering a list
+     *   that does, or its own inbound RPC.
      * - **`dead`** — a peer marked dead by a run of failed contacts is out of every ring view, so
      *   `stabilizeOnce` (which draws its probe targets from `getNeighbors`) never touches it
      *   again. Without this arm a peer that recovers but never dials us and never forms a
@@ -1442,6 +1476,18 @@ export declare class FretService implements IFretService, Startable {
      * `entries` defaults to a fresh `store.list()`, exactly as {@link classifyTargets}'s does.
      */
     private reprobeExcludedTargets;
+    /**
+     * Whether `e` is foreign on both kinds of evidence at once: its latest advertised protocol list
+     * names none of ours (`advertisedForeign`), *and* a full run of spaced negotiate refusals since
+     * the last positive proof says it really answers none of them. Neither alone stops re-probing.
+     * The list can be stale — captured before the remote's FRET registered its handlers, the
+     * ordinary shape for a host that starts the core service by hand after its node — and without
+     * `identifyPush` nothing refreshes it: two such peers trusting the list alone would never contact
+     * each other at all (`test/address-hints.relay.spec.ts` is that rig). A refusal run alone is what
+     * a same-network peer mid-restart produces, which is what the foreign arm exists to recover.
+     * Costs a relay {@link NEGOTIATE_FAILURE_THRESHOLD} failed pings per run, then silence.
+     */
+    private isSettledForeign;
     /**
      * Select one bounded re-probe arm's targets — peers matching `isCandidate` — the shared
      * mechanics of both arms of {@link reprobeExcludedTargets}: off-backoff and reachable candidates
@@ -1453,6 +1499,14 @@ export declare class FretService implements IFretService, Startable {
      * re-probed at most ~once per backoff window (doubling to a 32× cap) rather than every tick.
      * That growing factor is also what rotates the list under tick truncation: a probed peer's
      * factor grows, so it sorts behind the ones a truncated tick never reached.
+     *
+     * A peer that is foreign on both kinds of evidence ({@link isSettledForeign} — a relay, another
+     * network's node, once it has refused a run of our probes) is skipped by **both** arms: answering
+     * our ping cannot make it a ring member, so probing it — and redialing it when disconnected —
+     * was traffic forever with nothing to recover. If it does start serving this network, identify
+     * delivers the new list (`identifyPush`, or a reconnect re-running identify), or it contacts us
+     * itself; a dead one that comes back is revived by `peer:connect`. The filter only removes
+     * candidates, so the separate per-arm budgets stand.
      */
     private reprobeOffRingTargets;
     /**
@@ -1712,6 +1766,7 @@ export declare class FretService implements IFretService, Startable {
         id: string;
         metadata?: Record<string, unknown>;
     }>;
+    getPeerTenure(peerId: string): number | undefined;
     exportTable(): SerializedTable;
     importTable(table: SerializedTable): Promise<number>;
     /**

package/dist/src/service/fret-service.js

@@ -28,6 +28,7 @@ import { NearExchange, snapshotDigest } from './near-exchange.js';
 import { IdleBackoff } from './idle-backoff.js';
 import { ringNeighborsBothSides } from '../ring/ring-walk.js';
 import { createSparsityModel, normalizedLogDistance, sparsityBonus, touch as scoreTouch, recordSuccess as scoreSuccess, recordFailure as scoreFailure, initialRelevance, } from '../store/relevance.js';
+import { deadGraceMs, noteProven, provenTenureMs, TENURE_GAP_TOLERANCE_MS } from '../store/tenure.js';
 import { createLogger } from '../logger.js';
 const log = createLogger('service:fret');
 function isPlainObject(value) {
@@ -118,6 +119,20 @@ function requirePositiveMs(value, fallback, name) {
     }
     return value;
 }
+/**
+ * The configured dead-verdict grace ceiling (`FretConfig.maxDeadGraceMs`): a finite number of ms
+ * from 0 (the off switch) up to the tenure gap tolerance; absent takes `fallback`. Past the
+ * tolerance a grace could hold a peer "not dead" across a silence long enough that its session
+ * restarts on return — a contradiction, so it fails here rather than being clamped.
+ */
+function requireDeadGraceMs(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < 0 || value > TENURE_GAP_TOLERANCE_MS) {
+        throw new Error(`FretService: maxDeadGraceMs must be a finite number of milliseconds from 0 to ${TENURE_GAP_TOLERANCE_MS}, got ${String(value)}`);
+    }
+    return value;
+}
 /**
  * The peer ids named by configured bootstrap entries: a multiaddr's `p2p` component, otherwise
  * the entry itself as a bare peer id. An entry that yields no parseable id is logged and skipped
@@ -485,6 +500,13 @@ export class FretService {
          * sent). A redial cancelled mid-flight by `stop()` counts in neither verdict.
          */
         redials: { started: 0, connected: 0, failed: 0 },
+        /**
+         * Contact strikes that completed a failure run against a live peer but did not mark it
+         * `dead`, because the run had not yet lasted the peer's tenure-earned grace (see
+         * `applyContactStrike`). One per such strike, so a long-tenured peer that stays silent
+         * through its grace counts once per pass until the verdict lands.
+         */
+        deadGraceHeld: 0,
         /**
          * The stabilization loop's idle backoff, as of the last completed pass (see `IdleBackoff`):
          * `delayMs` is the passive delay the loop armed after it — the base while things change,
@@ -564,6 +586,7 @@ export class FretService {
             // Validated like `dialTimeoutMs`: a host that set it meant a number. A value at or
             // below the base interval is the off switch — `IdleBackoff` clamps the cap to the base.
             maxPassiveIntervalMs: requirePositiveMs(cfg?.maxPassiveIntervalMs, 60_000, 'maxPassiveIntervalMs'),
+            maxDeadGraceMs: requireDeadGraceMs(cfg?.maxDeadGraceMs, 300_000),
         };
         this.idle = new IdleBackoff({ baseMs: FretService.PASSIVE_INTERVAL_MS, capMs: this.cfg.maxPassiveIntervalMs });
         // A key that does not derive this node's peer id would seal records no receiver accepts
@@ -771,7 +794,7 @@ export class FretService {
      *
      * **Scoring never creates** — a peer we hold no entry for is not scored, and the call returns
      * before the `selfCoord()` await. See {@link applyTouch} for why, and for where creation does
-     * belong. The trailing `applyMembershipSignal` / `noteProofOfLife` land inside that guard and
+     * belong. The `applyMembershipSignal` / `noteProofOfLife` land inside that guard and
      * so stop running for a missing peer, which loses nothing: both already no-op on one.
      *
      * `latencyMs` is optional and must be supplied **only** when the caller timed a round trip
@@ -789,6 +812,16 @@ export class FretService {
      * inside the store instead of patching a value derived outside it.
      */
     async applySuccess(id, latencyMs) {
+        if (!this.store.getById(id))
+            return;
+        // Every applySuccess call in this service follows a completed RPC over this
+        // network's namespaced protocol (ping or maybeAct), which proves the peer
+        // serves this network → confirm membership for free off normal traffic…
+        this.applyMembershipSignal(id, 'rpc-success');
+        // …and proves it is reachable, which clears any contact-failure run and resurrects it if
+        // a previous run had marked it dead. Before the score, so the score reads the tenure this
+        // very proof extended or restarted — not a session from before a long absence.
+        this.noteRpcEvidence(id);
         const entry = this.store.getById(id);
         if (!entry)
             return;
@@ -806,13 +839,6 @@ export class FretService {
             // has nothing to say about.
             ...(latencyMs === undefined ? {} : { avgLatencyMs: next.avgLatencyMs }),
         });
-        // Every applySuccess call in this service follows a completed RPC over this
-        // network's namespaced protocol (ping or maybeAct), which proves the peer
-        // serves this network → confirm membership for free off normal traffic.
-        this.applyMembershipSignal(id, 'rpc-success');
-        // …and proves it is reachable, which clears any contact-failure run and resurrects it if
-        // a previous run had marked it dead.
-        this.noteRpcEvidence(id);
     }
     /**
      * Record a failed interaction with `id`.
@@ -851,7 +877,16 @@ export class FretService {
         this.applyContactStrike(id);
     }
     /**
-     * Count one failed contact against `id`, marking it `dead` once the run completes.
+     * Count one failed contact against `id`, marking it `dead` once the run completes — and, for a
+     * peer with long proven tenure, has also lasted that peer's grace.
+     *
+     * **The grace** (`deadGraceMs` in `store/tenure.ts`, capped by `maxDeadGraceMs`) is time, not
+     * strikes: strikes arrive at the pass rate, so a larger count would stretch seconds, never the
+     * minutes a server's maintenance takes. A peer under 10 minutes of tenure has none and is judged
+     * exactly as before. Tenure is frozen during the outage (no proof of life arrives), so the grace
+     * is stable across the run without being snapshotted at its start. A peer held in grace is still
+     * a live member: routing steers around it by its probe backoff, and cohorts keep it as a member
+     * that is merely unavailable.
      *
      * **Synchronous by construction.** `applySuccess` / `applyFailure` read an entry, await the
      * self coordinate, then write a value derived before the await — so two concurrent chains
@@ -884,20 +919,30 @@ export class FretService {
         // Clamped at the threshold so the counter stays bounded for a peer we keep re-probing;
         // a peer already dead simply stays dead.
         const failures = Math.min(e.contactFailures + 1, threshold);
-        const patch = { contactFailures: failures, lastContactFailureAt: now };
-        if (failures >= threshold && e.state !== 'dead')
+        // A run carrying no start stamp (counter written outside this method) reads as long over, so
+        // its verdict falls back to the strike count alone — today's rule, never a stuck grace.
+        const runStart = e.contactFailures === 0 ? now : e.contactRunStartedAt;
+        const completed = failures >= threshold && e.state !== 'dead';
+        const toDead = completed && now - runStart >= deadGraceMs(provenTenureMs(e), this.cfg.maxDeadGraceMs);
+        const patch = { contactFailures: failures, lastContactFailureAt: now, contactRunStartedAt: runStart };
+        if (toDead)
             patch.state = 'dead';
         this.store.update(id, patch);
-        // A strike on a peer that was not already dead progressed a run (or completed one). One
-        // on a peer already `dead` — the dead arm re-probing it — moves nothing: the peer is backed
-        // off, there is nothing new to act on, and counting it would reset the delay on every
-        // dead-arm probe forever.
-        if (e.state !== 'dead')
-            this.noteChange(`contact strike ${failures} on ${id}`);
+        if (completed && !toDead)
+            this.diag.deadGraceHeld++;
+        // A change is a strike that progressed the count, or the one that marked the peer dead. A
+        // grace-held strike at the clamped threshold moves nothing — it can repeat every pass for
+        // minutes, and counting it would pin the idle backoff at its base for the whole grace. So
+        // the verdict lands at most one passive interval after the grace expires. A strike on a peer
+        // already `dead` (the dead arm re-probing it) is never a change, or every dead-arm probe
+        // would reset the delay forever.
+        if (e.state !== 'dead' && (failures > e.contactFailures || toDead)) {
+            this.noteChange(toDead ? `contact run completed on ${id}` : `contact strike ${failures} on ${id}`);
+        }
     }
     /**
      * Record that `id` is demonstrably alive: clear its contact-failure run and, if it was marked
-     * `dead`, restore it to a live state.
+     * `dead`, restore it to a live state — and advance its session tenure (`store/tenure.ts`).
      *
      * Called from every site that proves liveness: the RPC sites through {@link noteRpcEvidence},
      * and a fresh transport connection (`peer:connect`) directly. The counter reset is the
@@ -907,28 +952,45 @@ export class FretService {
      *
      * Relevance is deliberately *not* reset to a baseline. `scoreSuccess` already up-ranks on
      * success, and wiping the health counters would erase the record of a peer that flaps.
+     *
+     * This is the **only** place tenure advances, so it counts proof of life and nothing else:
+     * hearsay (`noteDiscovered`, address hints, the peerStore listeners) never reaches it. The
+     * stamp rides the same write as the liveness patch, and a stamp alone is **not** a change —
+     * otherwise every RPC from a settled neighbour would snap the idle backoff back to its base.
      */
     noteProofOfLife(id) {
         const e = this.store.getById(id);
         if (!e)
             return;
+        const patch = this.livenessPatch(e);
+        const settled = Object.keys(patch).length === 0;
+        // Self never reaches here by RPC; the guard keeps a meaningless tenure off its entry anyway.
+        const tenure = id === this.selfIdStr ? undefined : noteProven(e, Date.now());
+        if (settled && tenure === undefined)
+            return;
+        this.store.update(id, { ...patch, ...tenure });
+        // Only when the liveness half wrote — a run cleared or a `dead` peer revived. Proof of life
+        // from a peer already settled (an idle neighbour's ping) at most stamped tenure, which is
+        // not something the next pass could act on.
+        if (settled)
+            return;
+        this.noteChange(patch.state === undefined ? `contact run cleared for ${id}` : `${id} revived`);
+    }
+    /** What proof of life changes about `e`'s liveness bookkeeping — empty when already settled. */
+    livenessPatch(e) {
         const patch = {};
         // The spacing stamp is cleared alongside the count, because it only means anything
         // *within* a run: leaving it behind makes the first failure of the next run land inside
         // the spacing window of a failure from the run just ended, so that strike is discarded
         // and the peer gets a free miss after every recovery.
-        if (e.contactFailures !== 0 || e.lastContactFailureAt !== 0) {
+        if (e.contactFailures !== 0 || e.lastContactFailureAt !== 0 || e.contactRunStartedAt !== 0) {
             patch.contactFailures = 0;
             patch.lastContactFailureAt = 0;
+            patch.contactRunStartedAt = 0;
         }
         if (e.state === 'dead')
-            patch.state = this.isConnected(id) ? 'connected' : 'disconnected';
-        if (Object.keys(patch).length === 0)
-            return; // already settled
-        this.store.update(id, patch);
-        // Only when it wrote — a run cleared or a `dead` peer revived. Proof of life from a peer
-        // already settled (an idle neighbour's ping) returned above and is not a change.
-        this.noteChange(patch.state === undefined ? `contact run cleared for ${id}` : `${id} revived`);
+            patch.state = this.isConnected(e.id) ? 'connected' : 'disconnected';
+        return patch;
     }
     /**
      * The remote *answered on this network's namespaced protocol* — a framed reply came back,
@@ -1221,7 +1283,9 @@ export class FretService {
      * Classify `id` from a libp2p-reported protocol list (available once identify has
      * run). Member if any of our namespaced protocols appears; foreign if the list is
      * non-empty but contains none of them; left unknown if empty (identify pending).
-     * The demotion arm is deliberately weak — see `applyMembershipSignal`.
+     * The demotion arm is deliberately weak — see `applyMembershipSignal`. A non-empty list also
+     * records whether it named ours (`PeerEntry.advertisedForeign`), which the label alone cannot
+     * say for a member — see {@link noteAdvertisedProtocols}.
      *
      * NOTE: the positive arm resets the negotiate-failure run (identify listing one of our protocols
      * is strong evidence), so a stale-positive list re-applied often enough would keep a peer that
@@ -1242,8 +1306,24 @@ export class FretService {
         if (!protocols || protocols.length === 0)
             return; // identify not complete → stay unknown
         const mine = Object.values(this.protocols);
-        const signal = protocols.some((p) => mine.includes(p)) ? 'identify-member' : 'identify-foreign';
-        this.applyMembershipSignal(id, signal);
+        const advertisesOurs = protocols.some((p) => mine.includes(p));
+        this.noteAdvertisedProtocols(id, advertisesOurs);
+        this.applyMembershipSignal(id, advertisesOurs ? 'identify-member' : 'identify-foreign');
+    }
+    /**
+     * Record on `id`'s entry whether its latest non-empty advertised protocol list named ours
+     * (`PeerEntry.advertisedForeign`) — whatever its label, which the evidence-strength ordering
+     * settles separately: a confirmed member stays `member` on a list lacking ours, but the flag
+     * still says what it now advertises. Never a change on its own: clearing it coincides with the
+     * `identify-member` promotion, which counts for itself, and setting it on a member moves nothing
+     * a pass acts on — the flag only helps keep an *off-ring* peer out of the re-probe arms (see
+     * {@link isSettledForeign}).
+     */
+    noteAdvertisedProtocols(id, advertisesOurs) {
+        const advertisedForeign = !advertisesOurs;
+        const e = this.store.getById(id);
+        if (e && e.advertisedForeign !== advertisedForeign)
+            this.store.update(id, { advertisedForeign });
     }
     /**
      * Admit a peer libp2p's peerStore told us about, then classify it off `protocols` — the shared
@@ -2305,6 +2385,9 @@ export class FretService {
         // dead self has no path back short of a restart — the same guard `applyContactStrike` keeps.
         if (id === this.selfIdStr)
             return;
+        // NOTE: immediate whatever the sender's tenure — no dead-verdict grace — because the notice is
+        // the peer's own statement that it is going. A "back in N minutes" leave flavour that earns
+        // grace needs leave authentication first (tickets/backlog/22-debt-leave-authentication.md).
         this.store.update(id, { state: 'dead' });
     }
     /**
@@ -2932,26 +3015,36 @@ export class FretService {
             // buys phase 2 its turn. This return still fires for a `stop()` or a tick that really
             // is out of time.
             if (budget.signal.aborted) {
-                // Work left undone that no event will announce — the same reason a non-empty phase
-                // 2 is pending below. Harmless on a `stop()`, which resets the backoff anyway.
+                // Work left undone that no event will announce — phase 2 never selected, so nothing
+                // can tell whether unknowns were waiting. Harmless on a `stop()`, which resets the
+                // backoff anyway.
                 this.idle.notePending();
                 return;
             }
-            const targets = this.phaseTwoTargets();
-            // Pending on the *selection*, not on the label counts: a ring that ever lost a phone
-            // ungracefully holds a `dead` entry until capacity evicts it (never, on a small ring),
-            // and "a dead peer exists" would keep the loop from ever backing off. The selection is
-            // empty whenever every off-ring peer is inside its backoff window, so the loop sleeps
-            // over those windows — and re-probes a peer whose window expired meanwhile up to one
-            // interval late, which the docs state.
-            // NOTE: the ladder restarts at every probe of a *permanently* off-ring peer, and climbs
-            // 1.5 + 3 + 6 + 12 + 24 s = 46.5 s before that peer's 32 s window has passed, so a ring
-            // holding one settles at about five passes per window (~9 s apart) rather than at the
-            // cap. If idle rings with a dead entry still show up in profiles, hold pending for the
-            // classify arm only: the dead and foreign arms' probe outcomes land inside the pass (a
-            // strike that progresses nothing needs no follow-up pass), so they need no hold.
-            if (targets.length > 0)
+            const { classify, reprobe } = this.phaseTwoTargets();
+            // Pending on the classify arm's selection alone. An `unknown` peer is a transient
+            // population the ring is waiting on, so the next pass should carry on classifying at the
+            // base. A re-probe's outcome lands inside this pass: a success is a membership or revival
+            // change, a failure that progresses a run is a change, and one that progresses nothing
+            // needs no follow-up pass — so holding for it only kept a ring with a permanently
+            // off-ring peer (a dead phone, a relay) restarting the ladder every backoff window. A
+            // redial this pass outlives is held by `runStabilizationPass` on its own.
+            // NOTE: accepted tradeoff — once the loop has backed off, the re-probe arms service their
+            // budget (Core 2 / Edge 1 per arm) per *interval*, not per 1.5 s: a dead or
+            // negotiate-foreign peer whose window expires during a backed-off interval is re-probed up
+            // to one interval late, and with more such peers than the budget each waits about
+            // ceil(count / budget) intervals — at the 60 s cap, a Core ring holding 10 dead entries
+            // re-probes each about every 5 minutes while idle. Accepted because a recovered neighbour
+            // contacts us itself (an inbound RPC revives it), a reconnect revives it through
+            // `peer:connect`, and any change returns the loop to the base. Holding pending whenever an
+            // arm was truncated by its budget was rejected: at Edge's budget of 1, two dead entries
+            // whose windows align truncate every window and restart the ladder about every 32 s.
+            // Revisit if dead-recovery latency on large idle rings shows up as a problem — then hold
+            // pending when an off-ring arm was budget-truncated, accepting that saturated arms keep the
+            // loop awake.
+            if (classify.length > 0)
                 this.idle.notePending();
+            const targets = [...classify, ...reprobe];
             const phaseTwoPool = { concurrency: this.maintenanceConcurrency, signal: budget.signal };
             const probed = await runPooled(targets.map((id) => () => this.probeMembership(id, budget.signal)), phaseTwoPool);
             logRejected(probed, targets, 'probeMembership');
@@ -3298,12 +3391,15 @@ export class FretService {
      *
      * The gate lives here rather than inside the selectors so a bare selector call (from a test)
      * still exercises the real selection logic against the live table.
+     *
+     * The two selections come back apart ({@link PhaseTwoTargets}) because only the classify arm
+     * holds the idle backoff at its base; the tick pools them together.
      */
     phaseTwoTargets() {
         if (this.store.countByMembership('unknown') === 0
             && this.store.countByMembership('foreign') === 0
             && this.store.countByState('dead') === 0)
-            return [];
+            return { classify: [], reprobe: [] };
         // NOTE: the walk is captured once and `put` writes a *new* entry object rather than editing
         // in place, so a store mutation made after this line is invisible to the arms that run
         // after it. Sound today: all three arms are pure selection — they read the backoff state,
@@ -3311,7 +3407,7 @@ export class FretService {
         // happens later, in the pooled phase. If an arm ever writes to the store while selecting,
         // re-walk per arm rather than leaving the later arms on a stale array.
         const entries = this.store.list();
-        return [...this.classifyTargets(entries), ...this.reprobeExcludedTargets(entries)];
+        return { classify: this.classifyTargets(entries), reprobe: this.reprobeExcludedTargets(entries) };
     }
     /**
      * Bounded classification probe pass over `unknown` peers.
@@ -3362,9 +3458,12 @@ export class FretService {
      * - **`foreign`** — a same-network peer *mislabeled* foreign (e.g. identify completed before
      *   it registered our protocol handlers) is re-admitted by a successful namespaced ping.
      *   Before ring-membership gating this self-healed for free (`probeNeighborLatency` pinged
-     *   near ring peers regardless of label); gating closed that path. The `peer:update` identify
-     *   path also re-admits, but only if the remote pushes an update, so this is the dependable
-     *   backstop.
+     *   near ring peers regardless of label); gating closed that path. For a peer demoted by
+     *   negotiate strikes whose latest advertised list still names ours (a same-network peer
+     *   mid-restart on a host without `identifyPush`) this is the dependable backstop. A peer whose
+     *   latest list names none of ours is re-probed only until it has refused a full negotiate run
+     *   (see {@link isSettledForeign}); after that it comes back through identify delivering a list
+     *   that does, or its own inbound RPC.
      * - **`dead`** — a peer marked dead by a run of failed contacts is out of every ring view, so
      *   `stabilizeOnce` (which draws its probe targets from `getNeighbors`) never touches it
      *   again. Without this arm a peer that recovers but never dials us and never forms a
@@ -3400,6 +3499,20 @@ export class FretService {
             ...this.reprobeOffRingTargets(entries, (e) => e.state === 'dead', budget),
         ];
     }
+    /**
+     * Whether `e` is foreign on both kinds of evidence at once: its latest advertised protocol list
+     * names none of ours (`advertisedForeign`), *and* a full run of spaced negotiate refusals since
+     * the last positive proof says it really answers none of them. Neither alone stops re-probing.
+     * The list can be stale — captured before the remote's FRET registered its handlers, the
+     * ordinary shape for a host that starts the core service by hand after its node — and without
+     * `identifyPush` nothing refreshes it: two such peers trusting the list alone would never contact
+     * each other at all (`test/address-hints.relay.spec.ts` is that rig). A refusal run alone is what
+     * a same-network peer mid-restart produces, which is what the foreign arm exists to recover.
+     * Costs a relay {@link NEGOTIATE_FAILURE_THRESHOLD} failed pings per run, then silence.
+     */
+    isSettledForeign(e) {
+        return e.advertisedForeign && e.negotiateFailures >= FretService.NEGOTIATE_FAILURE_THRESHOLD;
+    }
     /**
      * Select one bounded re-probe arm's targets — peers matching `isCandidate` — the shared
      * mechanics of both arms of {@link reprobeExcludedTargets}: off-backoff and reachable candidates
@@ -3411,10 +3524,18 @@ export class FretService {
      * re-probed at most ~once per backoff window (doubling to a 32× cap) rather than every tick.
      * That growing factor is also what rotates the list under tick truncation: a probed peer's
      * factor grows, so it sorts behind the ones a truncated tick never reached.
+     *
+     * A peer that is foreign on both kinds of evidence ({@link isSettledForeign} — a relay, another
+     * network's node, once it has refused a run of our probes) is skipped by **both** arms: answering
+     * our ping cannot make it a ring member, so probing it — and redialing it when disconnected —
+     * was traffic forever with nothing to recover. If it does start serving this network, identify
+     * delivers the new list (`identifyPush`, or a reconnect re-running identify), or it contacts us
+     * itself; a dead one that comes back is revived by `peer:connect`. The filter only removes
+     * candidates, so the separate per-arm budgets stand.
      */
     reprobeOffRingTargets(entries, isCandidate, budget) {
         const selfStr = this.selfIdStr;
-        const candidates = entries.filter((e) => e.id !== selfStr && !this.backoff.isBackedOff(e.id) && isCandidate(e));
+        const candidates = entries.filter((e) => e.id !== selfStr && !this.isSettledForeign(e) && !this.backoff.isBackedOff(e.id) && isCandidate(e));
         if (candidates.length === 0)
             return [];
         // Only reachable peers are probeable; prefer connected over has-addresses.
@@ -4101,6 +4222,9 @@ export class FretService {
             backoffPenalty: (id) => this.backoff.penalty(id),
         };
     }
+    // NOTE: link quality is the success rate alone; session tenure (`store/tenure.ts`) is available
+    // on the entry but deliberately not folded in. If routes are ever measured failing mid-path on
+    // short-lived hops, weight this by `stabilityFactor(provenTenureMs(entry))`.
     linkQuality(id) {
         const entry = this.store.getById(id);
         if (!entry)
@@ -4425,6 +4549,10 @@ export class FretService {
             metadata: entry.metadata
         }));
     }
+    getPeerTenure(peerId) {
+        const entry = this.store.getById(peerId);
+        return entry ? provenTenureMs(entry) : undefined;
+    }
     exportTable() {
         const now = Date.now();
         return {

package/dist/src/service/idle-backoff.d.ts

@@ -9,7 +9,8 @@
  * base the moment a **change** is noted — anything the next pass could act on (a connection
  * forming or dropping, a new entry, a label or liveness transition, an address becoming known) —
  * and holds at the base, without counting as a change, while a pass left work **pending**
- * (off-ring peers it selected for probing, a redial it outlived).
+ * (a near probe it skipped on recent evidence, unknown peers it selected for classification, a
+ * redial it outlived, a phase its tick budget cut off).
  *
  * A change is recorded as a bump of a monotonic counter, and a pass snapshots that counter when it
  * opens: {@link endPass} compares the two, so a change that lands *during* a pass is seen at that
@@ -52,10 +53,10 @@ export declare class IdleBackoff {
     /** Open a pass: snapshot the change counter and clear the pending flag. */
     beginPass(): void;
     /**
-     * The open pass left work no event will announce the outcome of — it selected off-ring peers to
-     * probe, or a redial it started is still running. Holds the next delay at the base. Not a
+     * The open pass left work no event will announce the outcome of — it selected unknown peers to
+     * classify, or a redial it started is still running. Holds the next delay at the base. Not a
      * change: nothing happened yet, and counting it would reset the quiet count on every pass that
-     * merely *looked* at a dead peer inside its backoff window.
+     * merely *selected* a peer to probe.
      */
     notePending(): void;
     /**