agent-lyceum 0.13.1 → 0.15.0

package/dist/open-pr.js

@@ -48,6 +48,16 @@ const firstLine = (s) => s.split(/\r?\n/).find((l) => l.trim())?.trim() ?? "no o
 const sh = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
 /** Push the branch and open a pull request against the default branch. Never throws; says how to finish by hand when a step fails. */
 export function openPullRequest(i) {
+    if (i.existingUrl) {
+        // A squash merge leaves the branch looking unmerged, so ask GitHub. When the lookup itself fails, assume the PR is still open.
+        const view = i.run("gh", ["pr", "view", i.existingUrl, "--json", "state", "-q", ".state"], i.cwd);
+        if (!view.ok || view.out.trim() === "OPEN") {
+            const push = i.run("git", ["push", "-u", "origin", i.branch], i.cwd);
+            if (push.ok)
+                return { status: "opened", url: i.existingUrl, updated: true };
+            return { status: "failed", step: "push", reason: firstLine(push.out), manual: [`git -C ${sh(i.cwd)} push -u origin ${sh(i.branch)}`] };
+        }
+    }
     const base = defaultBase(i.cwd, i.run);
     try {
         atomicWrite(i.bodyFile, i.body);

package/dist/policy.d.ts

@@ -6,6 +6,7 @@ export interface AgentEnforcement {
     memory: Level;
     agentMd: Level;
     otherContext: Level;
+    shared: Level;
     repoInstructions: Level;
     owns: Level;
     /** Absolute paths outside the repo this agent may write. */
@@ -15,6 +16,8 @@ export interface AgentEnforcement {
 export interface WritePolicy {
     /** Directories the agent may write to (besides the repo). */
     allowDirs: string[];
+    /** Directories the agent may read besides the repo and its writable ones, but must not write (the run's handoff notes, for everyone but the lead). */
+    readDirs: string[];
     /** Individual files the agent may write (outside allowDirs). */
     allowFiles: string[];
     /** Files/dirs that must stay unwritable (checked even inside the repo). */
@@ -29,6 +32,12 @@ export declare function inboxDir(project: ResolvedProject, agent: string): strin
 /** The repo's own CLAUDE.md/AGENTS.md: in the lead's worktree when it has one (concurrent runs), else in the repo. */
 export declare function repoInstructionFiles(project: ResolvedProject): string[];
 export declare function memoryDirs(a: ResolvedAgent): string[];
+/** Folder name of a run's handoff notes inside `task-memory/<run-id>/`. Agent names start with a letter or digit, so it cannot be an agent's own folder. */
+export declare const SHARED_DIR = "_shared";
+/** The run's handoff folder: read by every agent, written only by the lead. Undefined outside a run and for `call`. */
+export declare function sharedDir(project: ResolvedProject): string | undefined;
+/** The index of the handoff notes: the one file shown in prompts, and the one the guard watches. */
+export declare function sharedIndex(project: ResolvedProject): string | undefined;
 /** The repo directory this agent works in: its own worktree, or the main repo. */
 export declare function repoDirFor(project: ResolvedProject, agent: string): string;
 export declare function writePolicy(project: ResolvedProject, agent: ResolvedAgent): WritePolicy;

package/dist/policy.js

@@ -19,6 +19,19 @@ export function repoInstructionFiles(project) {
 export function memoryDirs(a) {
     return [a.memory.global, a.memory.project, a.memory.task].filter((x) => !!x);
 }
+/** Folder name of a run's handoff notes inside `task-memory/<run-id>/`. Agent names start with a letter or digit, so it cannot be an agent's own folder. */
+export const SHARED_DIR = "_shared";
+/** The run's handoff folder: read by every agent, written only by the lead. Undefined outside a run and for `call`. */
+export function sharedDir(project) {
+    if (!project.run || project.solo === "call")
+        return undefined;
+    return path.join(project.paths.taskMemory, project.run.id, SHARED_DIR);
+}
+/** The index of the handoff notes: the one file shown in prompts, and the one the guard watches. */
+export function sharedIndex(project) {
+    const dir = sharedDir(project);
+    return dir ? path.join(dir, "MEMORY.md") : undefined;
+}
 const RUN_ENTRIES = ["state.json", "log.jsonl", "log.1.jsonl", "result.md", "task.md", "snapshots", "violations", "agents", "mail"];
 const MAIL_ENTRIES = ["inbox", "claims", "attempts", "journal.jsonl"];
 function entries(dir) {
@@ -54,10 +67,20 @@ export function writePolicy(project, agent) {
     const isLead = agent.name === project.lead && !project.solo;
     const ws = project.workspaces?.[agent.name];
     // A `call` has no mailboxes at all; a solo member of a run keeps its outbox to send `done`.
-    const allowDirs = [...memoryDirs(agent), ...(project.solo === "call" ? [] : [outboxDir(project, agent.name)]), ...(ws ? [ws.gitDir] : [])];
+    const shared = sharedDir(project);
+    const sharedIdx = sharedIndex(project);
+    const mayWriteShared = !!shared && agent.name === project.lead;
+    const allowDirs = [
+        ...memoryDirs(agent),
+        ...(project.solo === "call" ? [] : [outboxDir(project, agent.name)]),
+        ...(ws ? [ws.gitDir] : []),
+        ...(shared && mayWriteShared ? [shared] : []),
+    ];
     const allowFiles = [];
     if (isLead)
         allowFiles.push(commonFile(project));
+    if (mayWriteShared && sharedIdx)
+        allowFiles.push(sharedIdx);
     if (agent.canEditAgentMd) {
         for (const a of Object.values(project.agents))
             allowFiles.push(a.agentMd);
@@ -81,6 +104,8 @@ export function writePolicy(project, agent) {
     addDeny(commonFile(project));
     for (const f of repoInstructionFiles(project))
         addDeny(f);
+    if (shared && !mayWriteShared)
+        deny.push(shared);
     deny.push(...runDenyPaths(project), project.paths.config, path.join(project.home, "team.yaml"));
     // In a worktree: other agents' checkouts are off limits, and so are this checkout's own copies of the protected files.
     for (const [name, other] of Object.entries(project.workspaces ?? {}))
@@ -95,6 +120,7 @@ export function writePolicy(project, agent) {
         deny.push(path.join(ws.root, ".git"), ...["commondir", "config.worktree", "gitdir"].map((f) => path.join(ws.gitDir, f)));
     return {
         allowDirs,
+        readDirs: shared && !mayWriteShared ? [shared] : [],
         allowFiles,
         deny: [...new Set(deny)],
         owns: agent.owns,
@@ -118,17 +144,22 @@ export function enforcementFor(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, repoInstructions: lvl, owns: parallel ? "tool-rules" : "n/a" };
+        e = { memory: lvl, agentMd: lvl, otherContext: lvl, shared: isLeadAgent ? "n/a" : lvl, repoInstructions: lvl, owns: parallel ? "tool-rules" : "n/a" };
         if (!os)
             notes.push("OS sandbox unavailable (Windows, or Linux without bubblewrap): Bash can bypass Edit rules.");
+        if (!isLeadAgent && !os)
+            notes.push("Without the OS sandbox Bash can write _shared; only the handoff index (_shared/MEMORY.md) is checked after each wake-up.");
     }
     else {
         const lvl = os ? "os" : "prompt-only";
-        e = { memory: lvl, agentMd: lvl, otherContext: lvl, 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", owns: parallel ? "prompt-only" : "n/a" };
         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.");
         if (agent.canEditAgentMd)
             notes.push("can_edit_agent_md widens Codex writable roots to whole agent directories.");
     }

package/dist/prompt.d.ts

@@ -3,6 +3,7 @@ import type { Message } from "./mailbox.js";
 import type { Layer, MemoryFile, MissingPath, ProjectChanges } from "./memory-tidy.js";
 export declare const COMMON_LIMIT: number;
 export declare const MEMORY_INDEX_LIMIT: number;
+export declare const HANDOFF_LIMIT: number;
 export declare const LEAD_BATCH_LIMIT = 5;
 export declare function readPersona(agent: ResolvedAgent): string;
 /** The protocol of an agent working alone: no teammates, no ask. `run --agent` still ends with a `done` mail; `call` just answers. */
@@ -13,7 +14,7 @@ export declare function buildCallUserPrompt(agent: ResolvedAgent, task: string):
 export declare function buildSystemPrompt(project: ResolvedProject, agent: ResolvedAgent): string;
 /** 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. */
 export declare function pickMessages(project: ResolvedProject, agent: ResolvedAgent, queue: Message[]): Message[];
-export declare function buildUserPrompt(project: ResolvedProject, agent: ResolvedAgent, unread: Message[], handleCount?: number): string;
+export declare function buildUserPrompt(project: ResolvedProject, agent: ResolvedAgent, unread: Message[], handleCount?: number, handoff?: boolean): string;
 export interface TidyContext {
     layer: Layer;
     /** The memory directory being tidied. */

package/dist/prompt.js

@@ -1,7 +1,8 @@
 import fs from "node:fs";
+import { readFileCapped } from "./fs-util.js";
 import path from "node:path";
 import { REQUIRED_SECTIONS } from "./format.js";
-import { commonFile, memoryDirs, outboxDir, repoDirFor } from "./policy.js";
+import { commonFile, memoryDirs, outboxDir, repoDirFor, sharedDir, sharedIndex } from "./policy.js";
 function memoryLabel(agent, dir) {
     if (dir === agent.memory.task)
         return "task (this task only, isolated)";
@@ -9,16 +10,10 @@ function memoryLabel(agent, dir) {
 }
 export const COMMON_LIMIT = 8 * 1024;
 export const MEMORY_INDEX_LIMIT = 4 * 1024;
+export const HANDOFF_LIMIT = COMMON_LIMIT;
 export const LEAD_BATCH_LIMIT = 5;
 const BATCHABLE = new Set(["reply", "failure"]);
-function readCapped(file, limit) {
-    if (!fs.existsSync(file))
-        return undefined;
-    const buf = fs.readFileSync(file);
-    if (buf.length <= limit)
-        return { text: buf.toString("utf8"), truncated: false };
-    return { text: buf.subarray(0, limit).toString("utf8"), truncated: true };
-}
+const readCapped = readFileCapped;
 /** A PR only needs to say agent-lyceum opened it; no agent or role names. */
 const PR_ATTRIBUTION_RULE = "- If you open a pull request, end its description with a line saying it was opened by agent-lyceum (e.g. `🤖 Opened by agent-lyceum`). Do not name any agent or role in it.";
 /** A tool call that never returns (a server or daemon started in the foreground) burns the whole wake-up timeout and the finished work is thrown away with it. */
@@ -28,6 +23,14 @@ const OPEN_PR_RULE = "Add the frontmatter line `open_pr: true` to `done` only wh
 export function readPersona(agent) {
     return fs.readFileSync(agent.agentMd, "utf8").trim();
 }
+/** What the lead (or a solo agent) is told about the handoff notes: they are what a reopened task starts from. */
+function handoffRule(dir) {
+    return [
+        "",
+        "## Handoff for follow-ups",
+        `This task may be reopened later with a follow-up request, and the agents woken then start with fresh sessions. Before you send \`done\`, write what they need to carry on into \`${dir}\`: keep a \`MEMORY.md\` index there (one line per entry, pointing at a file) and record the decisions made and why, the interfaces agreed, the current state, what is left and what to do next, and the pitfalls met. Your teammates can read this folder but cannot write it; if a report from a teammate holds something worth keeping, add it yourself. Only the index is shown in prompts, and only the first ${HANDOFF_LIMIT / 1024} KB of it, so keep it short. These notes are about this task only; lessons that outlive it belong in your project or global memory.`,
+    ];
+}
 /** The protocol of an agent working alone: no teammates, no ask. `run --agent` still ends with a `done` mail; `call` just answers. */
 export function buildSoloSystemPrompt(project, agent) {
     const isCall = project.solo === "call";
@@ -38,6 +41,9 @@ export function buildSoloSystemPrompt(project, agent) {
     if (!isCall) {
         lines.push("## Finishing", `When the job is finished, create a Markdown file (any name ending in \`.md\`) directly inside \`${outboxDir(project, agent.name)}\` with this exact shape:`, "", "```", "---", "type: done", "subject: <short subject>", "outcome: completed|partial|blocked|failed", "---", "", "## Result", "## Files", "## Verification", "## Not done", "```", "", "That ends the run. `## Result` is the actual deliverable or conclusion (not just \"done\"), `## Files` the paths you created or changed, `## Verification` what you ran or checked and what it showed, `## Not done` anything skipped or unverified (or `None`). Only `completed` means success and it needs all four headings; if work remains or is blocked say `partial`/`blocked`/`failed` (those need only `## Result` and `## Not done`). A summary in your reply text is never delivered: without a `done` mail the run ends as idle with no report. " + OPEN_PR_RULE);
     }
+    const shared = sharedDir(project);
+    if (!isCall && shared)
+        lines.push(...handoffRule(shared));
     lines.push("", "## Memory");
     const mems = memoryDirs(agent);
     if (mems.length === 0)
@@ -100,7 +106,7 @@ export function buildSystemPrompt(project, agent) {
             "</ask>",
             "```",
             "",
-            "The answers come back to you as a `reply` mail containing an `<answers>` block. A user answer that starts with `other:` is free text. Do not ask what you could decide yourself, and do not ask again for something already answered.",
+            "The answers come back to you as a `reply` mail containing an `<answers>` block. A user answer may be one of your options or any free text of their own (it may start with `other:`). Do not ask what you could decide yourself, and do not ask again for something already answered.",
         ]
         : []), ...(isLead
         ? [
@@ -111,7 +117,7 @@ export function buildSystemPrompt(project, agent) {
             "Your final `done` mail must also include the full `## Steps` checklist. Tick only steps that were actually done and verified; leave undone ones",
             "(e.g. build, app start, commit) unticked and say so in the mail instead of reporting them as finished.",
         ]
-        : []), "", "## Memory");
+        : []), ...(isLead && sharedDir(project) ? handoffRule(sharedDir(project)) : []), "", "## Memory");
     const mems = memoryDirs(agent);
     if (mems.length === 0)
         lines.push("You have no long-term memory directory.");
@@ -143,7 +149,7 @@ export function pickMessages(project, agent, queue) {
     }
     return run;
 }
-export function buildUserPrompt(project, agent, unread, handleCount = 1) {
+export function buildUserPrompt(project, agent, unread, handleCount = 1, handoff = false) {
     const parts = [];
     const common = readCapped(commonFile(project), COMMON_LIMIT);
     parts.push("# Shared team context (COMMON.md)");
@@ -155,6 +161,14 @@ export function buildUserPrompt(project, agent, unread, handleCount = 1) {
             parts.push(`\n[COMMON.md was truncated at ${COMMON_LIMIT} bytes — the lead should condense it.]`);
         }
     }
+    const handoffFile = handoff ? sharedIndex(project) : undefined;
+    const notes = handoffFile ? readCapped(handoffFile, HANDOFF_LIMIT) : undefined;
+    if (handoffFile && notes?.text.trim()) {
+        parts.push("", `# Handoff notes from earlier segments of this task (${handoffFile})`, notes.text.trim());
+        if (notes.truncated)
+            parts.push(`\n[handoff index truncated at ${HANDOFF_LIMIT} bytes — the lead should condense it.]`);
+        parts.push("The other files in that folder are there to read on demand.");
+    }
     for (const dir of memoryDirs(agent)) {
         const idx = readCapped(path.join(dir, "MEMORY.md"), MEMORY_INDEX_LIMIT);
         const label = memoryLabel(agent, dir).split(" ")[0];

package/dist/run-session.d.ts

@@ -14,6 +14,8 @@ export declare const MAX_DONE_REJECTIONS = 2;
 export declare const MAX_ASK_REJECTIONS = 2;
 export interface RunSummary {
     runId: string;
+    /** The run's name; absent on runs from older versions. */
+    name?: string;
     runDir: string;
     rounds: number;
     endReason: EndReason;
@@ -34,12 +36,18 @@ export interface RunSummary {
 }
 export interface RunOptions {
     project: ResolvedProject;
+    /** Name for a new run: already decided and not used by another run of the project. */
+    name?: string;
     /** Run only this member of the project, alone (`run --agent`). A resumed run uses the one recorded in its state. */
     soloAgent?: string;
     /** The task for a new run; omit when resuming. */
     task?: PreparedTask;
     /** Continue this earlier run (same run dir, sessions and counters) instead of starting a new one. */
     resume?: RunState;
+    /** 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;
+    };
     runDir: string;
     invoker?: Invoker;
     /** Runs git and gh for the pull request. Tests pass a fake; the default is the real thing. */
@@ -51,6 +59,8 @@ export interface RunOptions {
 export declare class RunSession {
     private readonly opts;
     private readonly resume;
+    /** The handoff index as this segment started; the lead is noted when it is the same at `done`. */
+    private readonly sharedAtStart;
     private readonly invoke;
     private readonly say;
     private readonly cfg;

package/dist/run-session.js

@@ -9,11 +9,11 @@ import { abandonClaim, attemptLogDir, sourceIdOf, beginAttempt, claimMessages, c
 import { isInside } from "./paths.js";
 import { createRunLog } from "./run-log.js";
 import { endOutcome, resolveDoneOutcome } from "./run-outcome.js";
-import { outboxDir, ownsDirs } from "./policy.js";
+import { outboxDir, ownsDirs, sharedIndex } from "./policy.js";
 import { buildSystemPrompt, buildUserPrompt, pickMessages } from "./prompt.js";
-import { atomicWrite } from "./fs-util.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 { atomicWrite, readFileCapped } from "./fs-util.js";
+import { assertWorktreeRunnable, collectAgentChanges, dirtyPaths, existingAgentWorkspace, finishLeadBranch, integrateAgentChanges, prepareAgentWorkspace, recutLeadWorkspace, refusedIntegration, resolveWorkspaceMode, snapshotBase, snapshotHead, toplevel } from "./worktree.js";
+import { bindRunProject, newRunId, newRunState, roundLimit, saveRunState } from "./run-store.js";
 import { soloProject } from "./solo.js";
 import { taskMessageBody } from "./task.js";
 import { must } from "./assert.js";
@@ -24,6 +24,14 @@ export const RESULT_FILE = "result.md";
 export const MAX_DONE_REJECTIONS = 2;
 /** How many times a malformed `ask` goes back to its sender before the lead is told instead. */
 export const MAX_ASK_REJECTIONS = 2;
+/** How much of the handoff index is compared; the prompts show far less. */
+const INDEX_COMPARE_LIMIT = 1024 * 1024;
+/** The text of a file, "" when it is missing, undefined when there is no such file for this run (no handoff folder). */
+function readIndex(file) {
+    if (!file)
+        return undefined;
+    return readFileCapped(file, INDEX_COMPARE_LIMIT)?.text ?? "";
+}
 /** Prompt for a repeat attempt: the earlier one failed and may have changed things already. */
 function retryPrompt(prompt, error) {
     return `${prompt}\n\n# Retry notice\nYour previous attempt at this wake-up failed${error ? ` (${error})` : ""} after possibly changing files already. Its mail was discarded. Check the current state of the repository before redoing the work, and send the mail again.`;
@@ -31,6 +39,8 @@ function retryPrompt(prompt, error) {
 export class RunSession {
     opts;
     resume;
+    /** The handoff index as this segment started; the lead is noted when it is the same at `done`. */
+    sharedAtStart;
     invoke;
     say;
     cfg;
@@ -67,6 +77,8 @@ export class RunSession {
         const { task, resume, runDir } = opts;
         if (resume?.end_reason === "waiting")
             RunSession.assertAnswered(runDir, resume.run_id);
+        if (opts.followup && resume?.end_reason !== "done")
+            throw new Error("followup needs a finished (done) run");
         if (!task && !resume)
             throw new Error("runTeam needs a task or a run to resume");
         const invoke = opts.invoker ?? realInvoker;
@@ -86,10 +98,19 @@ export class RunSession {
             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;
+        let recut = false;
         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.`);
+            if (opts.followup) {
+                // A reopened run whose branch you already merged starts on a fresh branch from HEAD (never when work would be lost).
+                const r = recutLeadWorkspace(project, runId, project.lead, leadSpace, resume.result_branch?.head);
+                leadSpace = r.ws;
+                recut = r.recut;
+                if (r.recut)
+                    say(`  ${project.lead}'s branch was already merged: a fresh branch ${leadSpace.branch} was cut from HEAD ${leadSpace.base.slice(0, 8)}`);
+            }
         }
         ensureProjectDirs(project);
         fs.mkdirSync(runDir, { recursive: true });
@@ -103,7 +124,7 @@ export class RunSession {
         }
         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] };
+            state = { ...resume, max_rounds: roundLimit(resume, 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] };
             // A wake that was running when the process died never finished; keep it in the history as interrupted.
             for (const [agent, a] of Object.entries(resume.active ?? {})) {
                 state.wakes.push({
@@ -116,11 +137,24 @@ export class RunSession {
                     error: "interrupted",
                 });
             }
+            if (opts.followup) {
+                state.reopened = [...(resume.reopened ?? []), { at: new Date().toISOString() }];
+                state.round_floor = resume.rounds;
+                state.max_rounds = roundLimit(state, cfg.max_rounds);
+                state.result_branch = undefined;
+                state.done_rejections = 0;
+                if (recut && resume.pr_url) {
+                    // The recorded pull request is the merged branch's: it must not be mistaken for the new segment's.
+                    state.notes = [...(resume.notes ?? []), `The earlier pull request ${resume.pr_url} belongs to the merged branch; a new one is opened for the follow-up work.`];
+                    state.pr_url = undefined;
+                }
+            }
         }
         else {
             const t = taskMessageBody(task);
             state = newRunState({
                 run_id: runId,
+                name: opts.name,
                 project: project.name,
                 task_source: task.source,
                 task_path: task.sourcePath,
@@ -143,6 +177,26 @@ export class RunSession {
         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 ?? {}) });
+            if (opts.followup) {
+                const n = state.reopened?.length ?? 1;
+                fs.mkdirSync(path.join(runDir, "followups"), { recursive: true });
+                fs.writeFileSync(path.join(runDir, "followups", `${n}.md`), `${opts.followup.text.trimEnd()}\n`);
+                // A run finished before done-<n>.md existed has only result.md: keep that report before the next done overwrites it.
+                const prev = path.join(runDir, `done-${n}.md`);
+                const legacy = path.join(runDir, RESULT_FILE);
+                if (!fs.existsSync(prev) && fs.existsSync(legacy))
+                    fs.copyFileSync(legacy, prev);
+                const handoffIdx = sharedIndex(project);
+                const handoffLine = handoffIdx && fs.existsSync(handoffIdx) ? ` The handoff notes written for follow-ups are in \`${handoffIdx}\`.` : "";
+                deliver(project, {
+                    from: "user",
+                    to: project.lead,
+                    type: "task",
+                    subject: opts.followup.text.split("\n").find((l) => l.trim())?.slice(0, 80) ?? "Follow-up",
+                    body: `## Goal\n${opts.followup.text.trimEnd()}\n\n## Acceptance criteria\nAs stated in the goal; the earlier result still holds unless the goal changes it.\n\n## Scope\nThis run's earlier work and files.\n\n## Upstream\nThe previous final report is in \`${path.join(runDir, `done-${n}.md`)}\`; the original task is in \`${path.join(runDir, "task.md")}\`.${handoffLine}\n`,
+                });
+                log("reopen", { n });
+            }
         }
         else {
             const t = taskMessageBody(task);
@@ -165,6 +219,8 @@ export class RunSession {
         this.log = log;
         this.guard = guard;
         this.state = state;
+        // Only a segment that starts here has a baseline: a fresh run or a follow-up reopen. A plain resume continues one begun by an earlier process.
+        this.sharedAtStart = !resume || opts.followup ? readIndex(sharedIndex(project)) : undefined;
     }
     /** A waiting run only continues once every unanswered question has a valid answer. */
     static assertAnswered(runDir, runId) {
@@ -241,19 +297,19 @@ export class RunSession {
             workDir,
             workspace: spaces[agent.name],
             systemPrompt: buildSystemPrompt(aproject, agent),
-            userPrompt: buildUserPrompt(project, agent, queue, unread.length),
+            userPrompt: buildUserPrompt(project, agent, queue, unread.length, (state.reopened?.length ?? 0) > 0),
             timeoutSec: cfg.wake_timeout_sec,
         };
         let result;
         for (let attempt = 0; attempt <= cfg.retry; attempt++) {
-            if (state.rounds >= cfg.max_rounds) {
+            if (state.rounds >= state.max_rounds) {
                 result = { ok: false, text: "", exitCode: null, timedOut: false, error: "round limit reached" };
                 break;
             }
             const round = ++state.rounds;
             const started = Date.now();
             const att = beginAttempt(runDir, claim.id);
-            say(`[round ${state.rounds}/${cfg.max_rounds}] waking ${agent.name} (${agent.runtime})${attempt ? ` — retry ${attempt}` : ""}`);
+            say(`[round ${state.rounds}/${state.max_rounds}] waking ${agent.name} (${agent.runtime})${attempt ? ` — retry ${attempt}` : ""}`);
             const sessionId = agent.resume ? state.sessions[agent.name] : undefined;
             const handling = unread.map((m) => ({ from: m.meta.from, type: m.meta.type, subject: m.meta.subject, brief: briefOf(m.body), digest: digestOf(m.meta.type, m.body) }));
             state.active[agent.name] = { round, since: new Date(started).toISOString(), handling };
@@ -466,13 +522,22 @@ export class RunSession {
             log("rejected", r);
         }
         if (route.done) {
+            const handoffIdx = sharedIndex(project);
+            const nowShared = handoffIdx && this.sharedAtStart !== undefined ? readIndex(handoffIdx) : undefined;
+            if (nowShared !== undefined && nowShared === this.sharedAtStart) {
+                this.note(nowShared.trim()
+                    ? `shared-not-updated: the lead did not change the handoff notes (${handoffIdx}) in this segment; a follow-up will see them as they are.`
+                    : `shared-not-updated: the lead did not write handoff notes (${handoffIdx}) in this segment, so a follow-up will start without handoff notes.`);
+            }
             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;
             this.doneVerification = resolved.verification;
-            atomicWrite(path.join(runDir, RESULT_FILE), `# ${route.done.subject}\n\n**Outcome:** ${this.doneOutcome}${this.doneNote ? ` (${this.doneNote})` : ""}\n\n${route.done.body.trimEnd()}\n`);
+            const report = `# ${route.done.subject}\n\n**Outcome:** ${this.doneOutcome}${this.doneNote ? ` (${this.doneNote})` : ""}\n\n${route.done.body.trimEnd()}\n`;
+            atomicWrite(path.join(runDir, RESULT_FILE), report);
+            atomicWrite(path.join(runDir, `done-${(state.reopened?.length ?? 0) + 1}.md`), report);
             this.pendingDoneFile = route.done.file;
             log("done", { subject: route.done.subject });
             this.endReason = "done";
@@ -604,6 +669,7 @@ export class RunSession {
             return skip(`the work could not be committed on ${this.leadSpace.branch}.`);
         if (!rb.files)
             return skip(`${rb.branch} has no file changes.`);
+        const existingUrl = state.pr_url;
         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),
@@ -612,11 +678,14 @@ export class RunSession {
             body: prBody(this.doneMessage?.body ?? ""),
             bodyFile: path.join(runDir, "pr-body.md"),
             run: this.prRunner,
+            existingUrl,
         });
         log("pull-request", { ...result });
         if (result.status === "opened") {
+            say(`  pull request ${result.updated ? "updated" : "opened"}: ${result.url}`);
+            if (existingUrl && !result.updated && !state.notes?.some((n) => n.includes(existingUrl)))
+                this.note(`The earlier pull request ${existingUrl} was no longer open; a new one was opened for the follow-up work.`);
             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")}` : ""}`);
@@ -655,7 +724,7 @@ export class RunSession {
     async run() {
         if (this.resume)
             this.recover();
-        const { say, cfg, runId, runDir, project, wsMode, log, state, opts } = this;
+        const { say, runId, runDir, project, wsMode, log, state, opts } = this;
         // When the lead was the last one woken and left every mailbox empty without a `done`, remind it once instead of ending silently.
         let leadWasLast = false;
         let nudged = false;
@@ -682,7 +751,7 @@ export class RunSession {
                 this.endReason = "idle";
                 break;
             }
-            if (state.rounds >= cfg.max_rounds) {
+            if (state.rounds >= state.max_rounds) {
                 this.endReason = "max_rounds";
                 break;
             }
@@ -744,6 +813,6 @@ export class RunSession {
         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, resultBranch, pr };
+        return { runId, name: state.name, 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

@@ -99,6 +99,14 @@ export interface RunState {
     wakes: WakeRecord[];
     /** Checklist progress: seeded from the task, then replaced by the lead's latest `## Steps`. */
     steps?: Step[];
+    /** Readable name; lets `resume`, `clear` and `status` find the run without its id. Absent on runs from older versions. */
+    name?: string;
+    /** One entry per time a finished run was reopened with a follow-up. */
+    reopened?: {
+        at: string;
+    }[];
+    /** `rounds` at the last reopen; the round limit counts from here. */
+    round_floor?: number;
 }
 /** `20261006T010203456Z-<128 random bits>`: sorts by start time and cannot collide, even for two starts in one millisecond. */
 export declare function newRunId(d?: Date): string;
@@ -122,3 +130,26 @@ export declare function outcomeOf(s: Pick<RunState, "outcome" | "end_reason">):
     outcome: RunOutcome;
     verified: boolean;
 } | undefined;
+export declare function slugify(text: string): string;
+/** `base`, or `base-2`, `base-3` … the first that is not in `taken`. */
+export declare function uniqueName(base: string, taken: string[]): string;
+/** How a run is named in output: `name (run_id)`, or just the id for a run without a name. */
+export declare const runLabel: (r: {
+    name?: string;
+    run_id: string;
+}) => string;
+export type RunRef = {
+    dir: string;
+    state: RunState;
+};
+export type Resolved = {
+    ok: true;
+    run: RunRef;
+} | {
+    ok: false;
+    reason: "none" | "ambiguous";
+    candidates: RunRef[];
+};
+/** Find a run by full id, exact name, or a prefix of either that matches exactly one run. An exact id or name always wins. */
+export declare function resolveRun(runs: RunRef[], query: string): Resolved;
+export declare const roundLimit: (state: Pick<RunState, "round_floor">, maxRounds: number) => number;

package/dist/run-store.js

@@ -39,6 +39,9 @@ const WireState = z
     wakes: z.array(z.any()).optional(),
     solo_agent: z.string().optional(),
     steps: z.array(z.object({ text: z.string(), done: z.boolean() })).optional(),
+    name: z.string().optional(),
+    reopened: z.array(z.object({ at: z.string() })).optional(),
+    round_floor: nonNeg.optional(),
 })
     .passthrough();
 /** A fresh v2 state; every collection present. */
@@ -119,3 +122,38 @@ export function outcomeOf(s) {
         return undefined;
     return { outcome: s.end_reason === "lead_failed" ? "failed" : s.end_reason === "cancelled" ? "cancelled" : s.end_reason === "waiting" ? "waiting" : "partial", verified: false };
 }
+const NAME_MAX = 30;
+export function slugify(text) {
+    const s = text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, NAME_MAX)
+        .replace(/-+$/g, "");
+    return s || "task";
+}
+/** `base`, or `base-2`, `base-3` … the first that is not in `taken`. */
+export function uniqueName(base, taken) {
+    if (!taken.includes(base))
+        return base;
+    for (let n = 2;; n++) {
+        const suffix = `-${n}`;
+        // The result stays within the 30 characters of a slug: trim the base, then any "-" the trim leaves at its end.
+        const candidate = `${base.slice(0, Math.max(1, NAME_MAX - suffix.length)).replace(/-+$/g, "")}${suffix}`;
+        if (!taken.includes(candidate))
+            return candidate;
+    }
+}
+/** How a run is named in output: `name (run_id)`, or just the id for a run without a name. */
+export const runLabel = (r) => (r.name ? `${r.name} (${r.run_id})` : r.run_id);
+/** Find a run by full id, exact name, or a prefix of either that matches exactly one run. An exact id or name always wins. */
+export function resolveRun(runs, query) {
+    const exact = runs.filter((r) => r.state.run_id === query || r.state.name === query);
+    if (exact.length === 1)
+        return { ok: true, run: exact[0] };
+    const pool = exact.length ? exact : runs.filter((r) => r.state.run_id.startsWith(query) || (r.state.name ?? "").startsWith(query));
+    if (pool.length === 1)
+        return { ok: true, run: pool[0] };
+    return { ok: false, reason: pool.length ? "ambiguous" : "none", candidates: pool };
+}
+export const roundLimit = (state, maxRounds) => (state.round_floor ?? 0) + maxRounds;

package/dist/status.d.ts

@@ -11,6 +11,11 @@ export declare function latestUnfinishedRun(project: ResolvedProject): {
     dir: string;
     state: RunState;
 } | undefined;
+/** Runs a follow-up text can reopen: the finished ones (end_reason "done"). Newest first. */
+export declare function reopenCandidates(project: ResolvedProject): {
+    dir: string;
+    state: RunState;
+}[];
 export declare function listRuns(project: ResolvedProject, limit: number): {
     dir: string;
     state: RunState;
@@ -44,6 +49,8 @@ export interface QueueItem {
 }
 export interface RunReport {
     run_id: string;
+    /** Absent on runs from older versions. */
+    name?: string;
     dir: string;
     /** running: its dispatcher is alive; interrupted: it died mid-run; ended: it stopped (see end_reason). */
     state: "running" | "interrupted" | "ended" | "waiting";