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

package/docs/web-handoff.zh-CN.md

@@ -1,6 +1,92 @@
-# Web 继续本地任务
+# Web 新建 Agent、项目文件与继续本地任务
 
-项目仍以 CLI/tmux 作为默认接入。它适合继续已经托管的本地 Codex/Claude/shell：Web 打开同一个 pane，不另起执行器。
+Web 可以直接新建 Codex、Claude 或 DeepSeek Harness 后台 Agent，也可以继续同一项目中已有的 native worker 或受管终端。
+
+## 浏览文件与产物
+
+选择项目后，点击顶部“文件”，即可浏览项目目录并打开已保存的文件，无需先创建 Agent。
+支持逐层进入目录、返回上级、输入项目相对目录和刷新。会话中“引用与执行器能力”的文件
+检索结果也可以直接打开预览；“引用文件”仍然只在消息草稿里加入路径标记。
+
+| 文件类型 | 预览方式 |
+| --- | --- |
+| 文本、源代码 | 显示转义后的原文 |
+| Markdown | 显示基本排版与代码块，可切回源码 |
+| HTML | 隔离的静态预览，可切回源码；脚本、表单、导航和外部资源不运行 |
+| PNG、JPEG、GIF、WebP | 图片预览 |
+| PDF | 浏览器内置查看器；未支持内嵌显示时可下载查看 |
+| SVG | 仅显示源码 |
+| 其他二进制文件 | 提示暂不支持预览，不尝试按文本显示 |
+
+预览只读取当前项目内的普通文件，不修改文件，也不会把内容上传给模型。
+`dist`、`build` 等产物目录可以浏览；运行状态、依赖缓存及已知凭据路径不提供预览，
+符号链接和硬链接也不读取。目录每次最多显示 500 项，并提示未完整列出的情况；
+文本超过 1 MiB 时只显示前部并标记截断，截断 HTML 只显示源码。图片和 PDF 最大为
+10 MiB，超过限制会明确提示。文件在读取期间变化时，请刷新后重试。
+
+切换文件、切换项目或关闭预览会使旧请求失效。手机可在目录与预览之间返回切换；
+分屏辅助窗口的文件入口会在同一项目的主窗口中打开。静态预览不会启动生成网页所需的
+开发服务器。
+
+## 上传与编辑项目文件
+
+在“文件”中进入目标目录，选择一个本机文件并核对目标文件名，再点击上传。文件会保存到
+运行 HCC 的机器上当前项目的这个目录，单文件最大 10 MiB；不自动创建目录，不覆盖同名
+文件。上传不是聊天附件发送，不会自动让 Agent 读取文件。要在任务中引用文件，仍需在
+消息中明确引用项目路径。
+
+完整的 UTF-8 文本、源码、Markdown 和 HTML 可以切换到编辑模式，修改后显式保存。
+编辑上限为 1 MiB，截断预览和二进制文件不能在线编辑。UTF-8 BOM 与原有 CRLF 换行会
+保留；混合换行文件会提示保存时统一为 LF。没有编辑过的文本不能重复保存。
+保存前核对读取时的文件版本；
+另一窗口或本地程序已修改文件时，保留草稿并显示冲突，核对磁盘内容后再决定如何处理。
+HCC 的同文件写入会串行化；本地编辑器等其他程序不共享这个锁，因此这不是对任意外部
+写入的系统级原子版本交换。保存通过同目录临时文件替换，避免向读者暴露半写的文本。
+
+切换文件、项目或关闭文件窗口会保留当前页面内的编辑草稿；刷新或关闭整个页面仍可能
+丢失未保存内容。“返回预览”保留草稿，“放弃草稿并重载”会先确认再丢弃。
+遇到断线或写入回执不确定时，使用“读取已保存文件”核对文本，或“核对目标文件”比较
+上传文件的大小和内容哈希；不会自动重发保存或上传。上传回执恢复只在浏览器保存项目
+身份、路径、大小和哈希，不保存上传文件内容。
+
+上传、编辑与预览沿用相同的项目路径限制，不允许修改运行状态、依赖缓存、已知凭据路径、
+符号链接或硬链接。写入固定到经验证的目标父目录身份，不会跟随被替换的项目路径去写
+另一个目录；如果原目录在写入中被移动，需重新选择当前位置并核对写入结果。
+
+## 项目 Agent 启动默认值
+
+顶部“设置”中可保存当前项目的默认 Agent，以及 Codex、Claude、DeepSeek Harness
+各自的默认模型和工作目录。它们保存在所选项目的 HCC 数据库中，可供其他浏览器读取；
+语言、主题、密度和字号仍是当前浏览器的显示偏好。
+
+模型留空表示使用 provider 自身的当前配置；HCC 不会推测该配置中的模型，也不在保存时
+调用模型验证名称。工作目录保存为项目相对路径，`.` 表示项目根目录，其他值必须指向
+现有的项目内目录。新建时会再次检查目录，已经删除或移到项目外的目录不能用来启动。
+
+保存后，“新建 Agent”会预填相应 provider 的模型和目录，本次创建仍可修改。取消后再打开
+会保留尚未提交的草稿；默认值读取或重试不会覆盖已编辑的字段。成功创建后，下一次新建
+重新读取项目默认值。清空模型表示本次使用 provider 默认配置，可以覆盖已保存的项目模型。
+新值只用于后续 Web 新建 native worker；既有 worker、历史恢复、CLI 启动及高级终端/
+App Server 流程各自沿用原有配置。此处不管理 provider 登录、API key、端点、环境变量
+或全局配置文件。
+
+保存使用版本校验。其他窗口先保存后，当前窗口会显示冲突并保留输入，需重新载入并
+核对最新值；不会静默覆盖其他窗口的修改。“恢复初始值”先重置表单，保存后才生效。
+如果保存响应因断线而不确定，先重新读取配置核对结果。
+
+## 新建后台 Agent
+
+运行 `hcc web`，选择项目，再点击“新建 Agent”。选择 Codex、Claude 或 DeepSeek Harness 后，默认使用“后台 Agent”；无需预先运行 `hcc native start`。对应 CLI 或 Claude SDK 仍需已安装，身份认证沿用运行 hello-cc 的环境，Web 不代为安装或登录。
+
+工作目录使用该项目为此 provider 保存的默认值，未设置时为项目根目录，可改为项目内的子目录；worker 仍共享所选项目的任务、消息、锁和交接。需要在另一个项目工作时，先切换或添加该项目。模型预填项目中保存的默认值，也可在本次创建时修改或清空；留空使用 provider 当前配置，填写时应使用该 provider 支持的模型值。名称可留空自动生成。
+
+“新建 Agent”用于创建新的 native worker；恢复已关闭的 worker，请使用项目栏“历史”中的“HCC 保留历史”。既有 `hcc native start` 和 `--resume last` CLI 继续可用。创建后在同一 Web 会话内发送提示、查看回执和处理审批；创建成功不代表已经运行模型任务。关闭页面或停止 Web runtime 都不会停止独立的 native runtime/worker，需要明确执行关闭操作。
+
+“高级选项”保留终端 CLI、Codex 的结构化 App Server 及它们原有的恢复流程。Shell 使用终端，DeepSeek Harness 使用后台 Agent。以下交接说明分别适用于这些执行方式。
+
+## 继续已有终端
+
+CLI/tmux 适合继续已经托管的本地 Codex/Claude/shell：Web 打开同一个 pane，不另起执行器。
 
 运行 `hcc web` 后选择已有会话。选中项和未发送草稿按项目保存于当前浏览器；刷新会恢复原位置。第一个 Web 连接取得控制，其他窗口可观察，点击“接管浏览器控制”后才可写入。服务端检查控制 epoch，旧窗口不能继续输入、改变终端尺寸、修改该 peer 或处理审批。本地 tmux client 仍可直接输入，Web 会显示其连接状态。
 
