agent-lyceum 0.11.0 → 0.12.0

package/dist/run-session.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { realInvoker } from "./adapters/index.js";
 import { briefOf, digestOf, doneContract, parseSteps } from "./format.js";
 import { ProtectedGuard } from "./guard.js";
-import { addBatch, askersWithAnswers, askReplyPath, checkAnswers, describeCheck, isComplete, markDelivered, parseAskBody, readAskReply, renderAnswers, writeAskReply } from "./ask-reply.js";
+import { addBatch, askersWithAnswers, askReplyPath, checkAnswers, describeCheck, isComplete, markDelivered, parseAskBody, readAskReply, renderAnswers, resolveOptionLetters, writeAskReply } from "./ask-reply.js";
 import { deliver, deliverOnce, ensureProjectDirs, finishDone, listUnread, rejectDone, routeOutboxes, unreadFiles } from "./mailbox.js";
 import { abandonClaim, attemptLogDir, sourceIdOf, beginAttempt, claimMessages, commitClaim, finishAttempt, markOutputReady, parkOutbox, recoverRunMail, RouteJournal } from "./message-store.js";
 import { isInside } from "./paths.js";
@@ -12,11 +12,12 @@ import { endOutcome, resolveDoneOutcome } from "./run-outcome.js";
 import { outboxDir, ownsDirs } from "./policy.js";
 import { buildSystemPrompt, buildUserPrompt, pickMessages } from "./prompt.js";
 import { atomicWrite } from "./fs-util.js";
-import { assertWorktreeRunnable, collectAgentChanges, existingAgentWorkspace, integrateAgentChanges, prepareAgentWorkspace, resolveWorkspaceMode, snapshotBase } from "./worktree.js";
+import { assertWorktreeRunnable, collectAgentChanges, dirtyPaths, existingAgentWorkspace, finishLeadBranch, integrateAgentChanges, prepareAgentWorkspace, refusedIntegration, resolveWorkspaceMode, snapshotBase, snapshotHead, toplevel } from "./worktree.js";
 import { bindRunProject, newRunId, newRunState, saveRunState } from "./run-store.js";
 import { soloProject } from "./solo.js";
 import { taskMessageBody } from "./task.js";
 import { must } from "./assert.js";
+import { openPullRequest, prBody, prTitle, realRunner } from "./open-pr.js";
 export { newRunId };
 export const RESULT_FILE = "result.md";
 /** How many times a non-conforming `done` goes back to the lead before it is accepted as `partial`. */
