pi-messenger 0.13.2 → 0.14.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [0.14.1] - 2026-04-04
+
+### Changed
+- Added a `promptSnippet` for `pi_messenger` so Pi 0.59+ includes it in the default tool prompt section and reliably surfaces Crew/coordination workflows.
+
+## [0.14.0] - 2026-04-03
+
+### Added
+- **`leave` action** — `pi_messenger({ action: "leave" })` now lets the current session leave the mesh without restarting pi. It releases reservations, auto-unclaims the session's active swarm claim, closes the messenger overlay, and allows later rejoin from the same session.
+
+### Fixed
+- **Leave guardrails for Crew state** — `leave` now refuses while project planning, autonomous work, or session-owned in-progress Crew tasks are still active, preventing stranded coordination state.
+- **Immutable-session cwd handling** — Registration, folder scoping, auto-register path matching, and messenger context now follow the live session cwd after pi runtime/session replacement instead of relying on `process.cwd()`.
+
 ## [0.13.2] - 2026-03-19
 
 ### Added

package/README.md

@@ -47,6 +47,7 @@ pi_messenger({ action: "join" })
 pi_messenger({ action: "reserve", paths: ["src/auth/"], reason: "Refactoring" })
 pi_messenger({ action: "send", to: "GoldFalcon", message: "auth is done" })
 pi_messenger({ action: "release" })
