@phnx-labs/agents-cli 1.20.35 → 1.20.37

package/dist/lib/session/provenance.js

@@ -15,9 +15,22 @@
  * (gone, or owned by another uid) yields `undefined`, never a guess.
  *
  * `reply` is a read-only hint, not a send channel: it reports whether a rail
- * that can type back into this session exists today (tmux pane => addressable;
- * inherited/ignored stdin => null). The feed uses it to decide whether to show
- * a Send box. Actually delivering the keystrokes is Gap 2 (pty/tmux send-keys).
+ * that can type back into this session exists today and, if so, the exact
+ * address to type into. Two env-derived rails, in precedence order:
+ *
+ *   - tmux  — `$TMUX_PANE` (+ `$TMUX` socket): `tmux send-keys -t <pane>`. Works
+ *             inside ANY host app (a tmux pane can live under iTerm/Ghostty/VS
+ *             Code), so it wins whenever present.
+ *   - iterm — `$ITERM_SESSION_ID` (`w<n>t<n>p<n>:<UUID>`): the exact iTerm2
+ *             split, addressable by its session UUID via `tell session id …`
+ *             (focus-safe, no `activate`). Used when there's no tmux above it.
+ *
+ * Both are inherited env vars, so the split the agent lives in is recovered with
+ * zero cooperation from the agent. Inherited/ignored stdin with neither rail =>
+ * null (not env-addressable — resolution may still find an IDE rail off disk,
+ * see src/lib/terminal/resolve.ts). The feed uses `reply` to decide whether to
+ * show a Send box; the resolver turns it into a concrete inject target (Gap 2,
+ * src/lib/terminal/inject.ts).
  */
 import * as os from 'os';
 import { execFile } from 'child_process';
@@ -32,7 +45,20 @@ export const PROVENANCE_ENV_KEYS = [
     'TMUX_PANE',
     'TERM_PROGRAM',
     'STY',
+    'ITERM_SESSION_ID',
 ];
