@phnx-labs/agents-cli 1.20.54 → 1.20.56

package/dist/lib/registry.d.ts

@@ -44,6 +44,30 @@ export declare function mcpEntryToInstallSpec(entry: McpServerEntry): {
 } | null;
 /** Look up detailed info for an MCP server by exact name. */
 export declare function getMcpServerInfo(serverName: string, registryName?: string): Promise<McpServerEntry | null>;
+/** One row of a skill index document. */
+export interface SkillIndexEntry {
+    name: string;
+    description?: string;
+    source?: string;
+    identifier?: string;
+    trust_level?: string;
+    repo?: string;
+    path?: string;
+    tags?: string[];
+    author?: string;
+    installs?: number;
+    /** Lowercase hex sha256 of the skill's SKILL.md — written by `agents publish`. */
+    sha256?: string;
+}
+/** Raw shape of the skill index document served by Hermes and compatible registries. */
+export interface SkillIndexDocument {
+    version?: number;
+    generated_at?: string;
+    skill_count?: number;
+    skills: SkillIndexEntry[];
+}
+/** Map a raw skill-index row into the canonical SkillEntry shape. */
+export declare function normalizeSkillEntry(raw: SkillIndexEntry): SkillEntry;
 /** Search skill registries for entries matching a query string. */
 export declare function searchSkillRegistries(query: string, options?: {
     registry?: string;
@@ -66,3 +90,34 @@ export declare function parsePackageIdentifier(identifier: string): {
 };
 /** Resolve a package identifier to an installable package with source metadata. */
 export declare function resolvePackage(identifier: string): Promise<ResolvedPackage | null>;
+/** Lowercase hex sha256 of a file's bytes. Small files only (SKILL.md). */
+export declare function sha256OfFile(file: string): string;
+/**
+ * Parse an 'owner/repo' slug from a git remote URL (https or scp-style ssh).
+ * Returns null if the URL is not a recognizable GitHub-style remote.
+ */
+export declare function parseOwnerRepoFromRemote(remoteUrl: string): string | null;
+/**
+ * Walk a repo's skills/ and build a flat {@link SkillIndexDocument}. Each entry
+ * carries the sha256 of its SKILL.md so install can verify integrity after
+ * cloning — this is the artifact `agents publish` commits + pushes.
+ *
+ * `repoSlug` is the 'owner/repo' the skills are published under, written into
+ * each entry's `repo` field so {@link skillEntryToGitSource} resolves it to
+ * `gh:owner/repo`. `identifier` is set to the skill's directory name so
+ * `agents install skill:<name>` resolves against this index.
+ */
+export declare function buildSkillIndex(repoPath: string, repoSlug: string, opts?: {
+    generatedAt?: string;
+}): SkillIndexDocument;
+/**
+ * Verify a cloned skill's SKILL.md against the sha256 recorded in its registry
+ * entry. Returns ok when the entry carries no sha256 — indexes published before
+ * integrity hashes (or by third parties) simply skip the check. Returns an
+ * error when the file is missing or its hash differs, so install can abort
+ * rather than silently trusting a tampered artifact.
+ */
+export declare function verifySkillIntegrity(repoPath: string, entry: Pick<SkillEntry, 'name' | 'path' | 'sha256'>): {
+    ok: boolean;
+    error?: string;
+};

package/dist/lib/registry.js

@@ -6,8 +6,11 @@
  * with transport, runtime, and argument metadata.
  */
 import * as fs from 'fs';
+import * as path from 'path';
+import { createHash } from 'crypto';
 import { DEFAULT_REGISTRIES } from './types.js';
 import { readMeta, writeMeta } from './state.js';
+import { discoverSkillsFromRepo } from './skills.js';
 const UNSAFE_PACKAGE_SPEC_CHARS = /[;&|`$\s\x00-\x1f\x7f]/;
 const NPM_SPEC_PATTERN = /^(@[a-z0-9][a-z0-9-_.]*\/)?[a-z0-9][a-z0-9-_.]*(@[A-Za-z0-9._+-]+)?$/;
 const PYPI_SPEC_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*(\[[A-Za-z0-9,_-]+\])?(==[A-Za-z0-9._-]+)?$/;
@@ -213,7 +216,7 @@ async function fetchSkillIndex(url, apiKey) {
     return doc;
 }
 /** Map a raw skill-index row into the canonical SkillEntry shape. */
-function normalizeSkillEntry(raw) {
+export function normalizeSkillEntry(raw) {
     return {
         name: raw.name,
         description: raw.description,
@@ -225,6 +228,7 @@ function normalizeSkillEntry(raw) {
         installs: raw.installs,
         tags: raw.tags,
         trustLevel: raw.trust_level,
+        sha256: raw.sha256,
     };
 }
 /** Case-insensitive substring match against the fields users expect to search. */
@@ -418,3 +422,80 @@ export async function resolvePackage(identifier) {
     }
     return null;
 }
+// ============================================================================
+// PUBLISH — generate a self-hosted skill index + verify integrity on install
+// ============================================================================
+/** Lowercase hex sha256 of a file's bytes. Small files only (SKILL.md). */
+export function sha256OfFile(file) {
+    return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+/**
+ * Parse an 'owner/repo' slug from a git remote URL (https or scp-style ssh).
+ * Returns null if the URL is not a recognizable GitHub-style remote.
+ */
+export function parseOwnerRepoFromRemote(remoteUrl) {
+    const s = remoteUrl.trim().replace(/\.git$/, '');
+    // https://github.com/owner/repo  or  git@github.com:owner/repo
+    const m = s.match(/github\.com[/:]([^/]+\/[^/]+)$/);
+    return m ? m[1] : null;
+}
+/**
+ * Walk a repo's skills/ and build a flat {@link SkillIndexDocument}. Each entry
+ * carries the sha256 of its SKILL.md so install can verify integrity after
+ * cloning — this is the artifact `agents publish` commits + pushes.
+ *
+ * `repoSlug` is the 'owner/repo' the skills are published under, written into
+ * each entry's `repo` field so {@link skillEntryToGitSource} resolves it to
+ * `gh:owner/repo`. `identifier` is set to the skill's directory name so
+ * `agents install skill:<name>` resolves against this index.
+ */
+export function buildSkillIndex(repoPath, repoSlug, opts) {
+    const discovered = discoverSkillsFromRepo(repoPath);
+    const skills = discovered.map((s) => ({
+        name: s.name,
+        description: s.metadata.description || undefined,
+        identifier: s.name,
+        source: repoSlug,
+        repo: repoSlug,
+        path: path.relative(repoPath, s.path),
+        author: s.metadata.author,
+        sha256: sha256OfFile(path.join(s.path, 'SKILL.md')),
+    }));
+    return {
+        version: 1,
+        generated_at: opts?.generatedAt,
+        skill_count: skills.length,
+        skills,
+    };
+}
+/**
+ * Verify a cloned skill's SKILL.md against the sha256 recorded in its registry
+ * entry. Returns ok when the entry carries no sha256 — indexes published before
+ * integrity hashes (or by third parties) simply skip the check. Returns an
+ * error when the file is missing or its hash differs, so install can abort
+ * rather than silently trusting a tampered artifact.
+ */
+export function verifySkillIntegrity(repoPath, entry) {
+    if (!entry.sha256)
+        return { ok: true };
+    const rel = entry.path || path.join('skills', entry.name);
+    const skillMd = rel.endsWith('SKILL.md')
+        ? path.join(repoPath, rel)
+        : path.join(repoPath, rel, 'SKILL.md');
+    if (!fs.existsSync(skillMd)) {
+        return {
+            ok: false,
+            error: `Integrity check failed for skill '${entry.name}': SKILL.md not found at ${rel}.`,
+        };
+    }
+    const actual = sha256OfFile(skillMd);
+    const expected = entry.sha256.toLowerCase();
+    if (actual !== expected) {
+        return {
+            ok: false,
+            error: `Integrity check failed for skill '${entry.name}': expected sha256 ${expected}, got ${actual}. ` +
+                `The published SKILL.md does not match the registry index — refusing to install.`,
+        };
+    }
+    return { ok: true };
+}

package/dist/lib/routines.d.ts

@@ -60,6 +60,14 @@ export interface JobConfig {
     prompt: string;
     timezone?: string;
     repo?: string;
+    /**
+     * Fleet allowlist — restrict this routine to specific devices. When omitted
+     * or empty, the routine is unrestricted and fires on every device running the
+     * scheduler. When set, only devices whose `machineId()` matches any entry
+     * (via `normalizeHost`) schedule, fire, catch up, or count this job as
+     * overdue; everywhere else it is inert and `run` refuses with a pointer.
+     */
+    devices?: string[];
     variables?: Record<string, string>;
     sandbox?: boolean;
     allow?: JobAllowConfig;
@@ -77,11 +85,39 @@ export interface RunMeta {
     agent: AgentId;
     workflow?: string;
     pid: number | null;
+    /** Process birth time (epoch ms) recorded at spawn for pid-reuse detection. */
+    spawnedAt?: number;
     status: 'running' | 'completed' | 'failed' | 'timeout';
     startedAt: string;
     completedAt: string | null;
     exitCode: number | null;
 }
+/**
+ * True when the job may execute on this machine: no `devices` allowlist (or
+ * empty), or the allowlist includes this device. Both sides go through
+ * `normalizeHost` so `Yosemite-S0`, `yosemite-s0.tailnet.ts.net`, and
+ * `yosemite-s0` all agree. Every fire path (cron scheduler, webhook,
+ * catchup/overdue, manual run) gates on this.
+ */
+export declare function jobRunsOnThisDevice(config: Pick<JobConfig, 'devices'>): boolean;
+/** Human presentation of a device-affinity mismatch for commands and runner. */
+export interface JobEligibilityResult {
+    /** Full human message, e.g. "Job 'NAME' can only run on: a, b". */
+    message: string;
+    /** One-line copy-paste suggestion, e.g. "agents routines run NAME --host a". */
+    suggestion: string;
+    /** Comma-separated allowed devices label, e.g. "a, b". */
+    allowedLabel: string;
+    /** First allowed device (normalized), useful for the suggested host. */
+    firstHost: string;
+}
+/**
+ * Return null when the job may run here; otherwise return a structured,
+ * human-friendly eligibility failure. Centralizes the message/suggestion
+ * construction so manual run, executeJob, and executeJobDetached stay in
+ * sync. Scheduler/webhook/overdue paths continue to use jobRunsOnThisDevice.
+ */
+export declare function checkJobDeviceEligibility(config: Pick<JobConfig, 'name' | 'devices'>): JobEligibilityResult | null;
 /**
  * List all job configs, scanning project > user routine dirs.
  * Project routines (`<project>/.agents/routines/`) shadow user routines of the
@@ -95,7 +131,12 @@ export declare function listJobs(cwd?: string): JobConfig[];
  * only resolve user routines.
  */
 export declare function readJob(name: string, cwd?: string): JobConfig | null;
-/** Write a job config to disk, omitting fields that match defaults. */
+/** Write a job config to disk, omitting fields that match defaults.
+ *
+ * Updates the one existing supported extension (.yml or .yaml) atomically.
+ * New routines are written as .yml. If both extensions exist for the same
+ * name, the write fails explicitly so we never choose or drop a sibling.
+ */
 export declare function writeJob(config: JobConfig): void;
 /** Delete a job config file by name. Returns true if the file existed. */
 export declare function deleteJob(name: string): boolean;

package/dist/lib/routines.js

@@ -12,7 +12,9 @@ import * as yaml from 'yaml';
 import { Cron } from 'croner';
 import { getRoutinesDir, getRunsDir, ensureAgentsDir, getProjectRoutinesDir } from './state.js';
 import { safeJoin } from './paths.js';
+import { atomicWriteFileSync } from './fs-atomic.js';
 import { ALL_AGENT_IDS } from './agents.js';
+import { machineId, normalizeHost } from './machine-id.js';
 /** Canonical set of accepted GitHub trigger events — single source for validation. */
 export const GITHUB_TRIGGER_EVENTS = [
     'pull_request',
@@ -40,9 +42,38 @@ export function normalizeTriggerEvent(input) {
     };
     return aliases[key] ?? null;
 }
+/**
+ * True when the job may execute on this machine: no `devices` allowlist (or
+ * empty), or the allowlist includes this device. Both sides go through
+ * `normalizeHost` so `Yosemite-S0`, `yosemite-s0.tailnet.ts.net`, and
+ * `yosemite-s0` all agree. Every fire path (cron scheduler, webhook,
+ * catchup/overdue, manual run) gates on this.
+ */
+export function jobRunsOnThisDevice(config) {
+    if (!config.devices || config.devices.length === 0)
+        return true;
+    const self = machineId();
+    return config.devices.some((d) => normalizeHost(d) === self);
+}
+/**
+ * Return null when the job may run here; otherwise return a structured,
+ * human-friendly eligibility failure. Centralizes the message/suggestion
+ * construction so manual run, executeJob, and executeJobDetached stay in
+ * sync. Scheduler/webhook/overdue paths continue to use jobRunsOnThisDevice.
+ */
+export function checkJobDeviceEligibility(config) {
+    if (jobRunsOnThisDevice(config))
+        return null;
+    const allowed = (config.devices ?? []).map((d) => normalizeHost(d));
+    const allowedLabel = allowed.join(', ');
+    const firstHost = allowed[0] ?? 'HOST';
+    const message = `Job '${config.name}' can only run on: ${allowedLabel}`;
+    const suggestion = `agents routines run ${config.name} --host ${firstHost}`;
+    return { message, suggestion, allowedLabel, firstHost };
+}
 /** Default values applied to every job config when fields are omitted. */
 const JOB_DEFAULTS = {
-    mode: 'plan',
+    mode: 'auto',
     effort: 'auto',
     timeout: '10m',
     enabled: true,
@@ -110,6 +141,11 @@ function readJobFile(filePath) {
         const parsed = yaml.parse(content);
         if (!parsed || typeof parsed !== 'object')
             return null;
+        // Fail closed on the legacy singular `device` key. A routine that still
+        // carries it after v12 startup migration is unmigrated state and must be
+        // treated as unavailable/inert rather than unrestricted.
+        if (Object.prototype.hasOwnProperty.call(parsed, 'device'))
+            return null;
         return {
             ...JOB_DEFAULTS,
             ...parsed,
@@ -120,13 +156,25 @@ function readJobFile(filePath) {
         return null;
     }
 }
-/** Write a job config to disk, omitting fields that match defaults. */
+/** Write a job config to disk, omitting fields that match defaults.
+ *
+ * Updates the one existing supported extension (.yml or .yaml) atomically.
+ * New routines are written as .yml. If both extensions exist for the same
+ * name, the write fails explicitly so we never choose or drop a sibling.
+ */
 export function writeJob(config) {
     ensureAgentsDir();
     const jobsDir = getRoutinesDir();
-    const filePath = safeJoin(jobsDir, config.name + '.yml');
+    const ymlPath = safeJoin(jobsDir, config.name + '.yml');
+    const yamlPath = safeJoin(jobsDir, config.name + '.yaml');
+    const ymlExists = fs.existsSync(ymlPath);
+    const yamlExists = fs.existsSync(yamlPath);
+    if (ymlExists && yamlExists) {
+        throw new Error(`Routine '${config.name}' has both .yml and .yaml files; resolve the ambiguity before editing.`);
+    }
+    const filePath = ymlExists ? ymlPath : yamlExists ? yamlPath : ymlPath;
     const output = { ...config };
-    if (output.mode === 'plan')
+    if (output.mode === 'auto')
         delete output.mode;
     if (output.effort === 'auto')
         delete output.effort;
@@ -136,7 +184,10 @@ export function writeJob(config) {
         delete output.enabled;
     if (output.runOnce === false || output.runOnce === undefined)
         delete output.runOnce;
-    fs.writeFileSync(filePath, yaml.stringify(output), 'utf-8');
+    const devArr = output.devices;
+    if (!devArr || devArr.length === 0)
+        delete output.devices;
+    atomicWriteFileSync(filePath, yaml.stringify(output));
 }
 /** Delete a job config file by name. Returns true if the file existed. */
 export function deleteJob(name) {
@@ -219,6 +270,22 @@ export function validateJob(config) {
             errors.push('endAt must be a parseable ISO 8601 / RFC3339 timestamp (e.g., 2026-12-31T23:59:00Z)');
         }
     }
+    if (config.device !== undefined) {
+        errors.push('singular "device" key is no longer supported — replace with devices: [<name>] (an array)');
+    }
+    if (config.devices !== undefined) {
+        if (!Array.isArray(config.devices)) {
+            errors.push('devices must be an array of device names (as shown by `agents devices`)');
+        }
+        else {
+            for (const d of config.devices) {
+                if (typeof d !== 'string' || d.trim() === '') {
+                    errors.push('each entry in devices must be a non-empty device name');
+                    break;
+                }
+            }
+        }
+    }
     return errors;
 }
 /** Validate a job trigger block, returning a list of human-readable errors. */

package/dist/lib/runner.js

@@ -13,11 +13,11 @@
  * limit is detected mid-run (foreground `executeJob` only — detached daemon
  * fires once with the pre-flight pick).
  */
-import { spawn } from 'child_process';
+import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { resolveJobPrompt, parseTimeout, writeRunMeta, getRunDir, } from './routines.js';
+import { resolveJobPrompt, parseTimeout, writeRunMeta, getRunDir, checkJobDeviceEligibility, } from './routines.js';
 import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
@@ -378,6 +378,10 @@ function spawnJobAttempt(cmd, env, attemptLogPath, timeoutMs, combinedLogPath) {
  * failover across healthy same-agent accounts (RUSH-1016).
  */
 export async function executeJob(config, deps) {
+    const eligibility = checkJobDeviceEligibility(config);
+    if (eligibility) {
+        throw new Error(eligibility.message);
+    }
     maybeRotate();
     const launch = await resolveRoutineLaunch(config);
     const primaryVersion = launch.chain[0]?.version ?? config.version;
@@ -407,6 +411,7 @@ export async function executeJob(config, deps) {
         agent: effectiveAgent,
         ...(config.workflow ? { workflow: config.workflow } : {}),
         pid: null,
+        spawnedAt: Date.now(),
         status: 'running',
         startedAt: new Date().toISOString(),
         completedAt: null,
@@ -536,6 +541,11 @@ export async function executeJob(config, deps) {
 }
 /** Spawn a job as a detached process and return immediately with run metadata. */
 export async function executeJobDetached(config) {
+    const eligibility = checkJobDeviceEligibility(config);
+    if (eligibility) {
+        process.stderr.write(`[agents] daemon: skipping '${config.name}' — ${eligibility.message}\n`);
+        throw new Error(eligibility.message);
+    }
     // Pre-flight: pick a healthy version/account so the daemon does not launch
     // into a credit-exhausted install. Detached cannot mid-run failover (no exit
     // wait); the next schedule tick re-selects if this attempt still fails.
@@ -571,6 +581,7 @@ export async function executeJobDetached(config) {
         agent: effectiveAgent,
         ...(config.workflow ? { workflow: config.workflow } : {}),
         pid: null,
+        spawnedAt: Date.now(),
         status: 'running',
         startedAt: new Date().toISOString(),
         completedAt: null,
@@ -691,6 +702,45 @@ function inferFinalStatusFromLog(stdoutPath, agent) {
         return null;
     }
 }
+const MAX_WALL_CLOCK_MS = 24 * 60 * 60 * 1000;
+/**
+ * Verify that a PID still belongs to the process we spawned, not a recycled
+ * OS PID. Uses the recorded `spawnedAt` (epoch ms) from meta.json and
+ * compares against the process's actual start time via `ps`. Returns true
+ * when the PID is alive AND plausibly ours.
+ */
+function isPidOurs(pid, spawnedAt) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch {
+        return false;
+    }
+    if (spawnedAt === undefined)
+        return true;
+    if (process.platform === 'win32')
+        return true;
+    try {
+        const etime = execFileSync('ps', ['-p', String(pid), '-o', 'etime='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        if (!etime)
+            return true;
+        const parts = etime.replace(/-/g, ':').split(':').reverse();
+        let uptimeSec = 0;
+        if (parts[0])
+            uptimeSec += parseInt(parts[0], 10);
+        if (parts[1])
+            uptimeSec += parseInt(parts[1], 10) * 60;
+        if (parts[2])
+            uptimeSec += parseInt(parts[2], 10) * 3600;
+        if (parts[3])
+            uptimeSec += parseInt(parts[3], 10) * 86400;
+        const processStartMs = Date.now() - uptimeSec * 1000;
+        return Math.abs(processStartMs - spawnedAt) < 30_000;
+    }
+    catch {
+        return true;
+    }
+}
 /** Scan all runs marked "running" and finalize any whose process has exited. */
 export function monitorRunningJobs() {
     const runsDir = getRunsDir();
@@ -712,14 +762,17 @@ export function monitorRunningJobs() {
                     continue;
                 if (!meta.pid)
                     continue;
-                try {
-                    process.kill(meta.pid, 0);
+                const runDirPath = path.join(jobRunsPath, runDirEntry.name);
+                const stdoutPath = path.join(runDirPath, 'stdout.log');
+                const wallClockMs = Date.now() - Date.parse(meta.startedAt);
+                if (Number.isFinite(wallClockMs) && wallClockMs > MAX_WALL_CLOCK_MS) {
+                    meta.status = 'timeout';
+                    meta.completedAt = new Date().toISOString();
+                    writeRunMeta(meta);
+                    extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
+                    continue;
                 }
-                catch { /* process no longer running */
-                    const runDirPath = path.join(jobRunsPath, runDirEntry.name);
-                    const stdoutPath = path.join(runDirPath, 'stdout.log');
-                    // Prefer the agent's own success/error marker; fall back to "failed"
-                    // only when the stream ended without one (process killed mid-run).
+                if (!isPidOurs(meta.pid, meta.spawnedAt)) {
                     const inferred = inferFinalStatusFromLog(stdoutPath, meta.agent);
                     if (inferred) {
                         meta.status = inferred.status;

package/dist/lib/scheduler.js

@@ -6,7 +6,7 @@
  * on startup and reloads them on SIGHUP.
  */
 import { Cron } from 'croner';
-import { listJobs, deleteJob, isPastEndAt, setJobEnabled } from './routines.js';
+import { listJobs, deleteJob, isPastEndAt, setJobEnabled, jobRunsOnThisDevice } from './routines.js';
 /** In-memory cron scheduler that triggers a callback when jobs fire. */
 export class JobScheduler {
     jobs = new Map();
@@ -18,8 +18,9 @@ export class JobScheduler {
         const configs = listJobs();
         for (const config of configs) {
             // Trigger-only jobs (no cron schedule) fire via the webhook receiver,
-            // not the cron loop — skip them here.
-            if (config.enabled && config.schedule) {
+            // not the cron loop — skip them here. Jobs pinned to another device
+            // (routines are fleet-synced) never enter this machine's cron loop.
+            if (config.enabled && config.schedule && jobRunsOnThisDevice(config)) {
                 this.schedule(config);
             }
         }

package/dist/lib/teams/agents.js

@@ -8,6 +8,7 @@
  * multiple permission modes (plan, edit, full).
  */
 import { spawn, execSync, execFileSync } from 'child_process';
+import { getAgentsInvocation } from '../daemon.js';
 import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
@@ -1697,12 +1698,11 @@ export class AgentManager {
         return args;
     }
     buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null, profileName = null) {
-        const agentsCli = process.argv[1];
-        const cmd = [
-            process.execPath,
-            agentsCli,
-            ...this.buildRunArgv(agentType, prompt, mode, model, effort, version, profileName),
-        ];
+        // Route through getAgentsInvocation so a teammate launched by the compiled
+        // standalone binary (#315) doesn't relaunch as `agents /$bunfs/root/agents …`
+        // (process.argv[1] is the bun virtual entry there) → "unknown command".
+        const inv = getAgentsInvocation(this.buildRunArgv(agentType, prompt, mode, model, effort, version, profileName));
+        const cmd = [inv.command, ...inv.args];
         if (cwd)
             cmd.push('--cwd', cwd);
         // Pin the session UUID to our agent_id so buildExecEnv keys

package/dist/lib/tmux/binary.d.ts

@@ -8,6 +8,8 @@
  *    subcommand);
  *  - stdout/stderr capture is consistent for the session module to parse.
  */
+/** Oldest tmux release with `run-shell -C`, required by the managed pane-died hook. */
+export declare const MIN_TMUX_VERSION = "3.2";
 /**
  * Locate the tmux binary on PATH. Cached after first call — tmux either is or
  * isn't installed for the duration of the process.
@@ -19,6 +21,8 @@ export declare function findTmuxBinary(): string | null;
 export declare function isTmuxInstalled(): boolean;
 /** Best-effort tmux version string (e.g. "tmux 3.6a"). Returns null when not installed or version probe fails. */
 export declare function getTmuxVersion(): string | null;
+/** True for a `tmux -V` string at or above the supported 3.2 floor. */
+export declare function isTmuxVersionSupported(version: string | null): boolean;
 /**
  * Throw a user-friendly error when tmux isn't installed. Command handlers call
  * this first thing so the error message is the same shape every time.

package/dist/lib/tmux/binary.js

@@ -11,6 +11,9 @@
 import { spawn, spawnSync } from 'child_process';
 import { existsSync } from 'fs';
 let cachedBin;
+let cachedVersion;
+/** Oldest tmux release with `run-shell -C`, required by the managed pane-died hook. */
+export const MIN_TMUX_VERSION = '3.2';
 /**
  * Locate the tmux binary on PATH. Cached after first call — tmux either is or
  * isn't installed for the duration of the process.
@@ -45,13 +48,29 @@ export function isTmuxInstalled() {
 }
 /** Best-effort tmux version string (e.g. "tmux 3.6a"). Returns null when not installed or version probe fails. */
 export function getTmuxVersion() {
+    if (cachedVersion !== undefined)
+        return cachedVersion;
     const bin = findTmuxBinary();
     if (!bin)
         return null;
     const res = spawnSync(bin, ['-V'], { encoding: 'utf8' });
-    if (res.status !== 0)
-        return null;
-    return res.stdout.trim() || null;
+    if (res.status !== 0) {
+        cachedVersion = null;
+        return cachedVersion;
+    }
+    cachedVersion = res.stdout.trim() || null;
+    return cachedVersion;
+}
+/** True for a `tmux -V` string at or above the supported 3.2 floor. */
+export function isTmuxVersionSupported(version) {
+    if (!version)
+        return false;
+    const match = /^tmux\s+(\d+)\.(\d+)/.exec(version.trim());
+    if (!match)
+        return false;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    return major > 3 || (major === 3 && minor >= 2);
 }
 /**
  * Throw a user-friendly error when tmux isn't installed. Command handlers call
@@ -68,6 +87,10 @@ export function assertTmuxAvailable() {
                 : 'Install tmux from https://github.com/tmux/tmux';
         throw new TmuxUnavailableError(`tmux is not installed. ${hint}`);
     }
+    const version = getTmuxVersion();
+    if (!isTmuxVersionSupported(version)) {
+        throw new TmuxUnavailableError(`${version ?? 'tmux version unknown'} is unsupported. agents requires tmux ${MIN_TMUX_VERSION} or newer.`);
+    }
     return bin;
 }
 export class TmuxUnavailableError extends Error {

package/dist/lib/tmux/index.d.ts

@@ -3,6 +3,6 @@
  * (swarmify extension, `agents teams` multiplexer mode, future MCP wrapper)
  * should import from here.
  */
-export { findTmuxBinary, isTmuxInstalled, getTmuxVersion, assertTmuxAvailable, TmuxUnavailableError, TmuxCommandError, runTmux, attachTmux, } from './binary.js';
+export { findTmuxBinary, isTmuxInstalled, getTmuxVersion, isTmuxVersionSupported, MIN_TMUX_VERSION, assertTmuxAvailable, TmuxUnavailableError, TmuxCommandError, runTmux, attachTmux, } from './binary.js';
 export { getDefaultSocketPath, getSessionMetaPath, ensureTmuxDir, } from './paths.js';
 export { assertValidSessionName, slugifyName, hasSession, createSession, killSession, killAll, listSessions, splitPane, sendKeys, capturePane, readSessionMeta, TmuxSessionError, type SessionMeta, type CreateSessionOptions, type ListedSession, type SplitOptions, type SendOptions, type CaptureOptions, } from './session.js';

package/dist/lib/tmux/index.js

@@ -3,6 +3,6 @@
  * (swarmify extension, `agents teams` multiplexer mode, future MCP wrapper)
  * should import from here.
  */
-export { findTmuxBinary, isTmuxInstalled, getTmuxVersion, assertTmuxAvailable, TmuxUnavailableError, TmuxCommandError, runTmux, attachTmux, } from './binary.js';
+export { findTmuxBinary, isTmuxInstalled, getTmuxVersion, isTmuxVersionSupported, MIN_TMUX_VERSION, assertTmuxAvailable, TmuxUnavailableError, TmuxCommandError, runTmux, attachTmux, } from './binary.js';
 export { getDefaultSocketPath, getSessionMetaPath, ensureTmuxDir, } from './paths.js';
 export { assertValidSessionName, slugifyName, hasSession, createSession, killSession, killAll, listSessions, splitPane, sendKeys, capturePane, readSessionMeta, TmuxSessionError, } from './session.js';