@phnx-labs/agents-cli 1.20.88 → 1.20.89

package/dist/lib/factory/snapshot.js

@@ -0,0 +1,209 @@
+/**
+ * Read-only Software Factory state aggregation.
+ *
+ * ~/.agents/factory.yml example:
+ *
+ * ceiling: 4
+ * max_dispatch_per_tick: 2
+ * per_project:
+ *   Agents CLI: { weight: 2, cap: 2 }
+ * idle_boxes: [yosemite-m1, yosemite-m2]
+ * digest: { times: ["09:00", "17:00"], tz: America/Los_Angeles }
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { execFile as execFileCallback } from 'child_process';
+import { promisify } from 'util';
+import * as yaml from 'yaml';
+import { getActiveSessions } from '../session/active.js';
+import { serializeActiveSessionsForJson } from '../../commands/sessions.js';
+import { readAuthHealthCache } from '../auth-health.js';
+import { readStatsCache } from '../devices/stats-cache.js';
+const execFile = promisify(execFileCallback);
+export const FACTORY_PROJECTS = [
+    { name: 'Prix', repo: 'phnx-labs/prix' },
+    { name: 'Rush App', repo: 'phnx-labs/rush' },
+    { name: 'Rush CLI', repo: 'phnx-labs/rush-cli' },
+    { name: 'Agents CLI', repo: 'phnx-labs/agents-cli' },
+    { name: 'Linear CLI', repo: 'phnx-labs/linear-cli' },
+];
+const defaults = () => ({
+    source: 'default',
+    ceiling: 4,
+    max_dispatch_per_tick: 2,
+    per_project: {},
+    idle_boxes: [],
+    digest: { times: [], tz: Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC' },
+});
+export function readFactoryConfig(home) {
+    const file = path.join(home, '.agents', 'factory.yml');
+    if (!fs.existsSync(file))
+        return defaults();
+    const raw = yaml.parse(fs.readFileSync(file, 'utf8'));
+    if (!raw || typeof raw !== 'object')
+        throw new Error(`${file} must contain a YAML mapping`);
+    const base = defaults();
+    return {
+        source: 'file',
+        ceiling: integer(raw.ceiling ?? base.ceiling, 'ceiling'),
+        max_dispatch_per_tick: integer(raw.max_dispatch_per_tick ?? base.max_dispatch_per_tick, 'max_dispatch_per_tick'),
+        per_project: parseProjectConfig(raw.per_project),
+        idle_boxes: stringArray(raw.idle_boxes, 'idle_boxes'),
+        digest: raw.digest ? {
+            times: stringArray(raw.digest.times, 'digest.times'),
+            tz: typeof raw.digest.tz === 'string' ? raw.digest.tz : base.digest.tz,
+        } : base.digest,
+    };
+}
+function integer(value, name) {
+    if (!Number.isInteger(value) || value < 0)
+        throw new Error(`factory.yml ${name} must be a non-negative integer`);
+    return value;
+}
+function stringArray(value, name) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((v) => typeof v !== 'string'))
+        throw new Error(`factory.yml ${name} must be a string array`);
+    return value;
+}
+function parseProjectConfig(value) {
+    if (value === undefined)
+        return {};
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('factory.yml per_project must be a mapping');
+    return Object.fromEntries(Object.entries(value).map(([name, item]) => {
+        const record = item;
+        return [name, { weight: integer(record?.weight, `per_project.${name}.weight`), cap: integer(record?.cap, `per_project.${name}.cap`) }];
+    }));
+}
+function json(text) {
+    return JSON.parse(text);
+}
+function issueCount(payload) {
+    if (Array.isArray(payload))
+        return payload.length;
+    if (payload && typeof payload === 'object') {
+        const record = payload;
+        if (typeof record.count === 'number')
+            return record.count;
+        if (Array.isArray(record.issues))
+            return record.issues.length;
+    }
+    return 0;
+}
+export function queueCounts(todoPayload, openPayload) {
+    const issues = openPayload && typeof openPayload === 'object' && Array.isArray(openPayload.issues)
+        ? openPayload.issues : [];
+    const blocked = issues.filter((issue) => {
+        const state = issue.state && typeof issue.state === 'object' ? issue.state : {};
+        const labels = issue.labels && typeof issue.labels === 'object' && Array.isArray(issue.labels.nodes)
+            ? issue.labels.nodes : [];
+        return String(state.name ?? '').toLowerCase().includes('block') || labels.some((label) => String(label.name ?? '').toLowerCase() === 'blocked');
+    }).length;
+    const inProgress = issues.filter((issue) => {
+        const state = issue.state && typeof issue.state === 'object' ? issue.state : {};
+        return String(state.type ?? '').toLowerCase() === 'started' && !String(state.name ?? '').toLowerCase().includes('block');
+    }).length;
+    return { todo: issueCount(todoPayload), inProgress, blocked };
+}
+export function parsePullRequests(repo, payload) {
+    if (!Array.isArray(payload))
+        return [];
+    return payload.map((raw) => {
+        const pr = raw;
+        const checks = Array.isArray(pr.statusCheckRollup) ? pr.statusCheckRollup : [];
+        const states = checks.map((check) => String(check.conclusion ?? check.state ?? check.status ?? '').toUpperCase());
+        const ci = states.some((s) => ['FAILURE', 'ERROR', 'CANCELLED', 'TIMED_OUT'].includes(s)) ? 'failing'
+            : states.some((s) => ['', 'PENDING', 'QUEUED', 'IN_PROGRESS'].includes(s)) ? 'pending'
+                : states.length > 0 ? 'passing' : 'none';
+        return {
+            repo,
+            number: Number(pr.number),
+            ci,
+            review: String(pr.reviewDecision ?? 'none').toLowerCase(),
+            mergeable: String(pr.mergeable ?? 'unknown').toLowerCase(),
+        };
+    });
+}
+export function parseDevices(payload, cached = {}) {
+    const rows = Array.isArray(payload) ? payload : [];
+    return rows.map((raw) => {
+        const row = raw;
+        const name = String(row.name ?? row.host ?? '');
+        const stats = row.stats && typeof row.stats === 'object' ? row.stats : cached[name] ?? row;
+        const candidate = stats.loadPercent ?? stats.load ?? stats.loadPct;
+        const load = typeof candidate === 'number' && Number.isFinite(candidate) ? candidate : null;
+        return { name, load, idle: row.idle === true || (load !== null && load < 20) };
+    }).filter((row) => row.name.length > 0);
+}
+export function readRecentRuns(home, limit = 3) {
+    const root = path.join(home, '.agents', '.history', 'runs');
+    if (!fs.existsSync(root))
+        return [];
+    const found = [];
+    for (const routine of fs.readdirSync(root)) {
+        const routineDir = path.join(root, routine);
+        if (!fs.statSync(routineDir).isDirectory())
+            continue;
+        const routineRuns = [];
+        for (const run of fs.readdirSync(routineDir)) {
+            const file = path.join(routineDir, run, 'meta.json');
+            if (!fs.existsSync(file))
+                continue;
+            try {
+                const meta = JSON.parse(fs.readFileSync(file, 'utf8'));
+                const started = Date.parse(String(meta.startedAt ?? meta.createdAt ?? ''));
+                const ended = Date.parse(String(meta.finishedAt ?? meta.completedAt ?? meta.updatedAt ?? ''));
+                const duration = typeof meta.durationMs === 'number' ? meta.durationMs : Number.isFinite(started) && Number.isFinite(ended) ? ended - started : null;
+                routineRuns.push({ routine, status: String(meta.status ?? 'unknown'), durationMs: duration, mtime: fs.statSync(file).mtimeMs });
+            }
+            catch { /* A concurrently-written or malformed run is not a completed outcome. */ }
+        }
+        found.push(...routineRuns.sort((a, b) => b.mtime - a.mtime).slice(0, limit));
+    }
+    return found.sort((a, b) => b.mtime - a.mtime).map(({ mtime: _, ...run }) => run);
+}
+function latestClaudeVerdict(entries) {
+    return Object.entries(entries)
+        .filter(([key]) => key.split(':').includes('claude'))
+        .map(([, value]) => value)
+        .sort((a, b) => b.checkedAt - a.checkedAt)[0]?.verdict ?? null;
+}
+export async function buildFactorySnapshot(overrides = {}) {
+    const deps = {
+        home: os.homedir(),
+        now: () => new Date(),
+        activeSessions: () => getActiveSessions(),
+        run: async (file, args) => (await execFile(file, args, { maxBuffer: 10 * 1024 * 1024 })).stdout,
+        readAuth: readAuthHealthCache,
+        readDeviceStats: readStatsCache,
+        ...overrides,
+    };
+    const linear = path.join(deps.home, '.agents', 'skills', 'linear', 'scripts', 'linear');
+    const safeRun = async (file, args) => {
+        try {
+            return json(await deps.run(file, args));
+        }
+        catch {
+            return null;
+        }
+    };
+    const sessionsPromise = deps.activeSessions().then(serializeActiveSessionsForJson);
+    const queuePromise = Promise.all(FACTORY_PROJECTS.map(async ({ name }) => {
+        const query = (status) => safeRun(linear, ['tasks', '--project', name, '--label', 'pilot', '--status', status, '--cycle', 'all', '--all', '--json']);
+        const [todo, open] = await Promise.all([query('todo'), query('open')]);
+        return [name, queueCounts(todo, open)];
+    })).then(Object.fromEntries);
+    const prsPromise = Promise.all(FACTORY_PROJECTS.map(async ({ repo }) => parsePullRequests(repo, await safeRun('gh', ['pr', 'list', '--repo', repo, '--state', 'open', '--json', 'number,title,statusCheckRollup,reviewDecision,mergeable'])))).then((rows) => rows.flat());
+    // `devices list --json` is the registry's read-only JSON surface. Load comes
+    // from the daemon-warmed cache so snapshot never probes or writes reachability.
+    const devicesPromise = safeRun('agents', ['devices', 'list', '--json']).then((payload) => parseDevices(payload, deps.readDeviceStats()));
+    const [sessions, queues, prs, devices] = await Promise.all([sessionsPromise, queuePromise, prsPromise, devicesPromise]);
+    return {
+        generatedAt: deps.now().toISOString(), sessions, queues, prs, devices,
+        recentRuns: readRecentRuns(deps.home), auth: { claude: latestClaudeVerdict(deps.readAuth()) },
+        config: readFactoryConfig(deps.home),
+    };
+}

