@bitkyc08/opencodex 2.82.0 → 2.84.0

package/src/link/ssh-runner.ts

@@ -1,6 +1,8 @@
 import { homedir } from "node:os";
 
 const DEFAULT_OUTPUT_BYTES = 64 * 1024;
+const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+const TUNNEL_OUTPUT_EXIT_GRACE_MS = 250;
 const HINT_MAX_CHARS = 160;
 // Written as escapes on purpose: invisible and bidi controls must never sit literally in source.
 const ANSI_SEQUENCE = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b\[[0-?]*[ -/]*[@-~]|\u001b[@-_]/g;
@@ -93,10 +95,21 @@ export class SshRunnerError extends Error {
   }
 }
 
-async function readOutput(stream: ReadableStream<Uint8Array>, maxBytes: number, kill?: () => void, fatalUtf8 = true): Promise<string> {
+async function readOutput(stream: ReadableStream<Uint8Array>, maxBytes: number, kill?: () => void, fatalUtf8 = true, exited?: Promise<number>, signal?: AbortSignal): Promise<string> {
   const reader = stream.getReader();
   const chunks: Uint8Array[] = [];
   let total = 0;
+  let finished = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const cancel = (): void => { void reader.cancel().catch(() => {}); };
+  const onExit = (): void => {
+    if (!finished) timer = setTimeout(cancel, TUNNEL_OUTPUT_EXIT_GRACE_MS);
+  };
+  signal?.addEventListener("abort", cancel, { once: true });
+  if (signal?.aborted) cancel();
+  // A descendant may inherit a pipe after ssh exits. Cancellation completes pending reads
+  // immediately; do not await the underlying source's possibly unbounded cancel promise.
+  void exited?.then(onExit, onExit);
   try {
     for (;;) {
       const next = await reader.read();
@@ -104,11 +117,15 @@ async function readOutput(stream: ReadableStream<Uint8Array>, maxBytes: number,
       total += next.value.byteLength;
       if (total > maxBytes) {
         kill?.();
+        cancel();
         throw new SshRunnerError("output_limit", `ssh output exceeded ${maxBytes} bytes`);
       }
       chunks.push(next.value);
     }
   } finally {
+    finished = true;
+    if (timer !== undefined) clearTimeout(timer);
+    signal?.removeEventListener("abort", cancel);
     reader.releaseLock();
   }
   const bytes = new Uint8Array(total);
@@ -149,8 +166,8 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
     } catch (error) {
       throw new SshRunnerError("spawn", `could not spawn ${argv[0] ?? "ssh"}`, { cause: error });
     }
-    const stdout = readOutput(outputStream(child.stdout), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"));
-    const stderr = readOutput(outputStream(child.stderr), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"), false);
+    const stdout = readOutput(outputStream(child.stdout), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"), true, child.exited);
+    const stderr = readOutput(outputStream(child.stderr), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"), false, child.exited);
     void stdout.catch(() => {});
     void stderr.catch(() => {});
     return {
@@ -165,9 +182,13 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
 
   return {
     async run(argv, options = {}) {
+      const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+      if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new SshRunnerError("timeout", "timeoutMs must be a positive integer at most 2147483647");
+      }
       const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_OUTPUT_BYTES;
-      if (!Number.isInteger(maxOutputBytes) || maxOutputBytes < 0) {
-        throw new SshRunnerError("output_limit", "maxOutputBytes must be a non-negative integer");
+      if (!Number.isInteger(maxOutputBytes) || maxOutputBytes < 0 || maxOutputBytes > MAX_OUTPUT_BYTES) {
+        throw new SshRunnerError("output_limit", `maxOutputBytes must be an integer between 0 and ${MAX_OUTPUT_BYTES}`);
       }
       let child: Bun.Subprocess;
       try {
@@ -181,41 +202,50 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
         throw new SshRunnerError("spawn", `could not spawn ${argv[0] ?? "ssh"}`, { cause: error });
       }
 
-      const stdout = readOutput(outputStream(child.stdout), Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), () => defaultKill(child, "SIGTERM"));
-      const stderr = readOutput(outputStream(child.stderr), Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), () => defaultKill(child, "SIGTERM"), false);
-      if (options.stdin !== undefined) {
-        try {
-          const input = child.stdin;
-          if (!input || typeof input === "number") throw new Error("ssh stdin was not piped");
-          await input.write(options.stdin);
-          await input.end();
-        } catch (error) {
-          child.kill("SIGTERM");
-          throw new SshRunnerError("spawn", "could not write ssh stdin", { cause: error });
-        }
-      }
-
-      const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
-      let timedOut = false;
+      const cancellation = new AbortController();
+      let stdout: Promise<string> | undefined;
+      let stderr: Promise<string> | undefined;
       let timer: ReturnType<typeof setTimeout> | undefined;
       const timeout = new Promise<never>((_, reject) => {
         timer = setTimeout(() => {
-          timedOut = true;
-          defaultKill(child, "SIGTERM");
           reject(new SshRunnerError("timeout", `ssh command exceeded ${timeoutMs}ms`));
         }, timeoutMs);
       });
       try {
-        const code = await Promise.race([child.exited, timeout]);
-        const [out, err] = await Promise.all([stdout, stderr]);
-        if (timedOut) throw new SshRunnerError("timeout", `ssh command exceeded ${timeoutMs}ms`);
+        const outStream = outputStream(child.stdout), errStream = outputStream(child.stderr);
+        stdout = readOutput(outStream, maxOutputBytes, undefined, true, undefined, cancellation.signal);
+        stderr = readOutput(errStream, Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), undefined, false, undefined, cancellation.signal);
+        const stdin = async (): Promise<void> => {
+          if (options.stdin === undefined) return;
+          try {
+            const input = child.stdin;
+            if (!input || typeof input === "number") throw new Error("ssh stdin was not piped");
+            await input.write(options.stdin);
+            // A timed-out write may settle later; do not start another operation after failure.
+            if (cancellation.signal.aborted) return;
+            await input.end();
+          } catch (error) {
+            throw new SshRunnerError("spawn", "could not write ssh stdin", { cause: error });
+          }
+        };
+        // Observe all rejections immediately, including errors arriving after timeout. One
+        // deadline covers stdin, exit and EOF: an inherited output pipe is still unfinished work.
+        const [, code, out, err] = await Promise.race([
+          Promise.all([stdin(), child.exited, stdout, stderr]), timeout,
+        ]);
         return { code, stdout: out, stderr: err };
       } catch (error) {
+        cancellation.abort();
+        // Only terminate this local SSH child. A kill failure must not hide the original error.
+        try { defaultKill(child, "SIGTERM"); } catch { /* Preserve the command failure when an already-gone child cannot be signalled. */ }
         if (error instanceof SshRunnerError) throw error;
         throw new SshRunnerError("spawn", "ssh command failed", { cause: error });
       } finally {
         if (timer !== undefined) clearTimeout(timer);
-        void Promise.allSettled([stdout, stderr, child.exited]);
+        void child.exited.catch(() => {});
+        // reader.cancel closes pending reads even if the source's cancel promise never settles.
+        // Do not await stdin or process exit: neither is guaranteed to settle after SIGTERM.
+        await Promise.allSettled([stdout, stderr]);
       }
     },
     spawnTunnel,
@@ -227,3 +257,4 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
 }
 
 export const SSH_OUTPUT_CAP_BYTES = DEFAULT_OUTPUT_BYTES;
+export const SSH_MAX_OUTPUT_BYTES = MAX_OUTPUT_BYTES;

package/src/link/status-projection.ts

@@ -2,6 +2,7 @@ import type { LinkStore } from "./store";
 import type { LinkTunnelStatus } from "./supervisor";
 import type { TunnelState } from "./tunnel-state";
 import { readCompensation, type CompensationStore } from "./compensation";
+import type { OcxClientConnectionConfig } from "../types";
 
 export type LinkWireState = "connecting" | "connected" | "reconnecting" | "failed" | "idle";
 
@@ -25,6 +26,8 @@ export interface LinkStatusDto {
   };
 }
 
+export interface ClientLinkIdentity { direction: "hub-initiated" | "client-initiated"; alias?: string }
+
 export interface LinkListenerStatusProjection {
   state: "off" | "listening" | "failed";
   port: number | null;
@@ -32,6 +35,7 @@ export interface LinkListenerStatusProjection {
 
 export interface LinkStatusConfig {
   runtimeRole?: "standalone" | "hub" | "client";
+  client?: Pick<OcxClientConnectionConfig, "transport" | "link" | "serverUrl" | "connectedAt">;
 }
 
 function asWireState(state: TunnelState | "client-owned"): LinkWireState {
@@ -60,7 +64,7 @@ function stateDetails(
 
 /**
  * Project private link state into the exact K16 wire DTO. `clientChild` lets a client-side caller
- * report a child state this module cannot read itself (an invalid client sidecar); link code
+ * report a child state this module cannot read itself (including an invalid client sidecar); link code
  * stays free of client imports, so the caller supplies it.
  */
 export function projectLinkStatus(
@@ -70,6 +74,7 @@ export function projectLinkStatus(
   config: LinkStatusConfig,
   compensation: CompensationStore = readCompensation(),
   clientChild: LinkStatusDto["child"] = null,
+  identity: ClientLinkIdentity | null = null,
 ): LinkStatusDto {
   const byId = new Map(supervisorStates.map(status => [status.linkId, status]));
   const links = store.links.map(record => ({
@@ -79,18 +84,31 @@ export function projectLinkStatus(
     ...stateDetails(record, byId.get(record.id), compensation),
     tunnelPort: record.tunnelPort,
   }));
-  const childRecord = config.runtimeRole === "client" ? store.links[0] : undefined;
-  const invalidClientSidecar = config.runtimeRole === "client" ? clientChild : null;
+  const childRecord = config.runtimeRole === "client"
+    ? (config.client?.transport === "link" ? store.links.find(record => record.id === config.client?.link?.linkId) : store.links[0])
+    : undefined;
+  const projectedClientChild = config.runtimeRole === "client" ? clientChild : null;
   const childStatus = childRecord
     ? stateDetails(childRecord, byId.get(childRecord.id), compensation)
     : undefined;
   const role = config.runtimeRole === "client"
     ? "child"
     : store.links.length > 0 ? "home" : "standalone";
+  // Home owns the record and reverse SSH process. The Child's persisted connection supplies
+  // identity and port, while an optional caller observation supplies live tunnel state.
+  const client = config.runtimeRole === "client" && config.client?.transport === "link" ? config.client : undefined;
+  const child = projectedClientChild ?? (childRecord && childStatus ? { alias: childRecord.alias, ...childStatus }
+    : client?.link ? { alias: identity?.alias ?? client.serverUrl, state: "idle" as const, since: client.connectedAt, reason: null } : null);
+  if (client?.link && child && identity) {
+    const active = links.find(link => link.id === client.link!.linkId);
+    const projected = { id: client.link.linkId, direction: identity.direction, tunnelPort: client.link.tunnelPort, ...child, alias: identity.alias ?? child.alias };
+    if (active) Object.assign(active, projected, compensation.entries[active.id] && childRecord ? stateDetails(childRecord, byId.get(active.id), compensation) : {});
+    else links.push(projected);
+  }
   return {
     role,
     listener: { state: listenerStatus.state, port: listenerStatus.port },
     links,
-    child: invalidClientSidecar ?? (childRecord && childStatus ? { alias: childRecord.alias, ...childStatus } : null),
+    child,
   };
 }

package/src/link/supervisor.ts

@@ -7,6 +7,8 @@ import { createSshRunner, type SshChild, type SshRunner } from "./ssh-runner";
 import {
   classifySshStderr,
   dueForSpawn,
+  failedTunnel,
+  HOME_TUNNEL_RETRY_POLICY,
   IDLE,
   reduceTunnel,
   type TunnelState,
@@ -33,6 +35,13 @@ export interface LinkSupervisor {
   ensureStarted(): Promise<void>;
   reload(): Promise<void>;
   stopLink(linkId: string): Promise<void>;
+  /** Reserve a link against reconnects and automatic spawns for a removal transaction. */
+  holdLink?(linkId: string): () => void;
+  /**
+   * Restart one Home-initiated tunnel now: stop its child, forget the backoff or failed state,
+   * and spawn a fresh attempt. False when the link is not a Home-initiated link of this store.
+   */
+  reconnect(linkId: string): Promise<boolean>;
   status(): readonly LinkTunnelStatus[];
   notifyAuthenticatedRequest?(apiKeyId: string): void;
   stop(): Promise<void>;
@@ -67,6 +76,20 @@ export interface LinkSupervisorDeps {
 
 const TIMER_MS = 1_000;
 const SPAWN_GRACE_MS = 5_000;
+/**
+ * A retry runs while the network may still be down, and ssh can wait out its whole ConnectTimeout
+ * (10 s for the TCP connect, the SSH handshake and key exchange, see ssh-argv.ts) before it exits.
+ * A retry is promoted only once it has outlived that, so an attempt that never reached the Child
+ * does not read connected and restart the outage clock. Like the first attempt's five seconds,
+ * liveness is a heuristic: authentication and the forward request come after ConnectTimeout, so
+ * one that stalls past the grace reads connected until ssh exits.
+ */
+const RETRY_GRACE_MS = 15_000;
+
+/** A retry whose ssh child is still running: reconnecting, or failed under the retry policy. */
+function retryInFlight(state: TunnelState): boolean {
+  return (state.kind === "reconnecting" || state.kind === "failed") && state.inFlight === true;
+}
 
 function sameArgv(left: readonly string[], right: readonly string[]): boolean {
   return left.length === right.length && left.every((value, index) => value === right[index]);
@@ -129,10 +152,19 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
   let started = false;
   let stopping = false;
   let lifecycleFlight: Promise<void> | undefined;
+  let lifecycleRevision = 0;
   let timer: ReturnType<typeof setInterval> | undefined;
   const states = new Map<string, TunnelState>();
-  const children = new Map<string, { child: SshChild; argv: readonly string[] }>();
+  const children = new Map<string, { child: SshChild; argv: readonly string[]; spawnedAt: number }>();
+  /** Per-link generation, advanced by spawns and explicit stop/removal reservations. */
+  const generations = new Map<string, number>();
+  const linkRevisions = new Map<string, number>();
+  /** Reconnects in flight, so overlapping requests for one link restart it once. */
+  const reconnects = new Map<string, Promise<boolean>>();
+  const holds = new Map<string, number>();
   const orphanUnverified = new Set<string>();
+  /** The generation of the child whose exit is still being classified, per link. */
+  const exiting = new Map<string, number>();
   const recordInstances = new Map<string, string>();
 
   const reconcileApiKeys = (): void => {
@@ -187,14 +219,17 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
   };
 
   const setEvent = (linkId: string, event: Parameters<typeof reduceTunnel>[1]): TunnelState => {
-    const next = reduceTunnel(states.get(linkId) ?? IDLE, event, deps.random);
+    const next = reduceTunnel(states.get(linkId) ?? IDLE, event, deps.random, HOME_TUNNEL_RETRY_POLICY);
     states.set(linkId, next);
     return next;
   };
 
   const spawnFor = (record: LinkRecord): void => {
-    if (stopping || record.direction !== "hub-initiated" || children.has(record.id)) return;
-    if (states.get(record.id)?.kind === "failed") return;
+    if (stopping || holds.has(record.id) || record.direction !== "hub-initiated" || children.has(record.id)) return;
+    // Only a fresh link or a due attempt spawns. A reload must neither skip the backoff nor start
+    // a second child while an exited one is still reporting its stderr.
+    const prior = states.get(record.id);
+    if (prior && prior.kind !== "idle" && !dueForSpawn(prior, now())) return;
     if (store.listenerPort === null) {
       states.set(record.id, { kind: "failed", since: now(), reason: "forward" });
       return;
@@ -209,7 +244,11 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
         knownHostsFile: linkKnownHostsPath(),
       });
       const child = runner.spawnTunnel(argv);
-      children.set(record.id, { child, argv });
+      const generation = (generations.get(record.id) ?? 0) + 1;
+      generations.set(record.id, generation);
+      // An older child's exit still being classified no longer speaks for this link.
+      exiting.delete(record.id);
+      children.set(record.id, { child, argv, spawnedAt: now() });
       orphanUnverified.delete(record.id);
       setEvent(record.id, { type: "spawn", now: now() });
       writePidfile(pidfilePath(record.id), { version: 1, linkId: record.id, pid: child.pid, argv });
@@ -218,9 +257,17 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
         children.delete(record.id);
         conditionalRemovePidfile(record.id, child.pid);
         if (stopping) return;
-        const stderr = child.stderr ? await child.stderr : "";
-        const next = setEvent(record.id, { type: "exit", now: now(), stderrClass: classifySshStderr(stderr) });
-        if (next.kind === "failed") return;
+        exiting.set(record.id, generation);
+        try {
+          let stderr = "";
+          // An unreadable stderr (the runner rejects it past its size cap) still reports the exit.
+          try { stderr = child.stderr ? await child.stderr : ""; } catch { /* classified as unknown */ }
+          // A reconnect may have started a fresh child meanwhile; its own lifecycle owns the state.
+          if (generations.get(record.id) !== generation) return;
+          setEvent(record.id, { type: "exit", now: now(), stderrClass: classifySshStderr(stderr) });
+        } finally {
+          if (exiting.get(record.id) === generation) exiting.delete(record.id);
+        }
       }).catch(() => {
         if (children.get(record.id)?.child !== child) return;
         children.delete(record.id);
@@ -228,23 +275,40 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
         if (!stopping) setEvent(record.id, { type: "exit", now: now(), stderrClass: "network" });
       });
     } catch {
-      states.set(record.id, { kind: "failed", since: now(), reason: "forward" });
+      const at = now();
+      states.set(record.id, failedTunnel("forward", at, HOME_TUNNEL_RETRY_POLICY, prior?.kind === "failed" ? prior.since : at));
     }
   };
 
   const tick = (): void => {
-    if (stopping) return;
+    if (stopping || lifecycleFlight) return;
     const current = now();
     for (const record of store.links) {
       if (record.direction !== "hub-initiated") continue;
-      const next = setEvent(record.id, { type: "tick", now: current });
+      if (holds.has(record.id)) continue;
+      // The exit is still being classified. Failing the link on the outage clock now would make
+      // a later host-key or auth exit land on a failed state that ignores it.
+      if (exiting.has(record.id)) continue;
+      const before = states.get(record.id) ?? IDLE;
       const child = children.get(record.id);
-      if (next.kind === "failed" && child) {
+      // Promotion is checked before the outage limit, so a child that has outlived its grace by the
+      // time this tick runs (at the limit, or late after a sleep) is promoted rather than killed.
+      // An idle Child may send no catalog request for hours; for a retry, staying up past the
+      // retry grace is the proof instead, as five seconds is for a first attempt.
+      if (child && ((before.kind === "connecting" && current - before.since >= SPAWN_GRACE_MS)
+        || (retryInFlight(before) && current - child.spawnedAt >= RETRY_GRACE_MS))) {
+        setEvent(record.id, { type: "ready", now: current });
+        continue;
+      }
+      const next = setEvent(record.id, { type: "tick", now: current });
+      if (next.kind === "failed" && !next.inFlight && child && retryInFlight(before)) {
+        // A retry started just before the outage limit has not had its grace yet. It carries on as
+        // the failed state's retry instead of being killed with a link that may already be back.
+        states.set(record.id, { ...next, inFlight: true });
+      } else if (next.kind === "failed" && !next.inFlight && child) {
         child.child.kill("SIGTERM");
         children.delete(record.id);
         conditionalRemovePidfile(record.id, child.child.pid);
-      } else if (next.kind === "connecting" && child && current - next.since >= SPAWN_GRACE_MS) {
-        setEvent(record.id, { type: "ready", now: current });
       } else if (dueForSpawn(next, current)) {
         spawnFor(record);
       }
@@ -273,37 +337,45 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
     syncTimer();
   };
 
-  let queuedLifecycle: (() => void | Promise<void>) | undefined;
   const runLifecycle = (operation: () => void | Promise<void>): Promise<void> => {
-    if (lifecycleFlight) {
-      queuedLifecycle = operation;
-      return lifecycleFlight;
-    }
-    lifecycleFlight = (async () => {
-      let next: (() => void | Promise<void>) | undefined = operation;
-      while (next) {
-        await next();
-        next = queuedLifecycle;
-        queuedLifecycle = undefined;
-      }
-    })().finally(() => {
-      lifecycleFlight = undefined;
-      queuedLifecycle = undefined;
+    // Every caller keeps its own operation and completion; no later reload can replace a stop.
+    const flight = (lifecycleFlight ?? Promise.resolve()).catch(() => {}).then(operation).finally(() => {
+      if (lifecycleFlight === flight) lifecycleFlight = undefined;
     });
-    return lifecycleFlight;
+    lifecycleFlight = flight;
+    return flight;
   };
 
-  const stopLink = async (linkId: string): Promise<void> => {
+  const stopChild = async (linkId: string): Promise<void> => {
     const current = children.get(linkId);
     if (!current) {
       states.set(linkId, IDLE);
       return;
     }
+    const generation = generations.get(linkId);
     children.delete(linkId);
     current.child.kill("SIGTERM");
     await current.child.exited;
     conditionalRemovePidfile(linkId, current.child.pid);
-    states.set(linkId, IDLE);
+    // A stop or removal reservation made while this child exited owns the next state.
+    if (generations.get(linkId) === generation) states.set(linkId, IDLE);
+  };
+
+  const invalidateLink = (linkId: string): void => {
+    linkRevisions.set(linkId, (linkRevisions.get(linkId) ?? 0) + 1);
+    generations.set(linkId, (generations.get(linkId) ?? 0) + 1);
+  };
+
+  const holdLink = (linkId: string): (() => void) => {
+    holds.set(linkId, (holds.get(linkId) ?? 0) + 1);
+    invalidateLink(linkId);
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const remaining = (holds.get(linkId) ?? 1) - 1;
+      if (remaining) holds.set(linkId, remaining); else holds.delete(linkId);
+    };
   };
 
   return {
@@ -315,6 +387,7 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
       return runLifecycle(begin);
     },
     async reload() {
+      lifecycleRevision += 1;
       await runLifecycle(async () => {
         if (stopping) return;
         if (!started) {
@@ -332,7 +405,7 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
         store = nextStore;
         for (const [linkId] of [...children]) {
           if (nextInstances.has(linkId) && !changed.has(linkId)) continue;
-          await stopLink(linkId);
+          await stopChild(linkId);
           states.delete(linkId);
           orphanUnverified.delete(linkId);
           recordInstances.delete(linkId);
@@ -353,12 +426,42 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
         syncTimer();
       });
     },
-    stopLink,
+    stopLink(linkId: string) {
+      invalidateLink(linkId);
+      return runLifecycle(() => stopChild(linkId));
+    },
+    holdLink,
+    reconnect(linkId: string) {
+      const inFlight = reconnects.get(linkId);
+      if (inFlight) return inFlight;
+      const linkRevision = linkRevisions.get(linkId);
+      let restarted = false;
+      const flight = runLifecycle(async () => {
+        if (stopping || !started || holds.has(linkId) || linkRevisions.get(linkId) !== linkRevision) return;
+        const record = store.links.find(link => link.id === linkId && link.direction === "hub-initiated");
+        if (!record) return;
+        // A preceding reload may have spawned a new generation; it is the current one we drain.
+        const generation = generations.get(linkId);
+        const revision = lifecycleRevision;
+        const instance = recordInstance(record, store.listenerPort);
+        await stopChild(linkId);
+        const latest = readStore();
+        const fresh = latest.links.find(link => link.id === linkId && link.direction === "hub-initiated");
+        if (stopping || holds.has(linkId) || generations.get(linkId) !== generation
+          || lifecycleRevision !== revision || !fresh || recordInstance(fresh, latest.listenerPort) !== instance) return;
+        spawnFor(fresh);
+        restarted = true;
+      }).then(() => restarted).finally(() => { reconnects.delete(linkId); });
+      reconnects.set(linkId, flight);
+      return flight;
+    },
     notifyAuthenticatedRequest(apiKeyId: string) {
       for (const record of store.links) {
         if (record.direction === "hub-initiated" && record.apiKeyId === apiKeyId && children.has(record.id)) {
           const state = states.get(record.id);
-          if (state?.kind === "connecting" || state?.kind === "reconnecting") setEvent(record.id, { type: "ready", now: now() });
+          if (state?.kind === "connecting" || state?.kind === "reconnecting" || (state && retryInFlight(state))) {
+            setEvent(record.id, { type: "ready", now: now() });
+          }
         }
       }
     },
@@ -383,20 +486,12 @@ export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervi
         clearTimer(timer);
         timer = undefined;
       }
-      const active = [...children.entries()];
-      for (const [linkId, current] of active) {
-        children.delete(linkId);
-        current.child.kill("SIGTERM");
-      }
-      await Promise.all(active.map(async ([linkId, current]) => {
-        await current.child.exited;
-        conditionalRemovePidfile(linkId, current.child.pid);
-        states.set(linkId, IDLE);
-      }));
-      for (const record of store.links) {
-        if (record.direction === "hub-initiated") states.set(record.id, IDLE);
-      }
-      if (lifecycleFlight) await lifecycleFlight;
+      await runLifecycle(async () => {
+        await Promise.all([...children.keys()].map(stopChild));
+        for (const record of store.links) {
+          if (record.direction === "hub-initiated") states.set(record.id, IDLE);
+        }
+      });
     },
   };
 }

package/src/link/tunnel-state.ts

@@ -6,10 +6,10 @@
  * - reconnecting: a transient failure; requests through the link fail with 503 meanwhile, and a
  *   new attempt is due at `retryAt`.
  * - failed: auth, host key and forward failures, and a link that stayed down for FAILED_AFTER_MS.
- *   Without a retry policy (the Home's `-R` supervisor) it needs the user. With one (the Child's
- *   own `-L` tunnel) a reason that has a delay is tried again at `retryAt`, and the retry attempt
- *   runs with `inFlight` while the state still reads failed; a reason without a delay stays
- *   terminal.
+ *   Without a retry policy it needs the user. With one (the Home's `-R` supervisor and the Child's
+ *   own `-L` tunnel both run with one) a reason that has a delay is tried again at `retryAt`, and
+ *   the retry attempt runs with `inFlight` while the state still reads failed; a reason without a
+ *   delay stays terminal.
  */
 
 export type TunnelFailure = "auth" | "hostkey" | "forward" | "timeout";
@@ -48,6 +48,13 @@ export const CLIENT_TUNNEL_RETRY_POLICY: TunnelRetryPolicy = {
   retryFailedAfterMs: { timeout: 60_000, forward: 60_000, auth: 5 * 60_000 },
 };
 
+/**
+ * The Home's `-R` supervisor dials the Child's sshd on the same cadence and limits. A sleep, an
+ * outage longer than FAILED_AFTER_MS, or a forward the Child's sshd still holds for the session
+ * that just died heals about a minute after it clears, instead of waiting for a proxy restart.
+ */
+export const HOME_TUNNEL_RETRY_POLICY: TunnelRetryPolicy = CLIENT_TUNNEL_RETRY_POLICY;
+
 export const IDLE: TunnelState = { kind: "idle" };
 
 /** Capped exponential backoff with ±20% jitter. `random` is injectable for tests. */

package/src/oauth/anthropic-continuity.ts

@@ -1,6 +1,7 @@
 import { detectClaudeCodeToken, hasClaudeCredentialContinuity } from "./local-token-detect";
 import { normalizeAnthropicIdentity, resolveAnthropicAccountIdentity, type AnthropicIdentityResolver } from "./anthropic-identity";
 import { credentialGeneration, type AuthStore } from "./store";
+import { mergeOAuthPlan } from "./plan";
 import { REFRESH_SKEW_MS } from "./refresh-policy";
 import type { OAuthCredentials, ProviderAccountSet } from "./types";
 import type { AnthropicInstanceId } from "../providers/anthropic-instance-id";
@@ -30,7 +31,7 @@ export async function newerClaudeCredentialForInstance(
   const before = normalizeAnthropicIdentity(stored.anthropicIdentity, stored.access);
   if (hasClaudeCredentialContinuity(stored, disk)) {
     return { kind: "adopt", diskGeneration: credentialGeneration(disk), credential: {
-      ...stored, ...disk, anthropicIdentity: disk.access === stored.access ? before : undefined,
+      ...stored, ...disk, plan: mergeOAuthPlan(disk, stored), anthropicIdentity: disk.access === stored.access ? before : undefined,
     } };
   }
   // Independent observations share a deadline through the caller signal; neither extends the other.
@@ -42,7 +43,7 @@ export async function newerClaudeCredentialForInstance(
   if (!oldIdentity || !newIdentity) return { kind: "unresolved", diskGeneration };
   if (oldIdentity.accountUuid !== newIdentity.accountUuid) return { kind: "different", diskGeneration };
   return { kind: "adopt", diskGeneration: credentialGeneration(disk), credential: {
-    ...stored, ...disk, accountId: newIdentity.accountUuid, anthropicIdentity: newIdentity,
+    ...stored, ...disk, accountId: newIdentity.accountUuid, anthropicIdentity: newIdentity, plan: newProof?.plan ?? null,
   } };
 }
 
@@ -75,5 +76,5 @@ export function captureAnthropicCredentialOwnerForInstance(instance: AnthropicIn
 }
 
 function identityMetadata(credential: OAuthCredentials): string {
-  return JSON.stringify([credential.source, credential.accountId, credential.email, credential.anthropicIdentity]);
+  return JSON.stringify([credential.source, credential.accountId, credential.email, credential.anthropicIdentity, credential.plan]);
 }

package/src/oauth/anthropic-identity.ts

@@ -4,12 +4,13 @@ import { createHash } from "node:crypto";
 import { readBoundedResponseBody } from "../lib/bounded-body";
 import { CLAUDE_CLI_USER_AGENT } from "../providers/claude-cli-identity";
 import type { OAuthCredentials } from "./types";
+import { normalizeOAuthPlan } from "./plan";
 
 const PROFILE_URL = "https://api.anthropic.com/api/oauth/profile";
 const PROFILE_TIMEOUT_MS = 10_000;
 const PROFILE_MAX_BYTES = 65_536;
 export type AnthropicIdentity = NonNullable<OAuthCredentials["anthropicIdentity"]>;
-export type AnthropicIdentityResolver = (access: string, signal?: AbortSignal) => Promise<AnthropicIdentity | undefined>;
+export type AnthropicIdentityResolver = (access: string, signal?: AbortSignal) => Promise<(AnthropicIdentity & { plan?: string }) | undefined>;
 
 export function bindAnthropicIdentity(access: string, accountUuid: unknown): AnthropicIdentity | undefined {
   if (!access || typeof accountUuid !== "string" || !accountUuid.length || accountUuid.length > 128
@@ -48,8 +49,18 @@ export const resolveAnthropicAccountIdentity: AnthropicIdentityResolver = async
     const data: unknown = JSON.parse(body.text);
     if (!data || typeof data !== "object" || !("account" in data)) return undefined;
     const account = data.account;
-    return account && typeof account === "object" && "uuid" in account
+    const identity = account && typeof account === "object" && "uuid" in account
       ? bindAnthropicIdentity(access, account.uuid) : undefined;
+    if (!identity) return undefined;
+    const organization = "organization" in data ? data.organization : undefined;
+    const org = organization && typeof organization === "object"
+      ? organization as Record<string, unknown> : undefined;
+    const strip = (value: unknown, prefix: string) => {
+      const label = normalizeOAuthPlan(value);
+      return label ? normalizeOAuthPlan(label.startsWith(prefix) ? label.slice(prefix.length) : label) : undefined;
+    };
+    const plan = strip(org?.rate_limit_tier, "default_claude_") ?? strip(org?.organization_type, "claude_");
+    return { ...identity, ...(plan ? { plan } : {}) };
   } catch {
     // Unavailable identity is an explicit unresolved result, never an ownership guess.
     return undefined;