agent-comms 8.15.8 → 8.15.10

package/src/core/connection-code-tool.ts

@@ -0,0 +1,92 @@
+/**
+ * CommsTool's gateway_generate_connection_code/gateway_redeem_connection_code handlers (agent-comms#188), extracted out of tool.ts's own class body purely to keep that file under its own line-count budget -- these two handlers have no dependency on CommsTool's other state (agentId/harness/cwd context every other handler takes), so free functions taking the store and action directly are a cleaner shape than private methods would have been anyway.
+ */
+
+import type { CommsResult, MeshOnlyFeatures } from "./tool.js";
+import { tryMeshAction } from "./tool.js";
+import type { CommsAction, ConnectionCode } from "./types.js";
+
+/**
+ * Generates a fresh connection code vouching for this store's own device-id, optionally PGP-signed with a caller-supplied private key. See ConnectionCodeLedger.generate's own doc comment for what each option means.
+ */
+export async function handleGatewayGenerateConnectionCode(
+  store: Readonly<MeshOnlyFeatures>,
+  action: CommsAction & { action: "gateway_generate_connection_code" },
+): Promise<CommsResult> {
+  if (!store.generateConnectionCode) {
+    return {
+      content: "Connection codes are not available on this store.",
+      isError: true,
+    };
+  }
+  const generateConnectionCode = store.generateConnectionCode.bind(store);
+  return tryMeshAction("generate connection code", async () => {
+    const code = await generateConnectionCode({
+      ...(action.ttlMs !== undefined && { ttlMs: action.ttlMs }),
+      ...(action.privateKey !== undefined && {
+        privateKeyArmored: action.privateKey,
+      }),
+      ...(action.passphrase !== undefined && {
+        passphrase: action.passphrase,
+      }),
+    });
+    const signedNote =
+      code.signature !== undefined ? " (PGP-signed)" : " (unsigned)";
+    return `Connection code generated${signedNote}, valid until ${code.expiresAt}. Share it with the counterpart out of band; it can be redeemed once:\n${JSON.stringify(code)}`;
+  });
+}
+
+/**
+ * Validates a candidate connection code (assembled from action's own code/expiresAt/device/signature fields) and, on success, trusts the device-id it vouches for. When the candidate carries a signature but action supplies a fingerprint with no publicKey, fetches the signer's public key from a keyserver first via fetchPgpPublicKeyByFingerprintImpl -- injected rather than imported directly so a test can supply a fake resolver instead of making a real network call.
+ */
+export async function handleGatewayRedeemConnectionCode(
+  store: Readonly<MeshOnlyFeatures>,
+  action: CommsAction & { action: "gateway_redeem_connection_code" },
+  fetchPgpPublicKeyByFingerprintImpl: (fingerprint: string) => Promise<string>,
+): Promise<CommsResult> {
+  if (!store.redeemConnectionCode) {
+    return {
+      content: "Connection codes are not available on this store.",
+      isError: true,
+    };
+  }
+  const candidate: ConnectionCode = {
+    code: action.code,
+    expiresAt: action.expiresAt,
+    deviceId: action.device,
+    ...(action.signature !== undefined && { signature: action.signature }),
+  };
+
+  let publicKeyArmored = action.publicKey;
+  if (
+    candidate.signature !== undefined &&
+    publicKeyArmored === undefined &&
+    action.fingerprint !== undefined
+  ) {
+    try {
+      publicKeyArmored = await fetchPgpPublicKeyByFingerprintImpl(
+        action.fingerprint,
+      );
+    } catch (err) {
+      return {
+        content: `Failed to fetch PGP public key for fingerprint ${action.fingerprint}: ${err instanceof Error ? err.message : String(err)}`,
+        isError: true,
+      };
+    }
+  }
+
+  const redeemConnectionCode = store.redeemConnectionCode.bind(store);
+  return tryMeshAction("redeem connection code", async () => {
+    const result = await redeemConnectionCode(candidate, {
+      ...(publicKeyArmored !== undefined && { publicKeyArmored }),
+      ...(action.fingerprint !== undefined && {
+        expectedFingerprint: action.fingerprint,
+      }),
+    });
+    const fingerprintNote =
+      result.fingerprint !== undefined
+        ? ` (signature verified, signing key fingerprint ${result.fingerprint})`
+        : " (no signature; freshness only)";
+    return `Trusted remote gateway device ${result.deviceId} via connection code${fingerprintNote}.`;
+  });
+}

