cowork-flow 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 1.6.0 - 2026-09-20
+
+### 门禁诚实化（收集一致 / 平台 skip / CI 同门禁）
+
+- **收集一致**：`tests/test_agents_managed_block.py` 的两条断言原为模块级函数，`python -m unittest`（发布门禁与 `test:template` 用的收集器）收集不到它们（实测 `Ran 0 tests`），只有 pytest 能看到。现移入 `unittest.TestCase`，并进入 `CORE_TEMPLATE_TEST_MODULES`（core 套件 176 → 178）。新增 `tests/test_test_collection.py` 守卫：`tests/` 下再出现对 unittest 不可见的模块级 `def test_*` 即失败。
+- **Windows 静默通过**：`test/dsh-home-patch.test.js` 此前在 win32 顶层 `process.exit(0)`，`node --test` 把整个文件记为**通过文件**（不进 skipped、不进 fail）。现改为 7 个用例带 `{ skip: <具体原因> }`，Windows 上如实计入 skipped。
+- **恒真断言**：`tests/test_host_adapters.py` 三处「断言自己刚写死的字面量长度」（`assertEqual(2, len(surfaces))` 等）改为非空断言——不再恒真，也不引入需要同步维护的数字。
+- **CI 与发布同门禁**：ubuntu job 不再分步跑 fast / integration / core，合并为一步 `npm run release:check`（与 publish.yml 完全相同的命令，`setup-python` 前置到它之前）；`test/package.test.js` 新增断言锁定该一致性。此前 `test:node:full` 与 `test:template:full` 两层只在发布时首次执行，PR 侧从不运行。
+
+### 宿主必需集合单源化
+
+- 删除 Python `host_manifest.REQUIRED_CAPABILITY_MATRIX_HOSTS` 与 JS 镜像常量：`capabilityMatrix.hosts` 的必需宿主集合改由 manifest 的 `platforms` 派生（`set(platform_ids)` / `new Set([...platformIds])`）。
+- 删除 `host-assets.schema.json` 中第三处宿主名枚举——它处于漂移状态（要求 5 家、含 `dsh`、缺 `kimi-code`，而数据是 6 家）。schema 只约束结构，宿主覆盖由运行时按数据校验。
+- 新增共享 fixture `tests/fixtures/host-manifest/invalid-missing-matrix-host.json`（平台已声明但矩阵缺条目），Python 与 JS 两侧都拒绝（`capability matrix missing host: codex`），证明常量删除后该规则仍生效。
+- `spec/runtime/index.md` 记录派生规则。
+
+### 死代码与文档漂移清理
+
+- 删除仅测试可达的 skill-path 链：`context_discovery` 的 `detect_installed_platforms`（手写 3 宿主）、`SKILL_REPLICA_DIR_BY_PLATFORM`、`skill_root`、`skill_path`，以及 `adapters/cli/task.py` 的三个未调用别名。该链在生产代码零调用，真实契约由 `infra/skill_manifest` 与 manifest 的 `skillTarget` 承担。
+- 删除 `infra/paths.py` 中 `return` 之后的孤儿 try 块（引用未定义的 `file_path`，为 2026-08-05 移除 journal 流程时遗留）。
+- 删除 `fact_view.STAGE_CONTRACT_STATES`（文件内零引用；活定义在 `workflow_state_hook`）、`lifecycle_checks` 两个零调用的 `*_blockers` 包装、`adapters/review/test_intent` 的恒空校验器 `validate_test_intent` 与三个未被读取的常量，以及断言其返回空的同义用例。
+- 文档对齐：README 保护文件描述与 `syncPolicy` 实际一致（两个 spec 例外文件 + `.developer`）；两处 spec-check 文案 3s → 2.5s；`spec/schemas/index.md` 补列 `host-assets.schema.json`；清理指向已 untrack `docs/` 的历史死链。
+
+### DSH 注入接线覆盖
+
+- `presets/dsh/plugins/workflow-state.js` 的 `apply(ctx)` 此前零测试。新增用例覆盖：四个刷新事件的接线、section 注册（name/order）、无缓存时返回空文本、非编辑调用下 `tools/post-execute` 原样透传 downstream、非 cowork-flow 根目录静默降级——全部在 Windows 上真实执行。「刷新替换而非累积」用例按既有惯例在 Windows skip（宿主解释器限制）。
+
+### Windows 检出与行尾契约
+
+- 根因：`presets/kimi-code/hooks/cowork-flow-inject.mjs` 落在 `* text=auto` 下且未被 `.gitattributes` 钉行尾，Windows 全新检出（Git for Windows 默认 `core.autocrlf=true`，与 `windows-latest` 一致）把它写成 CRLF；`install-kimi-hook` 原样拷贝为全局 hook shim，于是 `test/kimi-hook.test.js` 的 `/^#!\/usr\/bin\/env node\n/` 断言失败，`test:fast` → `windows-core` 确定性红。
+- 修复：`.gitattributes` 为 `*.js`/`*.mjs` 声明 `text eol=lf`（与已钉的 `.py`/`.md`/`.json` 等一致）；`test/package.test.js` 新增行尾契约断言锁定该声明。
+- 为什么只在 Windows CI 可见：开发者工作区与 ubuntu 检出都是 LF，只有 Windows 全新检出是 CRLF。断言保持严格——CRLF shebang 的脚本在 POSIX 上无法直接执行，要修的是检出契约而不是判据。
+- 证据：全新检出实测踩中同一断言失败（`test:fast`）；仅把该文件规范化为 LF → 整条 `npm run test:windows:core` exit 0；Node 20.12.0 / 20.20.2 / 24.14.1 结果一致，与 Node 版本无关。
+
+### 净变化
+
+- 运行时代码（`template/.cowork-flow/scripts` + `src`）：**+4 / −114，净 −110 行**；runtime 模块数 80 不变（行尾修复不涉及运行时代码）。
+- 本次门禁工作：`e262196` **+365 / −200**（含 2 个新文件 +162 行）、`7fa3f8b` +3 / −2，行尾修复为小改动（行尾声明 + 契约守卫 + 记账）；新增集中在 `tests/` 与 `test/`。**AC-006「净行数 ≤ 0」未达成**——三条口径都是新增大于删除。
+- 版本口径参考：自 1.5.0 发版提交 `a4b0bfc` 起，1.6.0 全部提交的净变化由本版本更早的宿主特性主导，不属本次门禁工作。
+- 契约指纹：registry 登记的契约文件与 `spec/runtime/host-assets.json` 均未改动，指纹不变。
+
+### 平台差异与远端确认
+
+- Windows 上 `test:node:full` 的 skipped 明细新增 `dsh-home-patch` 的 7 条；这些用例在 ubuntu 发布门禁中真实执行。
+- POSIX-only：`a session refresh replaces the cached block instead of accumulating` 与既有 DSH 内容用例在本机（Windows）skip，未在本机执行。
+- 远端确认（提交 `e262196`，CI run 35503939861）：ubuntu job 首次执行 `release:check` **通过**——17 条此前只在发布时运行的 `release.test.js` POSIX 用例在 CI 上真实执行并全部通过。
+- 同一 run 的 `windows-core` 失败（步骤 `Run Windows core verification`，exit 1）。该 job 在改动前的 `aa0e34e` 上即为同样的失败，不是本版本的功能改动引入；根因是行尾契约缺失，已在本版本修复（见「Windows 检出与行尾契约」），远端日志无需仓库权限即可复现——全新 `git clone` 即可稳定踩中。
+
 ## 1.5.0 - 2026-09-18
 
 ### 发版开关 `--no-publish`
