very-happy-cli 0.2.165 → 0.2.167

package/README.md

@@ -161,7 +161,7 @@ The web client URL follows the same precedence (`HAPPY_WEBAPP_URL`, then
 
 Base managed Claude sessions receive `change_title`, `copy_to_clipboard`,
 `open_preview`, and `report_progress`. The managed Codex, Gemini, and ACP bridge
-exposes the first three except progress. For a plain `claude`, the standalone
+exposes the same four. For a plain `claude`, the standalone
 command is intentionally clipboard-only:
 
 ```bash

package/dist/{AcpBackend-DCfNt9bD.cjs → AcpBackend-D1IKJGz_.cjs}

@@ -3,10 +3,10 @@
 var node_child_process = require('node:child_process');
 var sdk = require('@agentclientprotocol/sdk');
 var node_crypto = require('node:crypto');
-var logger = require('./logger-D0hkk7Vo.cjs');
-var time = require('./time-BbzJ7PJQ.cjs');
+var logger = require('./logger-B_MWPbZz.cjs');
+var time = require('./time-BXvtjhe9.cjs');
 var contentLogMetadata = require('./contentLogMetadata-ZSFk_NjQ.cjs');
-var _package = require('./package-UkmvSFsg.cjs');
+var _package = require('./package-C9ZP9bpX.cjs');
 
 function acpImageBlocks(attachments, supportsImages) {
   return attachments.filter((file) => ["image/jpeg", "image/png", "image/gif", "image/webp"].includes(file.mimeType)).map((file) => {

package/dist/{AcpBackend-C11FnVw5.mjs → AcpBackend-kFZlee5E.mjs}

@@ -1,10 +1,10 @@
 import { spawn } from 'node:child_process';
 import { ndJsonStream, ClientSideConnection } from '@agentclientprotocol/sdk';
 import { randomUUID } from 'node:crypto';
-import { l as logger } from './logger-CknSVkIe.mjs';
-import { d as delay } from './time-v1Y_qEJp.mjs';
+import { l as logger } from './logger-CbBv3q_b.mjs';
+import { d as delay } from './time-PG5Dfwdv.mjs';
 import { c as contentLogMetadata, e as errorLogMetadata } from './contentLogMetadata-BlWI0egu.mjs';
-import { p as packageJson } from './package-VIUXrYZ1.mjs';
+import { p as packageJson } from './package-DU1DxhH9.mjs';
 
 function acpImageBlocks(attachments, supportsImages) {
   return attachments.filter((file) => ["image/jpeg", "image/png", "image/gif", "image/webp"].includes(file.mimeType)).map((file) => {

package/dist/{AcpSessionManager-BQnDJvct.mjs → AcpSessionManager-B7FIrsys.mjs}

@@ -1,5 +1,5 @@
 import { createId } from '@paralleldrive/cuid2';
-import { s as streamKeyOf, e as createEnvelope } from './index-vVWpCoTr.mjs';
+import { s as streamKeyOf, c as createEnvelope } from './index-B0HEEYGh.mjs';
 
 function turnOptions(turnId, time) {
   return turnId ? { turn: turnId, time } : { time };

package/dist/{AcpSessionManager-9yN2iH4b.cjs → AcpSessionManager-Zf00QnlL.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
 var cuid2 = require('@paralleldrive/cuid2');
-var index = require('./index-DqlyNgt4.cjs');
+var index = require('./index-C9hI8a10.cjs');
 
 function turnOptions(turnId, time) {
   return turnId ? { turn: turnId, time } : { time };

package/dist/{BasePermissionHandler-BwQHxl6M.cjs → BasePermissionHandler-DHxYAK5L.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var logger = require('./logger-D0hkk7Vo.cjs');
+var logger = require('./logger-B_MWPbZz.cjs');
 
 class BasePermissionHandler {
   pendingRequests = /* @__PURE__ */ new Map();

package/dist/{BasePermissionHandler-CwJ48yiB.mjs → BasePermissionHandler-DS0kRTNI.mjs}

@@ -1,4 +1,4 @@
-import { l as logger } from './logger-CknSVkIe.mjs';
+import { l as logger } from './logger-CbBv3q_b.mjs';
 
 class BasePermissionHandler {
   pendingRequests = /* @__PURE__ */ new Map();

package/dist/{BaseReasoningProcessor-ClF2g1qz.mjs → BaseReasoningProcessor-BRtCCt7q.mjs}

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { l as logger } from './logger-CknSVkIe.mjs';
+import { l as logger } from './logger-CbBv3q_b.mjs';
 
 class BaseReasoningProcessor {
   accumulator = "";

package/dist/{BaseReasoningProcessor-81lf_M8G.cjs → BaseReasoningProcessor-CsjVdt_H.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
 var node_crypto = require('node:crypto');
-var logger = require('./logger-D0hkk7Vo.cjs');
+var logger = require('./logger-B_MWPbZz.cjs');
 
 class BaseReasoningProcessor {
   accumulator = "";

package/dist/{agentGuidance-CQuNlNx8.mjs → agentGuidance-BDYt2Qy2.mjs}

@@ -5,6 +5,7 @@ const AGENT_GUIDANCE = (() => trimIdent(`
 
     - Terminal output is not a good delivery channel. When the user asks for a piece of text ("copy that", "give me X", "\u590D\u5236\u7ED9\u6211", "\u53D1\u6211"), hand it over with mcp__happy__copy_to_clipboard instead of printing it for them to select by hand.
     - When you produce or want to show a FILE (a document you wrote, a report, an image, a PDF, a diff), call mcp__happy__open_preview with its path instead of cat-ing it. Their client opens the rendered file.
+    - If the user wants to GET a file (any type: zip, docx, binary), pass download: true to mcp__happy__open_preview. Zip a directory first.
 
     Judgement, not reflex: use these when the user's goal is to RECEIVE something. If they are asking a question you can just answer, answer it. Do not preview a file you only read for your own reasoning, and do not preview the same file repeatedly within a turn.
 
@@ -12,9 +13,10 @@ const AGENT_GUIDANCE = (() => trimIdent(`
 `))();
 const PREVIEW_TOOL_NAME = "open_preview";
 const PREVIEW_TOOL_TITLE = "Open File Preview for the User";
-const PREVIEW_TOOL_DESCRIPTION = 'Open a file in the preview panel of every web client the user currently has open. Use this whenever you produce or want to show the user a file: a document or report you just wrote, a generated image or diagram, a PDF, a data file, or a source file you want them to look at. Trigger phrases include: "write me a doc", "show me that file", "let me see it", "\u5199\u4E2A\u6587\u6863", "\u7ED9\u6211\u770B\u770B\u8FD9\u4E2A\u6587\u4EF6", "\u6253\u5F00\u770B\u4E0B". Pass an absolute path (or one starting with ~). The file is read on this machine and rendered in their browser \u2014 markdown is rendered, images and PDFs are displayed, other text is syntax-highlighted. Prefer this over printing file contents to the terminal, which the user is probably not looking at. NOTE: this only requests that their client open the file; it cannot confirm the user actually looked at it, so do not assume they have seen it.';
+const PREVIEW_TOOL_DESCRIPTION = 'Open a file in the preview panel of every web client the user currently has open. Use this whenever you produce or want to show the user a file: a document or report you just wrote, a generated image or diagram, a PDF, a data file, or a source file you want them to look at. Trigger phrases include: "write me a doc", "show me that file", "let me see it", "\u5199\u4E2A\u6587\u6863", "\u7ED9\u6211\u770B\u770B\u8FD9\u4E2A\u6587\u4EF6", "\u6253\u5F00\u770B\u4E0B". Pass an absolute path (or one starting with ~). The file is read on this machine and rendered in their browser \u2014 markdown is rendered, images and PDFs are displayed, other text is syntax-highlighted. Prefer this over printing file contents to the terminal, which the user is probably not looking at. Set download: true when the user wants to GET the file rather than read it \u2014 any type, including zip archives, Word/Excel/PowerPoint documents, binaries and installers ("send me the file", "let me download it", "\u7ED9\u6211\u4E0B\u8F7D", "\u53D1\u6211\u8FD9\u4E2A\u6587\u4EF6"). Their client then shows a prominent download button (and may start the download on desktop). Only single regular files can be downloaded: zip a directory first and pass the archive. The web download limit is 50 MiB; compress or split anything larger. NOTE: this only requests that their client open the file; it cannot confirm the user actually looked at it or downloaded it, so do not assume they have.';
+const PREVIEW_DOWNLOAD_PARAM_DESCRIPTION = "true when the user wants to download/receive the file itself (any type) rather than just read it";
 const REPORT_PROGRESS_TOOL_NAME = "report_progress";
 const REPORT_PROGRESS_TOOL_TITLE = "Report Progress to the Task Board";
 const REPORT_PROGRESS_TOOL_DESCRIPTION = `Report what you are doing to the user's task board, so they can see the state of this session at a glance without reading the transcript. Call it at meaningful milestones only: when you start substantive work, when you get blocked and need the user, when something is ready for their review, and when you are done. Do NOT call it after every tool call or every file edit \u2014 it is a status line, not a log. Set attention to "blocked" when you cannot proceed without the user, "review" when you want them to look at something, and "none" for ordinary progress. Keep progress to one short line describing the current state (the user reads it on a card).`;
 
-export { AGENT_GUIDANCE as A, PREVIEW_TOOL_NAME as P, REPORT_PROGRESS_TOOL_NAME as R, PREVIEW_TOOL_TITLE as a, PREVIEW_TOOL_DESCRIPTION as b, REPORT_PROGRESS_TOOL_TITLE as c, REPORT_PROGRESS_TOOL_DESCRIPTION as d };
+export { AGENT_GUIDANCE as A, PREVIEW_TOOL_NAME as P, REPORT_PROGRESS_TOOL_NAME as R, PREVIEW_TOOL_TITLE as a, PREVIEW_TOOL_DESCRIPTION as b, PREVIEW_DOWNLOAD_PARAM_DESCRIPTION as c, REPORT_PROGRESS_TOOL_TITLE as d, REPORT_PROGRESS_TOOL_DESCRIPTION as e };

package/dist/{agentGuidance-B5NATuFa.cjs → agentGuidance-BtBx2xxE.cjs}

@@ -7,6 +7,7 @@ const AGENT_GUIDANCE = (() => trimIdent.trimIdent(`
 
     - Terminal output is not a good delivery channel. When the user asks for a piece of text ("copy that", "give me X", "\u590D\u5236\u7ED9\u6211", "\u53D1\u6211"), hand it over with mcp__happy__copy_to_clipboard instead of printing it for them to select by hand.
     - When you produce or want to show a FILE (a document you wrote, a report, an image, a PDF, a diff), call mcp__happy__open_preview with its path instead of cat-ing it. Their client opens the rendered file.
+    - If the user wants to GET a file (any type: zip, docx, binary), pass download: true to mcp__happy__open_preview. Zip a directory first.
 
     Judgement, not reflex: use these when the user's goal is to RECEIVE something. If they are asking a question you can just answer, answer it. Do not preview a file you only read for your own reasoning, and do not preview the same file repeatedly within a turn.
 
@@ -14,12 +15,14 @@ const AGENT_GUIDANCE = (() => trimIdent.trimIdent(`
 `))();
 const PREVIEW_TOOL_NAME = "open_preview";
 const PREVIEW_TOOL_TITLE = "Open File Preview for the User";
-const PREVIEW_TOOL_DESCRIPTION = 'Open a file in the preview panel of every web client the user currently has open. Use this whenever you produce or want to show the user a file: a document or report you just wrote, a generated image or diagram, a PDF, a data file, or a source file you want them to look at. Trigger phrases include: "write me a doc", "show me that file", "let me see it", "\u5199\u4E2A\u6587\u6863", "\u7ED9\u6211\u770B\u770B\u8FD9\u4E2A\u6587\u4EF6", "\u6253\u5F00\u770B\u4E0B". Pass an absolute path (or one starting with ~). The file is read on this machine and rendered in their browser \u2014 markdown is rendered, images and PDFs are displayed, other text is syntax-highlighted. Prefer this over printing file contents to the terminal, which the user is probably not looking at. NOTE: this only requests that their client open the file; it cannot confirm the user actually looked at it, so do not assume they have seen it.';
+const PREVIEW_TOOL_DESCRIPTION = 'Open a file in the preview panel of every web client the user currently has open. Use this whenever you produce or want to show the user a file: a document or report you just wrote, a generated image or diagram, a PDF, a data file, or a source file you want them to look at. Trigger phrases include: "write me a doc", "show me that file", "let me see it", "\u5199\u4E2A\u6587\u6863", "\u7ED9\u6211\u770B\u770B\u8FD9\u4E2A\u6587\u4EF6", "\u6253\u5F00\u770B\u4E0B". Pass an absolute path (or one starting with ~). The file is read on this machine and rendered in their browser \u2014 markdown is rendered, images and PDFs are displayed, other text is syntax-highlighted. Prefer this over printing file contents to the terminal, which the user is probably not looking at. Set download: true when the user wants to GET the file rather than read it \u2014 any type, including zip archives, Word/Excel/PowerPoint documents, binaries and installers ("send me the file", "let me download it", "\u7ED9\u6211\u4E0B\u8F7D", "\u53D1\u6211\u8FD9\u4E2A\u6587\u4EF6"). Their client then shows a prominent download button (and may start the download on desktop). Only single regular files can be downloaded: zip a directory first and pass the archive. The web download limit is 50 MiB; compress or split anything larger. NOTE: this only requests that their client open the file; it cannot confirm the user actually looked at it or downloaded it, so do not assume they have.';
+const PREVIEW_DOWNLOAD_PARAM_DESCRIPTION = "true when the user wants to download/receive the file itself (any type) rather than just read it";
 const REPORT_PROGRESS_TOOL_NAME = "report_progress";
 const REPORT_PROGRESS_TOOL_TITLE = "Report Progress to the Task Board";
 const REPORT_PROGRESS_TOOL_DESCRIPTION = `Report what you are doing to the user's task board, so they can see the state of this session at a glance without reading the transcript. Call it at meaningful milestones only: when you start substantive work, when you get blocked and need the user, when something is ready for their review, and when you are done. Do NOT call it after every tool call or every file edit \u2014 it is a status line, not a log. Set attention to "blocked" when you cannot proceed without the user, "review" when you want them to look at something, and "none" for ordinary progress. Keep progress to one short line describing the current state (the user reads it on a card).`;
 
 exports.AGENT_GUIDANCE = AGENT_GUIDANCE;
+exports.PREVIEW_DOWNLOAD_PARAM_DESCRIPTION = PREVIEW_DOWNLOAD_PARAM_DESCRIPTION;
 exports.PREVIEW_TOOL_DESCRIPTION = PREVIEW_TOOL_DESCRIPTION;
 exports.PREVIEW_TOOL_NAME = PREVIEW_TOOL_NAME;
 exports.PREVIEW_TOOL_TITLE = PREVIEW_TOOL_TITLE;

package/dist/{agentHome-DvR176E5.mjs → agentHome-Ct-VXFeG.mjs}

@@ -1,13 +1,13 @@
 import chalk from 'chalk';
 import { homedir } from 'node:os';
-import { readSettings, updateSettings } from './persistence-DujtUH94.mjs';
+import { r as readSettings, u as updateSettings } from './persistence-ON0zpHfb.mjs';
 import 'node:fs';
-import './logger-CknSVkIe.mjs';
+import './logger-CbBv3q_b.mjs';
 import { d as describeAgentHome, p as probeLoginShellEnv, r as resolveAgentHomes, e as expandHomePath, A as AGENT_HOME_ENV_NAMES } from './loginShellEnv-Dw8M7tkI.mjs';
 import 'node:fs/promises';
-import './configuration-L1qcGTFM.mjs';
+import './configuration-WspKd2C2.mjs';
 import 'node:path';
-import './package-VIUXrYZ1.mjs';
+import './package-DU1DxhH9.mjs';
 import 'zod';
 import './authRelay-DSAvg1uv.mjs';
 import 'node:crypto';

package/dist/{agentHome-D3Nn82kI.cjs → agentHome-DeAWzhSe.cjs}

@@ -2,14 +2,14 @@
 
 var chalk = require('chalk');
 var os = require('node:os');
-var persistence = require('./persistence-C6ztVW1W.cjs');
+var persistence = require('./persistence-BYGl0QYw.cjs');
 require('node:fs');
-require('./logger-D0hkk7Vo.cjs');
+require('./logger-B_MWPbZz.cjs');
 var loginShellEnv = require('./loginShellEnv-BkuYtExZ.cjs');
 require('node:fs/promises');
-require('./configuration-BE61XNsg.cjs');
+require('./configuration-C3piBtxY.cjs');
 require('node:path');
-require('./package-UkmvSFsg.cjs');
+require('./package-C9ZP9bpX.cjs');
 require('zod');
 require('./authRelay-BdYkC1Po.cjs');
 require('node:crypto');

package/dist/{api-AzdzTKFs.cjs → api-BZYLRDM9.cjs}

@@ -1,22 +1,22 @@
 'use strict';
 
 var axios = require('axios');
-var logger = require('./logger-D0hkk7Vo.cjs');
-var lidState = require('./lidState-z9ekRpZu.cjs');
+var logger = require('./logger-B_MWPbZz.cjs');
+var lidState = require('./lidState-Bc2K9H9l.cjs');
 var node_events = require('node:events');
 var socket_ioClient = require('socket.io-client');
-var attachmentLimits = require('./attachmentLimits-eJZ4ZBjF.cjs');
+var attachmentLimits = require('./attachmentLimits-BEYEEBm8.cjs');
 var authRelay = require('./authRelay-BdYkC1Po.cjs');
 var limits = require('./limits-C-a7gr04.cjs');
-var time = require('./time-BbzJ7PJQ.cjs');
-var configuration = require('./configuration-BE61XNsg.cjs');
+var time = require('./time-BXvtjhe9.cjs');
+var configuration = require('./configuration-C3piBtxY.cjs');
 var node_crypto = require('node:crypto');
-var index = require('./index-DqlyNgt4.cjs');
-var registerCommonHandlers = require('./registerCommonHandlers--8ds2auE.cjs');
+var index = require('./index-C9hI8a10.cjs');
+var registerCommonHandlers = require('./registerCommonHandlers-DVYB3iVn.cjs');
 var cuid2 = require('@paralleldrive/cuid2');
-var sync = require('./sync-DwUUGGFz.cjs');
+var sync = require('./sync-Bvc-vh6C.cjs');
 var backgroundTaskActivity = require('./backgroundTaskActivity-CBvUdj39.cjs');
-var controlClient = require('./controlClient-RWTlQA4_.cjs');
+var controlClient = require('./controlClient-BI6Fw3fQ.cjs');
 var contentLogMetadata = require('./contentLogMetadata-ZSFk_NjQ.cjs');
 var chalk = require('chalk');
 
@@ -1590,6 +1590,14 @@ class ApiSessionClient extends node_events.EventEmitter {
     }
   }
   routeIncomingMessage(message, sourceLocalId) {
+    if (this.inboundFrozen) {
+      logger.logger.debug(`[API] Hibernating: holding inbound ${sourceLocalId ?? "(no localId)"}`);
+      this.frozenInbound.push({ message, sourceLocalId });
+      this.inboundRoutedDuringCommit = true;
+      return;
+    }
+    this.inboundRoutedDuringCommit = true;
+    this.noteActivity();
     if (sourceLocalId) this.promptQueueDrain?.onInbound(sourceLocalId);
     const messageWithSource = sourceLocalId && typeof message === "object" && message !== null ? { ...message, localKey: message.localKey ?? sourceLocalId } : message;
     const userResult = attachmentLimits.UserMessageSchema.safeParse(messageWithSource);
@@ -1835,6 +1843,7 @@ class ApiSessionClient extends node_events.EventEmitter {
     }
   }
   enqueueMessage(content, invalidate = true, localId) {
+    this.noteActivity();
     const encrypted = authRelay.encodeBase64(authRelay.encrypt(this.encryptionKey, this.encryptionVariant, content));
     this.pendingOutbox.push({
       content: encrypted,
@@ -2011,6 +2020,52 @@ class ApiSessionClient extends node_events.EventEmitter {
     };
     this.enqueueMessage(content);
   }
+  // ── B-587 hibernation support ──────────────────────────────────────────
+  /** Last user/agent activity this wrapper saw (spec §2.1). */
+  lastActivity = Date.now();
+  inboundFrozen = false;
+  frozenInbound = [];
+  heartbeatsMuted = false;
+  lastHeartbeat = 0;
+  get lastHeartbeatAt() {
+    return this.lastHeartbeat;
+  }
+  muteHeartbeats() {
+    this.heartbeatsMuted = true;
+  }
+  unmuteHeartbeats() {
+    this.heartbeatsMuted = false;
+  }
+  inboundRoutedDuringCommit = false;
+  noteActivity(now = Date.now()) {
+    if (now > this.lastActivity) this.lastActivity = now;
+  }
+  get lastActivityAt() {
+    return this.lastActivity;
+  }
+  /** The message cursor (highest seq this wrapper has seen). */
+  get messageCursor() {
+    return this.lastSeq;
+  }
+  /** Start watching for inbound routed during the hibernation commit window. */
+  beginHibernationCommit() {
+    this.inboundRoutedDuringCommit = false;
+  }
+  /** Was any inbound message routed since beginHibernationCommit()? */
+  inboundRoutedSinceCommit() {
+    return this.inboundRoutedDuringCommit;
+  }
+  /** Stop routing inbound messages; the next wrapper replays them (spec §3/§4). */
+  freezeInbound() {
+    this.inboundFrozen = true;
+  }
+  /** An aborted hibernation: route whatever arrived while frozen, in order. */
+  unfreezeInbound() {
+    this.inboundFrozen = false;
+    const held = this.frozenInbound;
+    this.frozenInbound = [];
+    for (const item of held) this.routeIncomingMessage(item.message, item.sourceLocalId);
+  }
   /**
    * Send a ping message to keep the connection alive
    */
@@ -2029,11 +2084,14 @@ class ApiSessionClient extends node_events.EventEmitter {
     }));
   });
   keepAlive(thinking, mode, backgroundTasks) {
+    if (this.heartbeatsMuted) return;
+    this.lastHeartbeat = Date.now();
     if (process.env.DEBUG) {
       logger.logger.debug(`[API] Sending keep alive message: ${thinking}`);
     }
     this.turnReporter.observe(thinking);
     if (backgroundTasks) this.backgroundTaskReporter.observe(backgroundTasks);
+    if (thinking || (backgroundTasks?.length ?? 0) > 0) this.noteActivity();
     this.socket.volatile.emit("session-alive", {
       sid: this.sessionId,
       time: Date.now(),
@@ -2112,14 +2170,16 @@ class ApiSessionClient extends node_events.EventEmitter {
    * payload on this channel is (clipboard, fs RPC) — and a path leaks
    * project/client names and directory structure.
    */
-  pushFilePreview(path, mode = "file") {
+  pushFilePreview(path, mode = "file", intent) {
     if (!this.socket.connected) {
       return { delivered: false, error: "not connected to the server" };
     }
     this.socket.emit("file-preview-push", {
       payload: authRelay.encodeBase64(authRelay.encrypt(this.encryptionKey, this.encryptionVariant, path)),
       enc: true,
-      mode
+      mode,
+      // B-562: only present for downloads, so a plain preview keeps the old wire shape.
+      ...intent ? { intent } : {}
     });
     return { delivered: true };
   }
@@ -2224,7 +2284,26 @@ class ApiSessionClient extends node_events.EventEmitter {
     });
   }
   updateMetadata(handler) {
-    this.metadataLock.inLock(async () => {
+    void this.writeMetadata(handler);
+  }
+  /**
+   * B-587: the same write, awaitable with a ceiling — the hibernation stamp
+   * must land before `session-end`. Resolves false on timeout (the write
+   * itself keeps retrying in the background, exactly like updateMetadata).
+   */
+  async updateMetadataAndWait(handler, timeoutMs = 1e4) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(() => resolve(false), timeoutMs);
+    });
+    try {
+      return await Promise.race([this.writeMetadata(handler).then(() => true), timeout]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  writeMetadata(handler) {
+    return this.metadataLock.inLock(async () => {
       let rateRefusals = 0;
       await time.backoff(async () => {
         let updated = handler(this.metadata);
@@ -2270,6 +2349,7 @@ class ApiSessionClient extends node_events.EventEmitter {
           this.agentState = answer.agentState ? authRelay.decrypt(this.encryptionKey, this.encryptionVariant, authRelay.decodeBase64(answer.agentState)) : null;
           this.agentStateVersion = answer.version;
           rateRefusals = 0;
+          if (Object.keys(this.agentState?.requests ?? {}).length > 0) this.noteActivity();
           logger.logger.debug("Agent state updated", this.agentState);
         } else if (answer.result === "version-mismatch") {
           if (answer.version > this.agentStateVersion) {
@@ -3086,7 +3166,7 @@ class ApiClient {
     return new ApiSessionClient(this.credential.token, session, opts);
   }
   async machineSyncClient(machine) {
-    const { ApiMachineClient } = await Promise.resolve().then(function () { return require('./apiMachine-B_cJldfa.cjs'); });
+    const { ApiMachineClient } = await Promise.resolve().then(function () { return require('./apiMachine-BgMxGPsR.cjs'); });
     return new ApiMachineClient(this.credential.token, machine);
   }
   push() {

package/dist/{api-DTVPUE7g.mjs → api-CReZazeT.mjs}

@@ -1,20 +1,20 @@
 import axios from 'axios';
-import { l as logger, r as redactLogValue } from './logger-CknSVkIe.mjs';
-import { R as RpcHandlerManager, a as answerSocketRequest, c as connectGuarded, s as socketConnectGuard, d as describeSocketAckDrop, b as safeAck, i as isRateQuotaCode, p as pauseForRateQuota, e as shouldReconnect } from './lidState-BLHLmhwd.mjs';
+import { l as logger, r as redactLogValue } from './logger-CbBv3q_b.mjs';
+import { R as RpcHandlerManager, a as answerSocketRequest, c as connectGuarded, s as socketConnectGuard, d as describeSocketAckDrop, b as safeAck, i as isRateQuotaCode, p as pauseForRateQuota, e as shouldReconnect } from './lidState-B2ZxdREe.mjs';
 import { EventEmitter } from 'node:events';
 import { io } from 'socket.io-client';
-import { A as AsyncLock, a as MAX_CHAT_ATTACHMENT_ENCRYPTED_BYTES, U as UserMessageSchema, F as FileEventMessageSchema } from './attachmentLimits-B8nzhw-i.mjs';
+import { A as AsyncLock, a as MAX_CHAT_ATTACHMENT_ENCRYPTED_BYTES, U as UserMessageSchema, F as FileEventMessageSchema } from './attachmentLimits-CxG3T18E.mjs';
 import { h as decrypt, d as decodeBase64, i as decryptBlob, e as encodeBase64, g as encrypt, l as libsodiumEncryptForPublicKey, j as libsodiumPublicKeyFromSecretKey, k as getRandomBytes } from './authRelay-DSAvg1uv.mjs';
 import { p as prepareClipboardText, d as prepareClipboardHistoryText } from './limits-DIo7rEBR.mjs';
-import { b as backoff, d as delay, e as exponentialBackoffDelay } from './time-v1Y_qEJp.mjs';
-import { c as configuration } from './configuration-L1qcGTFM.mjs';
+import { b as backoff, d as delay, e as exponentialBackoffDelay } from './time-PG5Dfwdv.mjs';
+import { c as configuration } from './configuration-WspKd2C2.mjs';
 import { createHmac, randomUUID } from 'node:crypto';
-import { e as createEnvelope, s as streamKeyOf, R as ReleaseDrainNoticeSchema, m as RelayAssignmentResponseSchema } from './index-vVWpCoTr.mjs';
-import { r as registerCommonHandlers } from './registerCommonHandlers-BR0J4g64.mjs';
+import { c as createEnvelope, s as streamKeyOf, R as ReleaseDrainNoticeSchema, q as RelayAssignmentResponseSchema } from './index-B0HEEYGh.mjs';
+import { r as registerCommonHandlers } from './registerCommonHandlers-B0PVff2U.mjs';
 import { createId } from '@paralleldrive/cuid2';
-import { I as InvalidateSync } from './sync-Dfm6K2te.mjs';
+import { I as InvalidateSync } from './sync-CCwYpJMS.mjs';
 import { B as BackgroundTaskReporter } from './backgroundTaskActivity-8PdPxrvy.mjs';
-import { h as notifyDaemonTurnEvent, j as notifyDaemonBackgroundTasks } from './controlClient-Ci7HTMII.mjs';
+import { k as notifyDaemonTurnEvent, m as notifyDaemonBackgroundTasks } from './controlClient-DTheOlvC.mjs';
 import { c as contentLogMetadata } from './contentLogMetadata-BlWI0egu.mjs';
 import chalk from 'chalk';
 
@@ -1588,6 +1588,14 @@ class ApiSessionClient extends EventEmitter {
     }
   }
   routeIncomingMessage(message, sourceLocalId) {
+    if (this.inboundFrozen) {
+      logger.debug(`[API] Hibernating: holding inbound ${sourceLocalId ?? "(no localId)"}`);
+      this.frozenInbound.push({ message, sourceLocalId });
+      this.inboundRoutedDuringCommit = true;
+      return;
+    }
+    this.inboundRoutedDuringCommit = true;
+    this.noteActivity();
     if (sourceLocalId) this.promptQueueDrain?.onInbound(sourceLocalId);
     const messageWithSource = sourceLocalId && typeof message === "object" && message !== null ? { ...message, localKey: message.localKey ?? sourceLocalId } : message;
     const userResult = UserMessageSchema.safeParse(messageWithSource);
@@ -1833,6 +1841,7 @@ class ApiSessionClient extends EventEmitter {
     }
   }
   enqueueMessage(content, invalidate = true, localId) {
+    this.noteActivity();
     const encrypted = encodeBase64(encrypt(this.encryptionKey, this.encryptionVariant, content));
     this.pendingOutbox.push({
       content: encrypted,
@@ -2009,6 +2018,52 @@ class ApiSessionClient extends EventEmitter {
     };
     this.enqueueMessage(content);
   }
+  // ── B-587 hibernation support ──────────────────────────────────────────
+  /** Last user/agent activity this wrapper saw (spec §2.1). */
+  lastActivity = Date.now();
+  inboundFrozen = false;
+  frozenInbound = [];
+  heartbeatsMuted = false;
+  lastHeartbeat = 0;
+  get lastHeartbeatAt() {
+    return this.lastHeartbeat;
+  }
+  muteHeartbeats() {
+    this.heartbeatsMuted = true;
+  }
+  unmuteHeartbeats() {
+    this.heartbeatsMuted = false;
+  }
+  inboundRoutedDuringCommit = false;
+  noteActivity(now = Date.now()) {
+    if (now > this.lastActivity) this.lastActivity = now;
+  }
+  get lastActivityAt() {
+    return this.lastActivity;
+  }
+  /** The message cursor (highest seq this wrapper has seen). */
+  get messageCursor() {
+    return this.lastSeq;
+  }
+  /** Start watching for inbound routed during the hibernation commit window. */
+  beginHibernationCommit() {
+    this.inboundRoutedDuringCommit = false;
+  }
+  /** Was any inbound message routed since beginHibernationCommit()? */
+  inboundRoutedSinceCommit() {
+    return this.inboundRoutedDuringCommit;
+  }
+  /** Stop routing inbound messages; the next wrapper replays them (spec §3/§4). */
+  freezeInbound() {
+    this.inboundFrozen = true;
+  }
+  /** An aborted hibernation: route whatever arrived while frozen, in order. */
+  unfreezeInbound() {
+    this.inboundFrozen = false;
+    const held = this.frozenInbound;
+    this.frozenInbound = [];
+    for (const item of held) this.routeIncomingMessage(item.message, item.sourceLocalId);
+  }
   /**
    * Send a ping message to keep the connection alive
    */
@@ -2027,11 +2082,14 @@ class ApiSessionClient extends EventEmitter {
     }));
   });
   keepAlive(thinking, mode, backgroundTasks) {
+    if (this.heartbeatsMuted) return;
+    this.lastHeartbeat = Date.now();
     if (process.env.DEBUG) {
       logger.debug(`[API] Sending keep alive message: ${thinking}`);
     }
     this.turnReporter.observe(thinking);
     if (backgroundTasks) this.backgroundTaskReporter.observe(backgroundTasks);
+    if (thinking || (backgroundTasks?.length ?? 0) > 0) this.noteActivity();
     this.socket.volatile.emit("session-alive", {
       sid: this.sessionId,
       time: Date.now(),
@@ -2110,14 +2168,16 @@ class ApiSessionClient extends EventEmitter {
    * payload on this channel is (clipboard, fs RPC) — and a path leaks
    * project/client names and directory structure.
    */
-  pushFilePreview(path, mode = "file") {
+  pushFilePreview(path, mode = "file", intent) {
     if (!this.socket.connected) {
       return { delivered: false, error: "not connected to the server" };
     }
     this.socket.emit("file-preview-push", {
       payload: encodeBase64(encrypt(this.encryptionKey, this.encryptionVariant, path)),
       enc: true,
-      mode
+      mode,
+      // B-562: only present for downloads, so a plain preview keeps the old wire shape.
+      ...intent ? { intent } : {}
     });
     return { delivered: true };
   }
@@ -2222,7 +2282,26 @@ class ApiSessionClient extends EventEmitter {
     });
   }
   updateMetadata(handler) {
-    this.metadataLock.inLock(async () => {
+    void this.writeMetadata(handler);
+  }
+  /**
+   * B-587: the same write, awaitable with a ceiling — the hibernation stamp
+   * must land before `session-end`. Resolves false on timeout (the write
+   * itself keeps retrying in the background, exactly like updateMetadata).
+   */
+  async updateMetadataAndWait(handler, timeoutMs = 1e4) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(() => resolve(false), timeoutMs);
+    });
+    try {
+      return await Promise.race([this.writeMetadata(handler).then(() => true), timeout]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  writeMetadata(handler) {
+    return this.metadataLock.inLock(async () => {
       let rateRefusals = 0;
       await backoff(async () => {
         let updated = handler(this.metadata);
@@ -2268,6 +2347,7 @@ class ApiSessionClient extends EventEmitter {
           this.agentState = answer.agentState ? decrypt(this.encryptionKey, this.encryptionVariant, decodeBase64(answer.agentState)) : null;
           this.agentStateVersion = answer.version;
           rateRefusals = 0;
+          if (Object.keys(this.agentState?.requests ?? {}).length > 0) this.noteActivity();
           logger.debug("Agent state updated", this.agentState);
         } else if (answer.result === "version-mismatch") {
           if (answer.version > this.agentStateVersion) {
@@ -3084,7 +3164,7 @@ class ApiClient {
     return new ApiSessionClient(this.credential.token, session, opts);
   }
   async machineSyncClient(machine) {
-    const { ApiMachineClient } = await import('./apiMachine-BQ-b4Lu3.mjs');
+    const { ApiMachineClient } = await import('./apiMachine-CWndf1Vn.mjs');
     return new ApiMachineClient(this.credential.token, machine);
   }
   push() {