solopup-memory 0.22.0-beta.3 → 0.23.0-beta.2

package/CHANGELOG.md

@@ -1,11 +1,27 @@
 # Changelog
 
+## 0.23.0-beta.2 — conflict-aware memory guidance
+
+- Guide agents to compare sources, scope and time when task history and long-term memory disagree, follow explicit current user corrections, and ask when evidence is insufficient.
+- Report whether `memory_search` is available to the current session; when it is unavailable or cannot be verified, do not claim a search was performed or that missing memory does not exist.
+- Preserve task history and existing memory admission rules; this guidance does not erase historical copies or guarantee model behavior. Super Agent workers still require explicit worktree setup and do not have memory tools by default.
+- The tested Super Agent prototype can skip preparation on retry after a failed preparation, causing a worker to start without project memory. Inspect the leftover workspace and ensure preparation reruns before retrying; this release does not fix the prototype.
+- Candidate validation and release status must be verified against release artifacts; no claim of real Super Agent semantic acceptance is implied.
+
+## 0.23.0-beta.1 — project memory across worktrees
+
+- Add an explicit, review-before-apply link between worktrees of the same local Git repository so a worker can use an existing project memory store. Existing independent stores are not merged or overwritten; linking is disabled until explicitly configured.
+- Add a reviewed unlink operation, local repository replacement detection, and concurrent registration protection.
+- The tested Super Agent prototype does not expose memory search or write tools to workers by default. A failed prepare can be skipped on retry; inspect the leftover directory and ensure preparation reruns before retrying.
+- Unlinking affects future path resolution, not in-flight work or existing conversation copies. Full G1, real-model semantics, cross-platform behavior, and all concurrency cases are not certified.
+
+
 ## 0.22.0-beta.3 — DSH 0.2.2 compatibility and first-run integration
 
 - Await callable asynchronous Session Projection registrations before publishing tools, prompt contributions or the successful load marker. Retain the new handle and use its `stateOf(session)`; preserve the legacy registry reader for older hosts. Registration rejection fails activation.
 - Integrate PR #2 first-run instructions, source-recall example and test-directory organization with the current detection, telemetry, dream planner and lock-contention fixes. All tests, including the newer main-branch suites, remain in the package and npm test.
 - Add real CLI/Loader history-contract probes covering activation, live Session projection, scoped history replacement, cold replay, registration rejection and disposal, using isolated homes and synthetic input without model calls. The actual archive runs these checks too.
-- This is a new source candidate, not a claim of npm publication, desktop semantic acceptance or production-data testing. Existing beta tags are unchanged.
+- Published as public beta `0.22.0-beta.3` to npm (dist-tag `beta`) and GitHub Releases; the npm tarball sha256 matches the release checksum. This is still not a claim of desktop semantic acceptance or production-data testing, and existing beta tags are unchanged.
 
 ## 0.22.0-beta.2 — detection layer, semantic pipeline gate, dream P0/P1
 

package/README.en.md