@@ -10,10 +96,12 @@
 
 ## Codex 结构化界面
 
-新建会话时选择 Codex，再把“Codex 接入方式”切换为“结构化 App Server（显式启用）”。需要本地已安装且支持 App Server 的 `codex`，登录和模型环境来自启动 hello-cc 的进程。hello-cc 不自动登录、不更改信任配置、不探测未公开的 TUI 内部 endpoint。
+在“新建 Agent”中选择 Codex，展开“高级选项”并选择结构化 App Server。需要本地已安装且支持 App Server 的 `codex`，登录和模型环境来自启动 hello-cc 的进程。hello-cc 不自动登录、不更改信任配置、不探测未公开的 TUI 内部 endpoint。
 
 可先运行 `hcc doctor --codex --json` 查看只读诊断。它分别报告已安装版本、CLI help 声明的 App Server 启动参数、hooks 配置与项目中的 hook 调用记录；这些事实不等于完整 RPC 能力、hooks 已受信任、stdout 投递成功或模型已接收。版本/help 探测使用独立临时 HOME/CODEX_HOME 并清理，防止 Codex 启动文件触碰用户目录；hooks 配置仍从原路径只读检查。没有充分回执的状态显示 `unknown`，不会自动触发 hook 或修改 trust。普通 `hcc doctor` 仍只检查数据库。
 
+升级 Codex 前可运行 `npm run codex:protocol -- --codex-bin /absolute/path/to/codex --out /tmp/hcc-protocol-new`。输出目录必须不存在；工具使用隔离 HOME/CODEX_HOME 生成官方 TypeScript 和 JSON Schema，记录版本/文件指纹并检查交接所依赖的协议子集。不兼容时返回非零退出码，未接入请求单独列出；生成成功不代表真实模型或外部授权验收。安装包内也可直接运行 `node /absolute/path/to/hello-cc/scripts/codex-protocol.mjs`。详见 `docs/codex-protocol.md`。
+
 结构化界面提供消息、当前 turn 状态、追加指令、轮次中断、计划、差异和人工交互。命令/文件审批以及空表单 MCP 工具确认由当前控制窗口明确批准本次或拒绝。文件与网络权限可逐项勾选，并明确选择本轮或会话有效期；只能授予原请求的子集。问题支持选项、其他/自由输入和敏感答案，需逐题明确填写。接管控制本身不会批准工具。
 
 表单输入与焦点会跨状态刷新保留，直接答案不写入 HCC 状态、事件、回执或浏览器存储。原 turn 完成、中断成功、provider 解决请求或执行器关闭后，请求卡片失效；旧控制窗口不能用过期 epoch 应答。参数被截断时只能拒绝或取消。MCP 支持下述标准表单和带原 thread/turn 标识的 URL 请求；嵌套对象、任意数组等复杂结构、动态工具及账号 token 刷新尚未接入。
@@ -36,7 +124,7 @@ MCP 标准表单可以直接在 Web 填写文本、数值、是/否和单选/多
 
 ## 本地 native worker 接手
 