+pi_messenger({ action: "leave" })
 ```
 
 For multi-agent task orchestration from a PRD:
@@ -67,7 +68,7 @@ pi_messenger({ action: "review", target: "task-1" })    // Reviewer checks imple
 
 **Messaging** - Send messages between agents. Recipients wake up immediately and see the message as a steering prompt.
 
-**File Reservations** - Claim files or directories. Other agents get blocked with a clear message telling them who to coordinate with. Auto-releases on exit.
+**File Reservations** - Claim files or directories. Other agents get blocked with a clear message telling them who to coordinate with. Auto-releases on `leave` or exit.
 
 **Stuck Detection** - Agents idle too long with an open task or reservation are flagged as stuck. Peers get a notification.
 
@@ -251,6 +252,7 @@ Agent definitions live in `crew/agents/` within the extension. To customize one
 | Action | Description |
 |--------|-------------|
 | `join` | Join the agent mesh |
+| `leave` | Leave the mesh for the current session |
 | `list` | List agents with presence info |
 | `status` | Show your status or crew progress |
 | `whois` | Detailed info about an agent (`name` required) |

package/crew/index.ts

@@ -77,6 +77,9 @@ export async function executeCrewAction(
     case 'status':
       return handlers.executeStatus(state, dirs, ctx.cwd ?? process.cwd());
 
+    case 'leave':
+      return handlers.executeLeave(state, dirs, ctx);
+
     case 'list':
       return handlers.executeList(state, dirs, ctx.cwd ?? process.cwd(), { stuckThreshold: config?.stuckThreshold });
 

package/handlers.ts

@@ -26,6 +26,7 @@ import * as store from "./store.js";
 import * as crewStore from "./crew/store.js";
 import { getAutoRegisterPaths, saveAutoRegisterPaths, matchesAutoRegisterPath } from "./config.js";
 import { readFeedEvents, logFeedEvent, pruneFeed, formatFeedLine, isCrewEvent, type FeedEvent } from "./feed.js";
+import { isAutonomousForCwd, isPlanningForCwd } from "./crew/state.js";
 import { loadCrewConfig } from "./crew/utils/config.js";
 
 let messagesSentThisSession = 0;
@@ -127,6 +128,118 @@ export function executeJoin(
   });
 }
 
+export async function executeLeave(
+  state: MessengerState,
+  dirs: Dirs,
+  ctx: ExtensionContext,
+) {
+  if (!state.registered) {
+    return notRegisteredError();
+  }
+
+  const cwd = ctx.cwd ?? process.cwd();
+
+  if (isPlanningForCwd(cwd)) {
+    return result(
+      "Cannot leave while Crew planning is active for this project. Cancel it first with pi_messenger({ action: \"plan.cancel\" }).",
+      { mode: "leave", error: "planning_active" }
+    );
+  }
+
+  if (isAutonomousForCwd(cwd)) {
+    return result(
+      "Cannot leave while autonomous Crew work is active for this project. Stop it first with pi_messenger({ action: \"work.stop\" }).",
+      { mode: "leave", error: "autonomous_active" }
+    );
+  }
+
+  const inProgressTasks = crewStore
+    .getTasks(cwd)
+    .filter(task => task.status === "in_progress" && task.assigned_to === state.agentName)
+    .map(task => task.id);
+
+  if (inProgressTasks.length > 0) {
+    return result(
+      `Cannot leave while Crew task${inProgressTasks.length === 1 ? "" : "s"} assigned to you ${inProgressTasks.length === 1 ? "is" : "are"} still in progress: ${inProgressTasks.join(", ")}. Finish, block, or reset ${inProgressTasks.length === 1 ? "it" : "them"} first.`,
+      { mode: "leave", error: "crew_tasks_in_progress", taskIds: inProgressTasks }
+    );
+  }
+
+  const activeClaim = store.getAgentCurrentClaim(dirs, state.agentName);
+  let releasedClaim: { spec: string; taskId: string; reason?: string } | undefined;
+  if (activeClaim) {
+    const claimDisplay = displaySpecPath(activeClaim.spec, cwd);
+    try {
+      const unclaimResult = await store.unclaimTask(dirs, activeClaim.spec, activeClaim.taskId, state.agentName);
+      if (!store.isUnclaimSuccess(unclaimResult)) {
+        return result(
+          `Cannot leave because the active swarm claim ${activeClaim.taskId} in ${claimDisplay} could not be released. Resolve it first and retry.`,
+          {
+            mode: "leave",
+            error: unclaimResult.error,
+            activeClaim: { ...activeClaim, spec: claimDisplay },
+            ...(store.isUnclaimNotYours(unclaimResult) ? { claimedBy: unclaimResult.claimedBy } : {}),
+          }
+        );
+      }
+      releasedClaim = activeClaim;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return result(
+        `Cannot leave because the active swarm claim ${activeClaim.taskId} in ${claimDisplay} could not be released: ${message}`,
+        {
+          mode: "leave",
+          error: "unclaim_failed",
+          message,
+          activeClaim: { ...activeClaim, spec: claimDisplay },
+        }
+      );
+    }
+  }
+
+  const releasedReservations = state.reservations.map(r => r.pattern);
+  state.reservations = [];
+  store.updateRegistration(state, dirs, ctx);
+  for (const pattern of releasedReservations) {
+    logFeedEvent(cwd, state.agentName, "release", pattern);
+  }
+
+  try {
+    store.unregister(state, dirs);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return result(
+      `Could not leave pi-messenger: ${message}`,
+      { mode: "leave", error: "unregister_failed", message }
+    );
+  }
+
+  logFeedEvent(cwd, state.agentName, "leave");
+  store.stopWatcher(state);
+
+  if (ctx.hasUI) {
+    ctx.ui.setStatus("messenger", undefined);
+  }
+
+  const claimText = releasedClaim
+    ? `\nReleased claim: ${releasedClaim.taskId} in ${displaySpecPath(releasedClaim.spec, cwd)}`
+    : "";
+
+  return result(
+    `Left pi-messenger.${releasedReservations.length > 0 ? `\nReleased reservations: ${releasedReservations.join(", ")}` : ""}${claimText}`,
+    {
+      mode: "leave",
+      releasedReservations,
+      releasedClaim: releasedClaim
+        ? {
+            ...releasedClaim,
+            spec: displaySpecPath(releasedClaim.spec, cwd),
+          }
+        : undefined,
+    }
+  );
+}
+
 export function executeStatus(state: MessengerState, dirs: Dirs, cwd: string = process.cwd()) {
   if (!state.registered) {
     return notRegisteredError();

package/index.ts

@@ -80,7 +80,7 @@ export default function piMessengerExtension(pi: ExtensionAPI) {
   // State & Configuration
   // ===========================================================================
 
-  const config: MessengerConfig = loadConfig(process.cwd());
+  let config: MessengerConfig = loadConfig(process.cwd());
 
   const state: MessengerState = {
     agentName: process.env.PI_AGENT_NAME || "",
@@ -95,6 +95,7 @@ export default function piMessengerExtension(pi: ExtensionAPI) {
     broadcastHistory: [],
     seenSenders: new Map(),
     model: "",
+    cwd: process.cwd(),
     gitBranch: undefined,
     spec: undefined,
     scopeToFolder: config.scopeToFolder,
@@ -337,7 +338,7 @@ export default function piMessengerExtension(pi: ExtensionAPI) {
   // ===========================================================================
 
   function sendRegistrationContext(ctx: ExtensionContext): void {
-    const folder = extractFolder(process.cwd());
+    const folder = extractFolder(ctx.cwd ?? state.cwd);
     const locationPart = state.gitBranch
       ? `${folder} on ${state.gitBranch}`
       : folder;
@@ -360,6 +361,7 @@ export default function piMessengerExtension(pi: ExtensionAPI) {
 Usage (action-based API - preferred):
   // Coordination
   pi_messenger({ action: "join" })                              → Join mesh
+  pi_messenger({ action: "leave" })                             → Leave mesh for this session
   pi_messenger({ action: "status" })                            → Get status
   pi_messenger({ action: "list" })                              → List agents with presence
   pi_messenger({ action: "feed", limit: 20 })                   → Activity feed
@@ -390,6 +392,8 @@ Usage (action-based API - preferred):
   
   // Crew: Review
   pi_messenger({ action: "review", target: "task-1" })          → Review impl`,
