@cryptolibertus/pi-peer 0.3.6 → 0.3.7

package/README.md

@@ -17,6 +17,7 @@ pi install ./packages/pi-peer
 - Local peer discovery and transport using project `.pi/peers.json`
 - Repo-scoped discovery: only Pi sessions in the same git repo/project appear as local peers
 - Idle watcher daemon: idle peers nudge stuck inbound activations and proactively inspect open goal-board work
+- Persona-aware scout routing: goal-board suggestions include recommended lanes, preferred roles, claim mode, and rationale so proactive peers can choose work that fits their role/persona
 - Protocol compatibility metadata (`protocolVersion`, min/max compatible versions), peer manifests, capabilities, and trust summaries in descriptors/status/list output
 - `PI_PEER_ID` runtime override for running multiple local Pi sessions
 - `pi-peer-publish` skill for safe npm release checks, version bumping, tag push, publish, and verification
@@ -57,7 +58,7 @@ 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. `/peer goal fanout` turns a goal into role-specific peer lanes, while `peer_progress` reports checkpoints from an inbound long-running task. Active write claims conflict on overlapping paths; 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. `/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`, `coordination`, etc.), preferred roles, a safe default claim mode, and rationale. Active write claims conflict on overlapping paths; 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`.
 
 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.
 
@@ -66,7 +67,7 @@ Normal goal closure requires at least one current passing vote, no current faile
 When peer messaging is enabled, the extension starts a lightweight in-process idle watcher on `session_start`. It only acts when Pi reports the agent is idle and there are no queued local follow-up messages. The watcher does two things:
 
 1. If an inbound peer task is active but appears not to have triggered a turn, it re-nudges the existing inbound prompt with `triggerTurn: true` using a cooldown.
-2. If no peer task is active, it reads `.pi/peer-goals.json`, derives the same read-only scout suggestions as `/peer scout`, and injects a concise self-prompt so the idle peer can propose, review, claim, vote, or no-op safely.
+2. If no peer task is active, it reads `.pi/peer-goals.json`, derives the same read-only scout suggestions as `/peer scout`, and injects a concise self-prompt so the idle peer can propose, review, claim, vote, or no-op safely. When the local peer has a configured `role` or `persona`, the watcher prefers suggestions whose lane matches that profile and leaves mismatched work for better-fit peers.
 
 Configuration can be placed in `.pi/peers.json` as `idleWatcher` or in `.pi/settings.json` under `peerMessaging.idleWatcher`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cryptolibertus/pi-peer",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "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,15 @@ 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 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." },
+  "failed-vote": { recommendedLane: "coordination", preferredRoles: ["planner", "coordinator", "reviewer"], claimMode: "read", suggestedIntent: "review", rationale: "Failed votes need triage before new implementation work." },
+  "stale-claim": { recommendedLane: "coordination", preferredRoles: ["planner", "coordinator"], claimMode: "read", suggestedIntent: "coordinate", rationale: "Stale claims need owner follow-up or release, not duplicate writes." },
+  "open-proposal": { recommendedLane: "coordination", preferredRoles: ["planner", "coordinator", "reviewer"], claimMode: "read", suggestedIntent: "review", rationale: "Open proposals need triage into accept, defer, or resolve decisions." },
+  close: { recommendedLane: "coordination", preferredRoles: ["planner", "coordinator", "reviewer"], claimMode: "read", suggestedIntent: "coordinate", rationale: "Ready goals need final closure checks and a concise handoff." },
+  "next-step": { recommendedLane: "research", preferredRoles: ["researcher", "reviewer", "planner", "coordinator", "worker"], claimMode: "read", suggestedIntent: "review", rationale: "Empty goals benefit from a read-only lane before write claims." },
+  review: { recommendedLane: "review", preferredRoles: ["reviewer", "qa", "coordinator", "planner"], claimMode: "read", suggestedIntent: "review", rationale: "Goals without current votes need read-only validation before closure." },
+});
 const GOAL_BOARD_LOCK_STALE_MS = 30_000;
 const GOAL_BOARD_LOCK_RETRY_MS = 10;
 const GOAL_BOARD_LOCK_TIMEOUT_MS = 5_000;
@@ -222,7 +231,8 @@ export function formatPeerGoalScout(board, options = {}) {
   const lines = ["# Peer Scout", "", "Proactive suggestions (read-only):"];
   for (const suggestion of suggestions.slice(0, limit)) {
     const pathText = suggestion.paths?.length ? ` · paths: ${suggestion.paths.join(", ")}` : "";
-    lines.push(`- ${suggestion.priority} · ${suggestion.goalId} · ${suggestion.kind}: ${suggestion.summary}${pathText}`);
+    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}`);
   }
   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.");
   return lines.join("\n");
