@brawnen/agent-harness-cli 0.1.1 → 0.1.2

package/README.md

@@ -2,11 +2,14 @@
 
 [中文](README.zh-CN.md)
 
-`@brawnen/agent-harness-cli` is the Node.js CLI for `agent-harness`.
+`@brawnen/agent-harness-cli` is the compatibility CLI for `agent-harness`.
 
-It is the runtime layer that turns protocol rules into a working task loop with:
+Its focus is no longer to be the long-term product center. It is the compatibility layer for:
 
 - initialization
+- host/runtime bootstrap
+- status inspection
+- manual fallback commands
 - task state
 - verification
 - reports
@@ -15,6 +18,10 @@ It is the runtime layer that turns protocol rules into a working task loop with:
 - delivery
 - documentation scaffolding
 
+The repo-local host runtime is becoming the primary execution surface. The CLI remains for initialization, diagnostics, and explicit manual operations.
+
+This package is now in maintenance mode. It remains publishable and usable, but it is no longer intended to grow into the long-term product center.
+
 ## Current Coverage
 
 The CLI currently includes these commands:
@@ -42,7 +49,7 @@ The current implementation also covers:
 
 ## Current Boundaries
 
-The CLI is already usable, but it is still an evolving implementation.
+The CLI is already usable, but it should now be treated as a bounded compatibility layer rather than an expanding surface.
 
 It currently does not try to provide:
 
@@ -51,6 +58,12 @@ It currently does not try to provide:
 - automatic `git push`
 - a deep upgrader / migration system
 
+Maintenance-mode interpretation:
+
+- keep it usable for bootstrap, diagnostics, and manual fallback
+- accept bug fixes, compatibility fixes, and documentation clarification
+- do not keep expanding host-specific wrapper behavior
+
 ## What The CLI Does Today
 
 ### `init`
@@ -226,6 +239,8 @@ Useful local checks:
 ```bash
 npm --prefix packages/cli run verify:task-core
 npm --prefix packages/cli run verify:codex-e2e
+npm --prefix packages/cli run verify:host-hooks
+npm --prefix packages/cli run verify:init-status
 ```
 
 From the repository root:
@@ -233,8 +248,14 @@ From the repository root:
 ```bash
 npm run codex:hooks:check
 npm run codex:e2e
+npm run runtime:host-hooks
+npm run runtime:init-status
+npm run runtime:p1:check
+node packages/cli/bin/agent-harness.js sync --check
 ```
 
+`codex:hooks:check` validates the source-of-truth hook files under `.harness/hosts/codex/hooks/`, not the generated root `.codex/` shell.
+
 ## Local Invocation Note
 
 If your current working directory is not the repository root, prefer calling the CLI with an absolute path, for example:
@@ -251,4 +272,5 @@ Do not assume `node packages/cli/bin/agent-harness.js ...` will work from an arb
 - installing `@brawnen/agent-harness-cli` from npm should automatically pull `@brawnen/agent-harness-protocol`
 - the protocol must not depend on the CLI
 - the default npm entrypoint is `npx @brawnen/agent-harness-cli init`
-- this repository currently treats the Node.js CLI as the only mainline implementation
+- this repository now treats the Node.js CLI as the compatibility layer of `Agent Harness Runtime`
+- repo-local hooks should now consume the stable runtime entry `@brawnen/agent-harness-cli/runtime-host`

package/README.zh-CN.md

@@ -2,7 +2,10 @@
 
 [English](README.md)
 
-这是 `agent-harness` 的 Node.js CLI。
+这是 `agent-harness` 的兼容 CLI。
+
+当前产品方向已经明确：宿主运行时逐步前移到 repo-local hooks，`CLI` 主要负责初始化、状态检查、人工 fallback 和显式交付动作。
+这个包现在已经进入维护态：保持可用、可发布、可诊断，但不再继续向长期主产品方向扩张。
 
 当前已完成：
 
@@ -22,9 +25,11 @@
 - 基础项目配置生成
 - `.codex/hooks.json` 最小方案
 
-还未完成：
+当前边界：
 
