@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/lib/fleet/types.d.ts

@@ -87,6 +87,14 @@ export interface DeviceProbe {
     cliVersion?: string;
     /** Agent ids currently installed on the device. */
     installedAgents: string[];
+    /**
+     * Installed version strings per agent id (e.g. `{ claude: ['2.1.170', '2.1.207'] }`),
+     * parsed from `agents view --json` on the device. Only populated when the plan
+     * involves a version-pinned spec (`claude@2.1.170`, or a `claude@all` expansion)
+     * — a bare `claude`/`claude@latest` roster never pays for the extra probe. When
+     * undefined, version-pinned specs fall back to id-level presence.
+     */
+    installedVersions?: Record<string, string[]>;
     /** Reason string when `reachable` is false or the probe partially failed. */
     note?: string;
 }
@@ -100,6 +108,9 @@ export interface FleetAction {
     kind: FleetActionKind;
     /** Agent id for agent/login actions; undefined for cli/config actions. */
     agent?: string;
+    /** Full agent spec for `add-agent` (e.g. `claude@2.1.170`) so the plan can show
+     * the exact version being installed; equals the id for a bare/latest spec. */
+    spec?: string;
     /** Human, one-line description of the action. */
     detail: string;
 }

package/dist/lib/fs-walk.d.ts

