agent-lyceum 0.17.3 → 0.19.0

package/dist/policy.js

@@ -1,7 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
 import { findOnPath } from "./fs-util.js";
-import { globStaticPrefix } from "./paths.js";
 export function commonFile(project) {
     return path.join(project.paths.shared, "common", "COMMON.md");
 }
@@ -123,8 +122,6 @@ export function writePolicy(project, agent) {
         readDirs: shared && !mayWriteShared ? [shared] : [],
         allowFiles,
         deny: [...new Set(deny)],
-        owns: agent.owns,
-        restrictRepoToOwns: project.dispatcher.max_parallel > 1 && agent.owns.length > 0 && !isLead,
     };
 }
 let sandboxProbe;
@@ -139,16 +136,19 @@ function osSandboxAvailable() {
         sandboxProbe = false;
     return sandboxProbe;
 }
+/** Test seam: pretend the OS sandbox is (un)available; `undefined` re-probes the host. */
+export function setOsSandboxForTest(available) {
+    sandboxProbe = available;
+}
 export function enforcementFor(project, agent) {
     const pol = writePolicy(project, agent);
     const os = osSandboxAvailable();
     const notes = [];
-    const parallel = project.dispatcher.max_parallel > 1;
     const isLeadAgent = agent.name === project.lead;
     let e;
     if (agent.runtime === "claude-code") {
         const lvl = os ? "os" : "tool-rules";
-        e = { memory: lvl, agentMd: lvl, otherContext: lvl, shared: isLeadAgent ? "n/a" : lvl, repoInstructions: lvl, owns: parallel ? "tool-rules" : "n/a" };
+        e = { memory: lvl, agentMd: lvl, otherContext: lvl, shared: isLeadAgent ? "n/a" : lvl, repoInstructions: lvl };
         if (!os)
             notes.push("OS sandbox unavailable (Windows, or Linux without bubblewrap): Bash can bypass Edit rules.");
         if (!isLeadAgent && !os)
@@ -156,7 +156,7 @@ export function enforcementFor(project, agent) {
     }
     else {
         const lvl = os ? "os" : "prompt-only";
-        e = { memory: lvl, agentMd: lvl, otherContext: lvl, shared: isLeadAgent ? "n/a" : os ? "os" : "post-hoc", repoInstructions: "post-hoc", owns: parallel ? "prompt-only" : "n/a" };
+        e = { memory: lvl, agentMd: lvl, otherContext: lvl, shared: isLeadAgent ? "n/a" : os ? "os" : "post-hoc", repoInstructions: "post-hoc" };
         notes.push("Codex cannot forbid single files inside the repo; CLAUDE.md/AGENTS.md changes are detected and reverted after each wake-up.");
         if (!isLeadAgent && !os)
             notes.push("Without the OS sandbox only the handoff index (_shared/MEMORY.md) is checked after each wake-up; other files in _shared are not protected.");
@@ -171,10 +171,6 @@ export function enforcementFor(project, agent) {
         notes,
     };
 }
-/** Static directory prefixes (absolute) of an agent's `owns` globs. */
-export function ownsDirs(project, agent) {
-    return agent.owns.map((g) => path.join(project.dir, globStaticPrefix(g)));
-}
 /** Can `agent` legitimately change this protected file? */
 export function mayEditProtected(project, agent, file) {
     return writePolicy(project, agent).allowFiles.includes(file);

package/dist/process-runner.js

@@ -83,12 +83,14 @@ export function runInvocation(inv, opts) {
             void Promise.all([endStream(outLog), endStream(errLog)]).then(() => {
                 if (spawnError) {
                     const hint = spawnError.code === "ENOENT" ? ` ("${inv.cmd}" not found on PATH)` : "";
-                    return resolve({ ok: false, text: "", exitCode: null, timedOut: false, error: `${spawnError.message}${hint}` });
+                    // a missing binary is a crash the chain may route around (the next candidate can be another CLI); other spawn errors stay unclassified
+                    const kind = hint ? "crash" : "unknown";
+                    return resolve({ ok: false, text: "", exitCode: null, timedOut: false, error: `${spawnError.message}${hint}`, kind });
                 }
                 if (reason === "cancel")
                     return resolve({ ...cancelled, exitCode: exitCode ?? null });
                 if (reason === "timeout")
-                    return resolve({ ok: false, text: "", exitCode: exitCode ?? null, timedOut: true, error: `timed out after ${opts.timeoutSec}s` });
+                    return resolve({ ok: false, text: "", exitCode: exitCode ?? null, timedOut: true, error: `timed out after ${opts.timeoutSec}s`, kind: "timeout" });
                 const parsed = parser
                     ? parser.finish({ code: exitCode ?? null, stdoutTail: stdoutTail.text(), stderrTail: stderrTail.text() })
                     : inv.parse({ stdout: fallback.length ? fallback.toString("utf8") : stdoutTail.text(), stderr: stderrTail.text(), code: exitCode ?? null });

package/dist/project-lock.d.ts

@@ -4,10 +4,13 @@ export declare const LOCK_FILE = "lock.json";
 export declare const LOCKS_DIR = "locks";
 export interface LockOptions {
     heartbeatMs?: number;
-    /** Most runs that may hold a lock of this project at once, this one included. Default 1. */
-    maxConcurrent?: number;
+    /** The run works directly in the project checkout (not in its own worktree): only one such run may be active. It is written with `exclusive` too, so older binaries keep out. */
+    checkout?: boolean;
     /** The holder needs the whole project (e.g. a memory tidy): refused while any other lock is alive, and it keeps every other lock out while held. */
     exclusive?: boolean;
+    /** For a checkout run's refusal message: the checkout directory, and why this run has no worktree. */
+    dir?: string;
+    reason?: string;
 }
 export interface LockInfo {
     token: string;
@@ -20,7 +23,12 @@ export interface LockInfo {
     heartbeat_at: string;
     /** Held by an operation that needs the project to itself (a memory tidy). */
     exclusive?: boolean;
+    /** `true`: works in the project checkout; `false`: in its own worktree (or holds no files, like `clear`). Absent: an older version's run, treated as a checkout run. */
+    checkout?: boolean;
 }
+export type LockKind = "checkout" | "whole" | "worktree";
+/** What a lock protects: the checkout, the whole project (tidy/restore), or nothing shared (a worktree run). Locks of older versions count as checkout runs. */
+export declare function lockKind(l: Pick<LockInfo, "exclusive" | "checkout">): LockKind;
 export interface ProjectLease {
     readonly info: LockInfo;
     /** True once another process replaced our lock file; the run should stop writing. */

package/dist/project-lock.js

@@ -10,6 +10,16 @@ export const LOCK_FILE = "lock.json";
 export const LOCKS_DIR = "locks";
 const ADMIT_FILE = ".admit";
 const HEARTBEAT_MS = 5000;
+/** What a lock protects: the checkout, the whole project (tidy/restore), or nothing shared (a worktree run). Locks of older versions count as checkout runs. */
+export function lockKind(l) {
+    if (l.exclusive && l.checkout === true)
+        return "checkout";
+    if (l.exclusive)
+        return "whole";
+    if (l.checkout === false)
+        return "worktree";
+    return "checkout";
+}
 /** Field 22 (starttime, in clock ticks) of a /proc/<pid>/stat line. The command name (field 2) may contain spaces and ")". */
 export function parseProcStat(text) {
     const end = text.lastIndexOf(")");
@@ -137,10 +147,9 @@ function heldError(info) {
     return new Error(`Run ${info.run_id} is still running (pid ${info.pid}, heartbeat ${Number.isFinite(late) ? late : "?"}s ago). ` +
         `A run cannot be started or resumed twice; wait for it to end, or stop it first.`);
 }
-function limitError(active, max) {
-    const list = active.map((l) => `${l.run_id} (pid ${l.pid})`).join(", ");
-    return new Error(`This project already has ${active.length} run(s) active: ${list}. At most ${max} may run at once (dispatcher.max_concurrent_runs: ${max}); ` +
-        `wait for one to end, stop one, or raise max_concurrent_runs in project.yaml.`);
+function checkoutBusyError(holder, dir, reason) {
+    return new Error(`Run ${holder.run_id} (pid ${holder.pid}) is working directly in ${dir}, and this run would too (${reason}), so only one can be active. ` +
+        `Wait for it to end or stop it; in a git repo with a commit, runs work in their own worktrees and can run side by side.`);
 }
 function exclusiveError(holder) {
     return new Error(`${holder.run_id} (pid ${holder.pid}) needs the project to itself (a memory tidy or restore); wait for it to finish, then try again.`);
@@ -214,7 +223,6 @@ export function acquireProjectLock(root, runId, opts = {}) {
     assertRunId(runId);
     fs.mkdirSync(path.join(root, LOCKS_DIR), { recursive: true });
     const file = runLockFile(root, runId);
-    const max = opts.maxConcurrent ?? 1;
     const now = new Date().toISOString();
     const info = {
         token: crypto.randomBytes(16).toString("hex"),
@@ -224,8 +232,10 @@ export function acquireProjectLock(root, runId, opts = {}) {
         run_id: runId,
         acquired_at: now,
         heartbeat_at: now,
-        ...(opts.exclusive ? { exclusive: true } : {}),
+        ...(opts.exclusive || opts.checkout ? { exclusive: true } : {}),
+        checkout: opts.checkout === true,
     };
+    const kind = lockKind(info);
     withAdmission(root, () => {
         // 1. This run's own lock: a live holder means it is already running; a dead one is replaced.
         const own = readLockFile(file);
@@ -246,13 +256,14 @@ export function acquireProjectLock(root, runId, opts = {}) {
             fs.rmSync(legacyFile(root), { force: true });
         // 3. The other runs that are active now.
         const active = listRunLocks(root).filter((l) => l.run_id !== runId && lockHolderAlive(l));
-        const exclusiveHolder = active.find((l) => l.exclusive);
-        if (exclusiveHolder)
-            throw exclusiveError(exclusiveHolder);
-        if (opts.exclusive && active.length)
+        const whole = active.find((l) => lockKind(l) === "whole");
+        if (whole)
+            throw exclusiveError(whole);
+        if (kind === "whole" && active.length)
             throw needsIdleError(active);
-        if (active.length >= max)
-            throw limitError(active, max);
+        const busy = kind === "checkout" ? active.find((l) => lockKind(l) === "checkout") : undefined;
+        if (busy)
+            throw checkoutBusyError(busy, opts.dir ?? root, opts.reason ?? "no worktree is available for it");
         if (!tryCreate(file, info))
             throw new Error(`Could not take the run lock ${file}; another process just took it. Try again.`);
     });

package/dist/prompt.js

@@ -131,9 +131,6 @@ export function buildSystemPrompt(project, agent) {
     lines.push("", "## Rules");
     lines.push("- Never edit any `AGENT.md`, `COMMON.md`, or the repository's own `CLAUDE.md`/`AGENTS.md`" +
         (isLead || agent.canEditAgentMd ? " unless you need to as lead (changes are logged)." : "."), "- Never touch another agent's memory, inbox or outbox, or the team's config files.", `- The shared team context is in \`${commonFile(project)}\`${isLead ? " (you maintain it; keep it short)" : " (read-only)"}.`, PR_ATTRIBUTION_RULE, NO_DAEMONS_RULE);
-    if (project.dispatcher.max_parallel > 1 && agent.owns.length > 0 && !isLead) {
-        lines.push(`- You own these repo paths and must only change files there: ${agent.owns.join(", ")}.`);
-    }
     return lines.join("\n");
 }
 /** Messages one wake-up handles: the oldest one, or for the lead a run of `reply`/`failure` mail (up to LEAD_BATCH_LIMIT) so it decides once on all of it. */

package/dist/run-outcome.d.ts

@@ -1,5 +1,5 @@
 import type { DoneContract } from "./format.js";
-import type { EndReason } from "./run-store.js";
+import type { EndReason, RunFailure } from "./run-store.js";
 import type { RunOutcome } from "./schema.js";
 export interface UnintegratedWork {
     agent: string;
@@ -16,17 +16,9 @@ export declare function resolveDoneOutcome(contract: DoneContract, rejections: n
 export declare function endOutcome(endReason: EndReason, done?: {
     outcome: RunOutcome;
     note?: string;
-}, failure?: {
-    agent: string;
-    error?: string;
-    attempts: number;
-}): {
+}, failure?: RunFailure): {
     outcome: RunOutcome;
     note?: string;
 };
 /** What to tell the user when an agent kept failing and the run stopped: where to look, what to fix, how to go on. */
-export declare function failureGuide(project: string, run: string, f: {
-    agent: string;
-    error?: string;
-    attempts: number;
-}, runDir: string): string;
+export declare function failureGuide(project: string, run: string, f: RunFailure, runDir: string): string;

package/dist/run-outcome.js

@@ -35,9 +35,14 @@ export function endOutcome(endReason, done, failure) {
 }
 /** What to tell the user when an agent kept failing and the run stopped: where to look, what to fix, how to go on. */
 export function failureGuide(project, run, f, runDir) {
+    // With a fallback chain: every model given up on, in order.
+    const tried = f.tried?.length
+        ? ["Models tried, in order:", ...f.tried.map((t, i) => `  ${i + 1}. ${t.model ? `${t.runtime}/${t.model}` : t.runtime}: ${t.kind ?? "unknown error"}${t.error ? ` (${t.error})` : ""}`)]
+        : [];
     return [
         "",
         `${f.agent} was called ${f.attempts} time(s) and failed every time (${f.error ?? "unknown error"}). The run stopped; nothing was lost: the message ${f.agent} was handling is still unread and the work done so far is kept.`,
+        ...tried,
         "To fix it:",
         `  1. Read why it failed: ${path.join(runDir, "log.jsonl")} (event "wake"), and the full output of each attempt in ${path.join(runDir, "mail", "attempts")}`,
         `  2. Fix the cause: the ${f.agent} CLI (installed, logged in, model name), a timeout (dispatcher.wake_timeout_sec), or its AGENT.md / the message it keeps failing on. Check with: agent-lyceum doctor -p ${project}`,

package/dist/run-session.d.ts

@@ -1,8 +1,8 @@
 import { type Invoker } from "./adapters/index.js";
 import type { ResolvedProject } from "./config.js";
 import type { RunOutcome } from "./schema.js";
-import { type ResultBranch } from "./worktree.js";
-import { newRunId, type EndReason, type RunState } from "./run-store.js";
+import { type ResultBranch, type WorkspacePlan } from "./worktree.js";
+import { newRunId, type EndReason, type RunFailure, type RunState } from "./run-store.js";
 import { type PreparedTask } from "./task.js";
 import { type CommandRunner, type PrOutcome } from "./open-pr.js";
 export { newRunId };
@@ -36,11 +36,7 @@ export interface RunSummary {
     /** The project's name, for the commands printed after the run. */
     project: string;
     /** The run stopped because this agent kept failing. */
-    failure?: {
-        agent: string;
-        error?: string;
-        attempts: number;
-    };
+    failure?: RunFailure;
 }
 export interface RunOptions {
     project: ResolvedProject;
@@ -52,6 +48,8 @@ export interface RunOptions {
     task?: PreparedTask;
     /** Continue this earlier run (same run dir, sessions and counters) instead of starting a new one. */
     resume?: RunState;
+    /** Where the run's agents work, decided by `planWorkspace` before the run's lock was taken; the session never recomputes it. */
+    plan: WorkspacePlan;
     /** Reopen a done run: this text becomes a new task for the lead. Only with `resume` of a run that ended `done`. */
     followup?: {
         text: string;
@@ -63,6 +61,8 @@ export interface RunOptions {
     /** Stop the run when this fires: running agents are killed, unread mail is kept, the run ends `cancelled` and can be resumed. */
     signal?: AbortSignal;
     log?: (line: string) => void;
+    /** The wait between retries of a model with a fallback chain; tests pass one that does not wait. Default: a timer cut short by `signal`. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
 }
 export declare class RunSession {
     private readonly opts;
@@ -87,6 +87,8 @@ export declare class RunSession {
     private doneOutcome;
     private doneNote;
     private failure;
+    /** Models cooling down after a rate limit or quota error; one table for the run, shared by parallel wake-ups. */
+    private readonly cooldowns;
     private doneVerification;
     /** The accepted `done` carried `open_pr: true` (only the lead can send `done`). */
     private openPrRequested;
@@ -111,6 +113,8 @@ export declare class RunSession {
     private pendingAgents;
     private pickBatch;
     private wake;
+    /** Copy the shared cooldown table into the state (only once something has cooled down); true when it was. */
+    private syncCooldowns;
     /**
      * A finished member's files go from its worktree into the repo before anyone reads its mail, so the lead
      * sees them. When that cannot be done, nothing is applied, the member's work stays on its branch, and the lead is told.