@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/lib/teams/remoteWorktree.js

@@ -102,6 +102,35 @@ 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 {
+        const base = remoteDefaultBranch(target, repoPath, opts);
+        const raw = remoteGit(target, repoPath, ['rev-list', '--count', `HEAD..origin/${base}`], 30000, opts);
+        const behind = parseInt(raw, 10);
+        if (!Number.isFinite(behind))
+            return null;
+        return { behind, base };
+    }
+    catch {
+        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;

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

@@ -30,7 +30,7 @@ export interface PlacementTeam {
  * 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; Factory auto-launch is the
+ * 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.

package/dist/lib/teams/scheduler.js

@@ -132,7 +132,7 @@ export function pickLeastLoaded(devices, roster, maxConcurrent) {
             .map((d) => `${d} (${load.get(d) ?? 0}/${maxConcurrent[d]})`)
             .join(', ');
         throw new Error(`Every device in the pool is at its agents.max-concurrent cap: ${detail}. ` +
-            `Raise a cap with 'agents devices configure <name> --max-agents N' or add a device to the pool.`);
+            `Raise a cap with 'agents devices config <name> agents.max-concurrent N' or add a device to the pool.`);
     }
     // Iterate the pool in declared order so the first device wins ties.
     let best = eligible[0];

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

@@ -27,6 +27,30 @@ export declare function gitDiff(worktreePath: string, maxBytes?: number): Promis
  * Falls back to `main` when origin/HEAD isn't set.
  */
 export declare function localDefaultBranch(gitRoot: string): Promise<string>;
+/**
+ * How many commits the checkout at `repoDir` is behind freshly-fetched
+ * `origin/<default>` — the staleness the `teams add` guard checks before pointing
+ * a team at a repo.
+ *
+ * Fetches `origin` FIRST, on purpose: the exact failure this guards (a team
+ * pointed at a repo "without fetching first" — a 71-commit-stale s1 checkout in
+ * the real incident) leaves the remote-tracking ref itself stale, so a naive
+ * `HEAD..origin/<default>` reads 0 and hides the drift. After the fetch the count
+ * is against the true remote.
+ *
+ * Measures the passed checkout's OWN root ({@link getGitRoot} / `--show-toplevel`,
+ * worktree-correct) — NOT {@link getMainRepoRoot}: for a `--use-worktree` shared
+ * worktree (or a caller standing inside a linked worktree), the teammate runs in
+ * THAT worktree, whose HEAD differs from the main checkout's, so folding to the
+ * main root would report the wrong tree's staleness. `origin/<default>` resolves
+ * from the shared object store regardless of which worktree we stand in. Returns
+ * null when `repoDir` isn't a git repo, origin is unreachable, or git errors — the
+ * caller treats null as "can't tell, don't block".
+ */
+export declare function commitsBehindDefault(repoDir: string): Promise<{
+    behind: number;
+    base: string;
+} | null>;
 /**
  * Create a new git worktree for a teammate, branched off the freshly-fetched
  * default branch. Fetches `origin` first and bases the branch on

package/dist/lib/teams/worktree.js

@@ -100,6 +100,48 @@ export async function localDefaultBranch(gitRoot) {
     }
     return 'main';
 }
+/**
+ * How many commits the checkout at `repoDir` is behind freshly-fetched
+ * `origin/<default>` — the staleness the `teams add` guard checks before pointing
+ * a team at a repo.
+ *
+ * Fetches `origin` FIRST, on purpose: the exact failure this guards (a team
+ * pointed at a repo "without fetching first" — a 71-commit-stale s1 checkout in
+ * the real incident) leaves the remote-tracking ref itself stale, so a naive
+ * `HEAD..origin/<default>` reads 0 and hides the drift. After the fetch the count
+ * is against the true remote.
+ *
+ * Measures the passed checkout's OWN root ({@link getGitRoot} / `--show-toplevel`,
+ * worktree-correct) — NOT {@link getMainRepoRoot}: for a `--use-worktree` shared
+ * worktree (or a caller standing inside a linked worktree), the teammate runs in
+ * THAT worktree, whose HEAD differs from the main checkout's, so folding to the
+ * main root would report the wrong tree's staleness. `origin/<default>` resolves
+ * from the shared object store regardless of which worktree we stand in. Returns
+ * null when `repoDir` isn't a git repo, origin is unreachable, or git errors — the
+ * caller treats null as "can't tell, don't block".
+ */
+export async function commitsBehindDefault(repoDir) {
+    const gitRoot = await getGitRoot(repoDir).catch(() => null);
+    if (!gitRoot)
+        return null;
+    try {
+        await execFileAsync('git', ['fetch', 'origin'], { cwd: gitRoot });
+    }
+    catch {
+        return null; // offline / no origin — can't assess staleness, don't block a team.
+    }
+    const base = await localDefaultBranch(gitRoot);
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-list', '--count', `HEAD..origin/${base}`], { cwd: gitRoot });
+        const behind = parseInt(stdout.trim(), 10);
+        if (!Number.isFinite(behind))
+            return null;
+        return { behind, base };
+    }
+    catch {
+        return null; // no origin/<default> tracking ref, detached probe, etc.
+    }
+}
 /**
  * Create a new git worktree for a teammate, branched off the freshly-fetched
  * default branch. Fetches `origin` first and bases the branch on

package/dist/lib/terminal/backends/vscodium-agent.d.ts

@@ -23,8 +23,17 @@ export declare const EDITOR_VARIANTS: EditorVariant[];
  * it, so a `command`/`cwd` containing `&` (or `=`) would be mis-split by a naive
  * multi-param query. base64url is `[A-Za-z0-9_-]` only (no `&`, `=`, `%`, `+`,
  * `/`), so it survives that decode untouched and round-trips exactly.
+ *
+ * Optional `meta.agent` / `meta.sessionId` / `meta.title` let the extension set
+ * the tab chip and status bar without sniffing the local process tree — required
+ * when `command` is a remote attach (`ssh … tmux attach`) with no agent binary
+ * on this box (#2478).
  */
