@cryptolibertus/pi-peer 0.3.7 → 0.4.1

package/README.md

@@ -17,7 +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
+- Persona-aware scout routing: goal-board suggestions include recommended lanes, preferred roles, claim mode, work keys, and rationale so proactive peers can self-select complementary 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
@@ -41,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"
@@ -58,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. 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`.
+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`.
 
 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.
 

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.7",
+  "version": "0.4.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

@@ -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,15 +140,15 @@ 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",
     "- `/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 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 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",
     "- `/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,6 +8,7 @@ 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." },
@@ -15,9 +16,14 @@ const SCOUT_LANES = Object.freeze({
   "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." },
+  "next-step": { recommendedLane: "research", preferredRoles: ["researcher", "reviewer", "planner", "coordinator"], claimMode: "read", suggestedIntent: "review", rationale: "Empty goals benefit from peers self-selecting read-only lanes 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 STARTUP_SCOUT_LANES = Object.freeze([
+  { lane: "research", preferredRoles: ["researcher", "planner", "coordinator"], summary: "No active work yet; self-select a research lane to map risks, options, and next moves." },
+  { lane: "review", preferredRoles: ["reviewer", "qa", "planner", "coordinator"], summary: "No active work yet; self-select a read-only review/QA lane to validate the plan and risks." },
+  { lane: "implementation", preferredRoles: ["worker"], summary: "No active work yet; self-select an implementation-planning lane, then claim write paths only after naming them." },
+]);
 const GOAL_BOARD_LOCK_STALE_MS = 30_000;
 const GOAL_BOARD_LOCK_RETRY_MS = 10;
 const GOAL_BOARD_LOCK_TIMEOUT_MS = 5_000;
