@cryptolibertus/pi-peer 0.5.0 → 0.5.1

package/README.md

@@ -60,7 +60,7 @@ Short aliases keep common board updates terse: `/peer goals`/`/peer ls`, `/peer
 
 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`.
 
-Normal goal closure requires at least one current passing vote, no current failed votes, no unresolved blocking objections, and no active write claims. Open proposals are intentionally non-blocking: they let peers show initiative without freezing closure. Stale write claims no longer block closure or new overlapping claims; use `/peer goal heartbeat` to revive work after a reconnect and `--force` only when intentionally overriding the readiness gate. 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 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.
 
 ## Idle watcher
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cryptolibertus/pi-peer",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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

@@ -265,7 +265,7 @@ export function deriveGoalState(goal, options = {}) {
     failedVotes,
     passingVotes,
     tasks,
-    readyToClose: goal?.status === "open" && blockingObjections.length === 0 && failedVotes.length === 0 && activeWriteClaims.length === 0 && passingVotes.length > 0,
+    readyToClose: goal?.status === "open" && blockingObjections.length === 0 && failedVotes.length === 0 && activeWriteClaims.length === 0 && openProposals.length === 0 && passingVotes.length > 0,
   };
 }
 
@@ -326,7 +326,20 @@ export function derivePeerGoalScoutSuggestions(board, options = {}) {
       push("P1", "stale-claim", `Ask owners to heartbeat or release ${state.staleClaims.length} stale claim${state.staleClaims.length === 1 ? "" : "s"}.`, { paths: uniqueEventPaths(state.staleClaims) });
     }
     if (state.openProposals.length) {
-      for (const proposal of state.openProposals.filter((item) => item.lane)) {
+      for (const proposal of state.openProposals.filter((item) => item.lane && proposalLaneWorkCompleted(state, goal.id, item))) {
+        const lane = normalizeLaneName(proposal.lane);
+        push("P1", "open-proposal", `Resolve fulfilled ${lane} proposal or record why it remains open: ${proposal.summary}`, {
+          paths: proposal.paths,
+          recommendedLane: "coordination",
+          preferredRoles: preferredRolesForLane("coordination"),
+          claimMode: "read",
+          suggestedIntent: "coordinate",
+          rationale: "A peer posted completion evidence and released the lane; flat hierarchy works best when any suitable peer resolves or explicitly defers fulfilled proposals.",
+          workKey: derivePeerGoalWorkKey({ goalId: goal.id, lane: "coordination", objective: `resolve fulfilled proposal ${proposal.id}`, mode: "read", paths: proposal.paths }),
+          relatedEventId: proposal.id,
+        });
+      }
+      for (const proposal of state.openProposals.filter((item) => item.lane && !proposalLaneWorkCompleted(state, goal.id, item))) {
         const lane = normalizeLaneName(proposal.lane);
         const summary = `Self-select proposed ${lane} lane: ${proposal.summary}`;
         push("P1", "open-proposal", summary, {
@@ -336,13 +349,16 @@ export function derivePeerGoalScoutSuggestions(board, options = {}) {
           claimMode: "read",
           suggestedIntent: suggestedIntentForLane(lane),
           rationale: "A peer proposed a lane; matching idle peers can claim or review it without planner assignment.",
-          workKey: proposal.workKey || derivePeerGoalWorkKey({ goalId: goal.id, lane, objective: proposal.summary, mode: "read", paths: proposal.paths }),
+          workKey: proposalLaneWorkKey(goal.id, lane, proposal),
           relatedEventId: proposal.id,
         });
       }
-      push("P1", "open-proposal", `Triage ${state.openProposals.length} open proposal${state.openProposals.length === 1 ? "" : "s"}; claim one or resolve it if obsolete.`, { paths: uniqueEventPaths(state.openProposals) });
+      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) {
+    if (state.readyToClose && !state.openProposals.length) {
       push("P1", "close", "Goal satisfies closure gates; close it or record a final note.");
       continue;
     }
@@ -356,7 +372,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) {
+    } else if (!state.currentVotes.length && !state.activeWriteClaims.length && !state.openProposals.length) {
       push("P2", "review", "No current peer vote; ask a peer for read-only review or record a pass/fail vote.");
     }
   }
@@ -698,6 +714,41 @@ function hasActiveClaimForScoutSuggestion(state, suggestion) {
   return state.activeClaims.some((claim) => claim.workKey === suggestion.workKey);
 }
 
+function proposalLaneWorkCompleted(state, goalId, proposal) {
+  const lane = normalizeLaneName(proposal?.lane);
+  const workKey = proposalLaneWorkKey(goalId, lane, proposal);
+  if (!workKey) return false;
+  const proposalAt = String(proposal.at || "");
+  const releasedClaim = state.releasedClaims.some((claim) => claim.workKey === workKey && String(claim.at || "") >= proposalAt);
+  if (!releasedClaim) return false;
+  return state.events.some((event) => ["finding", "handoff", "note"].includes(event.type) && event.workKey === workKey && String(event.at || "") >= proposalAt);
+}
+
+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 detail = [];
+  if (actionable !== total) detail.push(`${actionable} unclaimed actionable`);
+  if (owned) detail.push(`${owned} active-owned`);
+  if (fulfilled) detail.push(`${fulfilled} fulfilled awaiting resolve/defer`);
+  const suffix = detail.length ? ` (${detail.join("; ")})` : "";
+  return `Triage ${total} open proposal${total === 1 ? "" : "s"}${suffix}; claim one, resolve fulfilled work, or defer obsolete/ambiguous items.`;
+}
+
+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";
+  return "unclaimed";
+}
+
+function proposalLaneWorkKey(goalId, lane, proposal = {}) {
+  return proposal.workKey || derivePeerGoalWorkKey({ goalId, lane, objective: proposal.summary, mode: "read", paths: proposal.paths });
+}
+
 async function updatePeerGoalBoard(root, updater) {
   const path = goalBoardPath(root);
   await mkdir(dirname(path), { recursive: true });

package/src/peers/idle-watcher.mjs

@@ -1,4 +1,4 @@
-import { derivePeerGoalScoutSuggestions, loadPeerGoalBoard } from "./goal-board.mjs";
+import { deriveGoalState, derivePeerGoalScoutSuggestions, loadPeerGoalBoard } from "./goal-board.mjs";
 
 export const DEFAULT_PEER_IDLE_WATCHER_INTERVAL_MS = 15_000;
 export const DEFAULT_PEER_IDLE_WATCHER_COOLDOWN_MS = 5 * 60 * 1000;
@@ -119,6 +119,7 @@ export function derivePeerIdleActivation(board, options = {}) {
   const nowMs = Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
   for (const suggestion of suggestions) {
     if (!allowedKinds.has(suggestion.kind)) continue;
+    if (localPeerHasActiveGoalWork(board, suggestion.goalId, options.localPeerId)) continue;
     const activation = normalizeActivation(suggestion, options.localPeerId, options);
     if (!activation || !activationFitsPeer(activation, options)) continue;
     if (isActivationCoolingDown(options.state, activation, config, nowMs)) continue;
@@ -197,6 +198,15 @@ function activationFitsPeer(activation = {}, options = {}) {
   return fit.matched.length > 0;
 }
 
+function localPeerHasActiveGoalWork(board = {}, goalId, localPeerId) {
+  const peerId = cleanString(localPeerId);
+  if (!peerId || !goalId) return false;
+  const goal = board?.goals?.[goalId];
+  if (!goal) return false;
+  const state = deriveGoalState(goal);
+  return state.activeClaims.some((claim) => claim.peerId === peerId);
+}
+
 function peerPersonaFit(suggestion = {}, options = {}) {
   const preferredRoles = normalizeStringList(suggestion.preferredRoles);
   const localTerms = peerProfileTerms(options);