@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/teams/remoteWorktree.d.ts

@@ -1,63 +1,13 @@
 interface RemoteSshOptions {
     extraSshArgs?: string[];
 }
-/**
- * Render a path for safe interpolation into a REMOTE shell, expanding a leading
- * `~`/`~/` to `"$HOME"` so it resolves on the host. A plain `shellQuote('~/x')`
- * single-quotes the tilde and the remote shell leaves it literal (the same
- * reason dispatch.ts uses `$HOME`, not `~`). Everything after the tilde is still
- * single-quoted, so odd path characters stay safe.
- */
 export declare function remotePathExpr(p: string): string;
-/**
- * Create a worktree on the host for a teammate, branched off the freshly-fetched
- * default branch. Returns the absolute worktree path on the host.
- *
- * Same base policy as local `createWorktree`: fetch origin, then
- * `worktree add -b … origin/<default>` so a stale checkout can't fork the
- * teammate off old code.
- */
 export declare function createRemoteWorktree(target: string, repoPath: string, worktreeName: string, opts?: RemoteSshOptions): string;
-/**
- * How many commits the host checkout at `repoPath` is behind `origin/<default>` —
- * the remote analog of the local {@link commitsBehindDefault} staleness probe, and
- * the exact case from the incident this guard exists for (a distributed team
- * pointed at a 71-commit-stale checkout on another box).
- *
- * `ensureRemoteRepo` already fetched `origin` when it provisioned/reused the
- * checkout right before this runs, so the remote-tracking ref is usually fresh and
- * this reads it WITHOUT a second fetch: resolve the default branch, then
- * `rev-list --count HEAD..origin/<default>`. (That reuse fetch is best-effort —
- * an offline host leaves the ref stale, so this under-reports rather than blocks;
- * `createRemoteWorktree` re-fetches at launch so the teammate's base is still
- * fresh regardless.) Returns null on any git/ssh error (unreachable host, non-repo
- * path) — the caller treats null as "can't tell, don't block".
- */
 export declare function remoteCommitsBehindDefault(target: string, repoPath: string, opts?: RemoteSshOptions): {
     behind: number;
     base: string;
 } | null;
-/**
- * Ensure the team's repo is present on the host and return its absolute git
- * root. The canonical location is `~/.agents/repos/<slug>` (slug = sanitized
- * team name). Resolution, in order:
- *
- *   1. `~/.agents/repos/<slug>` already a git repo  → `git fetch origin`, use it.
- *   2. `repo` is a path that exists on the host as a git repo → use it in place.
- *   3. `repo` is a URL (or a non-existent path)      → `git clone` into the
- *      canonical location, then use it.
- *
- * `$HOME`-prefixed paths interpolate UNQUOTED (remotePathExpr) so the host shell
- * expands `$HOME` — single-quoting the tilde would defeat expansion, the same
- * hazard dispatch.ts avoids.
- */
 export declare function ensureRemoteRepo(target: string, repo: string, slug: string, opts?: RemoteSshOptions): string;
-/** True when the host worktree has uncommitted changes (staged or unstaged). */
 export declare function remoteWorktreeDirty(target: string, worktreePath: string, opts?: RemoteSshOptions): boolean;
-/**
- * Remove a host worktree and (optionally) its branch. Best-effort: prunes on a
- * "not a working tree" error and ignores a missing branch, matching local
- * `removeWorktree` semantics so cleanup never throws on a half-gone worktree.
- */
 export declare function removeRemoteWorktree(target: string, repoPath: string, worktreeName: string, deleteBranch?: boolean, opts?: RemoteSshOptions): void;
 export {};

package/dist/lib/teams/remoteWorktree.js

