@logicseek/hello-cc 1.1.0-rc.4 → 1.1.0-rc.5

package/CHANGELOG.md

@@ -16,6 +16,45 @@ the release description from the current changelog section. Use
 `npm run release:github` with `GH_TOKEN` or `GITHUB_TOKEN` only for local
 backfills.
 
+## 1.1.0-rc.5
+
+### Summary
+
+This preview adds desktop Agent communication adapters: idle inbox wakeup for
+existing DeepSeek Harness Agents, an opt-in bridge for one Claude Desktop Code
+session, and a read-only probe for an explicitly selected Codex endpoint.
+It continues the existing preview channel.
+
+### Highlights
+
+- Wake an idle live Harness Agent with external HCC messages through the official
+  followup API. Poll every second by default; set `inboxPollMs` to `0` to disable
+  idle wakeup. Preserve admission decisions and acknowledge only exact committed
+  context. Self messages, rejected input and reload gaps cannot create retry loops.
+- Generate a private Claude Desktop Mod with `hcc app claude serve`. Bind it to
+  one project and existing session; record replies and acknowledgements together
+  only after the matching main turn completes. Requires an embedded Claude Code
+  engine of at least 2.1.287 and explicit plugin loading in that session.
+- Preserve uncertain Claude deliveries across disconnects and restarts. Ordinary
+  hooks cannot replay those inputs or replace an active Mod owner. Read-only
+  inbox queries retain the unresolved messages for inspection.
+- Inspect an explicitly supplied Codex Unix socket with `hcc app codex probe`.
+  The probe does not start, resume or send to a thread, and does not establish
+  that Desktop owns that endpoint. Codex Desktop sending remains unavailable.
+- Include Chinese and English capability, setup and acceptance guidance. Keep
+  the existing native CLI workers and their ownership boundaries.
+
+### Validation
+
+The implementation passed 1,825 local unit tests (two platform/privilege skips),
+all 13 regression stages and five checks against the official Harness runtime
+with deterministic localhost model responses. Merged-source CI also passed
+Linux/macOS regression, Web and installed Harness package acceptance. These
+checks do not establish real-model Desktop interoperability across all three
+Apps. The generated Claude plugin and marketplace pass the official 2.1.289
+strict validator. Device-specific results have separate receipts; the minimum
+Desktop engine version remains a prerequisite.
+
 ## 1.1.0-rc.4
 
 ### Summary

package/docs/README.md

@@ -41,3 +41,5 @@ authenticated selection of any existing server directory are accepted risks.
   surface, stack, shim behavior, and implementation plan.
 - [Architecture](architecture.md): target project layout, module boundaries,
   dependency direction, and staged migration plan.
+
+- [Desktop Agent communication](app-bridge.md): DSH idle wakeup, Claude Desktop Mod and read-only Codex probes.

package/docs/README.zh-CN.md

@@ -39,3 +39,5 @@ provider peer ID 已变更且不会映射旧 ID；受保护接口使用 Runtime
   迁移计划。
 
 `design.md` 和 `implementation.md` 目前只有英文版。
+
+- [桌面 Agent 通信](app-bridge.zh-CN.md)：DSH 空闲唤醒、Claude Desktop Mod 与 Codex 只读检查。

package/docs/app-bridge.md