+/**
+ * Extract the iTerm2 session UUID from `$ITERM_SESSION_ID`, whose value is
+ * `w<window>t<tab>p<pane>:<UUID>` — the `:`-suffix is exactly what iTerm2's
+ * `id of session` returns, so it's the address for `tell session id …`. Returns
+ * undefined for an empty/absent value; tolerates a bare value with no `:`.
+ */
+export function parseItermSession(value) {
+    if (!value)
+        return undefined;
+    const uuid = value.includes(':') ? value.slice(value.lastIndexOf(':') + 1) : value;
+    return uuid.trim() || undefined;
+}
 /** Parse the NUL-separated body of /proc/<pid>/environ into a plain object. */
 export function parseProcEnviron(buf) {
     const env = {};
@@ -99,13 +125,18 @@ export function deriveProvenance(env, hostname) {
     else if (env.STY) {
         mux = { kind: 'screen', session: env.STY };
     }
-    // A tmux pane is the one rail that lets an external process type into an
-    // already-running interactive agent (`tmux send-keys -t <pane>`). Everything
-    // else (inherited stdin from `agents run`, ignored stdin from teams) is not
-    // externally addressable without relaunching under a pty/tmux rail.
+    // Env-addressable rails, in precedence order. A tmux pane wins because it can
+    // live inside any host app (`tmux send-keys -t <pane>` reaches it regardless of
+    // whether iTerm/Ghostty/VS Code is above it). Absent tmux, an iTerm2 split is
+    // addressable by its session UUID. Everything else (inherited stdin from
+    // `agents run`, ignored stdin from teams, a plain VS Code integrated terminal)
+    // is not env-addressable — the resolver may still find an IDE rail off disk.
+    const itermSession = parseItermSession(env.ITERM_SESSION_ID);
     const reply = mux?.kind === 'tmux' && mux.pane
         ? { rail: 'tmux', target: mux.pane, socket: mux.socket }
-        : null;
+        : itermSession
+            ? { rail: 'iterm', session: itermSession }
+            : null;
     return {
         host: hostname,
         transport: ssh ? 'ssh' : 'local',

package/dist/lib/session/relative-time.js

@@ -21,8 +21,12 @@ export function formatRelativeTime(isoTimestamp) {
         return `${diffHrs} hour${diffHrs === 1 ? '' : 's'} ago`;
     if (diffDays < 7)
         return `${diffDays} day${diffDays === 1 ? '' : 's'} ago`;
-    // Older: show date
+    // Older: show the date. Append a 2-digit year for anything outside the current
+    // year so "Jun 28" is never ambiguous across years (e.g. "Jun 28 '25").
     const d = new Date(then);
     const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
-    return `${months[d.getMonth()]} ${d.getDate()}`;
+    const label = `${months[d.getMonth()]} ${d.getDate()}`;
+    return d.getFullYear() === new Date(now).getFullYear()
+        ? label
+        : `${label} '${String(d.getFullYear()).slice(-2)}`;
 }

package/dist/lib/session/remote-active.js

@@ -18,7 +18,9 @@ import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from '../devices/connect.js';
+import { resolveExplicitTargets } from '../devices/resolve-target.js';
 import { loadDevices } from '../devices/registry.js';
+import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
 import { machineId, normalizeHost } from './sync/config.js';
 /** Per-host SSH budget. Slightly above SSH_OPTS' ConnectTimeout=10 so a
  * reachable-but-slow remote still answers before we give up. */
@@ -29,8 +31,16 @@ const REMOTE_TIMEOUT_MS = 12_000;
  * on an unknown option. A remote new enough to fan out reads it and stays local.
  */
 export const NO_FANOUT_ENV = 'AGENTS_SESSIONS_LOCAL';
-/** The command run on each peer: answer for itself, as JSON, without recursing. */
-function remoteActiveCommand() {
+/** The command run on each peer: answer for itself, as JSON, without recursing.
+ * A Windows peer gets a PowerShell invocation (ssh lands in cmd.exe/PowerShell
+ * there, where `bash -lc` is not a command); every other OS keeps `bash -lc`. */
+function remoteActiveCommand(os) {
+    if (remoteShellFor(os) === 'powershell') {
+        return buildWindowsAgentsCommand({
+            args: ['sessions', '--active', '--json'],
+            env: { [NO_FANOUT_ENV]: '1' },
+        });
+    }
     const inner = `${NO_FANOUT_ENV}=1 agents sessions --active --json`;
     return `bash -lc ${shellQuote(inner)}`;
 }
@@ -80,8 +90,8 @@ function sshCapture(target, remoteCmd, timeoutMs) {
         child.on('close', (code) => done(code));
     });
 }
-async function fetchByTarget(target, machine, display) {
-    const { code, stdout } = await sshCapture(target, remoteActiveCommand(), REMOTE_TIMEOUT_MS);
+async function fetchByTarget(target, machine, display, os) {
+    const { code, stdout } = await sshCapture(target, remoteActiveCommand(os), REMOTE_TIMEOUT_MS);
     if (code !== 0) {
         process.stderr.write(chalk.gray(`  ${display}: unreachable or no agents CLI — skipped\n`));
         return [];
@@ -98,17 +108,9 @@ export async function gatherRemoteActive(hosts) {
     const self = machineId();
     const targets = [];
     if (hosts && hosts.length > 0) {
-        for (const h of hosts) {
-            try {
-                assertValidSshTarget(h);
-            }
-            catch {
-                process.stderr.write(chalk.gray(`  ${h}: not a valid ssh target — skipped\n`));
-                continue;
-            }
-            const bareHost = h.split('@').pop() || h;
-            targets.push({ target: h, machine: normalizeHost(bareHost), name: h });
-        }
+        // Resolve each token through the device registry so an explicit --host/--device
+        // dials the exact same address (and machine id) as the auto-discovery sweep.
+        targets.push(...await resolveExplicitTargets(hosts));
     }
     else {
         let reg;
@@ -129,13 +131,13 @@ export async function gatherRemoteActive(hosts) {
             if (d.platform !== 'windows' && d.platform !== 'linux' && d.platform !== 'macos')
                 continue;
             try {
-                targets.push({ target: sshTargetFor(d), machine: normalizeHost(d.name), name: d.name });
+                targets.push({ target: sshTargetFor(d), machine: normalizeHost(d.name), name: d.name, os: d.platform });
             }
             catch {
                 // No address on the profile — nothing to dial; skip silently.
             }
         }
     }
-    const results = await Promise.all(targets.map((t) => fetchByTarget(t.target, t.machine, t.name)));
+    const results = await Promise.all(targets.map((t) => fetchByTarget(t.target, t.machine, t.name, t.os)));
     return { sessions: results.flat(), deviceCount: targets.length };
 }

package/dist/lib/session/remote-list.d.ts

@@ -0,0 +1,51 @@
+import type { SessionMeta } from './types.js';
+/**
+ * The command run on each peer: answer for itself, as JSON, without recursing.
+ * `forwardedArgs` carry the caller's own query/filters (already including the
+ * leading `sessions` and a `--json`) so each peer returns a comparable slice.
+ * A Windows peer gets a PowerShell invocation (ssh lands in cmd.exe/PowerShell
+ * there, where `bash -lc` is not a command); every other OS keeps `bash -lc`.
+ */
+export declare function remoteListCommand(forwardedArgs: string[], os?: string): string;
+/**
+ * Parse a peer's `sessions --json` stdout into `SessionMeta[]`, tagging each
+ * with `machine`. Defensive against version skew / partial output: non-JSON or
+ * a non-array yields `[]`, and non-object entries are dropped rather than
+ * throwing. The `machine` we dialed always wins over any value the peer set on
+ * its own rows, so grouping keys off the computer we asked. Exported for unit
+ * testing without a live tailnet.
+ */
+export declare function parseRemoteList(stdout: string, machine: string): SessionMeta[];
+export interface RemoteListResult {
+    sessions: SessionMeta[];
+    /** How many peer machines we attempted to reach (drives the empty-fleet tip). */
+    deviceCount: number;
+}
+/**
+ * Gather listing sessions from other machines. With an explicit `hosts` list
+ * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
+ * online devices from `ag devices`, excluding this machine and any without an
+ * address. `forwardedArgs` are the caller's own sessions args (query + filters,
+ * already `--json`) so every peer returns the same slice this machine asked for.
+ */
+export declare function gatherRemoteList(forwardedArgs: string[], hosts?: string[]): Promise<RemoteListResult>;
+/** Resolve a peer's SSH target (and OS) from the device registry by its
+ * normalized machine id — the same id the fan-out tags rows with. Returns
+ * undefined when no registered device with an address matches. */
+export declare function resolvePeerTarget(machine: string): Promise<{
+    target: string;
+    os?: string;
+} | undefined>;
+/**
+ * Run `agents <args>` ON a peer over SSH, attached to this terminal (inherited
+ * stdio). `args` is the full arg vector after the binary — callers pass e.g.
+ * `['sessions', id, '--markdown']` or `['sessions', 'resume', id]`. Used when a
+ * picked session lives on another machine: its transcript and agent binary are
+ * there, so both reading (no TTY) and resuming (TTY) must execute on the peer —
+ * not via a local `--host` hop, which would discover locally and dead-end for a
+ * session that exists only on the peer. Resolves 'no-target' when the machine
+ * isn't a dialable registered device; the caller surfaces a clear message.
+ */
+export declare function runOnPeer(args: string[], machine: string, opts?: {
+    tty?: boolean;
+}): Promise<'ok' | 'no-target'>;

package/dist/lib/session/remote-list.js

@@ -0,0 +1,205 @@
+/**
+ * Cross-machine fan-out for the default `agents sessions` listing.
+ *
+ * `discoverSessions()` only scans the local disk. To browse the whole fleet in
+ * one list — without syncing anything — we run `agents sessions <same query>
+ * --json` on each peer over SSH and merge the parsed `SessionMeta[]`, tagging
+ * every row with the machine it came from so the picker/table can label and
+ * group by computer.
+ *
+ * This is the browse-listing sibling of `remote-active.ts` (which fans out
+ * `--active`): same transport, same device set, same recursion guard. The peer
+ * runs with `AGENTS_SESSIONS_LOCAL=1` so it answers only for itself and the
+ * sweep never recurses. A dead or slow host is skipped with a stderr note,
+ * never fatal — one asleep laptop must not blank the list.
+ */
+import { spawn } from 'child_process';
+import chalk from 'chalk';
+import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { sshTargetFor } from '../devices/connect.js';
+import { resolveExplicitTargets } from '../devices/resolve-target.js';
+import { loadDevices } from '../devices/registry.js';
+import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
+import { machineId, normalizeHost } from './sync/config.js';
+import { NO_FANOUT_ENV } from './remote-active.js';
+import { terminalWidth } from './width.js';
+/** Per-host SSH budget. Slightly above SSH_OPTS' ConnectTimeout=10 so a
+ * reachable-but-slow remote still answers before we give up. */
+const REMOTE_TIMEOUT_MS = 12_000;
+/**
+ * The command run on each peer: answer for itself, as JSON, without recursing.
+ * `forwardedArgs` carry the caller's own query/filters (already including the
+ * leading `sessions` and a `--json`) so each peer returns a comparable slice.
+ * A Windows peer gets a PowerShell invocation (ssh lands in cmd.exe/PowerShell
+ * there, where `bash -lc` is not a command); every other OS keeps `bash -lc`.
+ */
+export function remoteListCommand(forwardedArgs, os) {
+    if (remoteShellFor(os) === 'powershell') {
+        return buildWindowsAgentsCommand({
+            args: forwardedArgs,
+            env: { [NO_FANOUT_ENV]: '1' },
+        });
+    }
+    const inner = [`${NO_FANOUT_ENV}=1`, 'agents', ...forwardedArgs].map((t, i) => i === 0 ? t : shellQuote(t)).join(' ');
+    return `bash -lc ${shellQuote(inner)}`;
+}
+/**
+ * Parse a peer's `sessions --json` stdout into `SessionMeta[]`, tagging each
+ * with `machine`. Defensive against version skew / partial output: non-JSON or
+ * a non-array yields `[]`, and non-object entries are dropped rather than
+ * throwing. The `machine` we dialed always wins over any value the peer set on
+ * its own rows, so grouping keys off the computer we asked. Exported for unit
+ * testing without a live tailnet.
+ */
+export function parseRemoteList(stdout, machine) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const out = [];
+    for (const x of parsed) {
+        if (x && typeof x === 'object' && !Array.isArray(x)) {
+            // `_remote` marks these as living on the peer's disk (not a local mirror),
+            // so the picker routes read/resume back over SSH instead of the local FS.
+            out.push({ ...x, machine, _remote: true });
+        }
+    }
+    return out;
+}
+/** Run one remote `agents sessions … --json` and capture stdout. Resolves
+ * `{ code: null }` on spawn error or timeout (host treated as dead). */
+function sshCapture(target, remoteCmd, timeoutMs) {
+    assertValidSshTarget(target);
+    return new Promise((resolve) => {
+        const args = [...SSH_OPTS, ...controlOpts(), target, remoteCmd];
+        const child = spawn('ssh', args, { stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        let settled = false;
+        const done = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ code, stdout });
+        };
+        const timer = setTimeout(() => { child.kill('SIGKILL'); done(null); }, timeoutMs);
+        child.stdout.on('data', (d) => { stdout += d.toString(); });
+        child.on('error', () => done(null));
+        child.on('close', (code) => done(code));
+    });
+}
+async function fetchByTarget(target, machine, display, forwardedArgs, os) {
+    const { code, stdout } = await sshCapture(target, remoteListCommand(forwardedArgs, os), REMOTE_TIMEOUT_MS);
+    if (code !== 0) {
+        process.stderr.write(chalk.gray(`  ${display}: unreachable or no agents CLI — skipped\n`));
+        return [];
+    }
+    return parseRemoteList(stdout, machine);
+}
+/**
+ * Gather listing sessions from other machines. With an explicit `hosts` list
+ * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
+ * online devices from `ag devices`, excluding this machine and any without an
+ * address. `forwardedArgs` are the caller's own sessions args (query + filters,
+ * already `--json`) so every peer returns the same slice this machine asked for.
+ */
+export async function gatherRemoteList(forwardedArgs, hosts) {
+    const self = machineId();
+    const targets = [];
+    if (hosts && hosts.length > 0) {
+        // Resolve each token through the device registry so an explicit --host/--device
+        // dials the exact same address (and machine id) as the auto-discovery sweep.
+        targets.push(...await resolveExplicitTargets(hosts));
+    }
+    else {
+        let reg;
+        try {
+            reg = await loadDevices();
+        }
+        catch {
+            return { sessions: [], deviceCount: 0 };
+        }
+        for (const d of Object.values(reg)) {
+            if (d.tailscale?.online !== true)
+                continue;
+            if (normalizeHost(d.name) === self)
+                continue;
+            // Only machines that can actually run the CLI. iOS/tablet nodes register as
+            // `unknown` platform and can never answer, so skip them rather than burn a
+            // full ConnectTimeout on each.
+            if (d.platform !== 'windows' && d.platform !== 'linux' && d.platform !== 'macos')
+                continue;
+            try {
+                targets.push({ target: sshTargetFor(d), machine: normalizeHost(d.name), name: d.name, os: d.platform });
+            }
+            catch {
+                // No address on the profile — nothing to dial; skip silently.
+            }
+        }
+    }
+    const results = await Promise.all(targets.map((t) => fetchByTarget(t.target, t.machine, t.name, forwardedArgs, t.os)));
+    return { sessions: results.flat(), deviceCount: targets.length };
+}
+/** Resolve a peer's SSH target (and OS) from the device registry by its
+ * normalized machine id — the same id the fan-out tags rows with. Returns
+ * undefined when no registered device with an address matches. */
+export async function resolvePeerTarget(machine) {
+    let reg;
+    try {
+        reg = await loadDevices();
+    }
+    catch {
+        return undefined;
+    }
+    for (const d of Object.values(reg)) {
+        if (normalizeHost(d.name) !== machine)
+            continue;
+        try {
+            return { target: sshTargetFor(d), os: d.platform };
+        }
+        catch {
+            return undefined; // matched the machine, but it has no address to dial
+        }
+    }
+    return undefined;
+}
+/**
+ * Run `agents <args>` ON a peer over SSH, attached to this terminal (inherited
+ * stdio). `args` is the full arg vector after the binary — callers pass e.g.
+ * `['sessions', id, '--markdown']` or `['sessions', 'resume', id]`. Used when a
+ * picked session lives on another machine: its transcript and agent binary are
+ * there, so both reading (no TTY) and resuming (TTY) must execute on the peer —
+ * not via a local `--host` hop, which would discover locally and dead-end for a
+ * session that exists only on the peer. Resolves 'no-target' when the machine
+ * isn't a dialable registered device; the caller surfaces a clear message.
+ */
+export async function runOnPeer(args, machine, opts = {}) {
+    const peer = await resolvePeerTarget(machine);
+    if (!peer)
+        return 'no-target';
+    assertValidSshTarget(peer.target); // registry-sourced, but validate like the fan-out does
+    const cols = terminalWidth();
+    const remoteCmd = remoteShellFor(peer.os) === 'powershell'
+        ? buildWindowsAgentsCommand({ args, env: cols > 0 ? { COLUMNS: String(cols) } : undefined })
+        : `bash -lc ${shellQuote((cols > 0 ? [`COLUMNS=${cols}`] : []).concat(['agents', ...args].map(shellQuote)).join(' '))}`;
+    const sshArgs = [...SSH_OPTS, ...controlOpts()];
+    if (opts.tty)
+        sshArgs.push('-tt'); // force a PTY so the resumed agent is interactive
+    sshArgs.push(peer.target, remoteCmd);
+    return new Promise((resolve) => {
+        const child = spawn('ssh', sshArgs, { stdio: 'inherit' });
+        // ssh prints its own connection errors to the inherited stderr; a spawn
+        // failure (e.g. ssh not on PATH) has no such output, so name it. Either way
+        // we resolve once it settles so the picker flow completes.
+        child.on('error', (err) => {
+            process.stderr.write(chalk.red(`Failed to reach ${machine}: ${err?.message ?? 'ssh failed to launch'}\n`));
+            resolve('ok');
+        });
+        child.on('close', () => resolve('ok'));
+    });
+}

package/dist/lib/session/remote.d.ts

@@ -22,8 +22,14 @@ export declare function buildForwardedArgs(argv: string[], hosts?: Set<string>):
  * Build the single remote command string for `ssh <host> <cmd>`. Forwarded args
  * are quoted for the inner login shell, then the whole `agents …` invocation is
  * quoted again so it survives `bash -lc <...>`.
+ *
+ * `os` selects the remote shell: a Windows host gets a PowerShell invocation
+ * (ssh lands in cmd.exe/PowerShell there, where `bash -lc` does not exist);
+ * anything else — including unknown/absent — keeps the POSIX form unchanged.
+ * The forwarded terminal width rides across as an env var either way so the
+ * remote renders its table to the local screen.
  */
-export declare function buildRemoteCommand(forwardedArgs: string[], columns?: number): string;
+export declare function buildRemoteCommand(forwardedArgs: string[], columns?: number, os?: string): string;
 /** The four outcomes of one `ssh <host> agents sessions …` invocation. */
 export type SshOutcome = 'ok' | 'unreachable' | 'query-failed' | 'spawn-error';
 /**

package/dist/lib/session/remote.js

@@ -28,6 +28,8 @@ import { createHash } from 'crypto';
 import chalk from 'chalk';
 import { getCacheDir } from '../state.js';
 import { SSH_OPTS, controlOpts } from '../ssh-exec.js';
+import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
+import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 import { formatRelativeTime } from './relative-time.js';
 import { terminalWidth } from './width.js';
 /**
@@ -61,10 +63,12 @@ export function buildForwardedArgs(argv, hosts = new Set()) {
     const out = [];
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
-        if (a === '--host' || a === '-H') {
+        if (a === '--host' || a === '-H' || a === '--device') {
             // Commander's `<target...>` variadic accepts both `--host a --host b` and
             // `--host a b` — consume every consecutive token that is a known host so
             // the variadic form doesn't leak the extra hosts into the remote argv.
+            // `--device` is an alias for `--host` (its values are merged into the same
+            // host set), so strip it the same way — else the peer would re-fan-out.
             // Fall back to consuming the single next token when we have no host set
             // (e.g. malformed input) so the flag value never leaks either way.
             if (hosts.size > 0) {
@@ -76,7 +80,7 @@ export function buildForwardedArgs(argv, hosts = new Set()) {
             }
             continue;
         }
-        if (a.startsWith('--host=') || a.startsWith('-H='))
+        if (a.startsWith('--host=') || a.startsWith('-H=') || a.startsWith('--device='))
             continue;
         if (/^-H.+/.test(a))
             continue; // glued short form: -Hyosemite-s1
@@ -88,8 +92,18 @@ export function buildForwardedArgs(argv, hosts = new Set()) {
  * Build the single remote command string for `ssh <host> <cmd>`. Forwarded args
  * are quoted for the inner login shell, then the whole `agents …` invocation is
  * quoted again so it survives `bash -lc <...>`.
+ *
+ * `os` selects the remote shell: a Windows host gets a PowerShell invocation
+ * (ssh lands in cmd.exe/PowerShell there, where `bash -lc` does not exist);
+ * anything else — including unknown/absent — keeps the POSIX form unchanged.
+ * The forwarded terminal width rides across as an env var either way so the
+ * remote renders its table to the local screen.
  */
-export function buildRemoteCommand(forwardedArgs, columns) {
+export function buildRemoteCommand(forwardedArgs, columns, os) {
+    if (remoteShellFor(os) === 'powershell') {
+        const env = columns && columns > 0 ? { COLUMNS: String(columns) } : undefined;
+        return buildWindowsAgentsCommand({ args: forwardedArgs, env });
+    }
     const inner = ['agents', ...forwardedArgs].map(shellQuote).join(' ');
     // Forward the caller's terminal width so the remote renders the table to the
     // local screen (over SSH the remote's own COLUMNS is unset/wrong). `VAR=val
@@ -176,12 +190,14 @@ export function runRemoteSessions(hosts, argv = process.argv) {
     for (const host of hosts)
         assertValidSshTarget(host); // fail fast on any bad target
     const forwarded = buildForwardedArgs(argv, new Set(hosts));
-    const remoteCmd = buildRemoteCommand(forwarded, terminalWidth());
+    const cols = terminalWidth();
     const multi = hosts.length > 1;
     let failures = 0;
     for (const host of hosts) {
         if (multi)
             process.stdout.write(chalk.cyan(`\n── ${host} ──\n`));
+        // Per-host: a Windows peer needs a PowerShell command, POSIX peers `bash -lc`.
+        const remoteCmd = buildRemoteCommand(forwarded, cols, resolveRemoteOsSync(host));
         const res = spawnSync('ssh', [...SSH_OPTS, ...controlOpts(), host, remoteCmd], {
             encoding: 'utf8',
             maxBuffer: 64 * 1024 * 1024,

package/dist/lib/session/sync/config.d.ts

@@ -5,6 +5,19 @@
  */
 /** Secrets bundle holding the R2 credentials. */
 export declare const SYNC_BUNDLE = "r2.backups";
+/** Env var that overrides the persisted enable flag (on/off/true/false/1/0/yes/no). */
+export declare const SYNC_ENABLED_ENV = "AGENTS_SESSIONS_SYNC";
+/** Durable, machine-local path holding the sync enable flag. */
+export declare function syncStateFilePath(): string;
+/**
+ * Whether automatic session sync is enabled on this machine. Defaults to true;
+ * an unrecognized env value falls through to the file; an absent/unreadable file
+ * falls through to the default. Read fresh every call (no memoization) so a
+ * `--disable` takes effect on the daemon's next ~90s cycle without a restart.
+ */
+export declare function isSyncEnabled(): boolean;
+/** Persist the machine-local sync enable flag (durable across cache wipes). */
+export declare function setSyncEnabled(enabled: boolean): void;
 export interface R2Config {
     accountId: string;
     bucket: string;
@@ -33,18 +46,4 @@ export declare function loadR2Config(): R2Config;
  * does not re-storm every cycle. `now` is injectable for tests.
  */
 export declare function isSyncConfigured(now?: number): boolean;
-/**
- * Normalize a raw hostname into a stable device id: first label only,
- * lowercased, non-alphanumerics collapsed to hyphens. `zion.tail…ts.net` and
- * `ZION` both become `zion`. The single source for this transform — machineId()
- * and cross-machine session grouping must agree or the local machine won't
- * match its own registry key.
- */
-export declare function normalizeHost(raw: string): string;
-/**
- * This machine's stable, human-readable id, used as its R2 prefix and mirror
- * directory name. Tailnet hostnames (zion, yosemite-s0, mac-mini) are already
- * unique and readable; we lowercase and strip any domain suffix. Overridable
- * via AGENTS_SYNC_MACHINE_ID for tests and unusual setups.
- */
-export declare function machineId(): string;
+export { machineId, normalizeHost } from '../../machine-id.js';

package/dist/lib/session/sync/config.js

@@ -3,10 +3,65 @@
  * machine's stable identity. Credentials come from the `r2.backups` secrets
  * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
  */
-import * as os from 'os';
+import * as fs from 'fs';
+import * as path from 'path';
 import { readAndResolveBundleEnv } from '../../secrets/bundles.js';
+import { getHistoryDir } from '../../state.js';
 /** Secrets bundle holding the R2 credentials. */
 export const SYNC_BUNDLE = 'r2.backups';
+// ── Enable / disable switch ─────────────────────────────────────────────────
+// Whether the daemon's automatic cross-machine sync (and `agents sync
+// --sessions`) may run on THIS machine. Independent of credential presence
+// (isSyncConfigured): a machine can hold valid R2 creds yet still opt out of the
+// background push/pull — e.g. when on-demand `agents sessions --host` is
+// preferred over the ad-hoc R2 mirror. Manual `agents sessions sync` is an
+// explicit user action and is deliberately NOT gated by this switch.
+//
+// Resolution order: the AGENTS_SESSIONS_SYNC env var (a recognized on/off value
+// wins outright, for ad-hoc overrides and tests), then a durable machine-local
+// flag file, then the default (enabled). The flag lives in the durable
+// ~/.agents/.history tree — NOT .cache — so a cache wipe can never silently
+// re-enable a sync the operator turned off.
+/** Env var that overrides the persisted enable flag (on/off/true/false/1/0/yes/no). */
+export const SYNC_ENABLED_ENV = 'AGENTS_SESSIONS_SYNC';
+const SYNC_ENABLED_FILE = 'sessions-sync.json';
+const OFF_VALUES = new Set(['0', 'off', 'false', 'no', 'disabled']);
+const ON_VALUES = new Set(['1', 'on', 'true', 'yes', 'enabled']);
+/** Durable, machine-local path holding the sync enable flag. */
+export function syncStateFilePath() {
+    return path.join(getHistoryDir(), SYNC_ENABLED_FILE);
+}
+/**
+ * Whether automatic session sync is enabled on this machine. Defaults to true;
+ * an unrecognized env value falls through to the file; an absent/unreadable file
+ * falls through to the default. Read fresh every call (no memoization) so a
+ * `--disable` takes effect on the daemon's next ~90s cycle without a restart.
+ */
+export function isSyncEnabled() {
+    const envRaw = process.env[SYNC_ENABLED_ENV]?.trim().toLowerCase();
+    if (envRaw) {
+        if (OFF_VALUES.has(envRaw))
+            return false;
+        if (ON_VALUES.has(envRaw))
+            return true;
+        // Unrecognized value: ignore and consult the persisted flag.
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(syncStateFilePath(), 'utf-8'));
+        if (parsed && typeof parsed.enabled === 'boolean')
+            return parsed.enabled;
+    }
+    catch {
+        // Absent or unreadable → default enabled.
+    }
+    return true;
+}
+/** Persist the machine-local sync enable flag (durable across cache wipes). */
+export function setSyncEnabled(enabled) {
+    const p = syncStateFilePath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify({ enabled }, null, 2) + '\n', 'utf-8');
+}
 /**
  * Resolve R2 credentials from the `r2.backups` bundle. Throws a clear,
  * actionable error if the bundle or any key is missing — sync cannot proceed
@@ -93,22 +148,7 @@ export function isSyncConfigured(now = Date.now()) {
         return false;
     }
 }
-/**
- * Normalize a raw hostname into a stable device id: first label only,
- * lowercased, non-alphanumerics collapsed to hyphens. `zion.tail…ts.net` and
- * `ZION` both become `zion`. The single source for this transform — machineId()
- * and cross-machine session grouping must agree or the local machine won't
- * match its own registry key.
- */
-export function normalizeHost(raw) {
-    return raw.split('.')[0].trim().toLowerCase().replace(/[^a-z0-9_-]/g, '-') || 'unknown';
-}
-/**
- * This machine's stable, human-readable id, used as its R2 prefix and mirror
- * directory name. Tailnet hostnames (zion, yosemite-s0, mac-mini) are already
- * unique and readable; we lowercase and strip any domain suffix. Overridable
- * via AGENTS_SYNC_MACHINE_ID for tests and unusual setups.
- */
-export function machineId() {
-    return normalizeHost(process.env.AGENTS_SYNC_MACHINE_ID || os.hostname());
-}
+// machineId() and normalizeHost() now live in the dependency-free leaf
+// ../../machine-id.ts so low-level modules (state.ts) can use them without an
+// import cycle. Re-exported here for existing importers.
+export { machineId, normalizeHost } from '../../machine-id.js';