@phnx-labs/agents-cli 1.20.34 → 1.20.36

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

@@ -0,0 +1,53 @@
+/**
+ * Reconcile a local host-task record against the remote run's ground truth.
+ *
+ * A detached `--host` run outlives the local follower: it keeps running and
+ * writes its exit code to `<id>.exit` on the host even if the laptop sleeps or
+ * the SSH connection drops mid-follow. When that happens the local record is
+ * left at `status:'running'` forever, because the only path that finalizes it
+ * (dispatch's post-follow `updateTask`) never runs. This module re-reads the
+ * remote `.exit` on demand — from `agents hosts ps` / `logs` — and heals the
+ * record. We only ever CONFIRM completion; an unreachable host or an absent
+ * `.exit` leaves the record `running` (we never guess failure).
+ */
+import { type SshExecResult } from '../ssh-exec.js';
+import { type HostTask } from './tasks.js';
+export type RemoteExitState = {
+    state: 'running';
+} | {
+    state: 'done';
+    code: number;
+} | {
+    state: 'unreachable';
+};
+/**
+ * Classify a `cat <remoteExit>` result into a remote run state. Pure: all the
+ * bug-prone branching (ssh-failure vs absent vs empty vs coded) lives here so it
+ * can be unit-tested without a live host. ssh's own connection failure surfaces
+ * as code 255, a spawn error/timeout as `code === null`; neither is the remote
+ * command's exit and both mean "unreachable". An empty read is "still running"
+ * (the `.exit` is written only after the run ends, so absent `cat` → exit 1 →
+ * empty stdout, and a truncate-then-write mid-race is a sub-ms empty window).
+ */
+export declare function classifyExit(res: Pick<SshExecResult, 'code' | 'stdout' | 'timedOut'>): RemoteExitState;
+/**
+ * Read a task's remote `.exit` over ssh and classify it. `remoteExit` is a
+ * $HOME-prefixed path with a safe (hex) basename — intentionally unquoted so the
+ * remote shell expands $HOME (same contract as progress.ts's fetch).
+ */
+export declare function readRemoteExit(target: string, remoteExit: string, timeoutMs?: number): RemoteExitState;
+/**
+ * Heal one record. Terminal records are immutable (and never re-probed); a
+ * `running` record is resolved to completed/failed only when the remote `.exit`
+ * holds a code. Returns the (possibly updated) task.
+ */
+export declare function reconcileTask(task: HostTask): HostTask;
+/**
+ * Heal a list of records for a listing (`agents hosts ps`). Only `running` tasks
+ * are probed; each host is reachability-checked ONCE (deduped by target) so a
+ * down host costs a single short timeout instead of one per task, and its tasks
+ * are left `running` rather than falsely failed. Sequential by design — with the
+ * shared ssh control socket the live-host reads are sub-100ms, and a parallel
+ * (async) ssh path is deliberately out of scope.
+ */
+export declare function reconcileRunningTasks(tasks: HostTask[]): HostTask[];

package/dist/lib/hosts/reconcile.js

