@akagilnc/pi-workflow-roles 0.1.3837 → 0.1.3884

package/src/host-descriptions.ts

@@ -68,6 +68,7 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
 /**
  * Headless CLI family (#645). Claude is the first row; codex (#646) adds another.
  * fixedArgs: print mode, isolation without `--bare` (OAuth stays), full permissions.
+ * stream-json + verbose: live host events for sitian records (#811); result is last line.
  * `--setting-sources` empty = load no user/project/local CLAUDE.md/hooks/skills
  * (role envelope is delivered via `--system-prompt` wholesale replace).
  * `--strict-mcp-config` with no `--mcp-config` drops operator MCP + claude.ai connectors.
@@ -77,8 +78,10 @@ export const HEADLESS_HOST_DESCRIPTIONS: Readonly<Record<string, HeadlessHostDes
     binaryFromHome: Object.freeze([".local", "bin", "claude"]),
     sessionBindingFile: "claude-headless-session.json",
     fixedArgs: Object.freeze([
-      // One result envelope (not stream-json): typed receipt only; no event-stream copy.
-      "--output-format", "json",
+      // Live NDJSON events → sitian host-session records (#811); last line is the result receipt.
+      "--output-format", "stream-json",
+      // Intermediate assistant/tool/system events require verbose with stream-json.
+      "--verbose",
       "--permission-mode", "bypassPermissions",
       // Empty sources: no user/project/local operator surface (envelope owns materials).
       "--setting-sources", "",

package/src/host-session-record.ts

@@ -0,0 +1,41 @@
+/**
+ * Non-pi host turn events → sitian sole entry (ADR 0065 / 0077 / #811).
+ * Adapters capture host-native structured events; this helper only packages
+ * the common sitianReport call. session.jsonl stays header-only (#617 DK-4).
+ * Write failures propagate (SitianInfrastructureError) — not best-effort.
+ */
+import { sitianReport } from "./sitian-facade.ts";
+
+/** Volume category under `<run>/session/<kind>/records.jsonl`. */
+export const HOST_SESSION_RECORD_KIND = "host-session" as const;
+
+function eventField(event: unknown, key: string): string | undefined {
+  if (typeof event !== "object" || event === null || Array.isArray(event)) return undefined;
+  const value = (event as Record<string, unknown>)[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/** Live write of one host-emitted structured event. Throws on sitian persistence failure. */
+export function reportHostSessionEvent(input: {
+  readonly host: string;
+  readonly cwd: string;
+  readonly sessionParent: string;
+  readonly source: string;
+  readonly event: unknown;
+  readonly identity?: string;
+  readonly timestamp?: string;
+}): void {
+  const identity = input.identity ?? eventField(input.event, "uuid");
+  const timestamp = input.timestamp ?? eventField(input.event, "timestamp");
+  sitianReport({
+    level: "event",
+    kind: HOST_SESSION_RECORD_KIND,
+    host: input.host,
+    cwd: input.cwd,
+    sessionParent: input.sessionParent,
+    source: input.source,
+    payload: input.event,
+    ...(identity === undefined ? {} : { identity }),
+    ...(timestamp === undefined ? {} : { timestamp }),
+  });
+}

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/pi/role-turn-host.ts

@@ -15,7 +15,6 @@ import type {
   DurablePrincipal,
   DurablePrincipalAuthority,
   MethodBinding,
-  RoleTurnActivation,
   RoleTurnHost,
   RoleTurnKnownFailure,
   RoleTurnModelConfig,
@@ -24,6 +23,7 @@ import type {
 } from "../host-contracts.ts";
 import { ExplicitInternalActivationError } from "../host-contracts.ts";
 import { applyEngineChildEnv } from "../engine-detour.ts";
+import { projectActivationFlags } from "../role-activation-flags.ts";
 
 
 /** Package-relative Internal role entrypoint (ADR 0052; same path as public-cli registry). */
@@ -66,95 +66,18 @@ function buildSeatModelCliArgs(model: RoleTurnModelConfig | undefined): string[]
   ];
 }
 
-function buildActivationFlagArgs(activation: RoleTurnActivation): string[] {
-  switch (activation.role) {
-    case "judge":
-      return ["--ak-role", "judge"];
-    case "coder":
-      return [
-        "--ak-role",
-        "coder",
-        "--ak-coder-phase",
-        activation.phase,
-        "--ak-coder-task",
-        activation.taskPath,
-      ];
-    case "fixer":
-      return [
-        "--ak-role",
-        "fixer",
-        "--ak-fixer-phase",
-        activation.phase,
-        "--ak-fix-packet",
-        activation.packetPath,
-        ...(activation.prerequisitesPath === undefined
-          ? []
-          : ["--ak-fixer-prerequisites", activation.prerequisitesPath]),
-      ];
-    case "reviewer":
-      return [
-        "--ak-role",
-        "reviewer",
-        "--ak-review-base",
-        activation.baseRevision,
-        ...(activation.authorityRefs.length === 0
-          ? []
-          : ["--ak-review-authority-refs", JSON.stringify([...activation.authorityRefs])]),
-        ...(activation.ticketNumber === undefined
-          ? []
-          : ["--ak-review-ticket-number", String(activation.ticketNumber)]),
-      ];
-    case "merger":
-      return ["--ak-role", "merger", "--ak-merger-input", activation.inputPath];
-    case "collector":
-      return [
-        "--ak-role",
-        "collector",
-        "--ak-collector-repo",
-        activation.repo,
-        ...(activation.pr === undefined ? [] : ["--ak-collector-pr", activation.pr]),
-        ...(activation.requestManifestPath === undefined
-          ? []
-          : ["--ak-collector-request-manifest", activation.requestManifestPath]),
-        ...(activation.waitMs === undefined ? [] : ["--ak-collector-wait-ms", activation.waitMs]),
-      ];
-    case "doctor":
-      return ["--ak-role", "doctor", "--ak-doctor-case", activation.casePath];
-    case "notary":
-      return [
-        "--ak-role",
-        "notary",
-        "--ak-notary-source-run",
-        activation.sourceRun,
-        ...(activation.ticketNumber === undefined
-          ? []
-          : ["--ak-notary-ticket-number", String(activation.ticketNumber)]),
-      ];
-    case "countersign":
-      // ticketNumber rides activation/admission/invocation only (#632: no private flag).
-      return ["--ak-role", "countersign"];
-    case "gleaner-left":
-      return [
-        "--ak-role",
-        "gleaner-left",
-        "--ak-gleaner-left-base",
-        activation.baseRevision,
-      ];
-    case "inspector":
-      return ["--ak-role", "inspector"];
-    case "gatekeeper":
-      return ["--ak-role", "gatekeeper"];
-    case "navigator":
-      return ["--ak-role", "navigator"];
-    case "auditor":
-      return ["--ak-role", "auditor"];
-    case "diarist":
-      return ["--ak-role", "diarist"];
-    default: {
-      const _exhaustive: never = activation;
-      return _exhaustive;
-    }
+/**
+ * Pi last hop only: shared envelope flags → controlled-session argv pairs (#819).
+ * Flag membership/values stay in projectActivationFlags (middle layer).
+ */
+function activationFlagsToPiArgv(flags: ReadonlyMap<string, boolean | string>): string[] {
+  const args: string[] = [];
+  for (const [name, value] of flags) {
+    if (value === false) continue;
+    args.push(`--${name}`);
+    if (value !== true) args.push(String(value));
   }
+  return args;
 }
 
 function buildMethodArgs(methods: readonly MethodBinding[]): string[] {
@@ -193,9 +116,10 @@ export function applyPiNativeSkillInvocation(
 }
 
 /**
- * Translate a closed RoleTurnRequest into Pi argv after `--no-extensions -e entry`.
- * Controlled session constants and session coordinates are adapter-internal.
- * Single forced method → Pi-native `/skill:` on the argv prompt (coder/reviewer/merger).
+ * Pi last-hop argv after `--no-extensions -e entry` (#819).
+ * Activation flag membership comes from middle-layer projectActivationFlags;
+ * this function only renders session coords, controlled constants, and pairs.
+ * Single forced method → Pi-native `/skill:` on the argv prompt (#822).
  */
 export function buildPiTurnExtraArgs(
   request: RoleTurnRequest,
@@ -222,7 +146,8 @@ export function buildPiTurnExtraArgs(
     "--session-dir",
     sessionDirectory,
     ...extraPiArgs,
-    ...buildActivationFlagArgs(request.activation),
+    // Envelope assembly = projectActivationFlags; pi only renders argv pairs.
+    ...activationFlagsToPiArgv(projectActivationFlags(request)),
     "--mode",
     "json",
     ...buildSeatModelCliArgs(request.model),

package/src/prepared-role-turn.ts

@@ -0,0 +1,68 @@
+import type { RoleTurnKnownFailure, RoleTurnRequest } from "./host-contracts.ts";
+import { renderAgentStartMaterials } from "./agent-start-materials.ts";
+
+/** The shared envelope, prepared before session/new (systemPrompt delivery) and
+ * able to observe the host's real builtin tool surface once it arrives post-session. */
+export type PreparedRoleTurn = Readonly<{
+  mcpServers: readonly Readonly<Record<string, unknown>>[];
+  /**
+   * Structured system-prompt authority. `body` is the provider-facing prompt
+   * bytes; `materials` are typed agent-start reading materials (e.g. Notary
+   * session bound) that the adapter folds into the override at the provider
+   * boundary. This structure is the authoritative production input of the
+   * send path — never a test-only parallel face.
+   */
+  systemPrompt: { readonly body: string; readonly materials: readonly unknown[] };
+  /** Effective user prompt after host-side input transform (canonical Skill invocation). */
+  prompt: string;
+  /**
+   * Host abort signal armed only by typed infrastructure failure (envelope
+   * rememberInfrastructureFailure / non-correctable MCP catch). Lawful
+   * context.abort() (seal / non-sole) does not arm it. executeTurn races
+   * session/prompt against this so infra declarations terminate even when
+   * ACP never resolves (#593).
+   */
+  abortSignal?: AbortSignal;
+  /** Shared ledger consumes the complete ACP round after session/prompt resolves. */
+  closeRound(): Promise<
+    | { readonly accepted: true }
+    | {
+      readonly accepted: false;
+      /** Shared envelope provides officer/correctable text; adapters only deliver it (#813). */
+      readonly retry: {
+        readonly code: string;
+        readonly toolCallIds: readonly string[];
+        readonly message: string;
+      };
+    }
+    | { readonly accepted: false; readonly failure: RoleTurnKnownFailure }
+  >;
+  dispose?(): Promise<void>;
+  /**
+   * Headless CLI family (#645): role terminating-tool schema for host-native
+   * `--json-schema`. Present for every prepared turn; ACP ignores it.
+   */
+  jsonSchema: Readonly<Record<string, unknown>>;
+  /** Terminating tool name whose schema is `jsonSchema`. */
+  terminatingToolName: string;
+  /**
+   * Headless CLI family: feed host-native `structured_output` through the same
+   * terminating-tool path the MCP relay uses (ledger + gates). ACP ignores it.
+   */
+  ingestStructuredOutput(params: unknown): Promise<void>;
+}>;
+
+/** Fold structured system-prompt authority into the provider-visible ACP override. */
+export function renderSystemPromptOverride(authority: {
+  readonly body: string;
+  readonly materials: readonly unknown[];
+}): string {
+  return renderAgentStartMaterials(authority.body, authority.materials);
+}
+
+export type SessionIdentityAuthority = Readonly<{
+  load(principal: RoleTurnRequest["principal"]): Promise<string | undefined>;
+  bind(principal: RoleTurnRequest["principal"], sessionId: string): Promise<void>;
+  /** Durable principal session path for layout ownership / isAvailable — not a rebuild source (#617 DK-4). */
+  resolveSessionFile(principal: RoleTurnRequest["principal"]): string;
+}>;