@cryptolibertus/pi-peer 0.3.3 → 0.3.6

package/README.md

@@ -15,8 +15,11 @@ pi install ./packages/pi-peer
 - `/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
+- `pi-peer-publish` skill for safe npm release checks, version bumping, tag push, publish, and verification
 
 ## Setup and health checks
 
@@ -28,7 +31,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. `/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
 
@@ -58,15 +61,61 @@ The board is stored locally at `.pi/peer-goals.json`; outbound message snapshots
 
 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
+
+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.
+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

@@ -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,10 +44,13 @@ 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;
   });
 
@@ -581,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?.();
 }
 
@@ -593,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.3",
+  "version": "0.3.6",
   "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/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/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}`),
   ];

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;
+  }
+}