@orgloop/agentctl 1.3.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/metrics.d.ts

@@ -1,8 +1,6 @@
 import type { FuseEngine } from "./fuse-engine.js";
 import type { LockManager } from "./lock-manager.js";
-import type { SessionTracker } from "./session-tracker.js";
 export declare class MetricsRegistry {
-    private sessionTracker;
     private lockManager;
     private fuseEngine;
     sessionsTotalCompleted: number;
@@ -10,7 +8,12 @@ export declare class MetricsRegistry {
     sessionsTotalStopped: number;
     fusesExpiredTotal: number;
     sessionDurations: number[];
-    constructor(sessionTracker: SessionTracker, lockManager: LockManager, fuseEngine: FuseEngine);
+    /** Last-known active session count, updated by session.list fan-out */
+    private _activeSessionCount;
+    constructor(lockManager: LockManager, fuseEngine: FuseEngine);
+    /** Update the active session gauge (called after session.list fan-out) */
+    setActiveSessionCount(count: number): void;
+    get activeSessionCount(): number;
     recordSessionCompleted(durationSeconds?: number): void;
     recordSessionFailed(durationSeconds?: number): void;
     recordSessionStopped(durationSeconds?: number): void;

package/dist/daemon/metrics.js

@@ -1,5 +1,4 @@
 export class MetricsRegistry {
-    sessionTracker;
     lockManager;
     fuseEngine;
     sessionsTotalCompleted = 0;
@@ -7,11 +6,19 @@ export class MetricsRegistry {
     sessionsTotalStopped = 0;
     fusesExpiredTotal = 0;
     sessionDurations = []; // seconds
-    constructor(sessionTracker, lockManager, fuseEngine) {
-        this.sessionTracker = sessionTracker;
+    /** Last-known active session count, updated by session.list fan-out */
+    _activeSessionCount = 0;
+    constructor(lockManager, fuseEngine) {
         this.lockManager = lockManager;
         this.fuseEngine = fuseEngine;
     }
+    /** Update the active session gauge (called after session.list fan-out) */
+    setActiveSessionCount(count) {
+        this._activeSessionCount = count;
+    }
+    get activeSessionCount() {
+        return this._activeSessionCount;
+    }
     recordSessionCompleted(durationSeconds) {
         this.sessionsTotalCompleted++;
         if (durationSeconds != null)
@@ -43,7 +50,7 @@ export class MetricsRegistry {
             lines.push(labels ? `${name}{${labels}} ${value}` : `${name} ${value}`);
         };
         // Gauges
-        g("agentctl_sessions_active", "Number of active sessions", this.sessionTracker.activeCount());
+        g("agentctl_sessions_active", "Number of active sessions", this._activeSessionCount);
         const locks = this.lockManager.listAll();
         g("agentctl_locks_active", "Number of active locks", locks.filter((l) => l.type === "auto").length, 'type="auto"');
         g("agentctl_locks_active", "Number of active locks", locks.filter((l) => l.type === "manual").length, 'type="manual"');

package/dist/daemon/server.js

@@ -60,17 +60,29 @@ export async function startDaemon(opts = {}) {
         emitter,
     });
     const sessionTracker = new SessionTracker(state, { adapters });
-    const metrics = new MetricsRegistry(sessionTracker, lockManager, fuseEngine);
+    const metrics = new MetricsRegistry(lockManager, fuseEngine);
     // Wire up events
     emitter.on("fuse.expired", () => {
         metrics.recordFuseExpired();
     });
-    // 9. Validate all sessions on startup — mark dead ones as stopped (#40)
-    sessionTracker.validateAllSessions();
+    // 9. Initial PID liveness cleanup for daemon-launched sessions
+    //    (replaces the old validateAllSessions — much simpler, only checks launches)
+    const initialDead = sessionTracker.cleanupDeadLaunches();
+    if (initialDead.length > 0) {
+        for (const id of initialDead)
+            lockManager.autoUnlock(id);
+        console.error(`Startup cleanup: marked ${initialDead.length} dead launches as stopped`);
+    }
     // 10. Resume fuse timers
     fuseEngine.resumeTimers();
-    // 11. Start session polling
-    sessionTracker.startPolling();
+    // 11. Start periodic PID liveness check for lock cleanup (30s interval)
+    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,
@@ -140,7 +152,8 @@ export async function startDaemon(opts = {}) {
     });
     // Shutdown function
     const shutdown = async () => {
-        sessionTracker.stopPolling();
+        sessionTracker.stopLaunchCleanup();
+        sessionTracker.stopPendingResolution();
         fuseEngine.shutdown();
         state.flush();
         await state.persist();
@@ -247,30 +260,132 @@ function createRequestHandler(ctx) {
         const params = (req.params || {});
         switch (req.method) {
             case "session.list": {
-                let sessions = ctx.sessionTracker.listSessions({
-                    status: params.status,
-                    all: params.all,
-                });
-                if (params.group) {
-                    sessions = sessions.filter((s) => s.group === params.group);
+                const adapterFilter = params.adapter;
+                const statusFilter = params.status;
+                const showAll = params.all;
+                const groupFilter = params.group;
+                // Fan out discover() to adapters (or just one if filtered)
+                const adapterEntries = adapterFilter
+                    ? Object.entries(ctx.adapters).filter(([name]) => name === adapterFilter)
+                    : Object.entries(ctx.adapters);
+                const ADAPTER_TIMEOUT_MS = 5000;
+                const succeededAdapters = new Set();
+                const results = await Promise.allSettled(adapterEntries.map(([name, adapter]) => Promise.race([
+                    adapter.discover().then((sessions) => {
+                        succeededAdapters.add(name);
+                        return sessions.map((s) => ({ ...s, adapter: name }));
+                    }),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error(`Adapter ${name} timed out`)), ADAPTER_TIMEOUT_MS)),
+                ])));
+                // Merge fulfilled results, skip failed adapters
+                const discovered = results
+                    .filter((r) => r.status === "fulfilled")
+                    .flatMap((r) => r.value);
+                // Reconcile with launch metadata and enrich
+                const { sessions: allSessions, stoppedLaunchIds } = ctx.sessionTracker.reconcileAndEnrich(discovered, succeededAdapters);
+                // Release locks for sessions that disappeared from adapter results
+                for (const id of stoppedLaunchIds) {
+                    ctx.lockManager.autoUnlock(id);
+                }
+                // Apply filters
+                let sessions = allSessions;
+                if (statusFilter) {
+                    sessions = sessions.filter((s) => s.status === statusFilter);
+                }
+                else if (!showAll) {
+                    sessions = sessions.filter((s) => s.status === "running" || s.status === "idle");
                 }
+                if (groupFilter) {
+                    sessions = sessions.filter((s) => s.group === groupFilter);
+                }
+                // Sort: running first, then by most recent
+                sessions.sort((a, b) => {
+                    if (a.status === "running" && b.status !== "running")
+                        return -1;
+                    if (b.status === "running" && a.status !== "running")
+                        return 1;
+                    return (new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+                });
+                // Update metrics gauge
+                ctx.metrics.setActiveSessionCount(allSessions.filter((s) => s.status === "running" || s.status === "idle").length);
                 return sessions;
             }
             case "session.status": {
-                const session = ctx.sessionTracker.getSession(params.id);
-                if (!session)
-                    throw new Error(`Session not found: ${params.id}`);
-                return session;
+                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;
+                // Determine which adapters to search
+                const adaptersToSearch = adapterName
+                    ? Object.entries(ctx.adapters).filter(([name]) => name === adapterName)
+                    : Object.entries(ctx.adapters);
+                // Search adapters for the session
+                for (const [name, adapter] of adaptersToSearch) {
+                    try {
+                        const discovered = await adapter.discover();
+                        let match = discovered.find((d) => d.id === id);
+                        // Prefix match
+                        if (!match) {
+                            const prefixMatches = discovered.filter((d) => d.id.startsWith(id));
+                            if (prefixMatches.length === 1)
+                                match = prefixMatches[0];
+                        }
+                        if (match) {
+                            const meta = ctx.sessionTracker.getSession(match.id);
+                            return {
+                                id: match.id,
+                                adapter: name,
+                                status: match.status,
+                                startedAt: match.startedAt?.toISOString() ?? new Date().toISOString(),
+                                stoppedAt: match.stoppedAt?.toISOString(),
+                                cwd: match.cwd ?? meta?.cwd,
+                                model: match.model ?? meta?.model,
+                                prompt: match.prompt ?? meta?.prompt,
+                                tokens: match.tokens,
+                                cost: match.cost,
+                                pid: match.pid,
+                                spec: meta?.spec,
+                                group: meta?.group,
+                                meta: match.nativeMetadata ?? meta?.meta ?? {},
+                            };
+                        }
+                    }
+                    catch {
+                        // Adapter failed — try next
+                    }
+                }
+                // Fall back to launch metadata if adapters didn't find it
+                if (launchRecord)
+                    return launchRecord;
+                throw new Error(`Session not found: ${id}`);
             }
             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,
                 });
@@ -281,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.`);
                 }
@@ -315,47 +430,76 @@ function createRequestHandler(ctx) {
                 return record;
             }
             case "session.stop": {
-                const session = ctx.sessionTracker.getSession(params.id);
-                if (!session)
-                    throw new Error(`Session not found: ${params.id}`);
+                const id = params.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 (session.id.startsWith("pending-") &&
+                if (sessionId.startsWith("pending-") &&
                     params.force &&
-                    session.pid &&
-                    !isProcessAlive(session.pid)) {
-                    ctx.lockManager.autoUnlock(session.id);
-                    ctx.sessionTracker.removeSession(session.id);
+                    launchRecord?.pid &&
+                    !isProcessAlive(launchRecord.pid)) {
+                    ctx.lockManager.autoUnlock(sessionId);
+                    ctx.sessionTracker.removeSession(sessionId);
                     return null;
                 }
-                const adapter = ctx.adapters[session.adapter];
+                const adapterName = params.adapter || launchRecord?.adapter;
+                if (!adapterName)
+                    throw new Error(`Session not found: ${id}. Specify --adapter to stop a non-daemon session.`);
+                const adapter = ctx.adapters[adapterName];
                 if (!adapter)
-                    throw new Error(`Unknown adapter: ${session.adapter}`);
-                await adapter.stop(session.id, {
+                    throw new Error(`Unknown adapter: ${adapterName}`);
+                await adapter.stop(sessionId, {
                     force: params.force,
                 });
                 // Remove auto-lock
-                ctx.lockManager.autoUnlock(session.id);
-                // Mark stopped
-                const stopped = ctx.sessionTracker.onSessionExit(session.id);
+                ctx.lockManager.autoUnlock(sessionId);
+                // Mark stopped in launch metadata
+                const stopped = ctx.sessionTracker.onSessionExit(sessionId);
                 if (stopped) {
                     ctx.metrics.recordSessionStopped();
                 }
                 return null;
             }
             case "session.resume": {
-                const session = ctx.sessionTracker.getSession(params.id);
-                if (!session)
-                    throw new Error(`Session not found: ${params.id}`);
-                const adapter = ctx.adapters[session.adapter];
+                const id = params.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: ${session.adapter}`);
-                await adapter.resume(session.id, params.message);
+                    throw new Error(`Unknown adapter: ${adapterName}`);
+                await adapter.resume(resumeId, params.message);
                 return null;
             }
-            // --- Prune command (#40) ---
+            // --- Prune command (#40) --- kept for CLI backward compat
             case "session.prune": {
-                const pruned = ctx.sessionTracker.pruneDeadSessions();
-                return { pruned };
+                // In the stateless model, there's no session registry to prune.
+                // Clean up dead launches (PID liveness check) as a best-effort action.
+                const deadIds = ctx.sessionTracker.cleanupDeadLaunches();
+                for (const id of deadIds) {
+                    ctx.lockManager.autoUnlock(id);
+                }
+                return { pruned: deadIds.length };
             }
             case "lock.list":
                 return ctx.lockManager.listAll();
@@ -388,7 +532,7 @@ function createRequestHandler(ctx) {
                 return {
                     pid: process.pid,
                     uptime: Date.now() - startTime,
-                    sessions: ctx.sessionTracker.activeCount(),
+                    sessions: ctx.metrics.activeSessionCount,
                     locks: ctx.lockManager.listAll().length,
                     fuses: ctx.fuseEngine.listActive().length,
                 };

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

@@ -1,61 +1,78 @@
-import type { AgentAdapter, AgentSession } from "../core/types.js";
+import type { AgentAdapter, AgentSession, DiscoveredSession } from "../core/types.js";
 import type { SessionRecord, StateManager } from "./state.js";
 export interface SessionTrackerOpts {
     adapters: Record<string, AgentAdapter>;
-    pollIntervalMs?: number;
     /** Override PID liveness check for testing (default: process.kill(pid, 0)) */
     isProcessAlive?: (pid: number) => boolean;
 }
+/**
+ * Simplified session tracker for the stateless daemon core (ADR 004).
+ *
+ * Adapters own session truth. The daemon only tracks:
+ * - Launch metadata (prompt, group, spec, cwd) for sessions launched via agentctl
+ * - Locks and fuses (handled by LockManager / FuseEngine)
+ *
+ * The old polling loop, pruning, and state-based session registry are removed.
+ * session.list now fans out adapter.discover() at call time.
+ */
 export declare class SessionTracker {
     private state;
     private adapters;
-    private pollIntervalMs;
-    private pollHandle;
-    private polling;
     private readonly isProcessAlive;
+    private cleanupHandle;
+    private pendingResolutionHandle;
     constructor(state: StateManager, opts: SessionTrackerOpts);
-    startPolling(): void;
-    /** Run poll() with a guard to skip if the previous cycle is still running */
-    private guardedPoll;
-    stopPolling(): void;
-    private poll;
     /**
-     * Clean up ghost sessions in the daemon state:
-     * - pending-* entries whose PID matches a resolved session → remove pending
-     * - Any "running"/"idle" session in state whose PID is dead → mark stopped
+     * Start periodic PID liveness check for daemon-launched sessions.
+     * This is a lightweight check (no adapter fan-out) that runs every 30s
+     * to detect dead sessions and return their IDs for lock cleanup.
      */
-    private reapStaleEntries;
+    startLaunchCleanup(onDead?: (sessionId: string) => void): void;
+    stopLaunchCleanup(): void;
     /**
-     * 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.
+     * Start periodic background resolution of pending-* session IDs.
+     * Runs every 10s, discovers real UUIDs via adapter PID matching.
      */
-    validateAllSessions(): void;
+    startPendingResolution(onResolved?: (oldId: string, newId: string) => void): void;
+    stopPendingResolution(): void;
     /**
-     * Aggressively prune all clearly-dead sessions (#40).
-     * Returns the number of sessions pruned.
-     * Called via `agentctl prune` command.
+     * Resolve a single pending-* session ID on demand.
+     * Returns the resolved real UUID, or the original ID if resolution fails.
      */
-    pruneDeadSessions(): number;
+    resolvePendingId(id: string): Promise<string>;
     /**
-     * Remove stopped sessions from state that have been stopped for more than 7 days.
-     * This reduces overhead from accumulating hundreds of historical sessions.
+     * 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.
      */
-    private pruneOldSessions;
-    /** Track a newly launched session */
+    resolvePendingSessions(): Promise<Map<string, string>>;
+    /** Track a newly launched session (stores launch metadata in state) */
     track(session: AgentSession, adapterName: string): SessionRecord;
-    /** Get session record by id (exact or prefix) */
+    /** Get session launch metadata by id (exact or prefix match) */
     getSession(id: string): SessionRecord | undefined;
-    /** List all tracked sessions */
-    listSessions(opts?: {
-        status?: string;
-        all?: boolean;
-        adapter?: string;
-    }): SessionRecord[];
-    activeCount(): number;
-    /** Remove a session from state entirely (used for ghost cleanup) */
+    /** Remove a session from launch metadata */
     removeSession(sessionId: string): void;
-    /** Called when a session stops — returns the cwd for fuse/lock processing */
+    /** Called when a session stops — marks it in launch metadata, returns the record */
     onSessionExit(sessionId: string): SessionRecord | undefined;
+    /**
+     * Merge adapter-discovered sessions with daemon launch metadata.
+     *
+     * 1. Enrich discovered sessions with launch metadata (prompt, group, spec, etc.)
+     * 2. Reconcile: mark daemon-launched sessions as stopped if their adapter
+     *    succeeded but didn't return them (and they're past the grace period).
+     * 3. Include recently-launched sessions that adapters haven't discovered yet.
+     *
+     * Returns the merged session list and IDs of sessions that were marked stopped
+     * (for lock cleanup by the caller).
+     */
+    reconcileAndEnrich(discovered: DiscoveredSession[], succeededAdapters: Set<string>): {
+        sessions: SessionRecord[];
+        stoppedLaunchIds: string[];
+    };
+    /**
+     * Check PID liveness for daemon-launched sessions.
+     * Returns IDs of sessions whose PIDs have died.
+     * This is a lightweight check (no adapter fan-out) for lock cleanup.
+     */
+    cleanupDeadLaunches(): string[];
 }

package/dist/daemon/session-tracker.js

@@ -1,220 +1,158 @@
-/** Max age for stopped sessions in state before pruning (7 days) */
-const STOPPED_SESSION_PRUNE_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Grace period for recently-launched sessions.
+ * If a session was launched less than this many ms ago and the adapter
+ * doesn't return it yet, don't mark it stopped — the adapter may not
+ * have discovered it yet.
+ */
+const LAUNCH_GRACE_PERIOD_MS = 30_000;
+/**
+ * Simplified session tracker for the stateless daemon core (ADR 004).
+ *
+ * Adapters own session truth. The daemon only tracks:
+ * - Launch metadata (prompt, group, spec, cwd) for sessions launched via agentctl
+ * - Locks and fuses (handled by LockManager / FuseEngine)
+ *
+ * The old polling loop, pruning, and state-based session registry are removed.
+ * session.list now fans out adapter.discover() at call time.
+ */
 export class SessionTracker {
     state;
     adapters;
-    pollIntervalMs;
-    pollHandle = null;
-    polling = false;
     isProcessAlive;
+    cleanupHandle = null;
+    pendingResolutionHandle = null;
     constructor(state, opts) {
         this.state = state;
         this.adapters = opts.adapters;
-        this.pollIntervalMs = opts.pollIntervalMs ?? 5000;
         this.isProcessAlive = opts.isProcessAlive ?? defaultIsProcessAlive;
     }
-    startPolling() {
-        if (this.pollHandle)
-            return;
-        // Prune old stopped sessions on startup
-        this.pruneOldSessions();
-        // Initial poll
-        this.guardedPoll();
-        this.pollHandle = setInterval(() => {
-            this.guardedPoll();
-        }, this.pollIntervalMs);
-    }
-    /** Run poll() with a guard to skip if the previous cycle is still running */
-    guardedPoll() {
-        if (this.polling)
+    /**
+     * Start periodic PID liveness check for daemon-launched sessions.
+     * This is a lightweight check (no adapter fan-out) that runs every 30s
+     * to detect dead sessions and return their IDs for lock cleanup.
+     */
+    startLaunchCleanup(onDead) {
+        if (this.cleanupHandle)
             return;
-        this.polling = true;
-        this.poll()
-            .catch((err) => console.error("Poll error:", err))
-            .finally(() => {
-            this.polling = false;
-        });
-    }
-    stopPolling() {
-        if (this.pollHandle) {
-            clearInterval(this.pollHandle);
-            this.pollHandle = null;
-        }
-    }
-    async poll() {
-        // 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 {
-                // 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(disc.id);
-                    const record = discoveredToRecord(disc, adapterName);
-                    if (!existing) {
-                        this.state.setSession(disc.id, record);
-                    }
-                    else if (existing.status !== record.status ||
-                        (!existing.model && record.model)) {
-                        // Status changed or model resolved — update, preserving metadata
-                        this.state.setSession(disc.id, {
-                            ...existing,
-                            status: record.status,
-                            stoppedAt: record.stoppedAt,
-                            model: record.model || existing.model,
-                            tokens: record.tokens,
-                            cost: record.cost,
-                            prompt: record.prompt || existing.prompt,
-                            pid: record.pid,
-                        });
-                    }
-                }
-            }
-            catch {
-                // Adapter unavailable — skip
+        this.cleanupHandle = setInterval(() => {
+            const dead = this.cleanupDeadLaunches();
+            if (onDead) {
+                for (const id of dead)
+                    onDead(id);
             }
+        }, 30_000);
+    }
+    stopLaunchCleanup() {
+        if (this.cleanupHandle) {
+            clearInterval(this.cleanupHandle);
+            this.cleanupHandle = null;
         }
-        // Reap stale entries from daemon state
-        this.reapStaleEntries(adapterPidToId);
     }
     /**
-     * Clean up ghost sessions in the daemon state:
-     * - pending-* entries whose PID matches a resolved session → remove pending
-     * - Any "running"/"idle" session in state whose PID is dead → mark stopped
+     * Start periodic background resolution of pending-* session IDs.
+     * Runs every 10s, discovers real UUIDs via adapter PID matching.
      */
-    reapStaleEntries(adapterPidToId) {
-        const sessions = this.state.getSessions();
-        for (const [id, record] of Object.entries(sessions)) {
-            // Bug 2: If this is a pending-* entry and a real session has the same PID,
-            // the pending entry is stale — remove it
-            if (id.startsWith("pending-") && record.pid) {
-                const resolvedId = adapterPidToId.get(record.pid);
-                if (resolvedId && resolvedId !== id) {
-                    this.state.removeSession(id);
-                    continue;
-                }
-            }
-            // Bug 1: If session is "running"/"idle" but PID is dead, mark stopped
-            if ((record.status === "running" || record.status === "idle") &&
-                record.pid) {
-                // Only reap if the adapter didn't return this session as running
-                // (adapter is the source of truth for sessions it knows about)
-                const adapterId = adapterPidToId.get(record.pid);
-                if (adapterId === id)
-                    continue; // Adapter confirmed this PID is active
-                if (!this.isProcessAlive(record.pid)) {
-                    this.state.setSession(id, {
-                        ...record,
-                        status: "stopped",
-                        stoppedAt: new Date().toISOString(),
-                    });
+    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;
         }
     }
     /**
-     * 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.
+     * Resolve a single pending-* session ID on demand.
+     * Returns the resolved real UUID, or the original ID if resolution fails.
      */
-    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++;
+    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;
             }
         }
-        if (cleaned > 0) {
-            console.error(`Validated sessions on startup: marked ${cleaned} dead sessions as stopped`);
+        catch {
+            // Adapter failed — return original ID
         }
+        return id;
     }
     /**
-     * Aggressively prune all clearly-dead sessions (#40).
-     * Returns the number of sessions pruned.
-     * Called via `agentctl prune` command.
+     * 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.
      */
-    pruneDeadSessions() {
+    async resolvePendingSessions() {
+        const resolved = new Map();
         const sessions = this.state.getSessions();
-        let pruned = 0;
+        // Group pending sessions by adapter
+        const pendingByAdapter = new Map();
         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++;
-                }
+            if (!id.startsWith("pending-"))
                 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++;
-                }
-            }
+            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);
         }
-        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.
-     */
-    pruneOldSessions() {
-        const sessions = this.state.getSessions();
-        const now = Date.now();
-        let pruned = 0;
-        for (const [id, record] of Object.entries(sessions)) {
-            if (record.status !== "stopped" &&
-                record.status !== "completed" &&
-                record.status !== "failed") {
+        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);
+                    }
+                }
             }