@@ -139,7 +187,7 @@
 
 > **版本内容错位说明**：npm registry 上的 1.0.0 tarball 发布于 2026-08-26（仅含发版脚本修复之前的代码）。1.0.0 段下述的里程碑描述以本 1.1.0 为其实际发布载体——阶段 0-3 的全部内容自本版本起进入 npm 分发。
 
-### 方向落地（阶段 0-3，详见 1.0.0 段与 docs/direction.md）
+### 方向落地（阶段 0-3，详见 1.0.0 段）
 
 - 阶段 0：README 定位改写为「运行时上下文与协作事实层」；注入协议契约 `spec/contracts/context-injection.md`；契约指纹序列化三线统一 + slim 全覆盖 + 跨 host 一致性测试。
 - 阶段 1：`run state [task] --json` 事实视图；`<workflow-state>` 属性事实头 + `<decision-anchor>` 决策要点注入（三线一致）。

package/README.md

@@ -14,7 +14,7 @@
 | 事实接入 | `run state [task] --json` 事实视图；`run mcp-state` 无依赖 MCP 只读服务（`task_state` / `task_list` / `task_scope` / `task_specs`）供任何 MCP 客户端查询；`task scope` / `task specs` 为 CLI 同源事实命令。 |
 | 规范挂命令 | spec 首部 frontmatter 声明 `checks:` 命令，按编辑期/收口期执行；`run spec-check` 输出三态门禁（pass / violation / unchecked）。 |
 | 运行健康 | `doctor` 诊断 runtime、host assets、Skill replica 和任务 hygiene，不推进生命周期。 |
