pi-herdsman 0.20.1 → 0.21.0

package/SKILL.md

@@ -375,10 +375,10 @@ Chief supervises independent leads and never changes ownership. Use
 supervisor's attention, decision, or action, such as a blocker, warning, scope
 change, risk, or important evidence. Ordinary Leads without a verified
 supervisor continue independently; assigned project Leads may message the
-Manager role while its process is unavailable, and those messages remain
-retained with the project. For an assigned project, Herdsman automatically
-records the Lead's normal response to each project-assignment delivery as a
-project message for the current or a replacement Manager. If the Lead
+Manager role while its process is unavailable. Messages remain pending during
+Manager absence and are delivered to the next Manager that can receive them. For an assigned project, Herdsman
+automatically records the Lead's normal response to each project-assignment
+delivery as a project message for the Manager role. If the Lead
 successfully delegates or continues managed Agent work, the herd run owns that
 handoff until it settles; summarize the outcome, validation, and important
 unresolved points in the settled response. An unsuccessful delegation leaves
@@ -389,8 +389,9 @@ Descendants use `ask_owner`, not supervisor tools. Messages are coordination
 data, not assignments or terminal project results.
 
 `supervisor_message` is available to ordinary Leads and Managers. Assigned Lead
-messages are retained with the project and remain available to a replacement
-Manager, including when no Manager is active at send time. Manager messages to
+messages remain pending while Manager is absent and are delivered to the next
+Manager that can receive them; delivered messages are Pi conversation history,
+not pending Herdsman coordination. Manager messages to
 Leads use `staff_message`. For files, these tools accept ordinary paths,
 reusable direct-agent result refs, and already-supplied canonical result refs
 through `files`.
@@ -451,17 +452,17 @@ Pi Herdsman uses one durable vocabulary:
   through implementation and review iterations;
 - `staff_stop` stops an exact Lead and its owned Agent tree while preserving
   the assignment, Pi session, branch, and worktree. Successful Herdr worktree
-  removal retires the matching assignment and retained project messages while
-  preserving the Git branch. A missing worktree alone does not retire the
+  removal retires the matching assignment and any still-pending project
+  messages while preserving the Git branch. A missing worktree alone does not retire the
   assignment; `staff_resume` can reconstruct it. Never infer ownership from
   worktree membership or start an overlapping writer beside another Lead;
 - `/manager leave` preserves project work; a later Manager can resume the same
   branch-based assignment;
 - a **herd** is one Lead and the complete Agent tree it owns;
 - a **Lead** owns its Agents. An assigned project Lead sends
-  `supervisor_message` to project-scoped storage for the current or a
-  replacement Manager, even when no Manager is active; it does not route those
-  messages to Chief. An unassigned Lead routes to its active Manager when one
+  `supervisor_message` to project-scoped storage; pending messages survive
+  Manager absence and go to the next Manager that can receive them. Delivered
+  messages are not replayed; messages do not route to Chief. An unassigned Lead routes to its active Manager when one
   exists, otherwise to Chief;
 - an **Agent** handles one bounded assignment and may delegate only when its
   definition allows it;

package/dist/index.js

@@ -15,7 +15,7 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 // package.json
 var package_default = {
   name: "pi-herdsman",
-  version: "0.20.1",
+  version: "0.21.0",
   type: "module",
   description: "Asynchronous Pi subagents and agent fleet orchestration for parallel coding agents with nested delegation, background work, and supervision in herdr.",
   license: "Apache-2.0",
@@ -57,7 +57,8 @@ var package_default = {
       "./dist/index.js"
     ],
     skills: [
-      "."
+      "./SKILL.md",
+      "./skills"
     ],
     image: "https://raw.githubusercontent.com/boadij/pi-herdsman/main/docs/assets/thumbnail.webp"
   },
