@cryptolibertus/pi-peer 0.5.1 → 0.5.2

package/README.md

@@ -58,9 +58,9 @@ Useful commands (long form and short aliases):
 
 Short aliases keep common board updates terse: `/peer goals`/`/peer ls`, `/peer current`, `/peer scout`, `/peer fanout`, `/peer proposal`/`/peer propose`, `/peer take`/`/peer claim`, `/peer complete`/`/peer done`, `/peer objection`/`/peer block`, `/peer unblock`, `/peer note`, `/peer finding`, `/peer ping`/`/peer heartbeat`, `/peer drop`/`/peer release`, `/peer pass`, `/peer fail`, `/peer vote`, and `/peer close` map to the corresponding `/peer goal ...` actions.
 
-The board is stored locally at `.pi/peer-goals.json`; outbound message snapshots are stored in `.pi/peer-messages.json` so restarted planners can still inspect disconnected historical tasks. Mutating goal-board operations take a short local lock before load/modify/save so concurrent peer appends do not drop events. `/peer send --goal <goal-id> --claim <path[,path]>` and the `peer_send` tool's `goalId`/`claimedPaths` parameters link long-running peer tasks to the board: Symphony records a task, claims overlapping write paths before dispatch, injects goal/heartbeat instructions into the peer prompt, keeps the claim alive with local heartbeats, and releases the claim after the peer returns a final response. Each goal-linked dispatch also gets a semantic work key (`goalId | lane | objective | mode | paths`) so duplicate read/review/research lanes are leased just like write paths; pass `--key <work-key>` / `workKey` for an explicit fingerprint and `--duplicate-policy allow-parallel` only when independent second opinions are intentional. The default dispatch policy is `reuse`, so a matching active work key returns the existing claim/task handle instead of starting another peer. `/peer goal fanout` turns a goal into role-specific peer lanes, while `peer_progress` reports checkpoints from an inbound long-running task. Scout suggestions are persona-aware: they surface a recommended lane (`research`, `review`, `implementation`, `coordination`, etc.), preferred roles, a safe default claim mode, a stable work key, rationale, and suppress suggestions already covered by active work keys. `/peer scout` prints the exact work key and a copyable `claim:` command for each read-only suggestion, so idle peers can claim the same semantic lane the scout is using instead of inventing generic seed keys. Empty goals emit multiple lane-specific read-only suggestions so idle peers can self-select research, review/QA, or implementation-planning work instead of waiting for a planner to assign lanes. Lane-tagged proposals (for example `/peer goal propose <goal> "Check package contents" --lane review --key review:package-contents`) become matching scout suggestions that reuse the proposal work key, letting the next suitable peer claim or review that proposed lane and suppress duplicate suggestions while the lane is active. Active write claims conflict on overlapping paths; active semantic claims conflict on matching work keys; released, stale, or expired claims are kept visible but inactive. Completed goal-linked tasks are shown with their handoff status instead of remaining visually stuck as `running`. Claims become stale after 45 minutes without a heartbeat unless the claim or heartbeat sets `--stale-after-ms`.
+The board is stored locally at `.pi/peer-goals.json`; outbound message snapshots are stored in `.pi/peer-messages.json` so restarted planners can still inspect disconnected historical tasks. Mutating goal-board operations take a short local lock before load/modify/save so concurrent peer appends do not drop events. `/peer send --goal <goal-id> --claim <path[,path]>` and the `peer_send` tool's `goalId`/`claimedPaths` parameters link long-running peer tasks to the board: Symphony records a task, claims overlapping write paths before dispatch, injects goal/heartbeat instructions into the peer prompt, keeps the claim alive with local heartbeats, and releases the claim after the peer returns a final response. Each goal-linked dispatch also gets a semantic work key (`goalId | lane | objective | mode | paths`) so duplicate read/review/research lanes are leased just like write paths; pass `--key <work-key>` / `workKey` for an explicit fingerprint and `--duplicate-policy allow-parallel` only when independent second opinions are intentional. The default dispatch policy is `reuse`, so a matching active work key returns the existing claim/task handle instead of starting another peer. `/peer goal fanout` turns a goal into role-specific peer lanes; planned fanouts create `planned` task rows, while `--send` records only the dispatched peer task so boards do not accumulate orphan `dispatching` placeholders. Scout suggestions are persona-aware: they surface a recommended lane (`research`, `review`, `implementation`, `coordination`, etc.), preferred roles, a safe default claim mode, a stable work key, rationale, and suppress suggestions already covered by active work keys. `/peer scout` prints the exact work key and a copyable `claim:` command for each read-only suggestion, and fulfilled proposal lanes also print a direct `resolve:` command. Empty goals emit multiple lane-specific read-only suggestions so idle peers can self-select research, review/QA, or implementation-planning work instead of waiting for a planner to assign lanes; goals with stale-only claims prompt stale-claim cleanup instead of generic new startup lanes. Lane-tagged proposals (for example `/peer goal propose <goal> "Check package contents" --lane review --key review:package-contents`) become matching scout suggestions that reuse the proposal work key, letting the next suitable peer claim or review that proposed lane and suppress duplicate suggestions while the lane is active. Active write claims conflict on overlapping paths; active semantic claims conflict on matching work keys; released, stale, or expired claims are kept visible but inactive. Completed goal-linked tasks are shown with their handoff status instead of remaining visually stuck as `running`. Claims become stale after 45 minutes without a heartbeat unless the claim or heartbeat sets `--stale-after-ms`.
 