+    promptSnippet:
+      "Use for multi-agent coordination and Crew workflows: join/status/feed, create plans, run work waves, manage tasks, reserve files, and message agents.",
     parameters: Type.Object({
       action: Type.Optional(Type.String({
         description: "Action to perform (e.g., 'join', 'plan', 'work', 'task.start')"
@@ -468,6 +472,13 @@ Usage (action-based API - preferred):
         sendRegistrationContext(ctx);
       }
 
+      if (action === "leave" && !state.registered) {
+        overlayHandle?.hide();
+        overlayHandle = null;
+        overlayTui = null;
+        overlayOpening = false;
+      }
+
       return result;
     }
   });
@@ -769,6 +780,11 @@ Usage (action-based API - preferred):
 
   pi.on("session_start", async (_event, ctx) => {
     latestCtx = ctx;
+    state.cwd = ctx.cwd ?? process.cwd();
+    config = loadConfig(state.cwd);
+    state.scopeToFolder = config.scopeToFolder;
+    nameTheme.theme = config.nameTheme;
+    nameTheme.customWords = config.nameWords;
     resetAutonomousContinueGuard();
     startStatusHeartbeat();
     for (const entry of ctx.sessionManager.getEntries()) {
@@ -776,7 +792,7 @@ Usage (action-based API - preferred):
         restoreAutonomousState(entry.data as Parameters<typeof restoreAutonomousState>[0]);
       }
     }
-    const { staleCleared } = restorePlanningState(ctx.cwd ?? process.cwd());
+    const { staleCleared } = restorePlanningState(state.cwd);
     if (staleCleared && ctx.hasUI) {
       ctx.ui.notify("Stale planning state cleared (planner process exited)", "warning");
     }
@@ -785,7 +801,7 @@ Usage (action-based API - preferred):
     try { fs.rmSync(join(homedir(), ".pi/agent/messenger/feed.jsonl"), { force: true }); } catch {}
 
     const shouldAutoRegister = config.autoRegister || 
-      matchesAutoRegisterPath(process.cwd(), config.autoRegisterPaths);
+      matchesAutoRegisterPath(state.cwd, config.autoRegisterPaths);
 
     if (!shouldAutoRegister) {
       maybeAutoOpenCrewOverlay(ctx);
@@ -793,7 +809,7 @@ Usage (action-based API - preferred):
     }
 
     if (store.register(state, dirs, ctx, nameTheme)) {
-      const cwd = ctx.cwd ?? process.cwd();
+      const cwd = state.cwd;
       store.startWatcher(state, dirs, deliverMessage);
       updateStatus(ctx);
       pruneFeed(cwd, config.feedRetention);
@@ -889,28 +905,6 @@ Usage (action-based API - preferred):
     });
   }
 
-  pi.on("session_switch", async (_event, ctx) => {
-    latestCtx = ctx;
-    resetAutonomousContinueGuard();
-    const { staleCleared } = restorePlanningState(ctx.cwd ?? process.cwd());
-    if (staleCleared && ctx.hasUI) {
-      ctx.ui.notify("Stale planning state cleared (planner process exited)", "warning");
-    }
-    recoverWatcherIfNeeded();
-    updateStatus(ctx);
-    maybeAutoOpenCrewOverlay(ctx);
-  });
-  pi.on("session_fork", async (_event, ctx) => {
-    latestCtx = ctx;
-    resetAutonomousContinueGuard();
-    const { staleCleared } = restorePlanningState(ctx.cwd ?? process.cwd());
-    if (staleCleared && ctx.hasUI) {
-      ctx.ui.notify("Stale planning state cleared (planner process exited)", "warning");
-    }
-    recoverWatcherIfNeeded();
-    updateStatus(ctx);
-    maybeAutoOpenCrewOverlay(ctx);
-  });
   pi.on("session_tree", async (_event, ctx) => {
     latestCtx = ctx;
     const { staleCleared } = restorePlanningState(ctx.cwd ?? process.cwd());
@@ -1101,7 +1095,12 @@ Usage (action-based API - preferred):
     if (recentTestTimer) { clearTimeout(recentTestTimer); recentTestTimer = null; }
     if (recentEditTimer) { clearTimeout(recentEditTimer); recentEditTimer = null; }
     store.stopWatcher(state);
-    store.unregister(state, dirs);
+    try {
+      store.unregister(state, dirs);
+    } catch {
+      // Safe to ignore during shutdown: the process is exiting, so any leftover
+      // registration will be cleaned up as stale on the next registry read.
+    }
   });
 
   // ===========================================================================

