harnery 0.42.0 → 0.44.0

package/src/lib/guarded-remove.ts

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { lstatSync, readdirSync, readlinkSync, realpathSync, rmSync, type Stats } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, parse, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 
 export interface RemoveOptions {
   root: string;
@@ -16,6 +16,12 @@ export interface RemoveOptions {
   allowProtected?: string[];
   /** Directories whose own Git metadata and Harnery state may never be allowed (the live workspace). */
   liveRoots?: string[];
+  /** Command-layer validation of the current caller's ownership of this exact managed artifact root. */
+  assertOwnedArtifact?: (root: string) => void;
+  /** Inspection bound; values above 10,000 require verified ownership of the exact artifact root. */
+  entryLimit?: number;
+  /** Remove only verified-clean standalone clones inside the caller's owned artifact. */
+  cleanClone?: boolean;
 }
 
 export interface RemovalLink {
@@ -30,6 +36,7 @@ export interface RemovalReport {
   root: string;
   targets: string[];
   entries: number;
+  entry_limit: number;
   bytes: number;
   /** Protected paths removed because the caller named them with allowProtected. */
   protected: string[];
@@ -39,6 +46,7 @@ export interface RemovalReport {
 
 const protectedNames = new Set([".git", ".harnery", ".credentials", ".ssh", ".gnupg"]);
 const MAX_ENTRIES = 10_000;
+const MAX_OWNED_ARTIFACT_ENTRIES = 100_000;
 
 /** Permanent removal is deliberately limited to inspected, untracked local outputs. */
 export function guardedRemove(
@@ -48,18 +56,48 @@ export function guardedRemove(
 ): RemovalReport {
   const cwd = realpathSync(process.cwd());
   const root = checkedPath(options.root, new Set(), true);
-  const allowed = allowedProtected(options.allowProtected ?? [], root, options.liveRoots ?? []);
+  if (options.cleanClone) {
+    if (!options.recursive) throw new Error("Clean clone removal requires --recursive");
+    if (options.allowProtected?.length)
+      throw new Error("Clean clone removal cannot be combined with --allow-protected");
+    if (!options.assertOwnedArtifact)
+      throw new Error("Clean clone removal requires one current caller-owned managed artifact");
+    options.assertOwnedArtifact(root);
+  }
+  const entryLimit = options.entryLimit ?? MAX_ENTRIES;
+  if (
+    !Number.isSafeInteger(entryLimit) ||
+    entryLimit < 1 ||
+    entryLimit > MAX_OWNED_ARTIFACT_ENTRIES
+  )
+    throw new Error(`The entry limit must be an integer from 1 to ${MAX_OWNED_ARTIFACT_ENTRIES}`);
+  const assertEntryLimitAuthority = () => {
+    if (entryLimit <= MAX_ENTRIES) return;
+    if (!options.assertOwnedArtifact)
+      throw new Error(
+        "An entry limit above 10000 requires one current caller-owned managed artifact",
+      );
+    options.assertOwnedArtifact(root);
+  };
+  const allowed = allowedProtected(
+    options.allowProtected ?? [],
+    root,
+    options.liveRoots ?? [],
+    options.assertOwnedArtifact,
+  );
   const rootStat = lstatSync(root);
   const rootFingerprint = fingerprint(rootStat);
   if (!rootStat.isDirectory()) throw new Error("--root must be a directory");
   if (root === parse(root).root || root === realpathSync(homedir()))
     throw new Error("--root cannot be a filesystem root or home directory");
+  assertEntryLimitAuthority();
   if (paths.length === 0 || paths.length > 100) throw new Error("Supply 1-100 explicit targets");
   const targets = paths.map((path) => checkedPath(path, allowed));
   const snapshots = new Map<string, string>();
   const removedProtected = new Set<string>();
   const links: RemovalLink[] = [];
   const gitDirs = new Set<string>();
+  const cleanClones = new Set<string>();
   let bytes = 0;
   const devices = new Set<number>();
 
@@ -110,6 +148,10 @@ export function guardedRemove(
     if (stat.isDirectory() && !options.recursive)
       throw new Error(`Directory removal requires --recursive: ${target}`);
     const device = stat.dev;
+    if (options.cleanClone) {
+      assertCleanClone(target);
+      cleanClones.add(target);
+    }
     devices.add(device);
     const pending = [target];
     while (pending.length) {
@@ -118,6 +160,12 @@ export function guardedRemove(
       if (basename(path) === ARTIFACT_RECORD && insideArtifactWorkspace(path, null))
         throw new Error(`An artifact's record is managed by the artifact commands: ${path}`);
       if (protectedNames.has(basename(path).toLowerCase())) {
+        if (options.cleanClone && basename(path) === ".git") {
+          const clone = dirname(path);
+          assertCleanClone(clone);
+          cleanClones.add(clone);
+          allowed.add(path);
+        }
         if (!allowed.has(path)) throw new Error(protectedMessage(path));
         removedProtected.add(path);
       }
@@ -126,9 +174,9 @@ export function guardedRemove(
         // read, followed, or counted. (The target itself and its ancestors
         // were already refused if they were links, in checkedPath.)
         if (path === target) throw new Error(`Path contains a symlink: ${path}`);
-        if (snapshots.size >= MAX_ENTRIES)
+        if (snapshots.size >= entryLimit)
           throw new Error(
-            `Removal exceeds the ${MAX_ENTRIES}-entry limit; use the owning cleanup command`,
+            `Removal exceeds the ${entryLimit}-entry limit; use the owning cleanup command`,
           );
         snapshots.set(path, fingerprint(info));
         links.push({ path, target: readlinkSync(path) });
@@ -136,9 +184,9 @@ export function guardedRemove(
       }
       if (info.dev !== device || (!info.isDirectory() && !info.isFile()))
         throw new Error(`Mount boundary or special file cannot be removed: ${path}`);
-      if (snapshots.size >= MAX_ENTRIES)
+      if (snapshots.size >= entryLimit)
         throw new Error(
-          `Removal exceeds the ${MAX_ENTRIES}-entry limit; use the owning cleanup command`,
+          `Removal exceeds the ${entryLimit}-entry limit; use the owning cleanup command`,
         );
       snapshots.set(path, fingerprint(info));
       if (info.isFile()) bytes += info.size;
@@ -172,6 +220,7 @@ export function guardedRemove(
     root,
     targets,
     entries: snapshots.size,
+    entry_limit: entryLimit,
     bytes,
     protected: [...removedProtected].sort(),
     links,
@@ -185,11 +234,21 @@ export function guardedRemove(
     fingerprint(lstatSync(root)) !== rootFingerprint
   )
     throw new Error("Allowed root changed during inspection");
+  assertEntryLimitAuthority();
+  if (options.cleanClone) options.assertOwnedArtifact!(root);
+  // Ownership may have been released or changed while the contents were inspected.
+  allowedProtected(
+    options.allowProtected ?? [],
+    root,
+    options.liveRoots ?? [],
+    options.assertOwnedArtifact,
+  );
   for (const target of targets) {
     checkedPath(target, allowed);
     assertUntracked(target);
   }
   for (const dir of gitDirs) assertNoUnpushedHistory(dir);
+  for (const clone of cleanClones) assertCleanClone(clone);
   checkClaims(targets);
   for (const [path, previous] of snapshots) {
     if (fingerprint(lstatSync(path)) !== previous)
@@ -200,6 +259,47 @@ export function guardedRemove(
   return { ...report, applied: true };
 }
 
+/** A disposable clone must not be the only copy of work or a registered worktree. */
+function assertCleanClone(clone: string): void {
+  const metadata = join(clone, ".git");
+  const stat = lstatSync(metadata);
+  if (!stat.isDirectory() || stat.isSymbolicLink())
+    throw new Error(`Clean clone removal requires a standalone .git directory: ${clone}`);
+  const git = (args: string[]) => {
+    const result = spawnSync("git", ["-c", "core.fsmonitor=false", "-C", clone, ...args], {
+      encoding: "utf8",
+      timeout: 10_000,
+      maxBuffer: 4 * 1024 * 1024,
+      env: {
+        ...process.env,
+        LC_ALL: "C",
+        GIT_DIR: undefined,
+        GIT_COMMON_DIR: undefined,
+        GIT_WORK_TREE: undefined,
+        GIT_INDEX_FILE: undefined,
+        GIT_OPTIONAL_LOCKS: "0",
+      },
+    });
+    if (result.error || result.status !== 0)
+      throw new Error(`Cannot verify clean clone ${clone}: git ${args[0]} failed`);
+    return result.stdout;
+  };
+  if (
+    realpathSync(git(["rev-parse", "--show-toplevel"]).trim()) !== clone ||
+    realpathSync(resolve(clone, git(["rev-parse", "--git-common-dir"]).trim())) !== metadata
+  )
+    throw new Error(`Clean clone removal refuses shared repository metadata: ${clone}`);
+  const worktrees = git(["worktree", "list", "--porcelain", "-z"])
+    .split("\0")
+    .filter((entry) => entry.startsWith("worktree "));
+  if (worktrees.length !== 1 || worktrees[0] !== `worktree ${clone}`)
+    throw new Error(`Clean clone removal refuses registered or linked worktrees: ${clone}`);
+  if (git(["status", "--porcelain=v1", "--untracked-files=all"]).trim())
+    throw new Error(`Clean clone has uncommitted or untracked work: ${clone}`);
+  if (git(["rev-list", "--max-count=1", "HEAD", "--all", "--reflog", "--not", "--remotes"]).trim())
+    throw new Error(`Clean clone has HEAD, ref or reflog commits not on any remote: ${clone}`);
+}
+
 /** The metadata file the artifact commands keep in each artifact workspace. */
 const ARTIFACT_RECORD = ".harnery-artifact.json";
 
@@ -238,9 +338,14 @@ function insideAllowed(path: string, allowed: ReadonlySet<string>): boolean {
  * protected path strictly inside the root, reached without symlinks, and
  * never the Git metadata or Harnery state of a live workspace root.
  */
-function allowedProtected(paths: string[], root: string, liveRoots: string[]): Set<string> {
+function allowedProtected(
+  paths: string[],
+  root: string,
+  liveRoots: string[],
+  assertOwnedArtifact?: (root: string) => void,
+): Set<string> {
   const allowed = new Set<string>();
-  const live = liveRoots.map((dir) => resolve(dir));
+  const live = liveRoots.map((dir) => realpathSync(dir));
   for (const input of paths) {
     if (!input?.trim() || /[\0\r\n*?[\]$]/.test(input))
       throw new Error("Use a nonempty explicit --allow-protected path without wildcards");
@@ -261,13 +366,26 @@ function allowedProtected(paths: string[], root: string, liveRoots: string[]): S
     if (!named && !(info.isDirectory() && isRepositoryMetadata(path)))
       throw new Error(`--allow-protected must name a protected path itself: ${path}`);
     for (const dir of live) {
-      const own = [".git", ".harnery"].map((name) => resolve(dir, name));
-      if (
-        path === dir ||
-        strictlyInside(path, dir) ||
-        own.some((state) => path === state || strictlyInside(state, path))
-      )
+      if (path === dir || strictlyInside(path, dir))
+        throw new Error(`The live workspace's own state cannot be allowed: ${path}`);
+      for (const name of [".git", ".harnery"]) {
+        const state = resolve(dir, name);
+        if (path !== state && !strictlyInside(state, path)) continue;
+        // Only an explicitly named copied state directory inside one owned
+        // artifact may cross the outer live-state ancestor. Other live roots
+        // (including a checkout inside that artifact) still veto the path.
+        if (
+          name === ".harnery" &&
+          basename(path) === ".harnery" &&
+          info.isDirectory() &&
+          dirname(root) === resolve(state, "artifacts") &&
+          assertOwnedArtifact
+        ) {
+          assertOwnedArtifact(root);
+          continue;
+        }
         throw new Error(`The live workspace's own state cannot be allowed: ${path}`);
+      }
     }
     allowed.add(realpathSync(path));
   }

package/src/lib/identities/assume.ts

@@ -140,6 +140,7 @@ export function reclaimAbandonedLocalConflict(
   let sessionId = conflict.instance_id;
   let ageSecs: number | undefined;
   const liveRow = readLiveCoordinationRow(coordRoot, conflict.instance_id);
+  let expectedGenerationId = liveRow?.v3_generation_id ?? null;
   if (liveRow) {
     adapter = adapterOf(liveRow.platform);
     sessionId = liveRow.session_id || conflict.instance_id;
@@ -153,7 +154,9 @@ export function reclaimAbandonedLocalConflict(
       // It is required to join the exact producer state when recording the sweep.
       adapter = adapterOf(hb.platform);
       sessionId = hb.session_id || conflict.instance_id;
+      expectedGenerationId = hb.v3_generation_id ?? null;
     } catch {
+      expectedGenerationId = null;
       /* content unreadable — still reclaim the file */
     }
     try {
@@ -168,6 +171,7 @@ export function reclaimAbandonedLocalConflict(
     owner: conflict.instance_id,
     nativeSessionId: sessionId,
     adapter,
+    expectedGenerationId,
     observation: "stale_heartbeat",
     ageMs: Math.max(0, (ageSecs ?? 0) * 1_000),
   });

package/src/lib/tunnel/allowlist.ts

@@ -0,0 +1,208 @@
+// Address allowlist for the tunnel gate: exact addresses and CIDR ranges, IPv4
+// and IPv6. Pure functions with no I/O, shared by the gate worker (matching)
+// and the `tunnel allow` commands (validation + canonical spelling).
+//
+// An IPv6 phone and laptop on one Wi-Fi network have different addresses but
+// share a /64 prefix, so a range entry such as `2601:db8:1:2::/64` admits both.
+// An entry without a prefix length is a single address (/32 or /128).
+//
+// IPv4-mapped IPv6 addresses (`::ffff:203.0.113.8`) are IPv4 addresses reached
+// through a dual-stack socket, so they parse and match as IPv4.
+
+import { isIPv4, isIPv6 } from "node:net";
+
+export type IpFamily = 4 | 6;
+
+export interface ParsedIp {
+  family: IpFamily;
+  value: bigint;
+}
+
+export interface AllowEntry extends ParsedIp {
+  /** Prefix length in bits (32 or 128 for a single address). */
+  prefix: number;
+}
+
+const FULL_BITS: Record<IpFamily, number> = { 4: 32, 6: 128 };
+
+function parseIpv4(text: string): bigint | null {
+  if (!isIPv4(text)) return null;
+  let value = 0n;
+  for (const part of text.split(".")) value = (value << 8n) | BigInt(Number(part));
+  return value;
+}
+
+function parseIpv6(text: string): bigint | null {
+  if (!isIPv6(text)) return null;
+  let rest = text;
+  // A trailing dotted quad (`::ffff:1.2.3.4`, `64:ff9b::1.2.3.4`) is two groups.
+  const dotted = rest.match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/);
+  if (dotted) {
+    const v4 = parseIpv4(dotted[2] as string);
+    if (v4 === null) return null;
+    rest = `${dotted[1]}${(v4 >> 16n).toString(16)}:${(v4 & 0xffffn).toString(16)}`;
+  }
+  const halves = rest.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? (halves[0] as string).split(":") : [];
+  const tail = halves.length === 2 && halves[1] ? (halves[1] as string).split(":") : [];
+  const missing = 8 - head.length - tail.length;
+  if (halves.length === 1 ? missing !== 0 : missing < 1) return null;
+  const groups = [
+    ...head,
+    ...Array.from({ length: halves.length === 2 ? missing : 0 }, () => "0"),
+    ...tail,
+  ];
+  if (groups.length !== 8) return null;
+  let value = 0n;
+  for (const group of groups) {
+    if (!/^[0-9a-f]{1,4}$/i.test(group)) return null;
+    value = (value << 16n) | BigInt(Number.parseInt(group, 16));
+  }
+  return value;
+}
+
+/**
+ * Parse one address. Returns null for anything that is not an IP literal. A
+ * zone id (`fe80::1%en0`) is dropped, and an IPv4-mapped IPv6 address is
+ * reported as the IPv4 address it carries.
+ */
+export function parseIp(raw: string): ParsedIp | null {
+  let text = raw.trim();
+  if (text.startsWith("[") && text.endsWith("]")) text = text.slice(1, -1);
+  const zone = text.indexOf("%");
+  if (zone !== -1) text = text.slice(0, zone);
+  if (!text) return null;
+  const v4 = parseIpv4(text);
+  if (v4 !== null) return { family: 4, value: v4 };
+  const v6 = parseIpv6(text);
+  if (v6 === null) return null;
+  if (v6 >> 32n === 0xffffn) return { family: 4, value: v6 & 0xffffffffn };
+  return { family: 6, value: v6 };
+}
+
+function maskFor(family: IpFamily, prefix: number): bigint {
+  const bits = BigInt(FULL_BITS[family]);
+  const host = bits - BigInt(prefix);
+  return ((1n << bits) - 1n) ^ ((1n << host) - 1n);
+}
+
+/**
+ * Parse an allowlist entry: `203.0.113.8`, `203.0.113.0/24`, `2601:db8::1`, or
+ * `2601:db8:1:2::/64`. Host bits below the prefix are cleared, so
+ * `203.0.113.77/24` means the network `203.0.113.0/24`. Returns null when the
+ * entry is not a valid address or its prefix length is out of range.
+ */
+export function parseAllowEntry(raw: string): AllowEntry | null {
+  const text = raw.trim();
+  const slash = text.indexOf("/");
+  const address = parseIp(slash === -1 ? text : text.slice(0, slash));
+  if (!address) return null;
+  let prefix = FULL_BITS[address.family];
+  if (slash !== -1) {
+    const lengthText = text.slice(slash + 1);
+    if (!/^\d{1,3}$/.test(lengthText)) return null;
+    prefix = Number(lengthText);
+    // A prefix on an IPv4-mapped IPv6 entry counts from the IPv6 start, so
+    // `::ffff:1.2.3.0/120` is the IPv4 /24. Anything shorter is not an IPv4 range.
+    if (address.family === 4 && /:/.test(text.slice(0, slash))) {
+      if (prefix < 96 || prefix > 128) return null;
+      prefix -= 96;
+    }
+    if (prefix > FULL_BITS[address.family]) return null;
+  }
+  return { ...address, prefix, value: address.value & maskFor(address.family, prefix) };
+}
+
+function compress(groups: number[]): string {
+  // RFC 5952: collapse the longest run of two or more zero groups (first wins).
+  let bestStart = -1;
+  let bestLen = 0;
+  for (let i = 0; i < 8; ) {
+    if (groups[i] !== 0) {
+      i++;
+      continue;
+    }
+    let j = i;
+    while (j < 8 && groups[j] === 0) j++;
+    if (j - i > bestLen) {
+      bestStart = i;
+      bestLen = j - i;
+    }
+    i = j;
+  }
+  if (bestLen < 2) return groups.map((g) => g.toString(16)).join(":");
+  const left = groups.slice(0, bestStart).map((g) => g.toString(16));
+  const right = groups.slice(bestStart + bestLen).map((g) => g.toString(16));
+  return `${left.join(":")}::${right.join(":")}`;
+}
+
+/** Canonical text of an address (dotted quad, or compressed lowercase IPv6). */
+export function formatIp(ip: ParsedIp): string {
+  if (ip.family === 4) {
+    return [24n, 16n, 8n, 0n].map((shift) => Number((ip.value >> shift) & 0xffn)).join(".");
+  }
+  const groups: number[] = [];
+  for (let i = 7; i >= 0; i--) groups.push(Number((ip.value >> BigInt(i * 16)) & 0xffffn));
+  return compress(groups);
+}
+
+/** Canonical text of an entry; a single address carries no `/len` suffix. */
+export function formatAllowEntry(entry: AllowEntry): string {
+  const address = formatIp(entry);
+  return entry.prefix === FULL_BITS[entry.family] ? address : `${address}/${entry.prefix}`;
+}
+
+/**
+ * Canonical spelling of an allowlist entry, or null when invalid. Two spellings
+ * of one address or range (`2601:DB8:0:0::1`, `2601:db8::1`) normalize equal.
+ */
+export function normalizeAllowEntry(raw: string): string | null {
+  const entry = parseAllowEntry(raw);
+  return entry ? formatAllowEntry(entry) : null;
+}
+
+export interface Allowlist {
+  entries: AllowEntry[];
+  /** Entries that could not be parsed; they never match anything. */
+  invalid: string[];
+}
+
+export function compileAllowlist(rawEntries: readonly string[]): Allowlist {
+  const entries: AllowEntry[] = [];
+  const invalid: string[] = [];
+  for (const raw of rawEntries) {
+    const text = raw.trim();
+    if (!text) continue;
+    const entry = parseAllowEntry(text);
+    if (entry) entries.push(entry);
+    else invalid.push(text);
+  }
+  return { entries, invalid };
+}
+
+/** True when `ip` lies inside any entry. A missing or malformed address never matches. */
+export function allowlistMatches(list: Allowlist, ip: string): boolean {
+  const address = parseIp(ip);
+  if (!address) return false;
+  for (const entry of list.entries) {
+    if (entry.family !== address.family) continue;
+    const mask = maskFor(entry.family, entry.prefix);
+    if ((address.value & mask) === entry.value) return true;
+  }
+  return false;
+}
+
+/** The IPv6 /64 network prefix of an address, as a canonical `…/64` entry. */
+export function ipv6Slash64(address: string): string | null {
+  const ip = parseIp(address);
+  if (!ip || ip.family !== 6) return null;
+  return formatAllowEntry({ ...ip, prefix: 64, value: ip.value & maskFor(6, 64) });
+}
+
+/** A single IPv4 address as a `/32` entry. */
+export function ipv4Slash32(address: string): string | null {
+  const ip = parseIp(address);
+  if (!ip || ip.family !== 4) return null;
+  return `${formatIp(ip)}/32`;
+}

package/src/lib/tunnel/current-address.ts

@@ -0,0 +1,158 @@
+// This machine's public addresses as Cloudflare sees them, and the allowlist
+// bookkeeping around them (`tunnel allow add --current`).
+//
+// The tunnel gate admits a visitor by the `CF-Connecting-IP` header, which is
+// the address Cloudflare saw. Asking Cloudflare's own trace endpoint therefore
+// returns the same address the gate will later compare, with no third party and
+// no guess about NAT. The IPv4 and IPv6 probes use address literals, so each
+// travels over the family it is named for and needs no DNS.
+//
+// Entries the refresh adds are recorded in `auto_allowed`. The next refresh
+// replaces exactly those, so a machine that changes network does not pile up
+// stale addresses, and an entry added by hand is never removed.
+
+import { ipv4Slash32, ipv6Slash64, normalizeAllowEntry } from "./allowlist.ts";
+import type { TunnelConfig } from "./state.ts";
+
+export const TRACE_URL_V4 = "https://1.1.1.1/cdn-cgi/trace";
+export const TRACE_URL_V6 = "https://[2606:4700:4700::1111]/cdn-cgi/trace";
+
+export interface DetectedAddresses {
+  v4?: string;
+  v6?: string;
+  /** One note per family that could not be read. */
+  failures: string[];
+}
+
+export interface DetectOptions {
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+  /** Tries per family; a transient failure on a flaky network should not drop an address. */
+  attempts?: number;
+}
+
+/** The `ip=` value of a Cloudflare trace body, or null. */
+export function parseTraceIp(body: string): string | null {
+  const m = body.match(/^ip=(\S+)\s*$/m);
+  return m ? (m[1] as string) : null;
+}
+
+async function probe(url: string, family: 4 | 6, opts: Required<DetectOptions>): Promise<string> {
+  let last = "no answer";
+  for (let attempt = 0; attempt < opts.attempts; attempt++) {
+    try {
+      const res = await opts.fetch(url, { signal: AbortSignal.timeout(opts.timeoutMs) });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const ip = parseTraceIp(await res.text());
+      if (!ip) throw new Error("the trace had no ip= line");
+      const entry = family === 4 ? ipv4Slash32(ip) : ipv6Slash64(ip);
+      if (!entry) throw new Error(`expected an IPv${family} address, got ${ip}`);
+      return ip;
+    } catch (error) {
+      last = error instanceof Error ? error.message : String(error);
+    }
+  }
+  throw new Error(last);
+}
+
+/** Both families in parallel. A family that fails is reported, not thrown. */
+export async function detectPublicAddresses(
+  options: DetectOptions = {},
+): Promise<DetectedAddresses> {
+  const opts: Required<DetectOptions> = {
+    fetch: options.fetch ?? fetch,
+    timeoutMs: options.timeoutMs ?? 4_000,
+    attempts: options.attempts ?? 2,
+  };
+  const [v4, v6] = await Promise.allSettled([
+    probe(TRACE_URL_V4, 4, opts),
+    probe(TRACE_URL_V6, 6, opts),
+  ]);
+  const out: DetectedAddresses = { failures: [] };
+  if (v4.status === "fulfilled") out.v4 = v4.value;
+  else out.failures.push(`IPv4: ${(v4.reason as Error).message}`);
+  if (v6.status === "fulfilled") out.v6 = v6.value;
+  else out.failures.push(`IPv6: ${(v6.reason as Error).message}`);
+  return out;
+}
+
+export interface CurrentAddressPlan {
+  config: TunnelConfig;
+  /** Entries newly present in the allowlist. */
+  added: string[];
+  /** Automatic entries from an earlier refresh that are now gone. */
+  removed: string[];
+  /** The automatic entries after this refresh (the detected, not already listed by hand). */
+  automatic: string[];
+  changed: boolean;
+  warnings: string[];
+}
+
+const sameEntry = (a: string, b: string) =>
+  (normalizeAllowEntry(a) ?? a) === (normalizeAllowEntry(b) ?? b);
+const includesEntry = (list: readonly string[], entry: string) =>
+  list.some((e) => sameEntry(e, entry));
+
+/**
+ * Fold freshly detected addresses into the allowlist.
+ *
+ * When nothing was detected the config comes back untouched with a warning:
+ * a failed lookup must never empty the list. When at least one family was
+ * detected, a family that was not is treated as absent from this network, so
+ * its old automatic entry goes. The entries for the detected families replace
+ * every previous automatic entry; manual entries are kept in place.
+ */
+export function planCurrentAddresses(
+  config: TunnelConfig,
+  detected: DetectedAddresses,
+): CurrentAddressPlan {
+  const previousAuto = config.auto_allowed ?? [];
+  const wanted: string[] = [];
+  if (detected.v4) {
+    const entry = ipv4Slash32(detected.v4);
+    if (entry) wanted.push(entry);
+  }
+  if (detected.v6) {
+    const entry = ipv6Slash64(detected.v6);
+    if (entry) wanted.push(entry);
+  }
+
+  if (wanted.length === 0) {
+    return {
+      config,
+      added: [],
+      removed: [],
+      automatic: previousAuto,
+      changed: false,
+      warnings: [
+        `Could not detect this machine's public address (${detected.failures.join("; ") || "no answer"}). ` +
+          `The allowlist is unchanged${previousAuto.length ? `; the previous automatic entries stay: ${previousAuto.join(", ")}` : ""}.`,
+      ],
+    };
+  }
+
+  const manual = config.allowed_ips.filter((e) => !includesEntry(previousAuto, e));
+  // An address already listed by hand stays manual, so a later refresh keeps it.
+  const automatic = wanted.filter((e) => !includesEntry(manual, e));
+  const allowed = [...manual, ...automatic];
+  const before = config.allowed_ips;
+  const added = allowed.filter((e) => !includesEntry(before, e));
+  const removed = before.filter((e) => !includesEntry(allowed, e));
+  const warnings: string[] = [];
+  const missing = [detected.v4 ? null : "IPv4", detected.v6 ? null : "IPv6"].filter(Boolean);
+  if (missing.length > 0) {
+    warnings.push(
+      `${missing.join(" and ")} was not detected, so this network is treated as having none` +
+        (detected.failures.length ? ` (${detected.failures.join("; ")})` : "") +
+        ".",
+    );
+  }
+  return {
+    config: { ...config, allowed_ips: allowed, auto_allowed: automatic },
+    added,
+    removed,
+    automatic,
+    changed: added.length > 0 || removed.length > 0,
+    warnings,
+  };
+}