fix: harden release-facing contract closure

AGENTS.md

@@ -0,0 +1,115 @@
+# Codex Auto Memory Agent Notes
+
+## 功能描述
+
+`codex-auto-memory` 是一个面向 Codex 的 `Markdown-first` 本地记忆运行层。
+
+当前产品边界：
+
+- durable memory 与 session continuity 分层维护
+- `cam memory` 提供 inspect / audit surface
+- `cam session` 提供 temporary continuity surface
+- canonical source of truth 仍然是 Markdown，而不是数据库
+- 当前最稳入口仍然是 wrapper + CLI，同时继续向 hooks、skills、MCP-aware retrieval 演进
+
+## 使用方法
+
+常用开发命令：
+
+```bash
+pnpm install
+pnpm lint
+pnpm test
+pnpm build
+pnpm test:docs-contract
+pnpm test:dist-cli-smoke
+pnpm test:tarball-install-smoke
+```
+
+常用产品命令：
+
+```bash
+cam run
+cam sync
+cam memory
+cam memory reindex
+cam recall search "<query>"
+cam mcp serve
+cam mcp install --host codex
+cam mcp print-config --host codex
+cam mcp apply-guidance --host codex
+cam mcp doctor --host codex
+cam integrations install --host codex
+cam integrations apply --host codex
+cam integrations doctor --host codex
+cam session save
+cam session refresh
+cam session load
+cam session status
+```
+
+## 参数说明
+
+关键配置文件：
+
+- `codex-auto-memory.json`
+- `.codex-auto-memory.local.json`
+
+关键配置字段：
+
+- `autoMemoryEnabled`: 是否开启 durable memory sync
+- `extractorMode`: `codex` 或 `heuristic`
+- `defaultScope`: 默认 memory scope
+- `maxStartupLines`: startup durable memory 行预算
+- `sessionContinuityAutoLoad`: wrapper 是否自动注入 continuity
+- `sessionContinuityAutoSave`: wrapper 是否自动保存 continuity
+- `maxSessionContinuityLines`: continuity startup 行预算
+- `codexBinary`: 调用的 Codex 可执行文件
+
+集成相关公开参数：
+
+- `cam skills install --surface runtime|official-user|official-project`
+- `cam integrations install/apply --skill-surface runtime|official-user|official-project`
+- `cam ... --cwd <path>` 用于跨目录锚定目标项目
+
+## 返回值说明
+
+关键 JSON reviewer / integration contract：
+
+- `cam memory --json`: 返回 startup files、topic refs、recent sync audit、`topicDiagnostics`、`layoutDiagnostics` 等 inspect 信息
+- `cam memory reindex --json`: 返回 rebuilt sidecar 摘要与对应 `indexPath` / `generatedAt`
+- `cam recall search --json`: 返回 compact refs、`retrievalMode`、`stateResolution`、`executionSummary`、`diagnostics.checkedPaths`
+- `cam recall timeline --json`: 返回 lifecycle history、`warnings`、`lineageSummary`
+- `cam recall details --json`: 返回 detail、`latestState`、`latestAudit`、`warnings`
+- `cam mcp print-config --json`: 对 Codex 暴露 project-scoped MCP snippet、`workflowContract`、推荐 `AGENTS.md` guidance
+- `cam mcp doctor --json`: 暴露 retrieval MCP wiring、fallback assets、`codexStack`、`retrievalSidecar`
+- `cam integrations install/apply --json`: 暴露 staged subactions、rollback payload、`postInstallReadinessCommand` / `postApplyReadinessCommand`
+- `cam integrations doctor --json`: 暴露 `recommendedRoute`、`currentlyOperationalRoute`、`workflowContract`、`applyReadiness`
+
+## 项目规划
+
+当前优先事项：
+
+1. 继续保持 issue5 stack 的 reviewer contract、help surface、release-facing smoke 一致
+2. 收紧 issue-tracker durable memory replacement key，避免不同 host 的 tracker URL 因相同 repo/path 或 ticket id 被误判为同一条 memory
+3. 把 Claude Code / Gemini CLI 的官方公开宿主能力面，与本仓当前真实支持的 manual-only host 边界继续写清楚
+4. 保持 `Markdown-first` canonical store 与 sidecar retrieval plane 的边界稳定
+5. 保持 `cam integrations install` 与 `cam integrations apply` 的 AGENTS mutation boundary 清晰
+6. 继续扩大 deterministic release gate：`lint`、`test`、`docs-contract`、`dist-cli-smoke`、`tarball-install-smoke`
+
+下一阶段建议：
+
+1. 继续做小步 stack closure，而不是重新摊大 remediation
+2. 优先把 help / docs / smoke contract 固定成同一套公开语义
+3. 在不扩张宿主边界的前提下，继续维持 Codex-first、manual-only 非 Codex host 的产品表述
+4. 将 issue5 剩余 closeout seams 继续拆成小 PR：`cam init` 幂等/`--force`、`cam session status/load` 只读化、Vitest `.worktrees/**` 边界、docs/help parity
+5. 保持发布面验证串行执行：`dist-cli-smoke` 与 `tarball-install-smoke` 不并行跑，避免 `prepack -> rimraf dist` 造成假阴性
+
+## 变更记录
+
+- 2026-04-11: issue5 tail closeout 新增 cross-host issue-tracker 回归保护：`directive-utils` 现在用完整的 non-generic hostname 片段构造 issue-tracker resource key，避免不同 host 但相同 repo/path 或 ticket id 的 URL 互相覆盖；同时补强 `vitest.config.ts` 的默认 exclude contract 测试，并把 `integrations apply --cwd` 的 invalid-path fail-closed 行为纳入 source / dist / tarball 回归覆盖。
+- 2026-04-10: issue5 PR14 收口了三类 runtime contract seam：`mcp` 命令的空 `--cwd` 现在 fail-closed；`workflowContract` 的 resolved launcher 与显式 `launcherOverride` 保持一致；delete-only 的 forget follow-up 文案不再硬编码裸 `cam recall timeline`。
+- 2026-04-10: `test/recovery-records.test.ts` 已对齐当前 continuity 语义：`scope=both` continuity recovery marker 可以被后续 single-scope save/refresh 复用，并继续由 `session-command` 行为测试锁定。
+- 2026-04-10: 新增根级 `AGENTS.md`，补齐仓库级功能说明、命令面、关键 JSON 契约与项目规划。
+- 2026-04-10: 明确 `cam integrations install --help` 与四语 README 命令表的公开边界：install 编排 stack，但不更新 `AGENTS.md`。
+- 2026-04-10: 新增 Claude Code / Gemini CLI 宿主接入边界文档，并同步收紧宿主策略文档与 README 入口，明确非 Codex 宿主当前仍是 manual-only / snippet-first。