-export declare function spawnUri(scheme: string, cwd: string, command: string[], direction?: SplitDirection): string;
+export declare function spawnUri(scheme: string, cwd: string, command: string[], direction?: SplitDirection, meta?: {
+    agent?: string;
+    sessionId?: string;
+    title?: string;
+}): string;
 /** Build a backend bound to one editor variant. */
 export declare function makeVscodiumAgentBackend(variant: EditorVariant): TerminalBackend;
 /** Default backend: VSCodium (`codium` CLI, `vscodium://` scheme). */

package/dist/lib/terminal/backends/vscodium-agent.js

@@ -41,14 +41,25 @@ function appExists(p) {
  * it, so a `command`/`cwd` containing `&` (or `=`) would be mis-split by a naive
  * multi-param query. base64url is `[A-Za-z0-9_-]` only (no `&`, `=`, `%`, `+`,
  * `/`), so it survives that decode untouched and round-trips exactly.
+ *
+ * Optional `meta.agent` / `meta.sessionId` / `meta.title` let the extension set
+ * the tab chip and status bar without sniffing the local process tree — required
+ * when `command` is a remote attach (`ssh … tmux attach`) with no agent binary
+ * on this box (#2478).
  */
-export function spawnUri(scheme, cwd, command, direction) {
+export function spawnUri(scheme, cwd, command, direction, meta) {
     const payload = {
         command: command.join(' '),
         cwd,
     };
     if (direction)
         payload.split = direction;
+    if (meta?.agent)
+        payload.agent = meta.agent;
+    if (meta?.sessionId)
+        payload.sessionId = meta.sessionId;
+    if (meta?.title)
+        payload.title = meta.title;
     const p = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
     return `${scheme}://${EXTENSION_AUTHORITY}/spawn?p=${p}`;
 }
@@ -60,11 +71,11 @@ export function makeVscodiumAgentBackend(variant) {
         isAvailable(ctx) {
             return ctx.platform === 'darwin' && appExists(variant.app);
         },
-        buildTab(cwd, command) {
-            return { argv: [variant.cli, '--open-url', spawnUri(variant.scheme, cwd, command)] };
+        buildTab(cwd, command, meta) {
+            return { argv: [variant.cli, '--open-url', spawnUri(variant.scheme, cwd, command, undefined, meta)] };
         },
-        buildSplit(cwd, command, direction) {
-            return { argv: [variant.cli, '--open-url', spawnUri(variant.scheme, cwd, command, direction)] };
+        buildSplit(cwd, command, direction, meta) {
+            return { argv: [variant.cli, '--open-url', spawnUri(variant.scheme, cwd, command, direction, meta)] };
         },
     };
 }

package/dist/lib/terminal/engine.d.ts

@@ -21,6 +21,10 @@ export declare function openSurface(req: LaunchRequest, opts?: OpenOptions): Pro
 export interface SurfaceItem {
     cwd: string;
     command: string[];
+    /** Optional harness identity for editor-backed backends (vscodium-agent). */
+    agent?: string;
+    sessionId?: string;
+    title?: string;
 }
 export interface BuildRequestsOptions {
     backend: Backend;

package/dist/lib/terminal/engine.js

@@ -8,9 +8,12 @@ export function specForRequest(req) {
     const backend = BACKENDS[req.backend];
     if (!backend)
         throw new Error(`unknown backend: ${req.backend}`);
+    const meta = req.agent || req.sessionId || req.title
+        ? { agent: req.agent, sessionId: req.sessionId, title: req.title }
+        : undefined;
     if (req.layout === 'tab')
-        return backend.buildTab(req.cwd, req.command);
-    return backend.buildSplit(req.cwd, req.command, req.layout === 'split-down' ? 'down' : 'right');
+        return backend.buildTab(req.cwd, req.command, meta);
+    return backend.buildSplit(req.cwd, req.command, req.layout === 'split-down' ? 'down' : 'right', meta);
 }
 /** Open a single surface for one request. Never throws — failures come back in the result. */
 export async function openSurface(req, opts = {}) {
@@ -35,6 +38,9 @@ export function buildRequests(items, opts) {
         cwd: item.cwd,
         command: item.command,
         host: opts.host,
+        agent: item.agent,
+        sessionId: item.sessionId,
+        title: item.title,
     }));
 }
 /**

package/dist/lib/terminal/types.d.ts

@@ -25,6 +25,21 @@ export interface LaunchSpec {
     /** argv to run (e.g. `['osascript','-e',script]` or `['tmux','split-window',…]`). */
     argv: string[];
 }
+/**
+ * Optional identity the caller already knows about the surface. The
+ * vscodium-agent backend forwards these into the swarm-ext `/spawn` URI so the
+ * extension can set the tab chip/name/session without sniffing the local
+ * process tree (required for remote `ssh … tmux attach` resumes — #2478).
+ * Other backends ignore them.
+ */
+export interface SurfaceMeta {
+    /** Harness id: claude, codex, grok, … */
+    agent?: string;
+    /** Canonical session id. */
+    sessionId?: string;
+    /** Optional pre-baked tab title. */
+    title?: string;
+}
 /** A single "open this command as this surface" instruction. */
 export interface LaunchRequest {
     backend: Backend;
@@ -35,6 +50,10 @@ export interface LaunchRequest {
     command: string[];
     /** undefined / 'local' = this machine; otherwise a resolvable host alias. */
     host?: string;
+    /** Optional agent identity for editor-backed backends. */
+    agent?: string;
+    sessionId?: string;
+    title?: string;
 }
 /** Outcome of opening one surface. Never throws for launch failures — reports them. */
 export interface LaunchResult {
@@ -53,7 +72,7 @@ export interface TerminalBackend {
     /** Can this backend be driven here? (platform + app installed / inside tmux). */
     isAvailable(ctx: EngineContext): boolean;
     /** Command that opens a new tab running `command` in `cwd`. */
-    buildTab(cwd: string, command: string[]): LaunchSpec;
+    buildTab(cwd: string, command: string[], meta?: SurfaceMeta): LaunchSpec;
     /** Command that splits the current surface, running `command` in `cwd`. */
-    buildSplit(cwd: string, command: string[], direction: SplitDirection): LaunchSpec;
+    buildSplit(cwd: string, command: string[], direction: SplitDirection, meta?: SurfaceMeta): LaunchSpec;
 }

package/dist/lib/testdata/refresh-coordinator-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/testdata/refresh-coordinator-worker.js

@@ -0,0 +1,23 @@
+import * as fs from 'node:fs';
+import { setRefreshLockRootForTest, withRefreshLease } from '../refresh-coordinator.js';
+const [lockRoot, resultPath, countPath, key] = process.argv.slice(2);
+setRefreshLockRootForTest(lockRoot);
+await withRefreshLease({
+    scope: 'cross-process-test',
+    key,
+    readCompleted: () => {
+        try {
+            return Number(fs.readFileSync(resultPath, 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    },
+    isCompleted: (value) => value === 1,
+    refresh: async () => {
+        fs.appendFileSync(countPath, 'refresh\n');
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        fs.writeFileSync(resultPath, '1');
+        return 1;
+    },
+});

package/dist/lib/tickets/list.d.ts

@@ -0,0 +1,53 @@
+export type TicketSource = 'linear' | 'github';
+export interface TicketComment {
+    body: string;
+    createdAt?: string;
+    author?: string;
+}
+export interface TicketRow {
+    id: string;
+    source: TicketSource;
+    title: string;
+    description?: string;
+    status: 'todo' | 'in_progress' | 'done';
+    priority?: 'urgent' | 'high' | 'medium' | 'low';
+    metadata: {
+        identifier?: string;
+        url?: string;
+        labels?: string[];
+        assignee?: string;
+        assigneeKind?: 'user' | 'agent';
+        state?: string;
+        createdAt?: string;
+        dueDate?: string;
+        project?: string;
+        repo?: string;
+        comments?: TicketComment[];
+        images?: string[];
+    };
+}
+export interface TicketListResult {
+    tickets: TicketRow[];
+    cycleInfo: {
+        name: string;
+        startsAt: string;
+        endsAt: string;
+    } | null;
+    sources: {
+        linear: {
+            available: boolean;
+            error?: string;
+        };
+        github: {
+            available: boolean;
+            error?: string;
+        };
+    };
+}
+export interface TicketListOptions {
+    cwd: string;
+    linear: boolean;
+    github: boolean;
+    githubAssignedOnly: boolean;
+}
+export declare function listTickets(options: TicketListOptions): Promise<TicketListResult>;

package/dist/lib/tickets/list.js

@@ -0,0 +1,153 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+const AGENT_ASSIGNEE = /^(claude|codex|gemini|cursor|opencode|antigravity|grok|kimi|droid)$/i;
+function assigneeKind(name) {
+    if (!name)
+        return undefined;
+    return AGENT_ASSIGNEE.test(name.trim()) ? 'agent' : 'user';
+}
+function imageUrls(...bodies) {
+    const urls = new Set();
+    const pattern = /!\[[^\]]*\]\(\s*(https?:\/\/[^)\s]+)|<img\b[^>]*?\bsrc\s*=\s*["'](https?:\/\/[^"']+)/gi;
+    for (const body of bodies) {
+        if (typeof body !== 'string')
+            continue;
+        let match;
+        while ((match = pattern.exec(body)))
+            urls.add(match[1] || match[2]);
+    }
+    return urls.size > 0 ? [...urls] : undefined;
+}
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+async function readLinear(cwd) {
+    const { stdout } = await run('linear', ['tasks', '--json'], {
+        cwd,
+        timeout: 15_000,
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    const data = JSON.parse(stdout);
+    const cycle = data?.cycle;
+    const cycleInfo = cycle?.startsAt && cycle?.endsAt
+        ? { name: String(cycle.name ?? ''), startsAt: String(cycle.startsAt), endsAt: String(cycle.endsAt) }
+        : null;
+    const priority = {
+        1: 'urgent',
+        2: 'high',
+        3: 'medium',
+        4: 'low',
+    };
+    const tickets = (Array.isArray(data?.issues) ? data.issues : []).map((issue) => {
+        const labels = (issue.labels?.nodes ?? []).map((label) => String(label.name));
+        const comments = (issue.comments?.nodes ?? []).map((comment) => ({
+            body: String(comment.body ?? ''),
+            createdAt: comment.createdAt ? String(comment.createdAt) : undefined,
+            author: comment.user?.name ? String(comment.user.name) : undefined,
+        }));
+        const stateType = String(issue.state?.type ?? '');
+        const status = stateType === 'started'
+            ? 'in_progress'
+            : stateType === 'completed' || stateType === 'canceled'
+                ? 'done'
+                : 'todo';
+        const identifier = String(issue.identifier ?? issue.id ?? '');
+        return {
+            id: `linear:${identifier}`,
+            source: 'linear',
+            title: String(issue.title ?? ''),
+            description: issue.description ? String(issue.description) : undefined,
+            status,
+            priority: priority[Number(issue.priority)],
+            metadata: {
+                identifier,
+                url: issue.url ? String(issue.url) : undefined,
+                labels,
+                assignee: issue.assignee?.name ? String(issue.assignee.name) : undefined,
+                assigneeKind: assigneeKind(issue.assignee?.name),
+                state: issue.state?.name ? String(issue.state.name) : undefined,
+                createdAt: issue.createdAt ? String(issue.createdAt) : undefined,
+                dueDate: issue.dueDate ? String(issue.dueDate) : undefined,
+                project: issue.project?.name ? String(issue.project.name) : undefined,
+                comments,
+                images: imageUrls(issue.description, ...comments.map(comment => comment.body)),
+            },
+        };
+    });
+    return { tickets, cycleInfo };
+}
+async function readGithub(cwd, assignedOnly) {
+    const repo = (await run('gh', ['repo', 'view', '--json', 'nameWithOwner', '-q', '.nameWithOwner'], {
+        cwd,
+        timeout: 5_000,
+    })).stdout.trim();
+    if (!repo)
+        throw new Error('No GitHub repository resolved for this workspace.');
+    const args = [
+        'issue', 'list', '--repo', repo, '--state', 'open', '--limit', '50',
+        '--json', 'number,title,state,labels,assignees,url,body,createdAt',
+    ];
+    if (assignedOnly)
+        args.push('--assignee', '@me');
+    const { stdout } = await run('gh', args, { cwd, timeout: 15_000, maxBuffer: 16 * 1024 * 1024 });
+    const issues = JSON.parse(stdout);
+    return issues.map((issue) => {
+        const assignee = issue.assignees?.[0]?.login ? String(issue.assignees[0].login) : undefined;
+        const number = Number(issue.number);
+        return {
+            id: `github:${number}`,
+            source: 'github',
+            title: String(issue.title ?? ''),
+            description: issue.body ? String(issue.body) : undefined,
+            status: String(issue.state ?? '').toLowerCase() === 'closed' ? 'done' : 'todo',
+            metadata: {
+                identifier: `#${number}`,
+                url: issue.url ? String(issue.url) : undefined,
+                labels: (issue.labels ?? []).map((label) => String(label.name)),
+                assignee,
+                assigneeKind: assigneeKind(assignee),
+                state: String(issue.state ?? '').toLowerCase(),
+                createdAt: issue.createdAt ? String(issue.createdAt) : undefined,
+                repo,
+                images: imageUrls(issue.body),
+            },
+        };
+    });
+}
+export async function listTickets(options) {
+    const result = {
+        tickets: [],
+        cycleInfo: null,
+        sources: {
+            linear: { available: false },
+            github: { available: false },
+        },
+    };
+    const [linear, github] = await Promise.all([
+        options.linear
+            ? readLinear(options.cwd).then(value => ({ ok: true, value })).catch(error => ({ ok: false, error }))
+            : Promise.resolve(null),
+        options.github
+            ? readGithub(options.cwd, options.githubAssignedOnly).then(value => ({ ok: true, value })).catch(error => ({ ok: false, error }))
+            : Promise.resolve(null),
+    ]);
+    if (linear?.ok) {
+        result.sources.linear.available = true;
+        result.tickets.push(...linear.value.tickets);
+        result.cycleInfo = linear.value.cycleInfo;
+    }
+    else if (linear) {
+        result.sources.linear.error = errorMessage(linear.error);
+    }
+    if (github?.ok) {
+        result.sources.github.available = true;
+        result.tickets.push(...github.value);
+    }
+    else if (github) {
+        result.sources.github.error = errorMessage(github.error);
+    }
+    return result;
+}