@@ -106,7 +107,8 @@ var package_default = {
     "SKILL.md",
     "LICENSE",
     "docs",
-    "dist"
+    "dist",
+    "skills"
   ],
   publishConfig: {
     registry: "https://registry.npmjs.org/"
@@ -5455,6 +5457,11 @@ function expandedResultLines(tool, action, details, args, theme) {
       "session",
       details.session ?? details.session_id ?? details.pi_session_id ?? details.chiefSessionId
     ],
+    ["branch", tool === "staff" ? details.branch : void 0],
+    [
+      "task",
+      tool === "staff" && action === "resume" ? details.presentation_task : void 0
+    ],
     ["request", details.request_id],
     ["assignment request", details.assignment_request_id],
     ["pane", details.pane_id],
@@ -5511,8 +5518,26 @@ function expandedResultLines(tool, action, details, args, theme) {
       return lines;
     }
     const reports = Array.isArray(details.reports) ? details.reports : [];
+    const work = Array.isArray(details.work) ? details.work : [];
     lines.push(
       "",
+      ...work.length ? [
+        "project work:",
+        ...work.flatMap((item) => {
+          if (!item || typeof item !== "object") return [];
+          const branch = value(item.branch) || "unknown";
+          const status = value(item.status) || "unknown";
+          const runtime = value(item.runtime_state);
+          const task = value(item.task);
+          const issue = value(item.issue);
+          return [
+            `  ${branch} \xB7 ${status}${runtime ? ` \xB7 runtime=${runtime}` : ""}`,
+            ...task ? [`    task: ${task}`] : [],
+            ...issue ? [`    issue: ${issue}`] : []
+          ];
+        }),
+        ""
+      ] : [],
       ...reports.flatMap((lead) => {
         if (!lead || typeof lead !== "object") return [];
         const counts = lead.agent_counts && typeof lead.agent_counts === "object" ? lead.agent_counts : {};
@@ -5526,13 +5551,10 @@ function expandedResultLines(tool, action, details, args, theme) {
             `  agent counts: ${Object.entries(counts).filter(([, count]) => count !== void 0).map(([name, count]) => `${name}=${String(count)}`).join(" \xB7 ")}`
           ] : [],
           ...Array.isArray(lead.available_tools) ? [
-            `  can: ${lead.available_tools.map((tool2) => String(tool2).replace(/^staff_/, "")).join(", ")}`
+            `  can: ${lead.available_tools.map((tool2) => String(tool2).replace(/^staff_/, "")).join(", ") || "nothing"}`
           ] : []
         ];
-      }),
-      ...Array.isArray(details.assignments) ? details.assignments.map(
-        (assignment) => `assignment: ${value(assignment?.id)} \xB7 ${value(assignment?.phase)}${value(assignment?.branch) ? ` \xB7 branch: ${value(assignment.branch)}` : ""}${value(assignment?.workspace_id) ? ` \xB7 workspace: ${value(assignment.workspace_id)}` : ""}${value(assignment?.pane_id) ? ` \xB7 pane: ${value(assignment.pane_id)}` : ""}${value(assignment?.session) ? ` \xB7 session: ${value(assignment.session)}` : ""}`
-      ) : []
+      })
     );
   }
   if (action === "inspect")
@@ -6780,6 +6802,8 @@ async function drainCoordinationInbox(options) {
       }
       continue;
     }
+    const deliverAs = options.deliveryMode ? options.deliveryMode(record) : "followUp";
+    if (!deliverAs) continue;
     let token;
     const clearTransaction = async () => {
       if (token === void 0) return;
@@ -6856,7 +6880,7 @@ async function drainCoordinationInbox(options) {
               ...record.branch ? { branch: record.branch } : {}
             }
           },
-          { deliverAs: "followUp", triggerTurn: true },
+          { deliverAs, triggerTurn: true },
           record
         );
         await options.transaction?.revalidate(token, "after-send");
@@ -7594,6 +7618,16 @@ function listProjectMessages(runtime, repoKey, branch) {
     }
   }).sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
 }
