@cryptolibertus/pi-peer 0.3.2 → 0.3.5

package/README.md

@@ -12,9 +12,11 @@ pi install ./packages/pi-peer
 
 ## What it adds
 
-- `/peer help|setup|doctor|status|list|init|reconnect|resume|cancel|send|get|await|goal`
+- `/peer help|setup|doctor|status|list|init|reconnect|resume|cancel|send|get|await|goal|scout`
 - `peer_list`, `peer_send`, `peer_get`, `peer_await`, and `peer_progress` tools
 - 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
 - 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
 
@@ -28,11 +30,11 @@ 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. `/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.
 
 ## Flat goal board
 
-`/peer goal` provides a local blackboard for flat peer collaboration. Peers can create a shared goal, post findings/tasks/handoffs, claim read or write leases, object, resolve objections, and vote without a planner assigning every step.
+`/peer goal` provides a local blackboard for flat peer collaboration. Peers can create a shared goal, post findings/tasks/proposals/handoffs, claim read or write leases, object, resolve objections, scout for proactive next steps, and vote without a planner assigning every step.
 
 Useful commands (long form and short aliases):
 
@@ -42,6 +44,8 @@ Useful commands (long form and short aliases):
 /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 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"
@@ -50,21 +54,65 @@ Useful commands (long form and short aliases):
 /peer get <goal-id>
 ```
 
-Short aliases keep common board updates terse: `/peer goals`/`/peer ls`, `/peer current`, `/peer fanout`, `/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.
+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`.
 
-Normal goal closure requires at least one current passing vote, no current failed votes, no unresolved blocking objections, and no active write claims. 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.
+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.
+
+## Idle watcher
+
+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.
+
+Configuration can be placed in `.pi/peers.json` as `idleWatcher` or in `.pi/settings.json` under `peerMessaging.idleWatcher`:
+
+```json
+{
+  "idleWatcher": {
+    "enabled": true,
+    "intervalMs": 15000,
+    "cooldownMs": 300000,
+    "maxActivationsPerSession": 20
+  }
+}
+```
+
+Set `PI_PEER_IDLE_WATCHER=off` to disable it for a process. `PI_PEER_IDLE_WATCHER_INTERVAL_MS` and `PI_PEER_IDLE_WATCHER_COOLDOWN_MS` override timing for local testing.
 
 ## Package checks
 
 ```bash
-npm --prefix packages/pi-peer test
-npm --prefix packages/pi-peer run check:pack
-npm --prefix packages/pi-peer run smoke:pack
-npm --prefix packages/pi-peer run check
+npm test
+npm run check:pack
+npm run smoke:pack
+npm run check
+```
+
+## Publish to npm
+
+Use this release workflow after landing package changes on `main`:
+
+```bash
+# Keep local peer runtime state out of release commits.
+echo ".pi/" >> .git/info/exclude
+
+# Verify the package before changing the version.
+git status --short
+npm run check
+
+# Bump, commit, and tag the next patch version.
+npm version patch
+
+# Push the release commit and tag, then publish.
+git push origin main --tags
+npm publish --access public
 ```
 
+If `npm version patch` reports `Git working directory not clean`, inspect `git status --short`. Do not commit `.pi/`; add it to `.git/info/exclude` or remove local runtime files. If `package.json` was already bumped by the failed command, either commit/tag it manually or reset `package.json` and rerun `npm version patch`.
+
 ## Notes
 
 This package is MIT licensed and published from <https://github.com/CryptoLibertus/pi-peer>. Please use GitHub issues for bugs and feature requests. Peer writes and project mutations still depend on the receiving Pi session's normal approval and safety rules.

package/extensions/pi-peer/index.ts

@@ -6,7 +6,7 @@ import { installPeerRuntimeLifecycle } from "../../src/peers/extension-lifecycle
 import { initPeerConfig } from "../../src/peers/config.mjs";
 import { formatPeerCommandError, formatPeerHelp, formatPeerInitResult, parsePeerCommand } from "../../src/peers/command.mjs";
 import { createPeerRuntime, getPeerRuntimeValue } from "../../src/peers/runtime.mjs";
-import { appendPeerGoalEvent, beginPeerGoalTask, closePeerGoal, completePeerGoalTask, createPeerGoal, formatPeerGoal, formatPeerGoalList, loadPeerGoalBoard, recordPeerGoalTaskDispatch } from "../../src/peers/goal-board.mjs";
+import { appendPeerGoalEvent, beginPeerGoalTask, closePeerGoal, completePeerGoalTask, createPeerGoal, formatPeerGoal, formatPeerGoalList, formatPeerGoalScout, loadPeerGoalBoard, recordPeerGoalTaskDispatch } from "../../src/peers/goal-board.mjs";
 import { collectPeerRuntimeStatus, derivePeerDoctorReport, formatPeerDoctorText, formatPeerStatusLines, formatPeerStatusText } from "../../src/peers/status.mjs";
 import {
   peerAwaitToolResult,
@@ -17,6 +17,7 @@ import {
   peerSendTimeoutToolResult,
 } from "../../src/peers/tool-results.mjs";
 import { PEER_TOOL_NAMES, PEER_TOOL_PROMPT_GUIDELINES } from "../../src/peers/guidance.mjs";
+import { createPeerIdleWatcher } from "../../src/peers/idle-watcher.mjs";
 
 const MESSAGE_TYPE = "pi-peer";
 const runtimeByCwd = new Map<string, Promise<any>>();
@@ -35,6 +36,7 @@ export default function piPeerExtension(pi: ExtensionAPI) {
     activeContext = ctx;
     const runtime = await runtimeFor(pi, ctx.cwd);
     attachPeerUi(runtime, () => activeContext, (current: any) => refreshPeerUi(current, runtime));
+    attachPeerIdleWatcher(pi, runtime, () => activeContext, (current: any) => refreshPeerUi(current, runtime));
     await refreshPeerUi(ctx, runtime);
   });
 