-Normal goal closure requires at least one current passing vote, no current failed votes, no unresolved blocking objections, no active write claims, and no unresolved open proposals. Proposals let peers show initiative, then must be resolved or explicitly deferred before normal closure so the final handoff reflects human intent; use `--force` only when intentionally overriding that readiness gate. Stale write claims no longer block closure or new overlapping claims; use `/peer goal heartbeat` to revive work after a reconnect. Goal-linked tasks validate final handoff headings (`Status`, `Files changed`, `Verification`, `Blockers/risks`, `Safe for review`); missing sections create a blocking objection while still releasing the write claim. For multi-part work, use the fan-out gate: list peers, create/reuse a goal, delegate research/review/worker lanes, and include `Fan-out used: yes/no` plus peer handles in the final answer.
+Normal goal closure requires at least one current passing vote, no current failed votes, no unresolved blocking objections, no active claims or running tasks, and no unresolved open proposals. Proposals let peers show initiative, then must be resolved or explicitly deferred before normal closure so the final handoff reflects human intent; use `--force` only when intentionally overriding that readiness gate. Stale claims no longer block closure or new overlapping claims; use `/peer goal heartbeat` to revive work after a reconnect. Goal-linked tasks validate final handoff headings (`Status`, `Files changed`, `Verification`, `Blockers/risks`, `Safe for review`); missing sections create a blocking objection while still releasing the write claim. For multi-part work, use the fan-out gate: list peers, create/reuse a goal, delegate research/review/worker lanes, and include `Fan-out used: yes/no` plus peer handles in the final answer.
 
 ## Idle watcher
 

package/extensions/pi-peer/index.ts