@@ -44,7 +44,7 @@ The Chinese message asks to keep this project's delivery notes in Chinese. Curre
 
 Use the official plugin-manager command in [Quick install](#quick-install).
 
-The beta tag follows verified public beta releases. For an exact version, choose a published version from the release page, for example `solopup-memory@0.21.0-beta.3`. Git installation remains available with `github:OakcoderX/solopup-memory#v0.21.0-beta.3`; the release page supplies a full commit SHA for an immutable Git pin. This package ships executable ESM and has no dependency installation or build scripts. Alternatively download its release tarball and install the local file with `dsh plugin --profile desktop add /absolute/path/to/solopup-memory-0.21.0-beta.3.tgz --offline --ignore-scripts`.
+The beta tag follows verified public beta releases. For an exact version, choose a published version from the release page, for example `solopup-memory@0.22.0-beta.3`. Git installation remains available with `github:OakcoderX/solopup-memory#v0.22.0-beta.3`; the release page supplies a full commit SHA for an immutable Git pin. This package ships executable ESM and has no dependency installation or build scripts. Alternatively download its release tarball and install the local file with `dsh plugin --profile desktop add /absolute/path/to/solopup-memory-0.22.0-beta.3.tgz --offline --ignore-scripts`.
 
 Restart the profile and use `memory_status`. Existing legacy stores may require explicit local review. Do not delete control files to bypass that review. If upgrading from `dsh-memory`, create a full private backup, stop the hosts using that data, remove the old package, then install SoloPup Memory. Do not run both packages together. The data location and legacy format identifiers are intentionally retained.
 
@@ -72,6 +72,37 @@ Retrieval uses lexical matching, not embeddings; cross-language and synonym reca
 
 Verified locally on macOS with DSH Node 24. Other runtime/platform results must be read from actual CI and release receipts; registration or unit tests alone do not establish semantic quality or sustained-use acceptance.
 
+## Project memory across worktrees (0.23 beta)
+
+This feature starts in 0.23.0-beta.1 and is not part of 0.22.0-beta.3. Project stores remain separate by default. To explicitly link a worker worktree to an existing project store in the same local Git repository, run from the source or installed package directory:
+
+```sh
+node scripts/projects.mjs link --cwd /path/to/worker-worktree --owner /path/to/project-worktree
+# Inspect the preview and use its reviewed value:
+node scripts/projects.mjs link --cwd /path/to/worker-worktree --owner /path/to/project-worktree --apply --reviewed-link <reviewed>
+```
+
+The owner must already have a project store. Linking refuses an existing separate worker store; it does not merge or overwrite it. Clones are not linked automatically, and moving or restoring a repository can require registration again. Unlink using the same preview-then-apply process; it does not delete memory:
+
+```sh
+node scripts/projects.mjs unlink --cwd /path/to/worker-worktree
+node scripts/projects.mjs unlink --cwd /path/to/worker-worktree --apply --reviewed-link <reviewed>
+```
+
+Unlinking changes subsequent directory resolution; it is not immediate revocation for running work. Previously resolved store paths, in-flight capture jobs, and content already in sessions are not automatically invalidated or deleted. Stop the affected Workers and memory capture before unlinking, and review existing copies separately.
+
+To opt in from a Super Agent prepare command, append the following **after** the worktree creation command, replacing paths with local absolute paths. The plugin does not alter the Super Agent configuration. If creating or linking fails, this launch stops. The Super Agent prototype can skip preparation on retry when the directory remains; do not retry until the leftover directory is inspected and preparation is certain to run again.
+
+```sh
+node /absolute/path/to/solopup-memory/scripts/superagent-worktree.mjs --owner /absolute/path/to/project-worktree --apply
+```
+
+The helper reads `DSH_SUPERAGENT_DIR` supplied by the Super Agent and retains same-repository and existing-store checks. `--apply` records the user’s opt-in through the trusted prepare configuration.
+
+In the tested Super Agent prototype, default Worker tool restrictions do not expose `memory_search` or `memory_write`. A linked project can supply memory context to the Worker, but this does not enable direct use of those tools or establish Worker-initiated memory writes.
+
+Linking does not remove copies already sent to a model or stored in ordinary session history. Real-model semantic quality and all platforms have not been validated.
+
 ## Development
 
 Requires Node >=24.9. No npm dependencies are needed for the test suite. Tests live in `test/`; runtime modules retain their existing paths. The full explicit test set is preserved in both `npm test` and the package archive.

package/README.md

@@ -70,11 +70,44 @@ Markdown 索引和主题正文便于阅读；来源、候选、历史与调用
 
 条件全部成立才满足 `conditions`；任何一个例外成立就命中 `except`。同一条件不能既必须成立又必须排除。来源上限超出时明确拒绝，不截掉必要来源来凑数。
 
+## 跨 worktree 项目记忆（0.23 测试版）
+
+以下功能从 0.23.0-beta.1 开始提供，不属于 0.22.0-beta.3。默认各工作目录仍使用各自的项目库。若主 Agent 与 Worker 使用同一 Git 仓库的不同 worktree，可在源码或安装包目录中通过本地命令显式关联：
+
+```sh
+node scripts/projects.mjs link --cwd /path/to/worker-worktree --owner /path/to/project-worktree
+# 核对预览后，将返回的 reviewed 填入：
+node scripts/projects.mjs link --cwd /path/to/worker-worktree --owner /path/to/project-worktree --apply --reviewed-link <reviewed>
+```
+
+来源目录须已有项目库；Worker 若已有独立项目库，命令会拒绝，不会合并或覆盖。关联会检查本地仓库身份，不自动关联克隆；仓库或文件系统迁移后可能需要重新登记。取消关联同样先预览、再使用 `reviewed` 执行，且不删除记忆：
+
+```sh
+node scripts/projects.mjs unlink --cwd /path/to/worker-worktree
+node scripts/projects.mjs unlink --cwd /path/to/worker-worktree --apply --reviewed-link <reviewed>
+```
+
+取消关联只改变之后的目录解析，不是运行中任务的即时撤权：已解析出的项目库路径、正在处理的捕获任务及已进入会话的内容不会因此自动失效或删除。需要停止使用该共享关系时，先停止相关 Worker 和记忆捕获，再取消关联；历史副本须另行检查。
+
+超级 Agent 的准备命令可以在创建 worktree **之后**，显式追加以下命令，自动登记该次 Worker 目录。请将路径替换为本机的绝对路径；这是一项用户主动配置，不会自动改写超级 Agent 设置。若创建或登记失败，本次启动会停止；超级 Agent 原型重试时可能因目录已存在而跳过准备命令，不能直接重试，须先检查残留目录并确保准备步骤会重新执行。
+
+```sh
+node /absolute/path/to/solopup-memory/scripts/superagent-worktree.mjs --owner /absolute/path/to/project-worktree --apply
+```
+
+该命令读取超级 Agent 提供的 `DSH_SUPERAGENT_DIR`，仍执行同仓库和已有独立库检查；`--apply` 表示用户在准备配置中授权执行关联。
+
+在测试的超级 Agent 原型中，Worker 的默认工具限制不开放 `memory_search` 或 `memory_write`。关联可以让已登记的项目记忆进入 Worker 上下文，但不表示 Worker 可直接调用这些记忆工具；不要将其视为 Worker 主动写入记忆的支持。
+
+关联不会清除已发送给模型或保存在普通会话中的副本。真实模型语义质量和全部跨平台环境尚未验收。
+
+从 0.23.0-beta.2 起，记忆协议提示模型在任务历史与长期记忆不一致时核对来源、范围和时间；用户明确更正后按新要求工作，无法判断时向用户澄清。提示不能保证模型一定判断正确，也不会自动更改历史任务、清除会话副本或代替现有记忆写入审核。Worker 未配置记忆工具时，不能声称已经写入记忆。
+
 ## 安装与卸载
 
 使用上方[先试起来](#先试起来)的 DeepSeek Harness 官方插件管理器命令安装。代码为可直接执行的 ESM，无安装时构建脚本，也不需要 npm 账户。
 
-`beta` 标签跟随已公开并完成下载核验的测试版。需要固定版本时，从发行页选择准确版本号，例如 `solopup-memory@0.21.0-beta.3`；Git 安装也可用 `dsh plugin --profile desktop add github:OakcoderX/solopup-memory#v0.21.0-beta.3 --ignore-scripts`，需要不可变 Git 来源时，用发行页的完整提交 SHA 替换标签。也可下载发行页的 `.tgz`，使用 `dsh plugin --profile desktop add /absolute/path/to/solopup-memory-0.21.0-beta.3.tgz --offline --ignore-scripts`。
+`beta` 标签跟随已公开并完成下载核验的测试版。需要固定版本时，从发行页选择准确版本号，例如 `solopup-memory@0.22.0-beta.3`；Git 安装也可用 `dsh plugin --profile desktop add github:OakcoderX/solopup-memory#v0.22.0-beta.3 --ignore-scripts`，需要不可变 Git 来源时，用发行页的完整提交 SHA 替换标签。也可下载发行页的 `.tgz`，使用 `dsh plugin --profile desktop add /absolute/path/to/solopup-memory-0.22.0-beta.3.tgz --offline --ignore-scripts`。
 
 已安装旧名 `dsh-memory` 时，先完成完整备份、关闭使用该库的宿主，用官方管理器移除旧包，再安装新包；不要同时启用两个记忆插件。新名字继续使用原记忆库和控制格式。
 

package/RELEASE.md

@@ -1,12 +1,31 @@
+# 0.23.0-beta.2 — memory conflict guidance (candidate)
+
+This candidate adds a short instruction to the existing SoloPup memory protocol: compare source, scope and time when task history and long-term memory disagree; follow a current explicit user correction; ask when the evidence is insufficient; do not silently rewrite memory from guesses or historical retellings.
+
+The existing explicit same-repository worktree link remains opt-in. The tested Super Agent prototype does not expose memory search or write tools to workers by default. A failed prepare may be skipped on retry: inspect the leftover workspace and ensure preparation runs before retrying. This candidate does not repair that upstream behavior.
+
+The instruction is guidance for a model, not a guarantee. It does not delete task history, old conversations, prior model requests or external copies, nor does it guarantee immediate revocation in those copies. It does not add multi-user memory support. Real-model comparison and end-to-end Super Agent acceptance must be reported separately from automated tests.
+
+Publication status and final artifact verification are tracked by npm, GitHub Releases and release automation.
+# 0.23.0-beta.1 — project memory across worktrees
+
+This version adds opt-in, reviewed linking between worktrees of the same local Git repository. If a Super Agent prepare command fails after creating the directory, its prototype can skip preparation on retry and start the worker without the intended link; inspect the leftover directory and do not retry until preparation will run again. It does not automatically merge pre-existing project stores or link clones. Review the worktree identity, performance and recovery limits before use. G1 remains unpassed; real-model semantics and cross-platform operation have not been validated. Existing conversation or provider copies are not erased.
+
+Unlink changes future directory resolution and is not an immediate revocation barrier for already resolved paths or in-flight capture. Stop affected Workers and capture before unlinking and review retained copies.
+
+The tested Super Agent prototype does not expose `memory_search` or `memory_write` to Workers by default. Linking enables project context injection; it does not establish direct Worker memory tool access.
+
+A local candidate was installed and loaded in one daily DSH profile; its health check detected pre-existing pending withdrawal cleanup. Real-model semantic acceptance remains outstanding. The npm beta tag and GitHub Releases identify versions that have actually been published.
+
 # 0.22.0-beta.3 — DSH 0.2.2 compatibility and first-run integration
 
-**Source candidate, not a published beta.** This version integrates the unmerged onboarding/test-layout work with current main and waits for DSH asynchronous Session Projection registration before exposing dependent features. New hosts use retained projection handles; older hosts retain their registry-reader path. Existing beta tags and the published registry version are not rewritten.
+**Published public beta.** Published to npm as `0.22.0-beta.3` (dist-tag `beta`) and to GitHub Releases on 2026-11-09; the npm tarball sha256 `621bf9c0d21e39d769377a421e80330402c7d9d5840745209b8500a11c9f2fe2` matches the release `SHA256SUMS`. `memory_status` should report `0.22.0-beta.3` after a clean restart. This version integrates the onboarding/test-layout work with current main and waits for DSH asynchronous Session Projection registration before exposing dependent features. New hosts use retained projection handles; older hosts retain their registry-reader path. Existing beta tags and the published registry version are not rewritten.
 
 The isolated Linux host checks use the official npm CLI distributions for DSH 0.2.1-rc.5 and 0.2.2-rc.1, synthetic Sessions, no user profile or credentials, and no model calls. They cover six-tool activation, live projection state, exact removal of obsolete memory sections while preserving other content, cold replay, rejected registrations and owner disposal. This is not real-model semantic acceptance or daily desktop verification. See [COMPATIBILITY.md](COMPATIBILITY.md) and the integration receipt for exact results and remaining gates.
 
 # 0.22.0-beta.2 — detection layer, semantic pipeline gate, dream P0/P1
 
-**Source update, not a published beta.** (v0.22.0-beta.1 tag failed before submission because npm 11 parsed the relative tarball path as a GitHub shorthand; no npm version was published. This beta.2 commit fixes the path and passes the same gates.) This commit adds engineering infrastructure and read-only/planning features; it does not claim stable semantic acceptance or publish to npm/market. Published version remains 0.21.0-beta.3.
+**Superseded by 0.22.0-beta.3; never published.** (v0.22.0-beta.1 tag failed before submission because npm 11 parsed the relative tarball path as a GitHub shorthand; no npm version was published. This beta.2 commit fixes the path and passes the same gates, but publication completed only with beta.3.) This commit adds engineering infrastructure and read-only/planning features; stable semantic acceptance is still not claimed.
 
 - L0 detection: `detect.mjs` + `scripts/detect.mjs` read-only invariant checks (index format, projection consistency, anchors, withdrawal residue, duplicates/conflicts, budgets, scope, version drift, topic structure, duplicate stores). `memory_status` exposes a bounded `lint` summary.
 - L2 pipeline-fidelity suite: 10 frozen cases (~190ms) checking that a correct or deliberately wrong candidate keeps its conditions/meaning/expiry/scope through write → projection → retrieval. `semanticTruthEvaluated` stays false (no real extraction model run).

package/index.mjs

@@ -47,7 +47,7 @@ import { captureSessionEligible, captureInputDescriptor, enqueueCaptureInput, bi
 import { join, resolve, relative } from 'node:path'
 import { DEFAULT_AUTO_CAPTURE, normalizePluginConfig } from './plugin-config.mjs'
 import { optionalService } from './host-services.mjs'
-import { projectStoreDir, inspectProjectStore, migrateProjectStore, recoverProjectStore } from './project-stores.mjs'
+import { projectStoreDir, inspectProjectStore, migrateProjectStore, recoverProjectStore, linkWorktreeProject, unlinkWorktreeProject } from './project-stores.mjs'
 import { watchOptionalService } from './service-readiness.mjs'
 export { Config } from './plugin-config.mjs'
 
@@ -131,6 +131,8 @@ export function storeDirFor(scope, cwd) {
   return ensureManagedProject(root,projectStoreDir(root, findProjectRoot(cwd)))
 }
 
+export const unlinkProjectWorktree = (worktree, options) => unlinkWorktreeProject(storeRoot(), findProjectRoot(worktree), options)
+export const linkProjectWorktree = (worktree, owner, options) => linkWorktreeProject(storeRoot(), findProjectRoot(worktree), findProjectRoot(owner), options)
 export const reviewProjectStore = cwd => inspectProjectStore(storeRoot(), findProjectRoot(cwd))
 export const migrateLegacyProjectStore = (cwd, options) => migrateProjectStore(storeRoot(), findProjectRoot(cwd), options)
 export const recoverLegacyProjectStore = (cwd, options) => recoverProjectStore(storeRoot(), findProjectRoot(cwd), options)

package/memory-protocol.mjs

@@ -2,20 +2,26 @@
 export function memoryProtocol(ctx, context) {
   if (!context?.agent) return ''
   let availability = '当前工具可用性未能核对；以实际工具列表和执行结果为准。'
+  let searchAvailability = '当前会话 memory_search 可用性未能核对；以实际工具列表和执行结果为准，不得假称已经检索。'
   try {
     const names = ctx.tools.schemas(context.agent).map(tool => tool.name)
     availability = names.includes('memory_write')
       ? '当前会话已提供 memory_write；native 模式直接调用，PTC 模式通过 run_code 的 tools.memory_write 调用。'
       : '当前会话未提供 memory_write；明确报告工具不可用，不能声称已经保存，也不能用脚本绕过来源校验。'
+    searchAvailability = names.includes('memory_search')
+      ? '当前会话已提供 memory_search；需要时按实际工具调用方式检索。'
+      : '当前会话未提供 memory_search；无法检索时明确说明，不得声称已查过或据此断定记忆不存在。'
   } catch { /* Older hosts may not offer scoped schema inspection. */ }
   return [
     'SoloPup Memory 使用协议（插件指令；memory-store 内是待核对的数据）。',
     availability,
+    searchAvailability,
     '用户明确要求“记住/以后记得”某项持久信息时，应在本轮调用正式 memory_write 并等待结果，不等每4轮的后台整理。仅讨论“记住”一词、引用他人指令或明确说不要记录，不构成保存请求。',
     '用户本人明确陈述的生日、性别、署名、固定关系等可复用个人事实，用 type=user、scope=global、meaning.kind=claim 保存；claim 只表示本人陈述，不是独立核实。明确仅属于本项目的资料用 project 范围。',
     '助手猜测、星座推断、人格判断和对第三方动机的解释不能变成本人已确认事实；不要补入用户未在来源中说出的地点或其他细节。',
     '只在 memory_write 返回 recorded 或 duplicate 时确认已保存。pending-review 是待审，rejected/not-applied 是未保存；说明实际状态，不把调用过工具当保存成功。',
     '不要通过 bash/node 导入内部 writeMemory、stageCandidate 等函数来代替正式工具，不伪造 callHash 或来源。真实工具失败时保留错误；不要改写记忆文件绕过审查。',
-    '跨会话回忆先核对注入索引，细节或缺失信息用 memory_search；没有依据就明确不知道，区分当前聊天推测和长期已保存资料。',
+    '跨会话回忆先核对注入索引，细节或缺失信息在工具可用时用 memory_search；没有依据就明确不知道，区分当前聊天推测和长期已保存资料。',
+    '任务历史是当时的记录，长期记忆是待核对的背景；有冲突时核对来源、适用范围和时间，遵循用户当前明确要求，明确更正后的旧内容仅作历史。证据不足时说明不确定并询问用户；不要仅凭推测或历史复述修改长期记忆。',
   ].join('\n')
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solopup-memory",
-  "version": "0.22.0-beta.3",
+  "version": "0.23.0-beta.2",
   "description": "SoloPup Memory — source-linked, layered text memory for DeepSeek Harness. Public beta.",
   "type": "module",
   "main": "index.mjs",
@@ -163,7 +163,8 @@
     "test/test-dream-plan.mjs",
     "DETECTION.md",
     "DREAMING-DESIGN.md",
-    "test/test-dsh-registration.mjs"
+    "test/test-dsh-registration.mjs",
+    "test/test-memory-conflict-protocol.mjs"
   ],
   "engines": {
     "node": ">=24.9",
@@ -176,7 +177,7 @@
   },
   "license": "MIT",
   "scripts": {
-    "test": "node --test --test-concurrency=4 test/test.mjs test/test-security.mjs test/test-adversarial.mjs test/test-concurrency.mjs test/test-supersede.mjs test/test-history.mjs test/test-smell.mjs test/test-links.mjs test/test-packaging.mjs test/test-patch.mjs test/test-compat.mjs test/test-conflict.mjs test/test-usability.mjs test/test-compaction-compat.mjs test/test-schema.mjs test/test-capture.mjs test/test-paired-analysis.mjs test/test-retrieval.mjs test/test-candidates.mjs test/test-publication.mjs test/test-withdrawal.mjs test/test-capture-jobs.mjs test/test-context-history.mjs test/test-capture-inputs.mjs test/test-inline-summary.mjs test/test-withdrawal-archives.mjs test/test-plugin-contract.mjs test/test-project-stores.mjs test/test-service-readiness.mjs test/test-source-key.mjs test/test-tool-inputs.mjs test/test-tool-write-lifecycle.mjs test/test-tool-write-guard.mjs test/test-source-retirement.mjs test/test-managed-access.mjs test/test-managed-activation.mjs test/test-runtime-startup.mjs test/test-capture-revision.mjs test/test-meaning.mjs test/test-episodes.mjs test/test-belief-revision.mjs test/test-tool-observations.mjs test/test-capture-diagnostics.mjs test/test-snapshots.mjs test/test-restore.mjs test/test-status-both.mjs test/test-text-admission.mjs test/test-capture-submission.mjs test/test-capture-projections.mjs test/test-capture-validation.mjs test/test-capture-validation-job.mjs test/test-capture-validation-flow.mjs test/test-capture-validation-lineage.mjs test/test-native-write-validation.mjs test/test-native-service-lifecycle.mjs test/test-field-lineage.mjs test/test-capture-field-lineage.mjs test/test-validation-transition-context.mjs test/test-control-schema.mjs test/test-revision-admission.mjs test/test-rule-admission.mjs test/test-validation-source-refs.mjs test/test-source-completeness.mjs test/test-legacy-source-identity.mjs test/test-explicit-memory.mjs test/test-privacy.mjs test/test-detect.mjs test/test-telemetry.mjs test/test-semantic-suite.mjs test/test-dream-plan.mjs test/test-dsh-registration.mjs",
+    "test": "node --test --test-concurrency=4 test/test.mjs test/test-security.mjs test/test-adversarial.mjs test/test-concurrency.mjs test/test-supersede.mjs test/test-history.mjs test/test-smell.mjs test/test-links.mjs test/test-packaging.mjs test/test-patch.mjs test/test-compat.mjs test/test-conflict.mjs test/test-usability.mjs test/test-compaction-compat.mjs test/test-schema.mjs test/test-capture.mjs test/test-paired-analysis.mjs test/test-retrieval.mjs test/test-candidates.mjs test/test-publication.mjs test/test-withdrawal.mjs test/test-capture-jobs.mjs test/test-context-history.mjs test/test-capture-inputs.mjs test/test-inline-summary.mjs test/test-withdrawal-archives.mjs test/test-plugin-contract.mjs test/test-project-stores.mjs test/test-service-readiness.mjs test/test-source-key.mjs test/test-tool-inputs.mjs test/test-tool-write-lifecycle.mjs test/test-tool-write-guard.mjs test/test-source-retirement.mjs test/test-managed-access.mjs test/test-managed-activation.mjs test/test-runtime-startup.mjs test/test-capture-revision.mjs test/test-meaning.mjs test/test-episodes.mjs test/test-belief-revision.mjs test/test-tool-observations.mjs test/test-capture-diagnostics.mjs test/test-snapshots.mjs test/test-restore.mjs test/test-status-both.mjs test/test-text-admission.mjs test/test-capture-submission.mjs test/test-capture-projections.mjs test/test-capture-validation.mjs test/test-capture-validation-job.mjs test/test-capture-validation-flow.mjs test/test-capture-validation-lineage.mjs test/test-native-write-validation.mjs test/test-native-service-lifecycle.mjs test/test-field-lineage.mjs test/test-capture-field-lineage.mjs test/test-validation-transition-context.mjs test/test-control-schema.mjs test/test-revision-admission.mjs test/test-rule-admission.mjs test/test-validation-source-refs.mjs test/test-source-completeness.mjs test/test-legacy-source-identity.mjs test/test-explicit-memory.mjs test/test-privacy.mjs test/test-detect.mjs test/test-telemetry.mjs test/test-semantic-suite.mjs test/test-dream-plan.mjs test/test-dsh-registration.mjs test/test-memory-conflict-protocol.mjs",
     "eval": "node eval/run-eval.mjs",
     "gate": "node eval/run-eval.mjs --check",
     "verify": "node scripts/verify.mjs",

package/project-stores.mjs

@@ -1,7 +1,8 @@
 import {managedProjectOperation,registerManagedDestination} from './managed-access.mjs'
 /** Collision-resistant project identity and reviewed, recoverable legacy copying. */
 import { createHash, randomUUID } from 'node:crypto'
-import { constants, lstatSync, openSync, fstatSync, readFileSync, closeSync, readdirSync, renameSync, mkdirSync, rmSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { constants, lstatSync, openSync, fstatSync, readFileSync, closeSync, readdirSync, renameSync, mkdirSync, rmSync, realpathSync } from 'node:fs'
 import { join, resolve, dirname } from 'node:path'
 import { readSafely, writeSafely, ensureStoreDir, withLock } from './security.mjs'
 import { assertPublicationClear } from './publication.mjs'
@@ -102,9 +103,76 @@ function migrationLock(dir, run) {
   return withLock(dir, run, { timeoutMs: 0 })
 }
 
+// Explicit, same-local-Git-worktree mapping. This does not merge existing stores.
+const WORKTREE_LINKS = '.worktree-links.json'
+function worktreeIdentity(root) {
+  try {
+    const env = { PATH: process.env.PATH, HOME: process.env.HOME, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' }
+    const output = execFileSync('git', ['-C', root, 'rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir'], { env, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'] }).trim().split('\n')
+    if (output.length !== 2) fail('worktree-unavailable')
+    const [worktree, common] = output.map(path => realpathSync(path))
+    if (realpathSync(root) !== worktree) fail('worktree-root-required')
+    const commonStat = lstatSync(common, { bigint: true })
+    if (!commonStat.isDirectory() || commonStat.isSymbolicLink()) fail('worktree-unavailable')
+    const commonId = hash(`${commonStat.dev}:${commonStat.ino}:${commonStat.birthtimeNs}`)
+    return { worktree, common, commonId }
+  } catch (error) { if (error.message?.startsWith('project-store-')) throw error; fail('worktree-unavailable') }
+}
+function readWorktreeLinks(store) {
+  safeAncestors(join(store, 'projects'), store)
+  const file = join(store, 'projects', WORKTREE_LINKS)
+  let raw
+  try { raw = readPrivateFile(file).toString('utf8') } catch (error) { if (error.code === 'ENOENT') return { links: [], revision: digest(null) }; throw error }
+  let body
+  try { body = JSON.parse(raw) } catch { fail('worktree-links-corrupt') }
+  if (body?.schema !== 1 || !Array.isArray(body.links) || body.links.length > 128 || body.links.some(row => !row || Object.keys(row).sort().join('|') !== 'common|commonId|owner|worktree' || !hex(row.commonId) || !['common','owner','worktree'].every(key => typeof row[key] === 'string' && row[key].startsWith('/') && resolve(row[key]) === row[key])) || new Set(body.links.map(row => row.worktree)).size !== body.links.length) fail('worktree-links-corrupt')
+  return { links: body.links, revision: hash(raw) }
+}
+function linkedRoot(store, root) {
+  const links = readWorktreeLinks(store).links, physical = (() => { try { return realpathSync(root) } catch { return resolve(root) } })()
+  const link = links.find(row => row.worktree === physical)
+  if (!link) return root
+  const worker = worktreeIdentity(link.worktree), owner = worktreeIdentity(link.owner)
+  if (worker.common !== link.common || owner.common !== link.common || worker.commonId !== link.commonId || owner.commonId !== link.commonId || links.some(row => row.worktree === link.owner)) fail('worktree-link-changed')
+  const old = paths(store, link.worktree)
+  if (directory(old.target) || directory(old.legacy) || readClaim(old).value) fail('worktree-link-conflict')
+  return link.owner
+}
+function unlinkWorktreeLocal(store, worktree, options = {}) {
+  if (options.apply !== undefined && typeof options.apply !== 'boolean') fail('invalid-apply')
+  let physical
+  try { physical = realpathSync(worktree) } catch { physical = resolve(worktree) }
+  const current = readWorktreeLinks(store), row = current.links.find(link => link.worktree === physical)
+  if (!row) fail('worktree-link-not-found')
+  const review = digest({ revision: current.revision, unlink: row })
+  if (options.apply !== true) return { applied: false, worktree: row.worktree, owner: row.owner, reviewed: review }
+  if (options.reviewed !== review) fail('stale-worktree-link-review')
+  writeSafely(join(store, 'projects', WORKTREE_LINKS), JSON.stringify({ schema: 1, links: current.links.filter(link => link.worktree !== physical) }) + '\n')
+  return { applied: true, worktree: row.worktree, owner: row.owner, memoryDeleted: false }
+}
+function linkWorktreeLocal(store, worktree, owner, options = {}) {
+  if (options.apply !== undefined && typeof options.apply !== 'boolean') fail('invalid-apply')
+  const a = worktreeIdentity(worktree), b = worktreeIdentity(owner)
+  if (a.worktree === b.worktree || a.common !== b.common || a.commonId !== b.commonId) fail('worktree-not-same-repository')
+  const links = readWorktreeLinks(store), prior = links.links.find(row => row.worktree === a.worktree)
+  if (links.links.some(row => row.worktree === b.worktree) || links.links.some(row => row.owner === a.worktree)) fail('worktree-link-chain')
+  if (prior && (prior.owner !== b.worktree || prior.common !== a.common || prior.commonId !== a.commonId)) fail('worktree-link-conflict')
+  const old = paths(store, a.worktree), ownerPaths = paths(store, b.worktree)
+  if (directory(old.target) || directory(old.legacy) || readClaim(old).value) fail('worktree-link-conflict')
+  if (!directory(ownerPaths.target)) fail('worktree-owner-store-missing')
+  projectStoreDirLocal(store, b.worktree)
+  const review = digest({ revision: links.revision, worktree: a, owner: b })
+  if (options.apply !== true) return { applied: false, worktree: a.worktree, owner: b.worktree, reviewed: review, alreadyLinked: Boolean(prior) }
+  if (options.reviewed !== review) fail('stale-worktree-link-review')
+  if (prior) return { applied: false, alreadyLinked: true, worktree: a.worktree, owner: b.worktree }
+  ensureStoreDir(join(store, 'projects'))
+  writeSafely(join(store, 'projects', WORKTREE_LINKS), JSON.stringify({ schema: 1, links: [...links.links, { worktree: a.worktree, owner: b.worktree, common: a.common, commonId: a.commonId }] }) + '\n')
+  return { applied: true, worktree: a.worktree, owner: b.worktree }
+}
+
 /** No mkdir or metadata writes on normal lookup. Never read an ambiguous old store. */
 function projectStoreDirLocal(store, root) {
-  const p = paths(store, root), claim = readClaim(p).value
+  const p = paths(store, linkedRoot(store, root)), claim = readClaim(p).value
   if (directory(p.target) && lstatExists(join(p.target, IDENTITY)) && !identityMatches(p)) fail('identity-mismatch')
   if (claim?.projectId === p.id) {
     if (claim.state !== 'complete') fail('migration-needs-recovery')
@@ -120,9 +188,10 @@ function lstatExists(path) {
 }
 
 function inspectProjectStoreLocal(store, root) {
-  const p = paths(store, root), claim = readClaim(p), source = tree(p.legacy), targetExists = directory(p.target)
+  const effectiveRoot = linkedRoot(store, root)
+  const p = paths(store, effectiveRoot), claim = readClaim(p), source = tree(p.legacy), targetExists = directory(p.target)
   if (source) assertPublicationClear(p.legacy)
-  return { applied: false, projectId: p.id, legacyDir: p.legacy, targetDir: p.target, reviewedClaim: claim.revision,
+  return { applied: false, ...(effectiveRoot !== root ? { linkedWorktree: resolve(root), linkedOwner: effectiveRoot } : {}), projectId: p.id, legacyDir: p.legacy, targetDir: p.target, reviewedClaim: claim.revision,
     reviewedTree: source?.sha256, files: source?.files.length ?? 0, bytes: source?.bytes ?? 0, targetExists,
     state: claim.value ? claim.value.projectId !== p.id ? 'legacy-owned-by-another-project' : claim.value.state === 'prepared' ? 'needs-recovery' : 'migrated' : source ? 'legacy-needs-review' : 'fresh',
     sourceChangedSinceMigration: claim.value?.projectId === p.id && source ? source.sha256 !== claim.value.sourceHash : false }
@@ -130,6 +199,7 @@ function inspectProjectStoreLocal(store, root) {
 
 /** Copies, never merges or deletes the old library. Both revisions are required. */
 function migrateProjectStoreLocal(store, root, options = {}) {
+  if (linkedRoot(store, root) !== root) fail('worktree-unlink-before-migration')
   if (options.apply !== undefined && typeof options.apply !== 'boolean') fail('invalid-apply')
   if (options.apply !== true) return inspectProjectStore(store, root)
   const p = paths(store, root)
@@ -179,6 +249,7 @@ function migrateProjectStoreLocal(store, root, options = {}) {
 }
 
 function recoverProjectStoreLocal(store, root, options = {}) {
+  if (linkedRoot(store, root) !== root) fail('worktree-unlink-before-migration')
   if (options.apply !== undefined && typeof options.apply !== 'boolean') fail('invalid-apply')
   const p = paths(store, root), claim = readClaim(p)
   if (!claim.value || claim.value.projectId !== p.id) fail('no-owned-migration')
@@ -220,3 +291,11 @@ export function projectStoreDir(store,...args){return managedProjectOperation(st
 export function inspectProjectStore(store,...args){return managedProjectOperation(store,()=>inspectProjectStoreLocal(store,...args))}
 export function migrateProjectStore(store,root,options={}){return managedProjectOperation(store,()=>options.apply===true?finishManagedMigration(store,root,()=>migrateProjectStoreLocal(store,root,options)):migrateProjectStoreLocal(store,root,options),{write:options.apply===true})}
 export function recoverProjectStore(store,root,options={}){return managedProjectOperation(store,()=>options.apply===true?finishManagedMigration(store,root,()=>recoverProjectStoreLocal(store,root,options)):recoverProjectStoreLocal(store,root,options),{write:options.apply===true})}
+
+function changeWorktreeLinks(store, run) {
+  const dir = join(store, 'projects')
+  safeAncestors(dir, store); ensureStoreDir(dir)
+  return migrationLock(dir, run)
+}
+export function linkWorktreeProject(store,worktree,owner,options={}){return managedProjectOperation(store,()=>options.apply===true?changeWorktreeLinks(store,()=>linkWorktreeLocal(store,worktree,owner,options)):linkWorktreeLocal(store,worktree,owner,options),{write:options.apply===true})}
+export function unlinkWorktreeProject(store,worktree,options={}){return managedProjectOperation(store,()=>options.apply===true?changeWorktreeLinks(store,()=>unlinkWorktreeLocal(store,worktree,options)):unlinkWorktreeLocal(store,worktree,options),{write:options.apply===true})}

package/scripts/projects.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /** Local migration review only. No model-callable adoption or automatic old-store copying. */
 import { resolve } from 'node:path'
-import { reviewProjectStore, migrateLegacyProjectStore, recoverLegacyProjectStore } from '../index.mjs'
+import { reviewProjectStore, migrateLegacyProjectStore, recoverLegacyProjectStore, linkProjectWorktree, unlinkProjectWorktree } from '../index.mjs'
 const args = process.argv.slice(2), command = args.shift() ?? 'inspect'
 function option(name) {
   const index = args.indexOf(name)
@@ -10,10 +10,11 @@ function option(name) {
   const value = args[index + 1]; args.splice(index, 2); return value
 }
 try {
-  const cwd = resolve(option('--cwd') ?? process.cwd()), reviewedTree = option('--reviewed-tree'), reviewedClaim = option('--reviewed-claim'), reviewedMigration = option('--reviewed-migration')
+  const cwd = resolve(option('--cwd') ?? process.cwd()), reviewedTree = option('--reviewed-tree'), reviewedClaim = option('--reviewed-claim'), reviewedMigration = option('--reviewed-migration'), owner = option('--owner'), reviewedLink = option('--reviewed-link')
   const i = args.indexOf('--apply'), apply = i >= 0
   if (apply) args.splice(i, 1)
-  if (args.length || !['inspect', 'migrate', 'recover'].includes(command) || command === 'inspect' && apply) throw Error('usage: projects inspect/migrate/recover --cwd path; migrate/recover preview by default; apply requires current review hashes')
-  const result = command === 'inspect' ? reviewProjectStore(cwd) : command === 'migrate' ? migrateLegacyProjectStore(cwd, { apply, reviewedTree, reviewedClaim }) : recoverLegacyProjectStore(cwd, { apply, reviewedMigration })
+  if (args.length || !['inspect', 'migrate', 'recover', 'link', 'unlink'].includes(command) || command === 'inspect' && apply) throw Error('usage: projects inspect/migrate/recover/link/unlink --cwd path; link needs --owner; apply needs matching review hash')
+  if (command === 'link' && !owner) throw Error('link requires --owner')
+  const result = command === 'inspect' ? reviewProjectStore(cwd) : command === 'migrate' ? migrateLegacyProjectStore(cwd, { apply, reviewedTree, reviewedClaim }) : command === 'link' ? linkProjectWorktree(cwd, owner, { apply, reviewed: reviewedLink }) : command === 'unlink' ? unlinkProjectWorktree(cwd, { apply, reviewed: reviewedLink }) : recoverLegacyProjectStore(cwd, { apply, reviewedMigration })
   console.log(JSON.stringify(result, null, 2))
 } catch (error) { console.error(error.message); process.exitCode = 1 }

package/scripts/security-check.mjs

@@ -83,7 +83,7 @@ check('runtime-network', () => {
 })
 
 check('runtime-exec', () => {
-  const allowed = new Set(['restore.mjs'])
+  const allowed = new Set(['restore.mjs', 'project-stores.mjs'])
   const hits = []
   for (const file of runtimeFiles) {
     if (!/child_process|\bexecSync\b|\bspawnSync\b/.test(text(file))) continue
@@ -93,7 +93,11 @@ check('runtime-exec', () => {
   const restore = text(join(ROOT, 'restore.mjs'))
   assert(/spawnSync\('tar',\s*\[/.test(restore), 'restore.mjs 的子进程不是固定的 tar 参数调用')
   assert(!/shell:\s*true/.test(restore), 'restore.mjs 启用了 shell')
-  return 'restore.mjs 仅以固定参数调用 tar（无 shell）'
+  const projects = text(join(ROOT, 'project-stores.mjs'))
+  assert(/execFileSync\('git',\s*\['-C',\s*root,\s*'rev-parse',\s*'--path-format=absolute',\s*'--show-toplevel',\s*'--git-common-dir'\]/.test(projects), 'project-stores.mjs 的子进程不是固定的 git rev-parse 参数调用')
+  assert(!/shell:\s*true/.test(projects) && !/\b(?:spawn|exec|execSync|spawnSync)\s*\(/.test(projects), 'project-stores.mjs 出现非允许的子进程调用')
+  assert(/GIT_CONFIG_GLOBAL:\s*'\/dev\/null'/.test(projects) && /GIT_CONFIG_NOSYSTEM:\s*'1'/.test(projects) && /GIT_TERMINAL_PROMPT:\s*'0'/.test(projects), 'worktree 身份检查未隔离 Git 全局配置或交互')
+  return 'restore 固定调用 tar；project-stores 固定调用 git rev-parse；均无 shell'
 })
 
 check('secrets-shipped', () => {

package/scripts/soak.mjs

@@ -19,7 +19,7 @@ import { createHash } from 'node:crypto'
 import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 import { VERSION } from '../version.mjs'
 
@@ -30,6 +30,7 @@ const TOOLS = ['memory_write', 'memory_forget', 'memory_links', 'memory_search',
 const DATA_FILES = /^(MEMORY\.md|(user|feedback|project|reference)\.md|\.candidates\.json|\.episodes\.json|\.history\.jsonl)$/
 const hash = (file) => createHash('sha256').update(readFileSync(file)).digest('hex')
 const sleep = (ms) => new Promise((done) => setTimeout(done, ms))
+const activeHosts = new Set()
 
 function dataFingerprint(memoryRoot) {
   const out = []
@@ -73,6 +74,8 @@ async function startHost(home, profile) {
     env: { PATH: process.env.PATH, HOME: home, USERPROFILE: home, DSH_HOME: home, TMPDIR: join(home, 'tmp') },
     stdio: ['ignore', 'pipe', 'pipe'],
   })
+  activeHosts.add(child)
+  child.once('exit', () => activeHosts.delete(child))
   let output = ''
   child.stdout.on('data', (chunk) => (output += chunk))
   child.stderr.on('data', (chunk) => (output += chunk))
@@ -189,13 +192,14 @@ export async function soak({ cycles = 3 } = {}) {
     report.passed = false
     report.error = error.message
   } finally {
+    await Promise.all([...activeHosts].filter(child => child.exitCode === null && child.signalCode === null).map(stopHost))
     rmSync(base, { recursive: true, force: true })
   }
   report.finishedAt = new Date().toISOString()
   return report
 }
 
-if (process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`) {
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(realpathSync(resolve(process.argv[1]))).href) {
   const argv = process.argv.slice(2)
   const cyclesAt = argv.indexOf('--cycles')
   const cycles = cyclesAt >= 0 ? Number(argv[cyclesAt + 1]) : 3

package/scripts/superagent-worktree.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/** Explicitly configured Super Agent prepare helper; never creates worktrees or calls a model. */
+import { isAbsolute } from 'node:path'
+import { linkProjectWorktree } from '../index.mjs'
+
+try {
+  const args = process.argv.slice(2)
+  if (args.length !== 3 || args[0] !== '--owner' || !isAbsolute(args[1]) || args[2] !== '--apply') throw Error('usage: superagent-worktree --owner /absolute/project --apply')
+  const worktree = process.env.DSH_SUPERAGENT_DIR
+  if (typeof worktree !== 'string' || !isAbsolute(worktree)) throw Error('DSH_SUPERAGENT_DIR must be an absolute worktree path')
+  // Installing this command in the trusted prepare configuration is the user's
+  // opt-in; the project store still validates Git identity and stale reviews.
+  const preview = linkProjectWorktree(worktree, args[1])
+  const result = linkProjectWorktree(worktree, args[1], { apply: true, reviewed: preview.reviewed })
+  if (!result.applied && !result.alreadyLinked) throw Error('worktree association was not applied')
+  console.log(JSON.stringify(result))
+} catch (error) {
+  console.error(error.message)
+  process.exitCode = 1
+}

package/test/test-memory-conflict-protocol.mjs

@@ -0,0 +1,20 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {memoryProtocol} from '../memory-protocol.mjs'
+
+test('conflict guidance accompanies the actual protocol with no write tool', () => {
+  const result = memoryProtocol({tools:{schemas:()=>[]}}, {agent:{}})
+  assert.match(result, /任务历史是当时的记录/)
+  assert.match(result, /核对来源、适用范围和时间/)
+  assert.match(result, /证据不足时说明不确定并询问用户/)
+  assert.match(result, /不能声称已经保存/)
+  assert.match(result, /未提供 memory_search/)
+  assert.match(result, /不得声称已查过/)
+})
+test('reports available search and unknown availability separately', () => {
+  assert.match(memoryProtocol({tools:{schemas:()=>[{name:'memory_search'}]}}, {agent:{}}), /已提供 memory_search/)
+  assert.match(memoryProtocol({}, {agent:{}}), /memory_search 可用性未能核对/)
+})
+test('no agent receives no protocol', () => {
+  assert.equal(memoryProtocol({}, {}), '')
+})

package/test/test-project-stores.mjs

@@ -2,12 +2,12 @@ import {prepareMountedFixture} from '../fixture-host.mjs'
 import {realpathSync} from 'node:fs'
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync, symlinkSync, linkSync, existsSync, utimesSync } from 'node:fs'
-import { spawnSync } from 'node:child_process'
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync, symlinkSync, linkSync, existsSync, utimesSync, renameSync } from 'node:fs'
+import { spawn, spawnSync, execFileSync } from 'node:child_process'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { fileURLToPath } from 'node:url'
-import { projectStoreDir, projectIdentity, legacyProjectSlug, inspectProjectStore, migrateProjectStore, recoverProjectStore } from '../project-stores.mjs'
+import { projectStoreDir, projectIdentity, legacyProjectSlug, inspectProjectStore, migrateProjectStore, recoverProjectStore, linkWorktreeProject, unlinkWorktreeProject } from '../project-stores.mjs'
 import { storeDirFor, writeMemory, indexLine, searchStore, apply } from '../index.mjs'
 
 function box(run) {
@@ -226,3 +226,121 @@ test('an old but live migration lock is not stolen by another apply attempt', ()
   assert.throws(() => migrateProjectStore(box.store, box.a, options), /migration-busy/)
   assert.equal(readFileSync(lock, 'utf8'), raw)
 }))
+
+
+test('explicit same-repository worktree link shares an existing owner store without merging other stores', () => box(({ root, store }) => {
+  const repo = join(root, 'repo'), worker = join(root, 'worker'), conflicting = join(root, 'conflicting'), foreign = join(root, 'foreign')
+  const env = { PATH: process.env.PATH, HOME: root, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' }
+  const git = (...args) => execFileSync('git', args, { env, stdio: 'pipe' })
+  mkdirSync(repo); git('init', '-q', repo)
+  git('-C', repo, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', 'commit', '--allow-empty', '-qm', 'fixture')
+  git('-C', repo, 'worktree', 'add', '-qb', 'worker', worker)
+  git('-C', repo, 'worktree', 'add', '-qb', 'conflicting', conflicting)
+  mkdirSync(foreign); git('init', '-q', foreign)
+  const original = storeDirFor('project', repo), separate = storeDirFor('project', worker)
+  assert.notEqual(original, separate)
+  writeMemory({ type: 'project', dir: original, line: indexLine('project', 'Synthetic shared project violet775', undefined, false) })
+  writeMemory({ type: 'project', dir: storeDirFor('project', conflicting), line: indexLine('project', 'Synthetic preexisting project', undefined, false) })
+  assert.throws(() => linkWorktreeProject(store, foreign, repo), /worktree-not-same-repository/)
+  assert.throws(() => linkWorktreeProject(store, conflicting, repo), /worktree-link-conflict/)
+  const preview = linkWorktreeProject(store, worker, repo)
+  assert.equal(preview.applied, false); assert.notEqual(storeDirFor('project', worker), original)
+  assert.throws(() => linkWorktreeProject(store, worker, repo, { apply: true, reviewed: 'stale' }), /stale-worktree-link-review/)
+  assert.equal(linkWorktreeProject(store, worker, repo, { apply: true, reviewed: preview.reviewed }).applied, true)
+  assert.equal(storeDirFor('project', worker), original)
+  const inspected = inspectProjectStore(store, worker)
+  assert.equal(inspected.targetDir, original, 'inspection must report the store actually used by the worker')
+  assert.equal(inspected.linkedOwner, realpathSync(repo))
+  assert.throws(() => migrateProjectStore(store, worker), /worktree-unlink-before-migration/)
+  assert.throws(() => recoverProjectStore(store, worker), /worktree-unlink-before-migration/)
+  assert.equal(searchStore(storeDirFor('project', worker), 'violet775').hits.length, 1)
+  mkdirSync(separate, { recursive: true })
+  assert.throws(() => storeDirFor('project', worker), /worktree-link-conflict/, 'a later independently created store cannot be silently hidden')
+  const unlink = unlinkWorktreeProject(store, worker)
+  assert.throws(() => unlinkWorktreeProject(store, worker, { apply: true, reviewed: 'stale' }), /stale-worktree-link-review/)
+  assert.equal(unlinkWorktreeProject(store, worker, { apply: true, reviewed: unlink.reviewed }).memoryDeleted, false)
+  assert.equal(storeDirFor('project', worker), separate)
+  // A previously resolved directory is an ordinary local path, not an access token.
+  assert.equal(searchStore(original, 'violet775').hits.length, 1, 'unlink does not revoke an already resolved owner path')
+  const cliworker = join(root, 'cliworker'); git('-C', repo, 'worktree', 'add', '-qb', 'cliworker', cliworker)
+  const cli = fileURLToPath(new URL('../scripts/projects.mjs', import.meta.url)), cliEnv = { ...env, DSH_HOME: root }
+  const runCli = (...args) => spawnSync(process.execPath, [cli, ...args], { env: cliEnv, encoding: 'utf8' })
+  const cliPreview = runCli('link', '--cwd', cliworker, '--owner', repo)
+  assert.equal(cliPreview.status, 0, cliPreview.stderr)
+  const cliApplied = runCli('link', '--cwd', cliworker, '--owner', repo, '--apply', '--reviewed-link', JSON.parse(cliPreview.stdout).reviewed)
+  assert.equal(cliApplied.status, 0, cliApplied.stderr)
+  assert.equal(storeDirFor('project', cliworker), original)
+  const cliInspect = runCli('inspect', '--cwd', cliworker)
+  assert.equal(cliInspect.status, 0, cliInspect.stderr)
+  assert.equal(JSON.parse(cliInspect.stdout).targetDir, original)
+  assert.equal(JSON.parse(cliInspect.stdout).linkedOwner, realpathSync(repo))
+  const cliMigrate = runCli('migrate', '--cwd', cliworker)
+  assert.notEqual(cliMigrate.status, 0); assert.match(cliMigrate.stderr, /worktree-unlink-before-migration/)
+  const moved = join(root, 'moved-worker'); git('-C', repo, 'worktree', 'move', cliworker, moved)
+  assert.throws(() => storeDirFor('project', cliworker), /worktree-unavailable/, 'a moved worktree does not retain a stale mapping')
+  assert.notEqual(storeDirFor('project', moved), original, 'moving requires an explicit new registration')
+  const cliUnlink = runCli('unlink', '--cwd', cliworker)
+  assert.equal(cliUnlink.status, 0, cliUnlink.stderr)
+  const cliRemoved = runCli('unlink', '--cwd', cliworker, '--apply', '--reviewed-link', JSON.parse(cliUnlink.stdout).reviewed)
+  assert.equal(cliRemoved.status, 0, cliRemoved.stderr)
+  assert.notEqual(storeDirFor('project', cliworker), original)
+  const autoworker = join(root, 'autoworker'); git('-C', repo, 'worktree', 'add', '-qb', 'autoworker', autoworker)
+  const helper = fileURLToPath(new URL('../scripts/superagent-worktree.mjs', import.meta.url))
+  const runHelper = (worktree, ...args) => spawnSync(process.execPath, [helper, ...args], { env: { ...cliEnv, ...(worktree === undefined ? {} : { DSH_SUPERAGENT_DIR: worktree }) }, encoding: 'utf8' })
+  assert.notEqual(runHelper(undefined, '--owner', repo, '--apply').status, 0)
+  assert.notEqual(runHelper(autoworker, '--owner', repo).status, 0)
+  assert.notEqual(runHelper(foreign, '--owner', repo, '--apply').status, 0)
+  const helperResult = runHelper(autoworker, '--owner', repo, '--apply')
+  assert.equal(helperResult.status, 0, helperResult.stderr)
+  assert.equal(storeDirFor('project', autoworker), original)
+  assert.equal(runHelper(autoworker, '--owner', repo, '--apply').status, 0, 'preparing the same registered worktree is idempotent')
+}))
+
+
+test('a different repository recreated at the same paths cannot inherit a worktree link', () => box(({ root, store }) => {
+  const repo = join(root, 'repo-replaced'), worker = join(root, 'worker-replaced')
+  const env = { PATH: process.env.PATH, HOME: root, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' }
+  const git = (...args) => execFileSync('git', args, { env, stdio: 'pipe' })
+  mkdirSync(repo); git('init', '-q', repo)
+  git('-C', repo, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', 'commit', '--allow-empty', '-qm', 'original')
+  git('-C', repo, 'worktree', 'add', '-qb', 'old-worker', worker)
+  const original = storeDirFor('project', repo)
+  writeMemory({ type: 'project', dir: original, line: indexLine('project', 'Synthetic old decision plum749', undefined, false) })
+  const plan = linkWorktreeProject(store, worker, repo)
+  linkWorktreeProject(store, worker, repo, { apply: true, reviewed: plan.reviewed })
+  assert.equal(storeDirFor('project', worker), original)
+  git('-C', repo, 'worktree', 'remove', '--force', worker)
+  renameSync(join(repo, '.git'), join(root, 'old-git-preserved'))
+  git('init', '-q', repo)
+  git('-C', repo, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', 'commit', '--allow-empty', '-qm', 'different')
+  git('-C', repo, 'worktree', 'add', '-qb', 'new-worker', worker)
+  assert.throws(() => storeDirFor('project', worker), /worktree-link-changed/)
+}))
+
+
+test('independent processes cannot both apply conflicting previews to an unmanaged store', async () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-project-link-race-'))), store = join(root, 'memory'), repo = join(root, 'repo'), a = join(root, 'a'), b = join(root, 'b')
+  const env = { PATH: process.env.PATH, HOME: root, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' }
+  const git = (...args) => execFileSync('git', args, { env, stdio: 'pipe' })
+  const children = []
+  try {
+    mkdirSync(repo); git('init', '-q', repo)
+    git('-C', repo, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', 'commit', '--allow-empty', '-qm', 'fixture')
+    git('-C', repo, 'worktree', 'add', '-qb', 'a', a); git('-C', repo, 'worktree', 'add', '-qb', 'b', b)
+    writeMemory({ type: 'project', dir: projectStoreDir(store, repo), line: indexLine('project', 'Synthetic concurrent project', undefined, false) })
+    const reviews = [linkWorktreeProject(store, a, repo).reviewed, linkWorktreeProject(store, b, repo).reviewed]
+    const moduleUrl = new URL('../project-stores.mjs', import.meta.url).href
+    const source = `import {linkWorktreeProject} from ${JSON.stringify(moduleUrl)}; const [store,worker,owner,review]=process.argv.slice(1); process.send({ready:true}); process.on('message',()=>{try { const result=linkWorktreeProject(store,worker,owner,{apply:true,reviewed:review});process.send({status:result.applied?'applied':'other'}); } catch(error) {process.send({status:'denied',message:String(error.message)});} process.disconnect()})`
+    const results = [a, b].map((worker, index) => {
+      const child = spawn(process.execPath, ['--input-type=module', '-e', source, store, worker, repo, reviews[index]], { env, stdio: ['ignore', 'pipe', 'pipe', 'ipc'] }); children.push(child)
+      let result, errors = ''; child.stderr.on('data', data => { errors += data })
+      return { child, ready: new Promise((resolve, reject) => { child.on('message', message => { if (message.ready) resolve(); else result = message }); child.on('error', reject); child.on('exit', code => { if (code && !result) reject(Error(errors)) }) }), done: new Promise((resolve, reject) => { child.on('exit', code => code === 0 && result ? resolve(result) : reject(Error(errors || `child exited ${code}`))); child.on('error', reject) }) }
+    })
+    await Promise.all(results.map(item => item.ready)); results.forEach(item => item.child.send('go'))
+    const settled = await Promise.all(results.map(item => item.done))
+    assert.equal(settled.filter(item => item.status === 'applied').length, 1, JSON.stringify(settled))
+    assert.equal(settled.filter(item => item.status === 'denied' && /migration-busy|stale-worktree-link-review|memory-lock-busy|另一个写入占用/.test(item.message)).length, 1, JSON.stringify(settled))
+    const owner = projectStoreDir(store, repo)
+    assert.equal([a, b].filter(path => projectStoreDir(store, path) === owner).length, 1)
+  } finally { children.forEach(child => { if (child.exitCode === null) child.kill('SIGKILL') }); rmSync(root, { recursive: true, force: true }) }
+})

package/version.mjs

@@ -2,4 +2,4 @@
  * 版本单点。package.json 里的 version 必须与它一致，由 test-packaging.mjs 断言。
  * 打包工具不能读 ESM 常量时会回退读 package.json，所以两处都要在。
  */
-export const VERSION = '0.22.0-beta.3'
+export const VERSION = '0.23.0-beta.2'