@cryptolibertus/pi-peer 0.3.7 → 0.4.0

package/README.md

@@ -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`, `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.
 

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.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,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." },
@@ -105,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",
@@ -132,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 };
@@ -144,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",
@@ -151,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 };
@@ -168,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 : [];
@@ -248,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(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;
@@ -286,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:");
@@ -322,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(", ")}`);
@@ -344,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(", ")}`);
@@ -378,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),
@@ -407,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 = {};
@@ -422,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 };
@@ -446,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,
@@ -493,17 +572,45 @@ 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 = 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 hasActiveClaimForScoutSuggestion(state, suggestion) {
+  if (!suggestion?.workKey) return false;
+  return state.activeClaims.some((claim) => claim.workKey === suggestion.workKey);
 }
 
 async function updatePeerGoalBoard(root, updater) {