@@ -42,16 +44,19 @@ export default function piPeerExtension(pi: ExtensionAPI) {
     activeContext = ctx;
     const runtime = await runtimeFor(pi, ctx.cwd);
     await refreshPeerUi(ctx, runtime);
+    schedulePeerIdleCheck(runtime, "agent_end");
   });
 
   pi.on("session_shutdown", async (_event, ctx = {}) => {
-    await refreshPeerUi(ctx, await runtimeFor(pi, ctx.cwd));
+    const runtime = await runtimeFor(pi, ctx.cwd);
+    runtime.__peerIdleWatcher?.stop?.();
+    await refreshPeerUi(ctx, runtime);
     activeContext = undefined;
   });
 
   pi.registerCommand("peer", {
     description: "Pi-to-Pi peers: setup, doctor, status, list, send, get, await, progress, goal",
-    getArgumentCompletions: (prefix: string) => ["help", "status", "list", "init", "setup", "doctor", "reconnect", "resume", "cancel", "send", "get", "await", "progress", "goal", "goals", "ls", "current", "fanout", "claim", "take", "done", "complete", "block", "objection", "unblock", "pass", "fail"]
+    getArgumentCompletions: (prefix: string) => ["help", "status", "list", "init", "setup", "doctor", "reconnect", "resume", "cancel", "send", "get", "await", "progress", "goal", "goals", "ls", "current", "scout", "fanout", "proposal", "propose", "claim", "take", "done", "complete", "block", "objection", "unblock", "pass", "fail"]
       .filter((value) => value.startsWith(prefix))
       .map((value) => ({ value, label: value })),
     handler: async (rawArgs, ctx) => {
@@ -409,8 +414,9 @@ async function handlePeerGoalCommand(parsed: any, ctx: any, runtime: any) {
     if (!goal) throw new Error(goalId ? `peer goal ${goalId} not found` : "no current peer goal");
     return formatPeerGoal(goal);
   }
+  if (parsed.goalAction === "scout") return formatPeerGoalScout(await loadPeerGoalBoard(root), { goalId: parsed.goalId, limit: parsed.limit, includeClosed: parsed.includeClosed });
   if (parsed.goalAction === "fanout") return handlePeerGoalFanout(parsed, ctx, runtime, peerId);
-  if (["task", "finding", "handoff", "note"].includes(parsed.goalAction)) {
+  if (["task", "finding", "proposal", "propose", "handoff", "note"].includes(parsed.goalAction)) {
     const result = await appendPeerGoalEvent(root, parsed.goalId, {
       type: parsed.eventType,
       peerId,
@@ -580,6 +586,7 @@ async function resetRuntimeFor(cwd?: string) {
   const pending = runtimeByCwd.get(key);
   runtimeByCwd.delete(key);
   const runtime = await pending?.catch(() => undefined);
+  runtime?.__peerIdleWatcher?.stop?.();
   await runtime?.dispose?.();
 }
 
@@ -592,6 +599,29 @@ function attachPeerUi(runtime: any, activeContext: () => any, refresh: (ctx: any
   });
 }
 
+function attachPeerIdleWatcher(pi: ExtensionAPI, runtime: any, activeContext: () => any, refresh: (ctx: any) => Promise<void>) {
+  if (!runtime?.enabled || !runtime?.comms) return false;
+  if (!runtime.__peerIdleWatcher) {
+    runtime.__peerIdleWatcher = createPeerIdleWatcher({
+      pi,
+      runtime,
+      activeContext,
+      refresh,
+      messageType: MESSAGE_TYPE,
+      env: process.env,
+    });
+  }
+  return runtime.__peerIdleWatcher.start?.();
+}
+
+function schedulePeerIdleCheck(runtime: any, reason: string) {
+  if (!runtime?.__peerIdleWatcher?.check) return;
+  const timer = setTimeout(() => {
+    void runtime.__peerIdleWatcher.check(reason).catch(() => {});
+  }, 0);
+  timer.unref?.();
+}
+
 function ensureEnabled(runtime: any) {
   if (!runtime.enabled) throw new Error("Pi-to-Pi peer messaging is disabled for this project. Run /peer init or enable experimental.peerMessaging before using peer send/get/await.");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cryptolibertus/pi-peer",
-  "version": "0.3.2",
+  "version": "0.3.5",
   "description": "Pi package for local Pi-to-Pi peer messaging, slash commands, tools, and runtime transport.",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test ../../test/peer-*.test.mjs",
+    "test": "node --test test/peer-*.test.mjs",
     "check": "npm test && npm run check:pack",
     "check:pack": "npm pack --dry-run",
     "smoke:pack": "npm run check:pack",

package/src/peers/command.mjs

@@ -7,6 +7,9 @@ const PEER_GOAL_ALIASES = Object.freeze({
   ls: ["list"],
   current: ["show"],
   fanout: ["fanout"],
+  scout: ["scout"],
+  proposal: ["proposal"],
+  propose: ["propose"],
   claim: ["claim"],
   take: ["claim"],
   heartbeat: ["heartbeat"],
@@ -136,11 +139,12 @@ export function formatPeerHelp() {
     "- `/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 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 fanout`, `/peer take|claim`, `/peer complete|done`, `/peer objection|block`, `/peer unblock`, `/peer ping`, `/peer drop`, `/peer pass|fail` — short goal-board aliases",
+    "- `/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, and votes",
+    "- `/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 task|finding|handoff|note <goal-id> <summary> [--path <a,b>] [--status done]` — post goal-board events",
+    "- `/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 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",
@@ -171,6 +175,7 @@ function parsePeerGoalCommand(parsed, flags, positionals) {
     return { ...withAction, objective, constraints: listFlag(flags.constraint || flags.constraints) };
   }
   if (action === "show") return { ...withAction, goalId: rest[0] };
+  if (action === "scout") return { ...withAction, goalId: rest[0], limit: positiveIntegerFlag(flags.limit), includeClosed: flagEnabled(flags.includeClosed) };
   if (action === "fanout") {
     const goalId = rest[0];
     const objective = rest.slice(1).join(" ").trim();
@@ -189,11 +194,11 @@ function parsePeerGoalCommand(parsed, flags, positionals) {
       staleAfterMs: positiveIntegerFlag(flags.staleAfterMs),
     };
   }
-  if (["task", "finding", "handoff", "note"].includes(action)) {
+  if (["task", "finding", "proposal", "propose", "handoff", "note"].includes(action)) {
     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 === "task" ? "task" : 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) };
   }
   if (action === "claim") {
     if (flagEnabled(flags.write) && flags.mode === undefined) flags.mode = "write";

package/src/peers/config.mjs

@@ -3,6 +3,7 @@ import { hostname } from "node:os";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 
 import { normalizePeerDescriptor } from "./comms.mjs";
+import { normalizePeerIdleWatcherConfig } from "./idle-watcher.mjs";
 import { PEER_VERSION, peerProtocolMetadata, redactPeerAuditValue } from "./protocol.mjs";
 
 export const PEER_SETTINGS_RELATIVE_PATH = ".pi/settings.json";
@@ -33,6 +34,7 @@ export function parsePeerRuntimeConfig({ settings, peerFile, env } = {}) {
   for (const peer of configuredPeers(peerFile?.peers, "peers", warnings)) peersById.set(peer.peerId, { ...(peersById.get(peer.peerId) || {}), ...peer });
 
   const manifest = normalizePeerManifest(peerFile?.manifest || settings?.peerMessaging?.manifest || settings?.manifest);
+  const idleWatcher = normalizePeerIdleWatcherConfig(peerFile?.idleWatcher || settings?.peerMessaging?.idleWatcher || settings?.idleWatcher, { env });
   const peers = [...peersById.values()].map((peer) => markUnsupportedTransport(normalizePeerDescriptor({ ...manifestDefaults(manifest), ...peer }), warnings));
   const peerFileLocalPeerId = normalizePeerId(peerFile?.localPeerId);
   const settingsPeerMessagingLocalPeerId = normalizePeerId(settings?.peerMessaging?.localPeerId);
@@ -42,6 +44,7 @@ export function parsePeerRuntimeConfig({ settings, peerFile, env } = {}) {
     enabled,
     source: configSource(hasSettings, hasPeerFile),
     manifest,
+    idleWatcher,
     localPeerId,
     localPeerIdSource: localPeerIdSource({ peerFileLocalPeerId, settingsPeerMessagingLocalPeerId, settingsLocalPeerId }),
     peers,
@@ -101,6 +104,7 @@ export function summarizePeerRuntimeConfig(config) {
     localPeerProfile: summarizePeerProfile(config.localPeerProfile),
     protocolVersion: config.manifest?.protocolVersion || PEER_VERSION,
     manifest: summarizePeerManifest(config.manifest),
+    idleWatcher: summarizePeerIdleWatcher(config.idleWatcher),
     peerCount: Array.isArray(config.peers) ? config.peers.length : 0,
     peers: (config.peers || []).map((peer) => ({
       peerId: peer.peerId,
@@ -162,6 +166,15 @@ export function summarizePeerProfile(profile = {}) {
   return Object.keys(summary).length ? summary : undefined;
 }
 
+function summarizePeerIdleWatcher(idleWatcher = {}) {
+  return {
+    enabled: idleWatcher.enabled !== false,
+    intervalMs: idleWatcher.intervalMs,
+    cooldownMs: idleWatcher.cooldownMs,
+    maxActivationsPerSession: idleWatcher.maxActivationsPerSession,
+  };
+}
+
 function defaultLocalPeerId() {
   return `pi-${sanitizePeerId(hostname()) || "local"}`;
 }

package/src/peers/goal-board.mjs

@@ -5,7 +5,7 @@ import { setTimeout as sleep } from "node:timers/promises";
 
 export const PEER_GOAL_BOARD_RELATIVE_PATH = ".pi/peer-goals.json";
 
-const EVENT_TYPES = new Set(["finding", "task", "claim", "release", "heartbeat", "objection", "resolve", "vote", "handoff", "note"]);
+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 DEFAULT_GOAL_CLAIM_STALE_MS = 45 * 60 * 1000;
@@ -66,6 +66,7 @@ export async function appendPeerGoalEvent(root, goalId, eventInput = {}) {
     const goal = resolveGoal(board, goalId);
     const event = normalizeEvent(eventInput);
     if (event.type === "claim") validateClaim(goal, event);
+    if (event.type === "proposal") validateProposal(event);
     if (event.type === "release") validateRelease(goal, event);
     if (event.type === "heartbeat") validateHeartbeat(goal, event);
     goal.events.push(event);
@@ -172,6 +173,8 @@ export function deriveGoalState(goal, options = {}) {
   const blockingObjections = events
     .filter((event) => event.type === "objection" && isBlockingSeverity(event.severity) && !resolvedIds.has(event.id))
     .map(projectEventSummary);
+  const proposals = events.filter((event) => event.type === "proposal").map(projectEventSummary);
+  const openProposals = proposals.filter((event) => !resolvedIds.has(event.id));
   const votes = events.filter((event) => event.type === "vote").map(projectEventSummary);
   const currentVotes = currentPeerVotes(votes);
   const failedVotes = currentVotes.filter((vote) => vote.verdict === "fail");
@@ -187,6 +190,8 @@ export function deriveGoalState(goal, options = {}) {
     staleClaims,
     releasedClaims,
     blockingObjections,
+    proposals,
+    openProposals,
     votes,
     currentVotes,
     failedVotes,
@@ -205,10 +210,62 @@ export function formatPeerGoalList(board) {
     if (state.activeClaims.length) bits.push(`${state.activeClaims.length} active claim${state.activeClaims.length === 1 ? "" : "s"}`);
     if (state.staleClaims.length) bits.push(`${state.staleClaims.length} stale claim${state.staleClaims.length === 1 ? "" : "s"}`);
     if (state.blockingObjections.length) bits.push(`${state.blockingObjections.length} blocker${state.blockingObjections.length === 1 ? "" : "s"}`);
+    if (state.openProposals.length) bits.push(`${state.openProposals.length} proposal${state.openProposals.length === 1 ? "" : "s"}`);
     return bits.join(" · ");
   }).join("\n");
 }
 
+export function formatPeerGoalScout(board, options = {}) {
+  const suggestions = derivePeerGoalScoutSuggestions(board, options);
+  if (!suggestions.length) return "No proactive scout suggestions. Open goals look idle-safe or there are no matching goals.";
+  const limit = positiveNumber(options.limit) || suggestions.length;
+  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}`);
+  }
+  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");
+}
+
+export function derivePeerGoalScoutSuggestions(board, options = {}) {
+  const normalized = normalizeBoard(board);
+  const includeClosed = options.includeClosed === true;
+  const requestedGoalId = cleanText(options.goalId);
+  const goals = Object.values(normalized.goals)
+    .filter((goal) => (!requestedGoalId || goal.id === requestedGoalId) && (includeClosed || goal.status !== "closed"))
+    .sort((a, b) => String(b.updatedAt || "").localeCompare(String(a.updatedAt || "")));
+  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 }));
+    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;
+    }
+    if (state.failedVotes.length) {
+      push("P0", "failed-vote", `Address failed vote from ${state.failedVotes.map((vote) => vote.peerId || vote.id).join(", ")}.`);
+      continue;
+    }
+    if (state.staleClaims.length) {
+      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) {
+      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) {
+      push("P1", "close", "Goal satisfies closure gates; close it or record a final note.");
+      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.");
+    } 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.");
+    }
+  }
+  return suggestions;
+}
+
 export function formatPeerGoal(goal) {
   const state = goal && Array.isArray(goal.activeClaims) && Array.isArray(goal.expiredClaims) && Array.isArray(goal.staleClaims) ? goal : deriveGoalState(goal);
   const lines = [
@@ -233,6 +290,10 @@ export function formatPeerGoal(goal) {
     lines.push("", "Blocking objections:");
     for (const objection of state.blockingObjections) lines.push(`- ${objection.id} · ${objection.peerId} · ${objection.summary}`);
   }
+  if (state.openProposals.length) {
+    lines.push("", "Open proposals:");
+    for (const proposal of state.openProposals.slice(-8)) lines.push(`- ${proposal.id} · ${proposal.peerId} · ${proposal.summary}${proposal.paths?.length ? ` · ${proposal.paths.join(", ")}` : ""}`);
+  }
   if (state.currentVotes.length) {
     lines.push("", "Votes:");
     for (const vote of state.currentVotes.slice(-8)) lines.push(`- ${vote.peerId}: ${vote.verdict}${vote.confidence !== undefined ? ` (${vote.confidence})` : ""}${vote.summary ? ` — ${vote.summary}` : ""}`);
@@ -257,6 +318,10 @@ function validateClaim(goal, event) {
   }
 }
 
+function validateProposal(event) {
+  if (!event.summary) throw new Error("peer goal proposal requires a summary");
+}
+
 function validateRelease(goal, event) {
   if (!event.resolves) throw new Error("peer goal release requires a claim event id");
   const state = deriveGoalState(goal);
@@ -269,6 +334,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.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(", ")}`);
+  }
 }
 
 function validateGoalReadyToClose(state) {
@@ -410,6 +479,10 @@ function currentPeerVotes(votes) {
   return [...byPeer.values()];
 }
 
+function uniqueEventPaths(events) {
+  return [...new Set(events.flatMap((event) => Array.isArray(event.paths) ? event.paths : []))];
+}
+
 async function updatePeerGoalBoard(root, updater) {
   const path = goalBoardPath(root);
   await mkdir(dirname(path), { recursive: true });
@@ -460,11 +533,18 @@ function goalBoardPath(root) {
 }
 
 function pathsOverlap(a, b) {
-  return a.some((left) => b.some((right) => left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)));
+  return a.some((left) => b.some((right) => left === "." || right === "." || left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)));
 }
 
 function normalizePaths(value) {
-  return [...new Set(normalizeList(value).map((item) => item.replace(/^\.\//, "").replace(/\/+/g, "/").replace(/\/$/, "")).filter(Boolean))];
+  return [...new Set(normalizeList(value).map(normalizePath).filter(Boolean))];
+}
+
+function normalizePath(value) {
+  let path = cleanText(value).replace(/\/+/g, "/");
+  if (path === "" || path === "." || path === "/") return ".";
+  path = path.replace(/^\.\//, "").replace(/\/$/, "");
+  return path === "" || path === "." || path === "/" ? "." : path;
 }
 
 function normalizeList(value) {

package/src/peers/idle-watcher.mjs

@@ -0,0 +1,194 @@
+import { derivePeerGoalScoutSuggestions, loadPeerGoalBoard } from "./goal-board.mjs";
+
+export const DEFAULT_PEER_IDLE_WATCHER_INTERVAL_MS = 15_000;
+export const DEFAULT_PEER_IDLE_WATCHER_COOLDOWN_MS = 5 * 60 * 1000;
+export const DEFAULT_PEER_IDLE_WATCHER_MAX_PER_SESSION = 20;
+
+const FALSE_VALUES = new Set(["0", "false", "off", "no", "disabled"]);
+const TRUE_VALUES = new Set(["1", "true", "on", "yes", "enabled"]);
+const DEFAULT_ALLOWED_KINDS = ["blocker", "failed-vote", "stale-claim", "open-proposal", "close", "next-step", "review"];
+
+export function normalizePeerIdleWatcherConfig(input = {}, options = {}) {
+  const env = options.env || process.env;
+  const source = plainObject(input) ? input : {};
+  const envEnabled = parseBoolean(env.PI_PEER_IDLE_WATCHER);
+  return {
+    enabled: envEnabled ?? (source.enabled !== false),
+    intervalMs: positiveInteger(env.PI_PEER_IDLE_WATCHER_INTERVAL_MS) || positiveInteger(source.intervalMs) || DEFAULT_PEER_IDLE_WATCHER_INTERVAL_MS,
+    cooldownMs: positiveInteger(env.PI_PEER_IDLE_WATCHER_COOLDOWN_MS) || positiveInteger(source.cooldownMs) || DEFAULT_PEER_IDLE_WATCHER_COOLDOWN_MS,
+    maxActivationsPerSession: positiveInteger(source.maxActivationsPerSession) || DEFAULT_PEER_IDLE_WATCHER_MAX_PER_SESSION,
+    includeClosed: source.includeClosed === true,
+    allowedKinds: normalizeAllowedKinds(source.allowedKinds),
+  };
+}
+
+export function createPeerIdleWatcher(options = {}) {
+  const runtime = options.runtime;
+  const pi = options.pi;
+  const activeContext = typeof options.activeContext === "function" ? options.activeContext : () => undefined;
+  const refresh = typeof options.refresh === "function" ? options.refresh : async () => {};
+  const loadBoard = options.loadBoard || ((root) => loadPeerGoalBoard(root));
+  const now = typeof options.now === "function" ? options.now : () => Date.now();
+  const config = normalizePeerIdleWatcherConfig(options.config || runtime?.config?.idleWatcher || {}, { env: options.env });
+  const state = {
+    running: false,
+    timer: undefined,
+    activationCount: 0,
+    lastActivationAtByKey: new Map(),
+    checking: false,
+  };
+
+  async function check(reason = "timer") {
+    if (!runtime?.enabled || !config.enabled || state.checking) return { activated: false, reason: "disabled" };
+    state.checking = true;
+    try {
+      const ctx = activeContext();
+      const idle = isContextIdle(ctx);
+      if (!idle.ok) return { activated: false, reason: idle.reason };
+      if (state.activationCount >= config.maxActivationsPerSession) return { activated: false, reason: "activation limit reached" };
+      if (runtime?.pendingInboundCount?.() > 0) {
+        const nudged = runtime?.nudgeInboundIfIdle?.({ reason: "idle-watcher", cooldownMs: Math.min(activationNudgeCooldownMs(config), config.cooldownMs) });
+        if (nudged?.ok) {
+          state.activationCount = (state.activationCount || 0) + 1;
+          await refresh(ctx).catch(() => {});
+          return { activated: true, activation: { kind: "inbound-nudge", messageId: nudged.messageId, conversationId: nudged.conversationId, activationAttempts: nudged.activationAttempts } };
+        }
+        return { activated: false, reason: nudged?.reason || "inbound peer task active" };
+      }
+      const messages = runtime?.comms?.listMessages ? await runtime.comms.listMessages() : [];
+      const pendingMessages = messages.filter((message) => ["queued", "running"].includes(message.status));
+      if (pendingMessages.length) return { activated: false, reason: "peer messages pending" };
+
+      const board = await loadBoard(runtime.cwd || ctx?.cwd || process.cwd());
+      const activation = derivePeerIdleActivation(board, {
+        localPeerId: runtime.localPeerId,
+        config,
+        state,
+        nowMs: now(),
+      });
+      if (!activation) return { activated: false, reason: "no idle activation" };
+
+      const prompt = buildPeerIdleActivationPrompt(activation, { localPeerId: runtime.localPeerId });
+      pi.sendMessage({
+        customType: options.messageType || "pi-peer",
+        content: `Idle watcher activated (${reason}): ${activation.kind} for ${activation.goalId}\n\n${prompt}`,
+        display: true,
+        details: { kind: "peer_idle_activation", activation },
+      }, { deliverAs: "followUp", triggerTurn: true });
+      markPeerIdleActivation(state, activation, now());
+      await refresh(ctx).catch(() => {});
+      return { activated: true, activation };
+    } finally {
+      state.checking = false;
+    }
+  }
+
+  return {
+    config,
+    state,
+    start() {
+      if (state.running || !config.enabled || !runtime?.enabled) return false;
+      state.running = true;
+      state.timer = setInterval(() => {
+        void check("timer").catch(() => {});
+      }, config.intervalMs);
+      state.timer.unref?.();
+      // Let a freshly-started idle worker notice existing board work without waiting a full interval.
+      setTimeout(() => {
+        if (state.running) void check("startup").catch(() => {});
+      }, Math.min(1_000, config.intervalMs)).unref?.();
+      return true;
+    },
+    stop() {
+      state.running = false;
+      clearInterval(state.timer);
+      state.timer = undefined;
+    },
+    check,
+  };
+}
+
+export function derivePeerIdleActivation(board, options = {}) {
+  const config = normalizePeerIdleWatcherConfig(options.config || {});
+  if (!config.enabled) return undefined;
+  const suggestions = derivePeerGoalScoutSuggestions(board, { includeClosed: config.includeClosed });
+  const allowedKinds = new Set(config.allowedKinds || DEFAULT_ALLOWED_KINDS);
+  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;
+    if (isActivationCoolingDown(options.state, activation, config, nowMs)) continue;
+    return activation;
+  }
+  return undefined;
+}
+
+export function markPeerIdleActivation(state, activation, nowMs = Date.now()) {
+  if (!state || !activation) return false;
+  state.activationCount = (state.activationCount || 0) + 1;
+  if (!state.lastActivationAtByKey) state.lastActivationAtByKey = new Map();
+  state.lastActivationAtByKey.set(peerIdleActivationKey(activation), nowMs);
+  return true;
+}
+
+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.`;
+}
+
+export function peerIdleActivationKey(activation = {}) {
+  return [activation.goalId, activation.kind, activation.summary, ...(activation.paths || [])].join("|");
+}
+
+function isActivationCoolingDown(state, activation, config, nowMs) {
+  const last = state?.lastActivationAtByKey?.get?.(peerIdleActivationKey(activation));
+  return Number.isFinite(last) && nowMs - last < config.cooldownMs;
+}
+
+function normalizeActivation(suggestion = {}, localPeerId) {
+  if (!suggestion.goalId || !suggestion.kind || !suggestion.summary) return undefined;
+  return {
+    goalId: suggestion.goalId,
+    priority: suggestion.priority || "P2",
+    kind: suggestion.kind,
+    summary: suggestion.summary,
+    paths: Array.isArray(suggestion.paths) ? suggestion.paths.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim()) : [],
+    peerId: localPeerId,
+  };
+}
+
+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" };
+  if (typeof ctx.hasPendingMessages === "function" && ctx.hasPendingMessages()) return { ok: false, reason: "pending local messages" };
+  return { ok: true };
+}
+
+function activationNudgeCooldownMs(config = {}) {
+  return Math.max(5_000, Math.floor((config.intervalMs || DEFAULT_PEER_IDLE_WATCHER_INTERVAL_MS) * 2));
+}
+
+function normalizeAllowedKinds(value) {
+  if (!Array.isArray(value)) return DEFAULT_ALLOWED_KINDS;
+  const kinds = value.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim());
+  return kinds.length ? [...new Set(kinds)] : DEFAULT_ALLOWED_KINDS;
+}
+
+function parseBoolean(value) {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (TRUE_VALUES.has(normalized)) return true;
+  if (FALSE_VALUES.has(normalized)) return false;
+  return undefined;
+}
+
+function positiveInteger(value) {
+  const number = Number(value);
+  return Number.isInteger(number) && number > 0 ? number : undefined;
+}
+
+function plainObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/src/peers/inbound-bridge.mjs

@@ -7,6 +7,7 @@ export const PI_PEER_INBOUND_CUSTOM_TYPE = "pi-peer-inbound";
 export function createInboundPromptBridge(options = {}) {
   const pi = options.pi;
   const responseTimeoutMs = Number.isInteger(options.responseTimeoutMs) ? options.responseTimeoutMs : 30 * 60 * 1000;
+  const activationNudgeCooldownMs = Number.isInteger(options.activationNudgeCooldownMs) ? options.activationNudgeCooldownMs : 30_000;
   const queue = [];
   let activeEntry;
 
@@ -19,12 +20,7 @@ export function createInboundPromptBridge(options = {}) {
     startActiveTimer(entry);
 
     try {
-      pi.sendMessage({
-        customType: PI_PEER_INBOUND_CUSTOM_TYPE,
-        content: renderInboundPeerPrompt(entry.envelope, { responderProfile: options.responderProfile, homeDir: options.homeDir }),
-        display: true,
-        envelope: summarizeEnvelope(entry.envelope),
-      }, { deliverAs: "followUp", triggerTurn: true });
+      sendActiveEntryToPi(entry, "initial");
     } catch (error) {
       activeEntry = undefined;
       settleEntry(entry, { status: "ERROR", summary: error?.message || String(error) });
@@ -32,6 +28,23 @@ export function createInboundPromptBridge(options = {}) {
     }
   }
 
+  function sendActiveEntryToPi(entry, reason) {
+    const now = Date.now();
+    entry.activationAttempts = (entry.activationAttempts || 0) + 1;
+    entry.lastNudgeAt = now;
+    if (!entry.activatedAt) entry.activatedAt = now;
+    pi.sendMessage({
+      customType: PI_PEER_INBOUND_CUSTOM_TYPE,
+      content: renderInboundPeerPrompt(entry.envelope, { responderProfile: options.responderProfile, homeDir: options.homeDir }),
+      display: true,
+      envelope: summarizeEnvelope(entry.envelope),
+      details: {
+        activationReason: reason,
+        activationAttempts: entry.activationAttempts,
+      },
+    }, { deliverAs: "followUp", triggerTurn: true });
+  }
+
   function startActiveTimer(entry) {
     entry.timer = setTimeout(() => {
       if (activeEntry !== entry || entry.settled) return;
@@ -89,6 +102,34 @@ export function createInboundPromptBridge(options = {}) {
       return { ok: true, messageId: entry.messageId, conversationId: entry.conversationId, progress };
     },
 
+    nudgeActive(input = {}) {
+      const entry = activeEntry;
+      if (!entry || entry.settled) return { ok: false, reason: "no active inbound peer task" };
+      const cooldownMs = Number.isInteger(input.cooldownMs) ? input.cooldownMs : activationNudgeCooldownMs;
+      const now = Date.now();
+      if (entry.lastNudgeAt && now - entry.lastNudgeAt < cooldownMs) {
+        return { ok: false, reason: "inbound activation nudge cooldown", messageId: entry.messageId, conversationId: entry.conversationId, activationAttempts: entry.activationAttempts || 0 };
+      }
+      try {
+        sendActiveEntryToPi(entry, input.reason || "idle-nudge");
+        return { ok: true, messageId: entry.messageId, conversationId: entry.conversationId, activationAttempts: entry.activationAttempts || 0 };
+      } catch (error) {
+        return { ok: false, reason: error?.message || String(error), messageId: entry.messageId, conversationId: entry.conversationId, activationAttempts: entry.activationAttempts || 0 };
+      }
+    },
+
+    activeState() {
+      const entry = activeEntry;
+      return entry && !entry.settled ? {
+        messageId: entry.messageId,
+        conversationId: entry.conversationId,
+        activatedAt: entry.activatedAt,
+        lastNudgeAt: entry.lastNudgeAt,
+        activationAttempts: entry.activationAttempts || 0,
+        queuedCount: queue.length,
+      } : { queuedCount: queue.length };
+    },
+
     pendingCount() {
       return queue.length + (activeEntry && !activeEntry.settled ? 1 : 0);
     },

package/src/peers/local-transport.mjs

@@ -1,8 +1,8 @@
 import net from "node:net";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-import { chmod, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, readdir, realpath, rm, stat, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 
 import { PEER_VERSION, assertValidPeerEnvelope, createPeerEnvelope, isPeerProtocolCompatible, normalizePeerMessageResponseBody, peerProtocolMetadata, redactPeerAuditValue, resolvePeerAuthToken, validatePeerEnvelope } from "./protocol.mjs";
@@ -70,6 +70,7 @@ export function createLocalPeerEndpoint(options = {}) {
     ? options.presenceHeartbeatIntervalMs
     : DEFAULT_PRESENCE_HEARTBEAT_INTERVAL_MS;
   const authToken = resolveEndpointAuthToken(options);
+  let projectScope;
   let server;
   let descriptor;
   let presenceHeartbeatTimer;
@@ -117,6 +118,7 @@ export function createLocalPeerEndpoint(options = {}) {
         await chmod(socketDir, 0o700).catch(() => {});
       }
       if (socketPath && existsSync(socketPath)) await rm(socketPath, { force: true });
+      projectScope = options.projectScope || await derivePeerProjectScope(options.cwd);
       server = net.createServer((socket) => {
         sockets.add(socket);
         socket.once("close", () => sockets.delete(socket));
@@ -144,6 +146,7 @@ export function createLocalPeerEndpoint(options = {}) {
         maxHopCount: Number.isInteger(options.maxHopCount) ? options.maxHopCount : 1,
         pid: process.pid,
         cwd: options.cwd,
+        projectScope,
         sessionId: options.sessionId,
         role: safeDescriptorText(options.role),
         persona: safeDescriptorText(options.persona),
@@ -185,6 +188,7 @@ export async function discoverLocalPeerEndpoints(options = {}) {
   const discoveryDir = resolve(options.discoveryDir || LOCAL_PEER_DISCOVERY_DIR);
   const excludePeerId = options.excludePeerId;
   const maxAgeMs = Number.isInteger(options.maxAgeMs) ? options.maxAgeMs : 10 * 60 * 1000;
+  const projectScope = options.projectScope || (options.cwd ? await derivePeerProjectScope(options.cwd) : undefined);
   let names;
   try {
     names = await readdir(discoveryDir);
@@ -203,6 +207,10 @@ export async function discoverLocalPeerEndpoints(options = {}) {
     if (descriptor.transport !== "coms" || descriptor.status !== "active") continue;
     if (!descriptor.socketPath && !descriptor.pipeName) continue;
     if (!descriptor.updatedAt) continue;
+    if (projectScope) {
+      const descriptorScope = await descriptorProjectScope(descriptor);
+      if (!descriptorScope || descriptorScope !== projectScope) continue;
+    }
     const updatedAtMs = Date.parse(descriptor.updatedAt);
     if (!Number.isFinite(updatedAtMs) || Date.now() - updatedAtMs > maxAgeMs) continue;
     if (!Number.isInteger(descriptor.pid) || !processAlive(descriptor.pid)) continue;
@@ -218,6 +226,7 @@ export async function discoverLocalPeerEndpoints(options = {}) {
       compatible: isPeerProtocolCompatible(descriptor),
       capabilities: descriptor.capabilities || {},
       cwd: descriptor.cwd,
+      projectScope: descriptor.projectScope,
       role: descriptor.role,
       persona: descriptor.persona,
       sessionId: descriptor.sessionId,
@@ -230,6 +239,47 @@ export async function discoverLocalPeerEndpoints(options = {}) {
   return peers;
 }
 
+export async function derivePeerProjectScope(cwd) {
+  const start = await canonicalPath(cwd || process.cwd());
+  const root = await findGitRoot(start);
+  return root || start;
+}
+
+async function descriptorProjectScope(descriptor = {}) {
+  if (typeof descriptor.projectScope === "string" && descriptor.projectScope.trim()) return canonicalPath(descriptor.projectScope);
+  if (typeof descriptor.cwd === "string" && descriptor.cwd.trim()) return derivePeerProjectScope(descriptor.cwd);
+  return undefined;
+}
+
+async function findGitRoot(start) {
+  let current = resolve(start || process.cwd());
+  for (;;) {
+    if (await hasGitMarker(current)) return current;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+async function hasGitMarker(dir) {
+  try {
+    const marker = resolve(dir, ".git");
+    const info = await stat(marker);
+    return info.isDirectory() || info.isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function canonicalPath(path) {
+  const resolved = resolve(path || process.cwd());
+  try {
+    return await realpath(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
 async function sendEnvelopeToEndpoint(envelope, peer, options) {
   const socket = net.createConnection(peer.pipeName || peer.socketPath);
   const timeoutMs = options.timeoutMs;

package/src/peers/runtime.mjs

@@ -4,7 +4,7 @@ import { InMemoryPeerTransport, MemoryPeerRegistry, createPeerComms } from "./co
 import { applyLocalPeerIdOverride, loadLocalPeerProfile, loadPeerRuntimeConfig, summarizePeerRuntimeConfig } from "./config.mjs";
 import { deriveGoalState, loadPeerGoalBoard } from "./goal-board.mjs";
 import { createInboundPromptBridge } from "./inbound-bridge.mjs";
-import { LocalPeerTransport, createLocalPeerEndpoint, discoverLocalPeerEndpoints } from "./local-transport.mjs";
+import { LocalPeerTransport, createLocalPeerEndpoint, derivePeerProjectScope, discoverLocalPeerEndpoints } from "./local-transport.mjs";
 import { createPeerMessageStore } from "./message-store.mjs";
 import { redactPeerAuditValue } from "./protocol.mjs";
 import { collectPeerRuntimeStatus, deriveFanoutSuggestion } from "./status.mjs";
@@ -48,6 +48,7 @@ export async function createPeerRuntime(cwd, options = {}) {
     messageStore,
     persistedState: persistedMessages,
   });
+  const projectScope = options.projectScope || await derivePeerProjectScope(cwd);
   let localEndpoint;
   let discoveredPeerIds = new Set();
 
@@ -59,12 +60,13 @@ export async function createPeerRuntime(cwd, options = {}) {
     summary: { ...summarizePeerRuntimeConfig(config), localPeerId },
     localPeerId,
     cwd,
+    projectScope,
     get localEndpoint() {
       return localEndpoint?.descriptor;
     },
     async refreshLocalPeers() {
       if (!config.enabled) return [];
-      const peers = await discoverLocalPeerEndpoints({ discoveryDir: options.discoveryDir, excludePeerId: localPeerId });
+      const peers = await discoverLocalPeerEndpoints({ discoveryDir: options.discoveryDir, excludePeerId: localPeerId, projectScope });
       const nextDiscoveredPeerIds = new Set(peers.map((peer) => peer.peerId));
       for (const peerId of discoveredPeerIds) {
         if (nextDiscoveredPeerIds.has(peerId)) continue;
@@ -82,6 +84,7 @@ export async function createPeerRuntime(cwd, options = {}) {
         const endpoint = createLocalPeerEndpoint({
           peerId: localPeerId,
           cwd,
+          projectScope,
           sessionId: options.sessionId || ctx.sessionId,
           role: localPeerProfile.role || options.role,
           persona: localPeerProfile.persona || options.persona,
@@ -111,6 +114,15 @@ export async function createPeerRuntime(cwd, options = {}) {
     recordInboundProgress(progress) {
       return inboundBridge ? inboundBridge.recordProgress(progress) : { ok: false, reason: "no active inbound peer task" };
     },
+    pendingInboundCount() {
+      return inboundBridge ? inboundBridge.pendingCount() : 0;
+    },
+    nudgeInboundIfIdle(input) {
+      return inboundBridge ? inboundBridge.nudgeActive(input) : { ok: false, reason: "no active inbound peer task" };
+    },
+    activeInboundState() {
+      return inboundBridge ? inboundBridge.activeState() : { queuedCount: 0 };
+    },
     async shutdown() {
       if (inboundBridge) {
         inboundBridge.dispose("Peer runtime shutting down");

package/src/peers/status.mjs

@@ -28,6 +28,7 @@ export function derivePeerRuntimeStatus(runtime = {}, options = {}) {
     source: runtime.source || runtime.summary?.source || "none",
     localPeerId: runtime.localPeerId || runtime.summary?.localPeerId || "unknown",
     localPeerIdSource: runtime.summary?.localPeerIdSource || runtime.config?.localPeerIdSource,
+    projectScope: runtime.projectScope,
     protocolVersion: endpoint?.protocolVersion || runtime.summary?.protocolVersion || runtime.config?.manifest?.protocolVersion,
     localTrust: endpoint?.trust || runtime.config?.manifest?.trust || runtime.summary?.manifest?.trust,
     localCapabilities,
@@ -56,7 +57,7 @@ export function formatPeerStatusLines(status = {}) {
   const capsText = capabilitySummary(status.localCapabilities);
   const lines = [
     line("state", color, `🔗 peers ${enabledText} · id ${status.localPeerId || "unknown"}${profileText ? ` · ${profileText}` : ""}${protocolText} · source ${status.source || "none"}`),
-    line("endpoint", status.endpointStatus === "listening" ? "success" : status.enabled ? "warning" : "muted", `endpoint ${status.endpointStatus || "unknown"} · auth ${status.authStatus || "unknown"}`),
+    line("endpoint", status.endpointStatus === "listening" ? "success" : status.enabled ? "warning" : "muted", `endpoint ${status.endpointStatus || "unknown"} · auth ${status.authStatus || "unknown"}${status.projectScope ? " · repo scoped" : ""}`),
     line("peers", status.activeCount > 0 ? "accent" : "muted", `peers discovered ${status.discoveredCount || 0} · active ${status.activeCount || 0} · configured ${status.configuredPeers || 0}${capsText ? ` · caps ${capsText}` : ""}`),
     line("messages", status.pendingCount > 0 ? "accent" : "muted", `messages pending ${status.pendingCount || 0}`),
   ];