agent-lyceum 0.25.0 → 0.26.0

package/dist/status.js

@@ -5,7 +5,9 @@ import { RESULT_FILE } from "./dispatcher.js";
 import { bindRunProject, loadRunState, outcomeOf, roundsLabel, runLabel } from "./run-store.js";
 import { candidatesFor } from "./fallback.js";
 import { briefOf, digestOf } from "./format.js";
-import { listUnread } from "./mailbox.js";
+import { PENDING_DIR, listUnread, readMessageNoFollow } from "./mailbox.js";
+import { parseSlotName } from "./instances.js";
+import { inboxDir } from "./policy.js";
 import { tidyAdvice } from "./memory-tidy.js";
 import { inspectRunLock, lockHolderAlive } from "./project-lock.js";
 /** The run to show: the newest one still running (a resumed run keeps its old id, so newer runs may sit above it), else the newest run. */
@@ -154,7 +156,7 @@ function stepsLine(steps, c, finished = false) {
     return `目前：${clip(cur.text, 60)}`;
 }
 /** Order the dispatcher will wake agents: the lead first, otherwise the oldest mail. */
-function queueOf(project) {
+function queueOf(project, instances) {
     const rows = Object.values(project.agents)
         .map((a) => ({ agent: a.name, msg: listUnread(project, a.name)[0] }))
         .flatMap((r) => (r.msg ? [{ agent: r.agent, msg: r.msg }] : []));
@@ -163,7 +165,7 @@ function queueOf(project) {
             return x.agent === project.lead ? -1 : 1;
         return path.basename(x.msg.file).localeCompare(path.basename(y.msg.file));
     });
-    return rows.map((r) => ({
+    const items = rows.map((r) => ({
         agent: r.agent,
         from: r.msg.meta.from,
         type: r.msg.meta.type,
@@ -171,14 +173,44 @@ function queueOf(project) {
         brief: briefOf(r.msg.body),
         digest: digestOf(r.msg.meta.type, r.msg.body),
     }));
+    return [...items, ...heldQueue(project, instances)];
 }
+/** Mail the assigner still holds for roles with instances, oldest first per role. Unreadable files are skipped. */
+function heldQueue(project, instances) {
+    const out = [];
+    for (const role of Object.keys(instances?.roles ?? {}).sort()) {
+        const dir = path.join(inboxDir(project, role), PENDING_DIR);
+        let files = [];
+        try {
+            files = fs.readdirSync(dir).filter((f) => f.endsWith(".md") && !f.startsWith(".")).sort();
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            try {
+                const m = readMessageNoFollow(path.join(dir, f));
+                out.push({ agent: role, held: true, from: m.meta.from, type: m.meta.type, subject: m.meta.subject, brief: briefOf(m.body), digest: digestOf(m.meta.type, m.body) });
+            }
+            catch {
+                /* a half-written file: the next poll sees it */
+            }
+        }
+    }
+    return out;
+}
+/** How an agent is named on the text pages: an instance of a role shows as `role #k`. */
+const shownName = (name, slots) => {
+    const i = parseSlotName(name);
+    return i && slots?.[i.role]?.[i.k - 1] === name ? `${i.role} #${i.k}` : name;
+};
 /** One run as `status` sees it. Without `project`, liveness falls back to the recorded pid and there is no queue. */
 export function buildRunReport(run, project, opts = {}) {
     const s = run.state;
     const detail = opts.detail ?? true;
     const live = runIsAlive(s, project) && !s.end_reason;
     const o = outcomeOf(s);
-    const bound = project ? bindRunProject(project, run.dir, s.mail_layout) : undefined;
+    const bound = project ? bindRunProject(project, run.dir, s.mail_layout, s.instances) : undefined;
     const result = path.join(run.dir, RESULT_FILE);
     const hasResult = detail && s.end_reason === "done" && fs.existsSync(result);
     const cur = s.steps?.find((x) => !x.done);
@@ -221,7 +253,7 @@ export function buildRunReport(run, project, opts = {}) {
         current_step: cur?.text ?? null,
         active: s.active,
         // mail still waiting is what `resume` will pick up, so it is shown for every run that did not finish with a done
-        queue: detail && bound && s.end_reason !== "done" ? queueOf(bound) : [],
+        queue: detail && bound && s.end_reason !== "done" ? queueOf(bound, s.instances) : [],
         wakes: s.wakes,
         notes: s.notes ?? [],
         blocked_integrations: s.blocked_integrations ?? [],
@@ -230,6 +262,7 @@ export function buildRunReport(run, project, opts = {}) {
         mail_layout: s.mail_layout,
         workspace_mode: s.workspace_mode,
         last_wake: s.last_wake,
+        ...(s.instances ? { instances: s.instances.roles } : {}),
         ...(ask ? { ask } : {}),
     };
 }
@@ -277,7 +310,7 @@ export function buildStatusReport(base, runId, now = Date.now()) {
     else
         run = currentRun(base);
     // Mail is per run: count the unread mail of the run being shown.
-    const project = run ? bindRunProject(base, run.dir, run.state.mail_layout) : base;
+    const project = run ? bindRunProject(base, run.dir, run.state.mail_layout, run.state.instances) : base;
     const report = run ? buildRunReport(run, base) : undefined;
     let advice = [];
     try {
@@ -293,6 +326,7 @@ export function buildStatusReport(base, runId, now = Date.now()) {
             name: a.name,
             runtime: a.runtime,
             lead: a.name === project.lead,
+            ...(a.instance ? { role: a.instance.role, instance: a.instance.k } : {}),
             unread: listUnread(project, a.name).length,
             can_message: (a.canMessage === "all" ? Object.keys(project.agents) : a.canMessage).filter((n) => n !== a.name),
             last_wake: run?.state.last_wake[a.name],
@@ -309,10 +343,10 @@ export function buildTaskListReport(project) {
 // ---- text pages ----
 /** Agents in wake order, newest last; the ones working now are bracketed. */
 function flowLine(r, c) {
-    const names = (r.wakes ?? []).map((w) => w.agent);
+    const names = (r.wakes ?? []).map((w) => shownName(w.agent, r.instances));
     const shown = names.slice(-7);
     const parts = shown.map((n) => c.cyan(n));
-    const activeNames = r.live ? Object.keys(r.active ?? {}) : [];
+    const activeNames = r.live ? Object.keys(r.active ?? {}).map((n) => shownName(n, r.instances)) : [];
     const out = (names.length > shown.length ? "… → " : "") + parts.join(" → ");
     if (!activeNames.length)
         return out || "（尚無）";
@@ -320,7 +354,7 @@ function flowLine(r, c) {
 }
 /** The state label of a report: an outcome that was only inferred (old runs) is not shown as a checked result. */
 const reportLabel = (r) => runStateLabel({ end_reason: r.end_reason, outcome: r.outcome_verified ? r.outcome : undefined }, r.live);
-const mailText = (m) => `來自 ${m.from} 的 ${m.type}：「${clip(m.subject, 60)}」`;
+const mailText = (m, slots) => `來自 ${shownName(m.from, slots)} 的 ${m.type}：「${clip(m.subject, 60)}」${m.held ? "（保留中，等待空閒實例）" : ""}`;
 const taskText = (s) => s.task_summary ?? (s.task_source === "file" ? `檔案 ${s.task_path}` : "文字");
 /** The readable top block: what is happening, what is next, how far along the task is. */
 function summaryBlock(run, now, c) {
@@ -338,7 +372,7 @@ function summaryBlock(run, now, c) {
     const active = Object.entries(s.active ?? {});
     if (active.length) {
         for (const [i, [agent, a]] of active.entries()) {
-            lines.push(`${i === 0 ? L("現在：") : "          "}${c.cyan(agent)} ${live ? c.green(`工作中 ${since(a.since, now)}`) : c.yellow("曾在工作（已中斷）")}，處理 ${handlingText(a.handling)}`);
+            lines.push(`${i === 0 ? L("現在：") : "          "}${c.cyan(shownName(agent, s.instances))} ${live ? c.green(`工作中 ${since(a.since, now)}`) : c.yellow("曾在工作（已中斷）")}，處理 ${handlingText(a.handling)}`);
         }
     }
     else
@@ -346,7 +380,7 @@ function summaryBlock(run, now, c) {
     const queue = s.queue;
     if (queue.length) {
         for (const [i, q] of queue.slice(0, 3).entries())
-            lines.push(`${i === 0 ? L("下一個：") : "          "}${c.cyan(q.agent)} ← ${mailText(q)}`);
+            lines.push(`${i === 0 ? L("下一個：") : "          "}${c.cyan(q.agent)} ← ${mailText(q, s.instances)}`);
         if (queue.length > 3)
             lines.push(c.dim(`          … 還有 ${queue.length - 3} 筆`));
     }
@@ -387,10 +421,10 @@ function describeRun(s, now, c, limit = Infinity) {
     if (wakes.length > limit)
         lines.push(c.dim(`  … 省略較早的 ${wakes.length - limit} 筆（不帶 --monitor 可看完整紀錄）`));
     for (const w of limit < wakes.length ? wakes.slice(-limit) : wakes) {
-        lines.push(`  #${w.round} ${c.cyan(w.agent)} ${okText(c, w.ok)} (${Math.round(w.duration_ms / 1000)}s, ${tokens(w.output_tokens)} tok) — ${handlingText(w.handling)}`, `      → ${sentText(w.sent)}`);
+        lines.push(`  #${w.round} ${c.cyan(shownName(w.agent, s.instances))} ${okText(c, w.ok)} (${Math.round(w.duration_ms / 1000)}s, ${tokens(w.output_tokens)} tok) — ${handlingText(w.handling)}`, `      → ${sentText(w.sent)}`);
     }
     for (const [agent, a] of Object.entries(s.active ?? {})) {
-        lines.push(`  #${a.round} ${c.cyan(agent)} ${c.green(`工作中 ${since(a.since, now)}`)} — ${handlingText(a.handling)}`);
+        lines.push(`  #${a.round} ${c.cyan(shownName(agent, s.instances))} ${c.green(`工作中 ${since(a.since, now)}`)} — ${handlingText(a.handling)}`);
     }
     return lines;
 }
@@ -486,7 +520,7 @@ export function formatStatusReport(report, now = Date.now(), color = false) {
     const rows = [header];
     for (const a of report.agents) {
         const lw = a.last_wake;
-        rows.push([a.name + (a.lead ? " (lead)" : ""), a.runtime ?? "?", String(a.unread), lw ? `${lw.ok ? "成功" : "失敗"} ${lw.at}` : "-"]);
+        rows.push([(a.instance && a.instance >= 2 && a.role ? `${a.role} #${a.instance}` : a.name) + (a.lead ? " (lead)" : ""), a.runtime ?? "?", String(a.unread), lw ? `${lw.ok ? "成功" : "失敗"} ${lw.at}` : "-"]);
     }
     const w = header.map((_, i) => Math.max(...rows.map((r) => cols(r[i] ?? ""))));
     // Pad on the plain text first so ANSI codes never skew the column widths.

package/dist/worktree.d.ts

@@ -81,6 +81,7 @@ export declare function snapshotHead(project: ResolvedProject, runId: string): s
  * `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, from?: AgentWorkspace): string;
+export declare const workspaceRoot: (project: ResolvedProject, runId: string, agent: string) => 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
@@ -144,6 +145,11 @@ export declare function integrateAgentChanges(project: ResolvedProject, changes:
  * Throws when the metadata predates recording the git dir and the git dir cannot be told for certain.
  */
 export declare function existingAgentWorkspace(project: ResolvedProject, runId: string, agent: string): AgentWorkspace | undefined;
+/**
+ * The git dir recorded in an agent's worktree metadata, read-only (never completes or rewrites legacy metadata). undefined when there
+ * is no readable metadata or it predates recording the git dir.
+ */
+export declare function recordedGitDir(project: ResolvedProject, runId: string, agent: string): string | undefined;
 export interface WorkspaceWork {
     agent: string;
     root: string;

package/dist/worktree.js

@@ -290,7 +290,7 @@ export function snapshotBase(project, runId, n, from) {
         fs.rmSync(index, { force: true });
     }
 }
-const workspaceRoot = (project, runId, agent) => path.join(project.paths.root, "worktrees", runId, agent);
+export const workspaceRoot = (project, runId, agent) => path.join(project.paths.root, "worktrees", runId, agent);
 /** The user's repo's git common dir, as a real absolute path. Asked of the user's repo, never of a worktree. */
 const commonDirOf = (top) => fs.realpathSync(git(top, ["rev-parse", "--path-format=absolute", "--git-common-dir"]));
 /** The admin dirs under `<commonDir>/worktrees/` whose `gitdir` file names `<root>/.git` (the file may hold a relative path). */
@@ -594,6 +594,19 @@ export function existingAgentWorkspace(project, runId, agent) {
     }
     return fs.existsSync(root) ? describeWorkspace(project, root, agent, meta) : undefined;
 }
+/**
+ * The git dir recorded in an agent's worktree metadata, read-only (never completes or rewrites legacy metadata). undefined when there
+ * is no readable metadata or it predates recording the git dir.
+ */
+export function recordedGitDir(project, runId, agent) {
+    try {
+        const meta = JSON.parse(fs.readFileSync(`${workspaceRoot(project, runId, agent)}.json`, "utf8"));
+        return typeof meta.gitDir === "string" && meta.gitDir ? meta.gitDir : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** What is in an agent's worktree that exists nowhere else: uncommitted changes, and commits whose files are not in the main repo. */
 export function inspectWorkspace(project, runId, agent, target) {
     const root = workspaceRoot(project, runId, agent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-lyceum",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Config + dispatcher for teams of Claude Code / Codex agents with scoped context and file-based mailboxes",
   "keywords": [
     "ai",