+function removeProjectMessage(runtime, repoKey, branch, id) {
+  if (!UUID3.test(id)) throw new Error("Invalid project message ID");
+  const directory = projectMessageDirectory(runtime, repoKey, branch);
+  try {
+    unlinkSync6(join8(directory, `${id}.json`));
+    fsyncDirectory(directory);
+  } catch (error2) {
+    if (error2.code !== "ENOENT") throw error2;
+  }
+}
 function removeProjectMessages(runtime, repoKey, branch) {
   rmSync(projectMessageDirectory(runtime, repoKey, branch), {
     recursive: true,
@@ -7682,6 +7716,12 @@ guidance: continue independently; do not use supervisor_message until a supervis
 function supervisorStateMessage(customType, content, latestContent) {
   return latestContent === content ? void 0 : { customType, content, display: false };
 }
+function projectTaskSummary(text) {
+  const task = text.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/gu, " ").trim();
+  if (!task) return void 0;
+  const characters = Array.from(task);
+  return characters.length <= 160 ? task : `${characters.slice(0, 159).join("")}\u2026`;
+}
 function projectWorkSnapshot(options) {
   return options.assignments.map((assignment) => {
     const worktrees = options.worktrees.filter(
@@ -7710,16 +7750,13 @@ function projectWorkSnapshot(options) {
         status = "paused";
       }
     }
-    const task = assignment.text.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/gu, " ").trim();
-    const characters = Array.from(task);
+    const task = projectTaskSummary(assignment.text);
     return {
       branch: assignment.branch,
       session: assignment.id,
       status,
       ...runtimeState ? { runtimeState } : {},
-      ...task ? {
-        task: characters.length <= 160 ? task : `${characters.slice(0, 159).join("")}\u2026`
-      } : {},
+      ...task ? { task } : {},
       ...issue ? { issue } : {}
     };
   });
@@ -17803,6 +17840,7 @@ function createLeadProjectRuntime(host) {
       throw new Error(
         `No existing work was found on ${operation.branch}; start it with staff_delegate and a task.`
       );
+    const presentationTask = operation.action === "resume" ? projectTaskSummary(existing.text) : void 0;
     const id = operation.action === "resume" ? existing.id : operation.id;
     const branch = operation.branch;
     const topology = await runHerdr2(
@@ -17870,7 +17908,8 @@ function createLeadProjectRuntime(host) {
           branch,
           session: id,
           status: "active",
-          already_running: true
+          already_running: true,
+          ...presentationTask ? { presentation_task: presentationTask } : {}
         }
       };
     }
@@ -18320,7 +18359,8 @@ function createLeadProjectRuntime(host) {
           session: leadSessionId,
           workspace_id: workspaceId,
           branch: assignment.branch,
-          ...operation.action === "resume" ? { recovered: true } : {}
+          ...operation.action === "resume" ? { recovered: true } : {},
+          ...presentationTask ? { presentation_task: presentationTask } : {}
         }
       };
     } catch (error2) {
@@ -18404,7 +18444,9 @@ function createLeadProjectRuntime(host) {
             lead_counts: "leadCounts" in report ? report.leadCounts : void 0,
             leads: "leads" in report ? report.leads : []
           } : {},
-          available_actions: report.availableActions
+          available_tools: report.availableActions.map(
+            (action) => `staff_${action}`
+          )
         }))
       });
     }
@@ -18645,9 +18687,11 @@ function createLeadCoordinationRuntime(host) {
     quarantineChiefMessage: quarantineChiefMessage2,
     listProjectAssignments: listProjectAssignments2,
     listProjectMessages: listProjectMessages2,
+    removeProjectMessage: removeProjectMessage2,
     readProjectAssignment: readProjectAssignment2,
     importResultBindings: importResultBindings2
   } = host;
