@phnx-labs/agents-cli 1.20.33 → 1.20.35

package/dist/lib/drift-sync.js

@@ -0,0 +1,179 @@
+/**
+ * Interactive drift-sync flow — the single "we detected drift, want to fix it?"
+ * action, shared by `agents status`, `agents doctor`, and the menu-bar "NEEDS
+ * SYNC" row.
+ *
+ * It composes existing pieces, re-implementing nothing:
+ *   - computeSyncStatus()          — the unified detection engine (sync-status.ts)
+ *   - pullRepo()                   — fast-forward the `.system` repo (git.ts)
+ *   - promptAgentVersionSelection() — the "which agent types / versions?" picker
+ *   - heal({ mode: 'full' })       — the reconcile engine `doctor --fix` uses
+ *
+ * Combined flow (one confirmation): if `.system` is behind AND resources drifted,
+ * a single "Sync all detected" both pulls `.system` and reconciles the chosen
+ * version homes. The security posture is preserved — the `.system` pull only ever
+ * happens on an explicit user choice here, never silently (see auto-pull-worker.ts
+ * for why system auto-pull is off by default).
+ */
+import chalk from 'chalk';
+import { select, confirm } from '@inquirer/prompts';
+import { AGENTS } from './agents.js';
+import { pullRepo } from './git.js';
+import { heal } from './heal.js';
+import { promptAgentVersionSelection } from './versions.js';
+import { isInteractiveTerminal, isPromptCancelled } from '../commands/utils.js';
+import { computeSyncStatus, } from './sync-status.js';
+const agentName = (id) => AGENTS[id]?.name ?? id;
+/** "claude@2.1.170  2 drifted · 1 missing" for one version. */
+function versionLine(v) {
+    const bits = [];
+    if (v.counts.drifted)
+        bits.push(`${v.counts.drifted} drifted`);
+    if (v.counts.missing)
+        bits.push(`${v.counts.missing} missing`);
+    const label = `${agentName(v.agent)}@${v.version}`;
+    return `  ${label.padEnd(28)} ${chalk.yellow(bits.join(' · '))}`;
+}
+/** Render the drift summary (system freshness + each version owed a sync). */
+function renderSummary(status, needing) {
+    console.log(chalk.bold('\nSync status'));
+    if (status.system.behind > 0) {
+        console.log(`  ${'.system repo'.padEnd(28)} ${chalk.yellow(`${status.system.behind} commit${status.system.behind === 1 ? '' : 's'} behind`)} ${chalk.gray('— pull recommended')}`);
+    }
+    for (const v of needing)
+        console.log(versionLine(v));
+    if (status.totals.orphan > 0) {
+        console.log(chalk.gray(`  (${status.totals.orphan} orphan${status.totals.orphan === 1 ? '' : 's'} — run \`agents prune cleanup\`)`));
+    }
+}
+/** Fast-forward the `.system` repo. Returns whether it actually moved. */
+async function pullSystem(status) {
+    if (status.system.behind <= 0)
+        return false;
+    const res = await pullRepo(status.system.dir);
+    if (res.success) {
+        console.log(chalk.green(`Pulled .system (+${status.system.behind}).`));
+        return true;
+    }
+    console.log(chalk.red(`Could not pull .system: ${res.error ?? 'unknown error'}`));
+    return false;
+}
+/** Reconcile a set of versions grouped by agent via the shared heal engine. */
+async function healVersions(versionsByAgent, cwd) {
+    const out = [];
+    for (const [agent, versions] of versionsByAgent) {
+        if (versions.length === 0)
+            continue;
+        const res = await heal({ mode: 'full', cwd, agent, versions });
+        out.push(...res.versions);
+    }
+    return out;
+}
+/** Report which agents received what after a heal. */
+function reportHealed(healed) {
+    const touched = healed.filter((v) => v.healed.length > 0);
+    if (touched.length === 0) {
+        console.log(chalk.gray('Nothing to reconcile — homes already matched sources.'));
+        return;
+    }
+    const total = touched.reduce((n, v) => n + v.healed.length, 0);
+    const agents = [...new Set(touched.map((v) => agentName(v.agent)))].join(', ');
+    console.log(chalk.green(`Synced ${total} resource${total === 1 ? '' : 's'} to ${agents}.`));
+}
+function groupNeeding(needing) {
+    const m = new Map();
+    for (const v of needing) {
+        const list = m.get(v.agent) ?? [];
+        list.push(v.version);
+        m.set(v.agent, list);
+    }
+    return m;
+}
+/**
+ * The unified "drift detected — sync now?" flow. Returns a structured result so
+ * callers (menu-bar, doctor) can report without re-scanning.
+ */
+export async function promptDriftSync(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const status = opts.status ?? (await computeSyncStatus({ cwd }));
+    const needing = status.agents.filter((a) => a.needsSync);
+    const systemBehind = status.system.behind;
+    const base = {
+        systemBehindBefore: systemBehind,
+        systemPulled: false,
+        healed: [],
+        cancelled: false,
+        nothingToDo: false,
+    };
+    if (systemBehind <= 0 && needing.length === 0) {
+        console.log(chalk.green('Everything is in sync.'));
+        return { ...base, nothingToDo: true };
+    }
+    if (!opts.quiet)
+        renderSummary(status, needing);
+    // Non-interactive OR explicit --yes: reconcile everything detected.
+    if (opts.yes || !isInteractiveTerminal()) {
+        if (!opts.yes) {
+            // Non-TTY without --yes: report, don't act, don't throw.
+            console.log(chalk.gray('\nRun `agents status --yes` to sync, or `agents status` in a terminal to choose.'));
+            return base;
+        }
+        const systemPulled = await pullSystem(status);
+        const healed = await healVersions(groupNeeding(needing), cwd);
+        reportHealed(healed);
+        return { ...base, systemPulled, healed };
+    }
+    // Interactive gate.
+    let choice;
+    try {
+        choice = await select({
+            message: 'Sync now?',
+            choices: [
+                { name: 'Sync all detected', value: 'all' },
+                { name: 'Choose agents & resources', value: 'choose' },
+                { name: 'No', value: 'no' },
+            ],
+            default: 'all',
+        });
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return { ...base, cancelled: true };
+        throw err;
+    }
+    if (choice === 'no')
+        return { ...base, cancelled: true };
+    if (choice === 'all') {
+        const systemPulled = await pullSystem(status);
+        const healed = await healVersions(groupNeeding(needing), cwd);
+        reportHealed(healed);
+        return { ...base, systemPulled, healed };
+    }
+    // choice === 'choose': optional .system pull, then per-agent/version selection.
+    let systemPulled = false;
+    if (systemBehind > 0) {
+        try {
+            const pull = await confirm({ message: `Pull .system (${systemBehind} behind) first?`, default: true });
+            if (pull)
+                systemPulled = await pullSystem(status);
+        }
+        catch (err) {
+            if (!isPromptCancelled(err))
+                throw err;
+            return { ...base, systemPulled, cancelled: true };
+        }
+    }
+    const needingAgents = [...new Set(needing.map((a) => a.agent))];
+    let selection;
+    try {
+        selection = await promptAgentVersionSelection(needingAgents);
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return { ...base, systemPulled, cancelled: true };
+        throw err;
+    }
+    const healed = await healVersions(selection.versionSelections, cwd);
+    reportHealed(healed);
+    return { ...base, systemPulled, healed };
+}

