@sentropic/remote-cli 0.0.3

package/dist/index.d.ts

@@ -0,0 +1,730 @@
+#!/usr/bin/env node
+/**
+ * Live-session registry — the source of truth for `remote ls` / `remote
+ * restore`, so they stop GUESSING sessions from filesystem mtimes.
+ *
+ * Entries land here from:
+ *  - `remote run`        (source "run"  — local tmux sessions),
+ *  - Claude Code hooks   (source "hook" — `remote enroll --hook claude-*`),
+ *  - the restore scanner (source "scan" — legacy fallback),
+ *  - the control-plane   (source "remote" — reconciled by the caller).
+ *
+ * The file is `<configDir>/registry.json`, written atomically (tmp + rename).
+ * Every function takes an optional explicit path so tests never touch the real
+ * config dir (default path honors REMOTE_CLI_CONFIG_HOME like config.ts).
+ */
+type RegistryTool = "claude" | "codex" | "agy";
+type RegistryKind = "local-tmux" | "local" | "remote";
+type RegistrySource = "run" | "hook" | "scan" | "remote";
+/**
+ * Delegated-job extension (P1 of cross-type agent delegation). A job IS a
+ * RegistryEntry with `role: "job"` — same atomic-write, same liveness guards,
+ * same `listLive`. These fields are OPTIONAL so every existing entry stays a
+ * valid RegistryEntry (back-compat).
+ */
+type RegistryRole = "job";
+type JobState = "pending" | "running" | "throttled" | "done" | "failed";
+/**
+ * Rate-limit ("throttled") bookkeeping for a HEADLESS LOCAL job whose agent CLI
+ * hit a TRANSIENT provider rate-limit (reliability slice 1). A throttled job
+ * KEEPS its concurrency slot (the limit is account-wide; admitting a replacement
+ * just burns the same quota) and is auto-resumed by the conductor on
+ * `nextRetryAt` with exponential backoff, up to a hard attempt cap. All fields
+ * are written under `withRegistryLock`; the whole object is optional so every
+ * existing entry stays a valid RegistryEntry (back-compat).
+ */
+type ThrottleInfo = {
+    /** How many times this job has entered `throttled` (drives the backoff). */
+    attempts: number;
+    /** ISO ts of the FIRST throttle (for age / history windows). */
+    firstAt: string;
+    /** ISO ts the conductor may resume the job at (now + jitteredDelay(attempts)). */
+    nextRetryAt: string;
+    /** The signature tag that classified the last throttle (e.g. claude:rate-limited). */
+    lastSignature?: string;
+};
+type RegistryEntry = {
+    /** Stable key: claude session uuid / codex rollout id / remoteId / tmux slug. */
+    id: string;
+    tool: RegistryTool;
+    kind: RegistryKind;
+    cwd: string;
+    label?: string;
+    /** Conversation id usable with the CLI's --resume. */
+    convId?: string;
+    /** Control-plane session id (kind "remote"). */
+    remoteId?: string;
+    /** Full tmux session name (kind "local-tmux"), e.g. `remote-surch`. */
+    tmuxSession?: string;
+    /** Local process id (kind "local"); liveness = process.kill(pid, 0). */
+    pid?: number;
+    enrolledAt: string;
+    lastSeenAt: string;
+    endedAt?: string;
+    source: RegistrySource;
+    /** "job" marks a delegated agent (see `delegate.ts`); absent = a session. */
+    role?: RegistryRole;
+    /** Lifecycle of a delegated job (role "job" only). */
+    jobState?: JobState;
+    /** Parent job/session id that delegated this job. */
+    parent?: string;
+    /** The task the delegated agent was primed with. */
+    task?: string;
+    /** h2a instance to address the `job.done` callback to (P3); the delegating
+     * parent/master. Absent = no callback recipient (best-effort, no-op). */
+    callbackTo?: string;
+    /**
+     * P4 — queued-launch spec. A job over the concurrency cap is enrolled
+     * `pending` WITHOUT being launched; the conductor launches it later. These
+     * fields carry everything `startJob` needs to launch it from the queue (they
+     * are also set on an immediately-launched job, harmlessly). All optional so
+     * every existing entry stays a valid RegistryEntry (back-compat).
+     */
+    /** Run the job in a Pod (the remote control-plane URL), else a local tmux session. */
+    remoteTarget?: string;
+    /** Run-once-exit headless mode (claude -p / codex exec). */
+    headless?: boolean;
+    /** The cwd the delegate was invoked from (origin for the per-job worktree/logs). */
+    originCwd?: string;
+    /** Explicit `--cwd` override (local; used as-is, no worktree). */
+    explicitCwd?: string;
+    /** Remaining spawn-depth budget this job may spend if it re-delegates (P4 depth clamp). */
+    depthBudget?: number;
+    /** Track workpackage id to mirror this job under (`track item new --parent`). */
+    trackWp?: string;
+    /** Rate-limit backoff/resume bookkeeping (HEADLESS LOCAL only; reliability slice 1). */
+    throttle?: ThrottleInfo;
+    /** Model override passed to the CLI binary (--model for claude, -m for codex). */
+    model?: string;
+    /** Effort/reasoning override (claude --effort; not supported by codex). */
+    effort?: string;
+    /** Force a specific account from the pool (bypass selectAccountWithFallback). */
+    accountId?: string;
+};
+
+type PtyHandle = {
+    readonly cols: number;
+    readonly rows: number;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+    onData(handler: (chunk: string) => void): {
+        dispose(): void;
+    };
+    onExit(handler: (event: {
+        exitCode: number;
+        signal?: number;
+    }) => void): {
+        dispose(): void;
+    };
+};
+type PtySpawner = (options: {
+    command: string;
+    args: ReadonlyArray<string>;
+    cwd: string;
+    env: Readonly<Record<string, string>>;
+    cols: number;
+    rows: number;
+}) => PtyHandle;
+
+type RunOptions = {
+    readonly profile: string;
+    readonly resume?: string | true | undefined;
+    readonly port?: number;
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly startupArgs?: ReadonlyArray<string>;
+    readonly stdin?: NodeJS.ReadStream;
+    readonly stdout?: NodeJS.WriteStream;
+    readonly spawner?: PtySpawner;
+    readonly randomId?: (prefix: string) => string;
+    readonly clock?: () => Date;
+    readonly initialSize?: {
+        cols: number;
+        rows: number;
+    };
+};
+type RunResult = {
+    readonly sessionId: string;
+    readonly port: number;
+    readonly exit: Promise<{
+        exitCode: number;
+        signal?: number;
+    }>;
+    readonly stop: () => Promise<void>;
+};
+declare function run(options: RunOptions): Promise<RunResult>;
+
+type InputRetryOptions = {
+    readonly maxAttempts?: number;
+    readonly baseDelayMs?: number;
+    readonly maxDelayMs?: number;
+};
+type AttachOptions = {
+    readonly baseUrl: string;
+    readonly sessionId: string;
+    readonly stdin?: NodeJS.ReadStream;
+    readonly stdout?: NodeJS.WriteStream;
+    readonly stderr?: NodeJS.WriteStream;
+    readonly fetchImpl?: typeof fetch;
+    readonly inputRetry?: InputRetryOptions;
+};
+type AttachResult = {
+    readonly close: () => Promise<void>;
+    readonly finished: Promise<void>;
+};
+declare function attach(options: AttachOptions): Promise<AttachResult>;
+declare function listRemoteSessions(baseUrl: string, fetchImpl?: typeof fetch): Promise<ReadonlyArray<{
+    id: string;
+    profile: string;
+    target: string;
+    createdAt: string;
+    workspaceId?: string;
+    workspacePath?: string;
+    displayName?: string;
+    cliSessionId?: string;
+}>>;
+declare function stopRemoteSession(baseUrl: string, sessionId: string, reason?: string, fetchImpl?: typeof fetch): Promise<{
+    accepted: boolean;
+}>;
+declare function getRemoteSession(baseUrl: string, sessionId: string, fetchImpl?: typeof fetch): Promise<{
+    session: {
+        id: string;
+        profile: string;
+    };
+}>;
+declare function refreshRemoteSession(baseUrl: string, sessionId: string, credentials: Readonly<Record<string, string>>, fetchImpl?: typeof fetch, displayName?: string): Promise<{
+    sessionId: string;
+    accepted: boolean;
+}>;
+/**
+ * Rename a session's display name in the store without touching the Pod.
+ * Calls PATCH /sessions/:id with body { displayName }.
+ */
+declare function renameRemoteSession(baseUrl: string, sessionId: string, displayName: string, fetchImpl?: typeof fetch): Promise<{
+    sessionId: string;
+    displayName: string;
+    accepted: boolean;
+}>;
+declare function createRemoteSession(baseUrl: string, body: {
+    profile: string;
+    target?: string;
+    resume?: string;
+    startupArgs?: readonly string[];
+    displayName?: string;
+    credentials?: Readonly<Record<string, string>>;
+    metadata?: Readonly<Record<string, unknown>>;
+    workspaceSync?: boolean;
+    workspaceExport?: boolean;
+    workspaceId?: string;
+    workspacePath?: string;
+    home?: string;
+    agentImage?: string;
+}, fetchImpl?: typeof fetch): Promise<{
+    id: string;
+}>;
+
+declare const CLI_PROFILES: readonly ["shell", "codex", "opencode", "claude", "agy", "gemini", "mistral"];
+type CliProfile = (typeof CLI_PROFILES)[number];
+type SessionTarget = "docker" | "k3s" | "scaleway-kapsule" | "gke";
+
+type AuthBundle = Readonly<Record<string, string>>;
+declare class AuthBundleMissingError extends Error {
+    readonly profile: CliProfile;
+    readonly knownPaths: ReadonlyArray<string>;
+    readonly refreshHint: string;
+    constructor(profile: CliProfile, knownPaths: ReadonlyArray<string>, refreshHint: string);
+}
+type CollectAuthOptions = {
+    readonly home?: string;
+    readonly readFileImpl?: (path: string) => Promise<Uint8Array | Buffer>;
+};
+declare function collectProfileAuth(profile: CliProfile, options?: CollectAuthOptions): Promise<AuthBundle>;
+declare function assertRequiredAuthBundle(profile: CliProfile, bundle: AuthBundle): void;
+
+type CommandResult = {
+    readonly status: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut?: boolean;
+};
+type RunCommand = (command: string, args: ReadonlyArray<string>, options: {
+    timeoutMs: number;
+}) => Promise<CommandResult>;
+type AuthRefreshResult = {
+    readonly checked: true;
+    readonly command: string;
+} | {
+    readonly checked: false;
+    readonly reason: "no-status-command";
+};
+type EnsureAuthFreshOptions = {
+    readonly timeoutMs?: number;
+    readonly runCommand?: RunCommand;
+};
+declare class AuthRefreshError extends Error {
+    readonly profile: CliProfile;
+    readonly refreshHint: string;
+    readonly result: CommandResult;
+    constructor(profile: CliProfile, refreshHint: string, result: CommandResult);
+}
+declare function ensureProfileAuthFresh(profile: CliProfile, options?: EnsureAuthFreshOptions): Promise<AuthRefreshResult>;
+
+type AuthDiagnosticsStatus = AuthRefreshResult | {
+    readonly checked: false;
+    readonly reason: "skipped";
+};
+type AuthDiagnosticsResult = {
+    readonly profile: CliProfile;
+    readonly authStatus: AuthDiagnosticsStatus;
+    readonly bundledFiles: ReadonlyArray<string>;
+};
+type InspectProfileAuthOptions = CollectAuthOptions & {
+    readonly authRefresh?: boolean;
+    readonly runCommand?: RunCommand;
+};
+declare function inspectProfileAuth(profile: CliProfile, options?: InspectProfileAuthOptions): Promise<AuthDiagnosticsResult>;
+
+type ProfileConfig = {
+    readonly profile: CliProfile;
+    readonly command: string;
+    readonly args: ReadonlyArray<string>;
+};
+declare function isCliProfile(value: string): value is CliProfile;
+declare function coerceCliProfileName(value: string): CliProfile | undefined;
+declare function resolveProfile(name: string): ProfileConfig;
+declare function withResume(config: ProfileConfig, sessionId?: string | true): ProfileConfig;
+
+type SmokeRemoteProfileOptions = {
+    readonly profile: CliProfile;
+    readonly baseUrl: string;
+    readonly target?: SessionTarget;
+    readonly displayName?: string;
+    readonly timeoutMs?: number;
+    readonly auth?: boolean;
+    readonly authRefresh?: boolean;
+    readonly fetchImpl?: typeof fetch;
+    readonly collectAuth?: (profile: CliProfile) => Promise<AuthBundle>;
+    readonly ensureAuthFresh?: (profile: CliProfile) => Promise<AuthRefreshResult>;
+};
+type SmokeRemoteProfileResult = {
+    readonly profile: CliProfile;
+    readonly sessionId: string;
+    readonly terminalId: string;
+    readonly shell: string;
+};
+declare function smokeRemoteProfile(options: SmokeRemoteProfileOptions): Promise<SmokeRemoteProfileResult>;
+
+type OnConflict = "backup" | "keep-local" | "block";
+
+/**
+ * remote migrate — convenience wrapper for round-tripping a local CLI session
+ * to a remote (SCW k8s) session and back.
+ *
+ * Forward (local → remote):
+ *   1. Resolve remote URL.
+ *   2. Ensure the cwd is linked to a workspace (reads .remote/workspace.json).
+ *   3. Push the workspace archive (project files, honours .gitignore).
+ *   4. Create a remote session for <profile> bound to that workspace.
+ *   5. Hand off the current terminal to the remote session via `attach`.
+ *      The attach call blocks until the session ends or the user detaches
+ *      (Ctrl+P Ctrl+Q). There is no separate process to kill — `migrate`
+ *      itself IS the process holding the terminal, and attach takes it over.
+ *
+ * Back (remote → local):
+ *   1. Resolve URL + workspace.
+ *   2. Pull the workspace + conversation state (3-way merge).
+ *   3. Restore conversation state to the local HOME.
+ *   4. Stop the remote session.
+ *   5. Print the exact local CLI command to resume from the restored state.
+ *      We do NOT spawn the CLI — we print the command so the user can run it.
+ */
+
+type MigrateForwardOptions = {
+    /** CLI profile to start on the remote (e.g. "claude", "codex"). */
+    readonly profile: string;
+    /** Remote control-plane URL. Required — callers must resolve the default. */
+    readonly remoteUrl: string;
+    /**
+     * Workspace id override. When set, the cwd does not need an existing
+     * .remote/workspace.json (one is created/reused for that id).
+     * When absent, the .remote/workspace.json for the cwd is used or a new
+     * workspace is created and linked.
+     */
+    readonly workspaceId?: string;
+    /**
+     * Whether to pass a --resume/<conv-id> flag to the remote CLI.
+     * Pass `true` for the most-recent conversation, or a specific id string.
+     */
+    readonly resume?: string | true;
+    /**
+     * When true, do NOT hijack the current terminal: push + create the remote
+     * session, print the `remote attach` command, and return. Used to migrate
+     * many sessions non-interactively and to let YOUR terminal reconnect to the
+     * remote session itself (rather than this process taking it over).
+     */
+    readonly noAttach?: boolean;
+    /**
+     * Revive a session on the EXISTING workspace without re-pushing the project
+     * (preserves work done remotely) — for bringing a session back after an
+     * accidental exit. Path/HOME parity + resume still apply; the conversation is
+     * the one already on the retained PVC.
+     */
+    readonly reconnect?: boolean;
+    /** Tool CLIs whose local auth to also bundle into the Pod (scw, gh, aws, …). */
+    readonly tools?: ReadonlyArray<string>;
+    /** Inject a custom fetch for tests. */
+    readonly fetchImpl?: typeof fetch;
+    /** Override process.cwd() for tests. */
+    readonly cwd?: string;
+    /** Override process.stderr.write for tests. */
+    readonly stderr?: NodeJS.WriteStream;
+};
+type MigrateForwardResult = {
+    /** The workspace id that was used/created. */
+    readonly workspaceId: string;
+    /** The remote session id that was created. */
+    readonly sessionId: string;
+};
+type MigrateBackOptions = {
+    /** Remote control-plane URL. Required — callers must resolve the default. */
+    readonly remoteUrl: string;
+    /** Workspace id override; falls back to .remote/workspace.json. */
+    readonly workspaceId?: string;
+    /** Known remote session id (from lineage incarnation). When set, skips the
+     * list-sessions round-trip and targets this session directly. */
+    readonly sessionId?: string;
+    /**
+     * Conflict resolution for diverged conversations: "backup" | "keep-local".
+     * Defaults to "block" (leaves diverged files untouched, exits non-zero).
+     */
+    readonly onConflict?: OnConflict;
+    /** Inject a custom fetch for tests. */
+    readonly fetchImpl?: typeof fetch;
+    /** Override process.cwd() for tests. */
+    readonly cwd?: string;
+    /** Override HOME for session restore in tests. */
+    readonly home?: string;
+    /** Override process.stderr.write for tests. */
+    readonly stderr?: NodeJS.WriteStream;
+    /** Override process.stdout.write for tests. */
+    readonly stdout?: NodeJS.WriteStream;
+};
+type MigrateBackResult = {
+    /** The workspace id that was pulled. */
+    readonly workspaceId: string;
+    /** The session id that was stopped, if any. */
+    readonly stoppedSessionId?: string;
+    /** The resume command to print for the user. */
+    readonly resumeCommand: string;
+    /** Whether there were unresolved merge conflicts. */
+    readonly hasConflicts: boolean;
+};
+/**
+ * Forward: migrate the current local session to a remote k8s session.
+ *
+ * Steps: link workspace → push files → create remote session → attach terminal.
+ *
+ * Terminal handoff: `migrateForward` calls `attach`, which hijacks the current
+ * process's stdin/stdout in raw mode and blocks until the remote session ends
+ * or the user presses Ctrl+P Ctrl+Q to detach. There is no separate process
+ * involved — this function IS the process holding the terminal.
+ */
+declare function migrateForward(options: MigrateForwardOptions): Promise<MigrateForwardResult>;
+/**
+ * Back: pull the remote session back to local.
+ *
+ * Steps: pull workspace + conversation state → stop remote session → print
+ * resume command.
+ *
+ * We do NOT spawn the local CLI — we print the resume command so the user
+ * retains control of when and how they restart.
+ */
+declare function migrateBack(options: MigrateBackOptions): Promise<MigrateBackResult>;
+
+/**
+ * One MCP server provided by an installed plugin package.
+ *
+ * `command` is always "node" and `args` the script's realpath: some packages
+ * (track@0.2.0) have an entrypoint guard that breaks when the script is run
+ * through the npm-global bin symlink, so the bare bin name must never be
+ * registered — see plugin.ts.
+ */
+type PluginMcp = {
+    name: string;
+    command: string;
+    args: string[];
+    /**
+     * Bin script path relative to the package dir (e.g. "dist/mcp.js") — used by
+     * `remote plugin sync` to recompute the realpath inside remote Pods, where
+     * the npm global root differs from the local one.
+     */
+    scriptRel?: string;
+};
+/**
+ * How a plugin is installed in a session Pod. Default (omitted) = `npm`
+ * (`npm i -g <pkg>@<version>`). `curl` pipes an installer script
+ * (`curl -fsSL <spec> | bash`) — e.g. a Go binary's install.sh. `script` runs
+ * an arbitrary shell line (from the user's own config). Lets non-npm tools be
+ * propagated the same way.
+ */
+type PluginInstall = {
+    method: "npm" | "curl" | "script";
+    /** curl: the installer URL; script: the shell command. Unused for npm. */
+    spec?: string;
+};
+/** A plugin propagated to sessions (npm pkg, or curl/script installer) + MCP(s). */
+type PluginEntry = {
+    pkg: string;
+    version: string;
+    mcp: PluginMcp[];
+    /** Install method; omitted ⇒ npm (pkg@version). */
+    install?: PluginInstall;
+};
+
+/**
+ * Plugin/MCP DESIRED-STATE manifest + drift diff (remote supervise slice 3) —
+ * ADDITIVE, PURE. No IO, no clock. The watch loop / `plugin sync --check` call
+ * these to RENDER the desired set, HASH it (to gate a sidecar push exactly like
+ * CREDS_HASH_FILE), and DIFF it against what a Pod actually has installed.
+ *
+ * Why a manifest at all: MCP servers + plugin CLIs (track, h2a, harness,
+ * graphify, skills) baked/installed into Pods drift away from the LOCAL
+ * source-of-truth — a Pod restart loses globally-installed plugins, a re-pin
+ * bumps the local version, and nothing today DETECTS the gap (`plugin ls`
+ * prints `REMOTE ?`). The manifest is the canonical "what every Pod SHOULD have"
+ * record; its sha256 is the cheap drift signal (one `kubectl exec cat`), and the
+ * diff is the per-item report.
+ *
+ * BIGGEST REMAINING DRIFT SOURCE (DEFERRED — converge-on-session-start): a
+ * freshly (re)created Pod boots with NO plugins until the next `plugin sync` /
+ * watch pass reconciles it, so its CLI starts WITHOUT track/h2a/etc. Closing
+ * that needs the session-agent / orchestrator to run the sync BEFORE the CLI
+ * launches — a session-agent change that is OUT OF SCOPE this slice. It hooks in
+ * at the session-agent startup path (packages/session-agent, the pane that
+ * launches `<cli>`): before exec'ing the CLI, run the equivalent of
+ * `buildPodSyncScript` for each desired plugin + write this manifest sidecar.
+ * TODO(slice 4): wire converge-on-session-start there; until then the watch-pass
+ * reconcile (compareManifestHash → re-run buildPodSyncScript) is the safety net.
+ *
+ * NOTHING here is a NEW push path: `plugin sync` (no --check) still converges via
+ * the EXISTING buildPodSyncScript, untouched. This module only adds a manifest
+ * artifact + a read-only drift report.
+ */
+
+/** Drift status for one desired item in one Pod. */
+type DriftStatus = "ok" | "version-drift" | "missing" | "mcp-unregistered";
+/** One row of the drift report: a desired item's status in a Pod. */
+type DriftRow = {
+    readonly pod: string;
+    /** "plugin:<pkg>" or "mcp:<name>". */
+    readonly item: string;
+    readonly status: DriftStatus;
+    /** Human detail (e.g. "local@1.2.0 vs pod@1.1.0"); empty for ok. */
+    readonly detail: string;
+};
+
+/**
+ * `remote plugin` — install npm "plugin" packages (a CLI + an MCP server, e.g.
+ * @sentropic/track shipping bins `track` and `track-mcp`) for every agent CLI
+ * (claude, codex, agy), both LOCALLY (npm i -g + MCP registration) and inside
+ * live REMOTE session Pods (`remote plugin sync`: kubectl exec → npm i -g +
+ * per-profile MCP registration).
+ *
+ * agy (Antigravity CLI) has NO `agy mcp` subcommand: MCP servers are declared
+ * in ~/.gemini/config/mcp_config.json, a Claude-style `{"mcpServers": {…}}`
+ * JSON file (the agy changelog 1.0.3 calls this the "migrated" path; the old
+ * ~/.gemini/antigravity/mcp_config.json is legacy). We merge idempotently and
+ * keep a one-shot `.bak.<epoch>` backup the first time we touch a non-empty
+ * file.
+ *
+ * KNOWN PITFALL — broken entrypoint guard through the npm-global symlink:
+ * some packages (track@0.2.0) guard their entry script with a
+ * "was-I-run-directly?" check that compares argv[1] with the module path;
+ * invoked through the npm-global bin SYMLINK the two differ and the guard
+ * never fires (the CLI/MCP silently does nothing). So MCP servers are ALWAYS
+ * registered as `node <realpathSync(script)>` — never the bare bin name.
+ *
+ * Baking plugins into the session image is a separate TODO that belongs in
+ * packages/session-agent/Dockerfile (left untouched here): until then a Pod
+ * restart loses globally-installed plugins and `remote plugin sync` must be
+ * re-run.
+ *
+ * DRIFT (remote supervise slice 3, ADDITIVE): a desired-state manifest
+ * (plugin-manifest.ts) + a sidecar pushed to each Pod (~/.remote-manifest.json /
+ * ~/.remote-manifest.sha256, gated EXACTLY like CREDS_HASH_FILE), a read-only
+ * `plugin sync --check` drift report, and a watch-pass reconcile that re-runs
+ * the EXISTING buildPodSyncScript on a hash mismatch (an extra TRIGGER, not a
+ * new push path). The plain `plugin add`/`plugin sync` push is UNCHANGED.
+ *
+ * TODO(slice 4 — converge-on-session-start, the BIGGEST remaining drift source):
+ * a freshly (re)created Pod boots with NO plugins until the next sync/watch pass,
+ * so its CLI launches WITHOUT track/h2a/etc. Closing that needs the session-agent
+ * startup path (packages/session-agent, the pane that launches `<cli>`) to run
+ * the sync + write the manifest sidecar BEFORE exec'ing the CLI — OUT OF SCOPE
+ * here (do not touch session-agent this slice). The watch-pass reconcile is the
+ * interim safety net.
+ */
+
+type McpRequest = {
+    name: string;
+    bin: string;
+};
+/** Parse one `--mcp <name>=<bin>` spec. */
+declare function parseMcpSpec(spec: string): McpRequest;
+declare function parseMcpSpecs(specs: readonly string[]): McpRequest[];
+/**
+ * Heuristic when no --mcp is given: every bin ending in `-mcp` is an MCP
+ * server named after the bin minus the suffix (track-mcp → track).
+ */
+declare function detectMcpBins(bins: Readonly<Record<string, string>>): McpRequest[];
+/**
+ * Idempotently upsert the `[mcp_servers.<name>]` section in a config.toml
+ * body: an existing section (up to the next `[…]` header) is replaced in
+ * place, otherwise the block is appended. Applying twice is a no-op.
+ */
+declare function upsertCodexMcpServer(toml: string, name: string, command: string, args: readonly string[]): string;
+/** Idempotent `mcpServers.<name>` merge for a ~/.claude.json body. */
+declare function mergeClaudeMcpServers(json: string, name: string, command: string, args: readonly string[]): string;
+/**
+ * Bash script run inside a session Pod (`kubectl exec … bash -lc`) by
+ * `remote plugin sync`: installs the plugin globally, recomputes each MCP
+ * script's realpath against the POD's npm global root (the local realpath is
+ * meaningless there), then registers the MCP server for the Pod's profile.
+ * Every step echoes one line — the CLI prints them as the per-session recap.
+ */
+declare function buildPodSyncScript(plugin: PluginEntry, profile: string): string;
+/**
+ * Production wiring used by the supervise/watch pass: reconcile manifest drift
+ * for ONE session via the configured tunnel. Thin — the decision + the reused
+ * buildPodSyncScript live in `reconcilePodManifest`. No-op (and no error) when
+ * no plugins are configured. Best-effort; never throws into the caller.
+ */
+declare function reconcileSessionPlugins(sessionId: string, profile: string, stderr?: NodeJS.WriteStream): {
+    reconciled: boolean;
+};
+/**
+ * `remote plugin add <npmPkg> [--mcp name=bin]...` — npm i -g, register the
+ * MCP server(s) with claude + codex + agy, persist in the config.
+ */
+declare function pluginAdd(npmSpec: string, mcpSpecs: readonly string[], stderr?: NodeJS.WriteStream): PluginEntry;
+/**
+ * `remote plugin add <name> --curl <url>` / `--install "<shell>"` — register a
+ * NON-npm plugin (a tool installed by piping an https script, or an arbitrary
+ * shell command). No local install is run (unlike the npm path, which must read
+ * the package to detect MCP bins): the installer runs in each Pod on
+ * `remote plugin sync`. Validates the command up front so a bad URL fails now.
+ */
+declare function pluginAddInstaller(name: string, install: PluginInstall, stderr?: NodeJS.WriteStream): PluginEntry;
+/**
+ * `remote plugin ls` — pkg / version / MCPs / where (local ok/missing, remote).
+ *
+ * The REMOTE column is now REAL per-Pod drift status (slice 3), not the old
+ * guess-`?`: when a `url` is passed (the command is connected to the control-
+ * plane) we probe each live Pod via the same drift mechanism `--check` uses and
+ * summarize each plugin's worst per-Pod status across all Pods
+ * (ok / version-drift / missing). Without a url (offline) we still print `?`
+ * with the documented hint — the `?` only remains when we genuinely can't reach
+ * the cluster, never as guesswork when we can.
+ */
+declare function pluginLs(stdout?: NodeJS.WriteStream, url?: string): Promise<void>;
+/**
+ * `remote plugin sync` — for every live remote session: kubectl exec into the
+ * Pod, `npm i -g <pkg>@<version>`, then register the MCP servers for the
+ * Pod's profile. Prints a per-session recap. Needs the configured tunnel.
+ */
+declare function pluginSync(url: string, stderr?: NodeJS.WriteStream): Promise<void>;
+/**
+ * `remote plugin sync --check` — a READ-ONLY drift report (converges NOTHING).
+ * For each live Pod it probes the actual installed state (npm ls -g --json for
+ * the desired pkgs + the registered MCP server names from the config files the
+ * existing sync writes) via the argv-safe pod exec, then the pure
+ * `diffManifest` rows it: ok / version-drift / missing / mcp-unregistered.
+ * Prints a table and EXITS 1 when ANY row is drift (via process.exitCode). This
+ * REPLACES the `plugin ls` `REMOTE ?` guesswork with REAL per-Pod status. Pure
+ * decisions live in plugin-manifest.ts; this is the thin probe + printer.
+ */
+declare function pluginSyncCheck(url: string, stdout?: NodeJS.WriteStream, stderr?: NodeJS.WriteStream): Promise<DriftRow[]>;
+
+declare const packageName = "@sentropic/remote-cli";
+
+/** Validate `--watch <minutes>`: a whole number of minutes >= 1. */
+declare function parseWatchMinutes(raw: string): number;
+/**
+ * Soft-refresh EVERY live remote session (profile carried by each session).
+ * Per-session errors don't stop the pass; ends with a recap (ok / unchanged /
+ * failed) and returns the failure count. `hashes` carries the previous pass's
+ * bundle hashes (sessionId -> sha256) so unchanged creds are a no-op WITHOUT
+ * respawning the Pod CLI.
+ */
+declare function softRefreshAllSessions(url: string, opts: {
+    authRefresh?: boolean;
+}, hashes: Map<string, string>): Promise<{
+    failed: number;
+}>;
+/**
+ * Foreground refresh loop for `--watch <minutes>`: pass, sleep, repeat. NO
+ * daemonization, no pid file — the user runs it in a dedicated tmux window.
+ * Each pass is timestamped on stderr; SIGINT (Ctrl-C) stops it cleanly with a
+ * message and exit 0. Pass failures are logged and the loop keeps going.
+ */
+declare function watchRefreshLoop(minutes: number, pass: () => Promise<{
+    failed: number;
+}>, signals?: {
+    on(event: "SIGINT", listener: () => void): unknown;
+    removeListener(event: "SIGINT", listener: () => void): unknown;
+}): Promise<number>;
+/**
+ * P4 — the conductor's FOREGROUND watch loop (NO daemon, NO pid file — run it in
+ * a dedicated tmux window, exactly like `watchRefreshLoop` / `h2a bridge
+ * --watch`). Each pass is timestamped; SIGINT (Ctrl-C) stops it cleanly with a
+ * message and exit 0. A pass failure is logged and the loop keeps going. The
+ * `pass` is the conductor pass (reconcile + start `pending` jobs under the cap);
+ * `signals` is injectable so tests never emit a real SIGINT.
+ */
+declare function conductLoop(minutes: number, pass: () => Promise<{
+    started: number;
+    finished: number;
+}>, signals?: {
+    on(event: "SIGINT", listener: () => void): unknown;
+    removeListener(event: "SIGINT", listener: () => void): unknown;
+}): Promise<number>;
+type StartJobResult = {
+    started: true;
+    target: "local" | "remote";
+    detail: string;
+} | {
+    started: false;
+    error: string;
+};
+/**
+ * Launch a job that is enrolled in the registry (typically `pending`): spawn the
+ * agent (local detached tmux, or a Pod), advance the registry entry to
+ * `running`, mirror it under track (best-effort), and propagate the spawn-depth
+ * budget to the child via `REMOTE_DELEGATE_DEPTH`. The launch params are read
+ * from the entry's queued-launch fields (tool/task/headless/remoteTarget/
+ * originCwd/explicitCwd/depthBudget/trackWp), set at `delegate` time.
+ *
+ * Never throws: any spawn/registry error is returned as `{started:false}` so the
+ * conductor loop keeps going. For remote, the per-job workspace is created here
+ * (so a queued remote job doesn't hold a workspace while waiting).
+ */
+declare function startJob(job: RegistryEntry): Promise<StartJobResult>;
+/**
+ * Reliability slice 1 — RESUME a throttled HEADLESS LOCAL job. Relaunch the SAME
+ * job in the SAME `runCwd` it already ran in (its recorded `cwd` — NOT a fresh
+ * worktree, so it continues the prior conversation in place) with the tool's
+ * CONTINUE flag (`claude -p --continue` / `codex exec resume --last`, via the
+ * safe argv `buildThrottleResumeArgs` — never `bash -lc` concat), redirecting to
+ * the SAME result.json/output.log, then transition `throttled → running`. The
+ * throttle bookkeeping is PRESERVED so a re-throttle bumps `attempts` (the cap is
+ * enforced in reconcile). Never throws — a spawn error is returned as
+ * `{started:false}` so the conductor keeps going.
+ *
+ * SCOPE: headless local only. Interactive resume (send-keys) and remote resume
+ * (control-plane) are phase 2 — see the TODOs at the call site.
+ */
+declare function resumeThrottledJob(job: RegistryEntry): StartJobResult;
+declare function main(argv: ReadonlyArray<string>): Promise<number>;
+
+export { type AttachOptions, type AttachResult, type AuthBundle, AuthBundleMissingError, type AuthDiagnosticsResult, type AuthDiagnosticsStatus, AuthRefreshError, type MigrateBackOptions, type MigrateBackResult, type MigrateForwardOptions, type MigrateForwardResult, type ProfileConfig, type RunOptions, type RunResult, type SmokeRemoteProfileOptions, type SmokeRemoteProfileResult, type StartJobResult, assertRequiredAuthBundle, attach, buildPodSyncScript, coerceCliProfileName, collectProfileAuth, conductLoop, createRemoteSession, detectMcpBins, ensureProfileAuthFresh, getRemoteSession, inspectProfileAuth, isCliProfile, listRemoteSessions, main, mergeClaudeMcpServers, migrateBack, migrateForward, packageName, parseMcpSpec, parseMcpSpecs, parseWatchMinutes, pluginAdd, pluginAddInstaller, pluginLs, pluginSync, pluginSyncCheck, reconcileSessionPlugins, refreshRemoteSession, renameRemoteSession, resolveProfile, resumeThrottledJob, run, smokeRemoteProfile, softRefreshAllSessions, startJob, stopRemoteSession, upsertCodexMcpServer, watchRefreshLoop, withResume };