very-happy-cli 0.2.178 → 0.2.180

package/dist/sessionExitLifecycle-DFltxXU8.cjs

@@ -0,0 +1,148 @@
+'use strict';
+
+class MessageBuffer {
+  messages = [];
+  listeners = [];
+  nextId = 1;
+  addMessage(content, type = "assistant") {
+    const message = {
+      id: `msg-${this.nextId++}`,
+      timestamp: /* @__PURE__ */ new Date(),
+      content,
+      type
+    };
+    this.messages.push(message);
+    this.notifyListeners();
+  }
+  /**
+   * Update the last message of a specific type by appending content to it
+   * Useful for streaming responses where deltas should accumulate in one message
+   */
+  updateLastMessage(contentDelta, type = "assistant") {
+    for (let i = this.messages.length - 1; i >= 0; i--) {
+      if (this.messages[i].type === type) {
+        const oldMessage = this.messages[i];
+        const updatedMessage = {
+          ...oldMessage,
+          content: oldMessage.content + contentDelta
+        };
+        this.messages[i] = updatedMessage;
+        this.notifyListeners();
+        return;
+      }
+    }
+    this.addMessage(contentDelta, type);
+  }
+  /**
+   * Remove the last message of a specific type
+   * Useful for removing placeholder messages like "Thinking..." when actual response starts
+   */
+  removeLastMessage(type) {
+    for (let i = this.messages.length - 1; i >= 0; i--) {
+      if (this.messages[i].type === type) {
+        this.messages.splice(i, 1);
+        this.notifyListeners();
+        return true;
+      }
+    }
+    return false;
+  }
+  getMessages() {
+    return [...this.messages];
+  }
+  clear() {
+    this.messages = [];
+    this.nextId = 1;
+    this.notifyListeners();
+  }
+  onUpdate(listener) {
+    this.listeners.push(listener);
+    return () => {
+      const index = this.listeners.indexOf(listener);
+      if (index > -1) {
+        this.listeners.splice(index, 1);
+      }
+    };
+  }
+  notifyListeners() {
+    const messages = this.getMessages();
+    this.listeners.forEach((listener) => listener(messages));
+  }
+}
+
+const OFFLINE_EXIT_STAMP_TIMEOUT_MS = 3e3;
+async function settleSessionOnExit(sessionId, intent, deps) {
+  if (intent === "archive") {
+    deps.updateMetadata((currentMetadata) => ({
+      ...currentMetadata,
+      lifecycleState: "archived",
+      lifecycleStateSince: Date.now(),
+      archivedBy: "cli",
+      archiveReason: "User terminated"
+    }));
+  }
+  if (intent === "hibernate" && deps.hibernation) {
+    const stamp = deps.hibernation;
+    const handler = (currentMetadata) => ({ ...currentMetadata, hibernation: stamp });
+    const landed = deps.updateMetadataAndWait ? await deps.updateMetadataAndWait(handler) : (deps.updateMetadata(handler), false);
+    if (!landed) deps.log?.("[START] hibernation stamp not confirmed before going offline");
+  }
+  if (intent === "offline" && deps.exitCursor && deps.updateMetadataAndWait) {
+    const stamp = deps.exitCursor;
+    const landed = await deps.updateMetadataAndWait((currentMetadata) => ({ ...currentMetadata, exitCursor: stamp }), OFFLINE_EXIT_STAMP_TIMEOUT_MS);
+    if (!landed) deps.log?.("[START] offline exit cursor not confirmed before going offline");
+  }
+  deps.sendSessionDeath();
+  try {
+    if (intent === "archive") await deps.archiveSession(sessionId);
+    else await deps.deactivateSession(sessionId);
+  } catch (error) {
+    deps.log?.(`[START] ${intent === "archive" ? "archiveSession" : "deactivateSession"} during cleanup failed:`, error);
+  }
+}
+class SessionExitGate {
+  decided = null;
+  hibernateCommitted = false;
+  deferred = null;
+  /** Returns the intent to act on, or null when cleanup already started. */
+  claim(intent) {
+    if (this.decided === "hibernate" && !this.hibernateCommitted && intent !== "hibernate") {
+      if (this.deferred !== "archive") this.deferred = intent;
+      return null;
+    }
+    if (this.decided !== null) return null;
+    this.decided = intent;
+    return intent;
+  }
+  get current() {
+    return this.decided;
+  }
+  /** B-587: an exit was requested while the hibernation was deciding. */
+  get exitRequested() {
+    return this.deferred !== null;
+  }
+  /** B-587: the hibernation passed its last check — no more deferral. */
+  commitHibernate() {
+    if (this.decided === "hibernate") this.hibernateCommitted = true;
+  }
+  /**
+   * B-587: a hibernation that aborted hands the exit back. Returns the exit
+   * deferred meanwhile (the caller must run it now), or null.
+   */
+  release(intent) {
+    if (this.decided !== intent || intent === "hibernate" && this.hibernateCommitted) return null;
+    this.decided = null;
+    const deferred = this.deferred;
+    this.deferred = null;
+    return deferred;
+  }
+}
+function exitIntentFromArchiveFlag(archive) {
+  return archive ?? true ? "archive" : "offline";
+}
+
+exports.MessageBuffer = MessageBuffer;
+exports.OFFLINE_EXIT_STAMP_TIMEOUT_MS = OFFLINE_EXIT_STAMP_TIMEOUT_MS;
+exports.SessionExitGate = SessionExitGate;
+exports.exitIntentFromArchiveFlag = exitIntentFromArchiveFlag;
+exports.settleSessionOnExit = settleSessionOnExit;