-先用 `hcc native start --peer codex-worker --provider codex` 启动后台任务，再打开 Web 的同一项目。Web 自动发现实际仍由 native runtime 持有的 worker，显示其原 peer/session、事件和投递回执；发送、中断和明确关闭都通过原 runtime 执行，不新建 provider 子进程。Claude/dsh worker 也走这条路径，按实际能力显示中断操作。
+已有 worker 可以继续从 CLI 启动，例如 `hcc native start --peer codex-worker --provider codex`，再打开 Web 的同一项目；也可直接使用上方的新建入口。Web 自动发现实际仍由 native runtime 持有的 worker，显示其原 peer/session、事件和投递回执；接手已有 worker 后的发送、中断和明确关闭都通过原 runtime 执行，不另建 provider 子进程。Claude/dsh worker 也走这条路径，按实际能力显示中断操作。
 
 发送成功先显示队列回执；执行器接收、运行和完成分别使用实际投递状态。断线或不确定结果保留 submission ID，刷新不会重放消息。native runtime 重启或 worker 被替换时，旧 Web 视图及其控制凭证失效，重新发现当前 worker 后才能操作。
 
@@ -46,14 +134,28 @@ MCP 标准表单可以直接在 Web 填写文本、数值、是/否和单选/多
 
 ## 历史、协作工具与结果审阅
 
-项目栏“Codex 历史”可分页浏览当前项目已保存的 thread，读取上下文，再显式恢复或分叉。恢复仍要求旧执行器已确认停止；分叉生成新的 thread/peer，原任务 owner 不变。有正在托管的源会话时，分叉也必须取得该会话的浏览器控制。历史读取不会启动模型 turn。
+项目栏“历史”默认打开“HCC 保留历史”，可按 Codex、Claude、DeepSeek Harness 筛选当前项目的 native worker，查看已保留的 provider 事件与投递回执。native runtime 离线时仍可读取已保存记录；浏览历史不会启动 provider 或模型 turn。
+
+worker 列表最多显示最近 100 项，超过时提示截断。事件每页 100 条，可以前后翻页；投递回执显示该 worker 最新 100 条。当前存储只保留整个项目最近约 2,000 条 provider 事件；这不是 provider 的完整对话档案。历史中可能没有最初输入、早期已裁剪事件或尚未被 HCC 记录的输出。DSH ACP 恢复本身也不代表原始对话重放。
+
+恢复前先明确关闭原 worker，再选中历史项并确认。后端只接受已记录为 `closed`、原 peer/provider/session 与 owner 仍一致的记录；运行中、断连、失败或退出未确认的记录不能从此入口恢复。恢复沿用原 peer、provider 会话和工作目录，创建新的 native 执行器；不会重放已处理或投递状态不明的消息，尚未执行的队列消息会按现有 native 队列规则继续。provider 安装和账号要求仍然适用，DSH 还需实际 ACP runtime 声明 resume 能力。
+
+恢复请求只提交一次。断线或响应丢失后，页面保留原恢复记录，通过刷新查找同一 peer 的新执行器；不会自动重新恢复。浏览器刷新后也可继续检查结果。恢复成功仅表示执行器已接入，Claude SDK 的会话初始化仍可能等到第一条新提示后才确认。
+
+选择“Codex 已保存会话”，可分页浏览当前项目已保存的 thread，读取上下文，再显式恢复或分叉。恢复仍要求旧执行器已确认停止；分叉生成新的 thread/peer，原任务 owner 不变。有正在托管的源会话时，分叉也必须取得该会话的浏览器控制。历史读取不会启动模型 turn。
 
 Web 专用 Codex App Server，以及由 HCC 托管的 Codex/Claude/dsh native worker，自动接入 [项目与 peer 受限的 MCP 协作工具](mcp.zh-CN.md)。配置只传给对应执行器或 worker，不写全局 provider 配置；关闭 worker 前撤销其临时权限。模型可查询任务与 inbox、领取任务、发送消息、写 handoff、获取/释放自己的资源锁和记录本地证据；不替用户执行发布或业务验收。
 
 会话栏“结果审阅”汇总结构化 command 的执行状态与退出码、是否有 turn 差异、模型通过 MCP 明确提交的本地证据，以及人工添加的验收记录。自动结果仅在实时观察到新 turn 开始后归属当前任务；缺失该事件时，不会从历史快照补认任务证据。自动结果在项目数据库 events 中只保存中性标题、状态、退出码和来源 ID，不保存命令、输出或差异正文；正文仍可在可用的执行器会话或 provider 历史中查看。命令退出成功仅说明该命令成功；人工填写“通过”必须附证据引用。界面分别展示本地验证、发布部署、业务验收，并注明记录来源。turn 完成、测试记录或人工验收均不自动改变 hcc task 状态。`gc --history` 保留结果审计记录和最小提交去重凭据。
 
+## Codex 账号与限额
+
+Web 专用 Codex 和原生 Codex worker 新增只读“账号与限额”面板，观察窗口也可刷新。它显示本执行器的登录/供应商认证状态、可获取的订阅窗口、重置时间和读取时间；缺失或不支持的配额保持未知，账号切换与执行器替换拒绝旧查询结果。此操作不新建任务或 turn，也不提供登录、退出或 token 管理。未登录时需在运行任务的电脑完成本地 Codex 登录。使用方式、接口身份和真实/模拟验收边界见 [账号与限额说明](codex-account.zh-CN.md)。
+
 ## 验收边界
 