-- 更深的宿主集成
+- 继续支持初始化、状态检查、验证、报告和人工 fallback
+- 接受必要的 bug fix、兼容修复和文档澄清
+- 不再继续扩大宿主专属 wrapper 行为
 
 `init` MVP 当前负责：
 
@@ -218,7 +223,13 @@ node /abs/path/to/agent-harness/packages/cli/bin/agent-harness.js audit read --t
 Codex E2E 回归：
 
 - 可执行 `npm --prefix packages/cli run verify:codex-e2e`
+- 可执行 `npm --prefix packages/cli run verify:host-hooks`
+- 可执行 `npm --prefix packages/cli run verify:init-status`
+- 可执行 `npm --prefix packages/cli run verify:status-compat`
 - 或在仓库根目录执行 `npm run codex:e2e`
+- 或在仓库根目录执行 `npm run runtime:host-hooks`
+- 或在仓库根目录执行 `npm run runtime:init-status`
+- 或在仓库根目录执行 `npm run runtime:p1:check`
 - 当前最小回归覆盖：新任务自动 intake、follow-up 不误切、高风险确认链路、hook 降级提示
 - 当前回归采用“真实 `codex exec` smoke + hook 主链路回归”混合方式，优先验证我们自己的接入链路
 - 当前脚本会在**当前 trusted 仓库**里执行真实 Codex 回归，并清理自己创建的 task/audit/report 文件
@@ -229,4 +240,5 @@ Codex E2E 回归：
 - CLI 依赖 `@brawnen/agent-harness-protocol`
 - 从 npm 安装 `@brawnen/agent-harness-cli` 时，应自动带上 `@brawnen/agent-harness-protocol`
 - 默认 npm 入口是 `npx @brawnen/agent-harness-cli init`
-- 当前仓库以 Node.js CLI 作为唯一主线实现
+- 当前仓库将 Node.js CLI 视为 `Agent Harness Runtime` 的 compatibility layer
+- repo-local hooks 当前应通过 `@brawnen/agent-harness-cli/runtime-host` 这一稳定入口接入 runtime

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@brawnen/agent-harness-cli",
-  "version": "0.1.1",
-  "description": "CLI for task convergence, verification, reporting, and delivery in agent-harness projects.",
+  "version": "0.1.2",
+  "description": "Compatibility CLI for bootstrap, status, and manual fallback in agent-harness projects.",
   "license": "MIT",
   "bin": {
     "agent-harness": "./bin/agent-harness.js"
   },
