@orgloop/agentctl 1.4.0 → 1.5.0

package/README.md

@@ -42,12 +42,16 @@ agentctl list
 # List all sessions (including stopped, last 7 days)
 agentctl list -a
 
-# Peek at recent output from a session
+# Peek at recent output from a session (alias: logs)
 agentctl peek <session-id>
+agentctl logs <session-id>
 
 # Launch a new Claude Code session
 agentctl launch -p "Read the spec and implement phase 2"
 
+# Launch in a specific directory
+agentctl launch -p "Fix the auth bug" --cwd ~/code/mono
+
 # Launch a new Pi session
 agentctl launch pi -p "Refactor the auth module"
 
@@ -58,7 +62,7 @@ agentctl stop <session-id>
 agentctl resume <session-id> "fix the failing tests"
 ```
 
-Session IDs support prefix matching — `agentctl peek abc123` matches any session starting with `abc123`.
+Session IDs support prefix matching — `agentctl peek abc123` (or `agentctl logs abc123`) matches any session starting with `abc123`.
 
 ### Parallel Multi-Adapter Launch
 
@@ -141,20 +145,22 @@ agentctl status <id> [options]
   --adapter <name>     Adapter to use
   --json               Output as JSON
 
-agentctl peek <id> [options]
+agentctl peek|logs <id> [options]
   -n, --lines <n>      Number of recent messages (default: 20)
   --adapter <name>     Adapter to use
 
 agentctl launch [adapter] [options]
   -p, --prompt <text>  Prompt to send (required)
   --spec <path>        Spec file path
-  --cwd <dir>          Working directory
+  --cwd <dir>          Working directory (default: current directory)
   --model <model>      Model to use (e.g. sonnet, opus)
   --adapter <name>     Adapter to launch (repeatable for parallel launch)
   --matrix <file>      YAML matrix file for advanced sweep launch
   --group <id>         Filter by launch group (for list command)
   --force              Override directory locks
 
+When `--cwd` is omitted, the agent launches in the current working directory (`$PWD`). This means you should either `cd` into the target project first or pass `--cwd` explicitly. Launching from an unrelated directory (e.g. `~`) will start the agent in the wrong place.
+
 agentctl stop <id> [options]
   --force              Force kill (SIGINT then SIGKILL)
   --adapter <name>     Adapter to use

package/dist/adapters/claude-code.js

@@ -206,7 +206,7 @@ export class ClaudeCodeAdapter {
         // Claude Code's stream-json format emits a line with sessionId early on.
         let resolvedSessionId;
         if (pid) {
-            resolvedSessionId = await this.pollForSessionId(logPath, pid, 5000);
+            resolvedSessionId = await this.pollForSessionId(logPath, pid, 15000);
         }
         const sessionId = resolvedSessionId || (pid ? `pending-${pid}` : crypto.randomUUID());
         // Persist session metadata so status checks work after wrapper exits

package/dist/cli.js

@@ -336,13 +336,8 @@ program
     console.error(`Session not found: ${id}`);
     process.exit(1);
 });
-// peek
-program
-    .command("peek <id>")
-    .description("Peek at recent output from a session")
-    .option("-n, --lines <n>", "Number of recent messages", "20")
-    .option("--adapter <name>", "Adapter to use")
-    .action(async (id, opts) => {
+// Shared handler for peek/logs
+async function peekAction(id, opts) {
     const daemonRunning = await ensureDaemon();
     if (daemonRunning) {
         try {
@@ -386,7 +381,21 @@ program
     }
     console.error(`Session not found: ${id}`);
     process.exit(1);
-});
+}
+// peek
+program
+    .command("peek <id>")
+    .description("Peek at recent output from a session (alias: logs)")
+    .option("-n, --lines <n>", "Number of recent messages", "20")
+    .option("--adapter <name>", "Adapter to use")
+    .action(peekAction);
+// logs — alias for peek with higher default line count
+program
+    .command("logs <id>")
+    .description("Show recent session output (alias for peek, default 50 lines)")
+    .option("-n, --lines <n>", "Number of recent messages", "50")
+    .option("--adapter <name>", "Adapter to use")
+    .action(peekAction);
 // stop
 program
     .command("stop <id>")
@@ -453,7 +462,7 @@ program
     .description("Launch a new agent session (or multiple with --adapter flags)")
     .requiredOption("-p, --prompt <text>", "Prompt to send")
     .option("--spec <path>", "Spec file path")
-    .option("--cwd <dir>", "Working directory")
+    .option("--cwd <dir>", "Working directory (default: current directory)")
     .option("--model <model>", "Model to use (e.g. sonnet, opus)")
     .option("--force", "Override directory locks")
     .option("--worktree <repo>", "Auto-create git worktree from this repo before launch")

package/dist/daemon/lock-manager.d.ts

@@ -12,5 +12,7 @@ export declare class LockManager {
     manualLock(directory: string, by?: string, reason?: string): Lock;
     /** Manual unlock. Only removes manual locks. */
     manualUnlock(directory: string): void;
+    /** Update the sessionId on auto-locks when a pending ID is resolved to a real UUID. */
+    updateAutoLockSessionId(oldId: string, newId: string): void;
     listAll(): Lock[];
 }

package/dist/daemon/lock-manager.js

@@ -43,7 +43,7 @@ export class LockManager {
         const resolved = path.resolve(directory);
         const existing = this.check(resolved);
         if (existing?.type === "manual") {
-            throw new Error(`Already manually locked by ${existing.lockedBy}: ${existing.reason}`);
+            throw new Error(`Already manually locked by ${existing.lockedBy ?? "unknown"}${existing.reason ? `: ${existing.reason}` : ""}`);
         }
         const lock = {
             directory: resolved,
@@ -65,6 +65,16 @@ export class LockManager {
             throw new Error(`No manual lock on ${resolved}`);
         this.state.removeLocks((l) => l.directory === resolved && l.type === "manual");
     }
+    /** Update the sessionId on auto-locks when a pending ID is resolved to a real UUID. */
+    updateAutoLockSessionId(oldId, newId) {
+        const locks = this.state.getLocks();
+        for (const lock of locks) {
+            if (lock.type === "auto" && lock.sessionId === oldId) {
+                lock.sessionId = newId;
+            }
+        }
+        this.state.markDirty();
+    }
     listAll() {
         return this.state.getLocks();
     }

package/dist/daemon/server.js

@@ -79,6 +79,10 @@ export async function startDaemon(opts = {}) {
     sessionTracker.startLaunchCleanup((deadId) => {
         lockManager.autoUnlock(deadId);
     });
+    // 11b. Start periodic background resolution of pending-* session IDs (10s interval)
+    sessionTracker.startPendingResolution((oldId, newId) => {
+        lockManager.updateAutoLockSessionId(oldId, newId);
+    });
     // 12. Create request handler
     const handleRequest = createRequestHandler({
         sessionTracker,
@@ -149,6 +153,7 @@ export async function startDaemon(opts = {}) {
     // Shutdown function
     const shutdown = async () => {
         sessionTracker.stopLaunchCleanup();
+        sessionTracker.stopPendingResolution();
         fuseEngine.shutdown();
         state.flush();
         await state.persist();
@@ -306,7 +311,17 @@ function createRequestHandler(ctx) {
                 return sessions;
             }
             case "session.status": {
-                const id = params.id;
+                let id = params.id;
+                // On-demand resolution: if pending-*, try to resolve first
+                const trackedForResolve = ctx.sessionTracker.getSession(id);
+                const resolveTarget = trackedForResolve?.id || id;
+                if (resolveTarget.startsWith("pending-")) {
+                    const resolvedId = await ctx.sessionTracker.resolvePendingId(resolveTarget);
+                    if (resolvedId !== resolveTarget) {
+                        ctx.lockManager.updateAutoLockSessionId(resolveTarget, resolvedId);
+                        id = resolvedId;
+                    }
+                }
                 // Check launch metadata to determine adapter
                 const launchRecord = ctx.sessionTracker.getSession(id);
                 const adapterName = params.adapter || launchRecord?.adapter;
@@ -356,13 +371,21 @@ function createRequestHandler(ctx) {
             }
             case "session.peek": {
                 // Auto-detect adapter from tracked session, fall back to param or claude-code
-                const tracked = ctx.sessionTracker.getSession(params.id);
+                let tracked = ctx.sessionTracker.getSession(params.id);
+                let peekId = tracked?.id || params.id;
+                // On-demand resolution: if pending-*, try to resolve before peeking
+                if (peekId.startsWith("pending-")) {
+                    const resolvedId = await ctx.sessionTracker.resolvePendingId(peekId);
+                    if (resolvedId !== peekId) {
+                        ctx.lockManager.updateAutoLockSessionId(peekId, resolvedId);
+                        peekId = resolvedId;
+                        tracked = ctx.sessionTracker.getSession(resolvedId);
+                    }
+                }
                 const adapterName = params.adapter || tracked?.adapter || "claude-code";
                 const adapter = ctx.adapters[adapterName];
                 if (!adapter)
                     throw new Error(`Unknown adapter: ${adapterName}`);
-                // Use the full session ID if we resolved it from the tracker
-                const peekId = tracked?.id || params.id;
                 return adapter.peek(peekId, {
                     lines: params.lines,
                 });
@@ -373,7 +396,7 @@ function createRequestHandler(ctx) {
                 const lock = ctx.lockManager.check(cwd);
                 if (lock && !params.force) {
                     if (lock.type === "manual") {
-                        throw new Error(`Directory locked by ${lock.lockedBy}: ${lock.reason}. Use --force to override.`);
+                        throw new Error(`Directory locked by ${lock.lockedBy ?? "unknown"}${lock.reason ? `: ${lock.reason}` : ""}. Use --force to override.`);
                     }
                     throw new Error(`Directory in use by session ${lock.sessionId?.slice(0, 8)}. Use --force to override.`);
                 }
@@ -408,14 +431,24 @@ function createRequestHandler(ctx) {
             }
             case "session.stop": {
                 const id = params.id;
-                const launchRecord = ctx.sessionTracker.getSession(id);
+                let launchRecord = ctx.sessionTracker.getSession(id);
+                let sessionId = launchRecord?.id || id;
+                // On-demand resolution: if pending-*, try to resolve before stopping
+                if (sessionId.startsWith("pending-")) {
+                    const resolvedId = await ctx.sessionTracker.resolvePendingId(sessionId);
+                    if (resolvedId !== sessionId) {
+                        ctx.lockManager.updateAutoLockSessionId(sessionId, resolvedId);
+                        sessionId = resolvedId;
+                        launchRecord = ctx.sessionTracker.getSession(resolvedId);
+                    }
+                }
                 // Ghost pending entry with dead PID: remove from state with --force
-                if (launchRecord?.id.startsWith("pending-") &&
+                if (sessionId.startsWith("pending-") &&
                     params.force &&
-                    launchRecord.pid &&
+                    launchRecord?.pid &&
                     !isProcessAlive(launchRecord.pid)) {
-                    ctx.lockManager.autoUnlock(launchRecord.id);
-                    ctx.sessionTracker.removeSession(launchRecord.id);
+                    ctx.lockManager.autoUnlock(sessionId);
+                    ctx.sessionTracker.removeSession(sessionId);
                     return null;
                 }
                 const adapterName = params.adapter || launchRecord?.adapter;
@@ -424,7 +457,6 @@ function createRequestHandler(ctx) {
                 const adapter = ctx.adapters[adapterName];
                 if (!adapter)
                     throw new Error(`Unknown adapter: ${adapterName}`);
-                const sessionId = launchRecord?.id || id;
                 await adapter.stop(sessionId, {
                     force: params.force,
                 });
@@ -439,14 +471,24 @@ function createRequestHandler(ctx) {
             }
             case "session.resume": {
                 const id = params.id;
-                const launchRecord = ctx.sessionTracker.getSession(id);
+                let launchRecord = ctx.sessionTracker.getSession(id);
+                let resumeId = launchRecord?.id || id;
+                // On-demand resolution: if pending-*, try to resolve before resuming
+                if (resumeId.startsWith("pending-")) {
+                    const resolvedId = await ctx.sessionTracker.resolvePendingId(resumeId);
+                    if (resolvedId !== resumeId) {
+                        ctx.lockManager.updateAutoLockSessionId(resumeId, resolvedId);
+                        resumeId = resolvedId;
+                        launchRecord = ctx.sessionTracker.getSession(resolvedId);
+                    }
+                }
                 const adapterName = params.adapter || launchRecord?.adapter;
                 if (!adapterName)
                     throw new Error(`Session not found: ${id}. Specify --adapter to resume a non-daemon session.`);
                 const adapter = ctx.adapters[adapterName];
                 if (!adapter)
                     throw new Error(`Unknown adapter: ${adapterName}`);
-                await adapter.resume(launchRecord?.id || id, params.message);
+                await adapter.resume(resumeId, params.message);
                 return null;
             }
             // --- Prune command (#40) --- kept for CLI backward compat

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

@@ -20,6 +20,7 @@ export declare class SessionTracker {
     private adapters;
     private readonly isProcessAlive;
     private cleanupHandle;
+    private pendingResolutionHandle;
     constructor(state: StateManager, opts: SessionTrackerOpts);
     /**
      * Start periodic PID liveness check for daemon-launched sessions.
@@ -28,6 +29,23 @@ export declare class SessionTracker {
      */
     startLaunchCleanup(onDead?: (sessionId: string) => void): void;
     stopLaunchCleanup(): void;
+    /**
+     * Start periodic background resolution of pending-* session IDs.
+     * Runs every 10s, discovers real UUIDs via adapter PID matching.
+     */
+    startPendingResolution(onResolved?: (oldId: string, newId: string) => void): void;
+    stopPendingResolution(): void;
+    /**
+     * Resolve a single pending-* session ID on demand.
+     * Returns the resolved real UUID, or the original ID if resolution fails.
+     */
+    resolvePendingId(id: string): Promise<string>;
+    /**
+     * Batch-resolve all pending-* session IDs via adapter discovery.
+     * Groups pending sessions by adapter to minimize discover() calls.
+     * Returns a map of oldId → newId for each resolved session.
+     */
+    resolvePendingSessions(): Promise<Map<string, string>>;
     /** Track a newly launched session (stores launch metadata in state) */
     track(session: AgentSession, adapterName: string): SessionRecord;
     /** Get session launch metadata by id (exact or prefix match) */

package/dist/daemon/session-tracker.js

@@ -20,6 +20,7 @@ export class SessionTracker {
     adapters;
     isProcessAlive;
     cleanupHandle = null;
+    pendingResolutionHandle = null;
     constructor(state, opts) {
         this.state = state;
         this.adapters = opts.adapters;
@@ -47,6 +48,110 @@ export class SessionTracker {
             this.cleanupHandle = null;
         }
     }
+    /**
+     * Start periodic background resolution of pending-* session IDs.
+     * Runs every 10s, discovers real UUIDs via adapter PID matching.
+     */
+    startPendingResolution(onResolved) {
+        if (this.pendingResolutionHandle)
+            return;
+        this.pendingResolutionHandle = setInterval(async () => {
+            const resolved = await this.resolvePendingSessions();
+            if (onResolved) {
+                for (const [oldId, newId] of resolved) {
+                    onResolved(oldId, newId);
+                }
+            }
+        }, 10_000);
+    }
+    stopPendingResolution() {
+        if (this.pendingResolutionHandle) {
+            clearInterval(this.pendingResolutionHandle);
+            this.pendingResolutionHandle = null;
+        }
+    }
+    /**
+     * Resolve a single pending-* session ID on demand.
+     * Returns the resolved real UUID, or the original ID if resolution fails.
+     */
+    async resolvePendingId(id) {
+        if (!id.startsWith("pending-"))
+            return id;
+        const record = this.getSession(id);
+        if (!record || !record.pid)
+            return id;
+        const adapter = this.adapters[record.adapter];
+        if (!adapter)
+            return id;
+        try {
+            const discovered = await adapter.discover();
+            const match = discovered.find((d) => d.pid === record.pid);
+            if (match && match.id !== id) {
+                // Resolve: move state from pending ID to real UUID
+                const updatedRecord = { ...record, id: match.id };
+                this.state.removeSession(id);
+                this.state.setSession(match.id, updatedRecord);
+                return match.id;
+            }
+        }
+        catch {
+            // Adapter failed — return original ID
+        }
+        return id;
+    }
+    /**
+     * Batch-resolve all pending-* session IDs via adapter discovery.
+     * Groups pending sessions by adapter to minimize discover() calls.
+     * Returns a map of oldId → newId for each resolved session.
+     */
+    async resolvePendingSessions() {
+        const resolved = new Map();
+        const sessions = this.state.getSessions();
+        // Group pending sessions by adapter
+        const pendingByAdapter = new Map();
+        for (const [id, record] of Object.entries(sessions)) {
+            if (!id.startsWith("pending-"))
+                continue;
+            if (record.status === "stopped" || record.status === "completed")
+                continue;
+            if (!record.pid)
+                continue;
+            const list = pendingByAdapter.get(record.adapter) || [];
+            list.push({ id, record });
+            pendingByAdapter.set(record.adapter, list);
+        }
+        if (pendingByAdapter.size === 0)
+            return resolved;
+        // For each adapter with pending sessions, run discover() once
+        for (const [adapterName, pendings] of pendingByAdapter) {
+            const adapter = this.adapters[adapterName];
+            if (!adapter)
+                continue;
+            try {
+                const discovered = await adapter.discover();
+                const pidToId = new Map();
+                for (const d of discovered) {
+                    if (d.pid)
+                        pidToId.set(d.pid, d.id);
+                }
+                for (const { id, record } of pendings) {
+                    if (!record.pid)
+                        continue;
+                    const resolvedId = pidToId.get(record.pid);
+                    if (resolvedId && resolvedId !== id) {
+                        const updatedRecord = { ...record, id: resolvedId };
+                        this.state.removeSession(id);
+                        this.state.setSession(resolvedId, updatedRecord);
+                        resolved.set(id, resolvedId);
+                    }
+                }
+            }
+            catch {
+                // Adapter failed — skip
+            }
+        }
+        return resolved;
+    }
     /** Track a newly launched session (stores launch metadata in state) */
     track(session, adapterName) {
         const record = sessionToRecord(session, adapterName);

package/dist/hooks.js

@@ -31,13 +31,12 @@ export async function runHook(hooks, phase, ctx) {
         const result = await execAsync(script, {
             cwd: ctx.cwd,
             env,
-            timeout: 60_000,
+            timeout: 300_000,
         });
         return { stdout: result.stdout, stderr: result.stderr };
     }
     catch (err) {
         const e = err;
-        console.error(`Hook ${phase} failed:`, e.message);
-        return { stdout: e.stdout || "", stderr: e.stderr || "" };
+        throw new Error(`Hook ${phase} failed: ${e.message}`);
     }
 }

package/package.json

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