@@ -531,16 +531,20 @@ async function handlePeerGoalFanout(parsed: any, ctx: any, runtime: any, peerId:
   for (const targetPeerId of parsed.peers) {
     const mode = inferFanoutClaimMode(targetPeerId);
     const lane = inferFanoutWorkLane(targetPeerId, mode);
-    const summary = `${parsed.objective} [fanout:${targetPeerId}]`;
-    const task = await appendPeerGoalEvent(root, parsed.goalId, {
-      type: "task",
-      peerId,
-      summary,
-      paths: parsed.paths,
-      status: parsed.send ? "dispatching" : "planned",
-      metadata: { targetPeerId, fanout: true, claimMode: mode, workLane: lane },
-    });
-    planned.push({ peerId: targetPeerId, taskEventId: task.event.id, mode, lane });
+    const item: any = { peerId: targetPeerId, mode, lane };
+    if (!parsed.send) {
+      const summary = `${parsed.objective} [fanout:${targetPeerId}]`;
+      const task = await appendPeerGoalEvent(root, parsed.goalId, {
+        type: "task",
+        peerId,
+        summary,
+        paths: parsed.paths,
+        status: "planned",
+        metadata: { targetPeerId, fanout: true, claimMode: mode, workLane: lane },
+      });
+      item.taskEventId = task.event.id;
+    }
+    planned.push(item);
   }
   if (parsed.send) {
     await Promise.all(planned.map(async (item: any) => {
@@ -560,17 +564,19 @@ async function handlePeerGoalFanout(parsed: any, ctx: any, runtime: any, peerId:
           item.duplicate = true;
           item.messageId = goalLink.existingTask?.taskId || goalLink.existingTask?.metadata?.messageId;
           item.conversationId = goalLink.existingTask?.metadata?.conversationId;
-          await appendPeerGoalEvent(root, parsed.goalId, {
-            type: "handoff",
-            peerId: item.peerId,
-            summary: `Fan-out duplicate reused existing work key ${goalLink.workKey || "unknown"}`,
-            paths: parsed.paths,
-            taskId: item.taskEventId,
-            status: "done",
-            workKey: goalLink.workKey,
-            lane: item.lane,
-            metadata: { fanout: true, duplicate: true, targetPeerId: item.peerId, existingTaskId: item.messageId },
-          }).catch(() => {});
+          if (item.taskEventId) {
+            await appendPeerGoalEvent(root, parsed.goalId, {
+              type: "handoff",
+              peerId: item.peerId,
+              summary: `Fan-out duplicate reused existing work key ${goalLink.workKey || "unknown"}`,
+              paths: parsed.paths,
+              taskId: item.taskEventId,
+              status: "done",
+              workKey: goalLink.workKey,
+              lane: item.lane,
+              metadata: { fanout: true, duplicate: true, targetPeerId: item.peerId, existingTaskId: item.messageId },
+            }).catch(() => {});
+          }
           return;
         }
         const metadata = mergePeerMetadata({ fanout: true }, parsed.paths, parsed.goalId, { workKey: goalLink?.workKey, workLane: item.lane, duplicatePolicy: "reuse" });
@@ -590,12 +596,13 @@ async function handlePeerGoalFanout(parsed: any, ctx: any, runtime: any, peerId:
           await recordPeerSendGoalFailure(root, goalLink, { targetPeerId: item.peerId, prompt: parsed.objective, claimedPaths: parsed.paths, error });
         } else {
           await appendPeerGoalEvent(root, parsed.goalId, {
-            type: "handoff",
-            peerId: item.peerId,
+            type: item.taskEventId ? "handoff" : "task",
+            peerId: item.taskEventId ? item.peerId : peerId,
             summary: `Fan-out dispatch failed before claim: ${error?.message || String(error)}`,
             paths: parsed.paths,
             taskId: item.taskEventId,
             status: "blocked",
+            lane: item.lane,
             metadata: { fanout: true, targetPeerId: item.peerId },
           }).catch(() => {});
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cryptolibertus/pi-peer",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Pi package for local Pi-to-Pi peer messaging, slash commands, tools, and runtime transport.",
   "type": "module",
   "license": "MIT",

package/src/peers/goal-board.mjs

@@ -9,6 +9,7 @@ const EVENT_TYPES = new Set(["finding", "task", "proposal", "claim", "release",
 const BLOCKING_SEVERITIES = new Set(["blocking", "blocker", "critical"]);
 const VOTE_VERDICTS = new Set(["pass", "fail", "pass-with-risks"]);
 const DUPLICATE_POLICIES = new Set(["error", "reuse", "allow-parallel"]);
+const ACTIVE_TASK_STATUSES = new Set(["queued", "dispatching", "planned", "running", "pending", "blocked"]);
 const DEFAULT_GOAL_CLAIM_STALE_MS = 45 * 60 * 1000;
 const SCOUT_LANES = Object.freeze({
   blocker: { recommendedLane: "coordination", preferredRoles: ["planner", "coordinator", "reviewer"], claimMode: "read", suggestedIntent: "review", rationale: "Blocking objections need a coordination/review lane before more work starts." },
@@ -249,6 +250,7 @@ export function deriveGoalState(goal, options = {}) {
   const passingVotes = currentVotes.filter((vote) => vote.verdict === "pass" || vote.verdict === "pass-with-risks");
   const activeWriteClaims = activeClaims.filter((claim) => claim.mode === "write");
   const tasks = events.filter((event) => event.type === "task").map((event) => projectTaskSummary(event, events));
+  const activeTasks = tasks.filter(isActiveTaskSummary);
   return {
     ...goal,
     events,
@@ -265,7 +267,8 @@ export function deriveGoalState(goal, options = {}) {
     failedVotes,
     passingVotes,
     tasks,
-    readyToClose: goal?.status === "open" && blockingObjections.length === 0 && failedVotes.length === 0 && activeWriteClaims.length === 0 && openProposals.length === 0 && passingVotes.length > 0,
+    activeTasks,
+    readyToClose: goal?.status === "open" && blockingObjections.length === 0 && failedVotes.length === 0 && activeClaims.length === 0 && activeTasks.length === 0 && openProposals.length === 0 && passingVotes.length > 0,
   };
 }
 
@@ -295,6 +298,8 @@ export function formatPeerGoalScout(board, options = {}) {
     lines.push(`- ${suggestion.priority} · ${suggestion.goalId} · ${suggestion.kind}: ${suggestion.summary}${laneText}${pathText}${keyText}`);
     const claim = formatScoutClaimCommand(suggestion);
     if (claim) lines.push(`  claim: ${claim}`);
+    const resolve = formatScoutResolveCommand(suggestion);
+    if (resolve) lines.push(`  resolve: ${resolve}`);
   }
   lines.push("", "Next: post one with `/peer goal propose <goal-id> <summary>` or claim the exact suggested lane with the printed `claim:` command/work key. Scout does not mutate the board.");
   return lines.join("\n");
@@ -353,16 +358,18 @@ export function derivePeerGoalScoutSuggestions(board, options = {}) {
           relatedEventId: proposal.id,
         });
       }
-      push("P1", "open-proposal", formatOpenProposalTriageSummary(state, goal.id), {
-        paths: uniqueEventPaths(state.openProposals),
-        workKey: derivePeerGoalWorkKey({ goalId: goal.id, lane: "coordination", objective: "triage open proposals", mode: "read" }),
-      });
+      if (shouldSuggestOpenProposalTriage(state, goal.id)) {
+        push("P1", "open-proposal", formatOpenProposalTriageSummary(state, goal.id), {
+          paths: uniqueEventPaths(state.openProposals),
+          workKey: derivePeerGoalWorkKey({ goalId: goal.id, lane: "coordination", objective: "triage open proposals", mode: "read" }),
+        });
+      }
     }
     if (state.readyToClose && !state.openProposals.length) {
       push("P1", "close", "Goal satisfies closure gates; close it or record a final note.");
       continue;
     }
-    if (!state.activeClaims.length && !state.tasks.length && !state.openProposals.length) {
+    if (!state.activeClaims.length && !state.staleClaims.length && !state.tasks.length && !state.openProposals.length) {
       for (const lane of STARTUP_SCOUT_LANES) {
         push("P2", "next-step", lane.summary, {
           recommendedLane: lane.lane,
@@ -372,7 +379,7 @@ export function derivePeerGoalScoutSuggestions(board, options = {}) {
           rationale: "Multiple lane-specific suggestions let idle peers self-select complementary work and suppress duplicates by work key.",
         });
       }
-    } else if (!state.currentVotes.length && !state.activeWriteClaims.length && !state.openProposals.length) {
+    } else if (!state.currentVotes.length && !state.activeWriteClaims.length && !state.staleClaims.length && !state.openProposals.length) {
       push("P2", "review", "No current peer vote; ask a peer for read-only review or record a pass/fail vote.");
     }
   }
@@ -468,10 +475,17 @@ function validateGoalReadyToClose(state) {
   if (state.failedVotes.length) {
     throw new Error(`peer goal ${state.id} has failed peer votes: ${state.failedVotes.map((item) => item.peerId || item.id).join(", ")}`);
   }
-  if (state.activeWriteClaims.length) {
-    throw new Error(`peer goal ${state.id} has active write claims: ${state.activeWriteClaims.map((item) => item.id).join(", ")}`);
+  if (state.activeClaims.length) {
+    throw new Error(`peer goal ${state.id} has active claims: ${state.activeClaims.map((item) => item.id).join(", ")}`);
+  }
+  if (state.activeTasks?.length) {
+    throw new Error(`peer goal ${state.id} has active tasks: ${state.activeTasks.map((item) => item.taskId || item.id).join(", ")}`);
   }
-  if (!state.readyToClose) throw new Error(`peer goal ${state.id} is not ready to close; record at least one passing vote or use --force`);
+  if (state.openProposals.length) {
+    throw new Error(`peer goal ${state.id} has unresolved open proposals: ${state.openProposals.map((item) => item.id).join(", ")}`);
+  }
+  if (!state.passingVotes.length) throw new Error(`peer goal ${state.id} is not ready to close; record at least one passing vote or use --force`);
+  if (!state.readyToClose) throw new Error(`peer goal ${state.id} is not ready to close; use --force to override readiness gates`);
 }
 
 function normalizeEvent(input = {}) {
@@ -523,10 +537,9 @@ function taskSummary(input = {}) {
 
 function latestTaskForWorkKey(tasks = [], workKey) {
   if (!workKey) return undefined;
-  const activeStatuses = new Set(["queued", "dispatching", "running", "pending"]);
   return [...tasks]
     .reverse()
-    .find((task) => task.workKey === workKey && (!task.status || activeStatuses.has(String(task.status).toLowerCase())));
+    .find((task) => task.workKey === workKey && isActiveTaskSummary(task));
 }
 
 function normalizeBoard(board = {}) {
@@ -593,6 +606,10 @@ function projectTaskSummary(task, events) {
   });
 }
 
+function isActiveTaskSummary(task = {}) {
+  return !task.status || ACTIVE_TASK_STATUSES.has(String(task.status).toLowerCase());
+}
+
 function taskMatchesHandoff(task, event, events) {
   if (event.type !== "handoff" || event.at < task.at) return false;
   if (task.taskId && event.taskId === task.taskId) return true;
@@ -682,6 +699,11 @@ function formatScoutClaimCommand(suggestion = {}) {
   return `/peer goal claim ${shellQuote(suggestion.goalId)} ${shellQuote(suggestion.summary)} --mode read${lane} --key ${shellQuote(suggestion.workKey)}${paths}`;
 }
 
+function formatScoutResolveCommand(suggestion = {}) {
+  if (suggestion.kind !== "open-proposal" || !suggestion.relatedEventId || !String(suggestion.summary || "").startsWith("Resolve fulfilled")) return "";
+  return `/peer goal resolve ${shellQuote(suggestion.goalId)} ${shellQuote(suggestion.relatedEventId)} ${shellQuote("fulfilled lane complete")}`;
+}
+
 function shellQuote(value) {
   const text = String(value || "");
   if (/^[A-Za-z0-9_./:-]+$/.test(text)) return text;
@@ -724,11 +746,13 @@ function proposalLaneWorkCompleted(state, goalId, proposal) {
   return state.events.some((event) => ["finding", "handoff", "note"].includes(event.type) && event.workKey === workKey && String(event.at || "") >= proposalAt);
 }
 
+function shouldSuggestOpenProposalTriage(state, goalId) {
+  const counts = openProposalActionabilityCounts(state, goalId);
+  return counts.unclaimed > 0 || counts.fulfilled > 0;
+}
+
 function formatOpenProposalTriageSummary(state, goalId) {
-  const total = state.openProposals.length;
-  const actionable = state.openProposals.filter((proposal) => proposalLaneActionability(state, goalId, proposal) === "unclaimed").length;
-  const owned = state.openProposals.filter((proposal) => proposalLaneActionability(state, goalId, proposal) === "owned").length;
-  const fulfilled = state.openProposals.filter((proposal) => proposalLaneActionability(state, goalId, proposal) === "fulfilled").length;
+  const { total, unclaimed: actionable, owned, fulfilled } = openProposalActionabilityCounts(state, goalId);
   const detail = [];
   if (actionable !== total) detail.push(`${actionable} unclaimed actionable`);
   if (owned) detail.push(`${owned} active-owned`);
@@ -737,11 +761,17 @@ function formatOpenProposalTriageSummary(state, goalId) {
   return `Triage ${total} open proposal${total === 1 ? "" : "s"}${suffix}; claim one, resolve fulfilled work, or defer obsolete/ambiguous items.`;
 }
 
+function openProposalActionabilityCounts(state, goalId) {
+  const counts = { total: state.openProposals.length, unclaimed: 0, owned: 0, fulfilled: 0 };
+  for (const proposal of state.openProposals) counts[proposalLaneActionability(state, goalId, proposal)] += 1;
+  return counts;
+}
+
 function proposalLaneActionability(state, goalId, proposal) {
   const lane = normalizeLaneName(proposal?.lane);
   const workKey = proposalLaneWorkKey(goalId, lane, proposal);
-  if (workKey && state.activeClaims.some((claim) => claim.workKey === workKey)) return "owned";
   if (proposalLaneWorkCompleted(state, goalId, proposal)) return "fulfilled";
+  if (workKey && state.activeClaims.some((claim) => claim.workKey === workKey)) return "owned";
   return "unclaimed";
 }
 

package/src/peers/idle-watcher.mjs

@@ -35,6 +35,7 @@ export function createPeerIdleWatcher(options = {}) {
     timer: undefined,
     activationCount: 0,
     lastActivationAtByKey: new Map(),
+    lastActivationByGoal: new Map(),
     checking: false,
   };
 
@@ -132,7 +133,9 @@ export function markPeerIdleActivation(state, activation, nowMs = Date.now()) {
   if (!state || !activation) return false;
   state.activationCount = (state.activationCount || 0) + 1;
   if (!state.lastActivationAtByKey) state.lastActivationAtByKey = new Map();
+  if (!state.lastActivationByGoal) state.lastActivationByGoal = new Map();
   state.lastActivationAtByKey.set(peerIdleActivationKey(activation), nowMs);
+  state.lastActivationByGoal.set(activation.goalId, { at: nowMs, priority: activation.priority || "P2" });
   return true;
 }
 
@@ -165,8 +168,18 @@ export function peerIdleActivationKey(activation = {}) {
 }
 
 function isActivationCoolingDown(state, activation, config, nowMs) {
-  const last = state?.lastActivationAtByKey?.get?.(peerIdleActivationKey(activation));
-  return Number.isFinite(last) && nowMs - last < config.cooldownMs;
+  const exactLast = state?.lastActivationAtByKey?.get?.(peerIdleActivationKey(activation));
+  if (Number.isFinite(exactLast) && nowMs - exactLast < config.cooldownMs) return true;
+  const goalLast = state?.lastActivationByGoal?.get?.(activation.goalId);
+  if (!goalLast || !Number.isFinite(goalLast.at) || nowMs - goalLast.at >= config.cooldownMs) return false;
+  return priorityRank(activation.priority) >= priorityRank(goalLast.priority);
+}
+
+function priorityRank(priority) {
+  const normalized = String(priority || "P2").toUpperCase();
+  if (normalized === "P0") return 0;
+  if (normalized === "P1") return 1;
+  return 2;
 }
 
 function normalizeActivation(suggestion = {}, localPeerId, options = {}) {