README.en.md

@@ -206,7 +206,7 @@ cam audit
 | `cam remember` / `cam forget` | explicitly add or remove durable memory; both commands now also support `--cwd <path>` so manual corrections can target another project root directly; when `cam remember` omits `--topic`, it now performs lightweight durable-topic inference and prefers updating an existing memory instead of appending a second active entry when there is one clearly identifiable old value; `cam forget --archive` moves matching entries into the archive layer; `forget` now also shares the same multi-term query normalization as `recall search`, so queries like `pnpm npm` can match one memory across `summary/details` instead of requiring the original substring to appear contiguously; both commands now also support `--json`, returning a structured manual-mutation reviewer payload with `mutationKind`, `matchedCount`, `appliedCount`, `noopCount`, `summary`, `primaryEntry`, `entries[]`, `followUp`, `nextRecommendedActions`, and top-level lifecycle/detail fields (`latestAppliedLifecycle`, `latestLifecycleAttempt`, `latestLifecycleAction`, `latestState`, `latestSessionId`, `latestRolloutPath`, `latestAudit`, `timelineWarningCount`, `warnings`, `entry`, `lineageSummary`, `ref/path/historyPath`) whenever at least one matched ref exists; they now also add `leadEntryRef`, `leadEntryIndex`, `detailsAvailable`, `reviewRefState`, `uniqueAuditCount`, `auditCountsDeduplicated`, and `warningsByEntryRef` so delete/archive/multi-entry reviewer payloads are less ambiguous without breaking older consumers; empty `forget --json` results stay additive and now leave `nextRecommendedActions` empty instead of emitting placeholder refs; delete flows also distinguish timeline-only review refs from details-usable refs; text mode now also prints the same project-pinned `timeline/details -> recent -> reindex` follow-up route so manual corrections drop back into the reviewer loop naturally |
 | `cam recall search` / `timeline` / `details` | progressively retrieve durable memory through a search -> timeline -> details workflow; `search` now defaults to `state=auto, limit=8`, so active memory is checked before archived fallback while staying read-only, and multi-term queries now match across `id/topic/summary/details` instead of requiring every term to live in one field; the JSON surface now also exposes additive `retrievalMode`, `finalRetrievalMode`, `retrievalFallbackReason`, `stateResolution`, `executionSummary`, `searchOrder`, `totalMatchedCount`, `returnedCount`, `globalLimitApplied`, `truncatedCount`, `resultWindow`, `globalRank`, and `diagnostics.checkedPaths[].returnedCount` / `droppedCount` fields so fallback behavior, global sorting, and post-limit drops stay reviewer-visible; `finalRetrievalMode` is an explicit alias for the final result mode while `retrievalMode` keeps its compatibility semantics |
 | `cam mcp serve` | start a read-only retrieval MCP server that exposes the same workflow through `search_memories`, `timeline_memories`, and `get_memory_details` |
