@akagilnc/pi-workflow-roles 0.1.3873 → 0.1.3884

package/dist/public-cli/option-definitions.js

@@ -552,7 +552,7 @@ const NOTARY_OPTIONS = [
     },
 ];
 const MERGER_OPTIONS = [
-    // Merger project face differs: requires an in-progress ordinary merge root.
+    // Merger project face: worktree whose Git materials are handed to the role.
     {
         id: "project",
         owner: "merger",
@@ -563,8 +563,8 @@ const MERGER_OPTIONS = [
         repeatable: false,
         form: "option",
         description: {
-            en: "Project root with one ordinary in-progress merge (defaults to cwd).",
-            zh: "已有进行中 ordinary merge 的项目根（默认 cwd）。",
+            en: "Project root whose Git merge materials are read (defaults to cwd).",
+            zh: "读取 Git merge 材料的项目根（默认 cwd）。",
         },
     },
     bindOwner("merger", SHARED_ATTACH_SEMANTICS),
@@ -1003,10 +1003,10 @@ const ROLE_COMMAND_HELP = {
     },
     merger: {
         command: "merger",
-        summary: "Resolve one ordinary merge already in conflict.",
+        summary: "Reconcile merge materials in a worktree (escalate when nothing to merge).",
         usage: ["ak-role merger [options] <instruction>"],
         examples: [
-            'ak-role merger --project /path/to/worktree "Reconcile the active merge."',
+            'ak-role merger --project /path/to/worktree "Reconcile the merge."',
         ],
     },
     inspector: {

package/dist/public-cli/run-lifecycle.js

@@ -997,7 +997,6 @@ async function loadResumableRunRecord(home, runId, authority) {
                 const d = record.derived;
                 if (typeof d.targetObjectId === "string" &&
                     typeof d.sourceObjectId === "string" &&
-                    typeof d.automaticMergeTreeId === "string" &&
                     Array.isArray(d.expectedConflictPaths) &&
                     Array.isArray(d.resolutionScope) &&
                     d.expectedConflictPaths.every((p) => typeof p === "string") &&
@@ -1005,7 +1004,6 @@ async function loadResumableRunRecord(home, runId, authority) {
                     derived = {
                         targetObjectId: d.targetObjectId,
                         sourceObjectId: d.sourceObjectId,
-                        automaticMergeTreeId: d.automaticMergeTreeId,
                         expectedConflictPaths: d.expectedConflictPaths,
                         resolutionScope: d.resolutionScope,
                     };

package/dist/role-runtime.js

@@ -1176,19 +1176,12 @@ export function createRoleRuntimeExtension(dependencies) {
                 return dependencies.loadDiaristSoul();
             },
         });
-        let sessionMergerGitState = dependencies.mergerGitState;
         const merger = createMergerRoleRuntime(roleHost, {
             async loadSoul() { if (!dependencies.loadMergerSoul)
                 throw new Error("Merger runtime dependencies are not configured"); return dependencies.loadMergerSoul(); },
             async loadInput(path) { if (!dependencies.loadMergerInput)
                 throw new Error("Merger runtime dependencies are not configured"); return dependencies.loadMergerInput(path); },
-            gitState: {
-                activeMerge() { if (!sessionMergerGitState)
-                    throw new Error("Merger runtime dependencies are not configured"); return sessionMergerGitState.activeMerge(); },
-                completedMerge(mergeCommitId, automaticMergeTreeId) { if (!sessionMergerGitState)
-                    throw new Error("Merger runtime dependencies are not configured"); return sessionMergerGitState.completedMerge(mergeCommitId, automaticMergeTreeId); },
-            },
-        }, hostActions);
+        });
         // #676 E: shared envelope owns collector lifecycle (mode/fork, tool surface,
         // event gates). Role module supplies business activate/tools/materials only.
         let activeCollector;
@@ -1468,11 +1461,6 @@ export function createRoleRuntimeExtension(dependencies) {
                 auditor,
                 diarist,
                 merger: async () => {
-                    if (dependencies.mergerGitState === undefined) {
-                        sessionMergerGitState = dependencies.createMergerGitState?.(ctx.cwd);
-                    }
-                    if (sessionMergerGitState === undefined)
-                        throw new Error("Merger runtime dependencies are not configured");
                     await merger.activate();
                 },
             };

package/extensions/role-runtime.ts

@@ -32,7 +32,6 @@ import { loadPackagedCanonicalSkillBinding } from "../src/package-resources/meth
 import { JUDGE_OUTPUT_TOOL_NAME } from "../src/package-contracts/judge-output.ts";
 import { readOAuthKeepaliveProviders } from "../src/oauth-keepalive.ts";
 import {
-  createProductionMergerGitState,
   formatNavigatorRoleHelp,
 } from "../src/role-runtime.ts";
 import { loadAuditorSoulFromSubjectInput } from "../src/auditor-soul.ts";
@@ -160,8 +159,6 @@ export default function roleRuntime(pi: ExtensionAPI): void {
     },
     loadMergerSoul: () => loadMainRoleSessionMaterials("merger"),
     loadMergerInput: async (path) => JSON.parse(await readFile(path, "utf8")),
-    createMergerGitState: (repositoryRoot) =>
-      createProductionMergerGitState(repositoryRoot),
     async loadCanonicalSkillBinding(name) {
       // Coder TDD (#109) and Reviewer code-review (#111) are package-owned.
       // Optional Fixer diagnosing-bugs is available via --skill without this binding.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.3873",
+  "version": "0.1.3884",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/souls/merger.md

@@ -2,4 +2,4 @@
 
 你是校书郎。
 
-* 只解决调用方指定、已开始的一次 Git merge 的完整冲突集，保全双方已授权意图并创建该次普通双亲 merge commit；若需新的产品或权力决定则升级，不猜测。
+* 保全双方已授权意图并完成一次普通双亲 merge commit；无进行中合并、无活可干、或需新的产品/权力决定则升级，不猜测。

package/src/merger-contracts.ts

@@ -1,28 +1,24 @@
 import { Type, type Static } from "typebox";
-import { isFullGitObjectId } from "./git-object-id.ts";
 import { exactUtf8 } from "./exact-utf8.ts";
-import { sha256Hex } from "./sha256.ts";
 import { openToolObjectFromUnion } from "./open-tool-schema.ts";
 import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.ts";
 
-const oidPattern = "^(?:[0-9a-f]{40}|[0-9a-f]{64})$";
 const materialSchema = Type.Object({ bytesBase64: Type.String(), sha256: Type.String() }, { additionalProperties: false });
 const checkSchema = Type.Object({ name: Type.String({ minLength: 1 }), argv: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }) }, { additionalProperties: false });
 export const mergerInputSchema = Type.Object({
-  version: Type.Literal(1), attemptId: Type.String({ minLength: 1 }),
-  targetObjectId: Type.String({ pattern: oidPattern }), sourceObjectId: Type.String({ pattern: oidPattern }),
+  attemptId: Type.String({ minLength: 1, description: "对账 attempt 身份（transport）" }),
+  targetObjectId: Type.String({ description: "材料：target parent OID；可空" }),
+  sourceObjectId: Type.String({ description: "材料：source parent OID；可空" }),
   materials: Type.Object({ task: materialSchema, authority: materialSchema, targetIntent: materialSchema, sourceIntent: materialSchema }, { additionalProperties: false }),
-  expectedConflictPaths: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
-  resolutionScope: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+  expectedConflictPaths: Type.Array(Type.String(), { description: "材料：当前未合并路径；可空" }),
+  resolutionScope: Type.Array(Type.String(), { description: "材料：解析范围提示；可空" }),
   authorizedChecks: Type.Array(checkSchema),
 }, { additionalProperties: false });
 const mergerOutputVariants = Type.Union([
-  Type.Object({ status: Type.Literal("completed", { description: "completed — 形状指引，非 schema 闸" }), attemptId: Type.String({ minLength: 1, description: "已受理合并 attempt 身份" }), report: Type.String({ minLength: 1, description: "如实结果报告" }), mergeCommitId: Type.String({ pattern: oidPattern, description: "已核验的完成合并 commit object ID" }) }, { additionalProperties: false }),
-  Type.Object({ status: Type.Literal("escalate", { description: "escalate — 形状指引，非 schema 闸" }), attemptId: Type.String({ minLength: 1, description: "已受理合并 attempt 身份" }), diagnosis: Type.String({ minLength: 1, description: "合并完成需升级的原因" }), report: Type.String({ minLength: 1, description: "如实结果报告" }) }, { additionalProperties: false }),
+  Type.Object({ status: Type.Literal("completed", { description: "completed — 形状指引，非 schema 闸" }), attemptId: Type.String({ minLength: 1, description: "已受理合并 attempt 身份" }), report: Type.String({ minLength: 1, description: "如实结果报告" }), mergeCommitId: Type.String({ description: "完成合并 commit object ID" }) }, { additionalProperties: false }),
+  Type.Object({ status: Type.Literal("escalate", { description: "escalate — 形状指引，非 schema 闸" }), attemptId: Type.String({ minLength: 1, description: "已受理合并 attempt 身份" }), diagnosis: Type.String({ minLength: 1, description: "合并无法或不应由本席完成的原因（含无进行中合并、无活可干、需新的产品/权力决定）" }), report: Type.String({ minLength: 1, description: "如实结果报告" }) }, { additionalProperties: false }),
 ]);
-export const mergerOutputSchema = withInfrastructureFailureDeclaration(
-  openToolObjectFromUnion(mergerOutputVariants),
-);
+export const mergerOutputSchema = withInfrastructureFailureDeclaration(openToolObjectFromUnion(mergerOutputVariants));
 
 export type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends readonly (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;
 export type MergerMaterial = DeepReadonly<Static<typeof materialSchema>>;
@@ -39,37 +35,27 @@ export class MergerInputContractError extends Error {
   constructor(message = "Merger input violates its exact contract") { super(message); this.name = "MergerInputContractError"; }
 }
 function fail(message = "Merger input violates its exact contract"): never { throw new MergerInputContractError(message); }
-function canonicalPath(path: unknown): path is string { return typeof path === "string" && path.length > 0 && !path.startsWith("/") && !path.includes("\0") && path.split("/").every(part => part !== "" && part !== "." && part !== ".."); }
-function validatePathSet(value: unknown, label: string): string[] {
-  if (!Array.isArray(value) || value.length === 0 || !value.every(canonicalPath)) fail(`Merger ${label} must be a non-empty canonical path set`);
-  return value as string[];
-}
-function validateMaterial(value: unknown, label: string): void {
-  if (!record(value) || typeof value.bytesBase64 !== "string" || typeof value.sha256 !== "string") fail(`Merger ${label} material is malformed`);
-  const bytes = Buffer.from(value.bytesBase64, "base64");
-  exactUtf8(bytes, `Merger ${label} material`);
-  if (sha256Hex(bytes) !== value.sha256) fail(`Merger ${label} material digest mismatch`);
-}
 function deepFreeze<T>(value: T): T { if (value && typeof value === "object") { for (const child of Object.values(value as object)) deepFreeze(child); Object.freeze(value); } return value; }
+const asString = (v: unknown): string => typeof v === "string" ? v : "";
+const asStringArray = (v: unknown): string[] => Array.isArray(v) ? v.filter((item): item is string => typeof item === "string") : [];
+
+function readMaterial(value: unknown, label: string): MergerMaterial {
+  if (!record(value) || typeof value.bytesBase64 !== "string") fail(`Merger ${label} material is malformed`);
+  exactUtf8(Buffer.from(value.bytesBase64, "base64"), `Merger ${label} material`);
+  return { bytesBase64: value.bytesBase64, sha256: typeof value.sha256 === "string" ? value.sha256 : "" };
+}
 
 export function validateMergerInput(value: unknown): MergerInput {
-  if (!record(value) || blank(value.attemptId) || !isFullGitObjectId(value.targetObjectId) || !isFullGitObjectId(value.sourceObjectId) || value.targetObjectId.length !== value.sourceObjectId.length) fail("Merger input has invalid identity or object ID");
-  if (!record(value.materials)) fail();
-  for (const key of ["task", "authority", "targetIntent", "sourceIntent"] as const) validateMaterial(value.materials[key], key);
-  const conflicts = validatePathSet(value.expectedConflictPaths, "expected conflict paths");
-  const scope = validatePathSet(value.resolutionScope, "resolution scope");
-  if (!conflicts.every(path => scope.includes(path))) fail("Merger resolution scope must contain the complete conflict set");
-  if (!Array.isArray(value.authorizedChecks)) fail("Merger authorized checks are malformed");
-  for (const check of value.authorizedChecks) {
-    if (!record(check) || !Array.isArray(check.argv) || check.argv.length === 0 || check.argv.some(blank)) fail("Merger authorized check is malformed");
-  }
-  return deepFreeze(structuredClone(value) as MergerInput);
+  if (!record(value) || blank(value.attemptId)) fail("Merger input requires a non-empty attemptId for accounting");
+  if (!record(value.materials)) fail("Merger materials are missing");
+  const materials = { task: readMaterial(value.materials.task, "task"), authority: readMaterial(value.materials.authority, "authority"), targetIntent: readMaterial(value.materials.targetIntent, "targetIntent"), sourceIntent: readMaterial(value.materials.sourceIntent, "sourceIntent") };
+  const authorizedChecks = Array.isArray(value.authorizedChecks) ? value.authorizedChecks.filter((check): check is Record<string, unknown> => record(check)).map(c => ({ name: asString(c.name), argv: asStringArray(c.argv).filter(a => a.trim().length > 0) })).filter(c => c.name.trim().length > 0 && c.argv.length > 0) : [];
+  return deepFreeze(structuredClone({ attemptId: (value.attemptId as string).trim(), targetObjectId: asString(value.targetObjectId), sourceObjectId: asString(value.sourceObjectId), materials, expectedConflictPaths: asStringArray(value.expectedConflictPaths), resolutionScope: asStringArray(value.resolutionScope), authorizedChecks }) as MergerInput);
 }
 
-export function validateMergerOutput(value: unknown, expectedAttemptId?: string): MergerOutput {
-  if (!record(value) || (expectedAttemptId !== undefined && value.attemptId !== expectedAttemptId)) throw new Error("合并回执 attempt 不匹配");
+export function validateMergerOutput(value: unknown): MergerOutput {
+  if (!record(value)) throw new Error("合并回执无已识别的执行判别");
   const status = typeof value.status === "string" ? value.status : undefined;
-  if (status === "completed" && isFullGitObjectId(value.mergeCommitId)) return structuredClone(value) as MergerOutput;
-  if (status === "escalate") return structuredClone(value) as MergerOutput;
+  if (status === "completed" || status === "escalate") return structuredClone(value) as MergerOutput;
   throw new Error("合并回执无已识别的执行判别");
 }

package/src/merger-git-state.ts

@@ -1,30 +1,60 @@
 import { execFile } from "node:child_process";
+import { access, readFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
 import { promisify } from "node:util";
 import { exactUtf8 } from "./exact-utf8.ts";
 import { isFullGitObjectId } from "./git-object-id.ts";
 
 const execFileAsync = promisify(execFile);
-export type ActiveMergerGitState = { targetObjectId: string; sourceObjectId: string; unmergedPaths: string[]; automaticMergeTreeId: string };
-export type CompletedMergerGitState = { mergeCommitId: string; parentObjectIds: string[]; unmergedPaths: string[]; worktreeClean: boolean; resolutionChangedPaths: string[] };
+
+export type ActiveMergerGitState = {
+  targetObjectId: string;
+  sourceObjectId: string;
+  unmergedPaths: string[];
+};
+
 export interface MergerGitState {
   activeMerge(): Promise<ActiveMergerGitState>;
-  completedMerge(mergeCommitId: string, automaticMergeTreeId: string): Promise<CompletedMergerGitState>;
 }
 
+type GitExecError = { code?: unknown };
+
 async function git(cwd: string, args: string[]): Promise<Uint8Array> {
   const { stdout } = await execFileAsync("git", args, { cwd, encoding: "buffer", maxBuffer: 16 * 1024 * 1024 });
   return new Uint8Array(stdout);
 }
+
 function line(bytes: Uint8Array, label: string): string {
   const value = exactUtf8(bytes, label).trim();
   if (!value) throw new Error(`${label} is empty`);
   return value;
 }
-function nulPaths(bytes: Uint8Array, label: string): string[] {
-  const raw = exactUtf8(bytes, label);
-  if (raw.length > 0 && !raw.endsWith("\0")) throw new Error(`${label} is not NUL terminated`);
-  return raw.split("\0").filter(Boolean).sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+
+async function pathExists(path: string): Promise<boolean> {
+  try { await access(path, fsConstants.F_OK); return true; }
+  catch (error) { if ((error as { code?: unknown }).code === "ENOENT") return false; throw error; }
+}
+
+async function requireInsideWorkTree(cwd: string): Promise<void> {
+  const stdout = await git(cwd, ["rev-parse", "--is-inside-work-tree"]);
+  if (exactUtf8(stdout, "Git worktree check").trim() !== "true") throw new Error("Assigned path is not inside a Git work tree");
+}
+
+async function tryResolveCommit(cwd: string, rev: string): Promise<string | undefined> {
+  let stdout: Uint8Array;
+  try {
+    const res = await execFileAsync("git", ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`], { cwd, encoding: "buffer", maxBuffer: 16 * 1024 * 1024 });
+    stdout = new Uint8Array(res.stdout);
+  } catch (error) {
+    if ((error as GitExecError).code === 1) return undefined;
+    throw error;
+  }
+  const oid = line(stdout, `Git ${rev}`);
+  if (!isFullGitObjectId(oid)) throw new Error(`Git ${rev} identity is unavailable or invalid`);
+  return oid;
 }
+
 async function unmerged(cwd: string): Promise<string[]> {
   const raw = exactUtf8(await git(cwd, ["ls-files", "-u", "-z"]), "Git unmerged index");
   const paths = new Set<string>();
@@ -37,40 +67,40 @@ async function unmerged(cwd: string): Promise<string[]> {
   return [...paths].sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
 }
 
+async function resolveHeadMaterial(cwd: string): Promise<string> {
+  const commit = await tryResolveCommit(cwd, "HEAD");
+  if (commit !== undefined) return commit;
+  try {
+    await execFileAsync("git", ["rev-parse", "--verify", "--quiet", "HEAD"], { cwd, encoding: "buffer", maxBuffer: 16 * 1024 * 1024 });
+  } catch (error) {
+    if ((error as GitExecError).code === 1) return "";
+    throw error;
+  }
+  throw new Error("Git HEAD identity is unavailable or invalid");
+}
+
 export function createProductionMergerGitState(repositoryRoot = process.cwd()): MergerGitState {
   return {
     async activeMerge() {
-      const targetObjectId = line(await git(repositoryRoot, ["rev-parse", "--verify", "HEAD"]), "Git HEAD");
-      let mergeHeadRaw: Uint8Array;
-      try {
-        mergeHeadRaw = await git(repositoryRoot, ["rev-parse", "--verify", "MERGE_HEAD"]);
-      } catch {
-        throw new Error("Assigned repository does not have one ordinary in-progress merge");
+      await requireInsideWorkTree(repositoryRoot);
+      const targetObjectId = await resolveHeadMaterial(repositoryRoot);
+      const mergeHeadReported = line(await git(repositoryRoot, ["rev-parse", "--git-path", "MERGE_HEAD"]), "Git MERGE_HEAD path");
+      const mergeHeadPath = isAbsolute(mergeHeadReported) ? mergeHeadReported : resolve(repositoryRoot, mergeHeadReported);
+      let sourceObjectId = "";
+      if (await pathExists(mergeHeadPath)) {
+        const raw = exactUtf8(await readFile(mergeHeadPath), "Git MERGE_HEAD");
+        const mergeHeads = raw.trim().split(/\r?\n/).map((row) => row.trim()).filter(Boolean);
+        if (mergeHeads.length === 0) throw new Error("Git MERGE_HEAD is empty");
+        if (mergeHeads.length !== 1) throw new Error("Assigned repository does not have one ordinary in-progress merge");
+        const source = mergeHeads[0]!;
+        if (!isFullGitObjectId(source)) throw new Error("Git MERGE_HEAD identity is unavailable or invalid");
+        const resolved = await tryResolveCommit(repositoryRoot, source);
+        if (resolved === undefined || (targetObjectId !== "" && resolved.length !== targetObjectId.length)) {
+          throw new Error("Git MERGE_HEAD identity is unavailable or invalid");
+        }
+        sourceObjectId = resolved;
       }
-      const mergeHeads = exactUtf8(mergeHeadRaw, "Git MERGE_HEAD").trim().split(/\r?\n/).filter(Boolean);
-      if (mergeHeads.length !== 1 || !isFullGitObjectId(targetObjectId) || !isFullGitObjectId(mergeHeads[0]) || targetObjectId.length !== mergeHeads[0]!.length) throw new Error("Assigned repository does not have one ordinary in-progress merge");
-      let automaticMergeTreeRaw: Uint8Array;
-      try {
-        automaticMergeTreeRaw = await git(repositoryRoot, ["rev-parse", "--verify", "AUTO_MERGE^{tree}"]);
-      } catch {
-        throw new Error("Git automatic merge tree identity is unavailable or invalid");
-      }
-      const automaticMergeTreeId = line(automaticMergeTreeRaw, "Git automatic merge tree");
-      if (!isFullGitObjectId(automaticMergeTreeId) || automaticMergeTreeId.length !== targetObjectId.length) throw new Error("Git automatic merge tree identity is unavailable or invalid");
-      return { targetObjectId, sourceObjectId: mergeHeads[0]!, unmergedPaths: await unmerged(repositoryRoot), automaticMergeTreeId };
-    },
-    async completedMerge(mergeCommitId, automaticMergeTreeId) {
-      if (!isFullGitObjectId(mergeCommitId) || !isFullGitObjectId(automaticMergeTreeId) || mergeCommitId.length !== automaticMergeTreeId.length) throw new Error("Merger completion object ID is invalid");
-      const identity = exactUtf8(await git(repositoryRoot, ["show", "-s", "--format=%H%x00%P", mergeCommitId]), "Git merge commit").trimEnd().split("\0");
-      if (identity.length !== 2 || identity[0] !== mergeCommitId) throw new Error("Git merge completion identity drifted");
-      const parentObjectIds = identity[1]!.split(" ").filter(Boolean);
-      const currentHead = line(await git(repositoryRoot, ["rev-parse", "--verify", "HEAD"]), "Git HEAD");
-      const status = await git(repositoryRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
-      const frozenTree = line(await git(repositoryRoot, ["rev-parse", "--verify", `${automaticMergeTreeId}^{tree}`]), "Git frozen automatic merge tree");
-      if (frozenTree !== automaticMergeTreeId) throw new Error("Git frozen automatic merge tree identity drifted");
-      const mergeTree = line(await git(repositoryRoot, ["rev-parse", "--verify", `${mergeCommitId}^{tree}`]), "Git completed merge tree");
-      const resolutionChangedPaths = nulPaths(await git(repositoryRoot, ["diff-tree", "--no-commit-id", "--name-only", "-r", "-z", "--no-renames", automaticMergeTreeId, mergeTree]), "Git resolution path delta");
-      return { mergeCommitId: currentHead, parentObjectIds, unmergedPaths: await unmerged(repositoryRoot), worktreeClean: status.byteLength === 0 && currentHead === mergeCommitId, resolutionChangedPaths };
+      return { targetObjectId, sourceObjectId, unmergedPaths: await unmerged(repositoryRoot) };
     },
   };
 }

package/src/merger-role.ts

@@ -1,58 +1,62 @@
-import type { RoleHost, HostContext, HostToolResult } from "./host-contracts.ts";
-import { MERGER_ACCEPTED_TEXT, MERGER_OUTPUT_TOOL_NAME, mergerOutputSchema, validateMergerInput, validateMergerOutput, type MergerInput } from "./merger-contracts.ts";
-import type { MergerGitState } from "./merger-git-state.ts";
+import type { RoleHost, HostContext } from "./host-contracts.ts";
+import {
+  MERGER_ACCEPTED_TEXT,
+  MERGER_OUTPUT_TOOL_NAME,
+  mergerOutputSchema,
+  validateMergerInput,
+  type MergerInput,
+} from "./merger-contracts.ts";
 import { exactUtf8 } from "./exact-utf8.ts";
-import { isFullGitObjectId } from "./git-object-id.ts";
 
 export { MERGER_OUTPUT_TOOL_NAME };
-export const MERGER_INPUT_FLAG = { name: "ak-merger-input", definition: { description: "Path to an immutable digest-bound Merger v1 input JSON file", type: "string" as const } } as const;
-export type MergerRoleDependencies = { loadSoul(): Promise<string>; loadInput(path: string): Promise<unknown>; gitState: MergerGitState };
-export type MergerRoleHostActions = { failInfrastructure(error: unknown, ctx: HostContext, toolCallId?: string): never };
+export const MERGER_INPUT_FLAG = { name: "ak-merger-input", definition: { description: "Path to Merger assignment materials JSON", type: "string" as const } } as const;
 
-function same(a: readonly string[], b: readonly string[]): boolean { return a.length === b.length && a.every((value, i) => value === b[i]); }
-function materialText(input: MergerInput, key: keyof MergerInput["materials"]): string { return exactUtf8(Buffer.from(input.materials[key].bytesBase64, "base64"), `Merger ${key}`); }
+export type MergerRoleDependencies = { loadSoul(): Promise<string>; loadInput(path: string): Promise<unknown>; };
 
-export function createMergerRoleRuntime(pi: RoleHost, dependencies: MergerRoleDependencies, host: MergerRoleHostActions) {
-  let activation: { soul: string; input: Readonly<MergerInput>; automaticMergeTreeId: string } | undefined;
+function materialText(input: MergerInput, key: keyof MergerInput["materials"]): string {
+  return exactUtf8(Buffer.from(input.materials[key].bytesBase64, "base64"), `Merger ${key}`);
+}
+
+/**
+ * Merger (校书郎) role runtime.
+ * Code admits one submission and terminates the round (第 0 条).
+ * Git state / completion verification are not attendance or rejection gates (#827).
+ */
+export function createMergerRoleRuntime(pi: RoleHost, dependencies: MergerRoleDependencies) {
+  let activation: { soul: string; input: Readonly<MergerInput> } | undefined;
   let registered = false;
   let accepted = false;
   pi.registerFlag(MERGER_INPUT_FLAG.name, MERGER_INPUT_FLAG.definition);
-  return { async activate() {
-    const path = pi.getFlag(MERGER_INPUT_FLAG.name);
-    if (typeof path !== "string" || path.trim().length === 0) throw new Error("Merger requires --ak-merger-input");
-    const soul = (await dependencies.loadSoul()).trim(); if (!soul) throw new Error("Merger soul is empty");
-    const input = validateMergerInput(await dependencies.loadInput(path));
-    const state = await dependencies.gitState.activeMerge();
-    if (state.targetObjectId !== input.targetObjectId || state.sourceObjectId !== input.sourceObjectId || !same(state.unmergedPaths, input.expectedConflictPaths) || state.unmergedPaths.length === 0 || !isFullGitObjectId(state.automaticMergeTreeId) || state.automaticMergeTreeId.length !== input.targetObjectId.length) throw new Error("Merger activation rejected repository parent, merge, automatic-result, or complete conflict-set drift");
-    activation = { soul, input, automaticMergeTreeId: state.automaticMergeTreeId }; accepted = false;
-    if (!registered) { registered = true;
-      pi.registerTool({ name: MERGER_OUTPUT_TOOL_NAME, label: "合并输出", description: "提交合并结果；输出分支为 completed 与 escalate；基础设施及 Git 失败由 abort 通道承接。", promptSnippet: "提交合并结果", parameters: mergerOutputSchema,
-        async execute(id: string, params: unknown, _signal: AbortSignal | undefined, _update: unknown, ctx: HostContext) {
+  return {
+    async activate() {
+      const path = pi.getFlag(MERGER_INPUT_FLAG.name);
+      if (typeof path !== "string" || path.trim().length === 0) throw new Error("Merger requires --ak-merger-input");
+      const soul = (await dependencies.loadSoul()).trim();
+      if (!soul) throw new Error("Merger soul is empty");
+      const input = validateMergerInput(await dependencies.loadInput(path));
+      activation = { soul, input };
+      accepted = false;
+      if (!registered) {
+        registered = true;
+        pi.registerTool({
+          name: MERGER_OUTPUT_TOOL_NAME, label: "合并输出", description: "提交合并结果；输出分支为 completed 与 escalate。", promptSnippet: "提交合并结果", parameters: mergerOutputSchema,
+          async execute(_id: string, params: unknown, _signal: AbortSignal | undefined, _update: unknown, _ctx: HostContext) {
+            if (!activation) throw new Error("校书郎未激活");
+            if (accepted) throw new Error("合并回执已受理");
+            accepted = true;
+            return { content: [{ type: "text" as const, text: MERGER_ACCEPTED_TEXT }], details: params, terminate: true as const };
+          },
+        });
+        pi.on("before_agent_start", (event) => {
           if (!activation) throw new Error("校书郎未激活");
-          if (accepted) throw new Error("合并回执已受理");
-          let output;
-          try {
-            output = validateMergerOutput(params, activation.input.attemptId);
-          } catch (error) {
-            host.failInfrastructure(error, ctx, id);
-          }
-          if (output.status === "completed") {
-            let state;
-            try { state = await dependencies.gitState.completedMerge(output.mergeCommitId, activation.automaticMergeTreeId); }
-            catch (error) { host.failInfrastructure(error, ctx, id); }
-            const scope = new Set(activation.input.resolutionScope);
-            if (state.mergeCommitId !== output.mergeCommitId || !same(state.parentObjectIds, [activation.input.targetObjectId, activation.input.sourceObjectId]) || state.unmergedPaths.length !== 0 || !state.worktreeClean || state.resolutionChangedPaths.some(path => !scope.has(path))) host.failInfrastructure(new Error("Merger completed-state verification failed"), ctx, id);
-          }
-          accepted = true;
-          const acceptedDetails = output;
-          return { content: [{ type: "text" as const, text: MERGER_ACCEPTED_TEXT }], details: acceptedDetails, terminate: true as const };
-        } });
-      pi.on("before_agent_start", (event) => { if (!activation) throw new Error("校书郎未激活"); const admitted = { attemptId: activation.input.attemptId, targetObjectId: activation.input.targetObjectId, sourceObjectId: activation.input.sourceObjectId, task: materialText(activation.input, "task"), authority: materialText(activation.input, "authority"), targetIntent: materialText(activation.input, "targetIntent"), sourceIntent: materialText(activation.input, "sourceIntent"), expectedConflictPaths: activation.input.expectedConflictPaths, resolutionScope: activation.input.resolutionScope, authorizedChecks: activation.input.authorizedChecks }; return { systemPrompt: `${event.systemPrompt}\n\n<merger_soul>\n${activation.soul}\n</merger_soul>\n\n<merger_assignment>\n${JSON.stringify(admitted)}\n</merger_assignment>` }; });
-    }
-    // Host-neutral AK output only (ADR 0018 fail-closed); no host-builtin name hard-require.
-    const all = pi.getAllTools().map(tool => tool.name);
-    if (all.filter(item => item === MERGER_OUTPUT_TOOL_NAME).length !== 1) {
-      throw new Error(`Merger required tool collision or missing: ${MERGER_OUTPUT_TOOL_NAME}`);
-    }
-  } };
+          const admitted = { attemptId: activation.input.attemptId, targetObjectId: activation.input.targetObjectId, sourceObjectId: activation.input.sourceObjectId, task: materialText(activation.input, "task"), authority: materialText(activation.input, "authority"), targetIntent: materialText(activation.input, "targetIntent"), sourceIntent: materialText(activation.input, "sourceIntent"), expectedConflictPaths: activation.input.expectedConflictPaths, resolutionScope: activation.input.resolutionScope, authorizedChecks: activation.input.authorizedChecks };
+          return { systemPrompt: `${event.systemPrompt}\n\n<merger_soul>\n${activation.soul}\n</merger_soul>\n\n<merger_assignment>\n${JSON.stringify(admitted)}\n</merger_assignment>` };
+        });
+      }
+      const all = pi.getAllTools().map((tool) => tool.name);
+      if (all.filter((item) => item === MERGER_OUTPUT_TOOL_NAME).length !== 1) {
+        throw new Error(`Merger required tool collision or missing: ${MERGER_OUTPUT_TOOL_NAME}`);
+      }
+    },
+  };
 }

package/src/public-cli/invocation.ts

@@ -211,11 +211,10 @@ export type AdmittedReviewerInvocation = AdmittedRoleInvocationBase & {
   readonly authorityRefs: readonly string[];
 };
 
-/** Mechanical envelope derived from the active ordinary two-parent merge. */
+/** Mechanical materials read from current Git state (may be empty). */
 export type DerivedMergerEnvelope = {
   readonly targetObjectId: string;
   readonly sourceObjectId: string;
-  readonly automaticMergeTreeId: string;
   readonly expectedConflictPaths: readonly string[];
   readonly resolutionScope: readonly string[];
 };
@@ -810,17 +809,6 @@ export type ParseAnalystArgvResult =
   | ParseAnalystSweepArgv
   | ParseAnalystCohortArgv;
 
-/** Honest activation-class failure while deriving the active-merge envelope. */
-export class MergerEnvelopeDerivationError extends Error {
-  readonly code = "merger-envelope-derivation" as const;
-  /** Typed cause for #107 classifyPostAdmissionFailure (isTypedActivationError). */
-  readonly knownCause = "activation" as const;
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message, options);
-    this.name = "MergerEnvelopeDerivationError";
-  }
-}
-
 /** Reject missing/blank path values so empty overrides cannot silently degrade. */
 function requireOptionPath(
   flag: string,
@@ -2868,7 +2856,7 @@ export function parseMergerArgv(args: readonly string[]): ParseMergerArgvResult
       token.startsWith("--resolutionScope=")
     ) {
       throw new CliUsageError(
-        "merger does not accept public packet fields; the adapter derives the active-merge envelope",
+        "merger does not accept public packet fields; the adapter reads Git merge materials",
       );
     }
     if (token.startsWith("-") && token !== "-") {
@@ -2894,36 +2882,20 @@ function mergerMaterialFromUtf8(text: string): MergerInput["materials"]["task"]
 }
 
 /**
- * Derive the mechanical Merger envelope from an already-active ordinary merge.
- * Uses the production Git seam (HEAD, sole MERGE_HEAD, AUTO_MERGE, unmerged set).
- * Failures are activation-class facts — not CLI semantic guesses.
+ * Read merger materials from current Git state.
+ * No in-progress merge / empty conflict set still yields materials (possibly empty);
+ * code does not gate attendance on merge state (#827).
  */
 export async function deriveMergerEnvelopeFromActiveMerge(
   projectRoot: string,
   gitState: MergerGitState = createProductionMergerGitState(projectRoot),
 ): Promise<DerivedMergerEnvelope> {
-  let state;
-  try {
-    state = await gitState.activeMerge();
-  } catch (error) {
-    const message =
-      error instanceof Error && error.message.trim() !== ""
-        ? error.message
-        : "Assigned repository does not have one ordinary in-progress merge";
-    throw new MergerEnvelopeDerivationError(message, { cause: error });
-  }
-  if (state.unmergedPaths.length === 0) {
-    throw new MergerEnvelopeDerivationError(
-      "Assigned repository does not have one ordinary in-progress merge with a complete conflict set",
-    );
-  }
+  const state = await gitState.activeMerge();
   const expectedConflictPaths = Object.freeze([...state.unmergedPaths]);
-  // Scope is derived as the complete conflict set; the role may not broaden it.
   const resolutionScope = Object.freeze([...state.unmergedPaths]);
   return Object.freeze({
     targetObjectId: state.targetObjectId,
     sourceObjectId: state.sourceObjectId,
-    automaticMergeTreeId: state.automaticMergeTreeId,
     expectedConflictPaths,
     resolutionScope,
   });
@@ -2945,8 +2917,9 @@ export type AdmitMergerInvocationOptions = {
 
 /**
  * Admit a Merger Role run on the common Invocation request.
- * Mechanical envelope (parents, AUTO_MERGE, conflicts, scope) is derived from
- * the active merge — callers never supply public packet fields for those facts.
+ * Git materials (parents, conflicts, scope) are read from the worktree and
+ * handed to the role as assignment materials — including when empty (#827).
+ * Callers never supply public packet fields for those facts.
  */
 export async function admitMergerInvocation(
   options: AdmitMergerInvocationOptions,
@@ -2960,8 +2933,6 @@ export async function admitMergerInvocation(
   }
 
   const projectRoot = resolve(options.project ?? options.cwd);
-  // Derive mechanical envelope before placing a run identity so no-merge/drift
-  // fails honestly without orphan ledger rows or guessed packet fields.
   const derived = await deriveMergerEnvelopeFromActiveMerge(
     projectRoot,
     options.gitState ?? createProductionMergerGitState(projectRoot),
@@ -2988,18 +2959,18 @@ export async function admitMergerInvocation(
   const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
 
   // Intent materials seed primary-source investigation; the method owns the work.
+  const targetLabel = derived.targetObjectId === "" ? "(none observed)" : derived.targetObjectId;
+  const sourceLabel = derived.sourceObjectId === "" ? "(none observed)" : derived.sourceObjectId;
   const targetIntent = mergerMaterialFromUtf8(
-    `Investigate primary sources for target parent ${derived.targetObjectId}. Do not invent intent.`,
+    `Investigate primary sources for target parent ${targetLabel}. Do not invent intent.`,
   );
   const sourceIntent = mergerMaterialFromUtf8(
-    `Investigate primary sources for source parent ${derived.sourceObjectId}. Do not invent intent.`,
+    `Investigate primary sources for source parent ${sourceLabel}. Do not invent intent.`,
   );
   const taskMaterial = mergerMaterialFromUtf8(instruction);
   const authorityMaterial = mergerMaterialFromUtf8(instruction);
 
-  // Validate merger envelope before placing admitted identity.
   const mergerInput = validateMergerInput({
-    version: 1,
     attemptId: runId,
     targetObjectId: derived.targetObjectId,
     sourceObjectId: derived.sourceObjectId,
@@ -3011,7 +2982,6 @@ export async function admitMergerInvocation(
     },
     expectedConflictPaths: [...derived.expectedConflictPaths],
     resolutionScope: [...derived.resolutionScope],
-    // Authorized checks remain available on the assignment; default none.
     authorizedChecks: [],
   });
 
@@ -3035,7 +3005,6 @@ export async function admitMergerInvocation(
     derived: {
       targetObjectId: derived.targetObjectId,
       sourceObjectId: derived.sourceObjectId,
-      automaticMergeTreeId: derived.automaticMergeTreeId,
       expectedConflictPaths: [...derived.expectedConflictPaths],
       resolutionScope: [...derived.resolutionScope],
     },