@sentropic/h2a-runtime 0.81.0

package/dist/readiness.js

@@ -0,0 +1,169 @@
+/**
+ * readiness.ts — Phase A
+ *
+ * Best-effort, network-free readiness check before a session migration.
+ * All checks use spawnSync only — no network calls, never throws.
+ *
+ * Exported: checkReadiness(opts?) → ReadinessResult
+ */
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { localConvStat } from "./convsync.js";
+// ---------------------------------------------------------------------------
+// Thresholds for lazy mode
+// ---------------------------------------------------------------------------
+/** Max files in working set before switching to "lazy" mode. */
+const LAZY_FILES_THRESHOLD = 200;
+/** Max total bytes (50 MB) in working set before switching to "lazy" mode. */
+const LAZY_BYTES_THRESHOLD = 50 * 1024 * 1024;
+/** Transfer rate estimate: 10 MB/s */
+const TRANSFER_RATE_BYTES_PER_SEC = 10_000_000;
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Check whether the local workspace is ready for a session migration.
+ *
+ * All checks are best-effort and synchronous (no network, no throws).
+ * Returns a structured ReadinessResult.
+ */
+export function checkReadiness(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const profile = opts.profile;
+    const home = opts.home ?? homedir();
+    const spawn = opts.spawnImpl ?? spawnSync;
+    const blockers = [];
+    const warnings = [];
+    let mode = "full";
+    // ------------------------------------------------------------------
+    // auth_ok — `remote auth status` rc=0
+    // ------------------------------------------------------------------
+    try {
+        const authResult = spawn("remote", ["auth", "status"], {
+            cwd,
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        if (authResult.status !== 0) {
+            blockers.push("auth: CLI not authenticated");
+        }
+    }
+    catch {
+        blockers.push("auth: CLI not authenticated");
+    }
+    // ------------------------------------------------------------------
+    // repo_bootstrapped — `git rev-parse HEAD` rc=0
+    // ------------------------------------------------------------------
+    let gitOk = false;
+    try {
+        const gitResult = spawn("git", ["rev-parse", "HEAD"], {
+            cwd,
+            encoding: "utf8",
+            timeout: 5_000,
+        });
+        gitOk = gitResult.status === 0;
+        if (!gitOk) {
+            blockers.push("repo: not a git repository");
+        }
+    }
+    catch {
+        blockers.push("repo: not a git repository");
+    }
+    // ------------------------------------------------------------------
+    // plugins_parity_ok — non-blocking warning
+    // Not all profiles have a plugin manifest; absence is not a blocker.
+    // ------------------------------------------------------------------
+    // ------------------------------------------------------------------
+    // conv_resolvable — non-blocking warning
+    // Claude-profile only: verify a conversation exists for this cwd.
+    // Other profiles (codex/agy) don't use path-keyed conversations.
+    // ------------------------------------------------------------------
+    if (profile !== undefined &&
+        (profile === "claude" || profile === "claude-code")) {
+        try {
+            const conv = localConvStat(cwd, home);
+            if (!conv) {
+                warnings.push("conv: no local conversation found for this directory — " +
+                    "migrate will proceed but no active context will be transferred");
+            }
+        }
+        catch {
+            // best-effort: skip on any error
+        }
+    }
+    // ------------------------------------------------------------------
+    // deps_rebuilt — no-op in local mode
+    // ------------------------------------------------------------------
+    // ------------------------------------------------------------------
+    // hot_set_synced — in "full" mode, check working set size
+    // Only meaningful when we have a git repo
+    // ------------------------------------------------------------------
+    let pendingFiles = 0;
+    let pendingBytes = 0;
+    if (gitOk) {
+        try {
+            // Modified/staged files relative to HEAD
+            const diffResult = spawn("git", ["diff", "--name-only", "HEAD", "--"], {
+                cwd,
+                encoding: "utf8",
+                timeout: 15_000,
+            });
+            // Untracked files (not in .gitignore)
+            const untrackedResult = spawn("git", ["ls-files", "--others", "--exclude-standard"], {
+                cwd,
+                encoding: "utf8",
+                timeout: 15_000,
+            });
+            const diffLines = diffResult.status === 0 && diffResult.stdout
+                ? diffResult.stdout
+                    .split("\n")
+                    .map((l) => l.trim())
+                    .filter(Boolean)
+                : [];
+            const untrackedLines = untrackedResult.status === 0 && untrackedResult.stdout
+                ? untrackedResult.stdout
+                    .split("\n")
+                    .map((l) => l.trim())
+                    .filter(Boolean)
+                : [];
+            const allPendingFiles = [...new Set([...diffLines, ...untrackedLines])];
+            pendingFiles = allPendingFiles.length;
+            // Estimate bytes for pending files
+            for (const file of allPendingFiles) {
+                try {
+                    const filePath = join(cwd, file);
+                    if (existsSync(filePath)) {
+                        pendingBytes += statSync(filePath).size;
+                    }
+                }
+                catch {
+                    // best-effort: skip files we can't stat
+                }
+            }
+            // Switch to lazy if working set is too large
+            if (pendingFiles >= LAZY_FILES_THRESHOLD ||
+                pendingBytes >= LAZY_BYTES_THRESHOLD) {
+                mode = "lazy";
+            }
+        }
+        catch {
+            // best-effort: if git commands fail, leave pendingFiles/pendingBytes at 0
+        }
+    }
+    const est_seconds = Math.ceil(pendingBytes / TRANSFER_RATE_BYTES_PER_SEC);
+    const ready = blockers.length === 0;
+    return {
+        ready,
+        mode,
+        blockers,
+        warnings,
+        pending: {
+            files: pendingFiles,
+            bytes: pendingBytes,
+            est_seconds,
+        },
+    };
+}
+//# sourceMappingURL=readiness.js.map

package/dist/readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -0,0 +1,258 @@
+/**
+ * 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).
+ */
+export type RegistryTool = "claude" | "codex" | "agy";
+export type RegistryKind = "local-tmux" | "local" | "remote";
+export 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).
+ */
+export type RegistryRole = "job";
+export 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).
+ */
+export 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;
+};
+export 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;
+    /**
+     * Pinned llm-mesh gateway choice, captured at launch from an EXPLICIT
+     * --gw/--no-gw. Re-emitted verbatim by `remote restore` so each instance
+     * keeps its own gateway posture instead of falling back to the global
+     * default. Absent = launched in "auto" mode (follows the default).
+     */
+    gatewayMode?: "gateway" | "direct";
+};
+export type EnrollInput = {
+    id: string;
+    tool: RegistryTool;
+    kind: RegistryKind;
+    cwd: string;
+    source: RegistrySource;
+    label?: string;
+    convId?: string;
+    remoteId?: string;
+    tmuxSession?: string;
+    pid?: number;
+    role?: RegistryRole;
+    jobState?: JobState;
+    parent?: string;
+    task?: string;
+    callbackTo?: string;
+    remoteTarget?: string;
+    headless?: boolean;
+    originCwd?: string;
+    explicitCwd?: string;
+    depthBudget?: number;
+    trackWp?: string;
+    throttle?: ThrottleInfo;
+    model?: string;
+    effort?: string;
+    accountId?: string;
+    gatewayMode?: "gateway" | "direct";
+};
+/** Injectable liveness probes (tests stay deterministic, no tmux/pid needed). */
+export type LivenessOpts = {
+    tmuxHasSession?: (name: string) => boolean;
+    pidAlive?: (pid: number) => boolean;
+    /** System boot time (ms epoch). A `kind:"local"` entry last seen before this
+     * is dead — its process died in the reboot, so its PID must not be trusted
+     * (PID reuse would falsely resurrect it). Injectable for tests. */
+    bootTimeMs?: number;
+    /** cmdline of a pid (to detect PID reuse after a crash). Injectable for tests. */
+    processCmdline?: (pid: number) => string | undefined;
+};
+type RegistryOpts = LivenessOpts & {
+    path?: string;
+};
+export declare function resolveRegistryPath(): string;
+export declare function loadRegistry(path?: string): RegistryEntry[];
+/**
+ * Run `fn` under the registry lock: load the current entries, let `fn` mutate
+ * them (and compute a return value), then persist atomically — all inside ONE
+ * critical section, so concurrent processes serialize and no enroll/advance is
+ * lost. `fn` returns `{ entries, result, save? }`: `entries` is what to save
+ * (return the same array you mutated), `result` is passed back to the caller, and
+ * `save:false` skips the write entirely (a read-only no-op must not rewrite — nor
+ * create — the file). If the lock can't be taken (a crashed holder, contention
+ * storm), we proceed WITHOUT it rather than block a hook — best-effort,
+ * last-writer-wins as before. Exported for tests.
+ */
+export declare function withRegistryLock<T>(path: string, fn: (entries: RegistryEntry[]) => {
+    entries: RegistryEntry[];
+    result: T;
+    save?: boolean;
+}): T;
+/**
+ * Upsert by id. A re-enroll refreshes lastSeenAt, merges the new fields over
+ * the stored ones, and REVIVES an ended entry (endedAt is dropped) — e.g. a
+ * claude SessionStart on a resumed conversation.
+ */
+export declare function enroll(input: EnrollInput, path?: string): RegistryEntry;
+/**
+ * ATOMIC "is there a free slot? → enroll-as-running" (S3 fix). The cap check and
+ * the running-enroll happen in ONE locked critical section, so two concurrent
+ * `delegate`s can never both see the same free slot and overshoot the cap.
+ * `running` counts CURRENT `running` jobs (`role:"job"`); when `running < cap`
+ * the `input` is upserted with `jobState:"running"` and the returned entry is
+ * non-undefined. When the cap is full, NOTHING is written and `undefined` is
+ * returned (the caller enqueues a `pending` entry instead). Exported for tests.
+ */
+export declare function tryClaimSlot(input: EnrollInput, cap: number, path?: string): RegistryEntry | undefined;
+export declare function canTransitionJob(from: JobState, to: JobState): boolean;
+/**
+ * Does a job in `state` OCCUPY a concurrency slot? `running` does, and so does
+ * `throttled` — a throttled job is mid-flight (it KEEPS its slot rather than
+ * letting the conductor admit a replacement that would immediately throttle on
+ * the same account-wide limit). `pending`/`done`/`failed` do not. Pure, exported
+ * for the cap/admission logic in delegate.ts and its tests.
+ */
+export declare function occupiesSlot(state: JobState): boolean;
+/**
+ * Move a job to `to`, persisting the new state (and stamping endedAt for the
+ * terminal states). Returns the updated entry, or undefined when the id is
+ * unknown / not a job / the transition is illegal. Reuses the atomic write.
+ */
+export declare function advanceJob(id: string, to: JobState, path?: string): RegistryEntry | undefined;
+/** Live job entries (role "job"), liveness reconciled like any other entry. */
+export declare function listJobs(opts?: RegistryOpts): RegistryEntry[];
+/** Refresh lastSeenAt. Returns false when the id is unknown. */
+export declare function touchEntry(id: string, path?: string): boolean;
+/** Record the session's end. Returns false when the id is unknown. */
+export declare function markEnded(id: string, path?: string): boolean;
+/**
+ * Liveness:
+ *  - local-tmux -> the tmux session exists,
+ *  - local      -> pid alive (when recorded) AND not endedAt; without a pid
+ *                  (hook-enrolled: the hook's parent pid is a throwaway shell)
+ *                  we trust SessionEnd + prune,
+ *  - remote     -> always "live" here; the CALLER reconciles against
+ *                  listRemoteSessions (the registry cannot probe the cluster).
+ */
+export declare function isLive(e: RegistryEntry, opts?: LivenessOpts): boolean;
+/** Entries considered live right now (see isLive for the per-kind rules). */
+export declare function listLive(opts?: RegistryOpts): RegistryEntry[];
+/**
+ * Drop DEAD entries whose last activity (endedAt, else lastSeenAt) is older
+ * than maxAgeHours. Live entries always stay; recently-dead ones stay too so
+ * `restore` can still resume them after a reboot via the scan fallback.
+ * Returns the number of removed entries.
+ */
+export declare function prune(maxAgeHours: number, opts?: RegistryOpts): number;
+/** Map a CLI profile name to a registry tool (undefined for shell/opencode/…). */
+export declare function coerceRegistryTool(profile: string): RegistryTool | undefined;
+/**
+ * Auto-enrolment after `remote run` started a local tmux session. Best-effort
+ * plumbing: never throws (a registry hiccup must not break the run).
+ */
+export declare function enrollFromRun(args: {
+    profile: string;
+    slug: string;
+    tmuxSession: string;
+    cwd: string;
+    convId?: string;
+    gatewayMode?: "gateway" | "direct";
+}): void;
+export type LocalLsRow = {
+    slug: string;
+    profile: string;
+    state: "attached" | "detached" | "live";
+    path: string;
+    /** "registry" = enrolled (reliable cwd/convId); "guess" = tmux-only. */
+    badge: "registry" | "guess";
+    /** custom display name set via `remote rename`, shown in PROJECT column */
+    displayName?: string;
+};
+/**
+ * LOCAL rows for `remote ls`: live tmux sessions joined with the registry
+ * ([registry] vs [guess] badge), plus live registry-only sessions (e.g. a
+ * hook-enrolled claude running in a plain terminal). Dead registry entries are
+ * pruned on the way (layout maxAgeHours).
+ */
+export declare function listLocalForLs(opts?: RegistryOpts): LocalLsRow[];
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}