@phnx-labs/agents-cli 1.20.34 → 1.20.35

package/dist/lib/daemon.js

@@ -538,14 +538,42 @@ export function buildDetachedDaemonEnv(baseEnv = process.env) {
     }
     return env;
 }
-function startDetached() {
-    const agentsBin = getAgentsBinPath();
-    const logPath = getLogPath();
+/**
+ * Resolve how to launch the daemon: `node <entry> daemon _run`, matching the
+ * exact form that works under a direct `daemon _run`.
+ *
+ * We spawn the Node runtime (`process.execPath`) with the CLI entry as an
+ * argument rather than executing the entry path directly. Executing the `.js`
+ * path relies on its shebang on POSIX, and on Windows CreateProcess can't run a
+ * `.js`/shim directly at all — it gets launched through a transient
+ * console-owning wrapper (cmd.exe / the npm shim). When that wrapper exits it
+ * closes its console, and the detached daemon sharing that console receives a
+ * console-close event that trips its shutdown handler — the daemon comes up,
+ * binds the browser IPC socket, then tears itself down ~36ms later (#556).
+ * Going through `process.execPath` means a real PE/binary is spawned with
+ * `detached: true` and no console, so nothing signals the daemon after launch.
+ *
+ * When the entry isn't a JS file (e.g. a native launcher resolved via
+ * `which agents`), run it directly — it owns its own runtime resolution.
+ */
+export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
+    if (/\.(c|m)?js$/.test(agentsBin)) {
+        return { command: process.execPath, args: [agentsBin, 'daemon', '_run'] };
+    }
+    return { command: agentsBin, args: ['daemon', '_run'] };
+}
+export function startDetached(opts = {}) {
+    const agentsBin = opts.agentsBin ?? getAgentsBinPath();
+    const logPath = opts.logPath ?? getLogPath();
     const logFd = fs.openSync(logPath, 'a');
-    const child = spawn(agentsBin, ['daemon', '_run'], {
+    const { command, args } = getDaemonLaunch(agentsBin);
+    const child = spawn(command, args, {
         stdio: ['ignore', logFd, logFd],
         detached: true,
-        env: buildDetachedDaemonEnv(),
+        // No console window on Windows — a hidden, consoleless process can't be
+        // torn down by a console-close event when its launcher exits (#556).
+        windowsHide: true,
+        env: opts.env ?? buildDetachedDaemonEnv(),
     });
     child.unref();
     fs.closeSync(logFd);

package/dist/lib/devices/connect.d.ts

@@ -11,8 +11,9 @@ export declare function sshTargetFor(device: DeviceProfile): string;
 /**
  * Wrap a remote command for the device's shell. Windows devices speak
  * PowerShell, so a bare command is run through `powershell -NoProfile
- * -Command`; POSIX devices get the command verbatim (the remote login shell
- * parses it). Returns undefined when no command was given (interactive login).
+ * -EncodedCommand`; POSIX devices get the command verbatim (the remote login
+ * shell parses it). Returns undefined when no command was given (interactive
+ * login).
  */
 export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[]): string | undefined;
 /**

package/dist/lib/devices/connect.js

@@ -16,6 +16,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { encodePwshBase64 } from '../pwsh.js';
 import { getCacheDir } from '../state.js';
 import { hostNameFor } from './ssh-config.js';
 /** Env var the askpass shim reads to know which bundle holds the password. */
@@ -38,15 +39,16 @@ export function sshTargetFor(device) {
 /**
  * Wrap a remote command for the device's shell. Windows devices speak
  * PowerShell, so a bare command is run through `powershell -NoProfile
- * -Command`; POSIX devices get the command verbatim (the remote login shell
- * parses it). Returns undefined when no command was given (interactive login).
+ * -EncodedCommand`; POSIX devices get the command verbatim (the remote login
+ * shell parses it). Returns undefined when no command was given (interactive
+ * login).
  */
 export function wrapRemoteCommand(device, cmd) {
     if (cmd.length === 0)
         return undefined;
     const joined = cmd.join(' ');
     if (device.shell === 'powershell') {
-        return `powershell -NoProfile -Command ${shellQuote(joined)}`;
+        return `powershell -NoProfile -EncodedCommand ${encodePwshBase64(joined)}`;
     }
     return joined;
 }

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.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.
  *
@@ -722,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;
@@ -770,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 };
+}

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

@@ -5,6 +5,13 @@
  * a sibling `.exit` file. We poll `tail -c +<offset>` (durable, offset-tracked —
  * a dropped connection resumes from the saved offset) and finish when `.exit`
  * appears. Rich transcript-parser rendering is a fast-follow.
+ *
+ * Efficiency: each cycle is a SINGLE ssh round-trip that returns the new log
+ * bytes, a per-task sentinel, then the exit-file contents — half the process +
+ * handshake cost of the old tail-then-cat pair. It rides the default control
+ * socket (multiplex on) that the launch opened, and eases the poll interval off
+ * toward `maxPollMs` while the job is idle, so a quiet long-running follow no
+ * longer spawns thousands of ssh processes per hour on the laptop.
  */
 export interface FollowOptions {
     remoteLog: string;
@@ -15,7 +22,66 @@ export interface FollowOptions {
     echo?: boolean;
     /** Overall wall-clock cap; returns -1 on timeout. */
     timeoutMs?: number;
+    /** Fast poll interval while output is flowing (default 1500ms). */
     pollMs?: number;
+    /** Idle-backoff ceiling (default 4× the fast interval, min 4000ms). */
+    maxPollMs?: number;
 }
+/**
+ * Build the per-task sentinel that separates the log tail from the exit-file
+ * contents in one combined fetch. The task id (8 hex chars) makes collision with
+ * the agent's own output effectively impossible; callers still split on the LAST
+ * occurrence so a token echoed into the log can never be mistaken for the real
+ * trailing marker.
+ */
+export declare function exitMarker(taskId: string): string;
+/**
+ * Split a combined fetch (`<log bytes><marker><exit>`) back into its parts at the
+ * BYTE level. Splits on the LAST marker occurrence, so even if the agent's own
+ * output happened to echo the token, the real trailing sentinel still wins.
+ * Returns null when the marker is absent (a transient fetch miss — the remote
+ * shell never ran our printf), telling the caller to retry without advancing.
+ *
+ * Byte-level (not string) is load-bearing: `logChunk.length` is the EXACT number
+ * of log bytes consumed on the wire, which the follow loop adds to its offset. A
+ * string split would first UTF-8-decode, turning any multibyte char split at the
+ * `tail -c` boundary into a U+FFFD whose re-encoded length ≠ the wire bytes,
+ * drifting the offset (see followHostTask). `consumed` is returned explicitly for
+ * clarity; it always equals `logChunk.length`.
+ */
+export declare function splitProgressBytes(buf: Buffer, taskId: string): {
+    logChunk: Buffer;
+    exit: Buffer;
+    consumed: number;
+} | null;
+/**
+ * One round-trip: new log bytes since `offset`, the sentinel, then the exit
+ * file. Returns null on a transient fetch miss (ssh error / marker absent) so
+ * the caller simply retries next cycle without advancing the offset.
+ *
+ * `remoteLog`/`remoteExit` are $HOME-prefixed paths with safe (hex) basenames —
+ * intentionally unquoted so the remote shell expands $HOME.
+ */
+export declare function fetchProgress(target: string, opts: {
+    remoteLog: string;
+    remoteExit: string;
+    taskId: string;
+    offset: number;
+}): {
+    logChunk: Buffer;
+    exit: string;
+} | null;
+/**
+ * File identity (`dev:ino`) of a path on the remote host, or null if it can't be
+ * stat'd. GNU (`-c`) then BSD (`-f`) format, so it works on Linux and macOS hosts.
+ */
+export declare function readRemoteFileId(target: string, remotePath: string): string | null;
+/**
+ * True when the local mirror file IS the very file we're tailing — the
+ * localhost-as-host case, where `remoteLog` ($HOME-expanded) and `localLogPath`
+ * resolve to the same inode. Appending our read bytes back into it would feed the
+ * tail and multiply the log, so the caller must skip the mirror write.
+ */
+export declare function mirrorAliasesSource(localId: string | null, remoteId: string | null): boolean;
 /** Tail the remote log to stdout until the run finishes; return its exit code. */
 export declare function followHostTask(target: string, opts: FollowOptions): Promise<number>;