@@ -0,0 +1,110 @@
+# Desktop Agent communication
+
+Message persistence, model context admission and completed replies are separate
+states. HCC-owned native workers do not take over existing Desktop chats.
+
+These commands are introduced in preview version `1.1.0-rc.5` and require
+Node.js 24+. Use the existing `preview` installation channel. From this source
+checkout, replace `hcc` below with `node ./bin/hcc.mjs`; older installed versions
+do not include these commands.
+
+| Surface | Implementation | Evidence boundary |
+| --- | --- | --- |
+| DeepSeek Harness App / Web | Cordis tools and idle inbox wakeup on live Agents | Pinned official runtime with a deterministic localhost model, not installed Desktop/model acceptance |
+| Claude Desktop Code tab | Opt-in Mod for one selected existing session, bus replies and correlated completion | Embedded Claude Code 2.1.287+; protocol tests and official 2.1.289 strict static validation passed; Desktop acceptance pending |
+| Codex App | Read-only explicit app-server socket probe | No prompt/resume or verified Desktop endpoint ownership |
+
+## DeepSeek Harness
+
+Use the existing [Cordis integration](dsh.md). `inboxPollMs` defaults to 1000,
+accepts 100–60000, or 0 to disable idle polling. Set it in the Harness plugin
+configuration, not HCC's integrity-checked managed files. Active-step tools and
+context remain enabled.
+
+Only complete unread messages from other peers trigger `Agent.followup()`.
+Self messages cannot wake the Agent or starve later external input. Admission
+and tool policies remain effective. Only exact committed context is ACKed.
+Cancelled/rejected batches remain unread without automatic retry loops.
+Unload removes only this plugin's queued input; reload rediscovers live Agents.
+Ambiguous commits across a reload gap are not automatically replayed.
+
+```sh
+node scripts/dsh-inbox-acceptance.mjs --dsh-install /absolute/path/to/official-install
+```
+
+This isolated test uses ACP for Agent creation/cleanup but never calls
+`session/prompt`. It uses localhost deterministic responses, no credentials,
+and does not install or modify the user's App.
+
+## Claude Desktop Code
+
+Ordinary Chat and CLI Channels are different integrations. Check the embedded
+Desktop engine, not only the independently installed CLI:
+
+```sh
+hcc app claude capability --version 2.1.287
+hcc --root /absolute/project app claude serve --session-id EXISTING_SESSION_ID
+```
+
+The first command only checks the version prerequisite. The foreground bridge
+prints a new private marketplace directory, plugin name, marketplace name and
+peer ID. Explicitly load it in the original Desktop Code session:
+
+```text
+/plugin marketplace add <marketplaceDirectory>
+/plugin install <pluginName>@<marketplace>
+/reload-plugins
+```
+
+Desktop also supports **+ → Plugins → Add plugin**. Each generated marketplace
+has a unique name/version. HCC does not install/upgrade plugins or modify global
+settings/accounts. The generated `hcc-session-link` plugin and marketplace
+both passed official Claude Code 2.1.289 `claude plugin validate <directory>
+--strict`. This static check does not establish target Desktop compatibility
+or replace device acceptance.
+
+The target must not already have another HCC hooks/native/Mod owner. Once it
+connects, send through the existing bus:
+
+```sh
+hcc --root /absolute/project msg send --from coordinator --to PRINTED_PEER_ID --body 'Review the current task results'
+```
+
+The Mod uses `$.prompt.submit()` with Mod provenance. Only the matching main
+turn can complete the message; human turns and subagents cannot acknowledge
+it. Reply and ACK commit atomically. Incoming replies never generate another
+automatic reply. Queued/claimed/started do not mean completed. Aborts,
+disconnects and uncertain restarts remain unread with durable intent records;
+ordinary hooks also exclude those prior submissions from automatic context.
+Normal inbox queries retain them for explicit inspection before another send.
+
+Keep the command running. Ctrl-C removes this generated plugin and closes HCC's
+bridge, preserving the App session. The 0700 directory/0600 files contain a
+temporary local capability, not a Claude account credential: never publish or
+commit them. Same-OS-user access is inside the local trust boundary, not
+provider-attested identity.
+
+References: [Mods](https://code.claude.com/docs/en/plugins/mods/overview),
+[API](https://code.claude.com/docs/en/plugins/mods/api),
+[installation](https://code.claude.com/docs/en/plugins/install).
+
+## Codex App
+
+```sh
+hcc --root /absolute/project --json app codex probe \
+  --socket /absolute/path/to/known-control.sock --thread EXISTING_THREAD_ID
+```
+
+The probe only initializes, reads thread metadata without turns, and performs
+bounded loaded-thread queries. It never scans sockets, starts a daemon,
+resumes/starts/interrupts threads, or reads accounts. Closing affects only its
+own connection. Provider preview/name/error contents are not reported.
+
+`loaded: null` means unestablished. `writable` and `desktopEndpointVerified`
+remain false even when loaded. Public `thread/resume` can cold-restore a thread
+and has no atomic only-loaded precondition. An in-app tool is not automatically
+a public external HCC API. References are the installed official CLI 0.144.6
+help/schema snapshot and the official local source tree at
+`d109393270432531ac0010542ae7973801e0d9d7`. An exact CLI-to-source build match
+and online documentation recheck are not established. `app-server proxy`
+tunnels WebSocket frames, not native stdio JSONL.

package/docs/app-bridge.zh-CN.md

@@ -0,0 +1,80 @@
+# 桌面 Agent 通信
+
+消息入库、进入模型上下文和完成回复是不同状态。`hcc native` 启动的自有 worker 与桌面已有会话也是不同连接。
+
+以下入口从 `1.1.0-rc.5` 预览版本加入，要求 Node.js 24+。使用现有 `preview` 渠道安装；从源码运行时，可将下文的 `hcc` 替换为 `node ./bin/hcc.mjs`。较早的已安装版本不包含这些命令。
+
+| 对象 | 当前实现 | 验证边界 |
+| --- | --- | --- |
+| DeepSeek Harness App / Web | Cordis 插件在原 live Agent 中收件并唤醒 | 固定官方运行时＋本地确定性模型，尚不代表已安装桌面真实模型验收 |
+| Claude Desktop Code | 绑定一个已有会话的可选 Mod，以及 HCC 收件／自动回复 | 需要内嵌引擎 2.1.287+；协议测试和官方 2.1.289 严格静态校验已通过，桌面实测待完成 |
+| Codex App | 显式 app-server socket 的只读检查 | 不发 prompt、不恢复会话，尚未证明端点归属桌面 |
+
+## DeepSeek Harness
+
+沿用 [Cordis 安装方式](dsh.zh-CN.md)。插件默认每 1000ms 检查真实存活 Agent，通过官方 `followup()` 唤醒有外来未读消息的空闲会话。活动会话仍在步骤及停止边界处理。
+
+在 Harness 插件配置中设置 `inboxPollMs`：允许 `100..60000`，默认 `1000`；`0` 关闭自动空闲唤醒，保留活动步骤的协作工具与上下文。不要手改 HCC 带完整性校验的托管文件。
+
+- 自身消息不触发空闲唤醒，也不会挡住排在后面的外来消息。
+- 同一批消息只排队一次，准确的 `user/message` 提交后才 ACK。
+- 准入拒绝、取消或准备失败后保持未读，不自动重试同一批外来输入；新外来消息或人工后续步骤可继续处理。
+- 卸载只移除本插件未被领取的输入，不删除用户输入；热重载重新发现 live Agent。
+- 热重载监听空档内的提交结果若不明，保持未读且不自动重放。
+- 原有准入、工具审批、项目与 peer 身份约束继续生效。
+
+隔离测试命令：
+
+```sh
+node scripts/dsh-inbox-acceptance.mjs --dsh-install /absolute/path/to/official-install
+```
+
+测试使用私有临时目录和 localhost 模型响应。ACP 只创建／清理隔离 Agent，**不调用 `session/prompt`**，不读取账号凭据或修改已安装 App。
+
+## Claude Desktop Code
+
+普通 Chat 和 CLI Channels 是其他入口。先检查目标 **Desktop 内嵌引擎**，单独升级 CLI 不代表桌面也已更新：
+
+```sh
+hcc app claude capability --version 2.1.287
+hcc --root /absolute/project app claude serve --session-id EXISTING_SESSION_ID
+```
+
+第一条只检查版本前提；第二条为明确选定的已有 session ID 启动前台桥接，并输出 `marketplaceDirectory`、`pluginName`、`marketplace` 和 peer ID。随后由用户在原 Desktop Code 会话显式加载：
+
+```text
+/plugin marketplace add <marketplaceDirectory>
+/plugin install <pluginName>@<marketplace>
+/reload-plugins
+```
+
+Desktop 也提供 **＋ → Plugins → Add plugin**。生成器使用每次唯一的本地 marketplace 名称，防止复用旧桥接缓存。HCC 不自动安装、升级或改账号／全局配置。生成的 `hcc-session-link` 插件及其 marketplace 已通过官方 Claude Code 2.1.289 的 `claude plugin validate <directory> --strict` 校验。该静态校验不代替目标 Desktop 的版本检查和实机验收。
+
+原会话不能同时由其他 HCC hooks/native/Mod 适配器持有。连接成功后，从其他 peer 发送：
+
+```sh
+hcc --root /absolute/project msg send --from coordinator --to PRINTED_PEER_ID --body '请检查当前任务的测试结果'
+```
+
+Mod 使用官方 `$.prompt.submit()` 并保留 Mod 来源。只有精确匹配输入的主回合完成才能确认消息，其他人工回合和子代理结果不能误确认。回复与 ACK 在一个数据库事务内提交，收到 `reply` 不再自动回复，避免循环。
+
+排队、领取、开始均不等于完成。取消、断线或重启后的不确定投递保留未读与持久记录，不盲目重发。关闭桥接后，普通 Hooks 也不会重放这些旧输入；普通 inbox 查询仍可查看它们。先检查 App 的实际结果，再明确决定是否另发消息。
+
+保持前台命令运行。Ctrl-C 清理这次生成的插件并关闭桥接，不结束 App 会话。插件目录含此次桥接的临时凭据（目录 0700、文件 0600），不能分享、提交或发布到公共市场。它不是 Claude 账号凭据；同一 OS 用户能读取该目录的代码属于本地信任范围，不提供 provider 签名身份。
+
+依据：[Mods 概览](https://code.claude.com/docs/en/plugins/mods/overview)、[API](https://code.claude.com/docs/en/plugins/mods/api)、[插件安装](https://code.claude.com/docs/en/plugins/install)。
+
+## Codex App
+
+```sh
+hcc --root /absolute/project --json app codex probe \
+  --socket /absolute/path/to/known-control.sock --thread EXISTING_THREAD_ID
+```
+
+只连接给定 Unix socket，初始化后调用 `thread/read(includeTurns:false)` 和有界的 `thread/loaded/list`。不扫描 socket、不启动 daemon、不读取账号或完整聊天历史、不调用 resume/start/interrupt。结束时仅断开自己的连接，原始 preview/name/error 不写进报告。
+
+`loaded: null` 表示尚未确认。即使 loaded 为 true，`writable` 和 `desktopEndpointVerified` 也保持 false，因为该结果不能证明桌面正在使用同一执行器。
+
+公开 `thread/resume` 既可加入 live thread，也可冷恢复会话，没有“只能附着已加载会话”的原子条件。当前实现不把先检查再 resume 的竞争窗口当成纯附着。应用内聊天工具也不自动构成 HCC 外部程序的公开入口。
+
+参考依据为本机官方 CLI 0.144.6 的帮助与 schema 快照，以及本机官方源码树 `d109393270432531ac0010542ae7973801e0d9d7` 的 app-server README／协议定义。未证明源码树与 CLI 构建版本完全对应，也未完成官方网页在线复核。`app-server proxy` 传输 WebSocket 握手和帧，不是 native adapter 的 stdio JSONL。

package/docs/dsh.md

@@ -57,7 +57,7 @@ The Cordis plugin awaits `agent/created`, delegates the `agent/pre-step` decisio
 
 The plugin reuses CLI/MCP transactions and task/lock ownership rules. Context and tool output are each bounded to 16,000 characters by default. Truncation is explicit; incompletely delivered messages remain unread. The shared service also validates argument bounds and authority. ACK occurs only when Harness commits the exact context as a `user/message`; rejected admission, preparation failure and cancellation do not ACK early.
 
-`next()` delegation preserves deny/ask policy. Closing an Agent expires only its own peer. Unloading removes listeners/tool registrations and revokes stale authority; an existing Agent initializes again at its next awaited pre-step after reload. After an unclean exit, the same session can recover its Cordis owner only when the recorded process is verified dead or its PID has been reused. Live or unverifiable owners and conflicting hooks/native bindings remain protected. A project message does not wake an indefinitely idle Harness conversation. It enters at the next model step, or at an active turn's stop boundary.
+`next()` delegation preserves deny/ask policy. Closing an Agent expires only its own peer. Unloading removes listeners/tool registrations and revokes stale authority; after reload, polling rediscovers existing live Agents; an awaited pre-step can also initialize them. After an unclean exit, the same session can recover its Cordis owner only when the recorded process is verified dead or its PID has been reused. Live or unverifiable owners and conflicting hooks/native bindings remain protected. The plugin polls live Agents every 1000ms by default and uses official followup to wake idle Agents with external unread messages. Set inboxPollMs to 0 to disable idle polling; active steps and stop boundaries still process context. Self messages do not wake an Agent, rejected/cancelled batches are not repeatedly retried, and ACK follows exact context commit. See [Desktop Agent communication](app-bridge.md).
 
 ## Modes, Arguments And Routing
 

package/docs/dsh.zh-CN.md

@@ -57,7 +57,7 @@ Cordis 插件使用 `agent/created` 的等待式初始化、`agent/pre-step` 的
 
 底层复用 CLI/MCP 的事务、任务归属和锁规则。上下文与工具输出默认各限制 16,000 字符；过长输出明确标记截断，未完整投递的消息保留未读。工具参数的长度、数量和归属由服务再次验证。消息只在 Harness 提交对应 `user/message` 记录后 ACK；拒绝首轮、准备失败和取消不会提前 ACK。
 
-插件委托 `next()`，保留现有 deny/ask 权限决定。关闭 Agent 只更新其自身 peer；卸载时移除监听与工具注册，并使旧的执行权限失效。重新加载时，既有 Agent 在下一个等待式 pre-step 重新取得身份。异常退出后，只有核实原进程已退出或 PID 已被复用时，同一会话才能恢复 Cordis 归属；活跃或无法验证的 owner，以及 hooks/native 冲突绑定仍会被拒绝。发送项目消息本身不会唤醒持续空闲的 Harness 会话；它在下一步骤进入上下文，或在活动轮次的停止边界继续处理。
+插件委托 `next()`，保留现有 deny/ask 权限决定。关闭 Agent 只更新其自身 peer；卸载时移除监听与工具注册，并使旧的执行权限失效。重新加载时，轮询会重新发现既有 live Agent；等待式 pre-step 也可重新初始化其身份。异常退出后，只有核实原进程已退出或 PID 已被复用时，同一会话才能恢复 Cordis 归属；活跃或无法验证的 owner，以及 hooks/native 冲突绑定仍会被拒绝。插件默认每 1000ms 检查 live Agent，并用官方 followup 唤醒有外来未读消息的空闲会话；活动步骤和停止边界仍继续处理。inboxPollMs: 0 可关闭自动空闲唤醒。自身消息不触发唤醒，拒绝或取消不导致同批输入反复重试；上下文提交后才 ACK。详见 [桌面 Agent 通信](app-bridge.zh-CN.md)。
 
 ## 配置模式与参数
 

package/lib/cli/app.mjs

@@ -34,6 +34,7 @@ import { createMiscCommands } from '../cli/commands/misc.mjs';
 import { createInstallCommands } from '../cli/commands/install.mjs';
 import { createHookCommand } from '../cli/commands/hook.mjs';
 import { createDshCommands } from '../cli/commands/dsh.mjs';
+import { createAppBridgeCommands } from '../cli/commands/app-bridge.mjs';
 import { createNativeCommands } from '../cli/commands/native.mjs';
 import { createMcpCommands } from '../cli/commands/mcp.mjs';
 import { createPeerCommands } from '../cli/commands/peer.mjs';
@@ -354,6 +355,7 @@ const { cmdHook } = createHookCommand({
 });
 
 const { cmdDsh } = createDshCommands();
+const { cmdAppBridge } = createAppBridgeCommands();
 
 const { cmdPeer } = createPeerCommands({
   connect, now, tx, addEvent, auditPayload, printResult, CliError, parseOpts,
@@ -659,6 +661,7 @@ async function dispatch(ctx, rest) {
   if (command === 'web') return cmdWeb(ctx, args);
   if (command === 'hook') return cmdHook(ctx, args);
   if (command === 'dsh') return cmdDsh(ctx, args);
+  if (command === 'app') return cmdAppBridge(ctx, args);
   if (command === 'native') return cmdNative(ctx, args);
   if (command === 'mcp') return cmdMcp(ctx, args);
   if (command === 'install-hooks') return cmdInstallHooks(ctx, args);

package/lib/cli/commands/app-bridge.mjs

@@ -0,0 +1,89 @@
+import process from 'node:process';
+import { CliError } from '../../shared/errors.mjs';
+import { parseOpts, required, validateOpts, wantsHelp, intOpt } from '../../cli-args.mjs';
+import { printResult } from '../../format.mjs';
+import { projectDbPath } from '../../runtime/paths.mjs';
+import { assertSelectedCwdSnapshot } from '../../process/selected-cwd-identity.mjs';
+
+export function appBridgeHelp() {
+  console.log(`Usage:
+  hcc --root PROJECT app claude serve --session-id ID [--plugin-dir NEW_DIRECTORY]
+  hcc --root PROJECT app codex probe --socket ABSOLUTE_PATH --thread ID [--timeout-ms 5000]
+  hcc app claude capability --version VERSION
+
+Claude: generate an opt-in private Desktop Mod and run its local bridge in the
+foreground. Requires Claude Code 2.1.287+ in Desktop and the selected session.
+No plugin is installed and no account or global configuration is changed.
+Ctrl-C closes this bridge, removes its generated plugin and preserves the App.
+Queued/submitted input is not acknowledged until its own turn completes.
+
+Codex: read-only probe of an explicitly supplied existing Unix socket. It never
+starts/resumes a thread or sends a prompt. A loaded thread does not establish
+that the desktop App owns the endpoint; writable remains false.
+
+DSH App: use the Cordis integration (hcc dsh setup --mode cordis).
+Its inboxPollMs setting controls idle wakeup; 0 disables automatic polling.`);
+}
+
+export function createAppBridgeCommands() {
+  async function cmdAppBridge(ctx, args) {
+    if (!args.length || wantsHelp(args)) return appBridgeHelp();
+    const [provider, action, ...rest] = args;
+    const opts = parseOpts(rest);
+    if (provider === 'codex' && action === 'probe') {
+      validateOpts('app codex probe', opts, ['socket', 'thread', 'timeout-ms']);
+      const { probeCodexEndpoint } = await import('../../integrations/codex-app-probe.mjs');
+      if (ctx.initialRootIdentity) assertSelectedCwdSnapshot(ctx.initialRootIdentity);
+      const result = await probeCodexEndpoint({ socketPath: required(opts, 'socket'),
+        threadId: required(opts, 'thread'), expectedCwd: ctx.root, timeoutMs: intOpt(opts, 'timeout-ms', 5000) });
+      if (ctx.initialRootIdentity) assertSelectedCwdSnapshot(ctx.initialRootIdentity);
+      printResult(ctx, result, value => [
+        `Endpoint connected: ${value.transportConnected}; target loaded: ${value.loaded ?? 'unknown'}`,
+        'Desktop ownership unverified; message sending disabled.',
+        ...value.unmetConditions.map(item => `${item.code}: ${item.message}`)
+      ].join('\n'));
+      return result;
+    }
+    if (provider === 'claude' && action === 'capability') {
+      validateOpts('app claude capability', opts, ['version']);
+      const { claudeAppCapability } = await import('../../integrations/claude-app.mjs');
+      const result = claudeAppCapability(required(opts, 'version'));
+      const prerequisite = result.supported ? 'met' : 'not met';
+      printResult(ctx, result, value => `Desktop Mod version prerequisite: ${prerequisite} (minimum ${value.minimumVersion}); this does not test a connected session.`);
+      return result;
+    }
+    if (provider !== 'claude' || action !== 'serve') throw new CliError('BAD_ARGS', 'Unknown App bridge command');
+    validateOpts('app claude serve', opts, ['session-id', 'plugin-dir']);
+    // This service always uses the selected project's canonical managed bus.
+    if (ctx.dbPath !== projectDbPath(ctx.root)) throw new CliError('BAD_ARGS', 'App bridges use the project managed database; omit --db');
+    const sessionId = required(opts, 'session-id');
+    const { createClaudeAppBridge, writeClaudeAppPlugin } = await import('../../integrations/claude-app.mjs');
+    const { createClaudeAppCoordination } = await import('../../integrations/claude-app-collaboration.mjs');
+    let bridge, plugin, coordination, stop;
+    const finished = new Promise(resolve => { stop = resolve; });
+    const signal = () => stop();
+    try {
+      bridge = await createClaudeAppBridge({ root: ctx.root, sessionId, initialRootIdentity: ctx.initialRootIdentity });
+      plugin = writeClaudeAppPlugin({ directory: opts['plugin-dir'], bridge });
+      coordination = createClaudeAppCoordination({ root: ctx.root, sessionId, bridge, initialRootIdentity: ctx.initialRootIdentity,
+        onStatus: status => {
+          const message = status.error ? `Claude App bridge: ${status.error}` : `Claude App peer ${status.peer} connected`;
+          process.stderr.write(message + '\n');
+        } });
+      process.once('SIGINT', signal); process.once('SIGTERM', signal);
+      printResult(ctx, { sessionId, peer: coordination.peer, pluginDirectory: plugin.directory,
+        marketplaceDirectory: plugin.marketplaceDirectory, marketplace: plugin.marketplace, pluginName: plugin.name,
+        minimumVersion: plugin.minimumVersion, connected: false, foreground: true }, value =>
+        `Waiting for the selected Claude Desktop Code session.\nPeer: ${value.peer}\n` +
+        `Private marketplace: ${value.marketplaceDirectory}\nPlugin: ${value.pluginName}@${value.marketplace}\n` +
+        `Requires Claude Code ${value.minimumVersion}+. Add this local marketplace and plugin explicitly, then /reload-plugins in the selected session.\n` +
+        'Keep this command running; Ctrl-C removes the generated plugin and disconnects HCC.');
+      await finished;
+    } finally {
+      process.removeListener('SIGINT', signal); process.removeListener('SIGTERM', signal);
+      try { coordination?.close(); }
+      finally { try { await bridge?.close(); } finally { plugin?.dispose(); } }
+    }
+  }
+  return { cmdAppBridge };
+}

package/lib/cli/commands/hook.mjs

@@ -158,11 +158,30 @@ async function cmdHook(ctx, args) {
       process.exitCode = 0;
       return;
     }
+    // A Desktop Mod already drives this exact session. Ordinary hooks must
+    // neither replace its transport binding nor consume its inbox a second time.
+    const appOwnsSession = () => {
+      const appBinding = db.prepare(`SELECT * FROM peer_bindings WHERE transport='claude-mod'
+        AND runtime_target IS NOT NULL AND (peer=? OR (provider='claude' AND provider_session_id=?)) LIMIT 1`).get(peerId, sessionId);
+      if (!appBinding) return false;
+      if (kind !== 'claude' || appBinding.provider !== 'claude' ||
+          appBinding.provider_session_id !== sessionId || appBinding.runtime_session_id !== sessionId) {
+        throw new CliError('CLAUDE_APP_OWNERSHIP_CONFLICT', 'Hook does not match the existing Desktop Mod session');
+      }
+      return true;
+    };
+    if (appOwnsSession()) {
+      process.exitCode = 0;
+      return;
+    }
     const status = hookKey === 'stop' ? 'idle' : 'working';
     const providerAncestor = readAncestorCliInfo(isDsh ? 'dsh' : undefined);
     const providerPid = providerAncestor?.kind === kind ? Number(providerAncestor.pid) : null;
     const providerIdentity = providerPid ? liveProcessIdentity(providerPid) : null;
     const registerHookIdentity = () => {
+      // Recheck after obtaining the write transaction: a Mod may have
+      // registered while this hook was collecting process evidence.
+      if (kind === 'claude' && appOwnsSession()) return false;
       if (isDsh) assertDshHookBinding(db, peerId, sessionId);
       const existing = db.prepare('SELECT id FROM peers WHERE id = ?').get(peerId);
       if (!existing) {
@@ -224,8 +243,8 @@ async function cmdHook(ctx, args) {
     };
     // Keep the dsh conflict check and identity/binding writes atomic, so a
     // concurrent service/session registration cannot change the inspected row.
-    if (isDsh) tx(db, registerHookIdentity);
-    else registerHookIdentity();
+    const registered = isDsh || kind === 'claude' ? tx(db, registerHookIdentity) : registerHookIdentity();
+    if (registered === false) { process.exitCode = 0; return; }
     // hb-06: an active hook is proof the peer is working. During clock grace,
     // renew retained locks even when the wall-clock jump made them look expired.
     const hookNow = now();

package/lib/coordination-state.mjs

@@ -92,7 +92,7 @@ export function createCoordinationState(deps = {}) {
         ORDER BY resource ASC
       `).all();
       const messages = peer
-        ? queryInbox(db, peer, false, 50)
+        ? queryInbox(db, peer, false, 50, { excludeAppDeliveries: opts.excludeAppDeliveries === true })
         : db.prepare(`
             SELECT id, sender, recipient, task_id, kind, body, reply_to, thread_id, created_at
             FROM messages
@@ -142,7 +142,10 @@ export function createCoordinationState(deps = {}) {
   }
 
   function buildHookCoordinationContext(db, ctx, peerId) {
-    const snapshot = collectStateSnapshot(db, ctx, peerId);
+    // A prior App submission may have run even when its final reply was lost.
+    // Returning to ordinary hooks must not silently replay that input. Normal
+    // inbox/state queries keep it visible and unread for explicit inspection.
+    const snapshot = collectStateSnapshot(db, ctx, peerId, { excludeAppDeliveries: true });
     const openTasks = snapshot.tasks.slice(0, 8);
     const unread = snapshot.messages.slice(0, 5);
     const peers = snapshot.peers.slice(0, 8);

package/lib/core/coordination/messages.mjs

@@ -31,7 +31,10 @@ export function createMessageStore(deps = {}) {
     return messageId;
   }
 
-  function queryInbox(db, peer, includeAll, limit) {
+  function queryInbox(db, peer, includeAll, limit, options = {}) {
+    const excludeAppDeliveries = options.excludeAppDeliveries === true;
+    const appDeliveryFilter = excludeAppDeliveries
+      ? 'AND NOT EXISTS (SELECT 1 FROM meta WHERE key = ? || m.id)' : '';
     return db.prepare(`
       SELECT
         m.id, m.sender, m.recipient, m.task_id, m.kind, m.body,
@@ -42,9 +45,11 @@ export function createMessageStore(deps = {}) {
       WHERE
         (m.recipient IS NULL OR m.recipient = '' OR m.recipient = 'all' OR m.recipient = ?)
         AND (? = 1 OR r.read_at IS NULL)
+        ${appDeliveryFilter}
       ORDER BY m.id ASC
       LIMIT ?
-    `).all(peer, peer, includeAll ? 1 : 0, limit);
+    `).all(peer, peer, includeAll ? 1 : 0,
+      ...(excludeAppDeliveries ? [`claude-app.delivery.${peer}.`] : []), limit);
   }
 
   function queryTimelineMessages(db, peer, limit) {