package/dist/lib/fs-atomic.d.ts

@@ -16,9 +16,22 @@ export declare function atomicWriteFileSync(filePath: string, content: string, o
  * 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.
+ *
+ * `fn` is handed a `heartbeat()` it can call during a long, fully SYNCHRONOUS
+ * critical section. proper-lockfile keeps a held lock "alive" by refreshing its
+ * lockfile mtime on a `setTimeout` every `stale/2` — but that timer only fires
+ * when the event loop gets a turn. A synchronous hold that outruns `stale`
+ * (e.g. the scrypt-bound rotation loop in filestore.ts, ~16s on a real store)
+ * never yields, so the timer cannot run: the lock ages past `stale` mid-hold and a
+ * peer contending for it treats the live holder as crashed, breaks the lock, and
+ * interleaves — corrupting the invariant the lock exists to protect, with no crash
+ * involved. `heartbeat()` drives the same refresh synchronously (bumps the lockfile
+ * mtime), so a long sync holder stays fresh while the short `stale` window still
+ * detects a genuinely crashed holder within LOCK_STALE_MS. Callers whose critical
+ * section is short (a single read-modify-write) can ignore it.
  */
 export interface FileLockOptions {
     staleMs?: number;
     acquireTimeoutMs?: number;
 }
-export declare function withFileLock<T>(filePath: string, fn: () => T, opts?: FileLockOptions): T;
+export declare function withFileLock<T>(filePath: string, fn: (heartbeat: () => void) => T, opts?: FileLockOptions): T;

package/dist/lib/fs-atomic.js

@@ -58,12 +58,20 @@ export function atomicWriteFileSync(filePath, content, options = 'utf-8') {
 export function withFileLock(filePath, fn, opts = {}) {
     let release = null;
     let lastError;
+    // Set if a peer breaks this lock while we hold it. proper-lockfile reports that
+    // from its own refresh TIMER, so the default handler rethrows asynchronously —
+    // an uncatchable crash of the whole CLI process, from a callback no caller is
+    // on the stack for. Capture it instead and surface it synchronously below.
+    let compromised = null;
     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: staleMs });
+            release = lockfile.lockSync(filePath, {
+                stale: staleMs,
+                onCompromised: (err) => { compromised = err; },
+            });
             break;
         }
         catch (err) {
@@ -78,10 +86,34 @@ export function withFileLock(filePath, fn, opts = {}) {
         const message = lastError instanceof Error ? lastError.message : String(lastError);
         throw new Error(`Could not acquire lock for ${filePath} after ${acquireTimeoutMs}ms: ${message}`);
     }
+    // proper-lockfile's lock dir is `<filePath>.lock`; touching its mtime is exactly
+    // what proper-lockfile's own async updater does, so the staleness check keys off
+    // a fresh mtime. Best-effort: a failed touch just leaves the async updater's
+    // behaviour unchanged (no worse than before this heartbeat existed).
+    const lockDir = `${filePath}.lock`;
+    const heartbeat = () => {
+        try {
+            const now = new Date();
+            fs.utimesSync(lockDir, now, now);
+        }
+        catch { /* best effort */ }
+    };
     try {
-        return fn();
+        const result = fn(heartbeat);
+        // A compromised lock means a peer may have written under us — the caller must
+        // not treat the result as if it held exclusivity throughout.
+        if (compromised) {
+            throw new Error(`Lock for ${filePath} was broken by another process while held: ` +
+                `${compromised.message}`);
+        }
+        return result;
     }
     finally {
-        release();
+        // Releasing a lock a peer already stole throws ENOTACQUIRED; that is the
+        // stolen case, already reported above, so don't mask it with a teardown error.
+        try {
+            release();
+        }
+        catch { /* already gone */ }
     }
 }