package/src/core/connection-code.ts

@@ -0,0 +1,296 @@
+/**
+ * ConnectionCode generation and redemption (agent-comms#188): bootstraps GatewayTrust between two devices that have never established a mesh connection, since GatewayTrust's own deny-by-default, pin-the-key model otherwise requires a device-id to already be known and pasted in by hand (gateway_trust). One artifact, one generation flow, one redemption flow -- never two mechanisms bolted together.
+ *
+ * `code`/`expiresAt` are the always-checked half: freshness/liveness proof that whoever redeems this was on the other end of this exact exchange, recently. `signature` is the optional half: a detached PGP signature (armored) over `${code}:${expiresAt}:${deviceId}`, checked only when present. Redemption never requires a signature -- a device with no PGP identity still generates and redeems a bare code -- but when one is present, verifying it needs the signer's own public key, supplied by the caller either as a pasted armored block or (see pgp-keyserver.ts) fetched from a keyserver by fingerprint. Either way, a caller who also supplies the fingerprint they already independently trust gets it pinned: the verified key's own computed fingerprint must equal it, or redemption fails.
+ *
+ * PGP key material is never generated, stored, or managed by this module or by agent-comms generally -- signing and verification both take key material supplied per call by the caller, exactly as invoking `gpg --sign`/`gpg --verify` directly would. Building a persisted PGP-identity subsystem (key generation, passphrase storage, revocation) is a materially larger, security-sensitive scope the settled design (agent-comms#188) never asked for; a caller who wants a code signed brings whatever real-world PGP identity they already have (git-commit signing key, personal key on a keyserver, etc.) rather than trusting agent-comms to mint and hold a new one on their behalf.
+ *
+ * Persistence (ConnectionCodeLedger, backed by identity-store.ts's connection-code ledger) is two independent halves, not a request/response pair: the generating device's own issued-code record survives a restart between generation and hand-off (identity-store.ts's own doc comment on why), while the redeeming device's own redeemed-nonce record survives a restart within the code's own short validity window, enforcing genuine single-use locally rather than merely advisory "please don't reuse this" convention. Redemption never consults the issuer's own ledger -- there is no network round-trip back to whoever generated the code, since the whole point of this bootstrap is working before any connection between the two devices exists.
+ */
+
+import * as openpgp from "openpgp";
+import { nanoid } from "./nanoid.js";
+import {
+  loadConnectionCodeLedger,
+  saveConnectionCodeLedger,
+} from "./identity-store.js";
+import type { IdentitySlot, StoredConnectionCode } from "./identity-store.js";
+import type { ConnectionCode } from "./types.js";
+
+/** Nonce length: longer than nanoid's own 21-character default, since this identifier doubles as the single-use token a redemption check keys off, not merely a display id. */
+const CONNECTION_CODE_NONCE_LENGTH = 32;
+
+/** Minutes a generated code stays valid absent an explicit ttlMs override. */
+const DEFAULT_CONNECTION_CODE_TTL_MINUTES = 15;
+/** Seconds per minute, used to convert DEFAULT_CONNECTION_CODE_TTL_MINUTES to milliseconds. */
+const SECONDS_PER_MINUTE = 60;
+/** Milliseconds per second, used to convert DEFAULT_CONNECTION_CODE_TTL_MINUTES to milliseconds. */
+const MS_PER_SECOND = 1000;
+
+/** Default validity window for a generated code absent an explicit ttlMs: long enough for a human to relay it out of band (Slack, a phone call), short enough that "freshness" actually means something. */
+export const DEFAULT_CONNECTION_CODE_TTL_MS =
+  DEFAULT_CONNECTION_CODE_TTL_MINUTES * SECONDS_PER_MINUTE * MS_PER_SECOND;
+
+/** Every reason ConnectionCodeLedger.redeem can reject a candidate code. */
+export type ConnectionCodeInvalidReason =
+  | "expired"
+  | "already_redeemed"
+  | "signature_required"
+  | "signature_invalid"
+  | "fingerprint_mismatch";
+
+/** Thrown by ConnectionCodeLedger.redeem for every rejection reason above -- callers branch on `reason` rather than parsing `message`. */
+export class ConnectionCodeError extends Error {
+  constructor(
+    public readonly reason: ConnectionCodeInvalidReason,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ConnectionCodeError";
+  }
+}
+
+/** The exact canonical message a connection code's signature is computed over -- shared by generation and redemption so both sides agree on what was actually signed. Field order and the `:` separator are fixed by this function alone; `code` and `deviceId` are both hex/base64url alphabets that never contain `:`, so the three fields can't be confused with each other under concatenation. */
+function connectionCodeMessage(
+  candidate: Readonly<{
+    code: string;
+    expiresAt: string;
+    deviceId: string;
+  }>,
+): string {
+  return `${candidate.code}:${candidate.expiresAt}:${candidate.deviceId}`;
+}
+
+/** Signs `message` with `privateKeyArmored`, decrypting it with `passphrase` first if it is passphrase-protected. Returns the detached, armored PGP signature. */
+async function signConnectionCodeMessage(
+  message: string,
+  privateKeyArmored: string,
+  passphrase?: string,
+): Promise<string> {
+  let privateKey = await openpgp.readPrivateKey({
+    armoredKey: privateKeyArmored,
+  });
+  if (!privateKey.isDecrypted()) {
+    privateKey = await openpgp.decryptKey(
+      passphrase === undefined ? { privateKey } : { privateKey, passphrase },
+    );
+  }
+  const unsignedMessage = await openpgp.createMessage({ text: message });
+  // openpgp.d.ts's own sign() overloads return a conditional type keyed off T extends WebStream<Data>/NodeWebStream<Data>, which ESLint's own type-aware checking (typescript-eslint's projectService) can't resolve concretely here even though tsc itself has no trouble with it -- widening to `unknown` and narrowing with a runtime typeof check is the honest fix (Type Safety: "unknown with type narrowing"), not a cast papering over a real mismatch tsc would otherwise catch.
+  const signResult: unknown = await openpgp.sign({
+    message: unsignedMessage,
+    signingKeys: privateKey,
+    detached: true,
+  });
+  if (typeof signResult !== "string") {
+    throw new TypeError(
+      "openpgp.sign returned a stream rather than an armored string -- unexpected for a non-streaming Message input",
+    );
+  }
+  return signResult;
+}
+
+/** The result of checking a connection code's signature against a supplied public key: whether it verified, and (when readable) the signing key's own fingerprint, so a caller can compare it against whatever fingerprint they already trust. */
+interface VerifyConnectionCodeSignatureResult {
+  valid: boolean;
+  fingerprint?: string;
+}
+
+/** Verifies `signatureArmored` (a detached PGP signature) over `message` against `publicKeyArmored`. Never throws for an ordinary verification failure (wrong key, tampered message) -- returns `{ valid: false }` instead, reserving thrown errors for malformed input (unparsable armored text). */
+async function verifyConnectionCodeSignature(
+  message: string,
+  signatureArmored: string,
+  publicKeyArmored: string,
+): Promise<VerifyConnectionCodeSignatureResult> {
+  const publicKey = await openpgp.readKey({ armoredKey: publicKeyArmored });
+  const fingerprint = publicKey.getFingerprint();
+  const pgpMessage = await openpgp.createMessage({ text: message });
+  const signature = await openpgp.readSignature({
+    armoredSignature: signatureArmored,
+  });
+  const verificationResult = await openpgp.verify({
+    message: pgpMessage,
+    signature,
+    verificationKeys: publicKey,
+  });
+  const [sigResult] = verificationResult.signatures;
+  if (sigResult === undefined) return { valid: false, fingerprint };
+  try {
+    await sigResult.verified;
+    return { valid: true, fingerprint };
+  } catch {
+    return { valid: false, fingerprint };
+  }
+}
+
+/** Normalises a PGP fingerprint for comparison: openpgp.js's own getFingerprint() returns lowercase hex with no separators, but a human pasting one in from a keyserver page or business card may add spaces, colons, or uppercase. */
+function normalizeFingerprint(fingerprint: string): string {
+  return fingerprint.replace(/[\s:]+/g, "").toLowerCase();
+}
+
+export interface GenerateConnectionCodeOptions {
+  /** Overrides DEFAULT_CONNECTION_CODE_TTL_MS. */
+  ttlMs?: number;
+  /** Armored PGP private key to sign the code with. Omitted entirely -- not merely absent a signature -- when the caller has no PGP identity to sign with; the generated code is then bare, exactly as valid to redeem, just without the optional persistent-identity proof. */
+  privateKeyArmored?: string;
+  /** Passphrase for privateKeyArmored, if it is passphrase-protected. Ignored if privateKeyArmored is omitted. */
+  passphrase?: string;
+  /** Injectable clock for tests; defaults to Date.now(). */
+  now?: number;
+}
+
+export interface RedeemConnectionCodeOptions {
+  /** The signer's own armored PGP public key, needed only when the candidate code carries a signature. */
+  publicKeyArmored?: string;
+  /** A PGP fingerprint the caller already has independent reason to trust. When supplied alongside a signed code, the verified signing key's own computed fingerprint must equal it (case- and whitespace-insensitive) or redemption fails with "fingerprint_mismatch". When omitted, a present signature is still verified against publicKeyArmored, but nothing pins it to a fingerprint the caller actually recognises. */
+  expectedFingerprint?: string;
+  /** Injectable clock for tests; defaults to Date.now(). */
+  now?: number;
+}
+
+export interface RedeemConnectionCodeResult {
+  /** The device-id the redeemed code vouched for -- the caller's own responsibility to pass on to GatewayTrust.add. */
+  deviceId: string;
+  /** The signing key's fingerprint, present only when the code carried a signature that verified. */
+  fingerprint?: string;
+}
+
+/**
+ * Generates and redeems ConnectionCode artifacts, enforcing the always-checked freshness/liveness half (expiry, single-use) and the optional PGP-signature half (checked only when a code carries one). Optionally persisted per bridge slot via identity-store.ts's connection-code ledger (see this file's own header comment for what survives a restart and why); constructed with no slot, stays in-memory only, mirroring GatewayTrust's own no-slot fallback.
+ */
+export class ConnectionCodeLedger {
+  private readonly issued = new Map<string, StoredConnectionCode>();
+  private readonly redeemed = new Map<string, string>();
+  private readonly slot: Readonly<IdentitySlot> | undefined;
+
+  constructor(slot?: Readonly<IdentitySlot>) {
+    this.slot = slot;
+    if (slot !== undefined) {
+      const ledger = loadConnectionCodeLedger(slot);
+      for (const [nonce, record] of Object.entries(ledger.issued)) {
+        this.issued.set(nonce, record);
+      }
+      for (const [nonce, expiresAt] of Object.entries(ledger.redeemed)) {
+        this.redeemed.set(nonce, expiresAt);
+      }
+    }
+  }
+
+  /** Drops every issued or redeemed entry whose own expiresAt has already passed, so neither map accumulates forever across a long-running process or a slot that survives many restarts. */
+  private prune(now: number): void {
+    for (const [nonce, record] of this.issued) {
+      if (Date.parse(record.expiresAt) <= now) this.issued.delete(nonce);
+    }
+    for (const [nonce, expiresAt] of this.redeemed) {
+      if (Date.parse(expiresAt) <= now) this.redeemed.delete(nonce);
+    }
+  }
+
+  private persist(): void {
+    if (this.slot !== undefined) {
+      saveConnectionCodeLedger(this.slot, {
+        issued: Object.fromEntries(this.issued),
+        redeemed: Object.fromEntries(this.redeemed),
+      });
+    }
+  }
+
+  /**
+   * Generates a fresh ConnectionCode vouching for deviceId, optionally signed. The nonce is single-use in the sense that redeem() below will refuse to redeem it twice; nothing prevents the caller from generating any number of independent codes for the same deviceId.
+   */
+  async generate(
+    deviceId: string,
+    options: Readonly<GenerateConnectionCodeOptions> = {},
+  ): Promise<ConnectionCode> {
+    const now = options.now ?? Date.now();
+    this.prune(now);
+    const code = nanoid(CONNECTION_CODE_NONCE_LENGTH);
+    const expiresAt = new Date(
+      now + (options.ttlMs ?? DEFAULT_CONNECTION_CODE_TTL_MS),
+    ).toISOString();
+    const signature =
+      options.privateKeyArmored === undefined
+        ? undefined
+        : await signConnectionCodeMessage(
+            connectionCodeMessage({ code, expiresAt, deviceId }),
+            options.privateKeyArmored,
+            options.passphrase,
+          );
+
+    const connectionCode: ConnectionCode =
+      signature === undefined
+        ? { code, expiresAt, deviceId }
+        : { code, expiresAt, deviceId, signature };
+    const stored: StoredConnectionCode =
+      signature === undefined
+        ? { expiresAt, deviceId }
+        : { expiresAt, deviceId, signature };
+    this.issued.set(code, stored);
+    this.persist();
+    return connectionCode;
+  }
+
+  /**
+   * Validates a candidate ConnectionCode and returns the device-id it vouches for. Always checks expiry and single-use; when the candidate carries a signature, also verifies it (requiring options.publicKeyArmored) and, when options.expectedFingerprint is given, pins the verified signing key to it. Throws ConnectionCodeError for every rejection; the caller is responsible for calling GatewayTrust.add(result.deviceId) on success -- this ledger has no dependency on GatewayTrust itself.
+   */
+  async redeem(
+    candidate: Readonly<ConnectionCode>,
+    options: Readonly<RedeemConnectionCodeOptions> = {},
+  ): Promise<RedeemConnectionCodeResult> {
+    const now = options.now ?? Date.now();
+    this.prune(now);
+
+    if (Date.parse(candidate.expiresAt) <= now) {
+      throw new ConnectionCodeError(
+        "expired",
+        `Connection code expired at ${candidate.expiresAt}`,
+      );
+    }
+    if (this.redeemed.has(candidate.code)) {
+      throw new ConnectionCodeError(
+        "already_redeemed",
+        "Connection code has already been redeemed",
+      );
+    }
+
+    let fingerprint: string | undefined;
+    if (candidate.signature !== undefined) {
+      if (options.publicKeyArmored === undefined) {
+        throw new ConnectionCodeError(
+          "signature_required",
+          "Connection code carries a signature but no public key was supplied to verify it against",
+        );
+      }
+      const message = connectionCodeMessage(candidate);
+      const verification = await verifyConnectionCodeSignature(
+        message,
+        candidate.signature,
+        options.publicKeyArmored,
+      );
+      if (!verification.valid) {
+        throw new ConnectionCodeError(
+          "signature_invalid",
+          "Connection code signature does not verify against the supplied public key",
+        );
+      }
+      fingerprint = verification.fingerprint;
+      if (
+        options.expectedFingerprint !== undefined &&
+        (fingerprint === undefined ||
+          normalizeFingerprint(fingerprint) !==
+            normalizeFingerprint(options.expectedFingerprint))
+      ) {
+        throw new ConnectionCodeError(
+          "fingerprint_mismatch",
+          `Signing key fingerprint ${fingerprint ?? "(unknown)"} does not match the expected fingerprint ${options.expectedFingerprint}`,
+        );
+      }
+    }
+
+    this.redeemed.set(candidate.code, candidate.expiresAt);
+    this.persist();
+    return fingerprint === undefined
+      ? { deviceId: candidate.deviceId }
+      : { deviceId: candidate.deviceId, fingerprint };
+  }
+}

