@phnx-labs/agents-cli 1.20.72 → 1.20.74

package/dist/lib/fs-atomic.js

@@ -41,9 +41,9 @@ export function ensureLockTarget(filePath, initialContent = '', dirMode) {
  * Writes content to filePath via a temp file + rename so readers never see a
  * partial write. On POSIX, rename(2) is atomic.
  */
-export function atomicWriteFileSync(filePath, content) {
+export function atomicWriteFileSync(filePath, content, options = 'utf-8') {
     const tmpPath = `${filePath}.tmp-${process.pid}-${randomBytes(8).toString('hex')}`;
-    fs.writeFileSync(tmpPath, content, 'utf-8');
+    fs.writeFileSync(tmpPath, content, options);
     try {
         fs.renameSync(tmpPath, filePath);
     }
@@ -55,19 +55,15 @@ export function atomicWriteFileSync(filePath, content) {
         throw err;
     }
 }
-/**
- * Acquires an exclusive proper-lockfile lock on filePath, runs fn, then
- * releases the lock. Retries with capped linear back-off until either the lock
- * is acquired or LOCK_ACQUIRE_TIMEOUT_MS elapses. Breaks stale locks older than
- * LOCK_STALE_MS, so a crashed holder never blocks past the stale window.
- */
-export function withFileLock(filePath, fn) {
+export function withFileLock(filePath, fn, opts = {}) {
     let release = null;
     let lastError;
-    const deadline = Date.now() + LOCK_ACQUIRE_TIMEOUT_MS;
+    const staleMs = opts.staleMs ?? LOCK_STALE_MS;
+    const acquireTimeoutMs = opts.acquireTimeoutMs ?? LOCK_ACQUIRE_TIMEOUT_MS;
+    const deadline = Date.now() + acquireTimeoutMs;
     for (let attempt = 0;; attempt++) {
         try {
-            release = lockfile.lockSync(filePath, { stale: LOCK_STALE_MS });
+            release = lockfile.lockSync(filePath, { stale: staleMs });
             break;
         }
         catch (err) {
@@ -80,7 +76,7 @@ export function withFileLock(filePath, fn) {
     }
     if (!release) {
         const message = lastError instanceof Error ? lastError.message : String(lastError);
-        throw new Error(`Could not acquire lock for ${filePath} after ${LOCK_ACQUIRE_TIMEOUT_MS}ms: ${message}`);
+        throw new Error(`Could not acquire lock for ${filePath} after ${acquireTimeoutMs}ms: ${message}`);
     }
     try {
         return fn();

package/dist/lib/git.d.ts

@@ -91,6 +91,22 @@ export declare function getRepoCommit(repoPath: string): Promise<string>;
  * Returns null if gh is not installed or user is not authenticated.
  */
 export declare function getGitHubUsername(): Promise<string | null>;
+/**
+ * Resolve the GitHub username synchronously for `agents share`. Order:
+ *   1. `AGENTS_SHARE_GITHUB_USER` env override
+ *   2. `git config --global github.user`
+ * Falls back to null so callers can decide whether to require auth or proceed
+ * without a namespace.
+ */
+export declare function resolveGitHubUsernameSync(): string | null;
+/**
+ * Resolve the GitHub username asynchronously. Order:
+ *   1. `AGENTS_SHARE_GITHUB_USER` env override
+ *   2. `gh api user --jq ".login"`
+ *   3. `git config --global github.user`
+ * Returns null if none succeed.
+ */
+export declare function resolveGitHubUsername(): Promise<string | null>;
 /**
  * Get the remote URL for origin in a git repo.
  */

package/dist/lib/git.js

@@ -6,6 +6,7 @@
  * source parsing for GitHub shorthand, SSH, HTTPS, and local paths.
  */
 import simpleGit from 'simple-git';
+import { execFileSync } from 'node:child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -350,6 +351,47 @@ export async function getGitHubUsername() {
         return null;
     }
 }
+const GITHUB_USER_ENV = 'AGENTS_SHARE_GITHUB_USER';
+/** Best-effort sync read of `github.user` from git config. */
+function readGitConfigUser() {
+    try {
+        return execFileSync('git', ['config', '--global', 'github.user'], { stdio: ['ignore', 'pipe', 'ignore'] })
+            .toString()
+            .trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the GitHub username synchronously for `agents share`. Order:
+ *   1. `AGENTS_SHARE_GITHUB_USER` env override
+ *   2. `git config --global github.user`
+ * Falls back to null so callers can decide whether to require auth or proceed
+ * without a namespace.
+ */
+export function resolveGitHubUsernameSync() {
+    const env = process.env[GITHUB_USER_ENV]?.trim();
+    if (env)
+        return env;
+    return readGitConfigUser();
+}
+/**
+ * Resolve the GitHub username asynchronously. Order:
+ *   1. `AGENTS_SHARE_GITHUB_USER` env override
+ *   2. `gh api user --jq ".login"`
+ *   3. `git config --global github.user`
+ * Returns null if none succeed.
+ */
+export async function resolveGitHubUsername() {
+    const env = process.env[GITHUB_USER_ENV]?.trim();
+    if (env)
+        return env;
+    const gh = await getGitHubUsername();
+    if (gh)
+        return gh;
+    return readGitConfigUser();
+}
 /**
  * Get the remote URL for origin in a git repo.
  */
@@ -779,12 +821,47 @@ export async function pullRepo(dir) {
             return {
                 success: false,
                 commit: '',
-                error: `Working tree has uncommitted changes. Commit or discard them before pulling.\n\n  cd ${displayHomePath(dir)} && git status`,
+                error: `Blocked by local changes. Commit or discard them before pulling.\n\n  cd ${displayHomePath(dir)} && git status`,
             };
         }
         const branch = status.current || 'main';
         await git.fetch('origin');
-        await git.pull('origin', branch, { '--rebase': 'true' });
+        // Resolve the upstream ref to fast-forward against. Prefer the local
+        // branch's tracking config; otherwise ask origin for its default branch.
+        let tracking = status.tracking;
+        if (!tracking) {
+            try {
+                await git.raw(['remote', 'set-head', 'origin', '--auto']);
+                const sym = await git.raw(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']);
+                tracking = sym.trim();
+            }
+            catch {
+                tracking = `origin/${branch}`;
+            }
+        }
+        const localRef = await git.revparse(['HEAD']);
+        const remoteRef = await git.revparse([tracking]).catch(() => null);
+        if (!remoteRef) {
+            return { success: false, commit: '', error: `Could not resolve upstream ref ${tracking}` };
+        }
+        if (localRef === remoteRef) {
+            const log = await git.log({ maxCount: 1 });
+            return {
+                success: true,
+                commit: log.latest?.hash.slice(0, 8) || 'unknown',
+                branch,
+            };
+        }
+        try {
+            await git.merge(['--ff-only', tracking]);
+        }
+        catch {
+            return {
+                success: false,
+                commit: '',
+                error: `Blocked by local commits. Push or reset them before pulling.\n\n  cd ${displayHomePath(dir)} && git log --oneline HEAD...${tracking}`,
+            };
+        }
         installGithooksSymlinks(dir);
         const log = await git.log({ maxCount: 1 });
         return {

package/dist/lib/heal.js

@@ -23,7 +23,7 @@
  * `agents prune cleanup`, so a heal pass can never lose work.
  */
 import { ALL_AGENT_IDS } from './agents.js';
-import { syncResourcesToVersion, listInstalledVersions, getVersionHomePath, getActuallySyncedResources, compareVersions, } from './versions.js';
+import { syncResourcesToVersion, listInstalledVersions, isVersionIsolated, getVersionHomePath, getActuallySyncedResources, compareVersions, } from './versions.js';
 import { diffVersionResources, } from './doctor-diff.js';
 import { discoverPlugins, updatePlugin, readPluginSourceInfo, getUpstreamManifestVersion, } from './plugins.js';
 import { repairPluginManifestFile } from './plugin-marketplace.js';
@@ -266,9 +266,17 @@ export async function heal(opts) {
         ...repairedManifests.map((r) => r.plugin),
         ...refreshed.map((r) => r.plugin),
     ]);
+    // Isolated copies are excluded from every SWEEP. `agents add --isolated`
+    // promises "no settings carry-over, no resource sync", and this engine runs
+    // unattended from the daemon (~30s after start, then every ~6h) — a sweep that
+    // walked into an isolated home would quietly refill it with shared commands,
+    // skills, hooks, MCP config and permissions. Explicitly NAMED versions
+    // (`agents doctor <agent>@<version> --fix`) are honoured as-is: naming the
+    // version is the operator's consent.
+    const sweep = (a) => listInstalledVersions(a).filter((v) => !isVersionIsolated(a, v));
     const targets = opts.agent
-        ? [{ agent: opts.agent, versions: opts.versions ?? listInstalledVersions(opts.agent) }]
-        : ALL_AGENT_IDS.map((a) => ({ agent: a, versions: listInstalledVersions(a) }));
+        ? [{ agent: opts.agent, versions: opts.versions ?? sweep(opts.agent) }]
+        : ALL_AGENT_IDS.map((a) => ({ agent: a, versions: sweep(a) }));
     const versions = [];
     for (const t of targets) {
         for (const v of t.versions) {

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

@@ -1,17 +1,15 @@
 /**
- * Follow a dispatched host run by offset-tailing its remote log.
+ * Follow a dispatched host run by streaming its remote log.
  *
  * The run writes combined output to a log file on the host and its exit code to
- * 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.
+ * a sibling `.exit` file. The primary path opens one long-lived
+ * `ssh ... tail -f` stream (durable, offset-tracked — a dropped connection
+ * reconnects from the saved offset) and finishes when the remote-side watcher
+ * emits the exit sentinel. 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.
+ * Efficiency: a healthy follow holds exactly one ssh process/socket for the
+ * whole run instead of spawning once per poll cycle. If the connection drops,
+ * the next stream resumes at the byte offset already flushed locally.
  */
 /**
  * Cap for the LOCAL mirror of a distributed teammate's remote log. `followHostTask`
@@ -102,6 +100,26 @@ export declare function fetchProgress(target: string, opts: {
     logChunk: Buffer;
     exit: string;
 } | null;
+/**
+ * Remote shell for the persistent follow stream.
+ *
+ * Protocol: stream `tail -c +<offset+1> -f <log>` as raw stdout until `.exit`
+ * becomes non-empty, give tail one more polling interval to flush final bytes,
+ * stop it, then print the same per-task sentinel and `cat` the exit file on
+ * stderr. Keeping the terminal frame off stdout lets log bytes pass through
+ * live without buffering and without confusing agent output for our marker.
+ * `remoteLog`/`remoteExit` are dispatch-generated `$HOME` paths with safe hex
+ * basenames (or absolute paths in localhost integration tests), so they stay
+ * unquoted to preserve `$HOME` expansion just like `fetchProgress`.
+ */
+export declare function buildStreamingFollowCommand(opts: {
+    remoteLog: string;
+    remoteExit: string;
+    taskId: string;
+    offset: number;
+}): string;
+/** Extract the remote watcher frame from stderr, if the stream ended normally. */
+export declare function parseStreamingExitFrame(stderr: Buffer, taskId: string): Buffer | 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.

package/dist/lib/hosts/progress.js

@@ -1,20 +1,18 @@
 /**
- * Follow a dispatched host run by offset-tailing its remote log.
+ * Follow a dispatched host run by streaming its remote log.
  *
  * The run writes combined output to a log file on the host and its exit code to
- * 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.
+ * a sibling `.exit` file. The primary path opens one long-lived
+ * `ssh ... tail -f` stream (durable, offset-tracked — a dropped connection
+ * reconnects from the saved offset) and finishes when the remote-side watcher
+ * emits the exit sentinel. 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.
+ * Efficiency: a healthy follow holds exactly one ssh process/socket for the
+ * whole run instead of spawning once per poll cycle. If the connection drops,
+ * the next stream resumes at the byte offset already flushed locally.
  */
 import * as fs from 'fs';
-import { sshExec, sshExecRaw } from '../ssh-exec.js';
+import { sshExec, sshExecRaw, sshExecRawStream } from '../ssh-exec.js';
 import { localLogPath } from './tasks.js';
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -54,6 +52,7 @@ export function pullRemoteLogDelta(target, opts) {
         return null; // ssh itself failed / timed out
     return { bytes: res.stdout, newOffset: opts.offset + res.stdout.length };
 }
+const STREAM_EXIT_POLL_SECONDS = 1;
 /**
  * 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
@@ -116,6 +115,47 @@ export function fetchProgress(target, opts) {
         return null;
     return { logChunk: parts.logChunk, exit: parts.exit.toString('utf8') };
 }
+/**
+ * Remote shell for the persistent follow stream.
+ *
+ * Protocol: stream `tail -c +<offset+1> -f <log>` as raw stdout until `.exit`
+ * becomes non-empty, give tail one more polling interval to flush final bytes,
+ * stop it, then print the same per-task sentinel and `cat` the exit file on
+ * stderr. Keeping the terminal frame off stdout lets log bytes pass through
+ * live without buffering and without confusing agent output for our marker.
+ * `remoteLog`/`remoteExit` are dispatch-generated `$HOME` paths with safe hex
+ * basenames (or absolute paths in localhost integration tests), so they stay
+ * unquoted to preserve `$HOME` expansion just like `fetchProgress`.
+ */
+export function buildStreamingFollowCommand(opts) {
+    const printfArg = exitMarker(opts.taskId).replace(/\n/g, '\\n');
+    return [
+        'set +e',
+        'tail_pid=',
+        'cleanup() { if [ -n "$tail_pid" ]; then kill "$tail_pid" 2>/dev/null || true; wait "$tail_pid" 2>/dev/null || true; fi; }',
+        'trap cleanup EXIT HUP INT TERM',
+        `while [ ! -e ${opts.remoteLog} ] && [ ! -s ${opts.remoteExit} ]; do sleep ${STREAM_EXIT_POLL_SECONDS}; done`,
+        `tail -c +${opts.offset + 1} -f ${opts.remoteLog} 2>/dev/null &`,
+        'tail_pid=$!',
+        `while [ ! -s ${opts.remoteExit} ]; do`,
+        '  if ! kill -0 "$tail_pid" 2>/dev/null; then wait "$tail_pid" 2>/dev/null; exit 86; fi',
+        `  sleep ${STREAM_EXIT_POLL_SECONDS}`,
+        'done',
+        `sleep ${STREAM_EXIT_POLL_SECONDS}`,
+        'cleanup',
+        'tail_pid=',
+        `printf '${printfArg}' >&2`,
+        `cat ${opts.remoteExit} >&2 2>/dev/null`,
+    ].join('\n');
+}
+/** Extract the remote watcher frame from stderr, if the stream ended normally. */
+export function parseStreamingExitFrame(stderr, taskId) {
+    const marker = Buffer.from(exitMarker(taskId), 'utf8');
+    const idx = stderr.lastIndexOf(marker);
+    if (idx === -1)
+        return null;
+    return stderr.subarray(idx + marker.length);
+}
 /**
  * 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.
@@ -169,23 +209,40 @@ export async function followHostTask(target, opts) {
         return true;
     };
     for (;;) {
-        const r = fetchProgress(target, { remoteLog: opts.remoteLog, remoteExit: opts.remoteExit, taskId: opts.taskId, offset });
-        const gotOutput = r ? flush(r.logChunk) : false;
-        if (r && r.exit.trim() !== '') {
-            // Finished — one final fetch catches bytes written between our tail and
-            // the exit file appearing.
-            const tail = fetchProgress(target, { remoteLog: opts.remoteLog, remoteExit: opts.remoteExit, taskId: opts.taskId, offset });
-            if (tail)
-                flush(tail.logChunk);
-            const code = parseInt(r.exit.trim(), 10);
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            process.stderr.write('\n[hosts] follow timed out; the run continues on the host. Reattach with: agents hosts logs ' + opts.taskId + ' -f\n');
+            return -1;
+        }
+        const abort = new AbortController();
+        const timer = setTimeout(() => abort.abort(), remaining);
+        let gotOutput = false;
+        let exitFrame = null;
+        try {
+            const stream = await sshExecRawStream(target, buildStreamingFollowCommand({ remoteLog: opts.remoteLog, remoteExit: opts.remoteExit, taskId: opts.taskId, offset }), {
+                timeoutMs: remaining,
+                signal: abort.signal,
+                multiplex: true,
+                onStdout: (chunk) => { gotOutput = flush(chunk) || gotOutput; },
+            });
+            exitFrame = parseStreamingExitFrame(stream.stderr, opts.taskId);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (exitFrame) {
+            const code = parseInt(exitFrame.toString('utf8').trim(), 10);
             return Number.isFinite(code) ? code : 0;
         }
+        // SSH dropped before the remote watcher emitted the exit sentinel. Stdout
+        // chunks were flushed as they arrived, so reconnect from the advanced offset.
+        // If no bytes arrived, back off like the old idle poll.
         if (Date.now() > deadline) {
             process.stderr.write('\n[hosts] follow timed out; the run continues on the host. Reattach with: agents hosts logs ' + opts.taskId + ' -f\n');
             return -1;
         }
-        // Fast while output flows; ease toward maxMs when idle so a quiet job isn't
-        // polled needlessly. New output snaps the cadence back to fast.
+        // Reconnect quickly while output flows; ease toward maxMs when the stream
+        // drops without bytes so a flapping idle host does not spin ssh processes.
         waitMs = gotOutput ? fastMs : Math.min(maxMs, Math.round(waitMs * 1.5));
         await sleep(waitMs);
     }

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

@@ -108,7 +108,11 @@ export const RUN_OPTION_FORWARDING = {
     any: 'local-only',
     follow: 'local-only',
     lease: 'local-only',
+    box: 'local-only',
     keepBox: 'local-only',
+    reuse: 'local-only', // reuse-picker choice for --lease; the lease path is always local
+    bare: 'local-only', // skips the local setup-copy push; lease-only concern
+    tailscale: 'local-only', // --tailscale/--no-tailscale gate the lease net mode; never forwarded
     copyCreds: 'local-only', // copies creds TO the host before dispatch — local concern only
     authCheck: 'local-only', // --no-auth-check gates the local interactive login preflight; --host runs skip that preflight entirely
 };

package/dist/lib/hq/floor.d.ts

@@ -0,0 +1,87 @@
+import type { ActiveSession } from '../session/active.js';
+import type { OpenBlock } from '../feed.js';
+import type { AgentStatusDetail, TaskInfo } from '../teams/api.js';
+export type HqRoomKind = 'team' | 'machine' | 'lobby';
+export type HqAgentMood = 'working' | 'waiting' | 'blocked' | 'celebrating' | 'idle';
+export type HqAmbientKind = 'needs_input' | 'error' | 'pr' | 'team_active' | 'idle_scene';
+export interface HqAction {
+    id: string;
+    label: string;
+    command: string[];
+    target: {
+        kind: 'agent' | 'room' | 'floor';
+        id: string;
+    };
+    destructive?: boolean;
+    input?: Array<{
+        name: string;
+        label: string;
+        placeholder?: string;
+        required?: boolean;
+    }>;
+}
+export interface HqRoom {
+    id: string;
+    kind: HqRoomKind;
+    name: string;
+    machine?: string;
+    team?: string;
+    counts: {
+        agents: number;
+        needsInput: number;
+        running: number;
+        failed: number;
+    };
+    actions: HqAction[];
+}
+export interface HqAgent {
+    id: string;
+    label: string;
+    agent: string;
+    roomId: string;
+    mood: HqAgentMood;
+    status: string;
+    activity?: string;
+    preview?: string;
+    machine?: string;
+    team?: string;
+    teammate?: string;
+    sessionId?: string;
+    mailboxId?: string;
+    pid?: number;
+    prUrl?: string;
+    ticketId?: string;
+    actions: HqAction[];
+}
+export interface HqAmbientEvent {
+    id: string;
+    kind: HqAmbientKind;
+    roomId: string;
+    agentId?: string;
+    label: string;
+    intensity: 'low' | 'medium' | 'high';
+}
+export interface HqFloorSnapshot {
+    version: 1;
+    generatedAt: string;
+    counters: {
+        rooms: number;
+        agents: number;
+        teams: number;
+        needsInput: number;
+        failed: number;
+        prs: number;
+    };
+    rooms: HqRoom[];
+    agents: HqAgent[];
+    ambientEvents: HqAmbientEvent[];
+    actions: HqAction[];
+}
+export interface BuildHqFloorInput {
+    generatedAt?: Date;
+    sessions: ActiveSession[];
+    teams: TaskInfo[];
+    teammatesByTeam: Map<string, AgentStatusDetail[]>;
+    blocks: OpenBlock[];
+}
+export declare function buildHqFloor(input: BuildHqFloorInput): HqFloorSnapshot;