@@ -105,26 +111,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",
@@ -132,11 +173,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 };
@@ -144,6 +189,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",
@@ -151,11 +197,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 };
@@ -168,6 +217,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 : [];
@@ -248,7 +307,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(enrichScoutSuggestion({ 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;
@@ -261,6 +323,17 @@ 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)) {
+        const lane = normalizeLaneName(proposal.lane);
+        push("P1", "open-proposal", `Self-select proposed ${lane} lane: ${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.",
+        });
+      }
       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) });
     }
     if (state.readyToClose) {
@@ -268,7 +341,15 @@ export function derivePeerGoalScoutSuggestions(board, options = {}) {
       continue;
     }
     if (!state.activeClaims.length && !state.tasks.length && !state.openProposals.length) {
-      push("P2", "next-step", "No active work yet; propose a research, review, or implementation lane.");
+      for (const lane of STARTUP_SCOUT_LANES) {
+        push("P2", "next-step", lane.summary, {
+          recommendedLane: lane.lane,
+          preferredRoles: lane.preferredRoles,
+          claimMode: "read",
+          suggestedIntent: suggestedIntentForLane(lane.lane),
+          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) {
       push("P2", "review", "No current peer vote; ask a peer for read-only review or record a pass/fail vote.");
     }
@@ -286,11 +367,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:");
@@ -322,6 +403,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(", ")}`);
@@ -344,6 +429,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(", ")}`);
@@ -378,6 +467,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),
@@ -407,6 +499,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 = {};
@@ -422,7 +522,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 };
@@ -446,6 +546,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,
@@ -493,17 +596,66 @@ 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] || {};
-  return stripEmpty({
+  const recommendedLane = normalizeLaneName(suggestion.recommendedLane || lane.recommendedLane);
+  const claimMode = cleanText(suggestion.claimMode || lane.claimMode);
+  const enriched = stripEmpty({
     ...suggestion,
-    recommendedLane: suggestion.recommendedLane || lane.recommendedLane,
+    recommendedLane,
     preferredRoles: normalizeList(suggestion.preferredRoles || lane.preferredRoles),
     preferredCapabilities: normalizeList(suggestion.preferredCapabilities || lane.preferredCapabilities),
-    claimMode: cleanText(suggestion.claimMode || lane.claimMode),
+    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 normalizeLaneName(value) {
+  const lane = cleanText(value).toLowerCase();
+  if (["qa", "quality", "test", "testing"].includes(lane)) return "review";
+  if (["implement", "implementation", "developer", "engineer", "worker", "code", "coding"].includes(lane)) return "implementation";
+  if (["coordinate", "coordinator", "planning", "planner", "orchestration"].includes(lane)) return "coordination";
+  if (["researcher", "scout", "investigation"].includes(lane)) return "research";
+  return lane || "review";
+}
+
+function preferredRolesForLane(lane) {
+  const normalized = normalizeLaneName(lane);
+  if (normalized === "implementation") return ["worker"];
+  if (normalized === "research") return ["researcher", "planner", "coordinator"];
+  if (normalized === "coordination") return ["planner", "coordinator", "reviewer"];
+  return ["reviewer", "qa", "planner", "coordinator"];
+}
+
+function suggestedIntentForLane(lane) {
+  return normalizeLaneName(lane) === "implementation" ? "task" : "review";
+}
+
+function hasActiveClaimForScoutSuggestion(state, suggestion) {
+  if (!suggestion?.workKey) return false;
+  return state.activeClaims.some((claim) => claim.workKey === suggestion.workKey);
 }
 
 async function updatePeerGoalBoard(root, updater) {

package/src/peers/guidance.mjs

@@ -11,7 +11,7 @@ const PEER_SEND_GUIDANCE = "Use peer_send to send a prompt-first message to a pe
 const PEER_AWAIT_GUIDANCE = "Use peer_await with messageId values from queued or timed-out peer_send calls to read final assistant replies.";
 const PEER_GET_GUIDANCE = "Use peer_get to inspect a peer, message, conversation, runtime summary, active tasks via 'tasks', fan-out suggestions via 'fanout', or redacted audit state by id.";
 const PEER_PROGRESS_GUIDANCE = "Use peer_progress from inside an inbound long-running peer task to send structured checkpoint updates before the final handoff.";
-const PEER_FANOUT_GUIDANCE = "Fan-out gate: for multi-part, long-running, or implementation-plus-review work, call peer_list and delegate research/review/QA lanes with peer_send unless the user explicitly says to work solo; if you skip fan-out, state the reason in the final response.";
+const PEER_FANOUT_GUIDANCE = "Fan-out gate: for multi-part, long-running, or implementation-plus-review work, call peer_list and use a goal board plus peer_send for research/review/QA lanes unless the user explicitly says to work solo. For emergent self-organization tests, create/reuse a peer goal and let peers inspect scout suggestions or claim lane-specific work keys instead of over-assigning every lane; if you skip fan-out, state the reason in the final response.";
 
 export const PEER_INBOUND_FINAL_RESPONSE_GUIDANCE = "For inbound peer asks, answer the inbound ask in your final assistant response; that final assistant response is returned to the requesting peer. For write-capable task intents, end with a concise handoff: status, files changed, verification commands with exit status, and blockers.";
 

package/src/peers/idle-watcher.mjs

@@ -139,13 +139,28 @@ export function buildPeerIdleActivationPrompt(activation, options = {}) {
   const peerId = options.localPeerId || "this-peer";
   const paths = activation.paths?.length ? `\nPaths: ${activation.paths.join(", ")}` : "";
   const lane = activation.recommendedLane ? `\nRecommended lane: ${activation.recommendedLane}${activation.claimMode ? ` (${activation.claimMode})` : ""}${activation.preferredRoles?.length ? ` · preferred roles: ${activation.preferredRoles.join(", ")}` : ""}` : "";
+  const workKey = activation.workKey ? `\nWork key: ${activation.workKey}` : "";
+  const suggestedClaim = buildSuggestedReadClaim(activation);
   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.`;
+  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}${workKey}${rationale}${fit}${paths}${suggestedClaim}\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: claim a read-only lane with the work key above, post a proposal/finding/vote, or claim write work only when you intend to edit and can name the paths.\n- If the suggested claim fails as duplicate, inspect the board and stop with a brief handoff instead of starting parallel work.\n- Do not duplicate active claims, work keys, 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.`;
+}
+
+function buildSuggestedReadClaim(activation = {}) {
+  if (activation.claimMode !== "read" || !activation.workKey) return "";
+  const lane = activation.recommendedLane ? ` --lane ${shellQuote(activation.recommendedLane)}` : "";
+  const paths = activation.paths?.length ? activation.paths.map((path) => ` --path ${shellQuote(path)}`).join("") : "";
+  return `\nSuggested first action: /peer goal claim ${shellQuote(activation.goalId)} ${shellQuote(activation.summary)} --mode read${lane} --key ${shellQuote(activation.workKey)}${paths}`;
+}
+
+function shellQuote(value) {
+  const text = String(value || "");
+  if (/^[A-Za-z0-9_./:-]+$/.test(text)) return text;
+  return `'${text.replace(/'/g, `'"'"'`)}'`;
 }
 
 export function peerIdleActivationKey(activation = {}) {
-  return [activation.goalId, activation.kind, activation.recommendedLane, activation.summary, ...(activation.paths || [])].join("|");
+  return [activation.goalId, activation.kind, activation.recommendedLane, activation.workKey, activation.summary, ...(activation.paths || [])].join("|");
 }
 
 function isActivationCoolingDown(state, activation, config, nowMs) {
@@ -167,6 +182,7 @@ function normalizeActivation(suggestion = {}, localPeerId, options = {}) {
     claimMode: cleanString(suggestion.claimMode),
     suggestedIntent: cleanString(suggestion.suggestedIntent),
     rationale: cleanString(suggestion.rationale),
+    workKey: cleanString(suggestion.workKey),
     personaFit,
     paths: Array.isArray(suggestion.paths) ? suggestion.paths.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim()) : [],
     peerId: localPeerId,

package/src/peers/runtime.mjs

@@ -195,7 +195,7 @@ export async function getPeerRuntimeValue(runtime, id) {
     const peers = await runtime.comms.listPeers();
     const messages = await runtime.comms.listMessages();
     const suggestion = deriveFanoutSuggestion(peers, messages);
-    return { type: "fanout", value: { ...suggestion, checklist: ["Run peer_list before multi-lane work", "Create or reuse /peer goal", "Use /peer goal fanout or peer_send goalId+claimedPaths", "Final response must include Fan-out used: yes/no and peer handles"] } };
+    return { type: "fanout", value: { ...suggestion, checklist: ["Run peer_list before multi-lane work", "Create or reuse /peer goal", "For emergent self-organization, ask peers to inspect /peer scout or claim lane-specific work keys before assigning every lane", "Use /peer goal fanout or peer_send goalId+claimedPaths when direct dispatch is needed", "Final response must include Fan-out used: yes/no and peer handles"] } };
   }
   if (id === "audit") return { type: "audit", value: await runtime.comms.getAuditEntries() };