@accelerator-mzq/forge 1.4.0 → 2.0.0

package/dist/cli/commands/archive.d.ts

@@ -1,11 +1,16 @@
 import { Command } from 'commander';
+import type { SyncCheckInput } from '../../core/legacy-bridge/sync-check.js';
 export declare function buildArchiveCommand(): Command;
 /**
  * preflight 结果 union — caller 在 try 块内根据 kind 手动 release + exit,
  * 与 archive.ts 现有"business-rule fail 处理"convention 一致(line 154 / 160 等)。
  *
- * kind 'ok':可继续 archive(graceful skip 或 全过)
- * kind 'ack-missing' / 'critical-pending':caller 应 await release + exit 2
+ * kind 'ok':可继续 archive(graceful skip / 无 affected anchor / --api 跑完无 critical)
+ * kind 'ack-missing':ack 未就绪,caller 应 await release + exit 2
+ * kind 'critical-pending':**仅 --api 模式产生** —— 进程内跑 sync-check 后发现
+ *   critical pending 差异,sync-state 已写,caller 应 await release + exit 2
+ * kind 'halted-for-fulfillment':**仅 agent 模式产生** —— emit manifest +
+ *   暂停态文件已写,archive 应 halt,caller await release + exit 2
  */
 export type PreflightResult = {
     kind: 'ok';
@@ -16,29 +21,87 @@ export type PreflightResult = {
     kind: 'critical-pending';
     criticalCount: number;
     message: string;
+} | {
+    kind: 'halted-for-fulfillment';
+    message: string;
 };
 /**
- * Plan 7 §2.5:archive preflight — enforce_sync=true 时阻塞 critical 差异。
+ * Plan 7 §2.5 + Task 6.3:archive preflight — enforce_sync=true 时拦截 sync 差异。
  *
  * Graceful skip 路径(全部返 {kind:'ok'}):
  *   1. forge/config.yaml 不存在
  *   2. legacy-anchors.yaml 不存在
  *   3. legacy_bridge.allow_llm_calls != true
  *   4. legacy_bridge.enforce_sync != true
+ *   5. 无受影响 anchor / 全部读取失败(buildSyncCheckTask 返 null)
+ *
+ * 双模式(ack 就绪后):
+ *   - **agent 模式(默认,不带 --api)**:emit sync-check manifest 到 .cache +
+ *     写暂停态文件 → 返 {kind:'halted-for-fulfillment'},archive halt 等 agent fulfill。
+ *   - **--api 模式**:进程内直连 Anthropic API 跑 sync-check + 写 sync-state →
+ *     含 critical pending 返 {kind:'critical-pending'};否则返 {kind:'ok'} 续跑 archive。
  *
- * 走 LLM 路径时:
- *   - ack 不就绪 → 返 {kind:'ack-missing'}
- *   - 含 critical pending → sync-state 已写后返 {kind:'critical-pending'}
- *   - 全过 → 返 {kind:'ok'}
+ * ack 不就绪(两模式共有)→ 返 {kind:'ack-missing'}。
  *
  * **不再调 process.exit / console.error**:caller(archive 命令)负责打印消息 +
  * release archive.lock + exit,避免本函数内 process.exit 跳过 caller finally
  * 导致 archive.lock 文件残留。
  */
-export declare function runArchivePreflight(forgeRoot: string, changeId: string): Promise<PreflightResult>;
+export declare function runArchivePreflight(forgeRoot: string, changeId: string, opts?: {
+    api: boolean;
+}): Promise<PreflightResult>;
 /**
- * Plan 7 §2.5:post-archive hook — 不阻塞,仅在 enforce_sync=false 时跑(产报告)。
+ * Plan 7 §2.5 + Task 6.3:post-archive hook — 不阻塞,仅在 enforce_sync=false 时跑(产报告)。
  * enforce_sync=true 已由 preflight 跑过;graceful skip 路径同 preflight。
+ *
+ * agent 模式:emit sync-check manifest(非阻塞,archive 已完成,fulfill 后跑 --apply 出报告)。
+ * --api 模式:进程内直连 API 跑 sync-check + 写 sync-state(非阻塞,直接出报告)。
+ *
+ * I-2:archiveDate 由 archive 主流程透传(不自己算 new Date(),避免跨午夜偏一天)。
+ */
+export declare function runArchivePostHook(forgeRoot: string, changeId: string, opts: {
+    archiveDate: string;
+    api: boolean;
+}): Promise<void>;
+/**
+ * agent 模式:emit preflight sync-check manifest + 暂停态文件,halt archive(Task 6.3)。
+ *
+ * 调用前 gate 检查(config 存在 + allow_llm_calls + enforce_sync + anchors + ack)由
+ * runArchivePreflight 负责;本函数专注 emit 逻辑。
+ *
+ * @param ctx 已拼好的 SyncCheckInput(可选;不传则内部自拼,供测试直接调用)
  */
-export declare function runArchivePostHook(forgeRoot: string, changeId: string): Promise<void>;
+export declare function emitPreflightSyncCheck(forgeRoot: string, changeId: string, ctx?: SyncCheckInput): Promise<{
+    kind: 'halted-for-fulfillment' | 'skip';
+}>;
+/**
+ * agent 模式:enforce_sync=false 时 post-archive emit sync-check manifest(非阻塞,无暂停态)(Task 6.3)。
+ *
+ * archive 已完成;fulfill 后跑 forge legacy-bridge sync-check --apply 出报告。
+ * 调用前 gate 检查由 runArchivePostHook 负责。
+ *
+ * @param ctx 已拼好的 SyncCheckInput(可选;不传则内部自拼,供测试直接调用)
+ */
+export declare function emitPostHookSyncCheck(forgeRoot: string, changeId: string, ctx?: SyncCheckInput): Promise<{
+    kind: 'emitted' | 'skip';
+}>;
+/**
+ * Task 6.4:forge archive --resume 的 gate 复核。
+ *
+ * 复核两项:
+ * ① 产物绑定 — sync-state 的 produced_from 必须等于暂停态文件的 manifest_hash,
+ *              确保 sync-check --apply 产出的 sync-state 确实来自本次 preflight emit 的 manifest。
+ * ② critical 幂等重评 — sync-state 中不得有 severity=critical + status=pending 的差异;
+ *                       若有,说明 agent 未完全 resolve,不可续跑 archive。
+ *
+ * @param forgeRoot forge/ 根目录路径
+ * @param changeId  change id(e.g. 'add-pay')
+ * @returns { ok: true } 表示 gate 通过;{ ok: false, reason } 表示拒绝并附原因
+ */
+export declare function resumeArchiveGateCheck(forgeRoot: string, changeId: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
 //# sourceMappingURL=archive.d.ts.map

package/dist/cli/commands/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/archive.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuEpC,wBAAgB,mBAAmB,IAAI,OAAO,CAihB7C;AAkBD;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,CAAC,CAwF1B;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkE3F"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/archive.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAqD7E,wBAAgB,mBAAmB,IAAI,OAAO,CAglB7C;AAkBD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,GAAG,EAAE,OAAO,CAAA;CAAmB,GACtC,OAAO,CAAC,eAAe,CAAC,CAiF1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CA6Df;AA0DD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,cAAc,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,wBAAwB,GAAG,MAAM,CAAA;CAAE,CAAC,CAgCtD;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,cAAc,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAAA;CAAE,CAAC,CAevC;AA8BD;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA+DvD"}

package/dist/cli/commands/archive.js

@@ -10,7 +10,6 @@ import { existsSync, statSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
-import Anthropic from '@anthropic-ai/sdk';
 import { parseMarker } from '../../core/markers/index.js';
 import { validateMarkerSchema } from '../../core/validate/index.js';
 import { validateEvidence, validateReviewGitIntegrity, validateReviewOutcomes, } from '../../core/validate/marker-integrity.js';
@@ -22,9 +21,11 @@ import { promptRecoverChoice } from '../../core/archive/recover-prompt.js';
 import { applyDeltas } from '../../core/specs-sync/index.js';
 import { loadAnchorsFile } from '../../core/legacy-bridge/anchors.js';
 import { checkAck } from '../../core/legacy-bridge/ack.js';
-import { runSyncCheck } from '../../core/legacy-bridge/sync-check.js';
-import { renderDiffMarkdown, renderDiffYaml, hasCriticalPending, } from '../../core/legacy-bridge/diff-report.js';
+import { buildSyncCheckTask, applySyncCheckResult } from '../../core/legacy-bridge/sync-check.js';
+import { AgentHandoffRunner, ApiRunner, makeForgeApiClient, } from '../../core/legacy-bridge/runners.js';
+import { renderDiffMarkdown, renderDiffYaml } from '../../core/legacy-bridge/diff-report.js';
 import { readAnchorFile } from '../../core/legacy-bridge/encoding.js';
+import { FORGE_VERSION } from '../../index.js';
 // Task 8 (plan-9a §9): cross-cutting fence framework — 9g 实施完整 13 不变量逻辑
 import { crossCuttingFenceCheck } from '../../core/archive/fence.js';
 // plan-9d Task 6:verify_findings fence + ack-log consistency
@@ -63,12 +64,17 @@ function isProjectActuallyGit(cwd) {
     }
 }
 export function buildArchiveCommand() {
-    return new Command('archive')
+    return (new Command('archive')
         .argument('[changeId]', 'change directory id (e.g., add-login)')
         .description('Archive a verified+reviewed change')
         .option('--force', 'accept human-override or non-git review markers')
         .option('--recover', 'recover from a half-completed archive transaction')
         .option('--resume-summary <archiveId>', 'resume rename archive_summary.tmp.yaml → archive_summary.yaml (rare half-completed state, plan-9e1)')
+        // Task 6.3:--api 模式 — preflight/posthook 的 sync-check 进程内直连 API 跑完,
+        // 不 emit manifest、不写暂停态、不 halt(高保证 CI 场景绕过 agent-pause)
+        .option('--api', '直连 Anthropic API 跑 sync-check(不 emit manifest、不暂停)')
+        // Task 6.4:--resume — agent 履行 manifest 并跑 sync-check --apply 后,续跑 archive 主流程
+        .option('--resume', 'agent 履行后续跑 archive(gate 复核:produced_from 绑定 + critical 幂等重评)')
         .action(async (changeId, opts) => {
         const forgeRoot = join(process.cwd(), 'forge');
         // —— --recover 独立路径 ——
@@ -189,6 +195,28 @@ export function buildArchiveCommand() {
                     await release();
             }
         }
+        // —— Task 6.4:--resume 独立路径(agent 履行后 gate 复核 + 续跑 archive)——
+        // I-2:暂停态文件此处不删 —— 仅记下路径,延后到 archiveTransaction 成功后才删。
+        //      若 gate 通过但后续 marker check / fence / archiveTransaction 任一失败,
+        //      暂停态保留 → 用户修好后可再 `forge archive --resume` 重入(否则会因
+        //      「无暂停态文件」被拒,--resume 失去重入性陷入死角)。
+        let resumePausePath;
+        if (opts.resume) {
+            if (!changeId) {
+                console.error('✗ --resume 需要 changeId');
+                process.exit(1);
+            }
+            // gate 复核:produced_from 绑定 + critical 幂等重评
+            const gateResult = await resumeArchiveGateCheck(forgeRoot, changeId);
+            if (!gateResult.ok) {
+                console.error(`✗ --resume gate 复核失败:${gateResult.reason}`);
+                process.exit(2); // business-rule-fail
+            }
+            // gate 通过 → 记下暂停态路径(延后删),fall-through 续跑正常 archive 主流程
+            resumePausePath = join(forgeRoot, '.cache', `archive-pause-${changeId}.json`);
+            console.log(`✓ --resume gate 通过;续跑 archive ${changeId}…`);
+            // --resume 续跑后,opts.resume=true 不影响后续 opts 读取(changeId 已确认存在)
+        }
         // —— 正常 archive 路径 ——
         if (!changeId) {
             console.error('✗ changeId required (unless using --recover)');
@@ -203,11 +231,18 @@ export function buildArchiveCommand() {
             // 决策 #23:复用 archive.lock,不再 acquire legacy-bridge.lock。
             // preflight 不再 process.exit,改返 PreflightResult,caller 在 try 块内手动 release+exit
             // 与 marker check 现有 inline-release convention 一致(避免 process.exit 跳过 finally 致锁残留)
-            const preflightResult = await runArchivePreflight(forgeRoot, changeId);
-            if (preflightResult.kind !== 'ok') {
-                console.error(preflightResult.message);
-                await archiveRelease();
-                process.exit(2);
+            // Task 6.3:--api 透传 —— agent 模式 emit manifest+halt;--api 模式进程内跑 sync-check
+            // Task 6.4:--resume 时跳过 preflight — gate 复核已在 --resume 分支完成(暂停态也已清除),
+            //   再跑 preflight 会因 enforce_sync=true 再次 emit manifest + halt,造成死循环。
+            if (!opts.resume) {
+                const preflightResult = await runArchivePreflight(forgeRoot, changeId, {
+                    api: opts.api ?? false,
+                });
+                if (preflightResult.kind !== 'ok') {
+                    console.error(preflightResult.message);
+                    await archiveRelease();
+                    process.exit(2);
+                }
             }
             // plan-9g 默认开启 14 不变量 fence(brainstorm v6 删两 opt-in flag);所有 archive 调用都跑
             const fenceResult = await crossCuttingFenceCheck(join(forgeRoot, 'changes', changeId));
@@ -475,8 +510,25 @@ export function buildArchiveCommand() {
             }
             // 步骤 5:调 archiveTransaction(Move→Sync,含 .tmp 写 / rename / 回滚)
             await archiveTransaction({ forgeRoot, changeId, archiveDate, archiveSummary });
+            // I-2:archiveTransaction await 成功返回(失败会 throw 走外层 catch)即 transaction 成功点 ——
+            //      此处删 --resume 暂停态文件(正常收尾)。transaction 之前任一步失败时暂停态保留,
+            //      用户修好后可再 --resume 重入。仅 opts.resume 路径有此文件,非 resume 路径 undefined 跳过。
+            if (resumePausePath) {
+                // transaction 已成功;删暂停态失败(罕见权限错)不应让 archive 报错 —— 降级为 warn
+                try {
+                    await rm(resumePausePath, { force: true });
+                }
+                catch (e) {
+                    console.warn(`⚠ archive 已完成,但暂停态文件 ${resumePausePath} 清理失败(可手动删除):${e.message}`);
+                }
+            }
             // 步骤 5.5:Plan 7 post-archive hook(enforce_sync=false 时不阻塞,只产报告)
-            await runArchivePostHook(forgeRoot, changeId);
+            // Task 6.3 I-2:透传 archiveDate(避免 posthook 自己算 new Date() 跨午夜偏一天)
+            // Task 6.3 C-1:透传 --api
+            await runArchivePostHook(forgeRoot, changeId, {
+                archiveDate,
+                api: opts.api ?? false,
+            });
             // 步骤 6:plan-9e1 Task 4 — 渲染 archive_summary 输出(沿 design §2.4.4)
             const archiveDirName = `${archiveDate}-${changeId}`;
             console.log(renderArchiveSummaryOutput(archiveSummary, archiveDirName));
@@ -526,7 +578,7 @@ export function buildArchiveCommand() {
             if (archiveRelease)
                 await archiveRelease();
         }
-    });
+    }));
 }
 /**
  * 从 backup 目录把所有备份的 specs 文件还原到 currentSpecsDir(case C [2] 撤销归档用)。
@@ -545,24 +597,28 @@ async function restoreSpecsFromBackup(backupDir, currentSpecsDir) {
     }
 }
 /**
- * Plan 7 §2.5:archive preflight — enforce_sync=true 时阻塞 critical 差异。
+ * Plan 7 §2.5 + Task 6.3:archive preflight — enforce_sync=true 时拦截 sync 差异。
  *
  * Graceful skip 路径(全部返 {kind:'ok'}):
  *   1. forge/config.yaml 不存在
  *   2. legacy-anchors.yaml 不存在
  *   3. legacy_bridge.allow_llm_calls != true
  *   4. legacy_bridge.enforce_sync != true
+ *   5. 无受影响 anchor / 全部读取失败(buildSyncCheckTask 返 null)
+ *
+ * 双模式(ack 就绪后):
+ *   - **agent 模式(默认,不带 --api)**:emit sync-check manifest 到 .cache +
+ *     写暂停态文件 → 返 {kind:'halted-for-fulfillment'},archive halt 等 agent fulfill。
+ *   - **--api 模式**:进程内直连 Anthropic API 跑 sync-check + 写 sync-state →
+ *     含 critical pending 返 {kind:'critical-pending'};否则返 {kind:'ok'} 续跑 archive。
  *
- * 走 LLM 路径时:
- *   - ack 不就绪 → 返 {kind:'ack-missing'}
- *   - 含 critical pending → sync-state 已写后返 {kind:'critical-pending'}
- *   - 全过 → 返 {kind:'ok'}
+ * ack 不就绪(两模式共有)→ 返 {kind:'ack-missing'}。
  *
  * **不再调 process.exit / console.error**:caller(archive 命令)负责打印消息 +
  * release archive.lock + exit,避免本函数内 process.exit 跳过 caller finally
  * 导致 archive.lock 文件残留。
  */
-export async function runArchivePreflight(forgeRoot, changeId) {
+export async function runArchivePreflight(forgeRoot, changeId, opts = { api: false }) {
     const configPath = join(forgeRoot, 'config.yaml');
     if (!existsSync(configPath))
         return { kind: 'ok' };
@@ -582,61 +638,60 @@ export async function runArchivePreflight(forgeRoot, changeId) {
             message: `legacy_bridge.enforce_sync=true 但 ack 未就绪:${ack.reason};请先跑 forge legacy-bridge --acknowledge-data-transfer`,
         };
     }
-    // 拼 change context(同 sync-check 命令)
-    const changesDir = join(forgeRoot, 'changes', changeId);
-    let changeContext = '';
-    const affectedModules = [];
-    if (existsSync(join(changesDir, 'proposal.md'))) {
-        changeContext += await readFile(join(changesDir, 'proposal.md'), 'utf8');
-    }
-    const specsDir = join(changesDir, 'specs');
-    if (existsSync(specsDir)) {
-        const files = await readdir(specsDir);
-        for (const f of files) {
-            changeContext += `\n## specs/${f}\n${await readFile(join(specsDir, f), 'utf8')}`;
-            affectedModules.push(f.replace(/\.md$/, ''));
+    // 拼 change context(I-3:gate 已加载的 config + anchors 传入,不再二次 IO)
+    // preflight 时 change 还在 forge/changes/<id>/(archived=false,无需 archiveDate)
+    const ctx = await buildSyncCheckChangeContext(forgeRoot, changeId, { archived: false }, config, anchors);
+    if (opts.api) {
+        // —— --api 模式:进程内直连 API 跑 sync-check,不 emit manifest、不写暂停态 ——
+        const task = await buildSyncCheckTask(ctx, async (p) => (await readAnchorFile(p)).text);
+        if (!task)
+            return { kind: 'ok' }; // 无受影响 anchor → 无需 sync-check,续跑 archive
+        // 进程内调 Anthropic SDK(client 构造方式与旧 archive 代码一致:forge-eval/load-env)
+        const client = (await makeForgeApiClient());
+        const results = await new ApiRunner(client).run([task]);
+        // --api 无 manifest,produced_from 标 'api-inline' sentinel(区别于 agent 路径的 manifest_hash;
+        // 该 sync-state 不经 resume gate,Task 6.4 据此 sentinel 可识别 --api 来源)
+        const syncState = applySyncCheckResult(results[0]?.text ?? '', changeId, 'api-inline');
+        // 写 sync-state 到旧路径(沿旧 preflight 写盘方式)
+        await mkdir(join(forgeRoot, 'legacy-sync-state'), { recursive: true });
+        await writeFile(join(forgeRoot, 'legacy-sync-state', `${changeId}.md`), renderDiffMarkdown(syncState), 'utf8');
+        await writeFile(join(forgeRoot, 'legacy-sync-state', `${changeId}.yaml`), renderDiffYaml(syncState), 'utf8');
+        // 含 critical pending → critical-pending(死变体的归宿:archive 主流程 kind!=='ok' 会 halt)
+        const criticalDiffs = syncState.diffs.filter((d) => d.severity === 'critical' && d.status === 'pending');
+        if (criticalDiffs.length > 0) {
+            return {
+                kind: 'critical-pending',
+                criticalCount: criticalDiffs.length,
+                message: `✗ ${criticalDiffs.length} 项 critical 差异未 resolve;\n` +
+                    `跑 forge legacy-bridge resolve ${changeId} 后重试,或在 forge/legacy-sync-state/${changeId}.yaml 标 ack`,
+            };
         }
+        return { kind: 'ok' };
     }
-    // 跑 sync-check(决策 #23:复用 archive.lock,不再 acquire legacy-bridge.lock)
-    // 运行时动态加载 forge-eval/load-env(避免 src/ rootDir 静态分析边界限制)
-    const evalLoadEnvPath = new URL('../../../forge-eval/load-env.js', import.meta.url).href;
-    const { loadEnv } = (await import(/* @vite-ignore */ evalLoadEnvPath));
-    const { anthropicApiKey } = loadEnv();
-    const client = new Anthropic({ apiKey: anthropicApiKey });
-    const out = await runSyncCheck(client, {
-        changeId,
-        changeContext,
-        affectedModules,
-        anchors,
-        autoResolveCrossAnchor: config.legacy_bridge.auto_resolve_cross_anchor ?? false,
-        mtimeOf: (p) => {
-            try {
-                return Math.floor(statSync(p).mtimeMs / 1000);
-            }
-            catch {
-                return 0;
-            }
-        },
-    }, async (path) => (await readAnchorFile(path)).text);
-    await mkdir(join(forgeRoot, 'legacy-sync-state'), { recursive: true });
-    await writeFile(join(forgeRoot, 'legacy-sync-state', `${changeId}.md`), renderDiffMarkdown(out.syncState), 'utf8');
-    await writeFile(join(forgeRoot, 'legacy-sync-state', `${changeId}.yaml`), renderDiffYaml(out.syncState), 'utf8');
-    if (hasCriticalPending(out.syncState)) {
-        const criticalCount = out.syncState.diffs.filter((d) => d.severity === 'critical' && d.status === 'pending').length;
-        return {
-            kind: 'critical-pending',
-            criticalCount,
-            message: `✗ ${criticalCount} 项 critical 差异未 resolve;\n` +
-                `跑 forge legacy-bridge resolve ${changeId} 后重试,或在 forge/legacy-sync-state/${changeId}.yaml 标 ack`,
-        };
+    // —— agent 模式(默认):emit sync-check manifest + 写暂停态文件,halt archive ——
+    const emitResult = await emitPreflightSyncCheck(forgeRoot, changeId, ctx);
+    if (emitResult.kind === 'skip') {
+        // 无受影响 anchor / 全部读取失败 → graceful skip,继续 archive
+        return { kind: 'ok' };
     }
-    return { kind: 'ok' };
+    // halted-for-fulfillment:manifest 已写,暂停态已写,告知 caller halt
+    return {
+        kind: 'halted-for-fulfillment',
+        message: `sync-check manifest 已 emit(preflight);\n` +
+            `forge agent 履行后跑 forge legacy-bridge sync-check --apply --change-id ${changeId};\n` +
+            `暂停态文件:forge/.cache/archive-pause-${changeId}.json`,
+    };
 }
 /**
- * Plan 7 §2.5:post-archive hook — 不阻塞,仅在 enforce_sync=false 时跑(产报告)。
+ * Plan 7 §2.5 + Task 6.3:post-archive hook — 不阻塞,仅在 enforce_sync=false 时跑(产报告)。
  * enforce_sync=true 已由 preflight 跑过;graceful skip 路径同 preflight。
+ *
+ * agent 模式:emit sync-check manifest(非阻塞,archive 已完成,fulfill 后跑 --apply 出报告)。
+ * --api 模式:进程内直连 API 跑 sync-check + 写 sync-state(非阻塞,直接出报告)。
+ *
+ * I-2:archiveDate 由 archive 主流程透传(不自己算 new Date(),避免跨午夜偏一天)。
  */
-export async function runArchivePostHook(forgeRoot, changeId) {
+export async function runArchivePostHook(forgeRoot, changeId, opts) {
     const configPath = join(forgeRoot, 'config.yaml');
     if (!existsSync(configPath))
         return;
@@ -651,27 +706,76 @@ export async function runArchivePostHook(forgeRoot, changeId) {
     const ack = await checkAck(forgeRoot, config, anchors);
     if (!ack.ok)
         return; // ack 不就绪 → graceful skip
-    // 跑 sync-check 但不阻塞
-    const changesDir = join(forgeRoot, 'changes', 'archive', `${new Date().toISOString().slice(0, 10)}-${changeId}`);
-    const proposalPath = existsSync(join(changesDir, 'proposal.md'))
-        ? join(changesDir, 'proposal.md')
-        : join(forgeRoot, 'changes', changeId, 'proposal.md');
-    let changeContext = '';
-    if (existsSync(proposalPath)) {
-        changeContext = await readFile(proposalPath, 'utf8');
+    // 拼 change context(I-3:gate 已加载的 config + anchors 传入;I-2:archiveDate 透传)
+    // posthook 时 change 已归档到 archive/<archiveDate>-<id>/
+    const ctx = await buildSyncCheckChangeContext(forgeRoot, changeId, { archived: true, archiveDate: opts.archiveDate }, config, anchors);
+    if (opts.api) {
+        // —— --api 模式:进程内直连 API 跑 sync-check + 写 sync-state(非阻塞)——
+        // archive transaction 已完成;posthook 的 API 调用失败不应让 archive 报 exit 1 ——
+        // I-A:整段包 try/catch,失败降级为 warn(agent 模式 posthook 只写本地文件无此风险)
+        try {
+            const task = await buildSyncCheckTask(ctx, async (p) => (await readAnchorFile(p)).text);
+            if (!task)
+                return; // 无受影响 anchor → graceful skip
+            const client = (await makeForgeApiClient());
+            const results = await new ApiRunner(client).run([task]);
+            const syncState = applySyncCheckResult(results[0]?.text ?? '', changeId, 'api-inline');
+            await mkdir(join(forgeRoot, 'legacy-sync-state'), { recursive: true });
+            await writeFile(join(forgeRoot, 'legacy-sync-state', `${changeId}.md`), renderDiffMarkdown(syncState), 'utf8');
+            await writeFile(join(forgeRoot, 'legacy-sync-state', `${changeId}.yaml`), renderDiffYaml(syncState), 'utf8');
+            console.log(`⚠ ${syncState.diffs.length} 项老文档可能需更新,详见 forge/legacy-sync-state/${changeId}.md`);
+        }
+        catch (e) {
+            console.warn(`⚠ --api sync-check(posthook)失败,已跳过(archive 已完成):${e.message}`);
+        }
+        return;
     }
+    // —— agent 模式(默认):emit sync-check manifest(非阻塞,archive 已完成)——
+    const emitResult = await emitPostHookSyncCheck(forgeRoot, changeId, ctx);
+    if (emitResult.kind === 'emitted') {
+        console.log(`⚠ sync-check manifest 已 emit(posthook);forge agent 履行后跑 forge legacy-bridge sync-check --apply --change-id ${changeId} 可得报告`);
+    }
+    // kind='skip':无受影响 anchor / 全部读取失败 → graceful skip,无输出
+}
+/**
+ * 抽出:合并 runArchivePreflight/runArchivePostHook 两处重复的 change context 拼装。
+ *
+ * archived=false → forge/changes/<id>/;
+ * archived=true  → forge/changes/archive/<archiveDate>-<id>/。
+ *
+ * I-3:config 与 anchors 由调用方(preflight/posthook 的 gate 处)已加载并传入,
+ *      本函数不再二次 readFile/loadAnchorsFile —— 消除 double-IO + 避免
+ *      loadAnchorsFile 损坏时裸抛 LegacyAnchorsError 穿透成 unhandled rejection。
+ * I-2:archived=true 时用调用方透传的 archiveDate(archive 主流程算出的那个),
+ *      不再 new Date() —— 避免 archive 跨午夜完成时目录名偏一天致静默 skip。
+ */
+async function buildSyncCheckChangeContext(forgeRoot, changeId, opts, config, anchors) {
+    // 决定 change 目录:归档后在 archive/<archiveDate>-<id>/,归档前在 changes/<id>/
+    // archived=true 时 archiveDate 必传(由 posthook 透传 archive 主流程算出的值)
+    const changesDir = opts.archived && opts.archiveDate
+        ? join(forgeRoot, 'changes', 'archive', `${opts.archiveDate}-${changeId}`)
+        : join(forgeRoot, 'changes', changeId);
+    let changeContext = '';
     const affectedModules = [];
-    // 简化:从 changeId 推测 module(占位,真实环境靠 specs/<area>.md)
-    const evalLoadEnvPath = new URL('../../../forge-eval/load-env.js', import.meta.url).href;
-    const { loadEnv } = (await import(/* @vite-ignore */ evalLoadEnvPath));
-    const { anthropicApiKey } = loadEnv();
-    const client = new Anthropic({ apiKey: anthropicApiKey });
-    const out = await runSyncCheck(client, {
+    // 读 proposal.md
+    if (existsSync(join(changesDir, 'proposal.md'))) {
+        changeContext += await readFile(join(changesDir, 'proposal.md'), 'utf8');
+    }
+    // 读 specs/ 下各 .md,拼 changeContext + 收集 affectedModules
+    const specsDir = join(changesDir, 'specs');
+    if (existsSync(specsDir)) {
+        for (const f of await readdir(specsDir)) {
+            changeContext += `\n## specs/${f}\n${await readFile(join(specsDir, f), 'utf8')}`;
+            affectedModules.push(f.replace(/\.md$/, ''));
+        }
+    }
+    return {
         changeId,
         changeContext,
         affectedModules,
         anchors,
-        autoResolveCrossAnchor: config.legacy_bridge.auto_resolve_cross_anchor ?? false,
+        autoResolveCrossAnchor: config.legacy_bridge?.auto_resolve_cross_anchor ?? false,
+        // mtime 提供者:用于 cross-anchor 决策
         mtimeOf: (p) => {
             try {
                 return Math.floor(statSync(p).mtimeMs / 1000);
@@ -680,10 +784,154 @@ export async function runArchivePostHook(forgeRoot, changeId) {
                 return 0;
             }
         },
-    }, async (path) => (await readAnchorFile(path)).text);
-    await mkdir(join(forgeRoot, 'legacy-sync-state'), { recursive: true });
-    await writeFile(join(forgeRoot, 'legacy-sync-state', `${changeId}.md`), renderDiffMarkdown(out.syncState), 'utf8');
-    await writeFile(join(forgeRoot, 'legacy-sync-state', `${changeId}.yaml`), renderDiffYaml(out.syncState), 'utf8');
-    console.log(`⚠ ${out.syncState.diffs.length} 项老文档可能需更新,详见 forge/legacy-sync-state/${changeId}.md`);
+    };
+}
+/**
+ * agent 模式:emit preflight sync-check manifest + 暂停态文件,halt archive(Task 6.3)。
+ *
+ * 调用前 gate 检查(config 存在 + allow_llm_calls + enforce_sync + anchors + ack)由
+ * runArchivePreflight 负责;本函数专注 emit 逻辑。
+ *
+ * @param ctx 已拼好的 SyncCheckInput(可选;不传则内部自拼,供测试直接调用)
+ */
+export async function emitPreflightSyncCheck(forgeRoot, changeId, ctx) {
+    // ctx 未传(测试直接调用)→ 自行加载 config + anchors 拼 context
+    const syncCtx = ctx ?? (await buildSyncCheckContextStandalone(forgeRoot, changeId, false));
+    if (!syncCtx)
+        return { kind: 'skip' }; // standalone 加载失败(无 config/anchors)
+    // 构建 LlmTask(确定性 prep:findAffectedAnchors + redact)
+    const task = await buildSyncCheckTask(syncCtx, async (p) => (await readAnchorFile(p)).text);
+    // 无受影响 anchor 或全部读取失败 → graceful skip
+    if (!task)
+        return { kind: 'skip' };
+    // emit sync-check manifest 到 forge/.cache/legacy-bridge-task-sync-check.json
+    // meta 键名与 Task 6.2 runSyncCheckCommand emit 保持一致:changeId(驼峰)
+    const manifest = await new AgentHandoffRunner(forgeRoot, FORGE_VERSION).emit('sync-check', 1, [task], { gate_context: 'archive-preflight', changeId });
+    // 写暂停态文件:archive-pause-<changeId>.json
+    await mkdir(join(forgeRoot, '.cache'), { recursive: true });
+    await writeFile(join(forgeRoot, '.cache', `archive-pause-${changeId}.json`), JSON.stringify({
+        changeId,
+        paused_step: 'preflight-sync-check',
+        manifest_hash: manifest.manifest_hash,
+    }, null, 2), 'utf8');
+    return { kind: 'halted-for-fulfillment' };
+}
+/**
+ * agent 模式:enforce_sync=false 时 post-archive emit sync-check manifest(非阻塞,无暂停态)(Task 6.3)。
+ *
+ * archive 已完成;fulfill 后跑 forge legacy-bridge sync-check --apply 出报告。
+ * 调用前 gate 检查由 runArchivePostHook 负责。
+ *
+ * @param ctx 已拼好的 SyncCheckInput(可选;不传则内部自拼,供测试直接调用)
+ */
+export async function emitPostHookSyncCheck(forgeRoot, changeId, ctx) {
+    // ctx 未传(测试直接调用)→ 自行加载 config + anchors 拼 context(archived=true)
+    const syncCtx = ctx ?? (await buildSyncCheckContextStandalone(forgeRoot, changeId, true));
+    if (!syncCtx)
+        return { kind: 'skip' }; // standalone 加载失败
+    // 构建 LlmTask
+    const task = await buildSyncCheckTask(syncCtx, async (p) => (await readAnchorFile(p)).text);
+    // 无受影响 anchor → graceful skip
+    if (!task)
+        return { kind: 'skip' };
+    // emit sync-check manifest(meta 键名与 Task 6.2 一致:changeId 驼峰)
+    await new AgentHandoffRunner(forgeRoot, FORGE_VERSION).emit('sync-check', 1, [task], {
+        gate_context: 'archive-posthook',
+        changeId,
+    });
+    // 非阻塞:不写暂停态文件(archive 已完成)
+    return { kind: 'emitted' };
+}
+/**
+ * Task 6.3 I-3 配套:emitPreflightSyncCheck/emitPostHookSyncCheck 被测试直接调用
+ * (不经 runArchivePreflight/runArchivePostHook gate)时,自行加载 config + anchors。
+ *
+ * archived=true 时用「今日」作 archiveDate —— 仅 standalone 测试路径,生产路径
+ * 由 runArchivePostHook 透传准确的 archiveDate(I-2 已修主路径跨午夜 bug)。
+ *
+ * 返回 null:config 缺失 / anchors 缺失 → 调用方按 skip 处理。
+ */
+async function buildSyncCheckContextStandalone(forgeRoot, changeId, archived) {
+    const configPath = join(forgeRoot, 'config.yaml');
+    if (!existsSync(configPath))
+        return null;
+    const config = parseYaml(await readFile(configPath, 'utf8'));
+    const anchors = await loadAnchorsFile(forgeRoot).catch(() => null);
+    if (!anchors)
+        return null;
+    return buildSyncCheckChangeContext(forgeRoot, changeId, { archived, archiveDate: archived ? new Date().toISOString().slice(0, 10) : undefined }, config, anchors);
+}
+/**
+ * Task 6.4:forge archive --resume 的 gate 复核。
+ *
+ * 复核两项:
+ * ① 产物绑定 — sync-state 的 produced_from 必须等于暂停态文件的 manifest_hash,
+ *              确保 sync-check --apply 产出的 sync-state 确实来自本次 preflight emit 的 manifest。
+ * ② critical 幂等重评 — sync-state 中不得有 severity=critical + status=pending 的差异;
+ *                       若有,说明 agent 未完全 resolve,不可续跑 archive。
+ *
+ * @param forgeRoot forge/ 根目录路径
+ * @param changeId  change id(e.g. 'add-pay')
+ * @returns { ok: true } 表示 gate 通过;{ ok: false, reason } 表示拒绝并附原因
+ */
+export async function resumeArchiveGateCheck(forgeRoot, changeId) {
+    // 读暂停态文件:forge/.cache/archive-pause-<changeId>.json
+    const pausePath = join(forgeRoot, '.cache', `archive-pause-${changeId}.json`);
+    if (!existsSync(pausePath)) {
+        return {
+            ok: false,
+            reason: `无暂停态文件 archive-pause-${changeId}.json;archive 未在 preflight 暂停,无需 --resume`,
+        };
+    }
+    // 暂停态文件格式(Task 6.3 emitPreflightSyncCheck 写入):{ changeId, paused_step, manifest_hash }
+    // I-1:parse 包 try/catch —— 文件截断/手动误编辑致 JSON 损坏时转 business-fail,
+    //      用户看得出是哪个文件坏(否则裸 SyntaxError 被 action 外层兜底当未知错误)。
+    //      readFile 的 ENOENT 竞态(existsSync 后文件被删)也顺带被这层 catch 兜住,可接受。
+    let pause;
+    try {
+        pause = JSON.parse(await readFile(pausePath, 'utf8'));
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: `暂停态文件 ${pausePath} 解析失败(可能损坏):${err.message}`,
+        };
+    }
+    // 读 sync-state YAML:forge/legacy-sync-state/<changeId>.yaml
+    const statePath = join(forgeRoot, 'legacy-sync-state', `${changeId}.yaml`);
+    if (!existsSync(statePath)) {
+        return {
+            ok: false,
+            reason: `sync-state 缺失(forge/legacy-sync-state/${changeId}.yaml);请先让 agent fulfill manifest 后跑 forge legacy-bridge sync-check --apply --change-id ${changeId}`,
+        };
+    }
+    // I-1:同样包 try/catch —— sync-state YAML 损坏时转 business-fail
+    let state;
+    try {
+        state = parseYaml(await readFile(statePath, 'utf8'));
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: `sync-state 文件 ${statePath} 解析失败(可能损坏):${err.message}`,
+        };
+    }
+    // ① 产物绑定:sync-state.produced_from 必须等于暂停态的 manifest_hash
+    if (state.produced_from !== pause.manifest_hash) {
+        return {
+            ok: false,
+            reason: `produced_from(${state.produced_from ?? 'undefined'}) ≠ 暂停态 manifest_hash(${pause.manifest_hash});sync-state 非本次 --apply 产物,请重新履行 manifest 并跑 sync-check --apply`,
+        };
+    }
+    // ② critical 幂等重评:sync-state 中不得有 critical+pending 差异
+    // 注:archive.ts Task 6.3 已用内联 filter 而非 hasCriticalPending import,此处保持一致
+    const criticalPending = (state.diffs ?? []).filter((d) => d.severity === 'critical' && d.status === 'pending');
+    if (criticalPending.length > 0) {
+        return {
+            ok: false,
+            reason: `仍有 ${criticalPending.length} 项 critical 差异未 resolve;跑 forge legacy-bridge resolve ${changeId} 后重试`,
+        };
+    }
+    return { ok: true };
 }
 //# sourceMappingURL=archive.js.map