-| Host 分发 | Host Asset Manifest 驱动 Codex / OpenCode / Claude Code / ZCode / DeepSeek Harness 资产和 obsolete 清理。 |
+| Host 分发 | Host Asset Manifest 驱动 Codex / OpenCode / Claude Code / ZCode / Kimi Code / DeepSeek Harness 资产和 obsolete 清理。 |
 | 批处理与讨论 | Batch 发布 Host action；Party Mode 只输出 advisory final facts。 |
 | 发布准备 | `release:check`、`CHANGELOG.md`、`pack:check` 固定发布前证据。 |
 
@@ -76,7 +76,7 @@ cowork-flow mcp-state
 npm run release:check
 ```
 
-平台选项：`codex` / `opencode` / `claude-code` / `dsh` / `zcode` / `all`（逗号分隔）
+平台选项：`codex` / `opencode` / `claude-code` / `dsh` / `zcode` / `kimi-code` / `all`（逗号分隔）
 
 ## 仓库结构
 
@@ -90,6 +90,7 @@ template/
 ├── .opencode/                 # OpenCode agents / commands / plugins
 ├── .dsh/                      # DeepSeek Harness 标记（sync 检测 + 说明）
 ├── .zcode/                    # ⭐ ZCode 插件（hooks + skills + agents + scaffold instructions）
+├── .kimi-code/                # Kimi Code fixed agents（cowork-implement / check / research）
 └── .cowork-flow/
     ├── config.yaml            # 项目配置
     ├── scripts/               # Python 运行时
@@ -116,6 +117,7 @@ Skills 维护在 `template/skills/` 唯一源码，`init` / `sync` 时按目录
 |---|---|
 | `codex` / `opencode` | `.agents/skills/` |
 | `dsh` | `.agents/skills/` |
+| `kimi-code` | `.agents/skills/` |
 | `claude-code` | `.claude/skills/` |
 | `zcode` | `.cowork-flow/skills/`（内核 owner 解析用；系统提示层仍由 ZCode 插件单源提供，不重复加载） |
 
@@ -131,6 +133,7 @@ Skills 维护在 `template/skills/` 唯一源码，`init` / `sync` 时按目录
 | `install-zcode-plugin` | 安装 ZCode 插件到全局缓存 |
 | `install-dsh-preset` | 安装 DSH agent 预设到 `~/.dsh/.agent-presets/cowork-flow/`（整套 agent，可选） |
 | `install-dsh-hook` | 机器级注册 workflow-state hook 组合行到 `$DSH_HOME/cordis.patch.yml`（当前 DSH 的 agent 提示不收集 host 层 section，实时注入请用预设方式） |
+| `install-kimi-hook [--dry-run] [--force] [--uninstall]` | 机器级注册 UserPromptSubmit hook 到 `$KIMI_CODE_HOME/config.toml`（默认 `~/.kimi-code/`），向每个 Kimi Code 会话实时注入工作流上下文 |
 | `update [--dry-run]` | 升级 CLI 本身 |
 | `mcp-state` | 全局 MCP 事实入口：从 cwd 向上定位项目运行时并透传 `run mcp-state`（全局注册一次，所有 cowork-flow 项目通用） |
 
@@ -138,7 +141,7 @@ Skills 维护在 `template/skills/` 唯一源码，`init` / `sync` 时按目录
 
 | 选项 | 说明 |
 |---|---|
-| `--platform <p>` | 平台：`codex` / `opencode` / `claude-code` / `dsh` / `zcode` / `all` |
+| `--platform <p>` | 平台：`codex` / `opencode` / `claude-code` / `dsh` / `zcode` / `kimi-code` / `all` |
 | `--developer <n>` | 开发者名称 |
 | `--force` | 覆盖已有文件 |
 | `--dry-run` | 预览不写入 |
@@ -147,7 +150,7 @@ Skills 维护在 `template/skills/` 唯一源码，`init` / `sync` 时按目录
 
 - **自动识别**已安装 host 目录，只同步对应平台资产
 - **Skills** 从 `template/skills/` 按平台分发
-- **保护文件**：`config.yaml`、`spec/`（除 `workflow-state-templates.md`）、任务、计划、变更
+- **保护文件**：`config.yaml`、`.developer`、`spec/`（例外：`spec/contracts/workflow-state-templates.md` 与 `spec/contracts/spec-checks.md` 两个契约文件）、任务、计划
 - **正式版旧资产清理**：旧脚本位置、旧 adapter 资产和已废弃文件按 Host Asset Manifest 的 `obsoleteFiles` 清理；用户保护文件保持不变
 - **事务恢复**：上次未完成事务会在新一轮 sync 前恢复；事务元数据缺失或损坏时 fail-closed，不在未知状态上继续写入
 - **Dry-run readiness**：`sync --dry-run` 只构建计划并输出 `readiness=<json>`，不写文件或事务状态；字段包含 `wouldCopy`、`wouldSkipProtected`、`wouldRemoveObsolete`、`hostAssetRefresh`、`pendingRecovery`、`warnings`
@@ -246,6 +249,22 @@ cowork-flow install-dsh-preset --dry-run  # 预览不写入
 
 预设内置 **workflow-state hook**（`plugins/workflow-state.js`）：DSH 原生等效于 Codex/Claude hook，向系统提示末尾注入与其它宿主同构的 `<workflow-state>` 块，每条用户消息刷新一次，并在生命周期命令（`task`/`subagent`/`resume`）执行完成后立即轮内刷新（替换语义，不累积）。项目无 `.cowork-flow` 根、缺少 Python 或设 `COWORK_FLOW_HOOKS=0` / `COWORK_FLOW_DISABLE_HOOKS=1` 时静默降级，由 AGENTS.md 门禁的运行导航器兜底。
 
+## Kimi Code hook
+
+```bash
+cowork-flow install-kimi-hook             # 安装（无条件覆盖）；--force 与不带旗标同义
+cowork-flow install-kimi-hook --dry-run   # 预览将写入的托管块，不写文件
+cowork-flow install-kimi-hook --uninstall # 卸载托管块、shim 与版本标记
+```
+
+安装写入用户级 Kimi Code home（`KIMI_CODE_HOME`，未设置时默认 `~/.kimi-code/`）：hook 脚本 `hooks/cowork-flow-inject.mjs`、版本标记 `hooks/.cowork-flow-kimi-hook.json`，并在 `config.toml` 追加一段由注释标记包裹的托管块——一条 `[[hooks]]`，`event = "UserPromptSubmit"`、`command`、`timeout = 30`，不写 `matcher`（即匹配每条提交的提示）。配置文件按文本编辑、不做 TOML 重排，托管块以外的用户内容原样保留；卸载只移除这段托管块和上面两个文件，`config.toml` 因此变空时一并删除。
+
+Kimi Code 只注册 `UserPromptSubmit` 一个事件：`SessionStart` / `PostToolUse` 等观察型事件的 stdout 会被宿主丢弃，无法注入内容。hook 的 stdout 就是注入正文，宿主把它追加进提示上下文；shim 在项目根目录预检失败（非 cowork-flow 项目）时直接短路，不启动 Python 进程，全局开关为 `COWORK_FLOW_HOOKS=0` / `COWORK_FLOW_DISABLE_HOOKS=1`。
+
+> 安装或更新后需要**重启 Kimi Code 会话**（或重新加载配置）才会加载 hook。
+
+Kimi Code 的 Bash 工具不导出会话标识环境变量，CLI 侧身份只能取自注入头里的 `session="kimi_<id>"`，需要显式传 `COWORK_FLOW_CONTEXT_ID`（或 `COWORK_FLOW_HOST=kimi-code`）。`./.cowork-flow/run doctor` 把该 hook 的注册情况作为 warning 级项报告（`HOOK-NOT-INSTALLED` / `HOOK-SHIM-MISSING` / `HOOK-UNKNOWN-VERSION` / `HOOK-STALE`），不计入 errors。
+
 ## 任务流程
 
 ```