package/dist/lib/funnel.d.ts

@@ -2,4 +2,5 @@ export declare const FUNNEL_PORTS: readonly [443, 8443, 10000];
 export type FunnelPort = typeof FUNNEL_PORTS[number];
 export declare function parseFunnelPort(value: string | number): FunnelPort;
 export declare function buildFunnelStatusCommand(): string;
+export declare function buildFunnelDownCommand(publicPort: FunnelPort): string;
 export declare function buildFunnelUpCommand(publicPort: FunnelPort, localPort: number): string;

package/dist/lib/funnel.js

@@ -9,6 +9,14 @@ export function parseFunnelPort(value) {
 export function buildFunnelStatusCommand() {
     return 'tailscale funnel status';
 }
+export function buildFunnelDownCommand(publicPort) {
+    return [
+        'tailscale',
+        'funnel',
+        `--https=${publicPort}`,
+        'off',
+    ].map(shellQuote).join(' ');
+}
 export function buildFunnelUpCommand(publicPort, localPort) {
     if (!Number.isInteger(localPort) || localPort <= 0 || localPort > 65535) {
         throw new Error('Local port must be between 1 and 65535');

package/dist/lib/menubar/MenubarHelper.app/Contents/_CodeSignature/CodeResources

@@ -6,7 +6,7 @@
 	<dict>
 		<key>Resources/AppIcon.icns</key>
 		<data>
-		DFq5H08EkhgWIC3UvGMR9B58BZw=
+		jOjZVimcFRHoP2VPzgn8uM8mjkA=
 		</data>
 	</dict>
 	<key>files2</key>
@@ -15,7 +15,7 @@
 		<dict>
 			<key>hash2</key>
 			<data>
-			mBSjM6jlvN7J1jQowsvqTl7CHM0pur0e6qsHMuzk5k0=
+			GFvSLeNYJ3ASxW3OzcuiB4aID0gZUBkpozmWZkbTFNw=
 			</data>
 		</dict>
 	</dict>

package/dist/lib/menubar/install-menubar.d.ts

@@ -124,6 +124,48 @@ export declare function disableMenubarService(): void;
  * Best-effort — never throws into startup.
  */
 export declare function installMenubarLaunchAgentOnUpgrade(): void;
+/** One step of `agents menubar setup`, and how it came out. */
+export interface SetupStep {
+    /** What was configured. */
+    name: string;
+    /** `ok` — already correct or now correct; `changed` — this run fixed it;
+     *  `failed` — could not be configured (setup reports and exits nonzero). */
+    outcome: 'ok' | 'changed' | 'failed';
+    detail: string;
+}
+export interface SetupResult {
+    steps: SetupStep[];
+    /** Every step landed on `ok`/`changed` and exactly one helper is running. */
+    configured: boolean;
+    status: MenubarStatus;
+}
+/**
+ * Decide which live helper processes must be ended so exactly one status item
+ * survives. Pure so the choice is unit-testable without a live menu bar.
+ *
+ * EVERY current process is ended, including the wanted one: the caller
+ * re-kickstarts the launchd service straight after, so the survivor is the one
+ * launchd owns (RunAtLoad + KeepAlive), not whichever copy happened to win a
+ * race. Picking a survivor from a `ps` listing cannot do this — the list says
+ * nothing about which pid launchd will keep alive, so leaving one alive risks
+ * keeping the un-managed copy and re-creating the duplicate on next login.
+ */
+export declare function processesToEnd(status: Pick<MenubarStatus, 'instances' | 'foreignInstances'>): MenubarProcess[];
+/**
+ * `agents menubar setup` — configure the menu bar end-to-end, idempotently.
+ *
+ * The one command that gets a machine to the intended state: exactly one status
+ * item, owned by a launchd service that starts it at login and restarts it if it
+ * dies. Each concern is a reported step, so a partial failure names itself
+ * instead of hiding behind "enabled".
+ *
+ *   1. bundle      — install/refresh the .app at the stable App Support path
+ *   2. signature   — a valid code identity (macOS 26+ SIGKILLs an invalid one)
+ *   3. duplicates  — end every live helper, so the only survivor is launchd's
+ *   4. login item  — write the plist (RunAtLoad + KeepAlive) and bootstrap it
+ *   5. single      — verify exactly one helper came back up
+ */
+export declare function runMenubarSetup(): SetupResult;
 /** A live MenubarHelper process: its pid and the executable it is running. */
 export interface MenubarProcess {
     pid: number;
@@ -131,19 +173,26 @@ export interface MenubarProcess {
 }
 /**
  * Split the live MenubarHelper processes into the installed bundle's own
- * (`running`) and every other copy (`foreign`).
+ * (`own`) and every other copy (`foreign`).
  *
  * `pgrep -f MenubarHelper` conflated the two, so a stray dev build could hold
  * the global Cmd-Shift-V chord (RegisterEventHotKey is first-come) while status
  * still reported a healthy `running: yes` — the paste was dead and nothing said
  * so. A foreign copy is the thing to look for, so name it.
  *
+ * `own` is a LIST, not a boolean: two copies of the INSTALLED bundle can run at
+ * once (launchd's KeepAlive service plus a LaunchServices/`open` launch of the
+ * same .app), which is the duplicate the user actually sees — two agents marks
+ * in the menu bar. Collapsing them to `running: true` reported that state as
+ * healthy. The helper now refuses to be the second (SingleInstance.swift), and
+ * `agents menubar setup` ends any duplicate a pre-fix helper left behind.
+ *
  * Identity comes from `comm` (the resolved executable), never from a substring
  * of the command line: matching the latter flags any shell that merely mentions
  * MenubarHelper. `command` is consulted only to drop `--notify` one-shots.
  */
 export declare function classifyMenubarProcesses(commOutput: string, commandOutput: string, installedExec: string): {
-    running: boolean;
+    own: MenubarProcess[];
     foreign: MenubarProcess[];
 };
 export interface MenubarStatus {
@@ -155,6 +204,8 @@ export interface MenubarStatus {
     stale: boolean;
     serviceInstalled: boolean;
     running: boolean;
+    /** Live processes of the INSTALLED bundle. More than one is the duplicate. */
+    instances: MenubarProcess[];
     /** Live MenubarHelper processes that are NOT the installed bundle. */
     foreignInstances: MenubarProcess[];
     disabledByUser: boolean;