@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/git.js

@@ -7,6 +7,7 @@
  */
 import simpleGit from 'simple-git';
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { IS_WINDOWS, isWindowsAbsolutePath } from './platform/index.js';
 import { getPackageLocalPath } from './state.js';
@@ -494,6 +495,15 @@ export async function hasLocalChanges(dir) {
         return false;
     }
 }
+/**
+ * Render an absolute path in ~-relative form with forward slashes, matching the
+ * way the rest of the CLI prints home-anchored paths (e.g. `~/.agents/.system`).
+ */
+export function displayHomePath(dir) {
+    const home = os.homedir();
+    const rel = dir.startsWith(home) ? '~' + dir.slice(home.length) : dir;
+    return rel.replace(/\\/g, '/');
+}
 /**
  * Pull changes in an existing repo.
  * Refuses to pull if the working tree is dirty -- user must commit or discard changes first.
@@ -506,7 +516,7 @@ export async function pullRepo(dir) {
             return {
                 success: false,
                 commit: '',
-                error: 'Working tree has uncommitted changes. Commit or discard them before pulling.\n\n  cd ~/.agents && git status',
+                error: `Working tree has uncommitted changes. Commit or discard them before pulling.\n\n  cd ${displayHomePath(dir)} && git status`,
             };
         }
         await git.fetch();
@@ -522,6 +532,51 @@ export async function pullRepo(dir) {
         return { success: false, commit: '', error: err.message };
     }
 }
+/**
+ * Rebase a repo onto its remote, optionally pushing local commits back up.
+ *
+ * The one-repo counterpart to `pullRepo` used by `agents sync <repo>`:
+ *   1. Refuse if the working tree is dirty (commit or discard first).
+ *   2. `git fetch origin` then `git pull --rebase origin <branch>` — rebase, not
+ *      merge, so a local commit lands cleanly on top of upstream with no merge
+ *      bubble.
+ *   3. When `push` is set, `git push origin <branch>` to send local commits up.
+ *
+ * The branch is read from the repo's current HEAD (falls back to `main`) rather
+ * than hardcoded. System repos pass `push: false` — they are pull-only mirrors
+ * of the npm-shipped upstream.
+ */
+export async function syncRepoGit(dir, opts) {
+    try {
+        if (!isGitRepo(dir)) {
+            return { success: false, commit: '', pushed: false, error: `Not a git repo: ${dir}` };
+        }
+        const git = simpleGit(dir);
+        const status = await git.status();
+        if (!status.isClean()) {
+            return {
+                success: false,
+                commit: '',
+                pushed: false,
+                error: `Working tree has uncommitted changes. Commit or discard them first.\n\n  cd ${dir} && git status`,
+            };
+        }
+        const branch = status.current || 'main';
+        await git.fetch('origin');
+        await git.pull('origin', branch, { '--rebase': 'true' });
+        installGithooksSymlinks(dir);
+        let pushed = false;
+        if (opts.push) {
+            await git.push('origin', branch);
+            pushed = true;
+        }
+        const log = await git.log({ maxCount: 1 });
+        return { success: true, commit: log.latest?.hash.slice(0, 8) || 'unknown', pushed };
+    }
+    catch (err) {
+        return { success: false, commit: '', pushed: false, error: err.message };
+    }
+}
 /** Compute the sync status of a git repo, optionally scoped to a subdirectory. */
 export async function getGitSyncStatus(dir, subdir) {
     if (!isGitRepo(dir)) {

package/dist/lib/hooks/cache.d.ts

@@ -7,6 +7,12 @@ import type { HookCache, HookCacheConfig } from '../types.js';
 export declare function parseCacheConfig(raw: HookCache | undefined): HookCacheConfig | null;
 /** Parse "30s" | "5m" | "1h" | plain seconds. Returns seconds, or null on failure. */
 export declare function parseDuration(d: number | string | undefined): number | null;
+/**
+ * Reject hook names that could escape the shims directory when interpolated
+ * into a filename. Mirrors the containment gate on hook script resolution in
+ * hooks.ts (`resolveContainedHookPath`).
+ */
+export declare function isValidHookShimName(name: string): boolean;
 /** Absolute path of the generated shim for a hook name. */
 export declare function getHookShimPath(name: string): string;
 /**

package/dist/lib/hooks/cache.js

@@ -70,9 +70,35 @@ export function parseDuration(d) {
         return value * 60;
     return value;
 }
+/**
+ * Reject hook names that could escape the shims directory when interpolated
+ * into a filename. Mirrors the containment gate on hook script resolution in
+ * hooks.ts (`resolveContainedHookPath`).
+ */
+export function isValidHookShimName(name) {
+    return (!!name &&
+        name !== '.' &&
+        name !== '..' &&
+        !name.startsWith('-') &&
+        !/[\/\\\x00]/.test(name) &&
+        name.length <= 255);
+}
+/** Resolve shimsDir + `${name}.sh` and assert the result stays inside shimsDir. */
+function resolveContainedHookShimPath(shimsDir, name) {
+    if (!isValidHookShimName(name)) {
+        throw new Error(`Invalid hook shim name: ${name}`);
+    }
+    const resolvedRoot = path.resolve(shimsDir);
+    const candidate = path.join(shimsDir, `${name}.sh`);
+    const resolved = path.resolve(candidate);
+    if (!resolved.startsWith(resolvedRoot + path.sep)) {
+        throw new Error(`Invalid hook shim name: ${name}`);
+    }
+    return resolved;
+}
 /** Absolute path of the generated shim for a hook name. */
 export function getHookShimPath(name) {
-    return path.join(getHookShimsDir(), `${name}.sh`);
+    return resolveContainedHookShimPath(getHookShimsDir(), name);
 }
 /**
  * Generate (or refresh) the shim script for a hook. Idempotent — only writes
@@ -82,7 +108,7 @@ export function generateHookShim(args) {
     const shimsDir = args.paths?.shimsDir ?? getHookShimsDir();
     const cacheDir = args.paths?.cacheDir ?? getHookCacheDir();
     const logsDir = args.paths?.logsDir ?? getLogsDir();
-    const shimPath = path.join(shimsDir, `${args.name}.sh`);
+    const shimPath = resolveContainedHookShimPath(shimsDir, args.name);
     const content = renderShim(args.name, args.scriptPath, args.cache, { cacheDir, logsDir });
     fs.mkdirSync(shimsDir, { recursive: true });
     let existing = null;
@@ -105,9 +131,10 @@ export function generateHookShim(args) {
     return shimPath;
 }
 /**
- * Render the bash shim. Bash 3.2-compatible (macOS default). Uses python3 for
- * monotonic-ish nanosecond timing — already a hard dependency of other hooks
- * in this repo (04-capture-session-start-metadata.sh does the same).
+ * Render the bash shim. Bash 3.2-compatible (macOS default). Uses Python for
+ * hashing + monotonic-ish nanosecond timing + portable mtime, resolved at
+ * runtime (python3, then python) so a Windows Microsoft Store `python3` alias
+ * stub — which exits non-zero without running — doesn't silently break caching.
  */
 function renderShim(name, scriptPath, cache, paths) {
     const ttl = typeof cache.ttl === 'number' ? cache.ttl : (parseDuration(cache.ttl) ?? 0);
@@ -133,12 +160,25 @@ KEY_MODE=${q(key)}
 
 mkdir -p "$CACHE_DIR" "$LOGS_DIR"
 
+# Resolve a real Python. On Windows, bare python3 is often a Microsoft Store
+# app-execution alias stub that prints to stderr and exits non-zero (0 bytes on
+# stdout) -- command -v finds it but it cannot run, which silently empties the
+# hash + mtime primitives below and makes EVERY call a cache miss (the hook
+# re-runs every time). Probe by executing, not by lookup, and fall back to python.
+PY=""
+for _cand in python3 python; do
+  if command -v "$_cand" >/dev/null 2>&1 && "$_cand" -c 'import sys' >/dev/null 2>&1; then
+    PY="$_cand"; break
+  fi
+done
+[ -z "$PY" ] && PY=python3
+
 # Read stdin once (Claude/Codex/Gemini pass JSON on stdin to every hook).
 STDIN_PAYLOAD="$(cat || true)"
 
 # Portable sha1 — \`shasum\` is Perl, missing on minimal Linux images;
 # \`sha1sum\` is coreutils, missing on macOS. Truncate to 12 hex chars.
-sha1_12() { python3 -c 'import hashlib,sys; print(hashlib.sha1(sys.stdin.read().encode()).hexdigest()[:12])'; }
+sha1_12() { "$PY" -c 'import hashlib,sys; print(hashlib.sha1(sys.stdin.read().encode()).hexdigest()[:12])'; }
 
 # Derive cache key suffix from KEY_MODE. All untrusted inputs (cwd, session_id,
 # project path) are hashed before going into the filename so a malicious stdin
@@ -146,14 +186,14 @@ sha1_12() { python3 -c 'import hashlib,sys; print(hashlib.sha1(sys.stdin.read().
 cache_suffix=""
 case "$KEY_MODE" in
   per-cwd)
-    cwd_val="$(printf '%s' "$STDIN_PAYLOAD" | python3 -c 'import json,sys
+    cwd_val="$(printf '%s' "$STDIN_PAYLOAD" | "$PY" -c 'import json,sys
 try: print(json.load(sys.stdin).get("cwd","") or "")
 except Exception: pass' 2>/dev/null || true)"
     [ -z "$cwd_val" ] && cwd_val="$PWD"
     cache_suffix=".$(printf '%s' "$cwd_val" | sha1_12)"
     ;;
   per-session)
-    sid_val="$(printf '%s' "$STDIN_PAYLOAD" | python3 -c 'import json,sys
+    sid_val="$(printf '%s' "$STDIN_PAYLOAD" | "$PY" -c 'import json,sys
 try: print(json.load(sys.stdin).get("session_id","") or "")
 except Exception: pass' 2>/dev/null || true)"
     # Hash + fall back to a sentinel so missing-session doesn't silently
@@ -173,7 +213,7 @@ esac
 CACHE_FILE="$CACHE_DIR/$HOOK_NAME$cache_suffix.out"
 
 # Monotonic-ish nanosecond timer (macOS \`date\` has no %N).
-now_ns() { python3 -c 'import time; print(int(time.time()*1e9))'; }
+now_ns() { "$PY" -c 'import time; print(int(time.time()*1e9))'; }
 START_NS=$(now_ns)
 
 CACHE_STATUS=miss
@@ -181,10 +221,10 @@ CACHE_AGE=-1
 EXIT=0
 
 if [ -f "$CACHE_FILE" ]; then
-  # python3 is already a hard dep (used for now_ns) and gives portable mtime
+  # $PY is already resolved (used for now_ns) and gives portable mtime
   # without the macOS-vs-Linux \`stat\` flag divergence (-f %m vs -c %Y) that
   # blew up under \`set -u\` when the wrong flag produced literal "%m".
-  mtime=$(python3 -c 'import os,sys; print(int(os.path.getmtime(sys.argv[1])))' "$CACHE_FILE" 2>/dev/null)
+  mtime=$("$PY" -c 'import os,sys; print(int(os.path.getmtime(sys.argv[1])))' "$CACHE_FILE" 2>/dev/null)
   mtime=\${mtime:-0}
   now_s=$(date +%s)
   CACHE_AGE=$((now_s - mtime))
@@ -231,8 +271,10 @@ exit "$EXIT"
  * hook is renamed/deleted or has its `cache:` field removed.
  */
 export function removeHookShim(name, shimsDir) {
+    if (!isValidHookShimName(name))
+        return;
     const dir = shimsDir ?? getHookShimsDir();
-    const shimPath = path.join(dir, `${name}.sh`);
+    const shimPath = resolveContainedHookShimPath(dir, name);
     if (fs.existsSync(shimPath)) {
         try {
             fs.unlinkSync(shimPath);

package/dist/lib/hooks.d.ts

@@ -8,6 +8,19 @@
  * and syncing them across version switches.
  */
 export declare function resolveHookScriptPath(script: string): string | null;
+/**
+ * Convert an absolute path under HOME to a portable ~/... form with forward
+ * slashes. Hook commands stored this way work on both macOS and Windows:
+ * absolute Windows paths break in bash because backslashes are stripped as
+ * escape characters, whereas ~/... paths expand correctly via the ~/.claude
+ * symlink/junction on both platforms.
+ *
+ * `home` and `sep` are injectable so the Windows behavior (backslash sep,
+ * drive-letter home) is unit-testable on a POSIX CI host — pass sep='\\' to
+ * simulate Windows. With the defaults this is byte-identical to reading
+ * os.homedir()/path.sep at the call site.
+ */
+export declare function toPortableCommand(absPath: string, home?: string, sep?: string): string;
 import type { AgentId, InstalledHook, ManifestHook } from './types.js';
 export type HookEntry = {
     name: string;
@@ -165,3 +178,17 @@ export declare function registerHooksToSettings(agentId: AgentId, versionHome: s
     registered: string[];
     errors: string[];
 };
+/**
+ * Prune every Claude-family (`settings.json`) hook entry whose command lives
+ * under a removed version's home
+ * (`~/.agents/.history/versions/<agent>/<removedVersion>/home/…`).
+ *
+ * `agents remove <agent>@<version>` soft-deletes the version's files but leaves
+ * the hook entries other version homes registered against it — dead hooks that
+ * error on every tool call ("No such file or directory") until the next sync.
+ * This clears them from a remaining version's settings immediately. Only the
+ * removed version's entries are touched; the current version's entries, system
+ * hooks, and the user's own custom hooks are left intact. Returns the number of
+ * entries removed.
+ */
+export declare function pruneVersionHomeHookEntriesFromSettings(settingsPath: string, agent: AgentId, removedVersion: string): number;

package/dist/lib/hooks.js

@@ -68,11 +68,15 @@ function getManagedHookPrefixes() {
  * absolute Windows paths break in bash because backslashes are stripped as
  * escape characters, whereas ~/... paths expand correctly via the ~/.claude
  * symlink/junction on both platforms.
+ *
+ * `home` and `sep` are injectable so the Windows behavior (backslash sep,
+ * drive-letter home) is unit-testable on a POSIX CI host — pass sep='\\' to
+ * simulate Windows. With the defaults this is byte-identical to reading
+ * os.homedir()/path.sep at the call site.
  */
-function toPortableCommand(absPath) {
-    const home = os.homedir();
-    const normalized = absPath.split(path.sep).join('/');
-    const homeNorm = home.split(path.sep).join('/');
+export function toPortableCommand(absPath, home = os.homedir(), sep = path.sep) {
+    const normalized = absPath.split(sep).join('/');
+    const homeNorm = home.split(sep).join('/');
     if (normalized.startsWith(homeNorm + '/')) {
         return '~/' + normalized.slice(homeNorm.length + 1);
     }
@@ -113,8 +117,38 @@ function isManagedHookCommand(command, prefixes) {
     }
     return false;
 }
+/**
+ * Per-version-home command detection. Sync copies each hook script into the
+ * active version's home and registers the command by that version-scoped path
+ * (`~/.agents/.history/versions/<agent>/<version>/home/…`). Because the path
+ * embeds the version number, a later version's sync appends a fresh set whose
+ * paths never string-match (and thus never prune) the prior version's entries —
+ * so entries for every version installed over time pile up in one settings
+ * file, and once a version is removed its entries become dead hooks that error
+ * on every tool call. `versionHomeIdentity` extracts the `<agent>/<version>` a
+ * command (or home path) belongs to so stale sibling-version entries can be
+ * pruned. Returns null for any path outside a per-version home (system hooks,
+ * the user's own custom hooks) — those are never a prune target.
+ */
+const VERSION_HOME_SEGMENT_RE = /\.history\/versions\/([^/]+)\/([^/]+)\/home(?:\/|$)/;
+function versionHomeIdentity(commandOrPath) {
+    const norm = commandOrPath.split(/[\\/]/).join('/');
+    const m = VERSION_HOME_SEGMENT_RE.exec(norm);
+    return m ? { agent: m[1], version: m[2] } : null;
+}
+/**
+ * True when `command` points into a DIFFERENT version home of the same agent as
+ * `current` — i.e. a stale entry left behind by an earlier version's sync.
+ * Non-version-home commands (system + user-custom hooks) always return false.
+ */
+function isStaleSiblingVersionCommand(command, current) {
+    if (!current)
+        return false;
+    const id = versionHomeIdentity(command);
+    return id !== null && id.agent === current.agent && id.version !== current.version;
+}
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
-import { generateHookShim, parseCacheConfig, removeHookShim } from './hooks/cache.js';
+import { generateHookShim, isValidHookShimName, parseCacheConfig, removeHookShim } from './hooks/cache.js';
 import { getHookShimsDir } from './state.js';
 /**
  * Resolve the command path to register for a hook.
@@ -128,6 +162,8 @@ function resolveHookCommand(name, hookDef, resolveScript) {
     const scriptPath = resolveScript(hookDef.script);
     if (!scriptPath)
         return null;
+    if (!isValidHookShimName(name))
+        return null;
     const cache = parseCacheConfig(hookDef.cache);
     if (!cache) {
         // No caching opted in — make sure a previously generated shim from an
@@ -715,6 +751,24 @@ export function parseHookManifest(opts = {}) {
         }
         catch { /* skip unreadable manifest */ }
     }
+    // Extra-repo layer: hooks: section of each enabled extra repo's agents.yaml.
+    // Sits above system but below user, mirroring resolveHookScriptPath's
+    // first-found order (user > extra > system). Without this layer the script
+    // path of an extra-repo hook resolves but its events never register (#602).
+    // Earlier extras win over later ones, so iterate in reverse: the last write
+    // for a given name comes from the earliest-registered repo.
+    for (const { dir } of [...getEnabledExtraRepos()].reverse()) {
+        const extraMetaPath = path.join(dir, 'agents.yaml');
+        if (!fs.existsSync(extraMetaPath))
+            continue;
+        try {
+            const meta = yaml.parse(fs.readFileSync(extraMetaPath, 'utf-8'));
+            if (meta?.hooks)
+                for (const [name, def] of Object.entries(meta.hooks))
+                    merged[name] = def;
+        }
+        catch { /* skip unreadable extra-repo manifest */ }
+    }
     // User layer: hooks: section of agents.yaml.
     const userMetaPath = path.join(getUserAgentsDir(), 'agents.yaml');
     if (fs.existsSync(userMetaPath)) {
@@ -910,6 +964,12 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     if (agentId === 'claude') {
         return registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes);
     }
+    if (agentId === 'droid') {
+        // Droid's settings.json hooks schema is identical to Claude's (top-level
+        // `hooks` object → event → matcher-group array), so reuse the Claude
+        // registrar targeting `.factory/settings.json` (agentConfigDirName('droid')).
+        return registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes, agentConfigDirName('droid'));
+    }
     if (agentId === 'codex') {
         return registerHooksForCodex(versionHome, manifest, resolveScript, managedPrefixes);
     }
@@ -953,10 +1013,10 @@ const ANTIGRAVITY_EVENT_MAP = {
 const GEMINI_EVENT_MAP = {
     UserPromptSubmit: 'BeforeAgent',
 };
-function registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes) {
+function registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes, configDirName = '.claude') {
     const registered = [];
     const errors = [];
-    const configDir = path.join(versionHome, '.claude');
+    const configDir = path.join(versionHome, configDirName);
     const settingsPath = path.join(configDir, 'settings.json');
     let config = {};
     if (fs.existsSync(settingsPath)) {
@@ -983,15 +1043,21 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
         if (resolved)
             currentManifestPaths.add(resolved);
     }
-    // Remove stale entries: any hook command under a managed root that isn't
-    // in the current manifest is a leftover from a renamed/deleted hook script.
+    // Identity of the version home being synced. Used to prune entries that point
+    // at a DIFFERENT version home of the same agent (see isStaleSiblingVersionCommand).
+    const currentVh = versionHomeIdentity(versionHome);
+    // Remove stale entries: any hook command under a managed root that isn't in
+    // the current manifest is a leftover from a renamed/deleted hook script; any
+    // command pointing at a sibling version's home is a leftover from that
+    // version's sync (its version-scoped path never matches the current set).
     for (const eventEntries of Object.values(hooks)) {
         if (!Array.isArray(eventEntries))
             continue;
         for (const group of eventEntries) {
             if (!group.hooks)
                 continue;
-            group.hooks = group.hooks.filter((h) => !isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command));
+            group.hooks = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
+                !isStaleSiblingVersionCommand(h.command, currentVh));
         }
     }
     // Remove empty matcher groups left after cleanup
@@ -1043,6 +1109,65 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
     }
     return { registered, errors };
 }
+/**
+ * Prune every Claude-family (`settings.json`) hook entry whose command lives
+ * under a removed version's home
+ * (`~/.agents/.history/versions/<agent>/<removedVersion>/home/…`).
+ *
+ * `agents remove <agent>@<version>` soft-deletes the version's files but leaves
+ * the hook entries other version homes registered against it — dead hooks that
+ * error on every tool call ("No such file or directory") until the next sync.
+ * This clears them from a remaining version's settings immediately. Only the
+ * removed version's entries are touched; the current version's entries, system
+ * hooks, and the user's own custom hooks are left intact. Returns the number of
+ * entries removed.
+ */
+export function pruneVersionHomeHookEntriesFromSettings(settingsPath, agent, removedVersion) {
+    if (!fs.existsSync(settingsPath))
+        return 0;
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    }
+    catch {
+        return 0;
+    }
+    if (!config.hooks || typeof config.hooks !== 'object')
+        return 0;
+    const hooks = config.hooks;
+    let removed = 0;
+    for (const eventEntries of Object.values(hooks)) {
+        if (!Array.isArray(eventEntries))
+            continue;
+        for (const group of eventEntries) {
+            if (!group.hooks)
+                continue;
+            const before = group.hooks.length;
+            group.hooks = group.hooks.filter((h) => {
+                const id = versionHomeIdentity(h.command);
+                return !(id !== null && id.agent === agent && id.version === removedVersion);
+            });
+            removed += before - group.hooks.length;
+        }
+    }
+    if (removed === 0)
+        return 0;
+    // Drop matcher groups left empty by the prune.
+    for (const [event, eventEntries] of Object.entries(hooks)) {
+        if (!Array.isArray(eventEntries))
+            continue;
+        hooks[event] = eventEntries.filter((g) => g.hooks && g.hooks.length > 0);
+    }
+    try {
+        fs.writeFileSync(settingsPath, JSON.stringify(config, null, 2), 'utf-8');
+    }
+    catch {
+        // Best-effort cleanup: a write failure leaves the dead entry to be pruned
+        // on the next sync (see isStaleSiblingVersionCommand).
+        return 0;
+    }
+    return removed;
+}
 function registerHooksForCodex(versionHome, manifest, resolveScript, managedPrefixes) {
     const registered = [];
     const errors = [];

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

@@ -21,10 +21,25 @@ export interface DispatchOptions {
     mode?: string;
     model?: string;
     remoteCwd?: string;
+    /**
+     * Force the remote run's NEW session to use this exact id (Claude only, via
+     * `agents run --session-id`). Captured on the task record so the run is
+     * resumable by id. Mutually exclusive with `resume`.
+     */
+    sessionId?: string;
+    /** Resume an existing session on the host by id (via `agents run --resume`). */
+    resume?: string;
     /** Stream progress and block until completion (default true). */
     follow?: boolean;
     timeoutMs?: number;
 }
+/**
+ * Build the remote `agents run …` argv for a host dispatch. Pure so the
+ * session-id / resume flag wiring is unit-testable without an SSH round-trip.
+ * `--session-id` and `--resume` are mutually exclusive (the CLI rejects both);
+ * resume wins when — defensively — both are set.
+ */
+export declare function buildRunForwardedArgs(opts: DispatchOptions): string[];
 /** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
 export declare function dispatchToHost(host: Host, opts: DispatchOptions): Promise<DispatchResult>;
 export interface CommandDispatchOptions {

package/dist/lib/hosts/dispatch.js

@@ -12,7 +12,9 @@ import { randomUUID } from 'crypto';
 import { sshExec, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from './types.js';
 import { ensureHostReady } from './ready.js';
-import { saveTask, updateTask } from './tasks.js';
+import { remoteShellFor } from './remote-cmd.js';
+import { resolveRemoteOsSync } from './remote-os.js';
+import { saveTask, updateTask, terminalPatch } from './tasks.js';
 import { followHostTask } from './progress.js';
 // Use $HOME (not ~) so the path is correct whether or not it's quoted and
 // regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
@@ -22,8 +24,22 @@ const REMOTE_DIR = '$HOME/.agents/.cache/hosts';
  * The launch + task-record + optional follow core. Both `dispatchToHost` (run)
  * and `dispatchAgentsCommand` (teams) build their `forwardedArgs` and call here,
  * so the nohup/exit-file/offset-tail machinery lives in exactly one place.
+ *
+ * Windows remotes are refused up front: the detached launch is only half the
+ * contract — the follow/reconcile layer (`progress.ts`/`reconcile.ts`) offset-
+ * tails the log with POSIX `tail -c`/`printf`/`cat`/`stat`, which do not exist
+ * in cmd.exe/PowerShell. Shipping the launch alone would leave `run --host
+ * <windows>` dispatching but hanging on follow forever, so we fail fast with an
+ * actionable message instead. Read-only `--host` commands (view/sessions/…) run
+ * a single round-trip with no follow protocol and DO work against Windows.
  */
 async function launchDetached(host, target, opts) {
+    if (remoteShellFor(resolveRemoteOsSync(host.name)) === 'powershell') {
+        throw new Error(`Detached dispatch to Windows host "${host.name}" is not supported yet — the run ` +
+            `follow/reconcile layer is POSIX-only (offset-tails the remote log with tail/cat/stat). ` +
+            `Read-only --host commands (view, sessions, usage, cost, doctor, list, teams) do work ` +
+            `against Windows.`);
+    }
     const id = randomUUID().slice(0, 8);
     const remoteLog = `${REMOTE_DIR}/${id}.log`;
     const remoteExit = `${REMOTE_DIR}/${id}.exit`;
@@ -45,6 +61,7 @@ async function launchDetached(host, target, opts) {
         agent: opts.agentLabel,
         prompt: opts.promptLabel,
         pid: Number.isFinite(pid) ? pid : undefined,
+        sessionId: opts.sessionId,
         remoteLog,
         remoteExit,
         status: 'running',
@@ -61,12 +78,29 @@ async function launchDetached(host, target, opts) {
         echo: true,
         timeoutMs: opts.timeoutMs,
     });
-    const finished = updateTask(id, {
-        status: exitCode === 0 ? 'completed' : exitCode === -1 ? 'unknown' : 'failed',
-        exitCode: exitCode === -1 ? undefined : exitCode,
-        finishedAt: new Date().toISOString(),
-    });
-    return { task: finished ?? task, exitCode };
+    // -1 = the follow window closed while the run continues on the host. Leave the
+    // record 'running' (do NOT freeze it terminal) so a later `hosts ps`/`logs`
+    // reconcile against the remote `.exit` resolves the true final status.
+    const finished = exitCode === -1 ? task : (updateTask(id, terminalPatch(exitCode)) ?? task);
+    return { task: finished, exitCode };
+}
+/**
+ * Build the remote `agents run …` argv for a host dispatch. Pure so the
+ * session-id / resume flag wiring is unit-testable without an SSH round-trip.
+ * `--session-id` and `--resume` are mutually exclusive (the CLI rejects both);
+ * resume wins when — defensively — both are set.
+ */
+export function buildRunForwardedArgs(opts) {
+    const args = ['run', opts.agent, opts.prompt, '--quiet'];
+    if (opts.mode)
+        args.push('--mode', opts.mode);
+    if (opts.model)
+        args.push('--model', opts.model);
+    if (opts.resume)
+        args.push('--resume', opts.resume);
+    else if (opts.sessionId)
+        args.push('--session-id', opts.sessionId);
+    return args;
 }
 /** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
 export async function dispatchToHost(host, opts) {
@@ -74,18 +108,16 @@ export async function dispatchToHost(host, opts) {
     const { warnings } = ensureHostReady(host, { agent: opts.agent });
     for (const w of warnings)
         process.stderr.write(`[hosts] warning: ${w}\n`);
-    const forwardedArgs = ['run', opts.agent, opts.prompt, '--quiet'];
-    if (opts.mode)
-        forwardedArgs.push('--mode', opts.mode);
-    if (opts.model)
-        forwardedArgs.push('--model', opts.model);
     return launchDetached(host, target, {
-        forwardedArgs,
+        forwardedArgs: buildRunForwardedArgs(opts),
         remoteCwd: opts.remoteCwd,
         follow: opts.follow,
         timeoutMs: opts.timeoutMs,
         agentLabel: opts.agent,
         promptLabel: opts.prompt,
+        // On resume the remote session keeps its existing id; record that id so the
+        // task stays mapped to the same session.
+        sessionId: opts.resume ?? opts.sessionId,
     });
 }
 /**

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

@@ -0,0 +1,16 @@
+/**
+ * Shared host-task log viewer — the show-or-follow core behind both
+ * `agents hosts logs <id>` and the top-level `agents logs <id>`.
+ *
+ * A running task with follow re-enters the offset-tail (`followHostTask`);
+ * otherwise the captured local mirror (`localLogPath`) is printed. Kept in one
+ * place so the two commands can never drift.
+ */
+export interface HostLogResult {
+    /** False when no host task with this id exists (caller may fall through to sessions). */
+    found: boolean;
+    /** Process exit code to adopt when the task was shown/followed. */
+    exitCode?: number;
+}
+/** Show (or follow, when running) a dispatched host task's combined-stdout log. */
+export declare function showHostTaskLog(id: string, follow: boolean): Promise<HostLogResult>;