@phnx-labs/agents-cli 1.20.54 → 1.20.55

package/dist/lib/devices/sync.d.ts

@@ -11,6 +11,13 @@ import type { PendingDevice } from './pending.js';
  * the wrong account). Returns undefined when the username isn't a safe ssh
  * identifier, so a weird value never lands in the registry. */
 export declare function localLoginUser(): string | undefined;
+/**
+ * Reduce a raw OS username to a safe ssh account, or undefined. Windows reports
+ * the login as `COMPUTER\user` / `DOMAIN\user`; the ssh account is the bare name
+ * after the backslash — without this strip the `\` fails the charset guard and
+ * Windows boxes never pin a user. Pure, so the platform-specific munging is
+ * unit-tested without reading the real OS user. */
+export declare function sanitizeLoginUser(raw: string | undefined): string | undefined;
 /**
  * Fill in a device's login user during sync WITHOUT ever clobbering an account
  * the user pinned. Precedence: an existing registered user wins; else the local

package/dist/lib/devices/sync.js

@@ -34,7 +34,19 @@ export function localLoginUser() {
     catch {
         u = process.env.USER || process.env.USERNAME || undefined;
     }
-    return u && /^[a-zA-Z0-9._-]+$/.test(u) ? u : undefined;
+    return sanitizeLoginUser(u);
+}
+/**
+ * Reduce a raw OS username to a safe ssh account, or undefined. Windows reports
+ * the login as `COMPUTER\user` / `DOMAIN\user`; the ssh account is the bare name
+ * after the backslash — without this strip the `\` fails the charset guard and
+ * Windows boxes never pin a user. Pure, so the platform-specific munging is
+ * unit-tested without reading the real OS user. */
+export function sanitizeLoginUser(raw) {
+    if (!raw)
+        return undefined;
+    const bare = raw.includes('\\') ? raw.slice(raw.lastIndexOf('\\') + 1) : raw;
+    return /^[a-zA-Z0-9._-]+$/.test(bare) ? bare : undefined;
 }
 /**
  * Fill in a device's login user during sync WITHOUT ever clobbering an account

package/dist/lib/exec.js

@@ -927,14 +927,16 @@ async function runInTmux(options, executable, args) {
         // When the AGENT pane dies, detach the client (don't kill) so the session
         // survives just long enough to read the dead pane's exit status below. The
         // `#{hook_pane}` guard scopes this to the agent pane only: if the user splits
-        // the window and exits one of THEIR panes, the else-branch `kill-pane` closes
-        // that split in place instead of detaching everyone (the pane-died hook runs
-        // in the dead pane's context, so bare `kill-pane` targets it). Without the
-        // guard, exiting any split kicked the user clean out of tmux.
-        await setSessionHook(name, 'pane-died', agentPaneDiedHook(name, pane), socket);
-        // Stamp the schema marker so the daemon reconcile (which retrofits older
-        // sessions) recognizes this one as already current and skips it.
-        await markSessionHookSchema(name, socket);
+        // the window and exits one of THEIR panes, the else-branch closes that split
+        // in place instead of detaching everyone (`run-shell -C` executes the
+        // targeted kill inside tmux's server command queue, avoiding a second
+        // client racing the same socket under load, #965). Without the guard,
+        // exiting any split kicked the user clean out of tmux.
+        const hookInstalled = await setSessionHook(name, 'pane-died', agentPaneDiedHook(name, pane), socket);
+        // Stamp the schema marker only after tmux accepted the hook. A failed
+        // install stays unmarked so daemon reconciliation retries it later.
+        if (hookInstalled)
+            await markSessionHookSchema(name, socket);
         // Record the agent's OS pid (the pane leaf, thanks to `exec`) WITH its tmux
         // pane so the active-scan attributes it exactly and shows the %pane.
         let panePid = 0;

package/dist/lib/overdue.js

@@ -14,7 +14,7 @@
 import { Cron } from 'croner';
 import * as os from 'os';
 import { spawn } from 'child_process';
-import { listJobs, getLatestRun } from './routines.js';
+import { listJobs, getLatestRun, jobRunsOnThisDevice } from './routines.js';
 // Tolerance between "expected fire" and "recorded run start" — accounts for
 // the small gap between the cron tick and when the runner writes meta.json.
 const GRACE_MS = 60_000;
@@ -47,6 +47,11 @@ export function detectOverdueJobs(now = new Date()) {
         // Trigger-only jobs (no cron schedule) never have an expected fire time.
         if (!job.schedule)
             continue;
+        // A job pinned to another device is that device's to run, notify, and
+        // catch up — flagging it here would make every machine in the fleet nag
+        // (and `catchup` fire) for a job that must not run locally.
+        if (!jobRunsOnThisDevice(job))
+            continue;
         let expected = null;
         try {
             const cronOptions = { paused: true };

package/dist/lib/profiles-presets.js

@@ -88,6 +88,58 @@ export const PRESETS = [
             ANTHROPIC_SMALL_FAST_MODEL: 'deepseek/deepseek-chat-v3-0324',
         },
     },
+    {
+        name: 'open-claude',
+        description: 'Open-weight coding via OpenRouter inside Claude Code (Qwen3 Coder Next, 256K ctx, $0.15/$0.80 per 1M). HEADLESS-SAFE — best general preset for open-claude usage with Claude Code harness.',
+        ...OPENROUTER_AUTH,
+        env: {
+            ANTHROPIC_BASE_URL: OPENROUTER_BASE,
+            ANTHROPIC_MODEL: 'qwen/qwen3-coder-next',
+            ANTHROPIC_SMALL_FAST_MODEL: 'qwen/qwen3-coder-next',
+        },
+    },
+    {
+        name: 'claude-spark',
+        description: 'Meta Claude Spark 1.1 via OpenRouter inside Claude Code (open alternative). Model: meta/claude-spark-1.1 — free via opencode, now usable in Claude Code UI. HEADLESS-SAFE. For open-claude spark usage.',
+        ...OPENROUTER_AUTH,
+        env: {
+            ANTHROPIC_BASE_URL: OPENROUTER_BASE,
+            ANTHROPIC_MODEL: 'meta/claude-spark-1.1',
+            ANTHROPIC_SMALL_FAST_MODEL: 'meta/claude-spark-1.1',
+        },
+    },
+    // ----- OpenCode CLI (open-claude harness) -----
+    {
+        name: 'opencode',
+        description: 'OpenCode default — uses your configured model via opencode auth. Run `opencode auth` to login, then `agents run opencode --model meta/claude-spark-1.1 "prompt"` for spark usage.',
+        provider: 'opencode',
+        host: 'opencode',
+        authEnvVar: 'OPENCODE_API_KEY',
+        authOptional: true,
+        env: {},
+    },
+    {
+        name: 'opencode-spark',
+        description: 'Meta Claude Spark 1.1 via OpenCode (free, headless-safe). Pinned to meta/claude-spark-1.1 — best for open-claude usage with opencode harness.',
+        provider: 'opencode',
+        host: 'opencode',
+        authEnvVar: 'OPENCODE_API_KEY',
+        authOptional: true,
+        env: {
+            OPENCODE_MODEL: 'meta/claude-spark-1.1',
+        },
+    },
+    {
+        name: 'opencode-qwen',
+        description: 'Qwen3 Coder Next via OpenCode (open-claude path). Use `agents run opencode-qwen "prompt"` — free via opencode provider.',
+        provider: 'opencode',
+        host: 'opencode',
+        authEnvVar: 'OPENCODE_API_KEY',
+        authOptional: true,
+        env: {
+            OPENCODE_MODEL: 'qwen/qwen3-coder-next',
+        },
+    },
     // ----- xAI Grok Build CLI (native host) -----
     {
         name: 'grok-fast',

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,15 @@ export interface JobConfig {
     prompt: string;
     timezone?: string;
     repo?: string;
+    /**
+     * Pin this routine to one machine. `~/.agents/routines/` is synced to every
+     * device via the user repo, so without a pin an enabled routine fires on
+     * EVERY machine running the scheduler. When set, only the device whose
+     * `machineId()` matches (normalized hostname, e.g. `yosemite-s0`) schedules,
+     * fires, catches up, or counts this job as overdue; everywhere else it is
+     * inert and `run` refuses with an `agents ssh` pointer.
+     */
+    device?: string;
     variables?: Record<string, string>;
     sandbox?: boolean;
     allow?: JobAllowConfig;