package/dist/{sessionLock-DWX6BbiU.cjs → sessionLock-DRZUcKHT.cjs}

@@ -1,10 +1,11 @@
 'use strict';
 
-var persistence = require('./persistence-BfX72dne.cjs');
+var persistence = require('./persistence-9BMYspxG.cjs');
 var node_fs = require('node:fs');
 var path = require('node:path');
-var configuration = require('./configuration-4TGMrjul.cjs');
-var logger = require('./logger-DXTWlPzP.cjs');
+var configuration = require('./configuration-CYO-kPOS.cjs');
+var logger = require('./logger-CphW5nUE.cjs');
+var processTreeSnapshot = require('./processTreeSnapshot-mDbnuojn.cjs');
 
 const PROCESS_IDENTITY_FIELDS = [
   "hostPid",
@@ -41,7 +42,9 @@ function mergeReconnectMetadata(server, local, now) {
     archivedBy: void 0,
     archiveReason: void 0,
     // B-587: awake again — the hibernation stamp no longer describes us.
-    hibernation: void 0
+    hibernation: void 0,
+    // B-679: likewise the previous wrapper's offline-exit cursor.
+    exitCursor: void 0
   };
 }
 function applyServerSnapshot(response, snapshot) {
@@ -62,6 +65,23 @@ function applyHibernationReplay(response) {
   if (replaySeq === null) return { response, replaying: false };
   return { response: { ...response, seq: replaySeq }, replaying: true };
 }
+function readExitCursor(metadata) {
+  const raw = metadata?.exitCursor;
+  if (!raw || typeof raw !== "object") return null;
+  const { at, seq } = raw;
+  if (typeof at !== "number" || typeof seq !== "number" || !Number.isInteger(seq) || seq < 0) return null;
+  return { at, seq, v: 1 };
+}
+function exitCursorStamp(seq, now) {
+  return { at: now, seq, v: 1 };
+}
+function applyReconnectReplay(response) {
+  const wake = applyHibernationReplay(response);
+  if (wake.replaying) return { response: wake.response, replay: { source: "hibernation", seq: wake.response.seq } };
+  const cursor = readExitCursor(response.metadata);
+  if (!cursor || cursor.seq >= response.seq) return { response, replay: null };
+  return { response: { ...response, seq: cursor.seq }, replay: { source: "offline-exit", seq: cursor.seq } };
+}
 
 const runtime = {
   signal: (pid, signal) => process.kill(pid, signal),
@@ -100,6 +120,17 @@ function terminateProcess(pid, onSettled, impl = runtime, graceMs = 2e3) {
   }, graceMs);
   return true;
 }