@@ -48,11 +49,18 @@ export class RunSession {
     doneOutcome;
     doneNote;
     doneVerification;
+    /** The accepted `done` carried `open_pr: true` (only the lead can send `done`). */
+    openPrRequested = false;
+    prRunner;
     /** Inbox mail each agent in the current batch is working on; it is marked read only after its output is routed. */
     claims = new Map();
     noSessionNoted = new Set();
     /** Git worktrees of the non-lead agents in the batch being woken (empty in shared mode and for the lead). */
     batchSpaces = {};
+    /** Members whose worktree was refused (its git files were tampered with): never woken again in this run. */
+    refused = new Set();
+    /** Concurrent runs: the lead's own git worktree for the whole run. */
+    leadSpace;
     /** The attempt that produced each batch member's output; committed together with its claim. */
     attempts = new Map();
     constructor(opts) {
@@ -71,12 +79,28 @@ export class RunSession {
         // Each run gets its own memory directory per agent and (new runs) its own mailboxes.
         const project = bindRunProject(base, runDir, layout);
         // Parallel agents work in their own git worktrees; refuse early (before anything is written) when that cannot be done.
-        const wsMode = resolveWorkspaceMode(cfg);
+        // Whether the lead has its own worktree is decided when the run starts and kept for its resumes, whatever the config says by then.
+        const concurrent = resume ? resume.lead_workspace === true : cfg.max_concurrent_runs > 1;
+        const wsMode = concurrent ? "worktree" : resolveWorkspaceMode({ ...cfg, max_concurrent_runs: 1 });
         if (wsMode === "worktree")
-            assertWorktreeRunnable(project, { fresh: !resume });
+            assertWorktreeRunnable(project, { fresh: !resume, concurrent });
+        // Concurrent runs: the lead works in its own worktree cut from HEAD, so no other run (and not you) shares its files.
+        let leadSpace;
+        if (concurrent && resume) {
+            leadSpace = existingAgentWorkspace(project, runId, project.lead);
+            if (!leadSpace)
+                throw new Error(`Run ${runId} has no worktree for ${project.lead} (was it cleared?), so it cannot be resumed.`);
+        }
         ensureProjectDirs(project);
         fs.mkdirSync(runDir, { recursive: true });
         const log = createRunLog(path.join(runDir, "log.jsonl"), cfg.log_max_bytes);
+        if (concurrent && !resume) {
+            // Before the task is delivered or any state written, so a failure here leaves no half-started run.
+            leadSpace = prepareAgentWorkspace(project, runId, project.lead, snapshotHead(project, runId));
+            const uncommitted = dirtyPaths(project.dir).length;
+            say(`  starting from HEAD ${leadSpace.base.slice(0, 8)}${uncommitted ? ` (your ${uncommitted} uncommitted file(s) are not part of this run)` : ""}; ${project.lead} works on branch ${leadSpace.branch}`);
+            log("lead-workspace", { base: leadSpace.base, branch: leadSpace.branch, dir: leadSpace.dir, uncommitted });
+        }
         let state;
         if (resume) {
             state = { ...resume, max_rounds: cfg.max_rounds, pid: process.pid, ended_at: undefined, end_reason: undefined, workspace_mode: wsMode, outcome: undefined, outcome_note: undefined, verification: undefined, active: {}, wakes: [...resume.wakes] };
@@ -108,13 +132,15 @@ export class RunSession {
                 mail_layout: layout,
                 workspace_mode: wsMode,
                 solo_agent: soloName,
+                lead_workspace: concurrent ? true : undefined,
             });
             const seed = parseSteps(task.content, false);
             if (seed.length)
                 state.steps = seed;
         }
         const saveState = () => saveRunState(runDir, state);
-        const guard = new ProtectedGuard(project);
+        // Concurrent runs: the repo's instruction files the run can touch are the lead worktree's copies; your own tree is never watched (or restored).
+        const guard = new ProtectedGuard(leadSpace ? { ...project, workspaces: { ...project.workspaces, [project.lead]: leadSpace } } : project);
         if (resume) {
             log("resume", { rounds: state.rounds, interrupted: Object.keys(resume.active ?? {}) });
         }
@@ -125,7 +151,9 @@ export class RunSession {
             log("start", { task_source: task.source, bytes: task.bytes, inline: task.inline });
         }
         saveState();
+        this.leadSpace = leadSpace;
         this.opts = opts;
+        this.prRunner = opts.pr ?? realRunner;
         this.resume = resume;
         this.invoke = invoke;
         this.say = say;
@@ -140,9 +168,12 @@ export class RunSession {
     }
     /** A waiting run only continues once every unanswered question has a valid answer. */
     static assertAnswered(runDir, runId) {
-        const reply = readAskReply(runDir);
-        if (!reply)
+        const read = readAskReply(runDir);
+        if (!read)
             return;
+        const reply = resolveOptionLetters(read);
+        if (JSON.stringify(reply) !== JSON.stringify(read))
+            writeAskReply(runDir, reply);
         const check = checkAnswers(reply);
         if (!isComplete(check)) {
             throw new Error(`Run ${runId} is still waiting for answers in ${askReplyPath(runDir)}:\n${describeCheck(check).map((l) => `  ${l}`).join("\n")}`);
@@ -164,6 +195,7 @@ export class RunSession {
     pendingAgents() {
         const { project } = this;
         const rows = Object.values(project.agents)
+            .filter((a) => !this.refused.has(a.name))
             .map((a) => ({ a, files: unreadFiles(project, a.name) }))
             .flatMap((r) => (r.files[0] ? [{ a: r.a, first: path.basename(r.files[0]) }] : []));
         rows.sort((x, y) => x.first.localeCompare(y.first));
@@ -201,12 +233,13 @@ export class RunSession {
         const claim = claimMessages(runDir, agent.name, unread);
         claims.set(agent.name, claim);
         const workDir = path.join(runDir, "agents", agent.name);
-        const aproject = Object.keys(this.batchSpaces).length ? { ...project, workspaces: this.batchSpaces } : project;
+        const spaces = this.leadSpace ? { ...this.batchSpaces, [project.lead]: this.leadSpace } : this.batchSpaces;
+        const aproject = Object.keys(spaces).length ? { ...project, workspaces: spaces } : project;
         const base = {
             project: aproject,
             agent,
             workDir,
-            workspace: this.batchSpaces[agent.name],
+            workspace: spaces[agent.name],
             systemPrompt: buildSystemPrompt(aproject, agent),
             userPrompt: buildUserPrompt(project, agent, queue, unread.length),
             timeoutSec: cfg.wake_timeout_sec,
@@ -306,9 +339,17 @@ export class RunSession {
      */
     integrateMember(agent, ws, key) {
         const { say, project, log, state } = this;
-        const changes = collectAgentChanges(ws, agent.owns);
-        const r = integrateAgentChanges(project, changes);
-        log("integrate", { agent: agent.name, status: r.status, files: changes.files.map((f) => `${f.status} ${f.path}`), ...(r.status === "blocked" ? { reason: r.reason, report: r.report } : {}) });
+        let changes;
+        let r;
+        try {
+            changes = collectAgentChanges(ws, agent.owns);
+            r = integrateAgentChanges(project, changes, this.leadSpace);
+        }
+        catch (e) {
+            // e.g. a worktree whose git files were tampered with: nothing is applied, and the lead is told like for any blocked integration
+            r = refusedIntegration(project, ws, e.message);
+        }
+        log("integrate", { agent: agent.name, status: r.status, files: (changes?.files ?? []).map((f) => `${f.status} ${f.path}`), ...(r.status === "blocked" ? { reason: r.reason, report: r.report } : {}) });
         const blocked = (state.blocked_integrations ?? []).filter((b) => b.agent !== agent.name);
         if (r.status === "integrated") {
             state.blocked_integrations = blocked;
@@ -330,6 +371,20 @@ export class RunSession {
         });
         this.saveState();
     }
+    /** A member whose worktree was refused: it is not woken again in this run, and the lead is told so it can react. */
+    refuseMember(agent, reason) {
+        const { project, runId } = this;
+        this.refused.add(agent.name);
+        this.note(`${agent.name} was not woken: ${reason.split("\n")[0]}`);
+        deliverOnce(project, this.journal(), `refused:${runId}:${agent.name}`, {
+            from: "dispatcher",
+            to: project.lead,
+            type: "failure",
+            subject: `${agent.name} cannot be woken: its worktree was refused`,
+            body: `${agent.name} has unread mail, but its worktree cannot be used, so it is not woken again in this run and its unread mail stays unread.\n\n${reason}\n\nDo its work yourself or give it to another agent; do not wait for ${agent.name}.`,
+        });
+        this.saveState();
+    }
     /** After a batch (or, on resume, before the first one): revert guarded edits, route mail, detect done / lead failure. */
     settle(batch, results) {
         const { say, runDir, project, log, state, guard, claims, attempts } = this;
@@ -412,6 +467,7 @@ export class RunSession {
         }
         if (route.done) {
             this.doneMessage = { subject: route.done.subject, body: route.done.body };
+            this.openPrRequested = route.done.meta.open_pr === true;
             const resolved = resolveDoneOutcome(must(contract, "completion contract of the done report"), state.done_rejections ?? 0, state.blocked_integrations ?? []);
             this.doneOutcome = resolved.outcome;
             this.doneNote = resolved.note;
@@ -508,6 +564,65 @@ export class RunSession {
         say(`  waiting for your answers: ${askReplyPath(runDir)}`);
         return true;
     }
+    /**
+     * Concurrent runs, at the end of the run: the lead's work is committed on its branch for you to merge.
+     * A run that waits for your answers has not ended (it will be resumed in the same worktree), so it commits nothing.
+     */
+    finishLead(endReason) {
+        const { say, log, state, runDir, runId, project } = this;
+        if (!this.leadSpace || endReason === "waiting")
+            return undefined;
+        try {
+            const rb = finishLeadBranch(this.leadSpace, `agent-lyceum: ${project.lead}'s work for run ${runId}\n\n${state.task_summary}`, path.join(runDir, "lead.patch"));
+            state.result_branch = rb;
+            log("lead-branch", { ...rb });
+            say(rb.files ? `  work is on branch ${rb.branch} (${rb.files} file(s)); bring it into your repo with: git merge ${rb.branch}` : `  ${rb.branch}: no file changes`);
+            return rb;
+        }
+        catch (e) {
+            this.note(`Could not commit the work on ${this.leadSpace.branch}: ${e.message.split("\n")[0]}. It is still in ${this.leadSpace.root}.`);
+            return undefined;
+        }
+    }
+    /**
+     * The lead asked for a pull request in `done`. It is opened from the lead's branch, by the dispatcher, outside any agent sandbox.
+     * A request that cannot be honoured is reported and noted; it never changes how the run turned out.
+     */
+    maybeOpenPr(endReason, outcome, rb) {
+        if (!this.openPrRequested)
+            return undefined;
+        const { say, log, state, runDir, project } = this;
+        const skip = (reason) => {
+            this.note(`A pull request was asked for but not opened: ${reason}`);
+            return { status: "skipped", reason };
+        };
+        if (endReason !== "done" || outcome !== "completed")
+            return skip(`the run did not end completed (${endReason}, outcome ${outcome}).`);
+        if (!this.leadSpace)
+            return skip("this run has no worktree of its own, so there is no branch to push. Set dispatcher.max_concurrent_runs: 2 (or more) in project.yaml.");
+        if (!rb)
+            return skip(`the work could not be committed on ${this.leadSpace.branch}.`);
+        if (!rb.files)
+            return skip(`${rb.branch} has no file changes.`);
+        const result = openPullRequest({
+            // Never the lead's worktree: the agent can write it (and its git pointers), and git would run what it planted there.
+            cwd: toplevel(project.dir),
+            branch: rb.branch,
+            title: prTitle(state.task_summary),
+            body: prBody(this.doneMessage?.body ?? ""),
+            bodyFile: path.join(runDir, "pr-body.md"),
+            run: this.prRunner,
+        });
+        log("pull-request", { ...result });
+        if (result.status === "opened") {
+            state.pr_url = result.url;
+            say(`  pull request opened: ${result.url}`);
+        }
+        else {
+            this.note(`The pull request could not be opened (${result.step}: ${result.reason}). The branch ${rb.branch} is kept.${result.manual.length ? ` To finish by hand:\n${result.manual.map((m) => `  ${m}`).join("\n")}` : ""}`);
+        }
+        return result;
+    }
     /** On resume: sort out what the interrupted process left behind before anything is woken. */
     recover() {
         const { say, runId, runDir, project, wsMode, log } = this;
@@ -577,16 +692,34 @@ export class RunSession {
             if (wsMode === "worktree" && members.length) {
                 state.snapshots = (state.snapshots ?? 0) + 1;
                 this.saveState();
-                const ref = snapshotBase(project, runId, state.snapshots);
-                for (const a of members)
-                    this.batchSpaces[a.name] = prepareAgentWorkspace(project, runId, a.name, ref);
+                let ref;
+                try {
+                    ref = snapshotBase(project, runId, state.snapshots, this.leadSpace);
+                }
+                catch (e) {
+                    // The lead's worktree was refused (or could not be read): the run cannot go on, and the work stays where it is.
+                    this.note(`Could not snapshot ${this.leadSpace ? `${project.lead}'s worktree ${this.leadSpace.root}` : "the repo"} for the next batch: ${e.message.split("\n")[0]}`);
+                    this.endReason = "lead_failed";
+                    break;
+                }
+                for (const a of members) {
+                    try {
+                        this.batchSpaces[a.name] = prepareAgentWorkspace(project, runId, a.name, ref);
+                    }
+                    catch (e) {
+                        this.refuseMember(a, e.message);
+                    }
+                }
                 log("workspaces", { snapshot: ref, agents: Object.fromEntries(Object.entries(this.batchSpaces).map(([n, w]) => [n, w.dir])) });
             }
-            const results = await Promise.all(batch.map((a) => this.wake(a)));
-            leadWasLast = batch.some((a) => a.name === project.lead);
-            if (batch.some((a) => a.name !== project.lead))
+            this.guard.rebase();
+            // a member whose worktree was refused is not woken (it would have no worktree of its own)
+            const awake = wsMode === "worktree" ? batch.filter((a) => a.name === project.lead || this.batchSpaces[a.name]) : batch;
+            const results = await Promise.all(awake.map((a) => this.wake(a)));
+            leadWasLast = awake.some((a) => a.name === project.lead);
+            if (awake.some((a) => a.name !== project.lead))
                 nudged = false;
-            this.settle(batch, results);
+            this.settle(awake, results);
             if (!this.endReason && opts.signal?.aborted)
                 this.endReason = "cancelled";
         }
@@ -597,10 +730,20 @@ export class RunSession {
         state.outcome_note = outcomeNote;
         state.verification = this.doneVerification;
         state.ended_at = new Date().toISOString();
+        const resultBranch = this.finishLead(endReason);
+        let pr;
+        if (this.openPrRequested) {
+            // The network step can take minutes: the run is stored as ended first, so an interruption there loses nothing and a resume does not push again.
+            this.saveState();
+            if (this.pendingDoneFile)
+                finishDone(this.pendingDoneFile);
+            this.pendingDoneFile = undefined;
+            pr = this.maybeOpenPr(endReason, outcome, resultBranch);
+        }
         log("end", { reason: endReason, outcome, rounds: state.rounds });
         this.saveState();
         if (this.pendingDoneFile)
             finishDone(this.pendingDoneFile);
-        return { runId, runDir, rounds: state.rounds, endReason, outcome, outcomeNote, verification: this.doneVerification, doneMessage: this.doneMessage, askReplyPath: endReason === "waiting" ? askReplyPath(runDir) : undefined };
+        return { runId, runDir, rounds: state.rounds, endReason, outcome, outcomeNote, verification: this.doneVerification, doneMessage: this.doneMessage, askReplyPath: endReason === "waiting" ? askReplyPath(runDir) : undefined, resultBranch, pr };
     }
 }

package/dist/run-store.d.ts

@@ -1,6 +1,7 @@
 import type { ResolvedProject } from "./config.js";
 import type { DigestSection, Step } from "./format.js";
 import type { RunOutcome } from "./schema.js";
+import type { ResultBranch } from "./worktree.js";
 export declare const STATE_FILE = "state.json";
 export declare const STATE_SCHEMA_VERSION = 2;
 export type EndReason = "done" | "idle" | "max_rounds" | "lead_failed" | "cancelled" | "waiting";
@@ -75,6 +76,12 @@ export interface RunState {
     }[];
     /** Snapshots of the repo taken so far (`refs/agent-lyceum/<run>/base-<n>`). */
     snapshots?: number;
+    /** Concurrent runs: where the lead's work ended up (`git merge <branch>`). Set when the run ends. */
+    result_branch?: ResultBranch;
+    /** Set when the run started with the lead in its own worktree (max_concurrent_runs > 1 then); its resumes keep that, whatever the config says later. */
+    lead_workspace?: true;
+    /** The pull request the dispatcher opened for this run (when the lead asked for one and it worked). */
+    pr_url?: string;
     sessions: Record<string, string>;
     output_tokens: number;
     last_wake: Record<string, {

package/dist/scaffold.js

@@ -87,6 +87,7 @@ team:
 dispatcher:
   max_rounds: 30        # stop after this many agent wake-ups
   max_parallel: 1       # >1 needs non-overlapping "owns" for every non-lead agent, and a git repo
+  max_concurrent_runs: 1  # >1 lets several runs of this project be active at once, each in its own git worktree (needs a git repo); every run's work stays on its own branch
   workspace_mode: auto  # auto = a git worktree per non-lead agent when max_parallel > 1; shared | worktree to force
   wake_timeout_sec: 600
   retry: 1

package/dist/schema.d.ts

@@ -45,6 +45,7 @@ export type AgentPartialT = z.infer<typeof AgentPartial>;
 export declare const DispatcherPartial: z.ZodObject<{
     max_rounds: z.ZodOptional<z.ZodNumber>;
     max_parallel: z.ZodOptional<z.ZodNumber>;
+    max_concurrent_runs: z.ZodOptional<z.ZodNumber>;
     wake_timeout_sec: z.ZodOptional<z.ZodNumber>;
     retry: z.ZodOptional<z.ZodNumber>;
     strict: z.ZodOptional<z.ZodBoolean>;
@@ -95,6 +96,7 @@ export declare const ProjectConfig: z.ZodObject<{
     dispatcher: z.ZodDefault<z.ZodObject<{
         max_rounds: z.ZodOptional<z.ZodNumber>;
         max_parallel: z.ZodOptional<z.ZodNumber>;
+        max_concurrent_runs: z.ZodOptional<z.ZodNumber>;
         wake_timeout_sec: z.ZodOptional<z.ZodNumber>;
         retry: z.ZodOptional<z.ZodNumber>;
         strict: z.ZodOptional<z.ZodBoolean>;
@@ -139,6 +141,8 @@ export declare const ProjectConfig: z.ZodObject<{
 export interface DispatcherSettings {
     max_rounds: number;
     max_parallel: number;
+    /** How many runs of one project may be active at once. Above 1, every run works in its own git worktree. */
+    max_concurrent_runs: number;
     wake_timeout_sec: number;
     retry: number;
     strict: boolean;

package/dist/schema.js

@@ -45,6 +45,7 @@ export const DispatcherPartial = z
     .object({
     max_rounds: z.number().int().positive().optional(),
     max_parallel: z.number().int().positive().optional(),
+    max_concurrent_runs: z.number().int().positive().optional(),
     wake_timeout_sec: z.number().int().positive().optional(),
     retry: z.number().int().min(0).optional(),
     strict: z.boolean().optional(),
@@ -68,6 +69,7 @@ export const ProjectConfig = z
 export const DISPATCHER_DEFAULTS = {
     max_rounds: 30,
     max_parallel: 1,
+    max_concurrent_runs: 1,
     wake_timeout_sec: 600,
     retry: 1,
     strict: false,

package/dist/status.d.ts

@@ -16,7 +16,7 @@ export declare function listRuns(project: ResolvedProject, limit: number): {
     state: RunState;
 }[];
 /**
- * Is this run's dispatcher running now? Runs with a project lock (schema 2) are judged by the lock holder;
+ * Is this run's dispatcher running now? Runs with a lock (schema 2) are judged by the lock holder of that run;
  * the recorded pid is only the fallback for older runs and runs started without a lock.
  */
 export declare function runIsAlive(s: RunState, project?: ResolvedProject): boolean;

package/dist/status.js

@@ -6,7 +6,7 @@ import { bindRunProject, loadRunState, outcomeOf } from "./run-store.js";
 import { briefOf, digestOf } from "./format.js";
 import { listUnread } from "./mailbox.js";
 import { tidyAdvice } from "./memory-tidy.js";
-import { inspectProjectLock, lockHolderAlive } from "./project-lock.js";
+import { inspectRunLock, lockHolderAlive } from "./project-lock.js";
 export function latestRun(project) {
     const root = project.paths.runs;
     if (!fs.existsSync(root))
@@ -57,14 +57,14 @@ export function listRuns(project, limit) {
     return out;
 }
 /**
- * Is this run's dispatcher running now? Runs with a project lock (schema 2) are judged by the lock holder;
+ * Is this run's dispatcher running now? Runs with a lock (schema 2) are judged by the lock holder of that run;
  * the recorded pid is only the fallback for older runs and runs started without a lock.
  */
 export function runIsAlive(s, project) {
     if (project && s.schema_version >= 2) {
-        const l = inspectProjectLock(project.paths.root);
+        const l = inspectRunLock(project.paths.root, s.run_id);
         if (l)
-            return l.run_id === s.run_id && lockHolderAlive(l);
+            return lockHolderAlive(l);
     }
     return alive(s.pid);
 }

package/dist/validate.js

@@ -76,11 +76,18 @@ export function validateProject(project) {
             }
         }
     }
-    // Parallel agents each need their own checkout, which needs git.
-    if (project.dispatcher.workspace_mode === "shared" && project.dispatcher.max_parallel > 1) {
+    // Parallel agents and concurrent runs each need their own checkout, which needs git.
+    const concurrent = project.dispatcher.max_concurrent_runs > 1;
+    if (concurrent && project.dispatcher.workspace_mode === "shared") {
+        err(`dispatcher.workspace_mode "shared" cannot be combined with max_concurrent_runs > 1: every run needs its own git worktree (use "auto" or "worktree").`);
+    }
+    else if (concurrent && fs.existsSync(project.dir) && !isGitRepo(project.dir)) {
+        err(`max_concurrent_runs > 1 needs ${project.dir} to be a git repository (each run works in its own git worktree). Set max_concurrent_runs: 1.`);
+    }
+    else if (project.dispatcher.workspace_mode === "shared" && project.dispatcher.max_parallel > 1) {
         err(`dispatcher.workspace_mode "shared" cannot be combined with max_parallel > 1: parallel agents need separate git worktrees (use "auto" or "worktree").`);
     }
-    else if (resolveWorkspaceMode(project.dispatcher) === "worktree" && fs.existsSync(project.dir) && !isGitRepo(project.dir)) {
+    else if (!concurrent && resolveWorkspaceMode(project.dispatcher) === "worktree" && fs.existsSync(project.dir) && !isGitRepo(project.dir)) {
         err(`Parallel runs (worktree workspaces) need ${project.dir} to be a git repository. Run sequentially instead (max_parallel: 1, workspace_mode: auto or shared).`);
     }
     // Context paths should live outside the repo (the tool never writes into it).

package/dist/worktree.d.ts

@@ -1,34 +1,77 @@
 import type { ResolvedProject } from "./config.js";
 import type { DispatcherSettings } from "./schema.js";
 export type WorkspaceMode = "shared" | "worktree";
-/** Agents share the repo, or each non-lead agent gets its own git worktree. `auto` picks worktrees as soon as agents can run in parallel. */
-export declare function resolveWorkspaceMode(d: Pick<DispatcherSettings, "workspace_mode" | "max_parallel">): WorkspaceMode;
+/** Agents share the repo, or each non-lead agent gets its own git worktree. `auto` picks worktrees as soon as agents can run in parallel; several concurrent runs always do. */
+export declare function resolveWorkspaceMode(d: Pick<DispatcherSettings, "workspace_mode" | "max_parallel"> & Partial<Pick<DispatcherSettings, "max_concurrent_runs">>): WorkspaceMode;
 export interface AgentWorkspace {
     agent: string;
     /** Root of the git worktree. */
     root: string;
     /** Where the agent works: the worktree's counterpart of the project dir (differs from `root` when the project is a subfolder of the repo). */
     dir: string;
-    /** The worktree's private git dir inside the main repo's `.git/worktrees/`. */
+    /** The worktree's private git dir inside the main repo's `.git/worktrees/`. Recorded when the worktree was made, never asked of the worktree. */
     gitDir: string;
+    /** The main repo's git dir (absolute, real path): where config, hooks, objects and refs live. Recorded with `gitDir`. */
+    commonDir: string;
+    /** Fingerprint of `<gitDir>/config.worktree` when the worktree was made; absent when there was none. */
+    worktreeConfig?: string;
     branch: string;
     /** Commit of the snapshot this workspace's changes are measured against. */
     base: string;
 }
 export declare function git(cwd: string, args: string[], env?: NodeJS.ProcessEnv): string;
+type PinnedWorkspace = Pick<AgentWorkspace, "root" | "gitDir" | "commonDir" | "worktreeConfig" | "branch">;
+/**
+ * Refuse a worktree whose git files were rewritten in a way pinning cannot neutralise:
+ * - `commondir`: git's ref store follows it even with GIT_COMMON_DIR set, so refs would be read from and written to the agent's dir;
+ * - `config.worktree` (read when the user enabled extensions.worktreeConfig): it can name filters, chosen by the worktree's own
+ *   .gitattributes, and a signing program — more than any `-c` list can switch off;
+ * - files git writes by following links (COMMIT_EDITMSG, logs/HEAD): a symlink or hard link would make git write outside the sandbox;
+ * - `HEAD` not the worktree's own branch: the ref store is shared, so a HEAD naming another branch (say `main`) or a detached
+ *   commit would make the dispatcher commit onto, or measure against, a ref the agent chose. git writes exactly
+ *   `ref: refs/heads/<branch>\n` and keeps it so through the dispatcher's commits and `reset --hard`;
+ * - the worktree or its git dir replaced by a symlink.
+ */
+export declare function assertWorkspaceIntact(ws: PinnedWorkspace): void;
+/**
+ * Run git against an agent's worktree without letting git discover anything from it. The agent may rewrite the worktree's `.git`
+ * pointer file and its per-worktree git dir; git is told exactly where the git dir, the common dir and the work tree are
+ * (`ws.gitDir` / `ws.commonDir` come from the workspace meta, recorded before any agent ran in it), and the worktree is checked
+ * for what pinning cannot neutralise first (`assertWorkspaceIntact`).
+ * The cwd is the worktree root: git does not discover from it (GIT_DIR is set), and commands that take paths relative to the cwd
+ * (`git apply`) would otherwise write wherever the cwd is.
+ */
+export declare function agentGit(ws: PinnedWorkspace, args: string[], env?: NodeJS.ProcessEnv, input?: string | Buffer): string;
+/** `agentGit`, with a failing git command giving `undefined`. A worktree that fails `assertWorkspaceIntact` still throws. */
+export declare function tryAgentGit(ws: PinnedWorkspace, args: string[], env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Refuse a worktree that holds a git repository of its own. `status`, `add -A` and `commit` can visit a nested repository and run
+ * git there with that repository's config — which the agent wrote. Run before any command that walks the working tree.
+ * - untracked: `ls-files -o` (it does not enter them, and runs nothing) lists a nested repository as one entry ending in `/`;
+ * - a submodule entry in the (agent-writable) index that the snapshot did not have;
+ * - a submodule path from the snapshot that now holds a repository (`git worktree add` never fills it, and an agent cannot).
+ * A repo that uses submodules keeps working: its submodule entries come from the snapshot and stay empty in a worktree.
+ */
+export declare function assertNoNestedRepos(ws: AgentWorkspace): void;
 export declare function isGitRepo(dir: string): boolean;
+/** The main repository's top-level directory for `dir`. */
+export declare const toplevel: (dir: string) => string;
 /** Files in the repo with changes nobody committed (modified, staged or new and not ignored). Paths are relative to the repo root. */
 export declare function dirtyPaths(dir: string): string[];
 /** Refuse to start a worktree run when it cannot be isolated; returns nothing when it is fine. */
 export declare function assertWorktreeRunnable(project: ResolvedProject, opts: {
     fresh: boolean;
+    concurrent?: boolean;
 }): void;
+/** `refs/agent-lyceum/<run>/base-0` pointing at the repo's HEAD: where a concurrent run starts. Nothing in the repo changes. */
+export declare function snapshotHead(project: ResolvedProject, runId: string): string;
 /**
  * Commit the repo's current working tree (tracked changes and new, non-ignored files) as an unreferenced-by-branch
  * snapshot `refs/agent-lyceum/<run>/base-<n>`. Uses a throwaway index, so HEAD, branches, the real index and the
  * working tree are not touched. Returns the ref.
+ * `from`: the checkout to snapshot — the lead's worktree in a concurrent run; by default your repo's working tree.
  */
-export declare function snapshotBase(project: ResolvedProject, runId: string, n: number): string;
+export declare function snapshotBase(project: ResolvedProject, runId: string, n: number, from?: AgentWorkspace): string;
 /**
  * The agent's own checkout of the snapshot `baseRef`, at `<project home>/worktrees/<run>/<agent>`.
  * An existing checkout is reused: untouched, when it already is on this snapshot (resume) or holds unfinished
@@ -56,6 +99,11 @@ export interface ChangeSet {
 }
 /** Glob as used in `owns`: `**` crosses folders, `*` and `?` stay within one, `{a,b}` alternates. */
 export declare function globMatch(glob: string, file: string): boolean;
+/** Commit whatever is in an agent's worktree (no hooks, no signing, dispatcher identity). Returns the HEAD afterwards and whether a commit was made. */
+export declare function commitWorkspace(ws: AgentWorkspace, message: string): {
+    head: string;
+    committed: boolean;
+};
 /**
  * Commit whatever the agent left in its worktree and list what changed since its snapshot, checking every
  * changed path (modified, added, deleted, or either end of a rename) against the agent's `owns`, the project
@@ -74,14 +122,20 @@ export type IntegrationResult = {
     report: string;
     patch: string;
 };
+/** A member's changes that could not even be collected (e.g. its worktree was refused): reported like any blocked integration, with nothing applied. */
+export declare function refusedIntegration(project: ResolvedProject, workspace: AgentWorkspace, reason: string): IntegrationResult;
 /**
  * Bring an agent's collected changes into the main working tree (not the index, not HEAD), all or nothing.
  * Blocked, with nothing applied and the agent's work kept, when the changes break the rules, when a file
  * changed in the repo since the agent's snapshot, or when git cannot apply the patch. Repeating a call whose
  * changes are already in place is harmless.
+ * `target`: the checkout to bring the changes into — the lead's worktree in a concurrent run; by default your repo's working tree.
+ */
+export declare function integrateAgentChanges(project: ResolvedProject, changes: ChangeSet, target?: AgentWorkspace): IntegrationResult;
+/**
+ * An agent's existing worktree for this run, if it has one (no worktree or no metadata: undefined).
+ * Throws when the metadata predates recording the git dir and the git dir cannot be told for certain.
  */
-export declare function integrateAgentChanges(project: ResolvedProject, changes: ChangeSet): IntegrationResult;
-/** An agent's existing worktree for this run, if it has one. */
 export declare function existingAgentWorkspace(project: ResolvedProject, runId: string, agent: string): AgentWorkspace | undefined;
 export interface WorkspaceWork {
     agent: string;
@@ -95,9 +149,22 @@ export interface WorkspaceWork {
     unknown?: string;
 }
 /** What is in an agent's worktree that exists nowhere else: uncommitted changes, and commits whose files are not in the main repo. */
-export declare function inspectWorkspace(project: ResolvedProject, runId: string, agent: string): WorkspaceWork | undefined;
+export declare function inspectWorkspace(project: ResolvedProject, runId: string, agent: string, target?: AgentWorkspace): WorkspaceWork | undefined;
+export interface ResultBranch {
+    branch: string;
+    head: string;
+    /** The snapshot the run started from. */
+    base: string;
+    /** Files the branch changes relative to `base`. */
+    files: number;
+    /** The same changes as a patch file (absent when nothing changed). */
+    patch?: string;
+}
+/** Commit the lead's checkout on its branch (once, at the end of a run) and write what changed as a patch. Never touches your repo's working tree. */
+export declare function finishLeadBranch(ws: AgentWorkspace, message: string, patchFile: string): ResultBranch;
 /** Names of the agents that have a worktree for this run. */
 export declare function listWorkspaceAgents(project: ResolvedProject, runId: string): string[];
 /** The snapshot refs (`refs/agent-lyceum/<run>/...`) of a run. */
 export declare function listSnapshotRefs(project: ResolvedProject, runId: string): string[];
 export declare function deleteSnapshotRefs(project: ResolvedProject, runId: string): void;
+export {};