@@ -77,11 +86,20 @@ 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 `device` pin, or the pin
+ * names 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, 'device'>): boolean;
 /**
  * List all job configs, scanning project > user routine dirs.
  * Project routines (`<project>/.agents/routines/`) shadow user routines of the

package/dist/lib/routines.js

@@ -13,6 +13,7 @@ import { Cron } from 'croner';
 import { getRoutinesDir, getRunsDir, ensureAgentsDir, getProjectRoutinesDir } from './state.js';
 import { safeJoin } from './paths.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 +41,20 @@ export function normalizeTriggerEvent(input) {
     };
     return aliases[key] ?? null;
 }
+/**
+ * True when the job may execute on this machine: no `device` pin, or the pin
+ * names 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.device)
+        return true;
+    return normalizeHost(config.device) === machineId();
+}
 /** Default values applied to every job config when fields are omitted. */
 const JOB_DEFAULTS = {
-    mode: 'plan',
+    mode: 'auto',
     effort: 'auto',
     timeout: '10m',
     enabled: true,
@@ -126,7 +138,7 @@ export function writeJob(config) {
     const jobsDir = getRoutinesDir();
     const filePath = safeJoin(jobsDir, config.name + '.yml');
     const output = { ...config };
-    if (output.mode === 'plan')
+    if (output.mode === 'auto')
         delete output.mode;
     if (output.effort === 'auto')
         delete output.effort;
@@ -219,6 +231,11 @@ 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) {
+        if (typeof config.device !== 'string' || config.device.trim() === '') {
+            errors.push('device must be a non-empty device name (as shown by `agents devices`, e.g. yosemite-s0)');
+        }
+    }
     return errors;
 }
 /** Validate a job trigger block, returning a list of human-readable errors. */

package/dist/lib/runner.js

@@ -13,7 +13,7 @@
  * 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';
@@ -407,6 +407,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,
@@ -571,6 +572,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 +693,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 +753,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/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';