@orgloop/agentctl 1.2.0 → 1.3.0

package/dist/daemon/metrics.js

@@ -5,8 +5,7 @@ export class MetricsRegistry {
     sessionsTotalCompleted = 0;
     sessionsTotalFailed = 0;
     sessionsTotalStopped = 0;
-    fusesFiredTotal = 0;
-    clustersDeletedTotal = 0;
+    fusesExpiredTotal = 0;
     sessionDurations = []; // seconds
     constructor(sessionTracker, lockManager, fuseEngine) {
         this.sessionTracker = sessionTracker;
@@ -28,9 +27,8 @@ export class MetricsRegistry {
         if (durationSeconds != null)
             this.sessionDurations.push(durationSeconds);
     }
-    recordFuseFired() {
-        this.fusesFiredTotal++;
-        this.clustersDeletedTotal++;
+    recordFuseExpired() {
+        this.fusesExpiredTotal++;
     }
     generateMetrics() {
         const lines = [];
@@ -54,8 +52,7 @@ export class MetricsRegistry {
         c("agentctl_sessions_total", "Total sessions by status", this.sessionsTotalCompleted, 'status="completed"');
         c("agentctl_sessions_total", "Total sessions by status", this.sessionsTotalFailed, 'status="failed"');
         c("agentctl_sessions_total", "Total sessions by status", this.sessionsTotalStopped, 'status="stopped"');
-        c("agentctl_fuses_fired_total", "Total fuses fired", this.fusesFiredTotal);
-        c("agentctl_kind_clusters_deleted_total", "Total Kind clusters deleted", this.clustersDeletedTotal);
+        c("agentctl_fuses_expired_total", "Total fuses expired", this.fusesExpiredTotal);
         // Histogram (session duration)
         lines.push("# HELP agentctl_session_duration_seconds Session duration histogram");
         lines.push("# TYPE agentctl_session_duration_seconds histogram");

package/dist/daemon/server.js

@@ -1,9 +1,11 @@
+import { execFile } from "node:child_process";
 import { EventEmitter } from "node:events";
 import fs from "node:fs/promises";
 import http from "node:http";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
+import { promisify } from "node:util";
 import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { OpenClawAdapter } from "../adapters/openclaw.js";
@@ -11,29 +13,38 @@ import { OpenCodeAdapter } from "../adapters/opencode.js";
 import { PiAdapter } from "../adapters/pi.js";
 import { PiRustAdapter } from "../adapters/pi-rust.js";
 import { migrateLocks } from "../migration/migrate-locks.js";
+import { saveEnvironment } from "../utils/daemon-env.js";
+import { clearBinaryCache } from "../utils/resolve-binary.js";
 import { FuseEngine } from "./fuse-engine.js";
 import { LockManager } from "./lock-manager.js";
 import { MetricsRegistry } from "./metrics.js";
 import { SessionTracker } from "./session-tracker.js";
 import { StateManager } from "./state.js";
+const execFileAsync = promisify(execFile);
 const startTime = Date.now();
 export async function startDaemon(opts = {}) {
     const configDir = opts.configDir || path.join(os.homedir(), ".agentctl");
     await fs.mkdir(configDir, { recursive: true });
-    // 1. Check for existing daemon
     const pidFilePath = path.join(configDir, "agentctl.pid");
-    const existingPid = await readPidFile(pidFilePath);
-    if (existingPid && isProcessAlive(existingPid)) {
-        throw new Error(`Daemon already running (PID ${existingPid})`);
-    }
-    // 2. Clean stale socket
     const sockPath = path.join(configDir, "agentctl.sock");
+    // 1. Kill stale daemon/supervisor processes before anything else (#39)
+    await killStaleDaemons(configDir);
+    // 2. Verify no daemon is actually running by trying to connect to socket
+    const socketAlive = await isSocketAlive(sockPath);
+    if (socketAlive) {
+        throw new Error("Daemon already running (socket responsive)");
+    }
+    // 3. Clean stale socket file
     await fs.rm(sockPath, { force: true });
-    // 3. Run migration (idempotent)
+    // 4. Save shell environment for subprocess spawning (#42)
+    await saveEnvironment(configDir);
+    // 5. Clear binary cache on restart (#41 — pick up moved/updated binaries)
+    clearBinaryCache();
+    // 6. Run migration (idempotent)
     await migrateLocks(configDir).catch((err) => console.error("Migration warning:", err.message));
-    // 4. Load persisted state
+    // 7. Load persisted state
     const state = await StateManager.load(configDir);
-    // 5. Initialize subsystems
+    // 8. Initialize subsystems
     const adapters = opts.adapters || {
         "claude-code": new ClaudeCodeAdapter(),
         codex: new CodexAdapter(),
@@ -51,14 +62,16 @@ export async function startDaemon(opts = {}) {
     const sessionTracker = new SessionTracker(state, { adapters });
     const metrics = new MetricsRegistry(sessionTracker, lockManager, fuseEngine);
     // Wire up events
-    emitter.on("fuse.fired", () => {
-        metrics.recordFuseFired();
+    emitter.on("fuse.expired", () => {
+        metrics.recordFuseExpired();
     });
-    // 6. Resume fuse timers
+    // 9. Validate all sessions on startup — mark dead ones as stopped (#40)
+    sessionTracker.validateAllSessions();
+    // 10. Resume fuse timers
     fuseEngine.resumeTimers();
-    // 7. Start session polling
+    // 11. Start session polling
     sessionTracker.startPolling();
-    // 8. Create request handler
+    // 12. Create request handler
     const handleRequest = createRequestHandler({
         sessionTracker,
         lockManager,
@@ -69,7 +82,7 @@ export async function startDaemon(opts = {}) {
         configDir,
         sockPath,
     });
-    // 9. Start Unix socket server
+    // 13. Start Unix socket server
     const socketServer = net.createServer((conn) => {
         let buffer = "";
         conn.on("data", (chunk) => {
@@ -105,7 +118,9 @@ export async function startDaemon(opts = {}) {
         socketServer.listen(sockPath, () => resolve());
         socketServer.on("error", reject);
     });
-    // 10. Start HTTP metrics server
+    // 14. Write PID file (after socket is listening — acts as "lock acquired")
+    await fs.writeFile(pidFilePath, String(process.pid));
+    // 15. Start HTTP metrics server
     const metricsPort = opts.metricsPort ?? 9200;
     const httpServer = http.createServer((req, res) => {
         if (req.url === "/metrics" && req.method === "GET") {
@@ -123,8 +138,6 @@ export async function startDaemon(opts = {}) {
         httpServer.listen(metricsPort, "127.0.0.1", () => resolve());
         httpServer.on("error", reject);
     });
-    // 11. Write PID file
-    await fs.writeFile(pidFilePath, String(process.pid));
     // Shutdown function
     const shutdown = async () => {
         sessionTracker.stopPolling();
@@ -136,7 +149,7 @@ export async function startDaemon(opts = {}) {
         await fs.rm(sockPath, { force: true });
         await fs.rm(pidFilePath, { force: true });
     };
-    // 12. Signal handlers
+    // 16. Signal handlers
     for (const sig of ["SIGTERM", "SIGINT"]) {
         process.on(sig, async () => {
             console.log(`Received ${sig}, shutting down...`);
@@ -149,6 +162,86 @@ export async function startDaemon(opts = {}) {
     console.log(`  Metrics: http://localhost:${metricsPort}/metrics`);
     return { socketServer, httpServer, shutdown };
 }
+// --- Stale daemon cleanup (#39) ---
+/**
+ * Find and kill ALL stale agentctl daemon/supervisor processes.
+ * This ensures singleton enforcement even after unclean shutdowns.
+ */
+async function killStaleDaemons(configDir) {
+    // 1. Kill processes recorded in PID files
+    for (const pidFile of ["agentctl.pid", "supervisor.pid"]) {
+        const p = path.join(configDir, pidFile);
+        const pid = await readPidFile(p);
+        if (pid && pid !== process.pid && isProcessAlive(pid)) {
+            try {
+                process.kill(pid, "SIGTERM");
+                // Wait briefly for clean shutdown
+                await sleep(500);
+                if (isProcessAlive(pid)) {
+                    process.kill(pid, "SIGKILL");
+                }
+            }
+            catch {
+                // Already gone
+            }
+        }
+        // Clean up stale PID file
+        await fs.rm(p, { force: true }).catch(() => { });
+    }
+    // 2. Scan ps for any remaining agentctl daemon processes
+    try {
+        const { stdout } = await execFileAsync("ps", ["aux"]);
+        for (const line of stdout.split("\n")) {
+            if (!line.includes("agentctl") || !line.includes("daemon"))
+                continue;
+            if (line.includes("grep"))
+                continue;
+            const fields = line.trim().split(/\s+/);
+            if (fields.length < 2)
+                continue;
+            const pid = Number.parseInt(fields[1], 10);
+            if (Number.isNaN(pid) || pid === process.pid)
+                continue;
+            // Also skip our parent process (supervisor)
+            if (pid === process.ppid)
+                continue;
+            try {
+                process.kill(pid, "SIGTERM");
+                await sleep(200);
+                if (isProcessAlive(pid)) {
+                    process.kill(pid, "SIGKILL");
+                }
+            }
+            catch {
+                // Already gone
+            }
+        }
+    }
+    catch {
+        // ps failed — best effort
+    }
+}
+/**
+ * Check if a Unix socket is actually responsive (not just a stale file).
+ */
+async function isSocketAlive(sockPath) {
+    return new Promise((resolve) => {
+        const socket = net.createConnection(sockPath);
+        const timeout = setTimeout(() => {
+            socket.destroy();
+            resolve(false);
+        }, 1000);
+        socket.on("connect", () => {
+            clearTimeout(timeout);
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on("error", () => {
+            clearTimeout(timeout);
+            resolve(false);
+        });
+    });
+}
 function createRequestHandler(ctx) {
     return async (req) => {
         const params = (req.params || {});
@@ -242,10 +335,9 @@ function createRequestHandler(ctx) {
                 });
                 // Remove auto-lock
                 ctx.lockManager.autoUnlock(session.id);
-                // Mark stopped and start fuse if applicable
+                // Mark stopped
                 const stopped = ctx.sessionTracker.onSessionExit(session.id);
                 if (stopped) {
-                    ctx.fuseEngine.onSessionExit(stopped);
                     ctx.metrics.recordSessionStopped();
                 }
                 return null;
@@ -260,6 +352,11 @@ function createRequestHandler(ctx) {
                 await adapter.resume(session.id, params.message);
                 return null;
             }
+            // --- Prune command (#40) ---
+            case "session.prune": {
+                const pruned = ctx.sessionTracker.pruneDeadSessions();
+                return { pruned };
+            }
             case "lock.list":
                 return ctx.lockManager.listAll();
             case "lock.acquire":
@@ -269,6 +366,21 @@ function createRequestHandler(ctx) {
                 return null;
             case "fuse.list":
                 return ctx.fuseEngine.listActive();
+            case "fuse.set":
+                ctx.fuseEngine.setFuse({
+                    directory: params.directory,
+                    sessionId: params.sessionId,
+                    ttlMs: params.ttlMs,
+                    onExpire: params.onExpire,
+                    label: params.label,
+                });
+                return null;
+            case "fuse.extend": {
+                const extended = ctx.fuseEngine.extendFuse(params.directory, params.ttlMs);
+                if (!extended)
+                    throw new Error(`No active fuse for directory: ${params.directory}`);
+                return null;
+            }
             case "fuse.cancel":
                 ctx.fuseEngine.cancelFuse(params.directory);
                 return null;
@@ -311,3 +423,6 @@ function isProcessAlive(pid) {
         return false;
     }
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/daemon/session-tracker.d.ts

@@ -25,6 +25,19 @@ export declare class SessionTracker {
      * - Any "running"/"idle" session in state whose PID is dead → mark stopped
      */
     private reapStaleEntries;
+    /**
+     * Validate all sessions on daemon startup (#40).
+     * Any session marked as "running" or "idle" whose PID is dead gets
+     * immediately marked as "stopped". This prevents unbounded growth of
+     * ghost sessions across daemon restarts.
+     */
+    validateAllSessions(): void;
+    /**
+     * Aggressively prune all clearly-dead sessions (#40).
+     * Returns the number of sessions pruned.
+     * Called via `agentctl prune` command.
+     */
+    pruneDeadSessions(): number;
     /**
      * Remove stopped sessions from state that have been stopped for more than 7 days.
      * This reduces overhead from accumulating hundreds of historical sessions.

package/dist/daemon/session-tracker.js

@@ -42,24 +42,25 @@ export class SessionTracker {
         }
     }
     async poll() {
-        // Collect PIDs from all adapter-returned sessions (the source of truth)
+        // Collect PIDs from all adapter-discovered sessions (the source of truth)
         const adapterPidToId = new Map();
         for (const [adapterName, adapter] of Object.entries(this.adapters)) {
             try {
-                const sessions = await adapter.list({ all: true });
-                for (const session of sessions) {
-                    if (session.pid) {
-                        adapterPidToId.set(session.pid, session.id);
+                // Discover-first: adapter.discover() is the ground truth
+                const discovered = await adapter.discover();
+                for (const disc of discovered) {
+                    if (disc.pid) {
+                        adapterPidToId.set(disc.pid, disc.id);
                     }
-                    const existing = this.state.getSession(session.id);
-                    const record = sessionToRecord(session, adapterName);
+                    const existing = this.state.getSession(disc.id);
+                    const record = discoveredToRecord(disc, adapterName);
                     if (!existing) {
-                        this.state.setSession(session.id, record);
+                        this.state.setSession(disc.id, record);
                     }
                     else if (existing.status !== record.status ||
                         (!existing.model && record.model)) {
-                        // Status changed or model resolved — update
-                        this.state.setSession(session.id, {
+                        // Status changed or model resolved — update, preserving metadata
+                        this.state.setSession(disc.id, {
                             ...existing,
                             status: record.status,
                             stoppedAt: record.stoppedAt,
@@ -67,6 +68,7 @@ export class SessionTracker {
                             tokens: record.tokens,
                             cost: record.cost,
                             prompt: record.prompt || existing.prompt,
+                            pid: record.pid,
                         });
                     }
                 }
@@ -113,6 +115,79 @@ export class SessionTracker {
             }
         }
     }
+    /**
+     * Validate all sessions on daemon startup (#40).
+     * Any session marked as "running" or "idle" whose PID is dead gets
+     * immediately marked as "stopped". This prevents unbounded growth of
+     * ghost sessions across daemon restarts.
+     */
+    validateAllSessions() {
+        const sessions = this.state.getSessions();
+        let cleaned = 0;
+        for (const [id, record] of Object.entries(sessions)) {
+            if (record.status !== "running" && record.status !== "idle")
+                continue;
+            if (record.pid) {
+                if (!this.isProcessAlive(record.pid)) {
+                    this.state.setSession(id, {
+                        ...record,
+                        status: "stopped",
+                        stoppedAt: new Date().toISOString(),
+                    });
+                    cleaned++;
+                }
+            }
+            else {
+                // No PID recorded — can't verify, mark as stopped
+                this.state.setSession(id, {
+                    ...record,
+                    status: "stopped",
+                    stoppedAt: new Date().toISOString(),
+                });
+                cleaned++;
+            }
+        }
+        if (cleaned > 0) {
+            console.error(`Validated sessions on startup: marked ${cleaned} dead sessions as stopped`);
+        }
+    }
+    /**
+     * Aggressively prune all clearly-dead sessions (#40).
+     * Returns the number of sessions pruned.
+     * Called via `agentctl prune` command.
+     */
+    pruneDeadSessions() {
+        const sessions = this.state.getSessions();
+        let pruned = 0;
+        for (const [id, record] of Object.entries(sessions)) {
+            // Remove stopped/completed/failed sessions older than 24h
+            if (record.status === "stopped" ||
+                record.status === "completed" ||
+                record.status === "failed") {
+                const stoppedAt = record.stoppedAt
+                    ? new Date(record.stoppedAt).getTime()
+                    : new Date(record.startedAt).getTime();
+                const age = Date.now() - stoppedAt;
+                if (age > 24 * 60 * 60 * 1000) {
+                    this.state.removeSession(id);
+                    pruned++;
+                }
+                continue;
+            }
+            // Remove running/idle sessions whose PID is dead
+            if (record.status === "running" || record.status === "idle") {
+                if (record.pid && !this.isProcessAlive(record.pid)) {
+                    this.state.removeSession(id);
+                    pruned++;
+                }
+                else if (!record.pid) {
+                    this.state.removeSession(id);
+                    pruned++;
+                }
+            }
+        }
+        return pruned;
+    }
     /**
      * Remove stopped sessions from state that have been stopped for more than 7 days.
      * This reduces overhead from accumulating hundreds of historical sessions.
@@ -265,3 +340,20 @@ function sessionToRecord(session, adapterName) {
         meta: session.meta,
     };
 }
+/** Convert a DiscoveredSession (adapter ground truth) to a SessionRecord for state */
+function discoveredToRecord(disc, adapterName) {
+    return {
+        id: disc.id,
+        adapter: adapterName,
+        status: disc.status,
+        startedAt: disc.startedAt?.toISOString() ?? new Date().toISOString(),
+        stoppedAt: disc.stoppedAt?.toISOString(),
+        cwd: disc.cwd,
+        model: disc.model,
+        prompt: disc.prompt,
+        tokens: disc.tokens,
+        cost: disc.cost,
+        pid: disc.pid,
+        meta: disc.nativeMetadata ?? {},
+    };
+}

package/dist/daemon/state.d.ts

@@ -28,10 +28,20 @@ export interface Lock {
 }
 export interface FuseTimer {
     directory: string;
-    clusterName: string;
-    branch: string;
+    ttlMs: number;
     expiresAt: string;
     sessionId: string;
+    /** On-expire action: shell command, webhook URL, or event name */
+    onExpire?: FuseAction;
+    label?: string;
+}
+export interface FuseAction {
+    /** Shell script to run when fuse expires. CWD is the fuse directory. */
+    script?: string;
+    /** Webhook URL to POST to when fuse expires */
+    webhook?: string;
+    /** Event name to emit when fuse expires */
+    event?: string;
 }
 export interface PersistedState {
     sessions: Record<string, SessionRecord>;

package/dist/hooks.d.ts

@@ -1,5 +1,5 @@
 import type { LifecycleHooks } from "./core/types.js";
-export type HookPhase = "onCreate" | "onComplete" | "preMerge" | "postMerge";
+export type HookPhase = "onCreate" | "onComplete";
 export interface HookContext {
     sessionId: string;
     cwd: string;

package/dist/utils/daemon-env.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Save the current process environment to disk.
+ * Called at daemon start time when we still have the user's shell env.
+ */
+export declare function saveEnvironment(configDir: string): Promise<void>;
+/**
+ * Load the saved environment from disk.
+ * Returns undefined if the env file doesn't exist or is corrupt.
+ */
+export declare function loadSavedEnvironment(configDir: string): Promise<Record<string, string> | undefined>;
+/**
+ * Build an augmented environment for spawning subprocesses.
+ * Merges the saved daemon env with common bin paths to ensure
+ * binaries are findable even when the daemon is detached from the shell.
+ */
+export declare function buildSpawnEnv(savedEnv?: Record<string, string>, extraEnv?: Record<string, string>): Record<string, string>;

package/dist/utils/daemon-env.js

@@ -0,0 +1,85 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+const ENV_FILE = "daemon-env.json";
+/**
+ * Common bin directories that should be in PATH when spawning subprocesses.
+ * These cover the usual locations for various package managers and tools.
+ */
+function getCommonBinDirs() {
+    const home = os.homedir();
+    return [
+        path.join(home, ".local", "bin"),
+        "/usr/local/bin",
+        "/usr/bin",
+        "/bin",
+        "/usr/sbin",
+        "/sbin",
+        "/opt/homebrew/bin",
+        path.join(home, ".npm-global", "bin"),
+        path.join(home, ".local", "share", "mise", "shims"),
+        path.join(home, ".cargo", "bin"),
+    ];
+}
+/**
+ * Save the current process environment to disk.
+ * Called at daemon start time when we still have the user's shell env.
+ */
+export async function saveEnvironment(configDir) {
+    const envPath = path.join(configDir, ENV_FILE);
+    try {
+        const tmpPath = `${envPath}.tmp`;
+        await fs.writeFile(tmpPath, JSON.stringify(process.env));
+        await fs.rename(tmpPath, envPath);
+    }
+    catch (err) {
+        console.error(`Warning: could not save environment: ${err.message}`);
+    }
+}
+/**
+ * Load the saved environment from disk.
+ * Returns undefined if the env file doesn't exist or is corrupt.
+ */
+export async function loadSavedEnvironment(configDir) {
+    const envPath = path.join(configDir, ENV_FILE);
+    try {
+        const raw = await fs.readFile(envPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" && parsed !== null) {
+            return parsed;
+        }
+    }
+    catch {
+        // File doesn't exist or is corrupt
+    }
+    return undefined;
+}
+/**
+ * Build an augmented environment for spawning subprocesses.
+ * Merges the saved daemon env with common bin paths to ensure
+ * binaries are findable even when the daemon is detached from the shell.
+ */
+export function buildSpawnEnv(savedEnv, extraEnv) {
+    const base = {};
+    const source = savedEnv || process.env;
+    // Copy source env
+    for (const [k, v] of Object.entries(source)) {
+        if (v !== undefined)
+            base[k] = v;
+    }
+    // Augment PATH with common bin directories
+    const existingPath = base.PATH || "";
+    const existingDirs = new Set(existingPath.split(":").filter(Boolean));
+    const commonDirs = getCommonBinDirs();
+    const newDirs = commonDirs.filter((d) => !existingDirs.has(d));
+    if (newDirs.length > 0) {
+        base.PATH = [...existingPath.split(":").filter(Boolean), ...newDirs].join(":");
+    }
+    // Apply extra env overrides
+    if (extraEnv) {
+        for (const [k, v] of Object.entries(extraEnv)) {
+            base[k] = v;
+        }
+    }
+    return base;
+}

package/dist/utils/resolve-binary.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolve the absolute path to a binary, checking known locations first,
+ * then falling back to `which`. Results are cached per binary name.
+ *
+ * @param name - Binary name (e.g., "claude", "codex", "pi")
+ * @param knownLocations - Additional absolute paths to check first
+ * @returns Resolved absolute path, or bare name as last resort
+ */
+export declare function resolveBinaryPath(name: string, knownLocations?: string[]): Promise<string>;
+/**
+ * Clear the resolved path cache. Call this when binaries may have been
+ * updated (e.g., on daemon restart).
+ */
+export declare function clearBinaryCache(): void;

package/dist/utils/resolve-binary.js

@@ -0,0 +1,66 @@
+import { execFile } from "node:child_process";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/** Cache of resolved binary paths: name → absolute path */
+const resolvedCache = new Map();
+/**
+ * Resolve the absolute path to a binary, checking known locations first,
+ * then falling back to `which`. Results are cached per binary name.
+ *
+ * @param name - Binary name (e.g., "claude", "codex", "pi")
+ * @param knownLocations - Additional absolute paths to check first
+ * @returns Resolved absolute path, or bare name as last resort
+ */
+export async function resolveBinaryPath(name, knownLocations = []) {
+    const cached = resolvedCache.get(name);
+    if (cached)
+        return cached;
+    const home = os.homedir();
+    // Default well-known locations for common toolchains
+    const defaultLocations = [
+        path.join(home, ".local", "bin", name),
+        `/usr/local/bin/${name}`,
+        `/opt/homebrew/bin/${name}`, // Homebrew Apple Silicon
+        path.join(home, ".npm-global", "bin", name),
+        path.join(home, ".local", "share", "mise", "shims", name),
+        path.join(home, ".cargo", "bin", name),
+    ];
+    const candidates = [...knownLocations, ...defaultLocations];
+    for (const c of candidates) {
+        try {
+            await fs.access(c, fs.constants.X_OK);
+            // Resolve symlinks to get the actual binary path
+            const resolved = await fs.realpath(c);
+            await fs.access(resolved, fs.constants.X_OK);
+            resolvedCache.set(name, resolved);
+            return resolved;
+        }
+        catch {
+            // Try next
+        }
+    }
+    // Try `which <name>` as fallback
+    try {
+        const { stdout } = await execFileAsync("which", [name]);
+        const p = stdout.trim();
+        if (p) {
+            resolvedCache.set(name, p);
+            return p;
+        }
+    }
+    catch {
+        // Fall through
+    }
+    // Last resort: bare name (let PATH resolve it at spawn time)
+    return name;
+}
+/**
+ * Clear the resolved path cache. Call this when binaries may have been
+ * updated (e.g., on daemon restart).
+ */
+export function clearBinaryCache() {
+    resolvedCache.clear();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orgloop/agentctl",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Universal agent supervision interface — monitor and control AI coding agents from a single CLI",
   "type": "module",
   "bin": {