@cryptolibertus/pi-peer 0.3.6 → 0.4.0

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
@@ -40,14 +41,14 @@ pi install ./packages/pi-peer
 Useful commands (long form and short aliases):
 
 ```bash
-/peer goal create "Improve finalization safety" --constraint "one writer per path,no destructive commands"
+/peer goal create "Improve finalization safety" --constraint "one writer per path,no duplicate work,no destructive commands"
 /peer goal fanout <goal-id> "Fix PR waiting path" --peer researcher,reviewer,worker --path extensions/symphony/index.ts,test/pr-watcher-runtime.test.mjs --send --no-await
 /peer send worker "Fix PR waiting path" --goal <goal-id> --claim extensions/symphony/index.ts,test/pr-watcher-runtime.test.mjs --no-await
 /peer progress "tests are running" --phase verification
 /peer goal finding <goal-id> "PR auto-close can close before merge" --path extensions/symphony/index.ts
 /peer scout <goal-id> --limit 5
 /peer goal propose <goal-id> "Add a read-only reviewer before closing" --path extensions/symphony/index.ts
-/peer goal claim <goal-id> "Fix PR waiting path" --mode write --path extensions/symphony/index.ts,test/pr-watcher-runtime.test.mjs
+/peer goal claim <goal-id> "Fix PR waiting path" --mode write --path extensions/symphony/index.ts,test/pr-watcher-runtime.test.mjs --key implement:pr-waiting
 /peer goal heartbeat <goal-id> <claim-event-id> "still working after reconnect" --stale-after-ms 900000
 /peer goal release <goal-id> <claim-event-id> "worker lane complete"
 /peer goal object <goal-id> "Missing merged-PR 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. 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`, `coordination`, etc.), preferred roles, a safe default claim mode, rationale, and suppress suggestions already covered by active work keys. 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`.
 
 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/extensions/pi-peer/index.ts

@@ -101,7 +101,10 @@ export default function piPeerExtension(pi: ExtensionAPI) {
       metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
       claimedPaths: Type.Optional(Type.Array(Type.String({ description: "Paths this peer task is expected to own while running" }))),
       goalId: Type.Optional(Type.String({ description: "Peer goal id to link this long-running task to" })),
-      goalClaimMode: Type.Optional(Type.String({ description: "Goal-board claim mode for claimedPaths; defaults to write" })),
+      goalClaimMode: Type.Optional(Type.String({ description: "Goal-board claim mode; defaults to write when paths are supplied, otherwise read" })),
+      workKey: Type.Optional(Type.String({ description: "Semantic work fingerprint for idempotent peer dispatch" })),
+      workLane: Type.Optional(Type.String({ description: "Semantic work lane, e.g. research, review, coordination, or implementation" })),
+      duplicatePolicy: Type.Optional(Type.String({ description: "Duplicate work policy: reuse (default), error, or allow-parallel" })),
       goalStaleAfterMs: Type.Optional(Type.Number({ description: "Milliseconds before this goal claim is considered stale without heartbeat" })),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -109,16 +112,24 @@ export default function piPeerExtension(pi: ExtensionAPI) {
       attachPeerUi(runtime, () => activeContext, (current: any) => refreshPeerUi(current, runtime));
       ensureEnabled(runtime);
       await runtime.refreshLocalPeers();
-      const metadata = mergePeerMetadata(params.metadata, params.claimedPaths, params.goalId);
+      const metadata = mergePeerMetadata(params.metadata, params.claimedPaths, params.goalId, { workKey: params.workKey, workLane: params.workLane, duplicatePolicy: params.duplicatePolicy });
       const goalLink = await beginPeerSendGoalLink(ctx?.cwd, runtime, {
         goalId: params.goalId,
         targetPeerId: params.peer,
         prompt: params.prompt,
         claimedPaths: metadata.claimedPaths,
         claimMode: params.goalClaimMode,
+        workKey: metadata.workKey,
+        workLane: metadata.workLane,
+        duplicatePolicy: metadata.duplicatePolicy,
         staleAfterMs: params.goalStaleAfterMs,
       });
+      if (goalLink?.duplicate) {
+        await refreshPeerUi(ctx, runtime);
+        return duplicatePeerSendToolResult(goalLink);
+      }
       if (goalLink?.claimEvent?.id) metadata.goalClaimId = goalLink.claimEvent.id;
+      if (goalLink?.workKey) metadata.workKey = goalLink.workKey;
       let handle: any;
       try {
         handle = await runtime.comms.sendMessage(params.peer, {
@@ -323,9 +334,17 @@ async function handlePeerCommand(pi: ExtensionAPI, rawArgs: string, ctx: any, re
         prompt: parsed.prompt,
         claimedPaths: parsed.claimedPaths,
         claimMode: parsed.goalClaimMode,
+        workKey: parsed.workKey,
+        workLane: parsed.workLane,
+        duplicatePolicy: parsed.duplicatePolicy,
         staleAfterMs: parsed.goalStaleAfterMs,
       });
+      if (goalLink?.duplicate) {
+        await refresh();
+        return sendPeerMessage(pi, formatDuplicatePeerSend(goalLink));
+      }
       if (goalLink?.claimEvent?.id) metadata.goalClaimId = goalLink.claimEvent.id;
+      if (goalLink?.workKey) metadata.workKey = goalLink.workKey;
       let handle: any;
       try {
         handle = await runtime.comms.sendMessage(parsed.peerId, { prompt: withPeerGoalInstructions(parsed.prompt, goalLink), intent: parsed.intent, metadata }, { maxHopCount: parsed.maxHopCount, allowSelf: parsed.allowSelf });
@@ -425,6 +444,9 @@ async function handlePeerGoalCommand(parsed: any, ctx: any, runtime: any) {
       paths: parsed.paths,
       taskId: parsed.taskId,
       status: parsed.status,
+      workKey: parsed.workKey,
+      lane: parsed.workLane,
+      duplicatePolicy: parsed.duplicatePolicy,
     });
     return `Posted ${result.event.type} ${result.event.id} to ${result.goal.id}.\n\n${formatPeerGoal(result.goal)}`;
   }
@@ -435,6 +457,9 @@ async function handlePeerGoalCommand(parsed: any, ctx: any, runtime: any) {
       summary: parsed.summary,
       paths: parsed.paths,
       mode: parsed.mode,
+      lane: parsed.workLane,
+      workKey: parsed.workKey,
+      duplicatePolicy: parsed.duplicatePolicy,
       ttlMs: parsed.ttlMs,
       staleAfterMs: parsed.staleAfterMs,
     });
@@ -505,6 +530,7 @@ async function handlePeerGoalFanout(parsed: any, ctx: any, runtime: any, peerId:
   const planned = [];
   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",
@@ -512,9 +538,9 @@ async function handlePeerGoalFanout(parsed: any, ctx: any, runtime: any, peerId:
       summary,
       paths: parsed.paths,
       status: parsed.send ? "dispatching" : "planned",
-      metadata: { targetPeerId, fanout: true, claimMode: mode },
+      metadata: { targetPeerId, fanout: true, claimMode: mode, workLane: lane },
     });
-    planned.push({ peerId: targetPeerId, taskEventId: task.event.id, mode });
+    planned.push({ peerId: targetPeerId, taskEventId: task.event.id, mode, lane });
   }
   if (parsed.send) {
     await Promise.all(planned.map(async (item: any) => {
@@ -526,12 +552,31 @@ async function handlePeerGoalFanout(parsed: any, ctx: any, runtime: any, peerId:
           prompt: parsed.objective,
           claimedPaths: parsed.paths,
           claimMode: item.mode,
+          workLane: item.lane,
+          duplicatePolicy: "reuse",
           staleAfterMs: parsed.staleAfterMs,
         });
-        const metadata = mergePeerMetadata({ fanout: true }, parsed.paths, parsed.goalId);
+        if (goalLink?.duplicate) {
+          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(() => {});
+          return;
+        }
+        const metadata = mergePeerMetadata({ fanout: true }, parsed.paths, parsed.goalId, { workKey: goalLink?.workKey, workLane: item.lane, duplicatePolicy: "reuse" });
         if (goalLink?.claimEvent?.id) metadata.goalClaimId = goalLink.claimEvent.id;
         const handle = await runtime.comms.sendMessage(item.peerId, {
-          prompt: withPeerGoalInstructions(buildFanoutPrompt(parsed.objective, item.peerId, item.mode), goalLink),
+          prompt: withPeerGoalInstructions(buildFanoutPrompt(parsed.objective, item.peerId, item.mode, item.lane), goalLink),
           intent: item.mode === "write" ? "task" : "review",
           metadata,
         });
@@ -569,7 +614,7 @@ async function handlePeerGoalFanout(parsed: any, ctx: any, runtime: any, peerId:
   }
   const lines = [`Fan-out ${parsed.send ? "dispatched" : "planned"} for ${parsed.goalId}: ${parsed.objective}`];
   for (const item of planned) {
-    lines.push(`- ${item.peerId} · ${item.mode}${item.messageId ? ` · ${item.messageId}` : ""}${item.error ? ` · ${item.error.code}` : ""}`);
+    lines.push(`- ${item.peerId} · ${item.lane}/${item.mode}${item.duplicate ? " · duplicate reused" : ""}${item.messageId ? ` · ${item.messageId}` : ""}${item.error ? ` · ${item.error.code}` : ""}`);
   }
   lines.push("", "Final-answer checklist: include Fan-out used: yes, peer ids, message ids, blockers, and verification.");
   return lines.join("\n");
@@ -630,24 +675,56 @@ function sendPeerMessage(pi: ExtensionAPI, content: string) {
   pi.sendMessage({ customType: MESSAGE_TYPE, content, display: true });
 }
 
-function mergePeerMetadata(metadata: any, claimedPaths: unknown, goalId?: unknown) {
-  const base = metadata && typeof metadata === "object" && !Array.isArray(metadata) ? { ...metadata } : {};
+function mergePeerMetadata(metadata: any, claimedPaths: unknown, goalId?: unknown, work: any = {}) {
+  const base: any = metadata && typeof metadata === "object" && !Array.isArray(metadata) ? { ...metadata } : {};
   if (Array.isArray(claimedPaths)) {
     const paths = [...new Set(claimedPaths.filter((item): item is string => typeof item === "string" && item.trim()).map((item) => item.trim()))];
     if (paths.length) base.claimedPaths = paths;
   }
   if (typeof goalId === "string" && goalId.trim()) base.goalId = goalId.trim();
+  for (const [key, value] of Object.entries(work || {})) {
+    if (typeof value === "string" && value.trim()) base[key] = value.trim();
+  }
   return base;
 }
 
+function duplicatePeerSendToolResult(goalLink: any) {
+  return {
+    content: [{ type: "text", text: formatDuplicatePeerSend(goalLink) }],
+    details: { ok: true, kind: "peer_send_duplicate", duplicate: true, ...duplicatePeerSendDetails(goalLink) },
+  };
+}
+
+function formatDuplicatePeerSend(goalLink: any) {
+  const details = duplicatePeerSendDetails(goalLink);
+  const task = details.messageId ? ` Existing message: ${details.messageId}${details.conversationId ? ` in ${details.conversationId}` : ""}.` : "";
+  return `Duplicate peer work reused for ${details.goalId}: active claim ${details.claimId || "unknown"} already owns work key ${details.workKey || "unknown"}.${task}`;
+}
+
+function duplicatePeerSendDetails(goalLink: any) {
+  return {
+    goalId: goalLink?.goalId,
+    workKey: goalLink?.workKey,
+    claimId: goalLink?.existingClaim?.id,
+    claimPeerId: goalLink?.existingClaim?.peerId,
+    messageId: goalLink?.existingTask?.taskId || goalLink?.existingTask?.metadata?.messageId,
+    conversationId: goalLink?.existingTask?.metadata?.conversationId,
+  };
+}
+
 async function beginPeerSendGoalLink(root: string | undefined, runtime: any, options: any) {
   if (!options?.goalId) return undefined;
+  const paths = Array.isArray(options.claimedPaths) ? options.claimedPaths : [];
+  const mode = options.claimMode || (paths.length ? "write" : "read");
   return beginPeerGoalTask(root || process.cwd(), options.goalId, {
     requesterPeerId: runtime?.localPeerId || runtime?.summary?.localPeerId || "unknown",
     targetPeerId: options.targetPeerId,
     prompt: options.prompt,
-    claimedPaths: options.claimedPaths,
-    mode: options.claimMode || "write",
+    claimedPaths: paths,
+    mode,
+    lane: options.workLane || mode,
+    workKey: options.workKey,
+    duplicatePolicy: options.duplicatePolicy || "reuse",
     staleAfterMs: options.staleAfterMs,
   });
 }
@@ -662,6 +739,10 @@ async function recordPeerSendGoalDispatch(root: string | undefined, runtime: any
     messageId: handle.messageId,
     conversationId: handle.conversationId,
     claimEventId: goalLink.claimEvent?.id,
+    workKey: goalLink.workKey,
+    mode: goalLink.claimEvent?.mode,
+    lane: goalLink.claimEvent?.lane,
+    duplicatePolicy: goalLink.duplicatePolicy,
   });
 }
 
@@ -676,6 +757,9 @@ async function recordPeerSendGoalFailure(root: string | undefined, goalLink: any
     responseStatus: "DISPATCH_ERROR",
     summary: `DISPATCH_ERROR: ${options.error?.message || String(options.error || "peer send failed")}`,
     releaseSummary: "Peer message dispatch failed before delivery",
+    workKey: goalLink.workKey,
+    mode: goalLink.claimEvent?.mode,
+    lane: goalLink.claimEvent?.lane,
   }).catch(() => {});
 }
 
@@ -695,6 +779,9 @@ function trackPeerSendGoalCompletion(root: string | undefined, goalLink: any, ha
       responseStatus: response?.status,
       summary: summarizePeerGoalResponse(response),
       releaseSummary: `Peer message ${handle.messageId} completed with ${response?.status || "unknown"}`,
+      workKey: goalLink.workKey,
+      mode: goalLink.claimEvent?.mode,
+      lane: goalLink.claimEvent?.lane,
     });
     const missing = missingHandoffFields(response);
     if (missing.length) {
@@ -739,7 +826,9 @@ function withPeerGoalInstructions(prompt: string, goalLink: any) {
   const lines = [
     `Peer goal context:`,
     `- goalId: ${goalLink.goalId}`,
+    ...(goalLink.workKey ? [`- workKey: ${goalLink.workKey}`] : []),
     ...(goalLink.claimEvent?.id ? [`- claimEventId: ${goalLink.claimEvent.id}`, `- If this takes a while, send heartbeats with /peer goal heartbeat ${goalLink.goalId} ${goalLink.claimEvent.id} "still working".`] : []),
+    `- Before starting, inspect the goal board and stop if another active claim already owns the same work key.`,
     `- End with a concise handoff: status, files changed, verification, blockers.`,
     ``,
     `Original prompt:`,
@@ -753,8 +842,16 @@ function inferFanoutClaimMode(peerId: string) {
   return id.includes("worker") || id.includes("implement") ? "write" : "read";
 }
 
-function buildFanoutPrompt(objective: string, peerId: string, mode: string) {
-  const role = mode === "write" ? "implementation lane" : "read-only research/review lane";
+function inferFanoutWorkLane(peerId: string, mode: string) {
+  const id = String(peerId || "").toLowerCase();
+  if (id.includes("research") || id.includes("scout")) return "research";
+  if (id.includes("review") || id.includes("qa")) return "review";
+  if (id.includes("coordinator") || id.includes("planner")) return "coordination";
+  return mode === "write" ? "implementation" : "review";
+}
+
+function buildFanoutPrompt(objective: string, peerId: string, mode: string, lane: string) {
+  const role = mode === "write" ? `${lane} implementation lane` : `read-only ${lane} lane`;
   return `${objective}\n\nFan-out role for ${peerId}: ${role}. Stay within that lane. Report progress with peer_progress when work is long-running, and end with the required final handoff.`;
 }
 

package/package.json

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

@@ -65,10 +65,13 @@ export function parsePeerCommand(rawArgs = "") {
       maxHopCount: positiveIntegerFlag(flags.maxHopCount),
       allowSelf: flagEnabled(flags.allowSelf),
       goalId,
-      goalClaimMode: stringFlag(flags.claimMode, "write"),
+      goalClaimMode: stringFlag(flags.claimMode, undefined),
       goalStaleAfterMs: positiveIntegerFlag(flags.staleAfterMs),
+      workKey: stringFlag(flags.workKey || flags.key, undefined),
+      workLane: stringFlag(flags.workLane || flags.lane, undefined),
+      duplicatePolicy: stringFlag(flags.duplicatePolicy, undefined),
       claimedPaths,
-      metadata: metadataFromFlags(flags, { goalId, claimedPaths }),
+      metadata: metadataFromFlags(flags, { goalId, claimedPaths, workKey: stringFlag(flags.workKey || flags.key, undefined), workLane: stringFlag(flags.workLane || flags.lane, undefined), duplicatePolicy: stringFlag(flags.duplicatePolicy, undefined) }),
     };
   }
   if (subcommand === "goal") {
@@ -137,7 +140,7 @@ export function formatPeerHelp() {
     "- `/peer reconnect` — refresh local discovery and show current status",
     "- `/peer resume <message-id>` — resume a disconnected restored peer message after reconnect",
     "- `/peer cancel <message-id> [reason]` — mark a queued/running/disconnected peer message cancelled",
-    "- `/peer send <peer> <prompt> [--no-await] [--intent ask] [--goal <goal-id>] [--claim <path[,path]>] [--timeout-ms <ms>] [--allow-self]` — send a prompt-first peer message",
+    "- `/peer send <peer> <prompt> [--no-await] [--intent ask] [--goal <goal-id>] [--claim <path[,path]>] [--key <work-key>] [--duplicate-policy reuse|error|allow-parallel]` — send a prompt-first peer message",
     "- `/peer progress <summary> [--status running] [--phase <name>]` — send a structured checkpoint from an inbound long-running peer task",
     "- `/peer goals|ls`, `/peer current [goal-id]`, `/peer scout [goal-id]`, `/peer fanout`, `/peer propose`, `/peer take|claim`, `/peer complete|done`, `/peer objection|block`, `/peer unblock`, `/peer ping`, `/peer drop`, `/peer pass|fail` — short goal-board aliases",
     "- `/peer goal create <objective> [--constraint <a,b>]` — start a flat shared goal board",
@@ -145,7 +148,7 @@ export function formatPeerHelp() {
     "- `/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 task|finding|proposal|handoff|note <goal-id> <summary> [--path <a,b>] [--status done]` — post goal-board events",
-    "- `/peer goal claim <goal-id> <task> --mode write --path <a,b> [--ttl-ms <ms>] [--stale-after-ms <ms>]` — lease work without hierarchy",
+    "- `/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",
     "- `/peer goal release <goal-id> <claim-event-id> [summary]` — release a claimed lane",
     "- `/peer goal object <goal-id> <reason> [--path <a,b>]`, `/peer goal resolve <goal-id> <event-id> <summary>`, `/peer goal vote <goal-id> <pass|fail|pass-with-risks> [summary]`",
