@cryptolibertus/pi-peer 0.4.1 → 0.5.1

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. Empty goals now 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`) also become matching scout suggestions, letting the next suitable peer claim or review that proposed lane. 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. 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, 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.4.1",
+  "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/command.mjs

@@ -146,7 +146,7 @@ export function formatPeerHelp() {
     "- `/peer goal create <objective> [--constraint <a,b>]` — start a flat shared goal board",
     "- `/peer goal list|show [goal-id]` — inspect peer goals, active claims, blockers, proposals, and votes",
     "- `/peer goal fanout <goal-id> <objective> --peer <id[,id]> [--path <a,b>] [--send] [--no-await]` — plan or dispatch role-specific peer lanes",
-    "- `/peer goal scout [goal-id] [--limit <n>] [--include-closed]` — read-only proactive suggestions for what peers could do next",
+    "- `/peer goal scout [goal-id] [--limit <n>] [--include-closed]` — read-only proactive suggestions with exact work keys and copyable claim commands for what peers could do next",
     "- `/peer goal task|finding|proposal|handoff|note <goal-id> <summary> [--path <a,b>] [--lane research|review|implementation] [--status done]` — post goal-board events; lane-tagged proposals become scout suggestions peers can self-select",
     "- `/peer goal claim <goal-id> <task> --mode read|write --path <a,b> [--key <work-key>] [--duplicate-policy error|allow-parallel] [--ttl-ms <ms>]` — lease work without hierarchy",
     "- `/peer goal heartbeat <goal-id> <claim-event-id> [summary] [--ttl-ms <ms>] [--stale-after-ms <ms>]` — refresh a live or stale claim",

package/src/peers/goal-board.mjs

@@ -248,7 +248,7 @@ export function deriveGoalState(goal, options = {}) {
   const failedVotes = currentVotes.filter((vote) => vote.verdict === "fail");
   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(projectEventSummary);
+  const tasks = events.filter((event) => event.type === "task").map((event) => projectTaskSummary(event, events));
   return {
     ...goal,
     events,
@@ -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,
   };
 }
 
@@ -291,9 +291,12 @@ export function formatPeerGoalScout(board, options = {}) {
   for (const suggestion of suggestions.slice(0, limit)) {
     const pathText = suggestion.paths?.length ? ` · paths: ${suggestion.paths.join(", ")}` : "";
     const laneText = suggestion.recommendedLane ? ` · lane: ${suggestion.recommendedLane}${suggestion.preferredRoles?.length ? ` for ${suggestion.preferredRoles.join("/")}` : ""}${suggestion.claimMode ? ` (${suggestion.claimMode})` : ""}` : "";
-    lines.push(`- ${suggestion.priority} · ${suggestion.goalId} · ${suggestion.kind}: ${suggestion.summary}${laneText}${pathText}`);
+    const keyText = suggestion.workKey ? ` · key: ${suggestion.workKey}` : "";
+    lines.push(`- ${suggestion.priority} · ${suggestion.goalId} · ${suggestion.kind}: ${suggestion.summary}${laneText}${pathText}${keyText}`);
+    const claim = formatScoutClaimCommand(suggestion);
+    if (claim) lines.push(`  claim: ${claim}`);
   }
-  lines.push("", "Next: post one with `/peer goal propose <goal-id> <summary>` or claim safe work with `/peer goal claim <goal-id> <task> --mode read|write --path <path>`. Scout does not mutate the board.");
+  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");
 }
 
@@ -323,20 +326,39 @@ 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", `Self-select proposed ${lane} lane: ${proposal.summary}`, {
+        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, {
           paths: proposal.paths,
           recommendedLane: lane,
           preferredRoles: preferredRolesForLane(lane),
           claimMode: "read",
           suggestedIntent: suggestedIntentForLane(lane),
           rationale: "A peer proposed a lane; matching idle peers can claim or review it without planner assignment.",
+          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;
     }
@@ -350,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.");
     }
   }
@@ -559,6 +581,26 @@ function projectEventSummary(event) {
   });
 }
 
+function projectTaskSummary(task, events) {
+  const handoff = latestEvent(events.filter((event) => taskMatchesHandoff(task, event, events)));
+  const projected = projectEventSummary(task);
+  if (!handoff) return projected;
+  return stripEmpty({
+    ...projected,
+    status: handoff.status || "done",
+    completedAt: handoff.at,
+    handoffEventId: handoff.id,
+  });
+}
+
+function taskMatchesHandoff(task, event, events) {
+  if (event.type !== "handoff" || event.at < task.at) return false;
+  if (task.taskId && event.taskId === task.taskId) return true;
+  if (event.taskId === task.id) return true;
+  if (task.taskId || event.taskId || !task.workKey || event.workKey !== task.workKey) return false;
+  return events.filter((item) => item.type === "task" && item.workKey === task.workKey).length === 1;
+}
+
 function projectClaimSummary(claim, events, now) {
   const heartbeat = latestEvent(events.filter((event) => event.type === "heartbeat" && event.resolves === claim.id));
   const lastHeartbeatAt = heartbeat?.at;
@@ -625,13 +667,27 @@ function enrichScoutSuggestion(suggestion = {}) {
     claimMode,
     suggestedIntent: cleanText(suggestion.suggestedIntent || lane.suggestedIntent),
     rationale: cleanText(suggestion.rationale || lane.rationale),
+    relatedEventId: cleanText(suggestion.relatedEventId),
   });
   return stripEmpty({
     ...enriched,
-    workKey: suggestion.workKey || derivePeerGoalWorkKey({ goalId: enriched.goalId, lane: recommendedLane, objective: enriched.summary, mode: claimMode, paths: enriched.paths }),
+    workKey: normalizeWorkKey(suggestion.workKey) || derivePeerGoalWorkKey({ goalId: enriched.goalId, lane: recommendedLane, objective: enriched.summary, mode: claimMode, paths: enriched.paths }),
   });
 }
 
+function formatScoutClaimCommand(suggestion = {}) {
+  if (suggestion.claimMode !== "read" || !suggestion.workKey || !suggestion.goalId || !suggestion.summary) return "";
+  const lane = suggestion.recommendedLane ? ` --lane ${shellQuote(suggestion.recommendedLane)}` : "";
+  const paths = suggestion.paths?.length ? suggestion.paths.map((path) => ` --path ${shellQuote(path)}`).join("") : "";
+  return `/peer goal claim ${shellQuote(suggestion.goalId)} ${shellQuote(suggestion.summary)} --mode read${lane} --key ${shellQuote(suggestion.workKey)}${paths}`;
+}
+
+function shellQuote(value) {
+  const text = String(value || "");
+  if (/^[A-Za-z0-9_./:-]+$/.test(text)) return text;
+  return `'${text.replace(/'/g, `'"'"'`)}'`;
+}
+
 function normalizeLaneName(value) {
   const lane = cleanText(value).toLowerCase();
   if (["qa", "quality", "test", "testing"].includes(lane)) return "review";
@@ -658,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);