package/dist/lib/events.d.ts

@@ -1,7 +1,7 @@
 /**
  * Centralized event logging for agents-cli.
  *
- * Structured JSONL logs at ~/.agents/logs/events-YYYY-MM-DD.jsonl
+ * Structured JSONL logs at ~/.agents/.cache/logs/events-YYYY-MM-DD.jsonl
  * with automatic daily rotation and rich metadata for debugging/auditing.
  *
  * Features:
@@ -11,7 +11,7 @@
  * - Permissions: logs dir is 0700, files are 0600 (owner-only)
  * - Performance tracking: withTiming() wrapper for any async function
  */
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'resource.sync' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'resource.sync' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'error' | 'warn' | 'info' | 'debug';
 export interface EventMeta {
     ts: string;
     tz: string;
@@ -22,12 +22,18 @@ export interface EventMeta {
     pid: number;
     ppid: number;
     event: EventType;
+    osUser: string;
+    transport: 'local' | 'ssh';
+    sshClientIp?: string;
 }
 export interface EventPayload {
     agent?: string;
     version?: string;
     sessionId?: string;
     cwd?: string;
+    /** Top-level command group, e.g. 'teams', 'secrets' — the audit filter key. */
+    module?: string;
+    /** Full command path, e.g. 'teams create', 'secrets get'. */
     command?: string;
     args?: string[];
     input?: string;
@@ -155,6 +161,7 @@ export declare function query(options: {
     eventTypes?: EventType[];
     agent?: string;
     command?: string;
+    module?: string;
     limit?: number;
 }): EventRecord[];
 /**

package/dist/lib/events.js

@@ -1,7 +1,7 @@
 /**
  * Centralized event logging for agents-cli.
  *
- * Structured JSONL logs at ~/.agents/logs/events-YYYY-MM-DD.jsonl
+ * Structured JSONL logs at ~/.agents/.cache/logs/events-YYYY-MM-DD.jsonl
  * with automatic daily rotation and rich metadata for debugging/auditing.
  *
  * Features:
@@ -15,6 +15,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { createHash } from 'node:crypto';
+import { parseSshConnection } from './session/provenance.js';
 // ─── Constants ────────────────────────────────────────────────────────────────
 // Logs live under the cache bucket — they're regenerable telemetry.
 const LOGS_DIR = path.join(os.homedir(), '.agents', '.cache', 'logs');
@@ -130,6 +131,30 @@ function truncatePayload(payload, maxLength = DEFAULT_TRUNCATE_LENGTH) {
     }
     return result;
 }
+/**
+ * Who is running this process and from where. Derived once per process from the
+ * OS user and $SSH_CONNECTION (via the same parser the sessions layer uses), then
+ * cached — provenance can't change mid-process, so every emit() pays for it once.
+ */
+let _origin;
+function auditOrigin() {
+    if (_origin)
+        return _origin;
+    let osUser = 'unknown';
+    try {
+        osUser = os.userInfo().username;
+    }
+    catch {
+        // Container/edge cases where the uid has no passwd entry.
+    }
+    const ssh = process.env.SSH_CONNECTION ? parseSshConnection(process.env.SSH_CONNECTION) : undefined;
+    _origin = {
+        osUser,
+        transport: ssh ? 'ssh' : 'local',
+        ...(ssh ? { sshClientIp: ssh.clientIp } : {}),
+    };
+    return _origin;
+}
 // ─── Core API ─────────────────────────────────────────────────────────────────
 /**
  * Emit a structured event to the daily log file.
@@ -152,23 +177,33 @@ export function emit(event, payload = {}) {
             pid: process.pid,
             ppid: process.ppid,
             event,
+            ...auditOrigin(),
             ...truncatePayload(payload),
         };
         const line = JSON.stringify(record) + '\n';
         const logPath = getLogFilePath();
+        const isNew = !fs.existsSync(logPath);
         fs.appendFileSync(logPath, line, { mode: FILE_MODE });
-        // Ensure file permissions (appendFileSync doesn't respect mode on existing files)
-        try {
-            fs.chmodSync(logPath, FILE_MODE);
-        }
-        catch {
-            // May fail if not owner
+        // appendFileSync's mode only applies when it CREATES the file, so we chmod
+        // to guarantee 0600 — but only on first write to a given path this process.
+        // command.start/end fire on every invocation; chmod-per-append would double
+        // the syscalls on the hot path for no gain (perms don't drift mid-run).
+        if (isNew || logPath !== _chmoddedPath) {
+            _chmoddedPath = logPath;
+            try {
+                fs.chmodSync(logPath, FILE_MODE);
+            }
+            catch {
+                // May fail if not owner
+            }
         }
     }
     catch {
         // Silent failure - logging should never break the CLI
     }
 }
+/** Last log path this process chmod'd — avoids a redundant chmod per append. */
+let _chmoddedPath;
 /**
  * Convenience wrapper for timed operations.
  * Returns a function to call when the operation completes.
@@ -402,7 +437,7 @@ export function maybeRotate() {
  * @returns Array of event records
  */
 export function query(options) {
-    const { startDate, endDate = new Date(), eventTypes, agent, command, limit } = options;
+    const { startDate, endDate = new Date(), eventTypes, agent, command, module, limit } = options;
     const results = [];
     if (!fs.existsSync(LOGS_DIR))
         return results;
@@ -410,26 +445,50 @@ export function query(options) {
         .filter(f => f.startsWith('events-') && f.endsWith('.jsonl'))
         .sort()
         .reverse();
+    // Coarse file skip works on whole days, so floor the bounds to midnight —
+    // otherwise a sub-day window (`--since 2h` at 15:00 → startDate 13:00) would
+    // drop *today's* file, whose date stamps to 00:00. Precise filtering below is
+    // per-record on `ts`.
+    const startDay = startDate
+        ? new Date(startDate.getFullYear(), startDate.getMonth(), startDate.getDate())
+        : undefined;
+    const endDay = endDate
+        ? new Date(endDate.getFullYear(), endDate.getMonth(), endDate.getDate())
+        : undefined;
+    const startMs = startDate?.getTime();
+    const endMs = endDate?.getTime();
     for (const file of files) {
         const match = file.match(/^events-(\d{4})-(\d{2})-(\d{2})\.jsonl$/);
         if (!match)
             continue;
         const [, yyyy, mm, dd] = match;
         const fileDate = new Date(parseInt(yyyy), parseInt(mm) - 1, parseInt(dd));
-        if (startDate && fileDate < startDate)
+        if (startDay && fileDate < startDay)
             continue;
-        if (endDate && fileDate > endDate)
+        if (endDay && fileDate > endDay)
             continue;
         const content = fs.readFileSync(path.join(LOGS_DIR, file), 'utf-8');
         const lines = content.trim().split('\n').filter(Boolean);
         for (const line of lines.reverse()) {
             try {
                 const record = JSON.parse(line);
+                // Precise per-record window — the file skip above is day-granular only.
+                const recMs = Date.parse(record.ts);
+                if (startMs !== undefined && !isNaN(recMs) && recMs < startMs)
+                    continue;
+                if (endMs !== undefined && !isNaN(recMs) && recMs > endMs)
+                    continue;
                 if (eventTypes && !eventTypes.includes(record.event))
                     continue;
                 if (agent && record.agent !== agent)
                     continue;
-                if (command && record.command !== command)
+                // `--command` matches by path prefix on a word boundary, so a coarse
+                // "teams" catches "teams create"/"teams remove" while an exact
+                // "teams create" stays exact.
+                if (command && record.command !== command &&
+                    !(typeof record.command === 'string' && record.command.startsWith(command + ' ')))
+                    continue;
+                if (module && record.module !== module)
                     continue;
                 results.push(record);
                 if (limit && results.length >= limit) {

package/dist/lib/exec.d.ts

@@ -189,6 +189,21 @@ export declare function nativeResume(agent: AgentId): boolean;
 export declare function buildExecCommand(options: ExecOptions): string[];
 /** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */
 export declare function execAgent(options: ExecOptions): Promise<number>;
+/**
+ * Resolve how to spawn a shim target for a platform. Pure — testable on any host.
+ *
+ * POSIX always execs the binary directly (no shell). On Windows a bare
+ * (non-absolute) name or a `.cmd` companion goes through the shell so cmd.exe
+ * resolves it via PATHEXT — the common, `.cmd`-present path; an absolute `.cmd`
+ * or extensionless path is exec'd through the shell / directly. npm always ships
+ * a `<cmd>.cmd` companion on Windows, so the runnable target `execShimPassthrough`
+ * hands us is the `.cmd` (never a bare `.ps1`).
+ */
+export declare function resolveShimSpawn(platform: NodeJS.Platform, binary: string, extraArgs: string[]): {
+    command: string;
+    args: string[];
+    shell: boolean;
+};
 /**
  * Transparent passthrough exec for generated shims — the node-side delegate that
  * Windows `.cmd` shims call. Resolves the active version (explicit pin, else

package/dist/lib/exec.js

@@ -16,6 +16,7 @@ import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { getShimsDir } from './state.js';
+import { writePidSessionEntry } from './session/pid-registry.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -374,15 +375,6 @@ export const AGENT_COMMANDS = {
             edit: [],
         },
     },
-    roo: {
-        base: ['roo'],
-        promptFlag: 'positional',
-        modeFlags: {
-            plan: ['--mode', 'architect'],
-            edit: ['--mode', 'code'],
-        },
-        modelFlag: '--model',
-    },
     // TODO: --output-format json is documented but currently broken upstream
     // ("flags provided but not defined: -output-format"). Track resolution at
     // https://github.com/google-antigravity/antigravity-cli/issues/7 before
@@ -665,6 +657,25 @@ export async function execAgent(options) {
     const { exitCode } = await spawnAgent(options);
     return exitCode;
 }
+/**
+ * Resolve how to spawn a shim target for a platform. Pure — testable on any host.
+ *
+ * POSIX always execs the binary directly (no shell). On Windows a bare
+ * (non-absolute) name or a `.cmd` companion goes through the shell so cmd.exe
+ * resolves it via PATHEXT — the common, `.cmd`-present path; an absolute `.cmd`
+ * or extensionless path is exec'd through the shell / directly. npm always ships
+ * a `<cmd>.cmd` companion on Windows, so the runnable target `execShimPassthrough`
+ * hands us is the `.cmd` (never a bare `.ps1`).
+ */
+export function resolveShimSpawn(platform, binary, extraArgs) {
+    if (platform === 'win32') {
+        // Use win32 path semantics regardless of the host running this (the platform
+        // is the parameter, not process.platform) so `C:\...` reads as absolute.
+        const useShell = !path.win32.isAbsolute(binary) || binary.endsWith('.cmd');
+        return { command: binary, args: extraArgs, shell: useShell };
+    }
+    return { command: binary, args: extraArgs, shell: false };
+}
 /**
  * Transparent passthrough exec for generated shims — the node-side delegate that
  * Windows `.cmd` shims call. Resolves the active version (explicit pin, else
@@ -691,9 +702,9 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     // mode/effort are required by ExecOptions but unused by buildExecEnv (which only
     // derives the per-version config-dir env); pass the agent's default to satisfy the type.
     const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto' });
-    const useShell = process.platform === 'win32' && (!path.isAbsolute(binary) || binary.endsWith('.cmd'));
+    const { command, args, shell } = resolveShimSpawn(process.platform, binary, [...launchArgs, ...rawArgs]);
     return new Promise((resolve) => {
-        const child = spawn(binary, [...launchArgs, ...rawArgs], { cwd, stdio: 'inherit', env, shell: useShell });
+        const child = spawn(command, args, { cwd, stdio: 'inherit', env, shell });
         child.on('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
         child.on('error', (err) => {
             process.stderr.write(`agents: failed to launch ${agent}: ${err.message}\n`);
@@ -712,6 +723,15 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
  * unbuffered.
  */
 async function spawnAgent(options) {
+    // Assign a known session id up front for agents that accept one, so the
+    // launcher can record an EXACT pid -> session mapping (see pid-registry) —
+    // otherwise the headless `ag sessions --active` path can only guess
+    // "newest .jsonl in the cwd" and collapses co-located agents onto one row.
+    // Claude: `--session-id <uuid>` CREATES the session with that id (wired in
+    // buildExecCommand). Skip on resume — the id is the one being resumed.
+    if (options.agent === 'claude' && !options.resume && !options.sessionId) {
+        options = { ...options, sessionId: randomUUID() };
+    }
     const cmd = buildExecCommand(options);
     const [executable, ...args] = cmd;
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;
@@ -760,6 +780,18 @@ async function spawnAgent(options) {
             env: buildExecEnv(options),
             shell: useShell,
         });
+        // Record this launch so `ag sessions --active` can map the pid to its exact
+        // session (sessionId is set for Claude above) instead of guessing the newest
+        // .jsonl in the cwd — the collapse that made co-located agents indistinguishable.
+        // Best-effort: pruned when the pid dies; a failed write just degrades to the heuristic.
+        writePidSessionEntry({
+            pid: child.pid ?? 0,
+            agent: options.agent,
+            sessionId: options.sessionId,
+            cwd: options.cwd || process.cwd(),
+            tmuxPane: process.env.TMUX_PANE,
+            startedAtMs: Date.now(),
+        });
         // Mark startup time (time from function call to process spawn)
         timer.mark('startup');
         let budgetKilled = false;

package/dist/lib/hooks.js

@@ -910,6 +910,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 +959,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)) {

package/dist/lib/hosts/dispatch.js

@@ -12,7 +12,7 @@ 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 { 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
@@ -61,12 +61,11 @@ 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 };
 }
 /** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
 export async function dispatchToHost(host, opts) {

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>;

package/dist/lib/hosts/logs.js

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+import * as fs from 'fs';
+import chalk from 'chalk';
+import { loadTask, localLogPath, updateTask, terminalPatch } from './tasks.js';
+import { followHostTask } from './progress.js';
+import { reconcileTask } from './reconcile.js';
+/** Show (or follow, when running) a dispatched host task's combined-stdout log. */
+export async function showHostTaskLog(id, follow) {
+    const task = loadTask(id);
+    if (!task)
+        return { found: false };
+    if (follow && task.status === 'running') {
+        const code = await followHostTask(task.target, {
+            remoteLog: task.remoteLog,
+            remoteExit: task.remoteExit,
+            taskId: id,
+            echo: true,
+        });
+        // -1 = follow window closed; the run continues on the host (not a failure,
+        // so exit 0). Any real code is the finished run — persist the terminal
+        // status the killed dispatch follower would have written.
+        if (code === -1)
+            return { found: true, exitCode: 0 };
+        updateTask(id, terminalPatch(code));
+        return { found: true, exitCode: code };
+    }
+    // Non-follow view: heal a still-'running' record from the remote `.exit` so a
+    // plain `logs <id>` also unsticks a task whose follower was killed. No-op (no
+    // ssh) once the record is already terminal.
+    reconcileTask(task);
+    try {
+        process.stdout.write(fs.readFileSync(localLogPath(id), 'utf-8'));
+    }
+    catch {
+        console.log(chalk.gray('(no local log captured for this task)'));
+    }
+    return { found: true, exitCode: 0 };
+}