@@ -300,7 +319,7 @@ checks:
 唯一执行器是 `./.cowork-flow/run spec-check`：
 
 - **三态语义**：`pass`（退出码 0）；`violation` 阻断 `task complete`；`unchecked`（命令缺失、解释器缺失、超时）同样阻断，需显式 `--allow-unchecked` 放行，豁免留痕进 `task.json`。unchecked 永不冒充 pass。
-- **两个相位**：`when: edit` 在编辑期就地执行（超时钳制 2.5 秒，违规输出单行提示；五个宿主均已覆盖，其中 zcode 仅主会话），是 best-effort 提示不是门禁；收口期全量执行，未过项阻断状态推进。
+- **两个相位**：`when: edit` 在编辑期就地执行（超时钳制 2.5 秒，违规输出单行提示；具备编辑期 hook 的宿主均已覆盖，其中 zcode 仅主会话），是 best-effort 提示不是门禁；收口期全量执行，未过项阻断状态推进。
 - **扫描范围**：`.cowork-flow/spec/` 下的 markdown；`contracts/`、`runtime/`、`schemas/` 三个机器自有子树不参与。
 - **模板不带生效声明**：模板无法预知项目命令，而命令缺失会归 `unchecked` 并阻断收口；请把声明写进自建 spec 文件（如 `spec/team-xxx.md`）。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
   ],
   "scripts": {
     "test": "npm run test:fast",
-    "test:fast": "node --test test/asset-plan.test.js test/cli.test.js test/host-assets.test.js test/opencode-plugin.test.js test/package.test.js test/template-runner.test.js test/update.test.js test/zcode-plugin.test.js",
+    "test:fast": "node --test test/asset-plan.test.js test/cli.test.js test/host-assets.test.js test/kimi-hook.test.js test/opencode-plugin.test.js test/package.test.js test/template-runner.test.js test/update.test.js test/zcode-plugin.test.js",
     "test:integration": "node --test --test-name-pattern=\"^(init copies the template into a new target directory|sync updates safe template files and preserves protected files)$\" test/init.test.js test/sync.test.js",
     "test:node:full": "node --test",
     "test:template": "node scripts/run-template-tests.js --suite core",

package/presets/kimi-code/hooks/cowork-flow-inject.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * cowork-flow Kimi Code hook — transport shim.
+ *
+ * Kimi Code appends a UserPromptSubmit hook's stdout to the prompt context
+ * verbatim, so all workflow facts are rendered by the single Python source
+ * (inject.py --host kimi-code, emit_text policy). This shim keeps only
+ * transport duties:
+ *   1. cheap project-root pre-check — a cwd outside any cowork-flow project
+ *      exits 0 without spawning anything, so the user-level hook never
+ *      touches unrelated repositories;
+ *   2. interpreter location (COWORK_FLOW_PYTHON → python3 → python → py -3);
+ *   3. stdin passthrough to inject.py, stdout/exit forwarding.
+ *
+ * Fail-open by construction: a missing interpreter, a missing runtime, or a
+ * broken project copy all exit 0 with empty stdout instead of blocking the
+ * user's prompt (a non-zero exit on UserPromptSubmit aborts the submit).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const WORKFLOW_DIR = ".cowork-flow";
+const INJECT_RELATIVE = join(
+  WORKFLOW_DIR,
+  "scripts",
+  "adapters",
+  "host",
+  "inject.py"
+);
+const HOST = "kimi-code";
+const SPAWN_TIMEOUT_MS = 20000; // config.toml grants the hook 30s
+
+function readHookInput() {
+  if (process.stdin.isTTY) return { raw: "", parsed: {} };
+  let raw = "";
+  try {
+    raw = readFileSync(0, "utf8").trim();
+  } catch {
+    return { raw: "", parsed: {} };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return { raw, parsed: parsed && typeof parsed === "object" ? parsed : {} };
+  } catch {
+    return { raw: "", parsed: {} };
+  }
+}
+
+function findProjectRoot(startDir) {
+  if (typeof startDir !== "string" || !startDir.trim()) return null;
+  let current = startDir.trim();
+  const root = dirname(current);
+  while (current !== root) {
+    if (existsSync(join(current, INJECT_RELATIVE))) return current;
+    current = dirname(current);
+  }
+  return existsSync(join(current, INJECT_RELATIVE)) ? current : null;
+}
+
+function pythonCandidates() {
+  const list = [];
+  const env = (process.env.COWORK_FLOW_PYTHON || "").trim();
+  if (env) list.push([env]);
+  list.push(["python3"], ["python"]);
+  if (process.platform === "win32") list.push(["py", "-3"]);
+  return list;
+}
+
+function main() {
+  if (
+    process.env.COWORK_FLOW_HOOKS === "0" ||
+    process.env.COWORK_FLOW_DISABLE_HOOKS === "1"
+  ) {
+    process.exit(0);
+  }
+
+  const { raw, parsed } = readHookInput();
+  const cwd =
+    typeof parsed?.cwd === "string" && parsed.cwd.trim()
+      ? parsed.cwd
+      : process.cwd();
+  const root = findProjectRoot(cwd);
+  if (!root) process.exit(0);
+
+  const injectScript = join(root, INJECT_RELATIVE);
+  for (const candidate of pythonCandidates()) {
+    let result;
+    try {
+      result = spawnSync(
+        candidate[0],
+        [...candidate.slice(1), injectScript, "--host", HOST],
+        {
+          input: raw,
+          timeout: SPAWN_TIMEOUT_MS,
+          encoding: "utf8",
+          windowsHide: true,
+        }
+      );
+    } catch {
+      continue;
+    }
+    if (result.error || result.status === null) continue;
+    if (result.stdout) process.stdout.write(result.stdout);
+    process.exit(result.status);
+  }
+  // No interpreter could run the entry: stay silent rather than break the
+  // user's submit (fail-open, same contract as the other host shims).
+  process.exit(0);
+}
+
+main();

package/src/cli.js

@@ -5,6 +5,7 @@ import { createInterface } from 'node:readline/promises';
 import { runInit } from './commands/init.js';
 import { runInstallDshHook } from './commands/install-dsh-hook.js';
 import { runInstallDshPreset } from './commands/install-dsh-preset.js';
+import { runInstallKimiHook } from './commands/install-kimi-hook.js';
 import { runInstallZCodePlugin } from './commands/install-zcode-plugin.js';
 import { runMcpState } from './commands/mcp-state.js';
 import { runSourceRefresh } from './commands/source-refresh.js';
@@ -19,6 +20,7 @@ Usage:
   cowork-flow install-zcode-plugin [--dry-run] [--force] [--prune-old]
   cowork-flow install-dsh-preset [--dry-run] [--force]
   cowork-flow install-dsh-hook [--dry-run] [--force] [--uninstall]
+  cowork-flow install-kimi-hook [--dry-run] [--force] [--uninstall]
   cowork-flow update
   cowork-flow sync [target] [--dry-run] [--force]
   cowork-flow source-refresh [target] [--dry-run]
@@ -201,6 +203,10 @@ export async function main(argv = process.argv.slice(2), options = {}) {
       return await runInstallDshHook(args);
     }
 
+    if (command === 'install-kimi-hook') {
+      return await runInstallKimiHook(args);
+    }
+
     if (command === 'mcp-state') {
       return await runMcpState(args);
     }

package/src/commands/install-kimi-hook.js

@@ -0,0 +1,343 @@
+import { access, copyFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+import { packageRoot } from '../lib/paths.js';
+import { readPackageInfo } from '../lib/package-info.js';
+
+const SHIM_NAME = 'cowork-flow-inject.mjs';
+const SHIM_SRC = join(packageRoot, 'presets', 'kimi-code', 'hooks', SHIM_NAME);
+const MARKER_FILE = '.cowork-flow-kimi-hook.json';
+const HOOK_EVENT = 'UserPromptSubmit';
+// Kimi Code's own hook default; kept explicit so an edit is visible here.
+const HOOK_TIMEOUT = 30;
+const MANAGED_START = '# cowork-flow: kimi hook start. Managed by "cowork-flow install-kimi-hook"; edits inside this block are replaced.';
+const MANAGED_END = '# cowork-flow: kimi hook end.';
+
+
+function parseArgs(args) {
+  return {
+    dryRun: args.includes('--dry-run'),
+    force: args.includes('--force'),
+    uninstall: args.includes('--uninstall')
+  };
+}
+
+
+function getKimiHome() {
+  return process.env.KIMI_CODE_HOME || join(homedir(), '.kimi-code');
+}
+
+
+async function pathExists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+
+async function readIfExists(file) {
+  try {
+    return await readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+
+/**
+ * Kimi Code's user-level config.toml, holding the `[[hooks]]` rows.
+ */
+function configFile(home) {
+  return join(home, 'config.toml');
+}
+
+
+/**
+ * Transport shim installed beside the config, spawned as
+ * `node <home>/hooks/cowork-flow-inject.mjs` from every session.
+ */
+function shimDest(home) {
+  return join(home, 'hooks', SHIM_NAME);
+}
+
+
+/**
+ * Version marker for the installed hook, written next to the shim. The
+ * installed files live outside any project, so nothing else records which
+ * release put them there — doctor reads this to tell an up-to-date install
+ * from one that predates the project runtime.
+ */
+function markerDest(home) {
+  return join(home, 'hooks', MARKER_FILE);
+}
+
+
+/**
+ * One `[[hooks]]` row that pipes every UserPromptSubmit payload into the
+ * shim. Kimi Code allows exactly four hook fields — event, matcher, command,
+ * timeout — and rejects the whole config when a row carries anything else,
+ * so the row is deliberately minimal. `matcher` is omitted on purpose:
+ * omitted means "match every prompt". Paths are quoted because a Kimi Code
+ * home may contain spaces (Windows user profiles).
+ */
+function hookBlock(home) {
+  const command = 'node "' + shimDest(home) + '"';
+  return [
+    MANAGED_START,
+    '[[hooks]]',
+    'event = ' + JSON.stringify(HOOK_EVENT),
+    'command = ' + JSON.stringify(command),
+    'timeout = ' + HOOK_TIMEOUT,
+    MANAGED_END
+  ].join('\n');
+}
+
+
+/**
+ * End of the `[[hooks]]` row starting at `start`: the next table header, the
+ * next row of the same array, or the end of file. Trailing blank lines stay
+ * outside the range so removal leaves them for the surrounding layout.
+ */
+function hookRowEnd(lines, start) {
+  let end = start + 1;
+  while (end < lines.length) {
+    const trimmed = lines[end].trim();
+    if (trimmed === '[[hooks]]' || (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+      break;
+    }
+    end += 1;
+  }
+  while (end > start + 1 && lines[end - 1].trim() === '') {
+    end -= 1;
+  }
+  return end;
+}
+
+
+/**
+ * Locate the managed block inside the config text.
+ *
+ * The config is edited as text on purpose: a TOML round-trip would rewrite
+ * every pretty-printed entry of the user's own config (providers, models,
+ * permissions), and the file must stay byte-stable outside the block. The
+ * marker comments take precedence so the block is removed even when the row
+ * no longer resembles ours; without markers, the only ownership signal left
+ * is a `[[hooks]]` row whose command names this shim. Returns null when
+ * neither exists.
+ */
+function findManagedBlock(text, home) {
+  const lines = text.split('\n');
+  const marked = lines.findIndex((line) => line.trim() === MANAGED_START);
+  if (marked !== -1) {
+    let end = marked + 1;
+    while (end < lines.length && lines[end].trim() !== MANAGED_END) {
+      end += 1;
+    }
+    return { start: marked, end: Math.min(end + 1, lines.length) };
+  }
+  const owns = shimDest(home).replace(/\\/g, '/');
+  for (let index = 0; index < lines.length; index += 1) {
+    if (lines[index].trim() !== '[[hooks]]') {
+      continue;
+    }
+    const end = hookRowEnd(lines, index);
+    const row = lines.slice(index, end).join('\n');
+    if (row.includes(MANAGED_START) || row.replace(/\\/g, '/').includes(owns)) {
+      return { start: index, end };
+    }
+  }
+  return null;
+}
+
+
+function withBlock(text, home) {
+  const block = hookBlock(home).split('\n');
+  const range = findManagedBlock(text, home);
+  if (range !== null) {
+    const lines = text.split('\n');
+    if (lines.slice(range.start, range.end).join('\n') === block.join('\n')) {
+      return { text, changed: false, existed: true };
+    }
+    return {
+      text: lines.slice(0, range.start).concat(block).concat(lines.slice(range.end)).join('\n'),
+      changed: true,
+      existed: true
+    };
+  }
+  const base = text.replace(/\s+$/, '');
+  const appended = base === '' ? block.join('\n') : base + '\n\n' + block.join('\n');
+  return { text: appended + '\n', changed: true, existed: false };
+}
+
+
+function withoutBlock(text, home) {
+  const range = findManagedBlock(text, home);
+  if (range === null) {
+    return { text, changed: false };
+  }
+  const lines = text.split('\n');
+  const kept = lines.slice(0, range.start).concat(lines.slice(range.end));
+  const body = kept.join('\n').replace(/^\n+/, '').replace(/\s+$/, '');
+  if (body === '') {
+    // Nothing of the user's own config remains: an empty file left behind
+    // would be a config that only ever held this hook.
+    return { text: '', changed: true };
+  }
+  return { text: body + '\n', changed: true };
+}
+
+
+/**
+ * Compact line preview for --dry-run: every line that differs plus its
+ * neighbours, so the operator sees where the block lands without a full-file
+ * dump.
+ */
+function previewDiff(before, after) {
+  // A trailing newline is a line terminator, not an extra empty line; without
+  // this the preview would always report a phantom last-line change.
+  const toLines = (text) => {
+    if (text === '') {
+      return [];
+    }
+    return (text.endsWith('\n') ? text.slice(0, -1) : text).split('\n');
+  };
+  const left = toLines(before);
+  const right = toLines(after);
+  const total = Math.max(left.length, right.length);
+  const shown = new Set();
+  for (let index = 0; index < total; index += 1) {
+    if (left[index] !== right[index]) {
+      for (let offset = -2; offset <= 2; offset += 1) {
+        if (index + offset >= 0 && index + offset < total) {
+          shown.add(index + offset);
+        }
+      }
+    }
+  }
+  const lines = [];
+  let previous = -1;
+  for (const index of [...shown].sort((a, b) => a - b)) {
+    if (previous !== -1 && index > previous + 1) {
+      lines.push('  ...');
+    }
+    const marker = left[index] === right[index] ? '  ' : '+ ';
+    lines.push('  ' + (index + 1) + ' ' + marker + (right[index] ?? ''));
+    previous = index;
+  }
+  return lines;
+}
+
+
+/**
+ * Install (or uninstall) the user-level Kimi Code context-injection hook.
+ *
+ * Kimi Code reads hooks only from $KIMI_CODE_HOME/config.toml, so the shim is
+ * installed under the same home and every session — in every project —
+ * invokes it; the shim itself exits silently outside cowork-flow projects.
+ * Only the Kimi Code home is written: no project file is touched.
+ */
+export async function runInstallKimiHook(args = []) {
+  const { dryRun, uninstall } = parseArgs(args);
+
+  if (!(await pathExists(SHIM_SRC))) {
+    throw new Error('Kimi Code hook shim missing at ' + SHIM_SRC + '. Reinstall cowork-flow.');
+  }
+
+  const home = getKimiHome();
+  const config = configFile(home);
+  const shim = shimDest(home);
+  const marker = markerDest(home);
+
+  if (dryRun) {
+    const before = await readIfExists(config);
+    if (uninstall) {
+      const result = before === null ? { changed: false } : withoutBlock(before, home);
+      console.log('[dry-run] Would uninstall Kimi Code context hook:');
+      console.log(
+        '  Config: ' + config
+          + (before === null
+            ? ' (absent; nothing to remove)'
+            : (result.changed ? ' (managed block found)' : ' (no managed block)'))
+      );
+      console.log('  Remove shim: ' + shim);
+      console.log('  Remove marker: ' + marker);
+      return;
+    }
+    console.log('[dry-run] Would install Kimi Code context hook:');
+    console.log('  Shim: ' + SHIM_SRC + ' -> ' + shim);
+    console.log('  Marker: ' + marker);
+    if (before === null) {
+      console.log('  Create config: ' + config);
+      for (const line of previewDiff('', hookBlock(home))) {
+        console.log(line);
+      }
+      return;
+    }
+    const result = withBlock(before, home);
+    if (!result.changed) {
+      console.log('  Config: ' + config + ' (managed block already up to date)');
+      return;
+    }
+    console.log('  Config: ' + config + (result.existed ? ' (update managed block)' : ' (append managed block)'));
+    for (const line of previewDiff(before, result.text)) {
+      console.log(line);
+    }
+    return;
+  }
+
+  if (uninstall) {
+    const before = await readIfExists(config);
+    if (before === null) {
+      console.log('No Kimi Code config at ' + config + '; nothing to uninstall.');
+    } else {
+      const result = withoutBlock(before, home);
+      if (!result.changed) {
+        console.log('No managed hook block found in ' + config + '.');
+      } else if (result.text === '') {
+        await rm(config, { force: true });
+        console.log('✓ Kimi Code context hook removed; ' + config + ' held nothing else and was deleted.');
+      } else {
+        await writeFile(config, result.text, 'utf8');
+        console.log('✓ Kimi Code context hook removed from ' + config);
+      }
+    }
+    const hadShim = await pathExists(shim);
+    await rm(shim, { force: true });
+    if (hadShim) {
+      console.log('✓ Removed hook shim ' + shim);
+    }
+    const hadMarker = await pathExists(marker);
+    await rm(marker, { force: true });
+    if (hadMarker) {
+      console.log('✓ Removed version marker ' + marker);
+    }
+    return;
+  }
+
+  const { version } = await readPackageInfo();
+  await mkdir(dirname(shim), { recursive: true });
+  await copyFile(SHIM_SRC, shim);
+  await writeFile(
+    marker,
+    `${JSON.stringify({ version, installedAt: new Date().toISOString() }, null, 2)}\n`,
+    'utf8'
+  );
+  const before = (await readIfExists(config)) ?? '';
+  const result = withBlock(before, home);
+  if (result.changed) {
+    await writeFile(config, result.text, 'utf8');
+  }
+
+  console.log('✓ cowork-flow Kimi Code hook shim installed to ' + shim);
+  console.log('  Recorded version ' + version + ' in ' + marker);
+  console.log(
+    '  Registered UserPromptSubmit hook in ' + config
+      + (result.changed ? (result.existed ? ' (block updated)' : ' (block appended)') : ' (already up to date)')
+  );
+  console.log('  Start a new Kimi Code session (or reload the config) for the hook to load.');
+  console.log('  Note: injection happens once per submitted prompt; other Kimi Code events cannot inject.');
+}