+  "exports": {
+    "./runtime-host": "./src/runtime-host/index.js"
+  },
   "type": "module",
   "files": [
     "bin",
@@ -35,10 +38,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@brawnen/agent-harness-protocol": "^0.1.1"
+    "@brawnen/agent-harness-protocol": "^0.1.2"
   },
   "scripts": {
-    "start": "node ./bin/agent-harness.js --help"
+    "start": "node ./bin/agent-harness.js --help",
+    "verify:codex-e2e": "node ./scripts/verify-codex-e2e.js",
+    "verify:host-hooks": "node ./scripts/verify-host-hooks-smoke.js",
+    "verify:init-status": "node ./scripts/verify-host-init-status.js",
+    "verify:status-compat": "node ./scripts/verify-sync-status-compat.js",
+    "verify:task-core": "node ./scripts/verify-task-core-classification.js"
   },
   "engines": {
     "node": ">=18"

package/src/commands/docs.js

@@ -154,31 +154,33 @@ function buildDesignNoteTemplate(title, context) {
   return [
     `# ${title}`,
     "",
-    "## 背景",
+    "## 决策摘要",
     "",
     `- task_id: \`${context.task_id}\``,
     `- intent: \`${context.intent}\``,
     `- risk_level: \`${context.risk_level}\``,
+    context.goal ? `- goal: ${context.goal}` : "- goal: 待补充",
     "",
-    "## 目标",
+    "## 要解决的问题",
     "",
-    context.goal ? `- ${context.goal}` : "- 待补充",
+    "- 问题：待补充",
     "",
-    "## 作用范围",
+    "## 采用方案",
     "",
-    ...toBulletLines(context.scope),
+    "- 方案：待补充",
     "",
-    "## 方案",
+    "## 为什么选这个方案",
     "",
-    "- 待补充",
+    "- 原因：待补充",
     "",
-    "## 风险与权衡",
+    "## 边界与风险",
     "",
-    "- 待补充",
+    ...toBulletLines(context.scope),
+    "- 风险与权衡：待补充",
     "",
-    "## 验证计划",
+    "## 验证",
     "",
-    "- 待补充",
+    "- 验证方式：待补充",
     ""
   ].join("\n");
 }
@@ -200,9 +202,13 @@ function buildAdrTemplate(title, context) {
     "",
     "## 决策",
     "",
-    "- 待补充",
+    "- 决策内容：待补充",
+    "",
+    "## 备选方案",
+    "",
+    "- 备选方案及放弃原因：待补充",
     "",
-    "## 后果",
+    "## 代价与后果",
     "",
     "- 正面影响：待补充",
     "- 代价与风险：待补充",

package/src/commands/init.js

@@ -3,9 +3,10 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { collectHostLayoutWrites } from "../lib/host-layout.js";
 import { DEFAULT_RUNTIME_DIR, defaultRuntimeRelativePath } from "../lib/runtime-paths.js";
 
-const CLI_VERSION = "0.1.0";
+const CLI_VERSION = "0.1.2";
 const RULE_MODES = new Set(["base", "full"]);
 const HOSTS = new Set(["auto", "claude-code", "codex", "gemini-cli"]);
 const MODES = new Set(["delivery", "explore", "poc"]);
@@ -36,16 +37,19 @@ export function runInit(argv) {
   const project = detectProject(cwd);
   const hosts = resolveHosts(cwd, parsed.options.host);
   const actions = [];
+  const warnings = [];
 
   queueInitActions({
     cwd,
     project,
     hosts,
     options: parsed.options,
-    actions
+    actions,
+    warnings
   });
 
   printPlan(actions, parsed.options.dryRun, cwd, project, hosts);
+  printWarnings(warnings);
 
   if (parsed.options.dryRun) {
     return 0;
@@ -277,8 +281,7 @@ function resolveHosts(cwd, explicitHost) {
 }
 
 function queueInitActions(context) {
-  const { actions, cwd, hosts, options, project } = context;
-  const ruleText = readText(path.join(PROTOCOL_ROOT, "rules", `${options.rules}.md`));
+  const { actions, cwd, hosts, options, project, warnings } = context;
 
   queueWriteAction({
     actions,
@@ -288,16 +291,34 @@ function queueInitActions(context) {
   });
 
   queueProtocolTemplates(actions, cwd, options.force);
-  queueRulesInjection(actions, cwd, hosts, options, ruleText);
+  queueHostLayoutActions(actions, warnings, cwd, hosts, options);
 
   if (!options.protocolOnly) {
     queueRuntimeFiles(actions, cwd);
-    if (hosts.includes("claude-code")) {
-      queueClaudeSettingsMerge(actions, cwd);
-    }
-    if (hosts.includes("gemini-cli")) {
-      queueGeminiSettingsMerge(actions, cwd);
-    }
+  }
+}
+
+function queueHostLayoutActions(actions, warnings, cwd, hosts, options) {
+  const layout = collectHostLayoutWrites(cwd, {
+    hosts,
+    includeConfigs: !options.protocolOnly,
+    includeRules: true,
+    rewrite: options.force,
+    seedMissing: true
+  });
+
+  warnings.push(...layout.warnings);
+
+  for (const write of layout.writes) {
+    actions.push({
+      description: describeHostLayoutWrite(write),
+      relativePath: path.relative(cwd, write.targetPath),
+      run: () => {
+        ensureDirectory(path.dirname(write.targetPath));
+        fs.writeFileSync(write.targetPath, write.content, "utf8");
+      },
+      skip: false
+    });
   }
 }
 
@@ -688,6 +709,38 @@ function printPlan(actions, dryRun, cwd, project, hosts) {
   }
 }
 
+function printWarnings(warnings) {
+  if (!Array.isArray(warnings) || warnings.length === 0) {
+    return;
+  }
+
+  console.log("");
+  console.log("提示：");
+  for (const warning of warnings) {
+    console.log(`  - ${warning}`);
+  }
+}
+
+function describeHostLayoutWrite(write) {
+  if (write.type === "source") {
+    return "写入收敛布局源文件";
+  }
+
+  if (write.type === "host") {
+    return "生成宿主薄壳配置";
+  }
+
+  if (write.type === "rule") {
+    return "生成宿主规则文件";
+  }
+
+  if (write.type === "generated") {
+    return "生成布局清单";
+  }
+
+  return "写入布局文件";
+}
+
 function readText(filePath) {
   return fs.readFileSync(filePath, "utf8");
 }

package/src/commands/report.js

@@ -256,15 +256,15 @@ function buildMissingArtifactsMessage(taskId, error, outputPolicy) {
 
     if (artifact === "design_note") {
       const suggestedPath = path.posix.join(outputPolicy.design_note.directory, `${taskId}-design-note.md`);
-      lines.push(`- design_note: 可先执行 \`node packages/cli/bin/agent-harness.js docs scaffold --type design-note --task-id ${taskId} --path ${suggestedPath}\``);
-      lines.push(`  然后在 report 中补上 \`--design-note ${suggestedPath}\``);
+      lines.push(`- design_note: 当前任务命中 design note 条件。若尚未沉淀设计决策，可执行 \`node packages/cli/bin/agent-harness.js docs scaffold --type design-note --task-id ${taskId} --path ${suggestedPath}\``);
+      lines.push(`  完成后在 report 中补上 \`--design-note ${suggestedPath}\``);
       continue;
     }
 
     if (artifact === "adr") {
       const suggestedPath = path.posix.join(outputPolicy.adr.directory, `${taskId}-adr.md`);
-      lines.push(`- adr: 可先执行 \`node packages/cli/bin/agent-harness.js docs scaffold --type adr --task-id ${taskId} --path ${suggestedPath}\``);
-      lines.push(`  然后在 report 中补上 \`--adr ${suggestedPath}\``);
+      lines.push(`- adr: 当前任务命中 ADR 条件。若尚未记录正式决策，可执行 \`node packages/cli/bin/agent-harness.js docs scaffold --type adr --task-id ${taskId} --path ${suggestedPath}\``);
+      lines.push(`  完成后在 report 中补上 \`--adr ${suggestedPath}\``);
     }
   }
 

package/src/commands/status.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { evaluateTaskDeliveryReadiness, summarizeDeliveryReadiness } from "../lib/delivery-policy.js";
+import { hasConvergedHostLayout, HOST_LAYOUT_VERSION } from "../lib/host-layout.js";
 import { evaluateTaskArtifactPolicy, inspectOutputPolicyWorkspace, normalizeOutputPolicy } from "../lib/output-policy.js";
 import { loadProjectConfig } from "../lib/project-config.js";
 import {
@@ -36,6 +37,10 @@ export function runStatus(argv) {
   pushCheck(checks, harnessConfig);
   exitCode = maxExitCode(exitCode, harnessConfig.severity);
 
+  const hostLayoutCheck = inspectHostLayout(cwd);
+  pushCheck(checks, hostLayoutCheck);
+  exitCode = maxExitCode(exitCode, hostLayoutCheck.severity);
+
   const deliveryPolicyCheck = inspectDeliveryPolicy(cwd);
   pushCheck(checks, deliveryPolicyCheck);
   exitCode = maxExitCode(exitCode, deliveryPolicyCheck.severity);
@@ -144,6 +149,28 @@ function inspectDeliveryPolicy(cwd) {
   return ok("delivery_policy", `active_task=${activeTask.task_id}；${summarizeDeliveryReadiness(readiness)}`);
 }
 
+function inspectHostLayout(cwd) {
+  if (!hasConvergedHostLayout(cwd)) {
+    return warn("host_layout", "未检测到 .harness/hosts 与 .harness/rules，当前仍可能处于旧布局");
+  }
+
+  const manifestPath = path.join(cwd, ".harness", "generated", "manifest.json");
+  if (!fs.existsSync(manifestPath)) {
+    return warn("host_layout", "已检测到收敛布局源目录，但缺少 .harness/generated/manifest.json");
+  }
+
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    const version = manifest.version ?? HOST_LAYOUT_VERSION;
+    const hosts = Array.isArray(manifest.hosts) && manifest.hosts.length > 0
+      ? manifest.hosts.join(", ")
+      : "unknown";
+    return ok("host_layout", `已启用收敛布局（version=${version}, hosts=${hosts}）`);
+  } catch {
+    return warn("host_layout", ".harness/generated/manifest.json 存在，但 JSON 解析失败");
+  }
+}
+
 function inspectOutputPolicy(cwd) {
   const config = loadProjectConfig(cwd);
   if (!config) {
@@ -359,36 +386,41 @@ function inspectClaudeHooks(cwd, runtimeMode, hasClaudeHost) {
     .map((hook) => hook.command)
     .filter(Boolean);
 
-  const hasPreTool = commands.some((command) =>
-    command.includes("agent-harness gate before-tool") ||
-    command.includes("@brawnen/agent-harness-cli gate before-tool") ||
-    command.includes("packages/cli/bin/agent-harness.js\" gate before-tool") ||
-    command.includes("packages/cli/bin/agent-harness.js gate before-tool")
-  );
-  const hasPostTool = commands.some((command) =>
-    command.includes("agent-harness state update") ||
-    command.includes("@brawnen/agent-harness-cli state update") ||
-    command.includes("packages/cli/bin/agent-harness.js\" state update") ||
-    command.includes("packages/cli/bin/agent-harness.js state update")
-  );
-  const hasSessionStart = commands.some((command) =>
-    command.includes("agent-harness hook claude session-start") ||
-    command.includes("@brawnen/agent-harness-cli hook claude session-start") ||
-    command.includes("packages/cli/bin/agent-harness.js\" hook claude session-start") ||
-    command.includes("packages/cli/bin/agent-harness.js hook claude session-start")
-  );
-  const hasUserPromptSubmit = commands.some((command) =>
-    command.includes("agent-harness hook claude user-prompt-submit") ||
-    command.includes("@brawnen/agent-harness-cli hook claude user-prompt-submit") ||
-    command.includes("packages/cli/bin/agent-harness.js\" hook claude user-prompt-submit") ||
-    command.includes("packages/cli/bin/agent-harness.js hook claude user-prompt-submit")
-  );
-  const hasStop = commands.some((command) =>
-    command.includes("agent-harness hook claude stop") ||
-    command.includes("@brawnen/agent-harness-cli hook claude stop") ||
-    command.includes("packages/cli/bin/agent-harness.js\" hook claude stop") ||
-    command.includes("packages/cli/bin/agent-harness.js hook claude stop")
-  );
+  const hasPreTool = hasCommandFragment(commands, [
+    "agent-harness gate before-tool",
+    "@brawnen/agent-harness-cli gate before-tool",
+    "packages/cli/bin/agent-harness.js\" gate before-tool",
+    "packages/cli/bin/agent-harness.js gate before-tool",
+    ".harness/hosts/claude/hooks/pre_tool_use.js"
+  ]);
+  const hasPostTool = hasCommandFragment(commands, [
+    "agent-harness state update",
+    "@brawnen/agent-harness-cli state update",
+    "packages/cli/bin/agent-harness.js\" state update",
+    "packages/cli/bin/agent-harness.js state update",
+    ".harness/hosts/claude/hooks/post_tool_use.js"
+  ]);
+  const hasSessionStart = hasCommandFragment(commands, [
+    "agent-harness hook claude session-start",
+    "@brawnen/agent-harness-cli hook claude session-start",
+    "packages/cli/bin/agent-harness.js\" hook claude session-start",
+    "packages/cli/bin/agent-harness.js hook claude session-start",
+    ".harness/hosts/claude/hooks/session_start.js"
+  ]);
+  const hasUserPromptSubmit = hasCommandFragment(commands, [
+    "agent-harness hook claude user-prompt-submit",
+    "@brawnen/agent-harness-cli hook claude user-prompt-submit",
+    "packages/cli/bin/agent-harness.js\" hook claude user-prompt-submit",
+    "packages/cli/bin/agent-harness.js hook claude user-prompt-submit",
+    ".harness/hosts/claude/hooks/user_prompt_submit.js"
+  ]);
+  const hasStop = hasCommandFragment(commands, [
+    "agent-harness hook claude stop",
+    "@brawnen/agent-harness-cli hook claude stop",
+    "packages/cli/bin/agent-harness.js\" hook claude stop",
+    "packages/cli/bin/agent-harness.js hook claude stop",
+    ".harness/hosts/claude/hooks/stop.js"
+  ]);
 
   if (hasSessionStart && hasUserPromptSubmit && hasPreTool && hasPostTool && hasStop) {
     return ok(".claude/settings.json", "Claude Code hooks 已配置（SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop）");
@@ -433,40 +465,45 @@ function inspectGeminiAdapter(cwd, runtimeMode, hasGeminiHost) {
     .map((hook) => hook.command)
     .filter(Boolean);
 
-  const hasSessionStart = commands.some((command) =>
-    command.includes("agent-harness hook gemini session-start") ||
-    command.includes("@brawnen/agent-harness-cli hook gemini session-start") ||
-    command.includes("packages/cli/bin/agent-harness.js\" hook gemini session-start") ||
-    command.includes("packages/cli/bin/agent-harness.js hook gemini session-start")
-  );
-  const hasBeforeAgent = commands.some((command) =>
-    command.includes("agent-harness hook gemini before-agent") ||
-    command.includes("@brawnen/agent-harness-cli hook gemini before-agent") ||
-    command.includes("packages/cli/bin/agent-harness.js\" hook gemini before-agent") ||
-    command.includes("packages/cli/bin/agent-harness.js hook gemini before-agent")
-  );
-  const hasBeforeTool = commands.some((command) =>
-    command.includes("agent-harness hook gemini before-tool") ||
-    command.includes("@brawnen/agent-harness-cli hook gemini before-tool") ||
-    command.includes("packages/cli/bin/agent-harness.js\" hook gemini before-tool") ||
-    command.includes("packages/cli/bin/agent-harness.js hook gemini before-tool")
-  );
-  const hasAfterTool = commands.some((command) =>
-    command.includes("agent-harness hook gemini after-tool") ||
-    command.includes("@brawnen/agent-harness-cli hook gemini after-tool") ||
-    command.includes("packages/cli/bin/agent-harness.js\" hook gemini after-tool") ||
-    command.includes("packages/cli/bin/agent-harness.js hook gemini after-tool")
-  );
-  const hasAfterAgent = commands.some((command) =>
-    command.includes("agent-harness hook gemini after-agent") ||
-    command.includes("@brawnen/agent-harness-cli hook gemini after-agent") ||
-    command.includes("packages/cli/bin/agent-harness.js\" hook gemini after-agent") ||
-    command.includes("packages/cli/bin/agent-harness.js hook gemini after-agent")
-  );
+  const hasSessionStart = hasCommandFragment(commands, [
+    "agent-harness hook gemini session-start",
+    "@brawnen/agent-harness-cli hook gemini session-start",
+    "packages/cli/bin/agent-harness.js\" hook gemini session-start",
+    "packages/cli/bin/agent-harness.js hook gemini session-start",
+    ".harness/hosts/gemini/hooks/session_start.js"
+  ]);
+  const hasBeforeAgent = hasCommandFragment(commands, [
+    "agent-harness hook gemini before-agent",
+    "@brawnen/agent-harness-cli hook gemini before-agent",
+    "packages/cli/bin/agent-harness.js\" hook gemini before-agent",
+    "packages/cli/bin/agent-harness.js hook gemini before-agent",
+    ".harness/hosts/gemini/hooks/before_agent.js"
+  ]);
+  const hasBeforeTool = hasCommandFragment(commands, [
+    "agent-harness hook gemini before-tool",
+    "@brawnen/agent-harness-cli hook gemini before-tool",
+    "packages/cli/bin/agent-harness.js\" hook gemini before-tool",
+    "packages/cli/bin/agent-harness.js hook gemini before-tool",
+    ".harness/hosts/gemini/hooks/before_tool.js"
+  ]);
+  const hasAfterTool = hasCommandFragment(commands, [
+    "agent-harness hook gemini after-tool",
+    "@brawnen/agent-harness-cli hook gemini after-tool",
+    "packages/cli/bin/agent-harness.js\" hook gemini after-tool",
+    "packages/cli/bin/agent-harness.js hook gemini after-tool",
+    ".harness/hosts/gemini/hooks/after_tool.js"
+  ]);
+  const hasAfterAgent = hasCommandFragment(commands, [
+    "agent-harness hook gemini after-agent",
+    "@brawnen/agent-harness-cli hook gemini after-agent",
+    "packages/cli/bin/agent-harness.js\" hook gemini after-agent",
+    "packages/cli/bin/agent-harness.js hook gemini after-agent",
+    ".harness/hosts/gemini/hooks/after_agent.js"
+  ]);
 
   const modeSummary = runtimeMode === "protocol-only"
     ? "当前为 protocol-only，但 hooks 已可用"
-    : "已检测到 .harness 运行时目录，可配合 hooks 与 CLI 做 state / verify / report";
+    : "已检测到 .harness 运行时目录，可配合 hooks 与兼容 CLI 做 state / verify / report";
 
   if (hasSessionStart && hasBeforeAgent && hasBeforeTool && hasAfterTool && hasAfterAgent) {
     return ok("Gemini adapter", `Gemini CLI hooks 已配置（SessionStart / BeforeAgent / BeforeTool / AfterTool / AfterAgent）；${modeSummary}`);
@@ -486,6 +523,10 @@ function hasCodexHookCommand(parsedHooks, eventName, commandFragment) {
     .some((hook) => typeof hook?.command === "string" && hook.command.includes(commandFragment));
 }
 
+function hasCommandFragment(commands, fragments) {
+  return commands.some((command) => fragments.some((fragment) => command.includes(fragment)));
+}
+
 function inspectRuntimeDirectories(cwd, runtimeMode) {
   if (runtimeMode === "protocol-only") {
     return skip("runtime", "protocol-only 模式，无需运行时目录");

package/src/commands/sync.js

@@ -0,0 +1,88 @@
+import { applyHostLayoutWrites, collectHostLayoutWrites, HOST_LAYOUT_HOSTS } from "../lib/host-layout.js";
+
+export function runSync(argv) {
+  const parsed = parseSyncArgs(argv);
+  if (!parsed.ok) {
+    console.error(parsed.error);
+    return 1;
+  }
+
+  const cwd = process.cwd();
+  const result = collectHostLayoutWrites(cwd, {
+    check: parsed.options.check,
+    hosts: parsed.options.hosts,
+    rewrite: parsed.options.rewrite,
+    seedMissing: true
+  });
+
+  for (const warning of result.warnings) {
+    console.error(`warn: ${warning}`);
+  }
+
+  if (parsed.options.check) {
+    if (result.warnings.length === 0 && result.writes.length === 0) {
+      console.log("host layout 已同步");
+      return 0;
+    }
+
+    for (const write of result.writes) {
+      console.log(`drift: ${write.relativePath}`);
+    }
+    return 1;
+  }
+
+  applyHostLayoutWrites(result.writes);
+
+  for (const write of result.writes) {
+    console.log(`write: ${write.relativePath}`);
+  }
+
+  if (result.warnings.length > 0) {
+    return 1;
+  }
+
+  console.log("sync 完成。");
+  return 0;
+}
+
+function parseSyncArgs(argv) {
+  const options = {
+    check: false,
+    hosts: null,
+    rewrite: false
+  };
+
+  const hosts = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--check") {
+      options.check = true;
+      continue;
+    }
+
+    if (arg === "--rewrite") {
+      options.rewrite = true;
+      continue;
+    }
+
+    if (arg === "--host") {
+      const value = argv[index + 1];
+      if (!HOST_LAYOUT_HOSTS.includes(value)) {
+        return { ok: false, error: "无效的 --host 参数。可选值: codex, claude-code, gemini-cli" };
+      }
+      hosts.push(value);
+      index += 1;
+      continue;
+    }
+
+    return { ok: false, error: `未知参数: ${arg}` };
+  }
+
+  if (hosts.length > 0) {
+    options.hosts = hosts;
+  }
+
+  return { ok: true, options };
+}