+  const reportedProjectMessageCleanupErrors = /* @__PURE__ */ new Set();
   const readLeadSessionIdsFromHost = (inventory, mailboxes, workspaceId) => readLeadSessionIds(inventory, mailboxes, workspaceId, host);
   const prepareCoordinationInput = async (ctx, text, files, operation, heading, recordForInput) => {
     const limits = await host.messageLimits(ctx);
@@ -19224,33 +19268,46 @@ function createLeadCoordinationRuntime(host) {
   const drainProjectMessages = async (ctx) => {
     if (activeRole() !== "manager" || leadRuntime.roleSuspended || !ctx.isIdle())
       return 0;
+    const runtime = supervisionRuntime2();
     const manager = await currentManager(ctx);
     if (!manager || !leadRuntime.managerLease || !sameManagerDescriptor2(manager, leadRuntime.managerLease.descriptor))
       return 0;
-    for (const assignment of listProjectAssignments2(
-      supervisionRuntime2(),
-      manager.repoKey
-    )) {
+    const hasProjectMessageReceipt = (record) => ctx.sessionManager.getEntries().some(
+      (entry) => entry?.customType === "pi-herdsman-project_message" && entry?.details?.id === record.id && entry?.details?.repoKey === record.repoKey && entry?.details?.branch === record.branch && entry?.details?.fromSessionId === record.fromSessionId
+    );
+    const consumeProjectMessage = (record) => {
+      try {
+        removeProjectMessage2(runtime, record.repoKey, record.branch, record.id);
+        reportedProjectMessageCleanupErrors.delete(record.id);
+      } catch (error2) {
+        if (!reportedProjectMessageCleanupErrors.has(record.id)) {
+          reportedProjectMessageCleanupErrors.add(record.id);
+          appendDurableError2(pi, ctx, "pi_herdsman_state_error", error2);
+        }
+      }
+    };
+    for (const assignment of listProjectAssignments2(runtime, manager.repoKey)) {
       for (const record of listProjectMessages2(
-        supervisionRuntime2(),
+        runtime,
         manager.repoKey,
         assignment.branch
       )) {
         if (record.fromSessionId !== assignment.id) continue;
-        const delivered = ctx.sessionManager.getEntries().some(
-          (entry) => entry?.customType === "pi-herdsman-project_message" && entry?.details?.id === record.id && entry?.details?.repoKey === record.repoKey && entry?.details?.branch === record.branch && entry?.details?.fromSessionId === record.fromSessionId
-        );
-        if (delivered) continue;
+        if (hasProjectMessageReceipt(record)) {
+          consumeProjectMessage(record);
+          continue;
+        }
         const current = await currentManager(ctx);
         const stillAssigned = readProjectAssignment2(
-          supervisionRuntime2(),
+          runtime,
           manager.repoKey,
           assignment.branch
         );
         if (!ctx.isIdle() || !current || !sameManagerDescriptor2(current, manager) || !stillAssigned || stillAssigned.id !== assignment.id)
           return 0;
         importResultBindings2(pi, ctx, record.resultBindings, "project_message");
-        await pi.sendMessage(
+        const backlog = record.createdAt < manager.createdAt;
+        pi.sendMessage(
           {
             customType: "pi-herdsman-project_message",
             content: `Project ${record.branch} from lead ${record.fromSessionId}:
@@ -19264,8 +19321,9 @@ ${record.text}`,
               fromSessionId: record.fromSessionId
             }
           },
-          { deliverAs: "followUp", triggerTurn: true }
+          backlog ? { triggerTurn: false } : { deliverAs: "followUp", triggerTurn: true }
         );
+        if (hasProjectMessageReceipt(record)) consumeProjectMessage(record);
         return 1;
       }
     }
@@ -19306,16 +19364,17 @@ function projectAssignmentInstruction(assignment) {
 
 Manager supervises project scope and assignment boundaries; you own technical
 decisions and orchestration of execution. Herdsman automatically hands your
-normal assignment response to the current or a replacement Manager. After
-successfully delegating or continuing managed Agent work, the herd run owns
-that handoff until it settles; summarize outcome, validation, and important
-unresolved points in your response. If delegation is unsuccessful, respond
+normal assignment response to the Manager role. If no Manager is available,
+the handoff remains pending until a Manager can receive it. After successfully
+delegating or continuing managed Agent work, the herd run owns that handoff
+until it settles; summarize outcome, validation, and important unresolved
+points in your response. If delegation is unsuccessful, respond
 locally. Later conversational replies stay local.
 
 Use supervisor_message only for material coordination requiring Manager
 attention, a decision, or action\u2014not routine status or a duplicate handoff.
-Messages are retained with the project while Manager is absent. Settlement is
-nonterminal; do not infer project closure from runtime state.`;
+Undelivered project handoffs survive Manager absence. Once delivered, they
+are not automatically replayed to later Managers. Settlement is nonterminal; do not infer project closure from runtime state.`;
 }
 function createLeadInboxRuntime(host) {
   let chiefInboxTimer;
@@ -19548,6 +19607,12 @@ function createLeadInboxRuntime(host) {
           managerDiagnostic("inbox_catch", { category: "cleanup" });
           appendDurableError2(pi, ctx, "pi_herdsman_state_error", error2);
         },
+        deliveryMode: (record) => {
+          const role2 = activeRole();
+          const supervisorDownlink = role2 === "lead" && (record.kind === "chief_message" || record.kind === "manager_message") || role2 === "manager" && record.kind === "chief_message";
+          if (supervisorDownlink) return "steer";
+          return ctx.isIdle() ? "followUp" : void 0;
+        },
         isDelivered: (id) => {
           const record = transactions.get(id)?.record;
           return record ? messageDelivered(ctx, record) : false;
@@ -19582,10 +19647,6 @@ function createLeadInboxRuntime(host) {
         sendMessage: async (message, options, record) => {
           const projectAssignment = typeof message === "object" && message !== null && "customType" in message && message.customType === "pi-herdsman-project_assignment";
           try {
-            if (!ctx.isIdle())
-              throw new Error(
-                "Coordination delivery deferred while recipient is active"
-              );
             let payload = message;
             let resultBindings = record.resultBindings;
             if (record.kind === "project_assignment") {
@@ -19713,7 +19774,6 @@ function createLeadInboxRuntime(host) {
         });
         return count;
       };
-      if (!ctx.isIdle()) return complete(0);
       const held = chiefStartPreflightHeld(ctx);
       managerDiagnostic("inbox_preflight", { reason: held ? "held" : "pass" });
       if (held) return complete(0);
@@ -20970,14 +21030,16 @@ Lead while preserving its assignment. Project retirement is user-controlled
 through successful Herdr worktree removal.
 
 Each project-assignment delivery to a Lead is an automatic handoff to you:
-Herdsman records the Lead's normal response as a project message for the current
-or a replacement Manager. If the Lead successfully delegates or
+Herdsman automatically hands the Lead's normal assignment response to the
+Manager role. If no Manager is available, the handoff remains pending until a Manager
+can receive it. If the Lead successfully delegates or
 continues managed Agent work, the herd run owns that handoff until it settles,
 and the Lead's settled response should summarize the outcome, validation, and
 important unresolved points. An unsuccessful delegation leaves the local
 assignment-response path available. Later conversational replies, including
 routine thanks or acknowledgments, remain local and are not automatically
-promoted. Review
+promoted. Undelivered project handoffs survive Manager absence. Once a handoff
+has been delivered, it is not automatically replayed to later Managers. Review
 received handoffs and request corrections with staff_message when needed.
 
 Project execution belongs to project Leads and their Agent trees. Your role
@@ -22181,7 +22243,7 @@ ${summary}`,
           ...staffTool,
           name: "staff_message",
           label: "staff message",
-          description: "Send a durable follow-up message to a direct report.",
+          description: "Send a durable supervisor message to a direct report; active work is steered cooperatively.",
           parameters: staffMessageParameters,
           promptSnippet: void 0,
           promptGuidelines: [FILE_HANDOFF_GUIDANCE],
@@ -22370,6 +22432,7 @@ ${summary}`,
           writeChiefMessage,
           listProjectAssignments,
           listProjectMessages,
+          removeProjectMessage,
           readProjectAssignment,
           importResultBindings
         },