-            const stoppedAt = record.stoppedAt
-                ? new Date(record.stoppedAt).getTime()
-                : new Date(record.startedAt).getTime();
-            if (now - stoppedAt > STOPPED_SESSION_PRUNE_AGE_MS) {
-                this.state.removeSession(id);
-                pruned++;
+            catch {
+                // Adapter failed — skip
             }
         }
-        if (pruned > 0) {
-            console.error(`Pruned ${pruned} sessions stopped >7 days ago from state`);
-        }
+        return resolved;
     }
-    /** Track a newly launched session */
+    /** Track a newly launched session (stores launch metadata in state) */
     track(session, adapterName) {
         const record = sessionToRecord(session, adapterName);
         // Pending→UUID reconciliation: if this is a real session (not pending),
@@ -229,7 +167,7 @@ export class SessionTracker {
         this.state.setSession(session.id, record);
         return record;
     }
-    /** Get session record by id (exact or prefix) */
+    /** Get session launch metadata by id (exact or prefix match) */
     getSession(id) {
         // Exact match
         const exact = this.state.getSession(id);
@@ -242,48 +180,11 @@ export class SessionTracker {
             return matches[0][1];
         return undefined;
     }
-    /** List all tracked sessions */
-    listSessions(opts) {
-        const sessions = Object.values(this.state.getSessions());
-        // Liveness check: mark sessions with dead PIDs as stopped
-        for (const s of sessions) {
-            if ((s.status === "running" || s.status === "idle") && s.pid) {
-                if (!this.isProcessAlive(s.pid)) {
-                    s.status = "stopped";
-                    s.stoppedAt = new Date().toISOString();
-                    this.state.setSession(s.id, s);
-                }
-            }
-        }
-        let filtered = sessions;
-        if (opts?.adapter) {
-            filtered = filtered.filter((s) => s.adapter === opts.adapter);
-        }
-        if (opts?.status) {
-            filtered = filtered.filter((s) => s.status === opts.status);
-        }
-        else if (!opts?.all) {
-            filtered = filtered.filter((s) => s.status === "running" || s.status === "idle");
-        }
-        // Dedup: if a pending-* entry shares a PID with a resolved entry, show only the resolved one
-        filtered = deduplicatePendingSessions(filtered);
-        return filtered.sort((a, b) => {
-            // Running first, then by recency
-            if (a.status === "running" && b.status !== "running")
-                return -1;
-            if (b.status === "running" && a.status !== "running")
-                return 1;
-            return new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime();
-        });
-    }
-    activeCount() {
-        return Object.values(this.state.getSessions()).filter((s) => s.status === "running" || s.status === "idle").length;
-    }
-    /** Remove a session from state entirely (used for ghost cleanup) */
+    /** Remove a session from launch metadata */
     removeSession(sessionId) {
         this.state.removeSession(sessionId);
     }
-    /** Called when a session stops — returns the cwd for fuse/lock processing */
+    /** Called when a session stops — marks it in launch metadata, returns the record */
     onSessionExit(sessionId) {
         const session = this.state.getSession(sessionId);
         if (session) {
@@ -293,6 +194,91 @@ export class SessionTracker {
         }
         return session;
     }
+    /**
+     * Merge adapter-discovered sessions with daemon launch metadata.
+     *
+     * 1. Enrich discovered sessions with launch metadata (prompt, group, spec, etc.)
+     * 2. Reconcile: mark daemon-launched sessions as stopped if their adapter
+     *    succeeded but didn't return them (and they're past the grace period).
+     * 3. Include recently-launched sessions that adapters haven't discovered yet.
+     *
+     * Returns the merged session list and IDs of sessions that were marked stopped
+     * (for lock cleanup by the caller).
+     */
+    reconcileAndEnrich(discovered, succeededAdapters) {
+        // Build lookups for discovered sessions
+        const discoveredIds = new Set(discovered.map((d) => d.id));
+        const discoveredPids = new Map();
+        for (const d of discovered) {
+            if (d.pid)
+                discoveredPids.set(d.pid, d.id);
+        }
+        // 1. Convert discovered sessions to records, enriching with launch metadata
+        const sessions = discovered.map((disc) => enrichDiscovered(disc, this.state.getSession(disc.id)));
+        // 2. Reconcile daemon-launched sessions that disappeared from adapter results
+        const stoppedLaunchIds = [];
+        const now = Date.now();
+        for (const [id, record] of Object.entries(this.state.getSessions())) {
+            if (record.status !== "running" &&
+                record.status !== "idle" &&
+                record.status !== "pending")
+                continue;
+            // If adapter for this session didn't succeed, include as-is from launch metadata
+            // (we can't verify status, so trust the last-known state)
+            if (!succeededAdapters.has(record.adapter)) {
+                sessions.push(record);
+                continue;
+            }
+            // Skip if adapter returned this session (it's still active)
+            if (discoveredIds.has(id))
+                continue;
+            // Check if this session's PID was resolved to a different ID (pending→UUID)
+            if (record.pid && discoveredPids.has(record.pid)) {
+                // PID was resolved to a real session — remove stale launch entry
+                this.state.removeSession(id);
+                stoppedLaunchIds.push(id);
+                continue;
+            }
+            // Grace period: don't mark recently-launched sessions as stopped
+            const launchAge = now - new Date(record.startedAt).getTime();
+            if (launchAge < LAUNCH_GRACE_PERIOD_MS) {
+                // Still within grace period — include as-is in results
+                sessions.push(record);
+                continue;
+            }
+            // Session disappeared from adapter results — mark stopped
+            this.state.setSession(id, {
+                ...record,
+                status: "stopped",
+                stoppedAt: new Date().toISOString(),
+            });
+            stoppedLaunchIds.push(id);
+        }
+        return { sessions, stoppedLaunchIds };
+    }
+    /**
+     * Check PID liveness for daemon-launched sessions.
+     * Returns IDs of sessions whose PIDs have died.
+     * This is a lightweight check (no adapter fan-out) for lock cleanup.
+     */
+    cleanupDeadLaunches() {
+        const dead = [];
+        for (const [id, record] of Object.entries(this.state.getSessions())) {
+            if (record.status !== "running" &&
+                record.status !== "idle" &&
+                record.status !== "pending")
+                continue;
+            if (record.pid && !this.isProcessAlive(record.pid)) {
+                this.state.setSession(id, {
+                    ...record,
+                    status: "stopped",
+                    stoppedAt: new Date().toISOString(),
+                });
+                dead.push(id);
+            }
+        }
+        return dead;
+    }
 }
 /** Check if a process is alive via kill(pid, 0) signal check */
 function defaultIsProcessAlive(pid) {
@@ -305,22 +291,25 @@ function defaultIsProcessAlive(pid) {
     }
 }
 /**
- * Remove pending-* entries that share a PID with a resolved (non-pending) session.
- * This is a safety net for list output — the poll() reaper handles cleanup in state.
+ * Convert a discovered session to a SessionRecord, enriching with launch metadata.
  */
-function deduplicatePendingSessions(sessions) {
-    const realPids = new Set();
-    for (const s of sessions) {
-        if (!s.id.startsWith("pending-") && s.pid) {
-            realPids.add(s.pid);
-        }
-    }
-    return sessions.filter((s) => {
-        if (s.id.startsWith("pending-") && s.pid && realPids.has(s.pid)) {
-            return false;
-        }
-        return true;
-    });
+function enrichDiscovered(disc, launchMeta) {
+    return {
+        id: disc.id,
+        adapter: disc.adapter,
+        status: disc.status,
+        startedAt: disc.startedAt?.toISOString() ?? new Date().toISOString(),
+        stoppedAt: disc.stoppedAt?.toISOString(),
+        cwd: disc.cwd ?? launchMeta?.cwd,
+        model: disc.model ?? launchMeta?.model,
+        prompt: disc.prompt ?? launchMeta?.prompt,
+        tokens: disc.tokens,
+        cost: disc.cost,
+        pid: disc.pid,
+        spec: launchMeta?.spec,
+        group: launchMeta?.group,
+        meta: disc.nativeMetadata ?? launchMeta?.meta ?? {},
+    };
 }
 function sessionToRecord(session, adapterName) {
     return {
@@ -340,20 +329,3 @@ 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/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.3.0",
+  "version": "1.5.0",
   "description": "Universal agent supervision interface — monitor and control AI coding agents from a single CLI",
   "type": "module",
   "bin": {