@@ -0,0 +1,81 @@
+/**
+ * Reconcile a local host-task record against the remote run's ground truth.
+ *
+ * A detached `--host` run outlives the local follower: it keeps running and
+ * writes its exit code to `<id>.exit` on the host even if the laptop sleeps or
+ * the SSH connection drops mid-follow. When that happens the local record is
+ * left at `status:'running'` forever, because the only path that finalizes it
+ * (dispatch's post-follow `updateTask`) never runs. This module re-reads the
+ * remote `.exit` on demand — from `agents hosts ps` / `logs` — and heals the
+ * record. We only ever CONFIRM completion; an unreachable host or an absent
+ * `.exit` leaves the record `running` (we never guess failure).
+ */
+import { sshExec, sshReachable } from '../ssh-exec.js';
+import { updateTask, terminalPatch } from './tasks.js';
+/**
+ * Classify a `cat <remoteExit>` result into a remote run state. Pure: all the
+ * bug-prone branching (ssh-failure vs absent vs empty vs coded) lives here so it
+ * can be unit-tested without a live host. ssh's own connection failure surfaces
+ * as code 255, a spawn error/timeout as `code === null`; neither is the remote
+ * command's exit and both mean "unreachable". An empty read is "still running"
+ * (the `.exit` is written only after the run ends, so absent `cat` → exit 1 →
+ * empty stdout, and a truncate-then-write mid-race is a sub-ms empty window).
+ */
+export function classifyExit(res) {
+    if (res.timedOut || res.code === null || res.code === 255)
+        return { state: 'unreachable' };
+    const out = res.stdout.trim();
+    if (out === '')
+        return { state: 'running' };
+    const code = parseInt(out, 10);
+    return { state: 'done', code: Number.isFinite(code) ? code : 0 };
+}
+/**
+ * Read a task's remote `.exit` over ssh and classify it. `remoteExit` is a
+ * $HOME-prefixed path with a safe (hex) basename — intentionally unquoted so the
+ * remote shell expands $HOME (same contract as progress.ts's fetch).
+ */
+export function readRemoteExit(target, remoteExit, timeoutMs = 6000) {
+    return classifyExit(sshExec(target, `cat ${remoteExit} 2>/dev/null`, { timeoutMs, multiplex: true }));
+}
+/**
+ * Heal one record. Terminal records are immutable (and never re-probed); a
+ * `running` record is resolved to completed/failed only when the remote `.exit`
+ * holds a code. Returns the (possibly updated) task.
+ */
+export function reconcileTask(task) {
+    if (task.status !== 'running')
+        return task;
+    const st = readRemoteExit(task.target, task.remoteExit);
+    if (st.state !== 'done')
+        return task;
+    return updateTask(task.id, terminalPatch(st.code)) ?? task;
+}
+/**
+ * Heal a list of records for a listing (`agents hosts ps`). Only `running` tasks
+ * are probed; each host is reachability-checked ONCE (deduped by target) so a
+ * down host costs a single short timeout instead of one per task, and its tasks
+ * are left `running` rather than falsely failed. Sequential by design — with the
+ * shared ssh control socket the live-host reads are sub-100ms, and a parallel
+ * (async) ssh path is deliberately out of scope.
+ */
+export function reconcileRunningTasks(tasks) {
+    const running = tasks.filter((t) => t.status === 'running');
+    if (running.length === 0)
+        return tasks;
+    const reachable = new Map();
+    const patched = new Map();
+    for (const t of running) {
+        if (!reachable.has(t.target))
+            reachable.set(t.target, sshReachable(t.target, 6000));
+        if (!reachable.get(t.target))
+            continue; // host down → leave running
+        const st = readRemoteExit(t.target, t.remoteExit);
+        if (st.state === 'done') {
+            const updated = updateTask(t.id, terminalPatch(st.code));
+            if (updated)
+                patched.set(t.id, updated);
+        }
+    }
+    return tasks.map((t) => patched.get(t.id) ?? t);
+}

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

@@ -11,8 +11,25 @@ export declare function getAllProviders(): HostProvider[];
 /** Every host across all registered providers, deduped by name (first wins). */
 export declare function listAllHosts(): Promise<Host[]>;
 /**
- * Resolve a host name to a single host across providers, or null if unknown.
- * First provider that owns the name wins (only `local` in v1).
+ * Thrown when a device resolves but can't be used as an offload target because
+ * it authenticates with a password. The offload path runs over `sshExec`, whose
+ * `SSH_OPTS` force `BatchMode=yes` (no password prompts), so only key / ssh-config
+ * auth can carry a `--host` run. Named so the top-level catch prints the message
+ * cleanly instead of a stack trace.
+ */
+export declare class DeviceOffloadUnsupportedError extends Error {
+    constructor(name: string);
+}
+/**
+ * Resolve a host name to a single host, or null if unknown. Resolution order:
+ *   1. host providers — the `agents hosts` registry (agents.yaml overlay + ssh-config)
+ *   2. the devices registry (`agents devices`) — a machine registered once with
+ *      `agents devices sync` is reachable by `--host`/`--device` with no second enroll
+ *   3. an ad-hoc `user@host` (must contain `@`, validated) — nothing to register
+ *
+ * A bare unknown name returns null so capability-tag routing (`resolveHostByCap`)
+ * stays reachable: `--host gpu` must fall through to a cap lookup, not be misread
+ * as an ad-hoc target.
  */
 export declare function resolveHost(name: string): Promise<Host | null>;
 /**

package/dist/lib/hosts/registry.js

@@ -6,6 +6,8 @@
  * `crabbox` later is a one-line `providers.set(...)` with no caller changes.
  */
 import { LocalHostProvider } from './providers/local.js';