@@ -1,31 +1,11 @@
-/**
- * Remote git-worktree utilities for distributed teams — the SSH analog of
- * `teams/worktree.ts`. Each function runs the SAME git argv the local helper
- * runs, but over SSH on the host that owns the teammate's checkout, so a
- * distributed teammate gets its own branch/worktree without a shared local tree.
- *
- * The repo is provisioned on the host by `ensureRemoteRepo` (reuse an existing
- * checkout or clone the team's `--repo`); we fetch origin and branch the worktree
- * off `origin/<default>` so remote teammates build on the freshly-fetched default
- * branch, mirroring the local git-workflow.
- */
 import { sshExec, shellQuote, assertValidSshTarget } from '../ssh-exec.js';
 import { assertSafeGitTransport } from '../git.js';
-// Same allowlist as the local helper — worktree names land in a branch name and
-// a path, so keep them injection-safe (no shell metacharacters).
 const WORKTREE_NAME_RE = /^[A-Za-z0-9_-]+$/;
 function assertName(worktreeName) {
     if (!WORKTREE_NAME_RE.test(worktreeName)) {
         throw new Error(`Invalid worktree name: ${worktreeName}`);
     }
 }
-/**
- * Render a path for safe interpolation into a REMOTE shell, expanding a leading
- * `~`/`~/` to `"$HOME"` so it resolves on the host. A plain `shellQuote('~/x')`
- * single-quotes the tilde and the remote shell leaves it literal (the same
- * reason dispatch.ts uses `$HOME`, not `~`). Everything after the tilde is still
- * single-quoted, so odd path characters stay safe.
- */
 export function remotePathExpr(p) {
     if (p === '~')
         return '"$HOME"';
@@ -33,13 +13,6 @@ export function remotePathExpr(p) {
         return '"$HOME"/' + shellQuote(p.slice(2));
     return shellQuote(p);
 }
-/**
- * Resolve the ABSOLUTE git top-level for a (possibly `~`-relative) repo path on
- * the host, or null when it isn't a git repo / the host is unreachable. Used by
- * `ensureRemoteRepo` to both VALIDATE and CANONICALIZE a repo location, so every
- * downstream remote command (launch `cd`, worktree create, polling) works from an
- * absolute path with no tilde-expansion hazard.
- */
 function resolveRemoteRepoRoot(target, repoPath, opts = {}) {
     assertValidSshTarget(target);
     const cmd = `git -C ${remotePathExpr(repoPath)} rev-parse --show-toplevel 2>/dev/null`;
@@ -47,7 +20,6 @@ function resolveRemoteRepoRoot(target, repoPath, opts = {}) {
     const root = res.stdout.trim();
     return res.code === 0 && root ? root : null;
 }
-/** Run one git command in `repoPath` on the host; throw with stderr on failure. */
 function remoteGit(target, repoPath, args, timeoutMs = 60000, opts = {}) {
     const cmd = ['git', '-C', repoPath, ...args].map(shellQuote).join(' ');
     const res = sshExec(target, cmd, { timeoutMs, multiplex: true, extraSshArgs: opts.extraSshArgs });
@@ -56,25 +28,15 @@ function remoteGit(target, repoPath, args, timeoutMs = 60000, opts = {}) {
     }
     return res.stdout.trim();
 }
-/** True when `repoPath` is a git working tree on the host. */
 function isRemoteGitRepo(target, repoPath, opts = {}) {
     assertValidSshTarget(target);
-    // remotePathExpr so a `~`/`$HOME`-relative path (the canonical repos dir) expands
-    // on the host — plain shellQuote would single-quote the tilde into a literal,
-    // making an existing checkout look absent and forcing a doomed re-clone.
     const cmd = `git -C ${remotePathExpr(repoPath)} rev-parse --git-dir 2>/dev/null`;
     const res = sshExec(target, cmd, { timeoutMs: 15000, multiplex: true, extraSshArgs: opts.extraSshArgs });
     return res.code === 0;
 }
-/**
- * Resolve the host repo's default branch name (origin/HEAD → `main`/`master`/…).
- * Falls back to `main` when origin/HEAD isn't set, matching the local recipe's
- * `remote set-head` step.
- */
 function remoteDefaultBranch(target, repoPath, opts = {}) {
     assertValidSshTarget(target);
     try {
-        // Refresh origin/HEAD first so a repo cloned before the default was set resolves.
         sshExec(target, ['git', '-C', repoPath, 'remote', 'set-head', 'origin', '--auto'].map(shellQuote).join(' '), { timeoutMs: 20000, multiplex: true, extraSshArgs: opts.extraSshArgs });
         const ref = remoteGit(target, repoPath, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], 60000, opts);
         return ref.replace(/^origin\//, '') || 'main';
@@ -83,14 +45,6 @@ function remoteDefaultBranch(target, repoPath, opts = {}) {
         return 'main';
     }
 }
-/**
- * Create a worktree on the host for a teammate, branched off the freshly-fetched
- * default branch. Returns the absolute worktree path on the host.
- *
- * Same base policy as local `createWorktree`: fetch origin, then
- * `worktree add -b … origin/<default>` so a stale checkout can't fork the
- * teammate off old code.
- */
 export function createRemoteWorktree(target, repoPath, worktreeName, opts = {}) {
     assertValidSshTarget(target);
     assertName(worktreeName);
@@ -102,21 +56,6 @@ export function createRemoteWorktree(target, repoPath, worktreeName, opts = {})
     remoteGit(target, gitRoot, ['worktree', 'add', '-b', branchName, worktreePath, `origin/${base}`], 120000, opts);
     return worktreePath;
 }
-/**
- * How many commits the host checkout at `repoPath` is behind `origin/<default>` —
- * the remote analog of the local {@link commitsBehindDefault} staleness probe, and
- * the exact case from the incident this guard exists for (a distributed team
- * pointed at a 71-commit-stale checkout on another box).
- *
- * `ensureRemoteRepo` already fetched `origin` when it provisioned/reused the
- * checkout right before this runs, so the remote-tracking ref is usually fresh and
- * this reads it WITHOUT a second fetch: resolve the default branch, then
- * `rev-list --count HEAD..origin/<default>`. (That reuse fetch is best-effort —
- * an offline host leaves the ref stale, so this under-reports rather than blocks;
- * `createRemoteWorktree` re-fetches at launch so the teammate's base is still
- * fresh regardless.) Returns null on any git/ssh error (unreachable host, non-repo
- * path) — the caller treats null as "can't tell, don't block".
- */
 export function remoteCommitsBehindDefault(target, repoPath, opts = {}) {
     assertValidSshTarget(target);
     try {
@@ -131,44 +70,24 @@ export function remoteCommitsBehindDefault(target, repoPath, opts = {}) {
         return null;
     }
 }
-// Team-name → repos-dir slug: same allowlist a worktree name uses, so it lands
-// safely in a path (`~/.agents/repos/<slug>`) with no shell metacharacters.
 const SLUG_RE = /[^A-Za-z0-9_-]/g;
-/** Sanitize a team name into a repos-directory slug (`[A-Za-z0-9_-]` only). */
 function repoSlug(name) {
     const s = name.replace(SLUG_RE, '-');
     if (!s)
         throw new Error(`Cannot derive a repo slug from team name: ${name}`);
     return s;
 }
-/**
- * Ensure the team's repo is present on the host and return its absolute git
- * root. The canonical location is `~/.agents/repos/<slug>` (slug = sanitized
- * team name). Resolution, in order:
- *
- *   1. `~/.agents/repos/<slug>` already a git repo  → `git fetch origin`, use it.
- *   2. `repo` is a path that exists on the host as a git repo → use it in place.
- *   3. `repo` is a URL (or a non-existent path)      → `git clone` into the
- *      canonical location, then use it.
- *
- * `$HOME`-prefixed paths interpolate UNQUOTED (remotePathExpr) so the host shell
- * expands `$HOME` — single-quoting the tilde would defeat expansion, the same
- * hazard dispatch.ts avoids.
- */
 export function ensureRemoteRepo(target, repo, slug, opts = {}) {
     assertValidSshTarget(target);
     const safeSlug = repoSlug(slug);
     const canonical = `~/.agents/repos/${safeSlug}`;
-    // 1. Canonical checkout already exists → fetch and reuse.
     if (isRemoteGitRepo(target, canonical, opts)) {
-        // Best-effort refresh; a fetch failure (offline origin) shouldn't block reuse.
         sshExec(target, `git -C ${remotePathExpr(canonical)} fetch origin`, { timeoutMs: 120000, multiplex: true, extraSshArgs: opts.extraSshArgs });
         const root = resolveRemoteRepoRoot(target, canonical, opts);
         if (!root)
             throw new Error(`Repo at ${canonical} on ${target} vanished mid-provision.`);
         return root;
     }
-    // 2. `repo` is a path that already exists on the host as a git repo → use it.
     if (repo && !looksLikeUrl(repo)) {
         const existing = resolveRemoteRepoRoot(target, repo, opts);
         if (existing) {
@@ -176,16 +95,10 @@ export function ensureRemoteRepo(target, repo, slug, opts = {}) {
             return existing;
         }
     }
-    // 3. Clone the URL (or a path-that-wasn't-there) into the canonical location.
     if (!repo) {
         throw new Error(`No repo configured for team on ${target}: set \`teams create --repo <url|path>\` ` +
             `or run this teammate from a git checkout so origin can be inferred.`);
     }
-    // A `--repo` is a git-transport source that clones ON THE REMOTE HOST — guard it
-    // like the local clone path (plugins.ts) does: reject remote-helper transports
-    // (`ext::sh -c …` runs arbitrary commands at clone time) and a leading `-`, then
-    // pass `--` so a leftover `-` can't be parsed as a git option. shellQuote only
-    // blocks *shell* injection and is orthogonal to *git-transport* injection.
     assertSafeGitTransport(repo);
     const clone = sshExec(target, `mkdir -p ${remotePathExpr('~/.agents/repos')} && ` +
         `git clone -- ${shellQuote(repo)} ${remotePathExpr(canonical)}`, { timeoutMs: 600000, multiplex: true, extraSshArgs: opts.extraSshArgs });
@@ -198,13 +111,11 @@ export function ensureRemoteRepo(target, repo, slug, opts = {}) {
         throw new Error(`Cloned ${repo} into ${canonical} on ${target} but it isn't a git repo.`);
     return root;
 }
-/** Heuristic: does `repo` look like a git URL (vs a filesystem path)? */
 function looksLikeUrl(repo) {
     return (/^(https?|git|ssh):\/\//.test(repo) ||
-        /^[^/\s]+@[^/\s]+:/.test(repo) || // scp-style: git@github.com:owner/repo.git
+        /^[^/\s]+@[^/\s]+:/.test(repo) ||
         repo.startsWith('git@'));
 }
-/** True when the host worktree has uncommitted changes (staged or unstaged). */
 export function remoteWorktreeDirty(target, worktreePath, opts = {}) {
     assertValidSshTarget(target);
     const cmd = ['git', '-C', worktreePath, 'status', '--porcelain'].map(shellQuote).join(' ');
@@ -213,11 +124,6 @@ export function remoteWorktreeDirty(target, worktreePath, opts = {}) {
         return false;
     return res.stdout.trim().length > 0;
 }
-/**
- * Remove a host worktree and (optionally) its branch. Best-effort: prunes on a
- * "not a working tree" error and ignores a missing branch, matching local
- * `removeWorktree` semantics so cleanup never throws on a half-gone worktree.
- */
 export function removeRemoteWorktree(target, repoPath, worktreeName, deleteBranch = true, opts = {}) {
     assertValidSshTarget(target);
     assertName(worktreeName);
@@ -233,7 +139,6 @@ export function removeRemoteWorktree(target, repoPath, worktreeName, deleteBranc
         });
     }
     if (deleteBranch) {
-        // Branch may not exist (removed already, or never created) — ignore failure.
         sshExec(target, ['git', '-C', gitRoot, 'branch', '-D', branchName].map(shellQuote).join(' '), {
             timeoutMs: 20000,
             multiplex: true,

package/dist/lib/teams/scheduler.d.ts

@@ -1,164 +1,53 @@
 import type { Headroom } from '../devices/health.js';
-/**
- * Live signal for one pool device, gathered by the caller (SSH probes) and
- * passed into the pure pick. Every field is optional/best-effort: a device with
- * no signal is neither excluded nor preferred — it degrades to the roster-count
- * path. `reachable === false` and `installed === false` are the only two
- * exclusion signals here; `headroom` drives the overload exclusion + the load
- * tier of the rank. See {@link DeviceStats}/{@link headroom} in devices/health.
- */
 export interface DevicePlacementSignal {
-    /** SSH probe answered. `false` → excluded (unreachable). undefined → unknown. */
     reachable?: boolean;
-    /**
-     * The probe was killed for exceeding its budget rather than failing to
-     * connect. Ranking treats it exactly like `reachable:false` — an
-     * unresponsive box is still not placeable — but the operator-facing
-     * exclusion reason says "probe timed out", not "unreachable" (PHNX-3682).
-     */
     timedOut?: boolean;
-    /** Headroom bucket from load+memory. `'loaded'` → excluded (overloaded). */
     headroom?: Headroom;
-    /** Normalized CPU load percent (finer rank tiebreak within a headroom tier). */
     loadPercent?: number;
-    /** Memory pressure percent (used with loadPercent for the load cost). */
     memPercent?: number;
-    /** Requested agent installed on the device. `false` → excluded (can't run). */
     installed?: boolean;
-    /** Requested agent has at least one launch-ready account. Ranks a ready device first. */
     signedIn?: boolean;
-    /** Requested agent has at least one row the interactive account picker can launch. */
     pickerEligible?: boolean;
-    /**
-     * The box's OWN aggregate readiness reason when it has no ready account
-     * (`runReady.reason`, e.g. `all signed_out`), so the placement error names why
-     * the remote turned itself away rather than a bare "no ready harness account"
-     * (PHNX-4116). Undefined when ready or when the remote gave no reason.
-     */
     reason?: string;
 }
-/** Team fields the placement cascade reads (a subset of TeamMeta). */
 interface PlacementTeam {
     devices?: string[];
 }
-/**
- * Optional placement inputs beyond the team + roster. `maxConcurrent` maps a
- * device name to its `agents.max-concurrent` cap (from the device doc — read
- * locally via `readMaxConcurrentCaps`, never probed over SSH). Teams counts
- * the team's OWN roster against the cap (device-global counting would need an
- * SSH probe per candidate — out of the hot path; AGI EXT auto-launch is the
- * device-wide counter). Only the least-loaded AUTO-PICK (cascade step 3)
- * honors caps: an explicit pin or a pool of one is the user's own choice and
- * is never second-guessed.
- */
 interface PlacementOptions {
-    /** Worker pool used when the team does not declare an explicit device pool. */
     defaultDevices?: string[];
     maxConcurrent?: Record<string, number>;
-    /**
-     * Live per-device signals (RUSH-2002). When present, the many-device pick
-     * filters unreachable/overloaded/not-installed devices and ranks the rest by
-     * health + harness + load. Absent → the pick stays a pure roster count.
-     */
     signals?: Map<string, DevicePlacementSignal>;
-    /** Human label of the requested agent (e.g. `claude@2.1.112`) for the
-     * fail-loud message. */
     agentLabel?: string;
-    /**
-     * Normalized hosts boosted with `auto-launch.preferred` (set by
-     * `agents devices config <name> auto-launch.preferred on`). A preferred device ranks ahead of a
-     * non-preferred one among the eligible survivors — after the signed-in tier
-     * (a preferred box that can't run the agent is still no use) and before load,
-     * so an operator boost overrides load-based ordering without overriding hard
-     * health. Empty/undefined leaves the ranking unchanged. See
-     * {@link autoLaunchPreferredSet}.
-     */
     preferred?: ReadonlySet<string>;
 }
-/** Why a device was excluded from the viable set, for the fail-loud message. */
 type ExclusionReason = 'unreachable' | 'probe-timed-out' | 'overloaded' | 'capped' | 'not-installed';
-/** A pool device dropped from the auto-pick, with the reason + live detail. */
 interface ExcludedDevice {
     device: string;
     reason: ExclusionReason;
-    /** Present for `capped`: `running/cap`. */
     detail?: string;
 }
-/**
- * No device in the pool can host the teammate. Carries the per-device reasons so
- * the caller can print exactly why the pool is unusable instead of silently
- * degrading to a local run the user did not ask for.
- */
 export declare class NoViableDeviceError extends Error {
     readonly excluded: ExcludedDevice[];
     readonly agentLabel?: string;
     constructor(excluded: ExcludedDevice[], agentLabel?: string);
 }
-/**
- * Whether a failed placement can become viable without changing the team.
- * Capacity and load are time-varying; a pool with at least one such exclusion
- * must remain schedulable so a later supervisor wave can retry it. A pool that
- * is only missing the requested harness is a durable configuration failure.
- */
 export declare function isTransientPlacementBlock(error: unknown): error is NoViableDeviceError;
-/** Build the user-facing fail-loud message from the per-device reasons. */
 export declare function formatNoViableMessage(excluded: ExcludedDevice[], agentLabel?: string): string;
-/**
- * A roster entry the load counter reads — the shape any teammate satisfies
- * (AgentProcess included). `status` is compared against `'running'` (the
- * AgentStatus.RUNNING value) without importing the enum, keeping this leaf pure.
- */
 export interface RosterEntry {
     hostName: string | null;
     status: string;
 }
-/**
- * Pool devices excluded from auto-pick because they are at (or over) their
- * `agents.max-concurrent` cap. Returned with the live counts so the caller can
- * state the reason to the user instead of the device silently never winning.
- */
 export declare function cappedDevices(devices: string[], roster: RosterEntry[], maxConcurrent: Record<string, number>): Array<{
     device: string;
     running: number;
     cap: number;
 }>;
-/**
- * Pick the least-loaded device from the pool — the one with the fewest RUNNING
- * teammates currently assigned to it. Ties break by pool order (first wins), so
- * an empty pool fills round-robin-ish as teammates launch. Pure: counts the
- * roster, no I/O.
- *
- * With `maxConcurrent`, devices at their cap are excluded; if EVERY device is
- * capped this throws naming each cap and the fix — a loud failure beats a
- * teammate silently landing on a machine its operator capped.
- */
 export declare function pickLeastLoaded(devices: string[], roster: RosterEntry[], maxConcurrent?: Record<string, number>): string;
-/**
- * Split the pool into the viable set and the excluded set (with reasons), from
- * the caps + live signals. Pure — the caller decides what to do with an empty
- * viable set. Reasons are checked in a stable order (unreachable → not-installed
- * → overloaded → capped) so a device reports its most fundamental blocker first.
- */
 export declare function classifyExclusions(devices: string[], roster: RosterEntry[], opts?: PlacementOptions): {
     eligible: string[];
     excluded: ExcludedDevice[];
 };
-/**
- * Health-, harness-, and load-aware pick over a pool (RUSH-2002). Filters
- * unreachable / overloaded / capped / not-installed devices, then ranks the
- * survivors by: (a) agent signed in, (b) lower load (headroom tier, then raw
- * load cost), (c) fewer running teammates, ties broken by pool order. Throws
- * {@link NoViableDeviceError} when nothing survives — never returns a local
- * fallback. Pure: all I/O is pre-resolved into `opts.signals`.
- */
 export declare function pickBestDevice(devices: string[], roster: RosterEntry[], opts?: PlacementOptions): string;
-/**
- * Resolve where a teammate runs. Returns `{ device: null }` only when the
- * explicitly/default-selected device is the local machine, and
- * `{ device: <name> }` for a remote placement. See the cascade in the module
- * header. Throws {@link NoViableDeviceError} when a required pool has no viable
- * host — the caller surfaces it at `teams start` rather than falling back local.
- */
 export declare function resolvePlacement(team: PlacementTeam, explicitDevice: string | null, roster: RosterEntry[], opts?: PlacementOptions): {
     device: string | null;
 };