@@ -238,7 +248,7 @@ export function derivePeerGoalScoutSuggestions(board, options = {}) {
   const suggestions = [];
   for (const goal of goals) {
     const state = deriveGoalState(goal);
-    const push = (priority, kind, summary, extra = {}) => suggestions.push(stripEmpty({ goalId: goal.id, priority, kind, summary, ...extra }));
+    const push = (priority, kind, summary, extra = {}) => suggestions.push(enrichScoutSuggestion({ goalId: goal.id, priority, kind, summary, ...extra }));
     if (state.blockingObjections.length) {
       push("P0", "blocker", `Resolve ${state.blockingObjections.length} blocking objection${state.blockingObjections.length === 1 ? "" : "s"} before more work.`, { paths: uniqueEventPaths(state.blockingObjections) });
       continue;
@@ -483,6 +493,19 @@ function uniqueEventPaths(events) {
   return [...new Set(events.flatMap((event) => Array.isArray(event.paths) ? event.paths : []))];
 }
 
+function enrichScoutSuggestion(suggestion = {}) {
+  const lane = SCOUT_LANES[suggestion.kind] || {};
+  return stripEmpty({
+    ...suggestion,
+    recommendedLane: suggestion.recommendedLane || lane.recommendedLane,
+    preferredRoles: normalizeList(suggestion.preferredRoles || lane.preferredRoles),
+    preferredCapabilities: normalizeList(suggestion.preferredCapabilities || lane.preferredCapabilities),
+    claimMode: cleanText(suggestion.claimMode || lane.claimMode),
+    suggestedIntent: cleanText(suggestion.suggestedIntent || lane.suggestedIntent),
+    rationale: cleanText(suggestion.rationale || lane.rationale),
+  });
+}
+
 async function updatePeerGoalBoard(root, updater) {
   const path = goalBoardPath(root);
   await mkdir(dirname(path), { recursive: true });

package/src/peers/idle-watcher.mjs

@@ -62,6 +62,9 @@ export function createPeerIdleWatcher(options = {}) {
       const board = await loadBoard(runtime.cwd || ctx?.cwd || process.cwd());
       const activation = derivePeerIdleActivation(board, {
         localPeerId: runtime.localPeerId,
+        localRole: runtime.config?.localPeerProfile?.role || runtime.localEndpoint?.role,
+        localPersona: runtime.config?.localPeerProfile?.persona || runtime.localEndpoint?.persona,
+        localCapabilities: runtime.localEndpoint?.capabilities || runtime.config?.manifest?.capabilities,
         config,
         state,
         nowMs: now(),
@@ -116,8 +119,8 @@ 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;
-    const activation = normalizeActivation(suggestion, options.localPeerId);
-    if (!activation) continue;
+    const activation = normalizeActivation(suggestion, options.localPeerId, options);
+    if (!activation || !activationFitsPeer(activation, options)) continue;
     if (isActivationCoolingDown(options.state, activation, config, nowMs)) continue;
     return activation;
   }
@@ -135,11 +138,14 @@ export function markPeerIdleActivation(state, activation, nowMs = Date.now()) {
 export function buildPeerIdleActivationPrompt(activation, options = {}) {
   const peerId = options.localPeerId || "this-peer";
   const paths = activation.paths?.length ? `\nPaths: ${activation.paths.join(", ")}` : "";
-  return `[Pi peer idle watcher]\nYou are local peer '${peerId}' and Pi is idle. A proactive goal-board scout suggestion is available.\n\nGoal: ${activation.goalId}\nSuggestion: ${activation.kind} (${activation.priority}) — ${activation.summary}${paths}\n\nInstructions:\n- First inspect current state with peer_get id '${activation.goalId}'.\n- If useful, take one small safe action: post a proposal/finding/vote, claim a read-only review lane, or claim write work only when you intend to edit and can name the paths.\n- Do not duplicate active claims or proposals. If the board is no longer actionable, say so briefly and stop.\n- For write work, respect goal-board claims and end with the required peer handoff sections.\n- Keep the response concise.`;
+  const lane = activation.recommendedLane ? `\nRecommended lane: ${activation.recommendedLane}${activation.claimMode ? ` (${activation.claimMode})` : ""}${activation.preferredRoles?.length ? ` · preferred roles: ${activation.preferredRoles.join(", ")}` : ""}` : "";
+  const rationale = activation.rationale ? `\nRationale: ${activation.rationale}` : "";
+  const fit = activation.personaFit?.matched?.length ? `\nPersona fit: matched ${activation.personaFit.matched.join(", ")}` : "";
+  return `[Pi peer idle watcher]\nYou are local peer '${peerId}' and Pi is idle. A proactive goal-board scout suggestion is available.\n\nGoal: ${activation.goalId}\nSuggestion: ${activation.kind} (${activation.priority}) — ${activation.summary}${lane}${rationale}${fit}${paths}\n\nInstructions:\n- First inspect current state with peer_get id '${activation.goalId}'.\n- If useful, take one small safe action that fits the recommended lane: post a proposal/finding/vote, claim a read-only review lane, or claim write work only when you intend to edit and can name the paths.\n- Do not duplicate active claims or proposals. If the board is no longer actionable, say so briefly and stop.\n- For write work, respect goal-board claims and end with the required peer handoff sections.\n- Keep the response concise.`;
 }
 
 export function peerIdleActivationKey(activation = {}) {
-  return [activation.goalId, activation.kind, activation.summary, ...(activation.paths || [])].join("|");
+  return [activation.goalId, activation.kind, activation.recommendedLane, activation.summary, ...(activation.paths || [])].join("|");
 }
 
 function isActivationCoolingDown(state, activation, config, nowMs) {
@@ -147,18 +153,76 @@ function isActivationCoolingDown(state, activation, config, nowMs) {
   return Number.isFinite(last) && nowMs - last < config.cooldownMs;
 }
 
-function normalizeActivation(suggestion = {}, localPeerId) {
+function normalizeActivation(suggestion = {}, localPeerId, options = {}) {
   if (!suggestion.goalId || !suggestion.kind || !suggestion.summary) return undefined;
+  const personaFit = peerPersonaFit(suggestion, options);
   return {
     goalId: suggestion.goalId,
     priority: suggestion.priority || "P2",
     kind: suggestion.kind,
     summary: suggestion.summary,
+    recommendedLane: cleanString(suggestion.recommendedLane),
+    preferredRoles: normalizeStringList(suggestion.preferredRoles),
+    preferredCapabilities: normalizeStringList(suggestion.preferredCapabilities),
+    claimMode: cleanString(suggestion.claimMode),
+    suggestedIntent: cleanString(suggestion.suggestedIntent),
+    rationale: cleanString(suggestion.rationale),
+    personaFit,
     paths: Array.isArray(suggestion.paths) ? suggestion.paths.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim()) : [],
     peerId: localPeerId,
   };
 }
 
+function activationFitsPeer(activation = {}, options = {}) {
+  const preferred = activation.preferredRoles || [];
+  if (activation.priority === "P0" || !preferred.length) return true;
+  const fit = activation.personaFit || peerPersonaFit(activation, options);
+  if (!fit.hasProfile) return true;
+  return fit.matched.length > 0;
+}
+
+function peerPersonaFit(suggestion = {}, options = {}) {
+  const preferredRoles = normalizeStringList(suggestion.preferredRoles);
+  const localTerms = peerProfileTerms(options);
+  if (!preferredRoles.length) return { hasProfile: localTerms.length > 0, matched: [] };
+  const matched = preferredRoles.filter((role) => localTerms.includes(normalizeRoleToken(role)));
+  return { hasProfile: localTerms.some(isKnownRoleTerm), matched };
+}
+
+function peerProfileTerms(options = {}) {
+  const terms = [options.localRole, options.localPersona, options.localPeerId]
+    .flatMap((value) => String(value || "").toLowerCase().split(/[^a-z0-9]+/g))
+    .map(normalizeRoleToken)
+    .filter(Boolean);
+  const capabilities = options.localCapabilities && typeof options.localCapabilities === "object" ? options.localCapabilities : {};
+  if (Array.isArray(capabilities.roles)) terms.push(...capabilities.roles.map(normalizeRoleToken));
+  return [...new Set(terms)];
+}
+
+function isKnownRoleTerm(value) {
+  return ["planner", "coordinator", "reviewer", "qa", "worker", "researcher"].includes(value);
+}
+
+function normalizeRoleToken(value) {
+  const token = String(value || "").trim().toLowerCase();
+  if (!token) return "";
+  if (/^(reviewer|review|qa|quality)\d*$/.test(token)) return token === "qa" ? "qa" : "reviewer";
+  if (/^(worker|implement|implementation|code|coder|engineer|developer|task)\d*$/.test(token)) return "worker";
+  if (/^(researcher|research|scout)\d*$/.test(token)) return "researcher";
+  if (/^(planner|plan|coordinate|coordinator|orchestrator)\d*$/.test(token)) return token.startsWith("planner") ? "planner" : "coordinator";
+  return token;
+}
+
+function normalizeStringList(value) {
+  if (Array.isArray(value)) return [...new Set(value.map(cleanString).filter(Boolean))];
+  if (typeof value === "string") return [...new Set(value.split(",").map(cleanString).filter(Boolean))];
+  return [];
+}
+
+function cleanString(value) {
+  return typeof value === "string" ? value.trim() : value == null ? "" : String(value).trim();
+}
+
 function isContextIdle(ctx) {
   if (!ctx) return { ok: false, reason: "no active session context" };
   if (typeof ctx.isIdle === "function" && !ctx.isIdle()) return { ok: false, reason: "agent busy" };

package/src/peers/status.mjs

@@ -133,20 +133,44 @@ function capabilitySummary(capabilities = {}) {
 }
 
 export function deriveFanoutSuggestion(peers = [], pendingMessages = []) {
-  const availablePeers = peers
+  const availablePeerDetails = peers
     .filter((peer) => !peer.current && !peer.self && peer.trust !== "disabled")
-    .map((peer) => peer.peerId)
-    .filter(Boolean);
+    .map((peer) => ({
+      peerId: peer.peerId,
+      role: safeStatusText(peer.role),
+      persona: safeStatusText(peer.persona),
+      recommendedLane: recommendLaneForPeer(peer),
+    }))
+    .filter((peer) => peer.peerId);
+  const availablePeers = availablePeerDetails.map((peer) => peer.peerId);
+  const lanes = availablePeerDetails.reduce((groups, peer) => {
+    const lane = peer.recommendedLane || "general";
+    if (!groups[lane]) groups[lane] = [];
+    groups[lane].push(peer.peerId);
+    return groups;
+  }, {});
   const activePeerTasks = pendingMessages.filter((message) => ["queued", "running"].includes(message.status));
   const recommended = availablePeers.length > 0 && activePeerTasks.length === 0;
+  const laneText = Object.entries(lanes).slice(0, 4).map(([lane, ids]) => `${lane}:${ids.slice(0, 3).join("/")}`).join(", ");
   return {
     recommended,
     availablePeers,
+    availablePeerDetails,
+    lanes,
     activePeerTaskCount: activePeerTasks.length,
-    warning: recommended ? `fan-out available for multi-lane work: ${availablePeers.slice(0, 4).join(", ")} — use /peer goal fanout or peer_send` : undefined,
+    warning: recommended ? `fan-out available for multi-lane work: ${availablePeers.slice(0, 4).join(", ")}${laneText ? ` · lanes ${laneText}` : ""} — use /peer goal fanout or peer_send` : undefined,
   };
 }
 
+function recommendLaneForPeer(peer = {}) {
+  const text = [peer.role, peer.persona, peer.peerId].filter(Boolean).join(" ").toLowerCase();
+  if (/(^|[^a-z0-9])(review|reviewer|qa|quality)\d*($|[^a-z0-9])/.test(text)) return "review";
+  if (/(^|[^a-z0-9])(research|researcher|scout)\d*($|[^a-z0-9])/.test(text)) return "research";
+  if (/(^|[^a-z0-9])(plan|planner|coord|coordinator|orchestrator)\d*($|[^a-z0-9])/.test(text)) return "coordination";
+  if (/(^|[^a-z0-9])(worker|implement|implementation|engineer|developer|code|coder|task)\d*($|[^a-z0-9])/.test(text)) return "implementation";
+  return "general";
+}
+
 function line(kind, color, text) {
   return { kind, color, text };
 }