+import { getDevice } from '../devices/registry.js';
+import { assertValidSshTarget } from '../ssh-exec.js';
 const providers = new Map();
 function initProviders() {
     if (providers.size > 0)
@@ -39,8 +41,54 @@ export async function listAllHosts() {
     return out;
 }
 /**
- * Resolve a host name to a single host across providers, or null if unknown.
- * First provider that owns the name wins (only `local` in v1).
+ * Thrown when a device resolves but can't be used as an offload target because
+ * it authenticates with a password. The offload path runs over `sshExec`, whose
+ * `SSH_OPTS` force `BatchMode=yes` (no password prompts), so only key / ssh-config
+ * auth can carry a `--host` run. Named so the top-level catch prints the message
+ * cleanly instead of a stack trace.
+ */
+export class DeviceOffloadUnsupportedError extends Error {
+    constructor(name) {
+        super(`Device "${name}" uses password auth, which --host offload can't use yet ` +
+            `(runs go over ssh with BatchMode=yes). Switch it to key auth with ` +
+            `\`agents devices set ${name} --auth key\`, or enroll it as a host with ` +
+            `\`agents hosts add ${name}\`.`);
+        this.name = 'DeviceOffloadUnsupportedError';
+    }
+}
+/**
+ * Bridge a registered device into a `Host` so `--host <device>` just works.
+ * A device's dnsName (preferred) or ip becomes the ssh address; `source: 'inline'`
+ * makes `sshTargetFor` emit `user@address`.
+ */
+function deviceToHost(device) {
+    if (device.auth.method === 'password') {
+        throw new DeviceOffloadUnsupportedError(device.name);
+    }
+    const address = device.address.dnsName ?? device.address.ip;
+    if (!address) {
+        throw new Error(`Device "${device.name}" has no address (Tailscale DNS name or IP) to reach it by.`);
+    }
+    return {
+        name: device.name,
+        provider: 'local',
+        source: 'inline',
+        address,
+        user: device.user,
+        ...(device.platform !== 'unknown' ? { os: device.platform } : {}),
+        enrolled: true,
+    };
+}
+/**
+ * Resolve a host name to a single host, or null if unknown. Resolution order:
+ *   1. host providers — the `agents hosts` registry (agents.yaml overlay + ssh-config)
+ *   2. the devices registry (`agents devices`) — a machine registered once with
+ *      `agents devices sync` is reachable by `--host`/`--device` with no second enroll
+ *   3. an ad-hoc `user@host` (must contain `@`, validated) — nothing to register
+ *
+ * A bare unknown name returns null so capability-tag routing (`resolveHostByCap`)
+ * stays reachable: `--host gpu` must fall through to a cap lookup, not be misread
+ * as an ad-hoc target.
  */
 export async function resolveHost(name) {
     for (const provider of getAllProviders()) {
@@ -48,6 +96,14 @@ export async function resolveHost(name) {
         if (host)
             return host;
     }
+    const device = await getDevice(name);
+    if (device)
+        return deviceToHost(device);
+    if (name.includes('@')) {
+        assertValidSshTarget(name);
+        const at = name.indexOf('@');
+        return { name, provider: 'local', source: 'inline', user: name.slice(0, at), address: name.slice(at + 1) };
+    }
     return null;
 }
 /**

package/dist/lib/hosts/remote-cmd.d.ts

@@ -32,5 +32,66 @@ export declare const HOST_ROUTING_SPECS: StripSpec[];
  * are quoted for the inner login shell, then the whole `agents …` invocation is
  * quoted again so it survives `bash -lc <...>` — `bash -lc` so the remote login
  * PATH resolves `agents`. An optional `cd` runs first for `--remote-cwd`.
+ *
+ * `os` selects the remote shell dialect: a Windows target gets a PowerShell
+ * invocation instead (ssh lands in cmd.exe/PowerShell there, where `bash -lc`
+ * does not exist). Anything else — including an unknown/absent OS — keeps the
+ * POSIX form, so linux/macos are byte-for-byte unchanged.
+ */
+export declare function buildRemoteAgentsInvocation(forwardedArgs: string[], remoteCwd?: string, os?: string): string;
+/** The two remote shell dialects we build commands for. */
+export type RemoteShell = 'posix' | 'powershell';
+/**
+ * Pick the remote shell dialect from a recorded OS/platform string. A Windows
+ * host (device-registry `platform: 'windows'`, or an enrolled `HostEntry.os`
+ * that reads `windows`/`Windows`/`win32`/…) speaks PowerShell; everything else,
+ * including `undefined`/unknown, defaults to POSIX so linux/macos never regress.
+ */
+export declare function remoteShellFor(os: string | undefined): RemoteShell;
+/**
+ * PowerShell single-quoted literal: wrap in `'…'` and double any embedded `'`.
+ * Single-quoted PS strings are fully literal (no `$var`, no backtick escapes),
+ * so this neutralises every metacharacter the same way POSIX `shellQuote` does.
+ */
+export declare function powershellQuote(s: string): string;
+/**
+ * Encode a PowerShell script for `powershell -EncodedCommand`: base64 of its
+ * UTF-16LE bytes. The payload is a bare base64 word (no spaces or shell
+ * metacharacters), so it survives being handed to ssh as a single argument and
+ * re-parsed by the remote's cmd.exe/PowerShell with zero quoting hazards —
+ * the robust way to ship a complex command to a Windows box over SSH.
+ */
+export declare function encodePowershell(script: string): string;
+/** Inverse of {@link encodePowershell} — decode an `-EncodedCommand` payload
+ * back to its script. Used by tests to assert on the built command. */
+export declare function decodePowershell(encoded: string): string;
+/** A single `agents …` invocation to run on a Windows remote. */
+export interface WindowsAgentsCommand {
+    /** `agents` argv (command name NOT included; `agents` is prepended). */
+    args: string[];
+    /** Env vars scoped to this invocation (POSIX `VAR=val` ↔ PS `$env:VAR=…`). */
+    env?: Record<string, string>;
+    /** Directory to enter before running (`--remote-cwd`). */
+    cwd?: string;
+    /**
+     * Append `exit $LASTEXITCODE` so a native `agents` exit code propagates out
+     * through `powershell.exe` (which otherwise exits 0 regardless). Default true;
+     * pass false for probes whose reachability keys off a sentinel, not the code.
+     */
+    propagateExit?: boolean;
+}
+/**
+ * The PowerShell script (pre-encoding) that {@link buildWindowsAgentsCommand}
+ * runs. Exposed so tests can decode the `-EncodedCommand` payload and compare
+ * against the exact script, without needing PowerShell on the test host.
+ *
+ * `& agents …` invokes the CLI from the machine PATH (Windows has no login
+ * shell, so there is no `bash -lc` equivalent — the shim is simply on PATH).
+ */
+export declare function windowsAgentsScript(cmd: WindowsAgentsCommand): string;
+/**
+ * Build the `ssh <target> <cmd>` string for one `agents …` invocation on a
+ * Windows remote: a `powershell -NoProfile -EncodedCommand <base64>` call. The
+ * Windows counterpart of `bash -lc '<...>'`, shared by every `--host` site.
  */
-export declare function buildRemoteAgentsInvocation(forwardedArgs: string[], remoteCwd?: string): string;
+export declare function buildWindowsAgentsCommand(cmd: WindowsAgentsCommand): string;

package/dist/lib/hosts/remote-cmd.js

@@ -48,9 +48,78 @@ export const HOST_ROUTING_SPECS = [
  * are quoted for the inner login shell, then the whole `agents …` invocation is
  * quoted again so it survives `bash -lc <...>` — `bash -lc` so the remote login
  * PATH resolves `agents`. An optional `cd` runs first for `--remote-cwd`.
+ *
+ * `os` selects the remote shell dialect: a Windows target gets a PowerShell
+ * invocation instead (ssh lands in cmd.exe/PowerShell there, where `bash -lc`
+ * does not exist). Anything else — including an unknown/absent OS — keeps the
+ * POSIX form, so linux/macos are byte-for-byte unchanged.
  */
-export function buildRemoteAgentsInvocation(forwardedArgs, remoteCwd) {
+export function buildRemoteAgentsInvocation(forwardedArgs, remoteCwd, os) {
+    if (remoteShellFor(os) === 'powershell') {
+        return buildWindowsAgentsCommand({ args: forwardedArgs, cwd: remoteCwd });
+    }
     const inner = ['agents', ...forwardedArgs].map(shellQuote).join(' ');
     const withCwd = remoteCwd ? `cd ${shellQuote(remoteCwd)} && ${inner}` : inner;
     return `bash -lc ${shellQuote(withCwd)}`;
 }
+/**
+ * Pick the remote shell dialect from a recorded OS/platform string. A Windows
+ * host (device-registry `platform: 'windows'`, or an enrolled `HostEntry.os`
+ * that reads `windows`/`Windows`/`win32`/…) speaks PowerShell; everything else,
+ * including `undefined`/unknown, defaults to POSIX so linux/macos never regress.
+ */
+export function remoteShellFor(os) {
+    return /^win/i.test((os ?? '').trim()) ? 'powershell' : 'posix';
+}
+/**
+ * PowerShell single-quoted literal: wrap in `'…'` and double any embedded `'`.
+ * Single-quoted PS strings are fully literal (no `$var`, no backtick escapes),
+ * so this neutralises every metacharacter the same way POSIX `shellQuote` does.
+ */
+export function powershellQuote(s) {
+    return "'" + s.replace(/'/g, "''") + "'";
+}
+/**
+ * Encode a PowerShell script for `powershell -EncodedCommand`: base64 of its
+ * UTF-16LE bytes. The payload is a bare base64 word (no spaces or shell
+ * metacharacters), so it survives being handed to ssh as a single argument and
+ * re-parsed by the remote's cmd.exe/PowerShell with zero quoting hazards —
+ * the robust way to ship a complex command to a Windows box over SSH.
+ */
+export function encodePowershell(script) {
+    return Buffer.from(script, 'utf16le').toString('base64');
+}
+/** Inverse of {@link encodePowershell} — decode an `-EncodedCommand` payload
+ * back to its script. Used by tests to assert on the built command. */
+export function decodePowershell(encoded) {
+    return Buffer.from(encoded, 'base64').toString('utf16le');
+}
+/**
+ * The PowerShell script (pre-encoding) that {@link buildWindowsAgentsCommand}
+ * runs. Exposed so tests can decode the `-EncodedCommand` payload and compare
+ * against the exact script, without needing PowerShell on the test host.
+ *
+ * `& agents …` invokes the CLI from the machine PATH (Windows has no login
+ * shell, so there is no `bash -lc` equivalent — the shim is simply on PATH).
+ */
+export function windowsAgentsScript(cmd) {
+    const { args, env, cwd, propagateExit = true } = cmd;
+    const parts = [];
+    if (env)
+        for (const [k, v] of Object.entries(env))
+            parts.push(`$env:${k} = ${powershellQuote(v)}`);
+    if (cwd)
+        parts.push(`Set-Location -LiteralPath ${powershellQuote(cwd)}`);
+    parts.push(`& ${['agents', ...args].map(powershellQuote).join(' ')}`);
+    if (propagateExit)
+        parts.push('exit $LASTEXITCODE');
+    return parts.join('; ');
+}
+/**
+ * Build the `ssh <target> <cmd>` string for one `agents …` invocation on a
+ * Windows remote: a `powershell -NoProfile -EncodedCommand <base64>` call. The
+ * Windows counterpart of `bash -lc '<...>'`, shared by every `--host` site.
+ */
+export function buildWindowsAgentsCommand(cmd) {
+    return `powershell -NoProfile -EncodedCommand ${encodePowershell(windowsAgentsScript(cmd))}`;
+}

package/dist/lib/hosts/remote-os.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolve a remote host's OS family so the SSH command layer can pick the right
+ * shell dialect (POSIX `bash -lc` vs Windows PowerShell). See `remoteShellFor`
+ * in `remote-cmd.ts` for how the string is consumed.
+ *
+ * Two sources, in priority order:
+ *   1. The device registry `platform` (`windows`/`linux`/`macos`), which is
+ *      populated fleet-wide by Tailscale sync — the reliable answer for a box
+ *      like `win-mini` that was discovered, not hand-enrolled.
+ *   2. The enrolled `HostEntry.os` overlay in agents.yaml (the `uname` captured
+ *      at `agents hosts add` time), for hosts that live only in that overlay.
+ *
+ * Missing/unknown from both → `undefined`, which `remoteShellFor` maps to POSIX.
+ * Kept synchronous so the sync `agents sessions --host` fan-out can use it.
+ */
+/** Resolve the OS/platform string for a host name, or undefined if unknown. */
+export declare function resolveRemoteOsSync(name: string): string | undefined;

package/dist/lib/hosts/remote-os.js

@@ -0,0 +1,30 @@
+/**
+ * Resolve a remote host's OS family so the SSH command layer can pick the right
+ * shell dialect (POSIX `bash -lc` vs Windows PowerShell). See `remoteShellFor`
+ * in `remote-cmd.ts` for how the string is consumed.
+ *
+ * Two sources, in priority order:
+ *   1. The device registry `platform` (`windows`/`linux`/`macos`), which is
+ *      populated fleet-wide by Tailscale sync — the reliable answer for a box
+ *      like `win-mini` that was discovered, not hand-enrolled.
+ *   2. The enrolled `HostEntry.os` overlay in agents.yaml (the `uname` captured
+ *      at `agents hosts add` time), for hosts that live only in that overlay.
+ *
+ * Missing/unknown from both → `undefined`, which `remoteShellFor` maps to POSIX.
+ * Kept synchronous so the sync `agents sessions --host` fan-out can use it.
+ */
+import { loadDevicesSync } from '../devices/registry.js';
+import { readMeta } from '../state.js';
+/** Resolve the OS/platform string for a host name, or undefined if unknown. */
+export function resolveRemoteOsSync(name) {
+    try {
+        const platform = loadDevicesSync()[name]?.platform;
+        if (platform && platform !== 'unknown')
+            return platform;
+    }
+    catch {
+        // A corrupt/unreadable device registry must never break command building —
+        // fall through to the host overlay and ultimately the POSIX default.
+    }
+    return readMeta().hosts?.[name]?.os;
+}

package/dist/lib/hosts/session-index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Register host-dispatched runs (`agents run --host <h>`) into the LOCAL session
+ * index so they show up in `agents sessions` and are resolvable by id — even
+ * though the transcript itself lives on the remote host.
+ *
+ * The transcript file is remote, so the row is registered with an EMPTY
+ * `file_path`. The DB's stale-row filter keeps rows with no file_path
+ * (`!file_path || existsSync(file_path)` in db.ts querySessions) precisely for
+ * this "synthetic file_path" case, and the scanner never prunes session rows —
+ * so the entry survives rescans. `cwd` is the LOCAL directory the dispatch was
+ * issued from, so the run appears in that project's session listing like any
+ * local run. The `[host/<name>]` label mirrors the cloud path's
+ * `[cloud/<status>]` convention.
+ */
+import type { SessionMeta } from '../session/types.js';
+import type { HostTask } from './tasks.js';
+export interface HostSessionContext {
+    /** Local directory the `agents run --host` was invoked from. */
+    cwd: string;
+    /** Prompt the run was launched with, used for the session topic. */
+    prompt: string;
+}
+/**
+ * Build the SessionMeta for a host-dispatched run. Returns null when the run has
+ * no captured session id (nothing stable to key/resume on) or its agent isn't a
+ * known session agent. Pure — no I/O — so the mapping is unit-testable.
+ */
+export declare function hostSessionMeta(task: HostTask, ctx: HostSessionContext): SessionMeta | null;
+/**
+ * Register (or refresh) a host-dispatched run in the local session index. No-op
+ * when the task carries no session id. Best-effort: a failed write must never
+ * break the dispatch itself, which has already been launched on the host.
+ */
+export declare function registerHostSession(task: HostTask, ctx: HostSessionContext): void;

package/dist/lib/hosts/session-index.js

@@ -0,0 +1,56 @@
+/**
+ * Register host-dispatched runs (`agents run --host <h>`) into the LOCAL session
+ * index so they show up in `agents sessions` and are resolvable by id — even
+ * though the transcript itself lives on the remote host.
+ *
+ * The transcript file is remote, so the row is registered with an EMPTY
+ * `file_path`. The DB's stale-row filter keeps rows with no file_path
+ * (`!file_path || existsSync(file_path)` in db.ts querySessions) precisely for
+ * this "synthetic file_path" case, and the scanner never prunes session rows —
+ * so the entry survives rescans. `cwd` is the LOCAL directory the dispatch was
+ * issued from, so the run appears in that project's session listing like any
+ * local run. The `[host/<name>]` label mirrors the cloud path's
+ * `[cloud/<status>]` convention.
+ */
+import { upsertSession } from '../session/db.js';
+import { SESSION_AGENTS } from '../session/types.js';
+/**
+ * Build the SessionMeta for a host-dispatched run. Returns null when the run has
+ * no captured session id (nothing stable to key/resume on) or its agent isn't a
+ * known session agent. Pure — no I/O — so the mapping is unit-testable.
+ */
+export function hostSessionMeta(task, ctx) {
+    const id = task.sessionId;
+    if (!id)
+        return null;
+    if (!SESSION_AGENTS.includes(task.agent))
+        return null;
+    return {
+        id,
+        shortId: id.slice(0, 8),
+        agent: task.agent,
+        timestamp: task.createdAt,
+        cwd: ctx.cwd,
+        // Remote transcript — no local file. Empty file_path is the sentinel the DB
+        // stale-filter treats as "always live" (see module doc).
+        filePath: '',
+        topic: ctx.prompt.split('\n')[0]?.slice(0, 120) || undefined,
+        label: `[host/${task.host}]`,
+    };
+}
+/**
+ * Register (or refresh) a host-dispatched run in the local session index. No-op
+ * when the task carries no session id. Best-effort: a failed write must never
+ * break the dispatch itself, which has already been launched on the host.
+ */
+export function registerHostSession(task, ctx) {
+    const meta = hostSessionMeta(task, ctx);
+    if (!meta)
+        return;
+    try {
+        upsertSession(meta, '');
+    }
+    catch {
+        /* index write is best-effort; the run is already live on the host */
+    }
+}

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

@@ -15,6 +15,13 @@ export interface HostTask {
     agent: string;
     prompt: string;
     pid?: number;
+    /**
+     * The agent session id the remote run was launched with (Claude only — the
+     * only agent that accepts `--session-id` to force a NEW session's id). Lets
+     * `agents sessions`/resume-by-id map a discovered session back to the host it
+     * lives on. Absent for agents that don't take an explicit session id.
+     */
+    sessionId?: string;
     /** Remote paths (under the host's ~/.agents/.cache/hosts/). */
     remoteLog: string;
     remoteExit: string;
@@ -29,4 +36,19 @@ export declare function localLogPath(id: string): string;
 export declare function saveTask(task: HostTask): void;
 export declare function loadTask(id: string): HostTask | null;
 export declare function updateTask(id: string, patch: Partial<HostTask>): HostTask | null;
+/**
+ * The record patch for a run that has finished with `code`. The single authority
+ * for the exit-code → status mapping, so the dispatch, reconcile, and log-follow
+ * paths can never disagree. A genuine remote exit code is never -1 (that sentinel
+ * means "follow window closed while the run continues"), so callers must resolve
+ * -1 as still-running and never pass it here.
+ */
+export declare function terminalPatch(code: number): Partial<HostTask>;
 export declare function listTasks(): HostTask[];
+/**
+ * Find the host task that launched a given agent session id, so a resume-by-id
+ * can re-dispatch to the host the session actually lives on. Newest task wins
+ * (listTasks is createdAt-desc) — a session id should be unique, but a re-run
+ * with the same forced id resolves to the most recent dispatch.
+ */
+export declare function findTaskBySessionId(sessionId: string): HostTask | null;

package/dist/lib/hosts/tasks.js

@@ -40,6 +40,20 @@ export function updateTask(id, patch) {
     saveTask(next);
     return next;
 }
+/**
+ * The record patch for a run that has finished with `code`. The single authority
+ * for the exit-code → status mapping, so the dispatch, reconcile, and log-follow
+ * paths can never disagree. A genuine remote exit code is never -1 (that sentinel
+ * means "follow window closed while the run continues"), so callers must resolve
+ * -1 as still-running and never pass it here.
+ */
+export function terminalPatch(code) {
+    return {
+        status: code === 0 ? 'completed' : 'failed',
+        exitCode: code,
+        finishedAt: new Date().toISOString(),
+    };
+}
 export function listTasks() {
     let files;
     try {
@@ -56,3 +70,18 @@ export function listTasks() {
     }
     return tasks.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
 }
+/**
+ * Find the host task that launched a given agent session id, so a resume-by-id
+ * can re-dispatch to the host the session actually lives on. Newest task wins
+ * (listTasks is createdAt-desc) — a session id should be unique, but a re-run
+ * with the same forced id resolves to the most recent dispatch.
+ */
+export function findTaskBySessionId(sessionId) {
+    if (!sessionId)
+        return null;
+    for (const task of listTasks()) {
+        if (task.sessionId === sessionId)
+            return task;
+    }
+    return null;
+}