package/lib.ts

@@ -73,6 +73,7 @@ export interface MessengerState {
   broadcastHistory: AgentMailMessage[];
   seenSenders: Map<string, string>;
   model: string;
+  cwd: string;
   gitBranch?: string;
   spec?: string;
   scopeToFolder: boolean;
@@ -388,8 +389,8 @@ export function buildSelfRegistration(state: MessengerState): AgentRegistration
     name: state.agentName,
     pid: process.pid,
     sessionId: "",
-    cwd: process.cwd(),
     model: state.model,
+    cwd: state.cwd,
     startedAt: state.sessionStartedAt,
     gitBranch: state.gitBranch,
     spec: state.spec,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-messenger",
-  "version": "0.13.2",
+  "version": "0.14.1",
   "description": "Inter-agent messaging and file reservation system for pi coding agent",
   "type": "module",
   "author": "Nico Bailon",

package/skills/pi-messenger-crew/SKILL.md

@@ -9,9 +9,10 @@ Use pi-messenger for multi-agent coordination and Crew task orchestration.
 
 ## Quick Reference
 
-### Join the Mesh (Required First)
+### Join or Leave the Mesh
 ```typescript
 pi_messenger({ action: "join" })
+pi_messenger({ action: "leave" })
 ```
 
 ### Check Status

package/store.ts

@@ -167,7 +167,7 @@ export function getRegistrationPath(state: MessengerState, dirs: Dirs): string {
 export function getActiveAgents(state: MessengerState, dirs: Dirs): AgentRegistration[] {
   const now = Date.now();
   const excludeName = state.agentName;
-  const myCwd = normalizeCwd(process.cwd());
+  const myCwd = normalizeCwd(state.cwd);
   const scopeToFolder = state.scopeToFolder;
 
   // Cache key includes scopeToFolder and cwd for proper cache invalidation
@@ -339,7 +339,7 @@ export function register(state: MessengerState, dirs: Dirs, ctx: ExtensionContex
 
     ensureDirSync(getMyInbox(state, dirs));
 
-    const cwd = normalizeCwd(process.cwd());
+    const cwd = normalizeCwd(ctx.cwd ?? process.cwd());
     const gitBranch = getGitBranch(cwd);
     const now = new Date().toISOString();
     const registration: AgentRegistration = {
@@ -378,6 +378,7 @@ export function register(state: MessengerState, dirs: Dirs, ctx: ExtensionContex
     if (verified) {
       state.registered = true;
       state.model = ctx.model?.id ?? "unknown";
+      state.cwd = cwd;
       state.gitBranch = gitBranch;
       state.activity.lastActivityAt = now;
       invalidateAgentsCache();
@@ -426,6 +427,7 @@ export function updateRegistration(state: MessengerState, dirs: Dirs, ctx: Exten
     const currentModel = ctx.model?.id ?? reg.model;
     reg.model = currentModel;
     state.model = currentModel;
+    reg.cwd = state.cwd;
     reg.reservations = state.reservations.length > 0 ? state.reservations : undefined;
     if (state.spec) {
       reg.spec = state.spec;
@@ -452,6 +454,7 @@ export function flushActivityToRegistry(state: MessengerState, dirs: Dirs, ctx:
     const currentModel = ctx.model?.id ?? reg.model;
     reg.model = currentModel;
     state.model = currentModel;
+    reg.cwd = state.cwd;
     reg.session = { ...state.session };
     reg.activity = { ...state.activity };
     reg.statusMessage = state.statusMessage;
@@ -464,11 +467,15 @@ export function flushActivityToRegistry(state: MessengerState, dirs: Dirs, ctx:
 export function unregister(state: MessengerState, dirs: Dirs): void {
   if (!state.registered) return;
 
+  const regPath = getRegistrationPath(state, dirs);
   try {
-    fs.unlinkSync(getRegistrationPath(state, dirs));
-  } catch {
-    // Ignore errors
+    fs.unlinkSync(regPath);
+  } catch (error) {
+    if (fs.existsSync(regPath)) {
+      throw error;
+    }
   }
+
   state.registered = false;
   invalidateAgentsCache();
 }
@@ -515,7 +522,7 @@ export function renameAgent(
 
   processAllPendingMessages(state, dirs, deliverFn);
 
-  const cwd = normalizeCwd(process.cwd());
+  const cwd = normalizeCwd(ctx.cwd ?? process.cwd());
   const gitBranch = getGitBranch(cwd);
   const now = new Date().toISOString();
   const registration: AgentRegistration = {
@@ -598,6 +605,7 @@ export function renameAgent(
   }
 
   state.model = ctx.model?.id ?? "unknown";
+  state.cwd = cwd;
   state.gitBranch = gitBranch;
   state.sessionStartedAt = now;
   state.activity.lastActivityAt = now;