+function terminateProcessTree(pid, onSettled, deps = {}) {
+  const snapshot = (deps.snapshot ?? ((root) => processTreeSnapshot.snapshotTree(root)))(pid);
+  const reap = deps.reap ?? ((entries) => processTreeSnapshot.killSurvivors(entries));
+  return (deps.terminate ?? terminateProcess)(pid, (stopped) => {
+    try {
+      reap(snapshot);
+    } catch {
+    }
+    onSettled(stopped);
+  });
+}
 
 const SESSION_LOCK_DIR = "session-locks";
 const defaultRuntime = () => ({
@@ -204,11 +235,13 @@ async function claimSessionOrExit(happySessionId, options) {
   process.on("exit", () => releaseSessionLock(happySessionId));
 }
 
-exports.applyHibernationReplay = applyHibernationReplay;
+exports.applyReconnectReplay = applyReconnectReplay;
 exports.applyServerSnapshot = applyServerSnapshot;
 exports.claimSessionOrExit = claimSessionOrExit;
+exports.exitCursorStamp = exitCursorStamp;
 exports.mergeReconnectMetadata = mergeReconnectMetadata;
 exports.processIdentityFields = processIdentityFields;
 exports.readSessionLock = readSessionLock;
 exports.terminateProcess = terminateProcess;
+exports.terminateProcessTree = terminateProcessTree;
 exports.withoutServerSnapshot = withoutServerSnapshot;

package/dist/{sessionLock-DBdtZGOL.mjs → sessionLock-nBXdJxJm.mjs}

@@ -1,8 +1,9 @@
-import { k as hibernationReplaySeq } from './persistence-DTk4sNpd.mjs';
+import { n as hibernationReplaySeq } from './persistence-BFUOHW5h.mjs';
 import { existsSync, readFileSync, unlinkSync, mkdirSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
-import { c as configuration, w as writePrivateFileSync } from './configuration-DVrb61aY.mjs';
-import { l as logger } from './logger--vAVtXB_.mjs';
+import { c as configuration, w as writePrivateFileSync } from './configuration-PxzEJumr.mjs';
+import { l as logger } from './logger-BUngm5Xg.mjs';
+import { s as snapshotTree, k as killSurvivors } from './processTreeSnapshot-CuLJDNC-.mjs';
 
 const PROCESS_IDENTITY_FIELDS = [
   "hostPid",
@@ -39,7 +40,9 @@ function mergeReconnectMetadata(server, local, now) {
     archivedBy: void 0,
     archiveReason: void 0,
     // B-587: awake again — the hibernation stamp no longer describes us.
-    hibernation: void 0
+    hibernation: void 0,
+    // B-679: likewise the previous wrapper's offline-exit cursor.
+    exitCursor: void 0
   };
 }
 function applyServerSnapshot(response, snapshot) {
@@ -60,6 +63,23 @@ function applyHibernationReplay(response) {
   if (replaySeq === null) return { response, replaying: false };
   return { response: { ...response, seq: replaySeq }, replaying: true };
 }
+function readExitCursor(metadata) {
+  const raw = metadata?.exitCursor;
+  if (!raw || typeof raw !== "object") return null;
+  const { at, seq } = raw;
+  if (typeof at !== "number" || typeof seq !== "number" || !Number.isInteger(seq) || seq < 0) return null;
+  return { at, seq, v: 1 };
+}
+function exitCursorStamp(seq, now) {
+  return { at: now, seq, v: 1 };
+}
+function applyReconnectReplay(response) {
+  const wake = applyHibernationReplay(response);
+  if (wake.replaying) return { response: wake.response, replay: { source: "hibernation", seq: wake.response.seq } };
+  const cursor = readExitCursor(response.metadata);
+  if (!cursor || cursor.seq >= response.seq) return { response, replay: null };
+  return { response: { ...response, seq: cursor.seq }, replay: { source: "offline-exit", seq: cursor.seq } };
+}
 
 const runtime = {
   signal: (pid, signal) => process.kill(pid, signal),
@@ -98,6 +118,17 @@ function terminateProcess(pid, onSettled, impl = runtime, graceMs = 2e3) {
   }, graceMs);
   return true;
 }
+function terminateProcessTree(pid, onSettled, deps = {}) {
+  const snapshot = (deps.snapshot ?? ((root) => snapshotTree(root)))(pid);
+  const reap = deps.reap ?? ((entries) => killSurvivors(entries));
+  return (deps.terminate ?? terminateProcess)(pid, (stopped) => {
+    try {
+      reap(snapshot);
+    } catch {
+    }
+    onSettled(stopped);
+  });
+}
 
 const SESSION_LOCK_DIR = "session-locks";
 const defaultRuntime = () => ({
@@ -202,4 +233,4 @@ async function claimSessionOrExit(happySessionId, options) {
   process.on("exit", () => releaseSessionLock(happySessionId));
 }
 
-export { applyServerSnapshot as a, applyHibernationReplay as b, claimSessionOrExit as c, mergeReconnectMetadata as m, processIdentityFields as p, readSessionLock as r, terminateProcess as t, withoutServerSnapshot as w };
+export { applyServerSnapshot as a, applyReconnectReplay as b, claimSessionOrExit as c, terminateProcessTree as d, exitCursorStamp as e, mergeReconnectMetadata as m, processIdentityFields as p, readSessionLock as r, terminateProcess as t, withoutServerSnapshot as w };

package/dist/{sessionOps-BAnr7n8t.cjs → sessionOps-BrGiU9-s.cjs}

@@ -1,12 +1,12 @@
 'use strict';
 
 var axios = require('axios');
-var configuration = require('./configuration-4TGMrjul.cjs');
+var configuration = require('./configuration-CYO-kPOS.cjs');
 var authRelay = require('./authRelay-Dy1qU9td.cjs');
-var controlClient = require('./controlClient-BTaZlbC6.cjs');
-var persistence = require('./persistence-BfX72dne.cjs');
+var controlClient = require('./controlClient-Bqv5v5OM.cjs');
+var persistence = require('./persistence-9BMYspxG.cjs');
 var node_crypto = require('node:crypto');
-var time = require('./time-A6zR3Iy6.cjs');
+var time = require('./time-Cjv0zxQO.cjs');
 var socket_ioClient = require('socket.io-client');
 var backgroundTaskActivity = require('./backgroundTaskActivity-CBvUdj39.cjs');
 
@@ -195,6 +195,10 @@ function agentPiece(body) {
   }
   return null;
 }
+function isSteerPrompt(body) {
+  const b = asRecord(body);
+  return !!b && asRecord(b.meta)?.delivery === "steer";
+}
 function userPromptText(body) {
   return isUserPrompt(body) ? body.content.text : null;
 }
@@ -214,6 +218,7 @@ function analyzeLatestTurn(entries, options = {}) {
   let lastMarker = null;
   let startedAfterPrompt = false;
   const emitsStarts = entries.some((entry) => sessionEnvelope(entry.body)?.ev?.t === "turn-start");
+  const steerAnchor = userIndex >= 0 && isSteerPrompt(entries[userIndex].body);
   for (let i = userIndex + 1; i < entries.length; i++) {
     const body = entries[i].body;
     if (options.anchor && isUserPrompt(body)) {
@@ -232,7 +237,7 @@ function analyzeLatestTurn(entries, options = {}) {
     }
     if (env?.ev?.t === "turn-end") {
       lastMarker = "end";
-      if (userIndex >= 0 && emitsStarts && !startedAfterPrompt) continue;
+      if (userIndex >= 0 && emitsStarts && !startedAfterPrompt && !steerAnchor) continue;
       ended = true;
       status = typeof env.ev.status === "string" ? env.ev.status : null;
       error = typeof env.ev.error === "string" ? env.ev.error : null;

package/dist/{sessionOps-BVoXe12O.mjs → sessionOps-C58iDeD5.mjs}

@@ -1,12 +1,12 @@
 import axios from 'axios';
-import { c as configuration } from './configuration-DVrb61aY.mjs';
+import { c as configuration } from './configuration-PxzEJumr.mjs';
 import { e as encodeBase64, g as encrypt, d as decodeBase64, h as decrypt } from './authRelay-DhQhkBvX.mjs';
-import { l as listDaemonSessions, s as stopDaemonSession } from './controlClient-BYKyGyxj.mjs';
-import { c as readCredentialsForConfiguredRelay, b as readPersistedSessions } from './persistence-DTk4sNpd.mjs';
+import { l as listDaemonSessions, f as stopDaemonSession } from './controlClient-DoeYovwP.mjs';
+import { b as readCredentialsForConfiguredRelay, c as readPersistedSessions } from './persistence-BFUOHW5h.mjs';
 import { randomUUID } from 'node:crypto';
-import { d as delay } from './time-BuGWTVP6.mjs';
+import { d as delay } from './time-D3ETL7Jb.mjs';
 import { io } from 'socket.io-client';
-import { b as backgroundTasksReport } from './backgroundTaskActivity-BVwJBl02.mjs';
+import { b as backgroundTasksReport } from './backgroundTaskActivity-8PdPxrvy.mjs';
 
 function sessionWebUrl(sessionId) {
   return `${configuration.webappUrl.replace(/\/+$/, "")}/session/${sessionId}`;
@@ -193,6 +193,10 @@ function agentPiece(body) {
   }
   return null;
 }
+function isSteerPrompt(body) {
+  const b = asRecord(body);
+  return !!b && asRecord(b.meta)?.delivery === "steer";
+}
 function userPromptText(body) {
   return isUserPrompt(body) ? body.content.text : null;
 }
@@ -212,6 +216,7 @@ function analyzeLatestTurn(entries, options = {}) {
   let lastMarker = null;
   let startedAfterPrompt = false;
   const emitsStarts = entries.some((entry) => sessionEnvelope(entry.body)?.ev?.t === "turn-start");
+  const steerAnchor = userIndex >= 0 && isSteerPrompt(entries[userIndex].body);
   for (let i = userIndex + 1; i < entries.length; i++) {
     const body = entries[i].body;
     if (options.anchor && isUserPrompt(body)) {
@@ -230,7 +235,7 @@ function analyzeLatestTurn(entries, options = {}) {
     }
     if (env?.ev?.t === "turn-end") {
       lastMarker = "end";
-      if (userIndex >= 0 && emitsStarts && !startedAfterPrompt) continue;
+      if (userIndex >= 0 && emitsStarts && !startedAfterPrompt && !steerAnchor) continue;
       ended = true;
       status = typeof env.ev.status === "string" ? env.ev.status : null;
       error = typeof env.ev.error === "string" ? env.ev.error : null;

package/dist/{sessionScanner-BtxoeluY.mjs → sessionScanner-Bm57LEXe.mjs}

@@ -1,10 +1,10 @@
-import { I as InvalidateSync } from './sync-DbW07iQS.mjs';
+import { I as InvalidateSync } from './sync-BvVhDO40.mjs';
 import { R as RawJSONLinesSchema } from './types-CkqAACXx.mjs';
 import { join } from 'node:path';
 import { statSync } from 'node:fs';
 import { r as readTranscriptIncrement, i as isValidTranscriptHint } from './transcriptCursor-B7T_gkQ0.mjs';
-import { l as logger } from './logger--vAVtXB_.mjs';
-import { s as startFileWatcher } from './startFileWatcher-CR09Snmz.mjs';
+import { l as logger } from './logger-BUngm5Xg.mjs';
+import { s as startFileWatcher } from './startFileWatcher-DXJ7yB5v.mjs';
 import { g as getProjectPath } from './path-D2wdaNSk.mjs';
 
 class Future {

package/dist/{sessionScanner-CDOYsEUD.cjs → sessionScanner-CaO8bLaG.cjs}

@@ -1,12 +1,12 @@
 'use strict';
 
-var sync = require('./sync-Dhmtk66S.cjs');
+var sync = require('./sync-Bn-idAoy.cjs');
 var types = require('./types-CRS-srZK.cjs');
 var path$1 = require('node:path');
 var node_fs = require('node:fs');
 var transcriptCursor = require('./transcriptCursor-DcXGLeSc.cjs');
-var logger = require('./logger-DXTWlPzP.cjs');
-var startFileWatcher = require('./startFileWatcher-Bqlqjt93.cjs');
+var logger = require('./logger-CphW5nUE.cjs');
+var startFileWatcher = require('./startFileWatcher-D9cYzZOq.cjs');
 var path = require('./path-B7zW-WwE.cjs');
 
 class Future {

package/dist/{sessions-C3sZJkzI.mjs → sessions-BXyBHo8n.mjs}

@@ -1,26 +1,27 @@
 import chalk from 'chalk';
-import { D as DEFAULT_RECENT_LIMIT, M as MAX_READ_LIMIT, l as listAccountSessions, a as listSessions, w as waitForTurnEnd, T as TurnWaitTimeoutError, r as readSessionTranscript, b as stopSession, c as resolvePermissionRequest, d as archiveSession } from './sessionOps-BVoXe12O.mjs';
+import { D as DEFAULT_RECENT_LIMIT, M as MAX_READ_LIMIT, l as listAccountSessions, a as listSessions, w as waitForTurnEnd, T as TurnWaitTimeoutError, r as readSessionTranscript, b as stopSession, c as resolvePermissionRequest, d as archiveSession } from './sessionOps-C58iDeD5.mjs';
 import { i as isValidSessionId } from './ids-DU6sLx4C.mjs';
-import { c as cliPeerSelf, l as listPeerSessions, s as sendPeerMessage, P as PEER_SCOPES } from './peerTools-3R9RUARX.mjs';
-import { b as readPersistedSessions } from './persistence-DTk4sNpd.mjs';
+import { c as cliPeerSelf, e as executeSessionPeerTool, l as listPeerSessions, s as sendPeerMessage, P as PEER_SCOPES } from './peerTools-BOlDRyhi.mjs';
+import { c as readPersistedSessions } from './persistence-BFUOHW5h.mjs';
 import { resolve } from 'node:path';
-import { f as fillForeignAccountRows, l as listRemoteSessions, a as listRemotePeers, w as waitForRemoteTurnEnd, r as readRemoteTranscript } from './remoteSessionClient-DRb2Jr5s.mjs';
+import { f as fillForeignAccountRows, l as listRemoteSessions, a as listRemotePeers, w as waitForRemoteTurnEnd, r as readRemoteTranscript } from './remoteSessionClient-PP-mOKmw.mjs';
 import 'axios';
-import './configuration-DVrb61aY.mjs';
+import './configuration-PxzEJumr.mjs';
 import 'node:fs';
 import 'node:os';
-import './package-B7B03ejW.mjs';
+import './package-7Ld1YMhh.mjs';
 import 'node:fs/promises';
 import './authRelay-DhQhkBvX.mjs';
 import 'node:crypto';
 import 'tweetnacl';
-import './controlClient-BYKyGyxj.mjs';
-import './logger--vAVtXB_.mjs';
+import './controlClient-DoeYovwP.mjs';
+import './logger-BUngm5Xg.mjs';
 import 'node:util';
-import './time-BuGWTVP6.mjs';
+import './time-D3ETL7Jb.mjs';
 import 'socket.io-client';
-import './backgroundTaskActivity-BVwJBl02.mjs';
+import './backgroundTaskActivity-8PdPxrvy.mjs';
 import 'zod';
+import './client-Ca5Pcgy_.mjs';
 
 const MACHINE_ID_RE = /^[a-zA-Z0-9_-]{1,128}$/;
 const ACTIONS = ["list", "read", "stop", "archive", "approve", "deny", "peers", "message"];
@@ -65,7 +66,7 @@ function parseSessionsArgs(args) {
     } else if (arg === "--scope") {
       const value = args[++i];
       if (value === void 0) throw new Error("--scope requires a value");
-      if (!PEER_SCOPES.includes(value)) throw new Error(`--scope must be one of ${PEER_SCOPES.join(", ")}`);
+      if (value !== "project" && !PEER_SCOPES.includes(value)) throw new Error(`--scope must be one of ${[...PEER_SCOPES, "project"].join(", ")}`);
       options.scope = value;
     } else if (arg === "--cwd") {
       const value = args[++i];
@@ -162,7 +163,7 @@ ${chalk.bold("Usage:")}
   very-happy sessions archive <id> [--json]
   very-happy sessions approve <id> <requestId> [--for-session] [--json]
   very-happy sessions deny <id> <requestId> [--reason <text>] [--json]
-  very-happy sessions peers [--scope repo|cwd|machine] [--cwd <dir>] [--machine <id>] [--json]
+  very-happy sessions peers [--scope repo|cwd|machine|project] [--cwd <dir>] [--machine <id>] [--json]
   very-happy sessions message <id> <text> [--reply-to <msgId>] [--machine <id>] [--json]
 
 ${chalk.bold("Actions:")}
@@ -200,7 +201,10 @@ ${chalk.bold("Actions:")}
              managed session's shell, else this CLI) and tells the peer how to
              reply. A session another machine spawned is delivered through
              that machine's daemon, with this host named in the header.
-             Refused for sessions that are not running, or terminal mirrors.
+             Refused for sessions that are not running, or terminal mirrors \u2014
+             except a session in the same project as the sender: there the
+             message is kept server-side and read on its next turn
+             (\`status: offline-stored\`, exit 0).
              \`delivered\` follows \`very-happy send\`: true only when a
              wrapper was attached before and after the POST (\`stored\` = it
              is on the server anyway).
@@ -225,7 +229,9 @@ ${chalk.bold("Options:")}
   --timeout <s>      read --wait only: give up after <s> seconds (default 600).
   --for-session      approve only: approved_for_session instead of approved.
   --reason <text>    deny only: reason forwarded to the wrapper.
-  --scope <s>        peers only: repo (default) | cwd | machine.
+  --scope <s>        peers only: repo (default) | cwd | machine | project
+                     (project = the other sessions of the calling session's
+                     Very Happy project on any machine).
   --cwd <dir>        peers only: directory the scope is computed from
                      (default: the process cwd, or HAPPY_SESSION_ID's cwd).
   --reply-to <id>    message only: the peer message id being answered.
@@ -249,7 +255,8 @@ ${chalk.bold("Exit codes:")}
   2  read --wait: the turn had not ended when --timeout ran out (the
      partial state is still printed)
   0  success (approve/deny: the wrapper acknowledged the verdict; check
-     \`settled\` in --json to see whether the request has left the pending set)
+     \`settled\` in --json to see whether the request has left the pending set;
+     message: delivered, or kept for a same-project session's next turn)
   1  bad arguments, unknown session, no machine of the account holds it (or
      its machine is offline / too old), request not pending, session not
      online, or the operation failed (including \`stop\` on a session the
@@ -282,6 +289,9 @@ function formatAccountSummaryLine(summary) {
   parts.push(summary.url);
   return parts.join(" ");
 }
+function peerMessageExitCode(result) {
+  return result.delivered || result.status === "offline-stored" ? 0 : 1;
+}
 function permissionFailureRecord(sessionId, requestId, error) {
   return { sessionId, requestId, error: error instanceof Error ? error.message : String(error) };
 }
@@ -373,8 +383,18 @@ async function handleSessionsCommand(args) {
       const cwd = options.cwd ? resolve(options.cwd) : process.cwd();
       const persisted = readPersistedSessions();
       const context = { self: () => cliPeerSelf(process.env, cwd, persisted), readPersisted: () => persisted };
+      if (options.action === "peers" && options.scope === "project") {
+        const self = cliPeerSelf(process.env, cwd, persisted);
+        const listing = await executeSessionPeerTool("session_peers", { scope: "project" }, context);
+        if (options.json) console.log(JSON.stringify(listing));
+        else if (!listing.project) console.log(`Not in a project (${self.sessionId}).`);
+        else if (listing.peers.length === 0) console.log(`No other sessions in project "${listing.project.name}".`);
+        else for (const peer of listing.peers) console.log([peer.sessionId, `[${peer.state ?? "?"}]`, peer.title ? `title="${peer.title}"` : "", peer.agent ? `agent=${peer.agent}` : "", peer.machine ? `machine=${peer.machine}` : "", peer.doing ? `doing="${peer.doing}"` : "", peer.url].filter(Boolean).join(" "));
+        process.exit(0);
+      }
       if (options.action === "peers") {
-        const listing = options.machine ? await listRemotePeers(options.machine, { ...options.scope ? { scope: options.scope } : {}, ...options.cwd ? { cwd: options.cwd } : {} }) : await listPeerSessions(context, options.scope ?? "repo");
+        const scope = options.scope === "project" ? void 0 : options.scope;
+        const listing = options.machine ? await listRemotePeers(options.machine, { ...scope ? { scope } : {}, ...options.cwd ? { cwd: options.cwd } : {} }) : await listPeerSessions(context, scope ?? "repo");
         if (options.json) {
           console.log(JSON.stringify(listing));
         } else if (listing.peers.length === 0) {
@@ -398,9 +418,11 @@ async function handleSessionsCommand(args) {
         const result = await sendPeerMessage(context, { to: target, body: options.text, replyTo: options.replyTo, ...options.machine ? { machineId: options.machine } : {} });
         if (options.json) console.log(JSON.stringify(result));
         else if (result.delivered) console.log(`Message ${result.messageId} delivered to ${target}${result.machine ? ` on ${result.machine.host}` : ""}
+${result.url}`);
+        else if (result.status === "offline-stored") console.log(`Message ${result.messageId} ${result.note ?? "stored"} (${target} is not running; same project)
 ${result.url}`);
         else console.error(chalk.yellow("Not delivered:"), result.error ?? `session is ${result.status}`, result.stored ? "(stored server-side, unread)" : "");
-        process.exit(result.delivered ? 0 : 1);
+        process.exit(peerMessageExitCode(result));
       } catch (error) {
         if (options.json) console.log(JSON.stringify({ delivered: false, to: target, error: error instanceof Error ? error.message : String(error) }));
         throw error;
@@ -504,4 +526,4 @@ ${result.url}`);
   }
 }
 
-export { SESSIONS_HELP, handleSessionsCommand, parseSessionsArgs, permissionFailureRecord };
+export { SESSIONS_HELP, handleSessionsCommand, parseSessionsArgs, peerMessageExitCode, permissionFailureRecord };