+以下既有记录分别对应当时的执行器、交接和交互流程，不代表新增的统一“新建 Agent”、项目启动默认值、文件上传编辑、HCC 历史或 Web native 恢复入口已完成真实模型或发布验收。
+
 本地验证包含真实 SQLite/HTTP、模拟交互请求、隔离 tmux 与桌面/手机浏览器。安装版 Codex 0.144.6 的协议验收另行覆盖 initialize、thread/start/list、10 个 MCP 工具发现和实际 `hcc_state` 读回；此协议检查不调用模型，可用 `node scripts/web-handoff-installed-acceptance.mjs` 重现。
 
 真实模型验收已在隔离项目和 Codex home 中完成“本地 → Web → 本地”三段文件任务，全程保持原 Codex 进程和 thread；关闭 Web runtime 后仍可继续。可用 `scripts/web-native-model-acceptance.mjs` 在明确需要真实模型调用时重现。三种 provider 的真实生命周期、模型 MCP 发信、回复/ACK 和无回复循环另有独立回执。交互表单另有 11 项模拟 provider 浏览器检查。真实 Codex 已经完成“提问 → Web 答复 → 指定文件权限 → 本轮授权 → 写入所选答案 → 后续请求拒绝 → 本地继续”的验收；默认加载的 Claude SDK 已完成真实 Write 工具批准、拒绝和本地续接。dsh 已完成真实 ACP 写入的 Web 批准、拒绝和原 session 本地续接，审批卡片另通过桌面与 390px 手机检查；仅在隔离 profile 中对指定验收文件设置公开审批策略。完整结果与运行条件见 本地验收记录 (源码目录: `docs/verification/2026-10-02-web-local-task-handoff.md`)。

package/lib/cli/app.mjs

@@ -54,7 +54,8 @@ import { readPackageMeta } from '../package-meta.mjs';
 import { removeGuidanceBlocks as removeGuidanceBlocksForRoot, writeGuidance as writeGuidanceForRoot } from '../guidance.mjs';
 import { globalRuntimePath, runtimePath } from '../runtime/paths.mjs';
 import { readRuntime, reclaimRuntimePointerFiles } from '../runtime/state.mjs';
-import { waitForProcessIdentityExit } from '../process/identity.mjs';
+import { waitForProcessIdentityExit, inspectProcessIdentity, compareProcessIdentity } from '../process/identity.mjs';
+import { withFileLock } from '../shared/file-lock.mjs';
 
 import { runtimeRequest } from '../runtime/client.mjs';
 
@@ -322,7 +323,7 @@ const { cmdDown, cmdFindRoot, cmdWhichReal } = createMiscCommands({
   path, fs, process, CliError, parseOpts, printResult,
   readRuntime, runtimeRequest, runtimePath, globalRuntimePath,
   reclaimRuntimePointerFiles, helpDown, loadSetup,
-  waitForProcessIdentityExit,
+  waitForProcessIdentityExit, inspectProcessIdentity, compareProcessIdentity, withFileLock,
   PRODUCT_NAME
 });
 
