@cryptolibertus/pi-peer 0.3.5 → 0.3.7

package/README.md

@@ -17,8 +17,10 @@ pi install ./packages/pi-peer
 - Local peer discovery and transport using project `.pi/peers.json`
 - Repo-scoped discovery: only Pi sessions in the same git repo/project appear as local peers
 - Idle watcher daemon: idle peers nudge stuck inbound activations and proactively inspect open goal-board work
+- Persona-aware scout routing: goal-board suggestions include recommended lanes, preferred roles, claim mode, and rationale so proactive peers can choose work that fits their role/persona
 - Protocol compatibility metadata (`protocolVersion`, min/max compatible versions), peer manifests, capabilities, and trust summaries in descriptors/status/list output
 - `PI_PEER_ID` runtime override for running multiple local Pi sessions
+- `pi-peer-publish` skill for safe npm release checks, version bumping, tag push, publish, and verification
 
 ## Setup and health checks
 
@@ -30,7 +32,7 @@ pi install ./packages/pi-peer
 /peer cancel <message-id> "superseded"
 ```
 
-`/peer setup` is a guided alias for `/peer init`: it creates `.pi/peers.json` only when the file is missing, seeds protocol/capability/trust manifest metadata, and never overwrites an existing config. `/peer doctor` is read-only and checks enablement, local identity, advertised endpoint, protocol compatibility, discovered peers, warnings, and resumable disconnected tasks. `/peer reconnect` refreshes local discovery after starting or restarting another Pi session. Discovery is repo/project scoped: sessions under the same `.git` root see each other, while sessions in other repos are ignored. Outside git, the resolved cwd is used as the scope. `/peer resume` re-dispatches a disconnected message restored from `.pi/peer-messages.json`; `/peer cancel` records a local cancellation so stale work is no longer treated as active.
+`/peer setup` is a guided alias for `/peer init`: it creates `.pi/peers.json` only when the file is missing, seeds protocol/capability/trust manifest metadata, and never overwrites an existing config. `/peer doctor` is read-only and checks enablement, local identity, advertised endpoint, protocol compatibility, discovered peers, warnings, and resumable disconnected tasks. `/peer reconnect` refreshes local discovery after starting or restarting another Pi session. Discovery is repo/project scoped: sessions under the same `.git` root see each other, while sessions in other repos are ignored. Outside git, the resolved cwd is used as the scope. `/peer resume` re-dispatches a disconnected message restored from `.pi/peer-messages.json`; `/peer cancel` records a local cancellation so stale work is no longer treated as active. List-style flags such as `--peer`, `--path`, and `--claim` accept comma-separated values or repeated flags.
 
 ## Flat goal board
 
@@ -56,7 +58,7 @@ Useful commands (long form and short aliases):
 
 Short aliases keep common board updates terse: `/peer goals`/`/peer ls`, `/peer current`, `/peer scout`, `/peer fanout`, `/peer proposal`/`/peer propose`, `/peer take`/`/peer claim`, `/peer complete`/`/peer done`, `/peer objection`/`/peer block`, `/peer unblock`, `/peer note`, `/peer finding`, `/peer ping`/`/peer heartbeat`, `/peer drop`/`/peer release`, `/peer pass`, `/peer fail`, `/peer vote`, and `/peer close` map to the corresponding `/peer goal ...` actions.
 
-The board is stored locally at `.pi/peer-goals.json`; outbound message snapshots are stored in `.pi/peer-messages.json` so restarted planners can still inspect disconnected historical tasks. Mutating goal-board operations take a short local lock before load/modify/save so concurrent peer appends do not drop events. `/peer send --goal <goal-id> --claim <path[,path]>` and the `peer_send` tool's `goalId`/`claimedPaths` parameters link long-running peer tasks to the board: Symphony records a task, claims overlapping write paths before dispatch, injects goal/heartbeat instructions into the peer prompt, keeps the claim alive with local heartbeats, and releases the claim after the peer returns a final response. `/peer goal fanout` turns a goal into role-specific peer lanes, while `peer_progress` reports checkpoints from an inbound long-running task. Active write claims conflict on overlapping paths; released, stale, or expired claims are kept visible but inactive. Claims become stale after 45 minutes without a heartbeat unless the claim or heartbeat sets `--stale-after-ms`.
+The board is stored locally at `.pi/peer-goals.json`; outbound message snapshots are stored in `.pi/peer-messages.json` so restarted planners can still inspect disconnected historical tasks. Mutating goal-board operations take a short local lock before load/modify/save so concurrent peer appends do not drop events. `/peer send --goal <goal-id> --claim <path[,path]>` and the `peer_send` tool's `goalId`/`claimedPaths` parameters link long-running peer tasks to the board: Symphony records a task, claims overlapping write paths before dispatch, injects goal/heartbeat instructions into the peer prompt, keeps the claim alive with local heartbeats, and releases the claim after the peer returns a final response. `/peer goal fanout` turns a goal into role-specific peer lanes, while `peer_progress` reports checkpoints from an inbound long-running task. Scout suggestions are persona-aware: they surface a recommended lane (`research`, `review`, `coordination`, etc.), preferred roles, a safe default claim mode, and rationale. Active write claims conflict on overlapping paths; released, stale, or expired claims are kept visible but inactive. Claims become stale after 45 minutes without a heartbeat unless the claim or heartbeat sets `--stale-after-ms`.
 
 Normal goal closure requires at least one current passing vote, no current failed votes, no unresolved blocking objections, and no active write claims. Open proposals are intentionally non-blocking: they let peers show initiative without freezing closure. Stale write claims no longer block closure or new overlapping claims; use `/peer goal heartbeat` to revive work after a reconnect and `--force` only when intentionally overriding the readiness gate. Goal-linked tasks validate final handoff headings (`Status`, `Files changed`, `Verification`, `Blockers/risks`, `Safe for review`); missing sections create a blocking objection while still releasing the write claim. For multi-part work, use the fan-out gate: list peers, create/reuse a goal, delegate research/review/worker lanes, and include `Fan-out used: yes/no` plus peer handles in the final answer.
 
@@ -65,7 +67,7 @@ Normal goal closure requires at least one current passing vote, no current faile
 When peer messaging is enabled, the extension starts a lightweight in-process idle watcher on `session_start`. It only acts when Pi reports the agent is idle and there are no queued local follow-up messages. The watcher does two things:
 
 1. If an inbound peer task is active but appears not to have triggered a turn, it re-nudges the existing inbound prompt with `triggerTurn: true` using a cooldown.
-2. If no peer task is active, it reads `.pi/peer-goals.json`, derives the same read-only scout suggestions as `/peer scout`, and injects a concise self-prompt so the idle peer can propose, review, claim, vote, or no-op safely.
+2. If no peer task is active, it reads `.pi/peer-goals.json`, derives the same read-only scout suggestions as `/peer scout`, and injects a concise self-prompt so the idle peer can propose, review, claim, vote, or no-op safely. When the local peer has a configured `role` or `persona`, the watcher prefers suggestions whose lane matches that profile and leaves mismatched work for better-fit peers.
 
 Configuration can be placed in `.pi/peers.json` as `idleWatcher` or in `.pi/settings.json` under `peerMessaging.idleWatcher`:
 
@@ -93,7 +95,9 @@ npm run check
 
 ## Publish to npm
 
-Use this release workflow after landing package changes on `main`:
+This package includes a `pi-peer-publish` Pi skill. Ask Pi to use it, or run `/skill:pi-peer-publish`, when you want an agent-guided release with safety checks, version bumping, tag push, publish, and npm verification.
+
+Use this manual release workflow after landing package changes on `main`:
 
 ```bash
 # Keep local peer runtime state out of release commits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cryptolibertus/pi-peer",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Pi package for local Pi-to-Pi peer messaging, slash commands, tools, and runtime transport.",
   "type": "module",
   "license": "MIT",