@@ -1,3 +1,16 @@
+/** A file surfaced by the walk, carrying the mtime+size from the walk's own stat. */
+export interface WalkedFile {
+    path: string;
+    mtimeMs: number;
+    size: number;
+}
+/**
+ * Walk a directory recursively for files with a given extension, newest first,
+ * keeping each match's mtime and size from the walk's own stat. Callers that
+ * then compare against the scan ledger reuse these instead of re-stat'ing every
+ * path — eliminating a second stat per file on the Codex/Droid/routine scans.
+ */
+export declare function walkForFilesWithStat(dir: string, ext: string, limit: number): WalkedFile[];
 /** Walk a directory recursively for files with a given extension, newest first. */
 export declare function walkForFiles(dir: string, ext: string, limit: number): string[];
 /**

package/dist/lib/fs-walk.js

@@ -36,20 +36,29 @@ function walkEntries(dir, ext, onFile) {
             else if (entry.name.endsWith(ext)) {
                 const stat = safeStatSync(full);
                 if (stat)
-                    onFile(full, stat.mtimeMs);
+                    onFile(full, stat.mtimeMs, stat.size);
             }
         }
     }
     walk(dir, 0);
 }
-/** Walk a directory recursively for files with a given extension, newest first. */
-export function walkForFiles(dir, ext, limit) {
+/**
+ * Walk a directory recursively for files with a given extension, newest first,
+ * keeping each match's mtime and size from the walk's own stat. Callers that
+ * then compare against the scan ledger reuse these instead of re-stat'ing every
+ * path — eliminating a second stat per file on the Codex/Droid/routine scans.
+ */
+export function walkForFilesWithStat(dir, ext, limit) {
     const results = [];
-    walkEntries(dir, ext, (filePath, mtimeMs) => {
-        results.push({ path: filePath, mtime: mtimeMs });
+    walkEntries(dir, ext, (filePath, mtimeMs, size) => {
+        results.push({ path: filePath, mtimeMs, size });
     });
-    results.sort((a, b) => b.mtime - a.mtime);
-    return results.slice(0, limit).map(r => r.path);
+    results.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return results.slice(0, limit);
+}
+/** Walk a directory recursively for files with a given extension, newest first. */
+export function walkForFiles(dir, ext, limit) {
+    return walkForFilesWithStat(dir, ext, limit).map(r => r.path);
 }
 /**
  * Return the newest mtime (ms) among files with the given extension, or null

package/dist/lib/heal.d.ts

@@ -87,10 +87,13 @@ export declare function healChangedAnything(r: HealResult): boolean;
 /** One-line summary of a heal pass for daemon logs. */
 export declare function summarizeHeal(r: HealResult): string;
 /**
- * Fire a native desktop notification when a background heal did something
- * noteworthy. Best-effort — missing `osascript`/`notify-send` or no display is
- * swallowed. Silent when the pass auto-fixed everything and nothing needs the
- * operator (no point pinging them for routine self-healing).
+ * Fire a branded desktop notification when a background heal did something
+ * noteworthy. Routed through the MenubarHelper companion (notify-desktop.ts) so
+ * it carries the agents-cli mark; clicking opens the runs folder
+ * (~/.agents/.history/runs, via the `routines:list` action the companion
+ * understands). Best-effort — a missing
+ * notifier or no display is swallowed. Silent when the pass auto-fixed everything
+ * and nothing needs the operator (no point pinging them for routine self-healing).
  */
 export declare function notifyHeal(r: HealResult): void;
 /**

package/dist/lib/heal.js

@@ -30,7 +30,7 @@ import { repairPluginManifestFile } from './plugin-marketplace.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { spawn } from 'child_process';
+import { notifyDesktop } from './menubar/notify-desktop.js';
 // ─── diff → selection mapping ────────────────────────────────────────────────
 // Which ResourceSelection key each healable diff kind writes through. `rules`
 // re-syncs via the whole-memory channel (not name-scoped); `promptcuts` is not
@@ -68,10 +68,13 @@ export function summarizeHeal(r) {
     return parts.length > 0 ? parts.join(', ') : 'nothing to heal';
 }
 /**
- * Fire a native desktop notification when a background heal did something
- * noteworthy. Best-effort — missing `osascript`/`notify-send` or no display is
- * swallowed. Silent when the pass auto-fixed everything and nothing needs the
- * operator (no point pinging them for routine self-healing).
+ * Fire a branded desktop notification when a background heal did something
+ * noteworthy. Routed through the MenubarHelper companion (notify-desktop.ts) so
+ * it carries the agents-cli mark; clicking opens the runs folder
+ * (~/.agents/.history/runs, via the `routines:list` action the companion
+ * understands). Best-effort — a missing
+ * notifier or no display is swallowed. Silent when the pass auto-fixed everything
+ * and nothing needs the operator (no point pinging them for routine self-healing).
  */
 export function notifyHeal(r) {
     const needsAttention = r.skippedPlugins.length;
@@ -79,27 +82,12 @@ export function notifyHeal(r) {
     if (needsAttention === 0 && healed === 0)
         return;
     const title = needsAttention > 0
-        ? `agents: ${needsAttention} plugin${needsAttention === 1 ? '' : 's'} need attention`
+        ? `${needsAttention} plugin${needsAttention === 1 ? '' : 's'} need attention`
         : 'agents: auto-healed config gaps';
     const body = needsAttention > 0
         ? `${summarizeHeal(r)}. Run: agents doctor --fix`
         : summarizeHeal(r);
-    const platform = os.platform();
-    try {
-        if (platform === 'darwin') {
-            const safeTitle = title.replace(/"/g, '\\"');
-            const safeBody = body.replace(/"/g, '\\"');
-            const child = spawn('osascript', ['-e', `display notification "${safeBody}" with title "${safeTitle}"`], { detached: true, stdio: 'ignore' });
-            child.unref();
-        }
-        else if (platform === 'linux') {
-            const child = spawn('notify-send', [title, body], { detached: true, stdio: 'ignore' });
-            child.unref();
-        }
-    }
-    catch {
-        // Notification is best-effort; nothing to do.
-    }
+    notifyDesktop({ title, body, action: 'routines:list' });
 }
 // ─── central plugin layer (version-independent, runs once per heal) ──────────
 /**

package/dist/lib/hooks.d.ts

@@ -139,6 +139,7 @@ export declare function listCentralHooks(): HookEntry[];
 export declare function parseHookManifest(opts?: {
     warn?: boolean;
 }): Record<string, ManifestHook>;
+export declare function selectHookManifest(manifest: Record<string, ManifestHook>, selected: string[]): Record<string, ManifestHook>;
 /**
  * Hook script files present on disk that no manifest entry declares — "dead"
  * hooks. The registrar only wires manifest-declared hooks into an agent's

package/dist/lib/hooks.js

@@ -801,6 +801,10 @@ export function parseHookManifest(opts = {}) {
     }
     return merged;
 }
+export function selectHookManifest(manifest, selected) {
+    const selectedHooks = new Set(selected);
+    return Object.fromEntries(Object.entries(manifest).filter(([name, hook]) => selectedHooks.has(name) || selectedHooks.has(path.basename(hook.script))));
+}
 /**
  * Hook script files present on disk that no manifest entry declares — "dead"
  * hooks. The registrar only wires manifest-declared hooks into an agent's
@@ -934,6 +938,15 @@ function sweepOrphanShims(manifest) {
 export function registerHooksToSettings(agentId, versionHome, hookManifest, agentsDirOverride) {
     const manifest = hookManifest || parseHookManifest();
     if (Object.keys(manifest).length === 0) {
+        if (agentId === 'opencode') {
+            const pluginPath = path.join(versionHome, '.config', 'opencode', 'plugins', 'agents-cli-hooks.ts');
+            try {
+                fs.rmSync(pluginPath, { force: true });
+            }
+            catch (e) {
+                return { registered: [], errors: [`Failed to remove agents-cli-hooks.ts: ${e.message}`] };
+            }
+        }
         return { registered: [], errors: [] };
     }
     sweepOrphanShims(manifest);
@@ -991,6 +1004,9 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     if (agentId === 'grok') {
         return registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefixes);
     }
+    if (agentId === 'opencode') {
+        return registerHooksForOpenCode(versionHome, manifest, resolveScript);
+    }
     if (agentId === 'kimi') {
         return registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefixes);
     }
@@ -1011,6 +1027,146 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     }
     return { registered: [], errors: [] };
 }
+const OPENCODE_DIRECT_EVENT_MAP = {
+    PreToolUse: 'tool.execute.before',
+    PostToolUse: 'tool.execute.after',
+    UserPromptSubmit: 'chat.message',
+};
+const OPENCODE_LIFECYCLE_EVENT_MAP = {
+    SessionStart: ['session.created'],
+    SessionEnd: ['session.deleted'],
+    Stop: ['session.idle', 'session.error'],
+    PreCompact: ['session.compacted'],
+    OnError: ['session.error'],
+    Notification: ['permission.asked'],
+};
+/**
+ * Compile canonical hooks.yaml entries into a local OpenCode plugin.
+ *
+ * OpenCode has no declarative shell-hook config block. It auto-loads direct
+ * TS/JS modules from ~/.config/opencode/plugins/, and supplies Bun's `$` shell
+ * primitive to each plugin. The generated module subscribes to native plugin
+ * events, sends the event payload to the managed hook script as JSON on stdin,
+ * and surfaces a non-zero script exit as a plugin error.
+ */
+function registerHooksForOpenCode(versionHome, manifest, resolveScript) {
+    const registered = [];
+    const errors = [];
+    const direct = new Map();
+    const lifecycle = new Map();
+    for (const [name, hookDef] of Object.entries(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
+            continue;
+        const command = resolveHookCommand(name, hookDef, resolveScript);
+        if (!command) {
+            errors.push(`${name}: script not found`);
+            continue;
+        }
+        const generated = {
+            name,
+            command,
+            ...(hookDef.timeout !== undefined ? { timeout: hookDef.timeout } : {}),
+            ...(hookDef.matcher ? { matcher: hookDef.matcher } : {}),
+        };
+        for (const event of hookDef.events) {
+            const directEvent = OPENCODE_DIRECT_EVENT_MAP[event];
+            if (directEvent) {
+                const hooks = direct.get(directEvent) ?? [];
+                hooks.push(generated);
+                direct.set(directEvent, hooks);
+                registered.push(`${name} -> ${directEvent}`);
+            }
+            for (const lifecycleEvent of OPENCODE_LIFECYCLE_EVENT_MAP[event] ?? []) {
+                const hooks = lifecycle.get(lifecycleEvent) ?? [];
+                hooks.push(generated);
+                lifecycle.set(lifecycleEvent, hooks);
+                registered.push(`${name} -> ${lifecycleEvent}`);
+            }
+        }
+    }
+    const serializedDirect = JSON.stringify(Object.fromEntries(direct), null, 2);
+    const serializedLifecycle = JSON.stringify(Object.fromEntries(lifecycle), null, 2);
+    const pluginSource = `// Generated by agents-cli. Re-run agents sync to update.
+const directHooks = ${serializedDirect}
+const lifecycleHooks = ${serializedLifecycle}
+
+function matches(hook, tool) {
+  if (!hook.matcher) return true
+  try {
+    return new RegExp(hook.matcher).test(tool)
+  } catch {
+    return hook.matcher === tool
+  }
+}
+
+async function runHooks(hooks, payload, $, matchTool = false) {
+  for (const hook of hooks ?? []) {
+    if (matchTool && !matches(hook, payload.tool_name ?? "")) continue
+    const input = JSON.stringify(payload)
+    const home = Bun.env.HOME ?? Bun.env.USERPROFILE ?? ""
+    const command = hook.command.startsWith("~/")
+      ? \`\${home}/\${hook.command.slice(2)}\`
+      : hook.command
+    const shell = Bun.which("bash") ?? Bun.which("sh")
+    if (!shell) throw new Error(\`\${hook.name} requires bash or sh\`)
+    const execArgs = [shell, "-c", 'exec "$1"', "agents-hook", command]
+    if (hook.timeout !== undefined) {
+      const child = Bun.spawn(execArgs, {
+        stdin: new Response(input),
+        stdout: "ignore",
+        stderr: "pipe",
+      })
+      let timedOut = false
+      const timer = setTimeout(() => {
+        timedOut = true
+        if (process.platform === "win32") {
+          Bun.spawnSync(["taskkill", "/PID", String(child.pid), "/T", "/F"])
+        } else {
+          child.kill()
+        }
+      }, hook.timeout * 1000)
+      const exitCode = await child.exited.finally(() => clearTimeout(timer))
+      const stderr = await new Response(child.stderr).text()
+      if (timedOut) {
+        throw new Error(\`\${hook.name} timed out after \${hook.timeout} seconds\`)
+      }
+      if (exitCode !== 0) {
+        throw new Error(\`\${hook.name} failed with exit code \${exitCode}: \${stderr.trim()}\`)
+      }
+      continue
+    }
+    const result = await $\`\${shell} -c \${'exec "$1"'} \${"agents-hook"} \${command} < \${new Response(input)}\`.nothrow().quiet()
+    if (result.exitCode !== 0) {
+      throw new Error(\`\${hook.name} failed with exit code \${result.exitCode}: \${result.stderr.toString().trim()}\`)
+    }
+  }
+}
+
+export const AgentsCliHooks = async ({ $ }) => ({
+  event: async ({ event }) => {
+    await runHooks(lifecycleHooks[event.type], { hook_event_name: event.type, ...event }, $)
+  },
+  "chat.message": async (input, output) => {
+    await runHooks(directHooks["chat.message"], { hook_event_name: "UserPromptSubmit", ...input, ...output }, $)
+  },
+  "tool.execute.before": async (input, output) => {
+    await runHooks(directHooks["tool.execute.before"], { hook_event_name: "PreToolUse", tool_name: input.tool, tool_input: output.args, ...input }, $, true)
+  },
+  "tool.execute.after": async (input, output) => {
+    await runHooks(directHooks["tool.execute.after"], { hook_event_name: "PostToolUse", tool_name: input.tool, tool_input: input.args, tool_response: output, ...input }, $, true)
+  },
+})
+`;
+    const pluginDir = path.join(versionHome, '.config', 'opencode', 'plugins');
+    try {
+        fs.mkdirSync(pluginDir, { recursive: true });
+        fs.writeFileSync(path.join(pluginDir, 'agents-cli-hooks.ts'), pluginSource, 'utf-8');
+    }
+    catch (e) {
+        errors.push(`Failed to write agents-cli-hooks.ts: ${e.message}`);
+    }
+    return { registered, errors };
+}
 /**
  * Antigravity (agy) event names differ from agents-cli manifest names. The
  * mapping below is the documented agy schema. PostToolUse has no exact

package/dist/lib/hosts/dispatch.d.ts

@@ -20,6 +20,15 @@ import { type HostCredentials } from './credentials.js';
  * remainder. Any other path (absolute or relative) is quoted verbatim.
  */
 export declare function remoteCdPrefix(remoteCwd?: string): string;
+/**
+ * Merge the resolved actor's provenance env UNDER a caller-supplied env, so every
+ * remote `agents …` invocation forwards `AGENTS_ACTOR*` / `GIT_*` across the SSH
+ * hop. Without it the remote re-resolves the actor from the ORIGINATING box's
+ * `SSH_CONNECTION` (the wrong IP) and mis-credits the run to the shared machine or
+ * `UNRESOLVED@<host>` (RUSH-2028). A caller-supplied value wins on any key
+ * collision, mirroring `buildExecEnv`'s `...options.env` precedence (exec.ts).
+ */
+export declare function withActorEnv(env?: Record<string, string>): Record<string, string>;
 /**
  * Launch a detached login-shell command in its own Unix session/process group.
  *
@@ -107,6 +116,13 @@ export interface DispatchOptions {
     name?: string;
     /** Resume an existing session on the host by id (via `agents run --resume`). */
     resume?: string;
+    /**
+     * Forward `--emit-session-id` so the remote run prints its resolved session id
+     * as a stdout sentinel (hosts/session-marker.ts). The launcher parses that id
+     * out of the followed log and stamps it on the task — the join that maps a
+     * remote-created session back home for agents that don't take `--session-id`.
+     */
+    emitSessionId?: boolean;
     /** Stream progress and block until completion (default true). */
     follow?: boolean;
     timeoutMs?: number;

package/dist/lib/hosts/dispatch.js

@@ -12,8 +12,9 @@ import { randomUUID } from 'crypto';
 import { sshExec, sshStream, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from './types.js';
 import { ensureHostReady } from './ready.js';
-import { remoteShellFor } from './remote-cmd.js';
+import { remoteShellFor, posixEnvExports } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
+import { resolveActor, actorEnv } from '../actor.js';
 import { saveTask, updateTask, terminalPatch } from './tasks.js';
 import { followHostTask } from './progress.js';
 import { wrapHostCommandWithCredentials } from './credentials.js';
@@ -56,6 +57,17 @@ export function remoteCdPrefix(remoteCwd) {
         return `cd "$HOME"/${shellQuote(rest)} && `;
     return `cd ${shellQuote(remoteCwd)} && `;
 }
+/**
+ * Merge the resolved actor's provenance env UNDER a caller-supplied env, so every
+ * remote `agents …` invocation forwards `AGENTS_ACTOR*` / `GIT_*` across the SSH
+ * hop. Without it the remote re-resolves the actor from the ORIGINATING box's
+ * `SSH_CONNECTION` (the wrong IP) and mis-credits the run to the shared machine or
+ * `UNRESOLVED@<host>` (RUSH-2028). A caller-supplied value wins on any key
+ * collision, mirroring `buildExecEnv`'s `...options.env` precedence (exec.ts).
+ */
+export function withActorEnv(env) {
+    return { ...actorEnv(resolveActor()), ...(env ?? {}) };
+}
 /**
  * Launch a detached login-shell command in its own Unix session/process group.
  *
@@ -174,10 +186,14 @@ async function launchDetached(host, target, opts) {
     const id = randomUUID().slice(0, 8);
     const remoteLog = `${REMOTE_DIR}/${id}.log`;
     const remoteExit = `${REMOTE_DIR}/${id}.exit`;
-    // Inner command run under a login shell so PATH resolves `agents`.
+    // Inner command run under a login shell so PATH resolves `agents`. Export the
+    // resolved actor provenance first so the detached remote run inherits it
+    // instead of re-resolving from this box's SSH_CONNECTION (RUSH-2028).
     const invocation = ['agents', ...opts.forwardedArgs].map(shellQuote).join(' ');
     const cwd = remoteCdPrefix(opts.remoteCwd);
-    let inner = `${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
+    const actorExports = posixEnvExports(withActorEnv());
+    const prelude = actorExports ? `${actorExports}; ` : '';
+    let inner = `${prelude}${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
     if (opts.copyCreds) {
         inner = wrapHostCommandWithCredentials(inner, opts.copyCreds);
     }
@@ -298,6 +314,8 @@ export function buildRunForwardedArgs(opts) {
         args.push('--resume', opts.resume);
     else if (opts.sessionId)
         args.push('--session-id', opts.sessionId);
+    if (opts.emitSessionId)
+        args.push('--emit-session-id');
     if (opts.passthroughArgs && opts.passthroughArgs.length > 0)
         args.push('--', ...opts.passthroughArgs);
     return args;
@@ -368,7 +386,11 @@ export async function runInteractiveOnHost(host, opts) {
         process.stderr.write(`[hosts] warning: ${w}\n`);
     const invocation = ['agents', ...buildInteractiveRunForwardedArgs(opts)].map(shellQuote).join(' ');
     const cwd = remoteCdPrefix(opts.remoteCwd);
-    let remoteCmd = `${cwd}${invocation}`;
+    // Forward actor provenance so the interactive remote run inherits it rather
+    // than re-resolving from this box's SSH_CONNECTION (RUSH-2028).
+    const actorExports = posixEnvExports(withActorEnv());
+    const prelude = actorExports ? `${actorExports}; ` : '';
+    let remoteCmd = `${prelude}${cwd}${invocation}`;
     if (opts.copyCreds) {
         remoteCmd = wrapHostCommandWithCredentials(remoteCmd, opts.copyCreds);
     }

package/dist/lib/hosts/passthrough.js

@@ -20,7 +20,7 @@ import chalk from 'chalk';
 import { assertValidSshTarget, sshStream } from '../ssh-exec.js';
 import { resolveHost, resolveHostByCap } from './registry.js';
 import { sshTargetFor } from './types.js';
-import { dispatchAgentsCommand } from './dispatch.js';
+import { dispatchAgentsCommand, withActorEnv } from './dispatch.js';
 import { stripRoutingFlags, buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { machineId } from '../session/sync/config.js';
@@ -98,6 +98,8 @@ const REMOTE_PASSTHROUGH = {
 const OWN_HOST_COMMANDS = new Set([
     'run',
     'exec', // deprecated alias of run
+    'harness', // `--host <agent>` names the host CLI to run under, not a remote device
+    'harnesses',
     'sessions',
     'feed',
     'computer',
@@ -265,9 +267,14 @@ export async function maybeRunOnHost(command, allArgs) {
     // profile, and single-quoted env values would not expand $HOME/$PATH.
     const isDoctorCommand = command === 'doctor' || (command === 'teams' && forwarded[1] === 'doctor');
     const remoteOs = resolveRemoteOsSync(host.name);
-    const env = isDoctorCommand && !/^win/i.test((remoteOs ?? '').trim())
+    const doctorPath = isDoctorCommand && !/^win/i.test((remoteOs ?? '').trim())
         ? { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' }
         : undefined;
+    // Forward actor provenance (AGENTS_ACTOR*/GIT_*) across the SSH hop, merged
+    // UNDER the doctor PATH so that PATH still wins — without this the remote
+    // re-resolves the actor from THIS box's SSH_CONNECTION and mis-credits it
+    // (RUSH-2028). Flows to both POSIX (export) and Windows ($env:) dialects.
+    const env = withActorEnv(doctorPath);
     const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd, remoteOs, env);
     const code = sshStream(target, remoteCmd, { tty: interactive, multiplex: true });
     if (code === 255) {

package/dist/lib/hosts/reconnect.d.ts

@@ -0,0 +1,78 @@
+import { type Host } from './types.js';
+/** ssh's connection-layer failure code — the signal that the link dropped rather
+ *  than the remote command exiting on its own. Mirrors ssh-exec.ts `sshStream`. */
+export declare const SSH_CONN_FAILURE = 255;
+/** Consecutive failed-to-connect reattaches before giving up. Backoff is capped at
+ *  {@link MAX_BACKOFF_MS}. A reattach that actually reconnected (then dropped again)
+ *  refills the budget, so a long session that blinks all day reconnects every time
+ *  — only consecutive UNREACHABLE attempts exhaust it. */
+export declare const MAX_ATTEMPTS = 6;
+export interface ReconnectState {
+    /** Consecutive failed-to-connect reattaches since the last genuine reconnection. */
+    attempt: number;
+}
+export interface ReconnectOutcome {
+    /** Exit code of the run (initial) or the last re-attach. */
+    code: number;
+    /** Whether the ssh handshake for this attempt actually completed. The initial run
+     *  and any reattach whose preflight probe succeeded are `connected`; a reattach
+     *  that couldn't reach the host is not. Drives the budget refill (see file head). */
+    connected: boolean;
+}
+export type ReconnectDecision = {
+    action: 'stop';
+    code: number;
+} | {
+    action: 'retry';
+    waitMs: number;
+    state: ReconnectState;
+};
+export declare function initialReconnectState(): ReconnectState;
+/** Exponential backoff capped at {@link MAX_BACKOFF_MS}: 2s, 4s, 8s, 16s, 30s… */
+export declare function backoffMs(attempt: number): number;
+/**
+ * Decide what to do after a run/re-attach returned `outcome`. Pure — the only
+ * input is the prior state and the outcome, the only output is the next action.
+ *
+ *  - a non-255 code means the remote command spoke for itself (clean detach = 0,
+ *    agent exit / no live session = non-zero) → stop and surface that code.
+ *  - a 255 means the link dropped → retry, unless the budget is spent.
+ *  - a 255 from an attempt that DID connect (a genuine reconnection that then
+ *    dropped) refills the budget first; a 255 that never connected counts against
+ *    it, so a host that stays unreachable gives up after MAX_ATTEMPTS.
+ */
+export declare function reconnectStep(state: ReconnectState, outcome: ReconnectOutcome): ReconnectDecision;
+/** Human-readable notice shown before each reconnect wait. "13 seconds", not "12.8s". */
+export declare function reconnectNotice(sessionId: string, host: string, attempt: number, waitMs: number): string;
+/** Notice shown once the retry budget is spent. */
+export declare function exhaustedNotice(sessionId: string, host: string): string;
+/**
+ * Re-attach the live remote tmux pane for `sessionId` by driving the peer's own
+ * `agents sessions focus`. A fast, un-multiplexed preflight probe (`ssh … true`)
+ * first establishes whether the host is actually reachable this attempt — that
+ * `connected` bit, not the call duration, is what the retry policy keys on. Only on
+ * a reachable host do we run the interactive attach (which carries no credentials —
+ * the agent already runs on the peer — so it rides the normal transport). Returns
+ * the ssh exit code (255 = dropped again / unreachable; 0 = clean detach; other =
+ * session ended) plus whether this attempt connected.
+ */
+export declare function reattachRemoteSession(host: Host, sessionId: string): ReconnectOutcome;
+export interface ReconnectLoopOpts {
+    host: Host;
+    sessionId: string;
+    /** The exit code from the initial interactive run (which, having run the agent,
+     *  is treated as a connected attempt). */
+    initialExit: number;
+    /** Injected for tests: the real re-attach and wait are swapped for deterministic
+     *  fakes so the loop's control flow is exercised without SSH. Production uses the
+     *  real {@link reattachRemoteSession} + `sleep`. */
+    reattach?: (host: Host, sessionId: string) => ReconnectOutcome;
+    wait?: (ms: number) => Promise<void>;
+    write?: (s: string) => void;
+}
+/**
+ * Drive the reconnect loop from the initial run's outcome to a terminal code.
+ * Only the real SSH re-attach and the wait are side effects; the decision is
+ * {@link reconnectStep}. Returns the exit code the process should ultimately use.
+ */
+export declare function reconnectInteractiveSession(opts: ReconnectLoopOpts): Promise<number>;