package/src/core/coordinator-role.ts

@@ -0,0 +1,224 @@
+/**
+ * CoordinatorRole: the elected holder of this machine's coordinator duties (agent-comms#341), the stale-agent PID probe, single-authority departure announcements, and the default cc-peer front. Held by gossiped, term-based claim (wire-mesh-core's CoordinatorElection over the spec's coordinator-frame) rather than by whoever binds the well-known port: a higher term always supersedes a lower one, an equal term breaks by lowest device-id, and any live peer can take the role over by raising the term, so a peer that never bound the port can hold it and the port stays only a compatibility first-contact address.
+ *
+ * Claims travel as wire-mesh session frames (MeshTransport.broadcastCoordinatorClaim/sendCoordinatorClaim), and only over sessions to peers on this machine, because both duties the role assigns are facts about one machine: a PID probe can only see local processes and the cc-peer front can only reach local Claude Code sessions.
+ *
+ * When a claim is made: a store claims only when it knows of no incumbent and is the first on the machine as far as it can tell. A store that bound the well-known port with no first-contact presence configured can meet other stores only through that port, so it claims at once; one that may be reachable through first contact (it bound the port, or could neither join nor bind it) first waits one claim wait for an incumbent's announcement, so a store arriving at an existing mesh never takes the role at an equal term before the holder's claim reaches it. Both ends of every machine-local session announce the incumbent they know as the session is enrolled. When the incumbent departs, the lowest device-id among the peers this side has a machine-local session to claims at once at a raised term, and every other survivor claims too if, one claim wait later, the claim it accepts still names a holder it has no session to, which covers a lowest-id peer that is itself gone or was never reachable. The same wait follows accepting a claim whose holder this side has no session to, so a claim naming a device that never joined cannot pin the role vacant.
+ */
+
+import {
+  CoordinatorElection,
+  compareDeviceIds,
+  type CoordinatorClaim,
+} from "wire-mesh-core/domain/coordinator-election";
+import {
+  deviceIdFromHex,
+  deviceIdToHex,
+} from "wire-mesh-core/domain/device-id";
+import type { CoordinatorFrame } from "wire-mesh-core/generated/protocol";
+import type { ConnectionHandle, MeshTransport } from "./transport.js";
+
+/** The longest delay setTimeout accepts: past it the timer fires at once, which would turn a long backoff into a burst of takeovers. */
+const MAX_TIMER_MS = 0x7fff_ffff;
+
+/** The claim this side currently accepts, in the hex form the rest of agent-comms addresses peers by. */
+export interface CoordinatorClaimView {
+  term: number;
+  holder: string;
+}
+
+/** What CoordinatorRole needs from MeshStore. The transport's electionPeerIds, not MeshStore's peer list, decides which peers count as survivors and as reachable holders, because only a peer with a machine-local session can ever claim the role or hear this side's claims. */
+export interface CoordinatorRoleDeps {
+  getPeerId: () => string;
+  requireTransport: () => Pick<
+    MeshTransport,
+    "broadcastCoordinatorClaim" | "sendCoordinatorClaim" | "electionPeerIds"
+  >;
+  /** How long this side waits for an incumbent's claim to reach it before claiming the role itself: after the incumbent departs, after accepting a claim whose holder it has no session to, and before a store that may not be alone claims a vacant role. MeshStore passes ROOM_REQUEST_TIMEOUT_MS, the ordinary bound on a frame reaching a connected peer, unless a test shortens it. */
+  claimWaitMs: number;
+  /** Starts the duties the role carries. Never runs concurrently with onLost. */
+  onGained: () => Promise<void>;
+  /** Stops the duties the role carries. Never runs concurrently with onGained. */
+  onLost: () => Promise<void>;
+  onError: (error: unknown) => void;
+}
+
+function sameClaim(
+  frame: Readonly<CoordinatorFrame>,
+  claim: Readonly<CoordinatorClaim>,
+): boolean {
+  return (
+    frame.term === claim.term &&
+    compareDeviceIds(frame.coordinator, claim.coordinator) === 0
+  );
+}
+
+export class CoordinatorRole {
+  /** Built on first use rather than at construction, because MeshStore's peerId is assigned after its constructor runs (every bridge sets it to the identity's device-id). */
+  private electionInstance: CoordinatorElection | undefined;
+  /** Whether the duties are running here, or are being started; set as each transition begins, so onGained and onLost each fire exactly once per change of holder. */
+  private holding = false;
+  /** Every onGained and onLost, chained so each starts only once the previous one has finished: a role lost and regained in quick succession must not start the duties while they are still being stopped. */
+  private transitions: Promise<void> = Promise.resolve();
+  /** Set while this side waits out claimWaitMs for an incumbent it can reach. */
+  private claimWait: ReturnType<typeof setTimeout> | undefined;
+  private stopped = false;
+  /** Takeovers this side has made in a row on an unreachable incumbent. Each doubles the next claim wait, so roles that cannot all reach one holder raise the term ever more slowly instead of at every wait; accepting a claim whose holder this side can reach ends the run. */
+  private takeoverStreak = 0;
+  /** The claim, as `term:holder`, each peer was last answered with. A peer whose view lags keeps sending the claims it knows, and answering each one with the same incumbent only multiplies the traffic: the answer is repeated only when the incumbent changes or the peer's session is enrolled afresh, since the earlier answer may have been lost with the old session. */
+  private readonly answered = new Map<string, string>();
+
+  constructor(private readonly deps: Readonly<CoordinatorRoleDeps>) {}
+
+  private get election(): CoordinatorElection {
+    this.electionInstance ??= new CoordinatorElection({
+      ownDevice: deviceIdFromHex(this.deps.getPeerId()),
+    });
+    return this.electionInstance;
+  }
+
+  /** Whether this side holds the role now. */
+  isHolder(): boolean {
+    return this.holding;
+  }
+
+  /** The claim this side currently accepts, or undefined when it has neither made nor heard one. */
+  current(): CoordinatorClaimView | undefined {
+    const claim = this.electionInstance?.current();
+    if (claim === undefined) return undefined;
+    return { term: claim.term, holder: deviceIdToHex(claim.coordinator) };
+  }
+
+  /** Claims the role at once when this side knows of no incumbent at all. Called by a store that can meet no other store except through the well-known port it just bound; a no-op once any claim has been made or heard. */
+  async claimIfVacant(): Promise<void> {
+    if (this.stopped || this.election.current() !== undefined) return;
+    await this.claim();
+  }
+
+  /** Claims the role one claim wait from now, unless by then this side has accepted a claim naming a holder it can reach. Called by a store that is alone as far as the well-known port tells it but may yet meet an incumbent through first contact, which gets that long to announce itself. */
+  claimIfVacantAfterWait(): void {
+    if (this.stopped || this.election.current() !== undefined) return;
+    this.startClaimWait();
+  }
+
+  /** Tells a peer whose machine-local session was just enrolled which claim this side accepts, so a joiner learns the incumbent instead of claiming over it. A no-op while this side knows of none. */
+  async announceTo(handle: Readonly<ConnectionHandle>): Promise<void> {
+    this.answered.delete(handle.id);
+    const frame = this.electionInstance?.announceCurrent();
+    if (frame === undefined) return;
+    await this.deps.requireTransport().sendCoordinatorClaim(handle, frame);
+  }
+
+  /** Evaluates a claim a peer gossiped. An accepted claim is gossiped on to every peer so the supersession reaches peers the sender is not connected to, and when it names a holder this side has no session to, this side waits one claim wait for that holder to appear before claiming over it; a stale or tiebreak-losing claim is answered with the incumbent so its sender converges, and a claim whose term no later claim could supersede is dropped unevaluated, neither gossiped nor answered. Receiving the incumbent itself is neither, and is dropped without a reply, which is what stops two peers that agree from echoing it forever. */
+  async handleClaim(
+    handle: Readonly<ConnectionHandle>,
+    frame: Readonly<CoordinatorFrame>,
+  ): Promise<void> {
+    if (this.stopped) return;
+    const result = this.election.evaluate(frame);
+    if (result.outcome === "accepted") {
+      this.answered.clear();
+      this.cancelClaimWait();
+      if (this.incumbentUnreachable()) this.startClaimWait();
+      else this.takeoverStreak = 0;
+      await this.deps.requireTransport().broadcastCoordinatorClaim(frame);
+    } else if (
+      result.outcome === "retained" &&
+      !sameClaim(frame, result.incumbent)
+    ) {
+      const incumbent = this.election.announceCurrent();
+      const answer = `${String(result.incumbent.term)}:${deviceIdToHex(result.incumbent.coordinator)}`;
+      if (incumbent !== undefined && this.answered.get(handle.id) !== answer) {
+        this.answered.set(handle.id, answer);
+        await this.deps
+          .requireTransport()
+          .sendCoordinatorClaim(handle, incumbent);
+      }
+    }
+    await this.syncHolding();
+  }
+
+  /** Recovers the role when the departed peer held it. The lowest device-id among the peers this side has a machine-local session to claims at once at a raised term; every other survivor waits one claim wait and claims itself if the claim it then accepts still names a holder it has no session to, then runs onDelayedTakeover (the caller's single-authority announcement of the departed holder, which a delayed successor makes too). */
+  async handleDeparture(
+    peerId: string,
+    onDelayedTakeover: () => Promise<void>,
+  ): Promise<void> {
+    if (this.stopped || this.current()?.holder !== peerId) return;
+    if (this.isLowestSurvivor(peerId)) {
+      await this.claim();
+      return;
+    }
+    this.startClaimWait(onDelayedTakeover);
+  }
+
+  /** Stops taking part and gives the duties up if this side held them, once any transition still running has finished. Idempotent. */
+  async stop(): Promise<void> {
+    this.stopped = true;
+    this.cancelClaimWait();
+    await this.syncHolding();
+  }
+
+  private isLowestSurvivor(departedPeerId: string): boolean {
+    const selfId = this.deps.getPeerId();
+    const self = deviceIdFromHex(selfId);
+    for (const id of this.deps.requireTransport().electionPeerIds()) {
+      if (id === departedPeerId || id === selfId) continue;
+      if (compareDeviceIds(deviceIdFromHex(id), self) < 0) return false;
+    }
+    return true;
+  }
+
+  /** Whether the claim this side accepts leaves the role without a holder it can reach: there is no claim at all, or it names a device that is neither this side nor a peer this side has a machine-local session to. */
+  private incumbentUnreachable(): boolean {
+    const claim = this.current();
+    if (claim === undefined) return true;
+    if (claim.holder === this.deps.getPeerId()) return false;
+    return !this.deps.requireTransport().electionPeerIds().has(claim.holder);
+  }
+
+  /** Waits one claim wait, then claims at a raised term and runs onTakeover (when given) if the incumbent is still unreachable. Replaces any wait already running, since only the latest accepted claim decides whether a takeover is due. */
+  private startClaimWait(onTakeover?: () => Promise<void>): void {
+    this.cancelClaimWait();
+    const wait = Math.min(
+      this.deps.claimWaitMs * 2 ** this.takeoverStreak,
+      MAX_TIMER_MS,
+    );
+    this.claimWait = setTimeout(() => {
+      this.claimWait = undefined;
+      if (this.stopped || !this.incumbentUnreachable()) return;
+      this.takeoverStreak += 1;
+      void this.claim()
+        .then(async () => onTakeover?.())
+        .catch(this.deps.onError);
+    }, wait);
+    // Never what keeps a process alive: a store shutting down stops the role anyway.
+    this.claimWait.unref();
+  }
+
+  private async claim(): Promise<void> {
+    const frame = this.election.claim();
+    await this.deps.requireTransport().broadcastCoordinatorClaim(frame);
+    await this.syncHolding();
+  }
+
+  private cancelClaimWait(): void {
+    if (this.claimWait === undefined) return;
+    clearTimeout(this.claimWait);
+    this.claimWait = undefined;
+  }
+
+  /** Queues a transition to whatever holding should now be. Resolves once that transition has run, and rejects with its failure; the chain itself carries on past a failure, which reaches this call's caller instead. */
+  private async syncHolding(): Promise<void> {
+    const next = this.transitions.then(async () => this.applyHolding());
+    this.transitions = next.catch(() => undefined);
+    await next;
+  }
+
+  /** Starts or stops the duties when the incumbent changed to or from this side since the previous transition. Reads the election afresh when the transition actually runs, not when it was queued, so a claim evaluated while an earlier transition was still running is reflected exactly once. */
+  private async applyHolding(): Promise<void> {
+    const holds = !this.stopped && this.electionInstance?.isSelf() === true;
+    if (holds === this.holding) return;
+    this.holding = holds;
+    await (holds ? this.deps.onGained() : this.deps.onLost());
+  }
+}

package/src/core/data-directory.ts

@@ -0,0 +1,32 @@
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** The environment default for the mesh's persistent keys, trust and ledgers. */
+export const DATA_DIR_ENV_VAR = "AGENT_COMMS_DATA_DIR";
+
+export interface DataDirectoryLocation {
+  /** Absolute base directory for all persistent mesh data, including the shared account and machine keys. Overrides the environment default and any legacy slot-only dir. */
+  dataDir?: string;
+}
+
+/** Explicit directory first, then the environment setting, then the existing home-directory default. Blank environment values are treated as unset. Non-absolute directories are rejected. */
+export function resolveDataDir({
+  dir,
+  env = process.env,
+}: Readonly<{
+  dir?: string | undefined;
+  env?: Readonly<Record<string, string | undefined>>;
+}> = {}): string {
+  const configured = env[DATA_DIR_ENV_VAR]?.trim();
+  const resolved =
+    dir ??
+    (configured !== undefined && configured !== ""
+      ? configured
+      : path.join(os.homedir(), ".agent-comms"));
+  if (!path.isAbsolute(resolved)) {
+    throw new Error(
+      `${DATA_DIR_ENV_VAR} or explicit dir must be an absolute path`,
+    );
+  }
+  return resolved;
+}