@@ -13,6 +13,7 @@
   ],
   "files": [
     "extensions",
+    "skills",
     "src",
     "README.md",
     "LICENSE"
@@ -32,6 +33,9 @@
   "pi": {
     "extensions": [
       "extensions/pi-peer/index.ts"
+    ],
+    "skills": [
+      "skills"
     ]
   },
   "engines": {

package/skills/pi-peer-publish/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: pi-peer-publish
+description: Publish @cryptolibertus/pi-peer to npm safely. Use when the user asks to publish, release, npm publish, bump the package version, or verify/package/push an npm release for this pi-peer package.
+---
+
+# Pi peer publish
+
+This skill publishes `@cryptolibertus/pi-peer` from the repository root.
+
+## Safety rules
+
+- Never publish with uncommitted source changes unless the user explicitly asks to include them and they have been committed first.
+- Never commit `.pi/`, local peer runtime state, npm debug logs, or generated tarballs.
+- Stop before `npm publish` unless the user has explicitly asked to publish now in the current conversation. If they only asked to prepare a release, stop after the dry run and show the exact publish command.
+- If `npm whoami` fails, stop and ask the user to authenticate with `npm login` or configure an automation token outside the chat.
+- For scoped packages, always publish with `--access public` unless `package.json` says otherwise.
+
+## Workflow
+
+1. Inspect release state:
+   ```bash
+   git status --short --branch
+   git remote get-url origin
+   git branch --show-current
+   npm whoami
+   npm view @cryptolibertus/pi-peer version --json
+   node -p "require('./package.json').version"
+   ```
+
+2. Ensure local peer state will not be committed:
+   ```bash
+   grep -qxF '.pi/' .git/info/exclude 2>/dev/null || echo '.pi/' >> .git/info/exclude
+   ```
+
+3. Verify package quality and tarball contents:
+   ```bash
+   npm run check
+   npm pack --dry-run
+   ```
+
+4. Choose the version bump:
+   - Default to `patch` for small fixes and docs.
+   - Use `minor` only for new user-facing capabilities.
+   - Use `major` only for breaking changes, and ask the user first.
+
+5. Bump, commit, and tag using npm so `package.json`, `package-lock.json` if present, and the git tag stay consistent:
+   ```bash
+   npm version patch
+   ```
+
+6. Push the release commit and tag:
+   ```bash
+   git push origin HEAD --follow-tags
+   ```
+
+7. Publish:
+   ```bash
+   npm publish --access public
+   ```
+
+8. Verify the published package:
+   ```bash
+   npm view @cryptolibertus/pi-peer version
+   npm view @cryptolibertus/pi-peer dist-tags --json
+   ```
+
+## Failure handling
+
+- If `npm version` fails because the working tree is dirty, inspect `git status --short`; commit intended changes or revert accidental/generated files before retrying.
+- If the tag already exists locally or remotely, compare the package version with `npm view`. Do not force-push tags. Pick the next valid version instead.
+- If `npm publish` says the version already exists, do not retry the same version. Verify with `npm view`, then bump to the next patch version if the user still wants to publish.
+- If tests fail, stop and fix the failure before bumping or publishing.
+
+## Final response
+
+Report:
+
+- Package name and version published
+- Commit hash and tag pushed
+- Verification commands with exit status
+- npm package URL
+- Any skipped step or blocker

package/src/peers/command.mjs

@@ -251,11 +251,13 @@ function parsePeerGoalCommand(parsed, flags, positionals) {
 }
 
 function stringFlag(value, fallback) {
+  if (Array.isArray(value)) return stringFlag(value.at(-1), fallback);
   if (typeof value === "string" && value.trim()) return value.trim();
   return fallback;
 }
 
 function positiveIntegerFlag(value) {
+  if (Array.isArray(value)) return positiveIntegerFlag(value.at(-1));
   if (value === undefined || value === true) return undefined;
   const number = Number(value);
   return Number.isInteger(number) && number > 0 ? number : undefined;
@@ -288,7 +290,9 @@ function capabilitiesFromFlags(flags = {}) {
 }
 
 function listFlag(value) {
-  if (Array.isArray(value)) return [...new Set(value.map((item) => String(item).trim()).filter(Boolean))];
-  if (typeof value !== "string" || !value.trim()) return [];
-  return [...new Set(value.split(",").map((item) => item.trim()).filter(Boolean))];
+  const values = Array.isArray(value) ? value : [value];
+  return [...new Set(values.flatMap((item) => {
+    if (typeof item !== "string") return [];
+    return item.split(",").map((part) => part.trim()).filter(Boolean);
+  }))];
 }

package/src/peers/goal-board.mjs

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

package/src/peers/idle-watcher.mjs

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

package/src/peers/status.mjs

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

package/src/utils.mjs

@@ -58,21 +58,22 @@ export function parseFlags(args) {
     const [rawKey, rawValue] = arg.slice(2).split(/=(.*)/s, 2);
     const key = rawKey.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
     if (rawValue !== undefined) {
-      flags[key] = rawValue;
+      appendFlagValue(flags, key, rawValue);
       continue;
     }
     const next = args[i + 1];
     if (next !== undefined && !next.startsWith("--")) {
-      flags[key] = next;
+      appendFlagValue(flags, key, next);
       i += 1;
     } else {
-      flags[key] = true;
+      appendFlagValue(flags, key, true);
     }
   }
   return { flags, positionals };
 }
 
 export function flagEnabled(value) {
+  if (Array.isArray(value)) return flagEnabled(value.at(-1));
   if (value === true) return true;
   if (typeof value === "number") return Number.isFinite(value) && value !== 0;
   if (typeof value === "string") {
@@ -81,3 +82,11 @@ export function flagEnabled(value) {
   }
   return false;
 }
+
+function appendFlagValue(flags, key, value) {
+  if (Object.prototype.hasOwnProperty.call(flags, key)) {
+    flags[key] = Array.isArray(flags[key]) ? [...flags[key], value] : [flags[key], value];
+  } else {
+    flags[key] = value;
+  }
+}