-| `cam integrations install --host codex` | install the recommended Codex integration stack in one explicit step by writing project-scoped MCP wiring and refreshing the hook bridge bundle plus Codex skill assets; it defaults to the runtime skill target, but also accepts `--skill-surface runtime|official-user|official-project`; stays idempotent, Codex-only, does not touch the Markdown memory store, and now rolls back staged MCP / hook / skill writes if installation fails mid-flight; `--json` now also returns a structured rollback failure payload; after installation it explicitly points you back to `cam integrations doctor --host codex` to confirm which retrieval route is operational in the current environment |
+| `cam integrations install --host codex` | install the recommended Codex integration stack in one explicit step by writing project-scoped MCP wiring and refreshing the hook bridge bundle plus Codex skill assets; it defaults to the runtime skill target, but also accepts `--skill-surface runtime|official-user|official-project`; stays idempotent, Codex-only, does not touch `AGENTS.md` or the Markdown memory store, and now rolls back staged MCP / hook / skill writes if installation fails mid-flight; `--json` now also returns a structured rollback failure payload; after installation it explicitly points you back to `cam integrations doctor --host codex` to confirm which retrieval route is operational in the current environment |
 | `cam integrations apply --host codex` | explicitly apply the full Codex integration state: it keeps `integrations install` unchanged, but also orchestrates `cam mcp apply-guidance --host codex`; it defaults to the runtime skill target, but also accepts `--skill-surface runtime|official-user|official-project`; if the `AGENTS.md` managed block is unsafe, the command returns a preflight `blocked` result before any stack writes happen, and if a later block or staged write fails the JSON payload now reports rollback outcome plus the final effective action; after apply you should still use doctor to confirm whether MCP, the local bridge bundle, or the resolved CLI route is the operational path |
 | `cam integrations doctor --host codex` | inspect the current Codex integration stack through a thin read-only aggregation surface that reports the recommended route and current route truth (`recommendedRoute`, `currentlyOperationalRoute`, `routeKind`, `routeEvidence`, `shellDependencyLevel`, `hostMutationRequired`, `preferredRouteBlockers`, `currentOperationalBlockers`), recommended preset, structured `workflowContract`, `applyReadiness`, additive `experimentalHooks` guidance, `layoutDiagnostics`, subchecks, and minimum next steps; `recommendedRoute` stays MCP-first, while the blocker fields separately explain why the preferred route is unavailable and whether the current fallback still has its own operational issues; it also surfaces skill-surface steering (`preferredSkillSurface`, `recommendedSkillInstallCommand`, `installedSkillSurfaces`, `readySkillSurfaces`) without describing skills as an executable fallback route; when doctor is anchored to another repository with `--cwd`, hook-fallback next steps now also project-pin the local bridge route via `CAM_PROJECT_ROOT=...`; when `cam` is unavailable on PATH, the direct CLI next step now prefers the resolved `node dist/cli.js recall ...` fallback instead of a broken bare `cam recall ...`; when the managed `AGENTS.md` block is unsafe, it now tells you to repair that block first instead of recommending `cam integrations apply --host codex` immediately |
 | `cam mcp install --host codex` | explicitly write the recommended Codex project-scoped host config for `codex_auto_memory`; only that server entry is updated, hooks/skills stay opt-in, and non-canonical custom fields on that entry are preserved when safe; lower-priority non-Codex host wiring stays in `docs/host-surfaces.md` instead of the default product path, and some of those routes remain `manual-only` |
@@ -323,6 +323,7 @@ See the architecture docs for the full boundary breakdown.
 ### Core design docs
 
 - [Claude reference contract (中文)](docs/claude-reference.md) | [English](docs/claude-reference.en.md)
+- [Claude Code / Gemini CLI host integration boundaries (中文)](docs/host-integration-claude-gemini.md)
 - [Architecture (中文)](docs/architecture.md) | [English](docs/architecture.en.md)
 - [Integration strategy (中文)](docs/integration-strategy.md)
 - [Host surfaces (中文)](docs/host-surfaces.md)