@@ -507,8 +508,9 @@ function webErrorStatus(err) {
   if (!(err instanceof CliError)) return 500;
   if (err.code === 'REGISTRY_BUSY') return 503;
   if (err.code === 'CODEX_START_FAILED') return 503;
+  if (err.code === 'PROJECT_PATH_CHANGED') return 409;
   if (err.code.startsWith('CODEX_') || ['STALE_CONTROL_EPOCH', 'UNKNOWN_CONTROL_CLIENT'].includes(err.code)) return 409;
-  if (['BAD_ARGS', 'BAD_REQUEST', 'PEER_IDENTITY_REQUIRED', 'REQUEST_TOO_LARGE'].includes(err.code)) return 400;
+  if (['BAD_ARGS', 'BAD_REQUEST', 'PEER_IDENTITY_REQUIRED', 'REQUEST_TOO_LARGE', 'INTERACTION_RESPONSE_INVALID'].includes(err.code)) return 400;
   if (['PEER_IDENTITY_MISMATCH', 'TASK_OWNED', 'TASK_OWNER_MISMATCH', 'LOCK_OWNED', 'PROJECT_NOT_REGISTERED', 'PROJECT_PATH_FORBIDDEN', 'RUNTIME_ADMIN_REQUIRED'].includes(err.code)) return 403;
   if (err.code.startsWith('NATIVE_')) return err.code === 'NATIVE_RUNTIME_OFFLINE' ? 503 : 409;
   if (['NOT_FOUND'].includes(err.code)) return 404;
@@ -576,11 +578,12 @@ function formatHookEventName(hookType) {
 }
 
 function writeGuidance(ctx) {
-  return writeGuidanceForRoot(ctx.root);
+  return writeGuidanceForRoot(ctx.root, { expectedSnapshot: ctx.initialRootIdentity });
 }
 
-function removeGuidanceBlocks(ctx) {
-  return removeGuidanceBlocksForRoot(ctx.root);
+function removeGuidanceBlocks(ctx, options = {}) {
+  return removeGuidanceBlocksForRoot(ctx.root,
+    { expectedSnapshot: ctx.initialRootIdentity, ...options });
 }
 
 function cmdMigrateState(ctx, args) {

package/lib/cli/commands/coordination.mjs

@@ -163,8 +163,13 @@ export function createCoordinationCommands(deps) {
     const kind = opts.kind || 'ask';
     const runtime = opts.inject ? readRuntime(ctx) : null;
     const db = connect(ctx);
-    touchCurrentPeer(db, ctx, identity, null, 'shell');
-    const id = sendMessage(db, sender, recipient, taskId, kind, body);
+    let id;
+    try {
+      touchCurrentPeer(db, ctx, identity, null, 'shell');
+      id = sendMessage(db, sender, recipient, taskId, kind, body);
+    } finally {
+      db.close();
+    }
     let injected = false;
     if (opts.inject) {
       await injectPeer(ctx, recipient, body, !opts['no-enter'], runtime, sender);

package/lib/cli/commands/gc.mjs

@@ -25,7 +25,7 @@ import {
 } from '../../core/coordination/gc-plan.mjs';
 import { runOptimisticEvidenceMutation } from '../../core/coordination/optimistic-evidence.mjs';
 import { peerEvidenceAllowsReap } from '../../core/peers/evidence.mjs';
-import { runtimePath, globalRuntimePath } from '../../runtime/paths.mjs';
+import { globalRuntimePath } from '../../runtime/paths.mjs';
 import { resolveProjectDatabase } from '../../runtime/project-path.mjs';
 import { readRuntime, reclaimRuntimePointerFiles } from '../../runtime/state.mjs';
 import { runtimeRequest, runtimeBufferGcUnavailable } from '../../runtime/client.mjs';
@@ -58,6 +58,10 @@ export function createGcCommands(deps) {
 // stale bufs) so automatic background gc bounds DB growth without deleting
 // user-meaningful history.
 // `db` is used open; the caller owns its lifecycle.
+function bufferDirectory(ctx) {
+  return path.join(resolveProjectDatabase({ root: ctx.root, createStateDir: false }).stateDir, BUFS_DIR_NAME);
+}
+
 function captureGcClockSubject(db, {
   bufferGcCutoffs,
   olderThanDays,
@@ -628,10 +632,6 @@ function runGcWithHistorySnapshot(ctx, db, {
   return results;
 }
 
-function bufferDirectory(ctx) {
-  return path.join(resolveProjectDatabase({ root: ctx.root, createStateDir: false }).stateDir, BUFS_DIR_NAME);
-}
-
 function bufferDirectoryPaths(directory) {
   try {
     return fs.readdirSync(directory).map((name) => path.resolve(directory, name));
@@ -659,16 +659,16 @@ function localBufferEvidence(ctx, db, directory, unknownTracker = null, candidat
   });
 }
 
-function runtimePointerPresent(ctx) {
+function runtimePointerPresent(localPointer) {
   return Boolean(process.env.HCC_RUNTIME_URL ||
-    fs.existsSync(runtimePath(ctx)) ||
+    fs.existsSync(localPointer) ||
     fs.existsSync(globalRuntimePath()));
 }
 
-function reclaimUnavailableRuntimePointers(ctx, { dryRun = false } = {}) {
+function reclaimUnavailableRuntimePointers(localPointer, { dryRun = false } = {}) {
   if (process.env.HCC_RUNTIME_URL) return { allowed: false, gcCutoffs: [] };
   const gcCutoffs = [];
-  const result = reclaimRuntimePointerFiles([runtimePath(ctx), globalRuntimePath()], {
+  const result = reclaimRuntimePointerFiles([localPointer, globalRuntimePath()], {
     dryRun,
     onReclaim: ({ gcCutoff }) => {
       if (Number.isSafeInteger(gcCutoff)) gcCutoffs.push(gcCutoff);
@@ -718,15 +718,17 @@ function deferredPreparedBufferGc(prepared, graceActive = false) {
 }
 
 async function prepareManualBufferGc(ctx, db, { retentionSec, dryRun }) {
-  const directory = bufferDirectory(ctx);
+  const stateDir = resolveProjectDatabase({ root: ctx.root, createStateDir: false }).stateDir;
+  const directory = path.join(stateDir, BUFS_DIR_NAME);
+  const localPointer = path.join(stateDir, 'runtime.json');
   const unknownTracker = new Map();
   const pointerGcCutoffs = [];
   const recoverRuntimePointers = () => {
-    const recovery = reclaimUnavailableRuntimePointers(ctx, { dryRun });
+    const recovery = reclaimUnavailableRuntimePointers(localPointer, { dryRun });
     pointerGcCutoffs.push(...recovery.gcCutoffs);
     return recovery.allowed;
   };
-  const pointerPresent = runtimePointerPresent(ctx);
+  const pointerPresent = runtimePointerPresent(localPointer);
   let runtime = null;
   try { runtime = readRuntime(ctx); } catch (error) {
     if (pointerPresent && !recoverRuntimePointers()) {

package/lib/cli/commands/hook.mjs

@@ -5,6 +5,7 @@ import { parseOpts, validateOpts } from '../../cli-args.mjs';
 import { tx } from '../../db/schema.mjs';
 import { resolveProjectDatabase } from '../../runtime/project-path.mjs';
 import { projectDbPath } from '../../runtime/paths.mjs';
+import { HOOK_ROOT_IDENTITY_ENV, assertHookRootIdentity } from '../../core/sessions/hook-root-identity.mjs';
 
 export function createHookCommand(deps) {
   const {
@@ -86,11 +87,22 @@ async function cmdHook(ctx, args) {
   const hccRoot = (nativeOwner || !isDsh) && process.env.HCC_ROOT
     ? path.resolve(process.env.HCC_ROOT)
     : path.resolve(hookCwd);
+  // First-party launches carry the original directory inode. Reject a stale
+  // callback before database resolution or project activity can target a new
+  // directory installed at the old pathname. dsh service hooks are intentionally
+  // payload-scoped and do not inherit a service-wide project identity.
+  const launchRootIdentity = (!isDsh || nativeOwner)
+    ? assertHookRootIdentity(hccRoot, process.env[HOOK_ROOT_IDENTITY_ENV]) : null;
 
   const dshProject = isDsh && !nativeOwner ? resolveProjectDatabase({ root: hccRoot, createStateDir: false }) : null;
   const nativeProject = nativeOwner ? resolveProjectDatabase({ root: hccRoot,
     db: process.env.HCC_DB, createStateDir: false }) : null;
-  const ordinaryDb = (ctx.root && path.resolve(ctx.root) === hccRoot ? ctx.dbPath : null) ||
+  const sameHookRoot = () => {
+    if (!ctx.root) return false;
+    try { return fs.realpathSync(ctx.root) === fs.realpathSync(hccRoot); }
+    catch { return path.resolve(ctx.root) === hccRoot; }
+  };
+  const ordinaryDb = (sameHookRoot() ? ctx.dbPath : null) ||
     process.env.HCC_DB;
   if (nativeProject && !fs.existsSync(nativeProject.db)) {
     throw new CliError('NATIVE_HOOK_OWNERSHIP_MISMATCH', 'Native hook database must already be owned by its runtime');
@@ -100,9 +112,9 @@ async function cmdHook(ctx, args) {
   const hookCtx = {
     ...ctx,
     root: nativeProject?.root || dshProject?.root || hccRoot,
-    dbPath: nativeProject?.db || dshProject?.db || ordinaryDefaultDb || path.resolve(ordinaryDb)
+    dbPath: nativeProject?.db || dshProject?.db || ordinaryDefaultDb || path.resolve(ordinaryDb),
+    ...(launchRootIdentity ? { initialRootIdentity: launchRootIdentity } : {})
   };
-  if (!nativeOwner) registerProjectActivity(hookCtx);
 
   // dsh uses only its true session ID. Ordinary hooks retain environment,
   // resume, session, and terminal identity precedence.
@@ -123,6 +135,7 @@ async function cmdHook(ctx, args) {
   // Hook delivery must not migrate another workspace's registered database.
   const db = isDsh || nativeOwner ? connect(hookCtx, { migrateRegistered: false }) : connect(hookCtx);
   try {
+    if (!nativeOwner) registerProjectActivity(hookCtx);
     if (nativeOwner) {
       // Native delivery owns context injection and completion receipts. Hooks
       // only renew its verified owner, never turn a native binding into a

package/lib/cli/commands/install.mjs

@@ -5,17 +5,19 @@ import { secureExistingProjectStateDirectory } from '../../runtime/project-path.
 import { legacyProjectStateDir, projectStateDir } from '../../runtime/paths.mjs';
 import { privateProjectStateDir, inspectPrivateProjectAuthority,
   purgePrivateProjectState } from '../../runtime/private-state.mjs';
+import { captureSelectedCwdIdentity } from '../../process/selected-cwd-identity.mjs';
+import { purgePinnedLegacyProjectState } from '../../process/pinned-project-state.mjs';
 
 export function createInstallCommands(deps) {
   const {
     path, fs, process, CliError, parseOpts, validateOpts, wantsHelp,
     printResult, commandPath, connect, readRuntime, runtimeRequest,
-    runtimePath, globalRuntimePath, PRODUCT_NAME, VERSION, NPM_PACKAGE_NAME,
+    globalRuntimePath, PRODUCT_NAME, VERSION, NPM_PACKAGE_NAME,
     helpInstallHooks, helpShim, helpUninstall, helpUpdate,
     loadSetup, shellCommand,
 
 
-    sameResolvedPath, writeGuidance, removeGuidanceBlocks,
+    sameResolvedPath, writeGuidance, removeGuidanceBlocks, spawnPinnedStateProcess,
   
   } = deps;
 
@@ -240,13 +242,23 @@ async function cmdUninstall(ctx, args) {
   if (opts.purge && !opts.yes) {
     throw new CliError('CONFIRM_REQUIRED', 'Refusing to purge project data without --yes');
   }
+  const selectedRoot = opts.purge ? captureSelectedCwdIdentity(ctx.root) : null;
+  let selectedLegacyState = null;
+  try {
   // Resolve before changing hooks, guidance, or runtime state. An unsafe root
   // with unmigrated legacy data must not be treated as an empty private store.
   let purgeStateDir = null;
+  let purgeIsLegacy = false;
   let missingPrivateState = false;
   if (opts.purge) {
     try {
-      purgeStateDir = secureExistingProjectStateDirectory(ctx.root).stateDir;
+      const resolved = secureExistingProjectStateDirectory(ctx.root);
+      purgeStateDir = resolved.stateDir;
+      purgeIsLegacy = path.resolve(purgeStateDir) === path.join(selectedRoot.canonical, '.hello-cc');
+      if (purgeIsLegacy && resolved.exists) {
+        selectedLegacyState = captureSelectedCwdIdentity(purgeStateDir);
+        selectedRoot.assertUnchanged();
+      }
     } catch (error) {
       if (projectStateDir(ctx.root) !== privateProjectStateDir(ctx.root)) throw error;
       const recoverablePending = error?.code === 'STATE_MIGRATION_REQUIRED' &&
@@ -261,7 +273,12 @@ async function cmdUninstall(ctx, args) {
   const lines = [];
 
   let runtime = null;
+  let runtimePointer = null;
   if (!missingPrivateState) {
+    // Keep the validated state route fixed across the asynchronous stop probe.
+    // Re-deriving it afterwards could remove another project's pointer if a
+    // user-supplied root alias is retargeted in the meantime.
+    runtimePointer = path.join(secureExistingProjectStateDirectory(ctx.root).stateDir, 'runtime.json');
     try {
       runtime = readRuntime(ctx);
     } catch (err) {
@@ -274,7 +291,7 @@ async function cmdUninstall(ctx, args) {
       lines.push('runtime stopped');
     } catch (err) {
       if (!(err instanceof CliError && err.code === 'RUNTIME_UNREACHABLE')) throw err;
-      try { fs.rmSync(runtimePath(ctx), { force: true }); } catch {}
+      try { fs.rmSync(runtimePointer, { force: true }); } catch {}
       lines.push('stale runtime file removed');
     }
   } else {
@@ -282,6 +299,7 @@ async function cmdUninstall(ctx, args) {
   }
 
   const { uninstallClaudeHooks, uninstallCodexHooks, uninstallShims, uninstallPathEntry } = await loadSetup();
+  selectedRoot?.assertUnchanged();
   const claude = uninstallClaudeHooks();
   const codex = uninstallCodexHooks();
   const shims = uninstallShims();
@@ -294,20 +312,26 @@ async function cmdUninstall(ctx, args) {
   let guidance = [];
   let purged = false;
   if (opts.purge) {
-    guidance = removeGuidanceBlocks(ctx);
+    guidance = removeGuidanceBlocks(ctx, { expectedBinding: selectedRoot });
     try {
-      if (path.resolve(purgeStateDir) === path.resolve(privateProjectStateDir(ctx.root))) {
+      selectedRoot.assertUnchanged();
+      if (!purgeIsLegacy) {
         // Revalidate and delete under the same transition lock used by init
         // and migration. An interrupted deletion remains marked purging.
         purgeStateDir = purgePrivateProjectState(ctx.root);
       } else {
         // Async shutdown and hook removal happened after the initial lookup.
         // Refuse a stale legacy target if project-state routing changed.
-        const current = secureExistingProjectStateDirectory(ctx.root).stateDir;
-        if (path.resolve(current) !== path.resolve(purgeStateDir)) {
+        const current = secureExistingProjectStateDirectory(ctx.root);
+        if (path.resolve(current.stateDir) !== path.resolve(purgeStateDir)) {
           throw new CliError('PROJECT_PATH_FORBIDDEN', 'Project state route changed during uninstall');
         }
-        fs.rmSync(purgeStateDir, { recursive: true, force: true });
+        if (selectedLegacyState) {
+          purgePinnedLegacyProjectState(ctx.root, purgeStateDir, selectedRoot, selectedLegacyState,
+            { spawnProcess: spawnPinnedStateProcess });
+        } else if (current.exists) {
+          throw new CliError('PROJECT_PATH_FORBIDDEN', 'Project state appeared during uninstall');
+        }
       }
       purged = true;
       lines.push(`project data removed: ${purgeStateDir}`);
@@ -327,6 +351,10 @@ async function cmdUninstall(ctx, args) {
   }
 
   printResult(ctx, { runtime: Boolean(runtime), claude, codex, shims, path_entry: pathEntry, purge: purged, guidance }, () => lines.join('\n'));
+  } finally {
+    selectedLegacyState?.release();
+    selectedRoot?.release();
+  }
 }
 
 // ─── hcc scan ────────────────────────────────────────────────────────────────

package/lib/cli/commands/lock.mjs

@@ -2,6 +2,7 @@
 // Factory pattern with injected deps.
 
 import { readTx } from '../../db/schema.mjs';
+import { isPeerEvidenceCompatibilityProtected } from '../../core/peers/evidence.mjs';
 import {
   findRequestedLock,
   upsertRequestedLock,
@@ -101,7 +102,8 @@ export function createLockCommands(deps) {
                 !(Number(row.expires_at) <= t && evidenceByOwner.get(row.owner)?.state === 'dead'))
             : subject.locks.filter((row) =>
                 Number(row.expires_at) > t ||
-                evidenceByOwner.get(row.owner)?.state === 'live'
+                evidenceByOwner.get(row.owner)?.state === 'live' ||
+                isPeerEvidenceCompatibilityProtected(evidenceByOwner.get(row.owner))
               );
           const conflict = activeLocks.find((row) => locksConflict(row, requested) && row.owner !== peer);
           if (conflict) {

package/lib/cli/commands/misc.mjs

@@ -1,17 +1,79 @@
 // Small utility commands extracted from bin/hcc.mjs: down, find-root, which-real.
+import { performance } from 'node:perf_hooks';
+import { resolveProjectDatabase } from '../../runtime/project-path.mjs';
 
 export function createMiscCommands(deps) {
   const {
-    path, process, CliError, parseOpts, printResult,
+    path, fs, process, CliError, parseOpts, printResult,
     readRuntime, runtimeRequest, runtimePath, globalRuntimePath,
     reclaimRuntimePointerFiles, helpDown, loadSetup,
-    waitForProcessIdentityExit,
+    waitForProcessIdentityExit, inspectProcessIdentity, compareProcessIdentity, withFileLock,
     PRODUCT_NAME
   } = deps;
 
+  function sameStopPointer(left, right) {
+    return left.raw === right.raw && ['dev', 'ino', 'size', 'mtimeMs', 'ctimeMs']
+      .every((key) => left.stat[key] === right.stat[key]);
+  }
+
+  function readStopPointer(file) {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('invalid runtime pointer');
+    const raw = fs.readFileSync(file, 'utf8');
+    const current = fs.lstatSync(file);
+    if (current.isSymbolicLink() || !current.isFile() ||
+        !sameStopPointer({ raw, stat }, { raw, stat: current })) {
+      throw new Error('runtime pointer changed');
+    }
+    return { raw, stat };
+  }
+
+  function stopOwnerEvidence(runtime, pointerFiles) {
+    try {
+      if (runtime.source === 'env') return null;
+      const source = pointerFiles.find((file) => path.resolve(file) === path.resolve(runtime.source || ''));
+      const url = new URL(runtime.base_url);
+      if (!source || !['http:', 'https:'].includes(url.protocol) ||
+          !['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)) return null;
+      const owner = runtime.process_identity || runtime.processIdentity;
+      if (Object.hasOwn(runtime, 'process_identity') && Object.hasOwn(runtime, 'processIdentity')) return null;
+      if (owner?.pid !== Number(runtime.pid) || compareProcessIdentity(owner, owner) !== 'live') return null;
+      const observed = inspectProcessIdentity(owner.pid);
+      if (observed.state !== 'live' || compareProcessIdentity(owner, observed.identity) !== 'live' ||
+          owner.commandHash !== observed.identity.commandHash) return null;
+      const pointer = readStopPointer(source);
+      const recorded = JSON.parse(pointer.raw);
+      if (Object.hasOwn(recorded, 'process_identity') && Object.hasOwn(recorded, 'processIdentity')) return null;
+      const recordedOwner = recorded.process_identity || recorded.processIdentity;
+      if (Number(recorded.pid) !== owner.pid ||
+          compareProcessIdentity(owner, recordedOwner) !== 'live' || owner.commandHash !== recordedOwner.commandHash ||
+          ['base_url', 'token', 'tls_ca_file'].some((key) => recorded[key] !== runtime[key])) return null;
+      return { source, owner, pointer };
+    } catch {
+      return null;
+    }
+  }
+
   async function cmdDown(ctx, args) {
     if (args[0] === '--help' || args[0] === '-h') return helpDown();
-    const pointerFiles = [runtimePath(ctx), globalRuntimePath()];
+    const stopStartedAt = performance.now();
+    const elapsedSince = (startedAt) => Math.max(0, Math.round(performance.now() - startedAt));
+    function stopFailure(error, phase, state = 'unknown', confirmationMs = null) {
+      // Retain the original error and transport context. Only fixed phase/state
+      // vocabulary and monotonic durations describe the local confirmation.
+      error.extra = {
+        ...error.extra,
+        stopPhase: phase,
+        state: ['live', 'dead', 'unknown'].includes(state) ? state : 'unknown',
+        stopElapsedMs: elapsedSince(stopStartedAt),
+        ...(confirmationMs === null ? {} : { confirmationMs })
+      };
+      return error;
+    }
+    const localPointer = ctx.root
+      ? path.join(resolveProjectDatabase({ root: ctx.root, createStateDir: false }).stateDir, 'runtime.json')
+      : runtimePath(ctx);
+    const pointerFiles = [localPointer, globalRuntimePath()];
     let runtime;
     try {
       runtime = readRuntime(ctx);
@@ -23,31 +85,61 @@ export function createMiscCommands(deps) {
         `${PRODUCT_NAME} stale runtime pointer removed${result.pointers === 1 ? '' : 's'}`);
       return;
     }
+    const stopEvidence = stopOwnerEvidence(runtime, pointerFiles);
     try {
       await runtimeRequest(ctx, 'POST', '/api/runtime/stop', {}, runtime);
     } catch (err) {
       if (!(err instanceof CliError && err.code === 'RUNTIME_UNREACHABLE')) throw err;
-      if (runtime.source === 'env') throw err;
-      const source = path.resolve(String(runtime.source || ''));
-      const localSource = pointerFiles.find((file) => path.resolve(file) === source);
-      if (!localSource) throw err;
-      const cleanup = reclaimRuntimePointerFiles([localSource], { reclaimUnknown: false });
-      if (cleanup.reclaimed !== 1 || cleanup.blocked) throw err;
-      printResult(ctx, { runtime: localSource }, () => `${PRODUCT_NAME} stale runtime pointer removed`);
+      if (!stopEvidence) throw stopFailure(err, 'evidence_unavailable');
+      const confirmationStartedAt = performance.now();
+      const stopped = await waitForProcessIdentityExit(stopEvidence.owner, {
+        timeoutMs: 5_000,
+        intervalMs: 25
+      });
+      const confirmationMs = elapsedSince(confirmationStartedAt);
+      if (stopped.state !== 'dead') throw stopFailure(err, 'exit_unconfirmed', stopped.state, confirmationMs);
+      let cleanup;
+      let cleanupPhase = 'pointer_cleanup_failed';
+      try {
+        cleanup = withFileLock(stopEvidence.source, (file) => {
+          let current;
+          try { current = readStopPointer(file); }
+          catch (error) {
+            if (error.code === 'ENOENT') return { reclaimed: 0, blocked: false };
+            throw error;
+          }
+          if (!sameStopPointer(stopEvidence.pointer, current)) {
+            cleanupPhase = 'pointer_changed';
+            throw err;
+          }
+          // Hold the pointer's existing lock across comparison and reclamation.
+          // A replacement owner must never be removed by this stop request.
+          return reclaimRuntimePointerFiles([file], {
+            reclaimUnknown: false,
+            withLock: (_file, operation) => operation(file)
+          });
+        }, { createParent: false });
+      } catch { throw stopFailure(err, cleanupPhase, 'dead', confirmationMs); }
+      if (cleanup.blocked || cleanup.reclaimed > 1) throw stopFailure(err, 'pointer_cleanup_failed', 'dead', confirmationMs);
+      printResult(ctx, { runtime: stopEvidence.source }, () => cleanup.reclaimed === 1
+        ? `${PRODUCT_NAME} stale runtime pointer removed`
+        : `${PRODUCT_NAME} runtime stopped`);
       return;
     }
     if (runtime.source !== 'env') {
       const processIdentity = runtime.process_identity || runtime.processIdentity || runtime.pid;
+      const confirmationStartedAt = performance.now();
       const stopped = await waitForProcessIdentityExit(processIdentity, {
         timeoutMs: 5_000,
         intervalMs: 25
       });
+      const confirmationMs = elapsedSince(confirmationStartedAt);
       if (stopped.state !== 'dead') {
-        throw new CliError(
+        throw stopFailure(new CliError(
           'RUNTIME_STOP_TIMEOUT',
           `Runtime accepted the stop request, but process ${runtime.pid || 'unknown'} did not exit within 5s.`,
-          { pid: runtime.pid || null, state: stopped.state }
-        );
+          { pid: runtime.pid || null }
+        ), 'exit_unconfirmed', stopped.state, confirmationMs);
       }
     }
     printResult(ctx, { runtime: runtime.source || runtime.base_url }, () => `${PRODUCT_NAME} runtime stopped`);