@@ -198,14 +201,14 @@ function parsePeerGoalCommand(parsed, flags, positionals) {
     const goalId = rest[0];
     const summary = rest.slice(1).join(" ").trim();
     if (!goalId || !summary) return { ...withAction, error: `/peer goal ${action} requires <goal-id> <summary>` };
-    return { ...withAction, goalId, eventType: action === "propose" ? "proposal" : action, summary, paths: listFlag(flags.path || flags.paths), severity: stringFlag(flags.severity, undefined), taskId: stringFlag(flags.taskId, undefined), status: stringFlag(flags.status, undefined) };
+    return { ...withAction, goalId, eventType: action === "propose" ? "proposal" : action, summary, paths: listFlag(flags.path || flags.paths), severity: stringFlag(flags.severity, undefined), taskId: stringFlag(flags.taskId, undefined), status: stringFlag(flags.status, undefined), workKey: stringFlag(flags.workKey || flags.key, undefined), workLane: stringFlag(flags.workLane || flags.lane, undefined), duplicatePolicy: stringFlag(flags.duplicatePolicy, undefined) };
   }
   if (action === "claim") {
     if (flagEnabled(flags.write) && flags.mode === undefined) flags.mode = "write";
     const goalId = rest[0];
     const summary = rest.slice(1).join(" ").trim();
     if (!goalId || !summary) return { ...withAction, error: "/peer goal claim requires <goal-id> <task>" };
-    return { ...withAction, goalId, summary, paths: listFlag(flags.path || flags.paths), mode: stringFlag(flags.mode, "read"), ttlMs: positiveIntegerFlag(flags.ttlMs), staleAfterMs: positiveIntegerFlag(flags.staleAfterMs) };
+    return { ...withAction, goalId, summary, paths: listFlag(flags.path || flags.paths), mode: stringFlag(flags.mode, "read"), workKey: stringFlag(flags.workKey || flags.key, undefined), workLane: stringFlag(flags.workLane || flags.lane, undefined), duplicatePolicy: stringFlag(flags.duplicatePolicy, undefined), ttlMs: positiveIntegerFlag(flags.ttlMs), staleAfterMs: positiveIntegerFlag(flags.staleAfterMs) };
   }
   if (action === "heartbeat") {
     const goalId = rest[0];
@@ -266,9 +269,15 @@ function positiveIntegerFlag(value) {
 function metadataFromFlags(flags = {}, options = {}) {
   const claimedPaths = options.claimedPaths || claimedPathsFlag(flags.claim || flags.claimedPath || flags.claimedPaths);
   const goalId = options.goalId || stringFlag(flags.goal || flags.goalId, undefined);
+  const workKey = options.workKey || stringFlag(flags.workKey || flags.key, undefined);
+  const workLane = options.workLane || stringFlag(flags.workLane || flags.lane, undefined);
+  const duplicatePolicy = options.duplicatePolicy || stringFlag(flags.duplicatePolicy, undefined);
   return {
     ...(claimedPaths.length ? { claimedPaths } : {}),
     ...(goalId ? { goalId } : {}),
+    ...(workKey ? { workKey } : {}),
+    ...(workLane ? { workLane } : {}),
+    ...(duplicatePolicy ? { duplicatePolicy } : {}),
   };
 }
 

package/src/peers/goal-board.mjs

@@ -8,7 +8,17 @@ export const PEER_GOAL_BOARD_RELATIVE_PATH = ".pi/peer-goals.json";
 const EVENT_TYPES = new Set(["finding", "task", "proposal", "claim", "release", "heartbeat", "objection", "resolve", "vote", "handoff", "note"]);
 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 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;
@@ -96,26 +106,61 @@ export async function closePeerGoal(root, goalId, input = {}) {
 
 export async function beginPeerGoalTask(root, goalId, input = {}) {
   const id = requiredGoalId(goalId || input.goalId);
-  const board = await loadPeerGoalBoard(root);
-  if (!board.goals[id]) throw new Error(`peer goal ${id} not found`);
-  const paths = normalizePaths(input.claimedPaths || input.paths);
-  if (!paths.length) return { goalId: id, goal: deriveGoalState(board.goals[id]) };
+  return updatePeerGoalBoard(root, (board) => {
+    const goal = resolveGoal(board, id);
+    const paths = normalizePaths(input.claimedPaths || input.paths);
+    const mode = cleanText(input.mode || input.claimMode || (paths.length ? "write" : "read")).toLowerCase();
+    const lane = cleanText(input.lane || input.workLane || input.intent || mode).toLowerCase();
+    const workKey = normalizeWorkKey(input.workKey) || derivePeerGoalWorkKey({
+      goalId: id,
+      lane,
+      objective: input.objective || input.summary || input.prompt,
+      mode,
+      paths,
+    });
+    if (!paths.length && !workKey) return { goalId: id, goal: deriveGoalState(goal) };
+
+    const duplicatePolicy = normalizeDuplicatePolicy(input.duplicatePolicy) || "reuse";
+    if (workKey && duplicatePolicy === "reuse") {
+      const state = deriveGoalState(goal);
+      const existingClaim = state.activeClaims.find((claim) => claim.workKey === workKey);
+      if (existingClaim) {
+        return {
+          goalId: id,
+          goal: state,
+          duplicate: true,
+          duplicatePolicy,
+          workKey,
+          existingClaim,
+          existingTask: latestTaskForWorkKey(state.tasks, workKey),
+        };
+      }
+    }
 
-  const result = await appendPeerGoalEvent(root, id, {
-    type: "claim",
-    peerId: cleanText(input.targetPeerId || input.peerId) || "unknown",
-    summary: taskSummary(input),
-    paths,
-    mode: cleanText(input.mode || input.claimMode || "write").toLowerCase(),
-    ttlMs: input.ttlMs,
-    staleAfterMs: input.staleAfterMs,
-    metadata: stripEmpty({ requesterPeerId: cleanText(input.requesterPeerId), targetPeerId: cleanText(input.targetPeerId) }),
+    const event = normalizeEvent({
+      type: "claim",
+      peerId: cleanText(input.targetPeerId || input.peerId) || "unknown",
+      summary: taskSummary(input),
+      paths,
+      mode,
+      lane,
+      workKey,
+      duplicatePolicy,
+      ttlMs: input.ttlMs,
+      staleAfterMs: input.staleAfterMs,
+      metadata: stripEmpty({ requesterPeerId: cleanText(input.requesterPeerId), targetPeerId: cleanText(input.targetPeerId), workKey, lane, duplicatePolicy }),
+    });
+    validateClaim(goal, event);
+    goal.events.push(event);
+    goal.updatedAt = event.at;
+    board.currentGoalId = goal.id;
+    return { goalId: id, goal: deriveGoalState(goal), claimEvent: event, workKey, duplicatePolicy };
   });
-  return { goalId: id, goal: result.goal, claimEvent: result.event };
 }
 
 export async function recordPeerGoalTaskDispatch(root, goalId, input = {}) {
   const id = requiredGoalId(goalId || input.goalId);
+  const workKey = normalizeWorkKey(input.workKey) || derivePeerGoalWorkKey({ goalId: id, lane: input.lane || input.workLane || input.intent || input.mode, objective: input.objective || input.summary || input.prompt, mode: input.mode || input.claimMode, paths: input.claimedPaths || input.paths });
   const result = await appendPeerGoalEvent(root, id, {
     type: "task",
     peerId: cleanText(input.requesterPeerId || input.peerId) || "unknown",
@@ -123,11 +168,15 @@ export async function recordPeerGoalTaskDispatch(root, goalId, input = {}) {
     paths: input.claimedPaths || input.paths,
     taskId: input.messageId,
     status: cleanText(input.status || "running"),
+    workKey,
+    lane: input.lane || input.workLane,
+    duplicatePolicy: input.duplicatePolicy,
     metadata: stripEmpty({
       messageId: cleanText(input.messageId),
       conversationId: cleanText(input.conversationId),
       targetPeerId: cleanText(input.targetPeerId),
       claimEventId: cleanText(input.claimEventId),
+      workKey,
     }),
   });
   return { goalId: id, goal: result.goal, taskEvent: result.event };
@@ -135,6 +184,7 @@ export async function recordPeerGoalTaskDispatch(root, goalId, input = {}) {
 
 export async function completePeerGoalTask(root, goalId, input = {}) {
   const id = requiredGoalId(goalId || input.goalId);
+  const workKey = normalizeWorkKey(input.workKey) || derivePeerGoalWorkKey({ goalId: id, lane: input.lane || input.workLane || input.intent || input.mode, objective: input.objective || input.summary || input.prompt, mode: input.mode || input.claimMode, paths: input.claimedPaths || input.paths });
   const handoff = await appendPeerGoalEvent(root, id, {
     type: "handoff",
     peerId: cleanText(input.targetPeerId || input.peerId) || "unknown",
@@ -142,11 +192,14 @@ export async function completePeerGoalTask(root, goalId, input = {}) {
     paths: input.claimedPaths || input.paths,
     taskId: input.messageId,
     status: cleanText(input.status || "done"),
+    workKey,
+    lane: input.lane || input.workLane,
     metadata: stripEmpty({
       messageId: cleanText(input.messageId),
       conversationId: cleanText(input.conversationId),
       claimEventId: cleanText(input.claimEventId),
       responseStatus: cleanText(input.responseStatus),
+      workKey,
     }),
   });
   if (!input.claimEventId) return { goalId: id, goal: handoff.goal, handoffEvent: handoff.event };
@@ -159,6 +212,16 @@ export async function completePeerGoalTask(root, goalId, input = {}) {
   return { goalId: id, goal: release.goal, handoffEvent: handoff.event, releaseEvent: release.event };
 }
 
+export function derivePeerGoalWorkKey(input = {}) {
+  const goalId = normalizeWorkKeyPart(input.goalId);
+  const lane = normalizeWorkKeyPart(input.lane || input.workLane || input.intent || "work");
+  const objective = normalizeWorkKeyPart(input.objective || input.summary || input.prompt || "work");
+  const mode = normalizeWorkKeyPart(input.mode || input.claimMode || "read");
+  const paths = normalizePaths(input.paths || input.claimedPaths).map(normalizeWorkKeyPart).sort();
+  const parts = [goalId, lane, objective, mode, paths.join(",")].filter((part) => part !== undefined && part !== "");
+  return parts.length ? parts.join("|") : undefined;
+}
+
 export function deriveGoalState(goal, options = {}) {
   const now = options.now || nowIso();
   const events = Array.isArray(goal?.events) ? goal.events : [];
@@ -222,7 +285,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 +302,10 @@ 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 = {}) => {
+      const suggestion = enrichScoutSuggestion({ goalId: goal.id, priority, kind, summary, ...extra });
+      if (!hasActiveClaimForScoutSuggestion(state, suggestion)) suggestions.push(suggestion);
+    };
     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;
@@ -276,11 +343,11 @@ export function formatPeerGoal(goal) {
   if (state.constraints?.length) lines.push(`constraints: ${state.constraints.join("; ")}`);
   if (state.activeClaims.length) {
     lines.push("", "Active claims:");
-    for (const claim of state.activeClaims) lines.push(`- ${claim.id} · ${claim.peerId} · ${claim.mode || "read"} · ${claim.summary}${claim.paths?.length ? ` · ${claim.paths.join(", ")}` : ""}`);
+    for (const claim of state.activeClaims) lines.push(`- ${claim.id} · ${claim.peerId} · ${claim.mode || "read"} · ${claim.summary}${claim.paths?.length ? ` · ${claim.paths.join(", ")}` : ""}${claim.workKey ? ` · key ${truncate(claim.workKey, 80)}` : ""}`);
   }
   if (state.staleClaims.length) {
     lines.push("", "Stale claims:");
-    for (const claim of state.staleClaims.slice(-8)) lines.push(`- ${claim.id} · ${claim.peerId} · ${claim.mode || "read"} · ${claim.summary}${claim.lastHeartbeatAt ? ` · last heartbeat ${claim.lastHeartbeatAt}` : ""}`);
+    for (const claim of state.staleClaims.slice(-8)) lines.push(`- ${claim.id} · ${claim.peerId} · ${claim.mode || "read"} · ${claim.summary}${claim.workKey ? ` · key ${truncate(claim.workKey, 80)}` : ""}${claim.lastHeartbeatAt ? ` · last heartbeat ${claim.lastHeartbeatAt}` : ""}`);
   }
   if (state.expiredClaims.length) {
     lines.push("", "Expired claims:");
@@ -312,6 +379,10 @@ function validateClaim(goal, event) {
   const paths = normalizePaths(event.paths);
   if (event.mode === "write" && paths.length === 0) throw new Error("write claims require --path <path[,path]>");
   const state = deriveGoalState(goal);
+  if (event.workKey && event.duplicatePolicy !== "allow-parallel") {
+    const duplicates = state.activeClaims.filter((claim) => claim.workKey === event.workKey);
+    if (duplicates.length) throw new Error(`claim duplicates active work key ${event.workKey} already held by ${duplicates.map((claim) => claim.id).join(", ")}`);
+  }
   if (event.mode === "write") {
     const conflicts = state.activeClaims.filter((claim) => claim.mode === "write" && pathsOverlap(paths, claim.paths || []));
     if (conflicts.length) throw new Error(`claim conflicts with active write claim ${conflicts.map((claim) => claim.id).join(", ")}`);
@@ -334,6 +405,10 @@ function validateHeartbeat(goal, event) {
   const state = deriveGoalState(goal);
   const claim = state.activeClaims.find((item) => item.id === event.resolves) || state.staleClaims.find((item) => item.id === event.resolves) || state.expiredClaims.find((item) => item.id === event.resolves);
   if (!claim) throw new Error(`peer goal heartbeat target ${event.resolves} is not an active, stale, or expired claim`);
+  if (claim.workKey && claim.duplicatePolicy !== "allow-parallel") {
+    const duplicates = state.activeClaims.filter((item) => item.id !== claim.id && item.workKey === claim.workKey);
+    if (duplicates.length) throw new Error(`heartbeat conflicts with active work key ${claim.workKey} already held by ${duplicates.map((item) => item.id).join(", ")}`);
+  }
   if (claim.mode === "write") {
     const conflicts = state.activeClaims.filter((item) => item.id !== claim.id && item.mode === "write" && pathsOverlap(claim.paths || [], item.paths || []));
     if (conflicts.length) throw new Error(`heartbeat conflicts with active write claim ${conflicts.map((item) => item.id).join(", ")}`);
@@ -368,6 +443,9 @@ function normalizeEvent(input = {}) {
     paths: normalizePaths(input.paths),
     taskId: cleanText(input.taskId),
     mode: cleanText(input.mode || (type === "claim" ? "read" : "")).toLowerCase() || undefined,
+    lane: cleanText(input.lane || input.workLane)?.toLowerCase(),
+    workKey: normalizeWorkKey(input.workKey),
+    duplicatePolicy: normalizeDuplicatePolicy(input.duplicatePolicy),
     resolves: cleanText(input.resolves),
     verdict: cleanText(input.verdict)?.toLowerCase(),
     confidence: confidenceValue(input.confidence),
@@ -397,6 +475,14 @@ function taskSummary(input = {}) {
   return cleanText(input.summary) || cleanText(input.prompt) || `Peer task for ${cleanText(input.targetPeerId || input.peerId) || "unknown"}`;
 }
 
+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())));
+}
+
 function normalizeBoard(board = {}) {
   const goals = plainObject(board.goals) ? board.goals : {};
   const normalizedGoals = {};
@@ -412,7 +498,7 @@ function normalizeBoard(board = {}) {
       createdBy: cleanText(goal.createdBy),
       closedAt: cleanText(goal.closedAt),
       closedBy: cleanText(goal.closedBy),
-      events: Array.isArray(goal.events) ? goal.events.map((event) => stripEmpty({ ...event, paths: normalizePaths(event.paths) })) : [],
+      events: Array.isArray(goal.events) ? goal.events.map((event) => stripEmpty({ ...event, paths: normalizePaths(event.paths), workKey: normalizeWorkKey(event.workKey), duplicatePolicy: normalizeDuplicatePolicy(event.duplicatePolicy), lane: cleanText(event.lane || event.workLane)?.toLowerCase() })) : [],
     };
   }
   return { version: 1, currentGoalId: cleanText(board.currentGoalId), goals: normalizedGoals };
@@ -436,6 +522,9 @@ function projectEventSummary(event) {
     paths: event.paths,
     taskId: event.taskId,
     mode: event.mode,
+    lane: event.lane,
+    workKey: event.workKey,
+    duplicatePolicy: event.duplicatePolicy,
     resolves: event.resolves,
     verdict: event.verdict,
     confidence: event.confidence,
@@ -483,6 +572,47 @@ function uniqueEventPaths(events) {
   return [...new Set(events.flatMap((event) => Array.isArray(event.paths) ? event.paths : []))];
 }
 
+function normalizeWorkKey(value) {
+  const text = cleanText(value);
+  if (!text) return undefined;
+  return text.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function normalizeWorkKeyPart(value) {
+  const text = cleanText(value);
+  if (!text) return undefined;
+  return text.toLowerCase().replace(/\s+/g, " ").replace(/[|]+/g, "/").trim();
+}
+
+function normalizeDuplicatePolicy(value) {
+  const policy = cleanText(value)?.toLowerCase();
+  return DUPLICATE_POLICIES.has(policy) ? policy : undefined;
+}
+
+function enrichScoutSuggestion(suggestion = {}) {
+  const lane = SCOUT_LANES[suggestion.kind] || {};
+  const recommendedLane = suggestion.recommendedLane || lane.recommendedLane;
+  const claimMode = cleanText(suggestion.claimMode || lane.claimMode);
+  const enriched = stripEmpty({
+    ...suggestion,
+    recommendedLane,
+    preferredRoles: normalizeList(suggestion.preferredRoles || lane.preferredRoles),
+    preferredCapabilities: normalizeList(suggestion.preferredCapabilities || lane.preferredCapabilities),
+    claimMode,
+    suggestedIntent: cleanText(suggestion.suggestedIntent || lane.suggestedIntent),
+    rationale: cleanText(suggestion.rationale || lane.rationale),
+  });
+  return stripEmpty({
+    ...enriched,
+    workKey: suggestion.workKey || derivePeerGoalWorkKey({ goalId: enriched.goalId, lane: recommendedLane, objective: enriched.summary, mode: claimMode, paths: enriched.paths }),
+  });
+}
+
+function hasActiveClaimForScoutSuggestion(state, suggestion) {
+  if (!suggestion?.workKey) return false;
+  return state.activeClaims.some((claim) => claim.workKey === suggestion.workKey);
+}
+
 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 };
 }