@orgloop/agentctl 1.1.0 → 1.2.0

package/dist/daemon/session-tracker.js

@@ -1,8 +1,11 @@
+/** Max age for stopped sessions in state before pruning (7 days) */
+const STOPPED_SESSION_PRUNE_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 export class SessionTracker {
     state;
     adapters;
     pollIntervalMs;
     pollHandle = null;
+    polling = false;
     isProcessAlive;
     constructor(state, opts) {
         this.state = state;
@@ -13,12 +16,25 @@ export class SessionTracker {
     startPolling() {
         if (this.pollHandle)
             return;
+        // Prune old stopped sessions on startup
+        this.pruneOldSessions();
         // Initial poll
-        this.poll().catch((err) => console.error("Poll error:", err));
+        this.guardedPoll();
         this.pollHandle = setInterval(() => {
-            this.poll().catch((err) => console.error("Poll error:", err));
+            this.guardedPoll();
         }, this.pollIntervalMs);
     }
+    /** Run poll() with a guard to skip if the previous cycle is still running */
+    guardedPoll() {
+        if (this.polling)
+            return;
+        this.polling = true;
+        this.poll()
+            .catch((err) => console.error("Poll error:", err))
+            .finally(() => {
+            this.polling = false;
+        });
+    }
     stopPolling() {
         if (this.pollHandle) {
             clearInterval(this.pollHandle);
@@ -40,14 +56,17 @@ export class SessionTracker {
                     if (!existing) {
                         this.state.setSession(session.id, record);
                     }
-                    else if (existing.status !== record.status) {
-                        // Status changed — update
+                    else if (existing.status !== record.status ||
+                        (!existing.model && record.model)) {
+                        // Status changed or model resolved — update
                         this.state.setSession(session.id, {
                             ...existing,
                             status: record.status,
                             stoppedAt: record.stoppedAt,
+                            model: record.model || existing.model,
                             tokens: record.tokens,
                             cost: record.cost,
+                            prompt: record.prompt || existing.prompt,
                         });
                     }
                 }
@@ -94,9 +113,44 @@ export class SessionTracker {
             }
         }
     }
+    /**
+     * 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") {
+                continue;
+            }
+            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++;
+            }
+        }
+        if (pruned > 0) {
+            console.error(`Pruned ${pruned} sessions stopped >7 days ago from state`);
+        }
+    }
     /** Track a newly launched session */
     track(session, adapterName) {
         const record = sessionToRecord(session, adapterName);
+        // Pending→UUID reconciliation: if this is a real session (not pending),
+        // remove any pending-PID placeholder with the same PID
+        if (!session.id.startsWith("pending-") && session.pid) {
+            for (const [id, existing] of Object.entries(this.state.getSessions())) {
+                if (id.startsWith("pending-") && existing.pid === session.pid) {
+                    this.state.removeSession(id);
+                }
+            }
+        }
         this.state.setSession(session.id, record);
         return record;
     }
@@ -116,7 +170,20 @@ export class SessionTracker {
     /** 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);
         }
@@ -137,6 +204,10 @@ export class SessionTracker {
     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) */
+    removeSession(sessionId) {
+        this.state.removeSession(sessionId);
+    }
     /** Called when a session stops — returns the cwd for fuse/lock processing */
     onSessionExit(sessionId) {
         const session = this.state.getSession(sessionId);
@@ -190,6 +261,7 @@ function sessionToRecord(session, adapterName) {
         tokens: session.tokens,
         cost: session.cost,
         pid: session.pid,
+        group: session.group,
         meta: session.meta,
     };
 }

package/dist/daemon/state.d.ts

@@ -15,6 +15,7 @@ export interface SessionRecord {
     cost?: number;
     pid?: number;
     exitCode?: number;
+    group?: string;
     meta: Record<string, unknown>;
 }
 export interface Lock {

package/dist/hooks.d.ts

@@ -6,6 +6,8 @@ export interface HookContext {
     adapter: string;
     branch?: string;
     exitCode?: number;
+    group?: string;
+    model?: string;
 }
 /**
  * Run a lifecycle hook script if defined.

package/dist/hooks.js

@@ -23,6 +23,10 @@ export async function runHook(hooks, phase, ctx) {
         env.AGENTCTL_BRANCH = ctx.branch;
     if (ctx.exitCode != null)
         env.AGENTCTL_EXIT_CODE = String(ctx.exitCode);
+    if (ctx.group)
+        env.AGENTCTL_GROUP = ctx.group;
+    if (ctx.model)
+        env.AGENTCTL_MODEL = ctx.model;
     try {
         const result = await execAsync(script, {
             cwd: ctx.cwd,

package/dist/launch-orchestrator.d.ts

@@ -0,0 +1,60 @@
+import type { AgentAdapter, LifecycleHooks } from "./core/types.js";
+/** A single adapter+model slot parsed from CLI flags */
+export interface AdapterSlot {
+    adapter: string;
+    model?: string;
+}
+/** Result of launching one slot within a group */
+export interface SlotLaunchResult {
+    slot: AdapterSlot;
+    sessionId: string;
+    pid?: number;
+    cwd: string;
+    branch: string;
+    error?: string;
+}
+/** Result of the full orchestrated launch */
+export interface OrchestratedLaunchResult {
+    groupId: string;
+    results: SlotLaunchResult[];
+}
+export interface OrchestrateOpts {
+    slots: AdapterSlot[];
+    prompt: string;
+    spec?: string;
+    cwd: string;
+    hooks?: LifecycleHooks;
+    adapters: Record<string, AgentAdapter>;
+    /** Optional: callback when daemon is available for lock/track */
+    onSessionLaunched?: (result: SlotLaunchResult) => void;
+    /** Optional: callback when group ID is generated (before launches) */
+    onGroupCreated?: (groupId: string) => void;
+}
+/** Generate a short group ID like "g-a1b2c3" */
+export declare function generateGroupId(): string;
+/**
+ * Generate a short suffix for a slot, used in worktree/branch naming.
+ * When an adapter appears multiple times, disambiguate using the model short name.
+ */
+export declare function slotSuffix(slot: AdapterSlot, allSlots: AdapterSlot[]): string;
+/** Build worktree path: <repo>-<groupId>-<suffix> */
+export declare function worktreePath(repo: string, groupId: string, suffix: string): string;
+/** Build branch name: try/<groupId>/<suffix> */
+export declare function branchName(groupId: string, suffix: string): string;
+/**
+ * Orchestrate a parallel multi-adapter launch.
+ *
+ * 1. Generate group ID
+ * 2. For each slot: create worktree, run on_worktree_create hook, launch adapter
+ * 3. Return all results (successes and failures)
+ */
+export declare function orchestrateLaunch(opts: OrchestrateOpts): Promise<OrchestratedLaunchResult>;
+/**
+ * Parse positional adapter slots from raw argv.
+ *
+ * Multiple --adapter flags, each optionally followed by --model:
+ *   --adapter claude-code --model opus --adapter codex
+ *
+ * Returns AdapterSlot[] representing each launch slot.
+ */
+export declare function parseAdapterSlots(rawArgs: string[]): AdapterSlot[];

package/dist/launch-orchestrator.js

@@ -0,0 +1,198 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { runHook } from "./hooks.js";
+import { createWorktree } from "./worktree.js";
+// --- Group ID generation ---
+/** Generate a short group ID like "g-a1b2c3" */
+export function generateGroupId() {
+    const hex = crypto.randomBytes(3).toString("hex");
+    return `g-${hex}`;
+}
+// --- Slot disambiguation ---
+/**
+ * Generate a short suffix for a slot, used in worktree/branch naming.
+ * When an adapter appears multiple times, disambiguate using the model short name.
+ */
+export function slotSuffix(slot, allSlots) {
+    const sameAdapter = allSlots.filter((s) => s.adapter === slot.adapter);
+    // Short adapter name: claude-code → cc, codex → codex, etc.
+    const adapterShort = shortenAdapter(slot.adapter);
+    if (sameAdapter.length <= 1) {
+        return adapterShort;
+    }
+    // Disambiguate with model short name
+    const modelShort = slot.model ? shortenModel(slot.model) : "default";
+    return `${adapterShort}-${modelShort}`;
+}
+/** Shorten adapter names for path-friendly suffixes */
+function shortenAdapter(adapter) {
+    const map = {
+        "claude-code": "cc",
+        "pi-rust": "pi-rs",
+    };
+    return map[adapter] || adapter;
+}
+/** Extract a short model name from a full model identifier */
+function shortenModel(model) {
+    // claude-opus-4-6 → opus, claude-sonnet-4-5 → sonnet
+    const opusMatch = model.match(/opus/i);
+    if (opusMatch)
+        return "opus";
+    const sonnetMatch = model.match(/sonnet/i);
+    if (sonnetMatch)
+        return "sonnet";
+    const haikuMatch = model.match(/haiku/i);
+    if (haikuMatch)
+        return "haiku";
+    // gpt-5.2-codex → gpt5-codex
+    const gptMatch = model.match(/gpt[- ]?(\d+)/i);
+    if (gptMatch) {
+        const rest = model.replace(/gpt[- ]?\d+\.?\d*/i, "").replace(/^[- .]+/, "");
+        return rest ? `gpt${gptMatch[1]}-${rest}` : `gpt${gptMatch[1]}`;
+    }
+    // Fallback: take last segment, sanitize
+    const parts = model.split(/[/:-]/);
+    return sanitizePath(parts[parts.length - 1] || model);
+}
+/** Sanitize a string for use in file paths and branch names */
+function sanitizePath(s) {
+    return s.replace(/[^a-zA-Z0-9-]/g, "").toLowerCase() || "default";
+}
+// --- Worktree + branch naming ---
+/** Build worktree path: <repo>-<groupId>-<suffix> */
+export function worktreePath(repo, groupId, suffix) {
+    const repoResolved = path.resolve(repo);
+    return `${repoResolved}-${groupId}-${suffix}`;
+}
+/** Build branch name: try/<groupId>/<suffix> */
+export function branchName(groupId, suffix) {
+    return `try/${groupId}/${suffix}`;
+}
+// --- Orchestrator ---
+/**
+ * Orchestrate a parallel multi-adapter launch.
+ *
+ * 1. Generate group ID
+ * 2. For each slot: create worktree, run on_worktree_create hook, launch adapter
+ * 3. Return all results (successes and failures)
+ */
+export async function orchestrateLaunch(opts) {
+    const { slots, prompt, spec, cwd, hooks, adapters } = opts;
+    const groupId = generateGroupId();
+    opts.onGroupCreated?.(groupId);
+    const repo = path.resolve(cwd);
+    // Phase 1: Create all worktrees (sequential to avoid git lock contention)
+    const worktrees = [];
+    for (const slot of slots) {
+        const suffix = slotSuffix(slot, slots);
+        const branch = branchName(groupId, suffix);
+        const worktree = await createWorktree({
+            repo,
+            branch,
+        });
+        // The createWorktree function names the path based on repo+branch slug.
+        // We need to override for our naming convention.
+        // Actually — createWorktree uses `<repo>-<branch-slug>` which for
+        // branch "try/g-a1b2c3/cc" becomes "<repo>-try-g-a1b2c3-cc".
+        // That's acceptable. Let's use the path it returns.
+        worktrees.push({ slot, suffix, branch, worktree });
+        // Run on_worktree_create hook (onCreate) if provided
+        if (hooks?.onCreate) {
+            await runHook(hooks, "onCreate", {
+                sessionId: "", // not yet launched
+                cwd: worktree.path,
+                adapter: slot.adapter,
+                branch,
+                group: groupId,
+                model: slot.model,
+            });
+        }
+    }
+    // Phase 2: Launch all adapters in parallel
+    const launchPromises = worktrees.map(async ({ slot, branch, worktree }) => {
+        const adapter = adapters[slot.adapter];
+        if (!adapter) {
+            return {
+                slot,
+                sessionId: "",
+                cwd: worktree.path,
+                branch,
+                error: `Unknown adapter: ${slot.adapter}`,
+            };
+        }
+        try {
+            const launchOpts = {
+                adapter: slot.adapter,
+                prompt,
+                spec,
+                cwd: worktree.path,
+                model: slot.model,
+                worktree: { repo: worktree.repo, branch },
+                hooks,
+            };
+            const session = await adapter.launch(launchOpts);
+            // Tag the session with the group
+            session.group = groupId;
+            const result = {
+                slot,
+                sessionId: session.id,
+                pid: session.pid,
+                cwd: worktree.path,
+                branch,
+            };
+            opts.onSessionLaunched?.(result);
+            return result;
+        }
+        catch (err) {
+            return {
+                slot,
+                sessionId: "",
+                cwd: worktree.path,
+                branch,
+                error: err.message,
+            };
+        }
+    });
+    const results = await Promise.all(launchPromises);
+    return { groupId, results };
+}
+// --- CLI flag parsing ---
+/**
+ * Parse positional adapter slots from raw argv.
+ *
+ * Multiple --adapter flags, each optionally followed by --model:
+ *   --adapter claude-code --model opus --adapter codex
+ *
+ * Returns AdapterSlot[] representing each launch slot.
+ */
+export function parseAdapterSlots(rawArgs) {
+    const slots = [];
+    let current = null;
+    for (let i = 0; i < rawArgs.length; i++) {
+        const arg = rawArgs[i];
+        if (arg === "--adapter" || arg === "-A") {
+            // Flush previous slot
+            if (current)
+                slots.push(current);
+            const value = rawArgs[++i];
+            if (!value || value.startsWith("-")) {
+                throw new Error(`--adapter requires a value`);
+            }
+            current = { adapter: value };
+        }
+        else if (arg === "--model" || arg === "-M") {
+            if (!current) {
+                throw new Error(`--model must follow an --adapter flag`);
+            }
+            const value = rawArgs[++i];
+            if (!value || value.startsWith("-")) {
+                throw new Error(`--model requires a value`);
+            }
+            current.model = value;
+        }
+    }
+    // Flush last slot
+    if (current)
+        slots.push(current);
+    return slots;
+}

package/dist/matrix-parser.d.ts

@@ -0,0 +1,40 @@
+import type { AdapterSlot } from "./launch-orchestrator.js";
+/** A single entry in the matrix array */
+export interface MatrixEntry {
+    adapter: string;
+    model?: string | string[];
+}
+/** Top-level matrix file schema */
+export interface MatrixFile {
+    prompt: string;
+    cwd?: string;
+    spec?: string;
+    hooks?: {
+        on_create?: string;
+        on_complete?: string;
+    };
+    matrix: MatrixEntry[];
+}
+/**
+ * Parse a YAML matrix file and expand into AdapterSlot[].
+ *
+ * Cross-product expansion: when a matrix entry has an array value for `model`,
+ * it expands into one slot per model value.
+ *
+ * Example:
+ *   matrix:
+ *     - adapter: claude-code
+ *       model: [opus, sonnet]
+ *     - adapter: codex
+ *
+ * Expands to 3 slots:
+ *   [{ adapter: "claude-code", model: "opus" },
+ *    { adapter: "claude-code", model: "sonnet" },
+ *    { adapter: "codex" }]
+ */
+export declare function parseMatrixFile(filePath: string): Promise<MatrixFile>;
+/**
+ * Expand a MatrixFile into AdapterSlot[].
+ * Handles cross-product expansion for array-valued fields.
+ */
+export declare function expandMatrix(matrix: MatrixFile): AdapterSlot[];

package/dist/matrix-parser.js

@@ -0,0 +1,69 @@
+import fs from "node:fs/promises";
+import YAML from "yaml";
+// --- Parsing ---
+/**
+ * Parse a YAML matrix file and expand into AdapterSlot[].
+ *
+ * Cross-product expansion: when a matrix entry has an array value for `model`,
+ * it expands into one slot per model value.
+ *
+ * Example:
+ *   matrix:
+ *     - adapter: claude-code
+ *       model: [opus, sonnet]
+ *     - adapter: codex
+ *
+ * Expands to 3 slots:
+ *   [{ adapter: "claude-code", model: "opus" },
+ *    { adapter: "claude-code", model: "sonnet" },
+ *    { adapter: "codex" }]
+ */
+export async function parseMatrixFile(filePath) {
+    const raw = await fs.readFile(filePath, "utf-8");
+    const parsed = YAML.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error(`Invalid matrix file: ${filePath}`);
+    }
+    if (!parsed.prompt || typeof parsed.prompt !== "string") {
+        throw new Error("Matrix file must have a 'prompt' field (string)");
+    }
+    if (!Array.isArray(parsed.matrix) || parsed.matrix.length === 0) {
+        throw new Error("Matrix file must have a non-empty 'matrix' array");
+    }
+    // Validate entries
+    for (const entry of parsed.matrix) {
+        if (!entry.adapter || typeof entry.adapter !== "string") {
+            throw new Error("Each matrix entry must have an 'adapter' field (string)");
+        }
+    }
+    return parsed;
+}
+/**
+ * Expand a MatrixFile into AdapterSlot[].
+ * Handles cross-product expansion for array-valued fields.
+ */
+export function expandMatrix(matrix) {
+    const slots = [];
+    for (const entry of matrix.matrix) {
+        const models = normalizeToArray(entry.model);
+        if (models.length === 0) {
+            // No model specified — single slot
+            slots.push({ adapter: entry.adapter });
+        }
+        else {
+            // One slot per model
+            for (const model of models) {
+                slots.push({ adapter: entry.adapter, model });
+            }
+        }
+    }
+    return slots;
+}
+/** Normalize a value to an array (handles string | string[] | undefined) */
+function normalizeToArray(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    return [value];
+}

package/dist/utils/partial-read.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Read the first N lines of a file by reading only `maxBytes` from the start.
+ * Avoids allocating the entire file into memory for large JSONL files.
+ *
+ * @param filePath - Path to the file
+ * @param maxLines - Maximum number of lines to return
+ * @param maxBytes - Maximum bytes to read from the start (default 8192)
+ * @returns Array of complete lines (up to maxLines)
+ */
+export declare function readHead(filePath: string, maxLines: number, maxBytes?: number): Promise<string[]>;
+/**
+ * Read the last N lines of a file by reading only `maxBytes` from the end.
+ * Avoids allocating the entire file into memory for large JSONL files.
+ *
+ * @param filePath - Path to the file
+ * @param maxLines - Maximum number of lines to return
+ * @param maxBytes - Maximum bytes to read from the end (default 65536)
+ * @returns Array of complete lines (up to maxLines, in order)
+ */
+export declare function readTail(filePath: string, maxLines: number, maxBytes?: number): Promise<string[]>;

package/dist/utils/partial-read.js

@@ -0,0 +1,66 @@
+import * as fs from "node:fs/promises";
+/**
+ * Read the first N lines of a file by reading only `maxBytes` from the start.
+ * Avoids allocating the entire file into memory for large JSONL files.
+ *
+ * @param filePath - Path to the file
+ * @param maxLines - Maximum number of lines to return
+ * @param maxBytes - Maximum bytes to read from the start (default 8192)
+ * @returns Array of complete lines (up to maxLines)
+ */
+export async function readHead(filePath, maxLines, maxBytes = 8192) {
+    const fh = await fs.open(filePath, "r");
+    try {
+        const stat = await fh.stat();
+        const bytesToRead = Math.min(maxBytes, stat.size);
+        if (bytesToRead === 0)
+            return [];
+        const buf = Buffer.alloc(bytesToRead);
+        const { bytesRead } = await fh.read(buf, 0, bytesToRead, 0);
+        if (bytesRead === 0)
+            return [];
+        const text = buf.subarray(0, bytesRead).toString("utf-8");
+        const lines = text.split("\n");
+        // If we didn't read the whole file, the last chunk may be incomplete — drop it
+        if (bytesRead < stat.size) {
+            lines.pop();
+        }
+        return lines.filter((l) => l.length > 0).slice(0, maxLines);
+    }
+    finally {
+        await fh.close();
+    }
+}
+/**
+ * Read the last N lines of a file by reading only `maxBytes` from the end.
+ * Avoids allocating the entire file into memory for large JSONL files.
+ *
+ * @param filePath - Path to the file
+ * @param maxLines - Maximum number of lines to return
+ * @param maxBytes - Maximum bytes to read from the end (default 65536)
+ * @returns Array of complete lines (up to maxLines, in order)
+ */
+export async function readTail(filePath, maxLines, maxBytes = 65536) {
+    const fh = await fs.open(filePath, "r");
+    try {
+        const stat = await fh.stat();
+        if (stat.size === 0)
+            return [];
+        const bytesToRead = Math.min(maxBytes, stat.size);
+        const offset = Math.max(0, stat.size - bytesToRead);
+        const buf = Buffer.alloc(bytesToRead);
+        const { bytesRead } = await fh.read(buf, 0, bytesToRead, offset);
+        if (bytesRead === 0)
+            return [];
+        const text = buf.subarray(0, bytesRead).toString("utf-8");
+        const lines = text.split("\n");
+        // If we didn't start from the beginning, the first chunk may be a partial line — drop it
+        if (offset > 0) {
+            lines.shift();
+        }
+        return lines.filter((l) => l.length > 0).slice(-maxLines);
+    }
+    finally {
+        await fh.close();
+    }
+}

package/dist/worktree.d.ts

@@ -22,3 +22,25 @@ export declare function createWorktree(opts: WorktreeCreateOpts): Promise<Worktr
  * Remove a git worktree.
  */
 export declare function removeWorktree(repo: string, worktreePath: string): Promise<void>;
+/** Info about an existing worktree from `git worktree list` */
+export interface WorktreeListEntry {
+    path: string;
+    branch: string;
+    head: string;
+    /** Whether this is the bare/main worktree */
+    bare: boolean;
+}
+/**
+ * List all git worktrees for a repo.
+ * Parses `git worktree list --porcelain` output.
+ */
+export declare function listWorktrees(repo: string): Promise<WorktreeListEntry[]>;
+/**
+ * Remove a worktree and optionally delete its branch.
+ */
+export declare function cleanWorktree(repo: string, worktreePath: string, opts?: {
+    deleteBranch?: boolean;
+}): Promise<{
+    removedPath: string;
+    deletedBranch?: string;
+}>;