@akagilnc/pi-workflow-roles 0.1.1751

package/src/git-object-id.ts

@@ -0,0 +1,11 @@
+export type GitObjectFormat = "sha1" | "sha256";
+
+export const FULL_GIT_OBJECT_ID_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+export function isFullGitObjectId(value: unknown): value is string {
+  return typeof value === "string" && FULL_GIT_OBJECT_ID_RE.test(value);
+}
+
+export function gitObjectIdWidth(format: GitObjectFormat): 40 | 64 {
+  return format === "sha1" ? 40 : 64;
+}

package/src/human-format.ts

@@ -0,0 +1,65 @@
+/**
+ * Human-read formatting helpers (#162 人读格式助手).
+ *
+ * Presentation layer only: machine consumers bite full-precision data-* values;
+ * these helpers format the same facts for human scanning (中文时长 / 紧凑 token /
+ * 成本有效精度 / 本地时刻). Shared by the S1 trajectory page and the S2 board —
+ * no structural change to either.
+ */
+
+/** 中文时长: two largest non-zero units (天/小时/分/秒). Non-finite/negative → 0 秒. */
+export function formatDurationZh(ms: number): string {
+  if (!Number.isFinite(ms) || ms <= 0) return "0 秒";
+  const units: Array<[number, string]> = [
+    [86_400_000, "天"],
+    [3_600_000, "小时"],
+    [60_000, "分"],
+    [1000, "秒"],
+  ];
+  let rest = Math.floor(ms);
+  const parts: string[] = [];
+  for (const [unitMs, label] of units) {
+    if (parts.length === 2) break;
+    const value = Math.floor(rest / unitMs);
+    if (value > 0) {
+      parts.push(`${value} ${label}`);
+      rest -= value * unitMs;
+    }
+  }
+  return parts.length > 0 ? parts.join(" ") : "0 秒";
+}
+
+/** 紧凑 token: exact below 1000; one-decimal k/M above (rounded). */
+export function formatTokensCompact(tokens: number): string {
+  if (!Number.isFinite(tokens) || tokens <= 0) return "0";
+  if (tokens < 1000) return String(Math.round(tokens));
+  const round1 = (x: number): string => {
+    const r = Math.round(x * 10) / 10;
+    return Number.isInteger(r) ? String(r) : r.toFixed(1);
+  };
+  if (tokens < 1_000_000) return `${round1(tokens / 1000)}k`;
+  return `${round1(tokens / 1_000_000)}M`;
+}
+
+/** 成本有效精度: ≥100 integer, ≥1 two decimals, <1 four significant digits; zeros stripped. */
+export function formatUsdPrecise(value: number): string {
+  if (!Number.isFinite(value) || value === 0) return "0";
+  const abs = Math.abs(value);
+  const strip = (text: string): string =>
+    text.includes(".") ? text.replace(/0+$/, "").replace(/\.$/, "") : text;
+  if (abs >= 100) return String(Math.round(value));
+  if (abs >= 1) return strip(value.toFixed(2));
+  return String(Number(value.toPrecision(4)));
+}
+
+/** 本地时刻: local wall clock of the instant; unparseable input passes through. */
+export function formatLocalDateTime(iso: string): string {
+  const ms = Date.parse(iso);
+  if (!Number.isFinite(ms)) return iso;
+  const d = new Date(ms);
+  const pad = (n: number): string => String(n).padStart(2, "0");
+  return (
+    `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+    `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
+  );
+}

package/src/in-process-session.ts

@@ -0,0 +1,78 @@
+/**
+ * Thin shared in-process AgentSession open (#233).
+ * Static Pi imports are safe for Navigator (same module instance as ModelRuntime).
+ * Auditor/evidence callers must dynamic-import this module so public-cli bundling
+ * does not statically reach @earendil-works/pi-coding-agent.
+ */
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  SettingsManager,
+  type ModelRuntime,
+  type SessionManager,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+
+export type OpenInProcessAgentSessionOptions = {
+  readonly cwd: string;
+  /** Required when loading a resource loader / systemPrompt. Callers own scratch lifecycle. */
+  readonly agentDir?: string;
+  readonly model: Model<Api>;
+  readonly modelRuntime: ModelRuntime;
+  readonly thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+  readonly sessionManager: SessionManager;
+  readonly systemPrompt?: string;
+  readonly customTools?: ToolDefinition[];
+  readonly noTools?: "all" | "builtin";
+  /** Optional allowlist — omit for unrestricted Pi defaults (ADR 0064). */
+  readonly tools?: string[];
+};
+
+/**
+ * Single createAgentSession + Settings construction for all in-process children.
+ */
+export async function openInProcessAgentSession(
+  options: OpenInProcessAgentSessionOptions,
+): Promise<{ session: Awaited<ReturnType<typeof createAgentSession>>["session"]; dispose(): void }> {
+  const settings = SettingsManager.inMemory({ compaction: { enabled: false }, retry: { enabled: false } });
+
+  const createArgs: Parameters<typeof createAgentSession>[0] = {
+    cwd: options.cwd,
+    model: options.model,
+    thinkingLevel: options.thinkingLevel ?? "off",
+    modelRuntime: options.modelRuntime,
+    sessionManager: options.sessionManager,
+    settingsManager: settings,
+    ...(options.noTools === undefined ? {} : { noTools: options.noTools }),
+    ...(options.tools === undefined ? {} : { tools: options.tools }),
+    ...(options.customTools === undefined ? {} : { customTools: options.customTools }),
+  };
+
+  if (options.agentDir !== undefined) {
+    const loader = new DefaultResourceLoader({
+      cwd: options.cwd,
+      agentDir: options.agentDir,
+      settingsManager: settings,
+      noExtensions: true,
+      noSkills: true,
+      noPromptTemplates: true,
+      noThemes: true,
+      noContextFiles: true,
+      ...(options.systemPrompt === undefined ? {} : { systemPrompt: options.systemPrompt }),
+    });
+    await loader.reload();
+    createArgs.agentDir = options.agentDir;
+    createArgs.resourceLoader = loader;
+  } else if (options.systemPrompt !== undefined) {
+    throw new Error("openInProcessAgentSession requires agentDir when systemPrompt is set");
+  }
+
+  const { session } = await createAgentSession(createArgs);
+  return {
+    session,
+    dispose() {
+      session.dispose();
+    },
+  };
+}

package/src/judge-auditor.ts

@@ -0,0 +1,55 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import {
+  createComplianceDecisionTool,
+  runComplianceAudit,
+  type ComplianceCompletion,
+  type ComplianceDecision,
+} from "./compliance-transport.ts";
+import { auditorRunDirectory } from "./auditor-dossier-tool.ts";
+import { loadAuditorSoul } from "./auditor-soul.ts";
+import {
+  readJudgeAuditSubjects,
+  resolveAuditDossier,
+  toAuditIncomplete,
+} from "./dossier-resolution.ts";
+
+export const JUDGE_AUDIT_TOOL_NAME = "ak_soul_audit_decision";
+export const SOUL_AUDIT_TOOL_NAME = JUDGE_AUDIT_TOOL_NAME;
+
+export type JudgeAuditOptions = {
+  context: ExtensionContext;
+  signal?: AbortSignal;
+};
+
+const auditDecisionTool = createComplianceDecisionTool(
+  JUDGE_AUDIT_TOOL_NAME,
+  "Return whether the proposed verdict demonstrably follows the judge soul and dossier evidence.",
+);
+
+/**
+ * Judge auditor: zero hand-delivered materials. Subjects recovered from the
+ * parent-session books. Public CLI injects AK_ROLE_RUN_DIR; bare Pi (ADR 0052)
+ * proceeds without that pointer and self-locates per soul.
+ */
+export function createPiJudgeAuditor(
+  runCompletion?: ComplianceCompletion,
+): (options: JudgeAuditOptions) => Promise<ComplianceDecision> {
+  return async (options) => {
+    const dossier = resolveAuditDossier();
+    if (dossier.status === "incomplete") return toAuditIncomplete(dossier.observation);
+    const subjects = readJudgeAuditSubjects(options.context);
+    if (subjects.status === "incomplete") return toAuditIncomplete(subjects.observation);
+
+    return runComplianceAudit({
+      tool: auditDecisionTool,
+      systemPrompt: await loadAuditorSoul("judge"),
+      roleLabel: "Soul compliance audit",
+      invalidDecisionLabel: "invalid soul audit decision",
+      ...(runCompletion === undefined ? {} : { runCompletion }),
+      context: options.context,
+      ...(auditorRunDirectory(options.context) === undefined ? {} : { runDirectory: auditorRunDirectory(options.context) }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+  };
+}

package/src/judge-recording-anti-forge.ts

@@ -0,0 +1,53 @@
+import { sha256Hex } from "./sha256.ts";
+
+/**
+ * On-demand anti-forge for judge recordings.
+ *
+ * Standing CI must not byte-pin soul free text. Call these only when a
+ * concrete recording is being consumed as evidence and must be checked
+ * against the soul body supplied at that moment (current or packaged).
+ */
+
+export function soulTextDigest(soulText: string): string {
+  return sha256Hex(soulText);
+}
+
+export function assertRecordingSoulDigest(options: {
+  claimedDigest: unknown;
+  soulText: string;
+  label: string;
+}): void {
+  if (typeof options.claimedDigest !== "string") {
+    throw new Error(`${options.label} metadata soulDigest must be a string`);
+  }
+  const actual = soulTextDigest(options.soulText);
+  if (actual !== options.claimedDigest) {
+    throw new Error(
+      `${options.label} metadata soulDigest must match the soul supplied at consumption`,
+    );
+  }
+}
+
+/**
+ * Construct-at-consumption check: resolve the packaged soul via the injected
+ * reader, then verify meta.soulDigest. Reader is injected so callers control
+ * git/fs access and tests stay synthetic.
+ */
+export function assertPackagedSoulMatchesMeta(
+  meta: Record<string, unknown>,
+  label: string,
+  readPackagedSoul: (packageSha: string, label: string) => string,
+): void {
+  if (typeof meta.packageSha !== "string") {
+    throw new Error(`${label} metadata packageSha must be a string`);
+  }
+  if (typeof meta.soulDigest !== "string") {
+    throw new Error(`${label} metadata soulDigest must be a string`);
+  }
+  const packagedSoul = readPackagedSoul(meta.packageSha, label);
+  assertRecordingSoulDigest({
+    claimedDigest: meta.soulDigest,
+    soulText: packagedSoul,
+    label,
+  });
+}

package/src/judge-role.ts

@@ -0,0 +1,160 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  AgentToolResult,
+} from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+
+import { disposeComplianceDecision } from "./audit-escalation.ts";
+import type { ComplianceDecision } from "./compliance-transport.ts";
+
+import {
+  JUDGE_OUTPUT_TOOL_NAME,
+  validateAcceptedJudgeDetails,
+  type JudgeVerdict,
+} from "./package-contracts/judge-output.ts";
+
+export { JUDGE_OUTPUT_TOOL_NAME };
+export type { JudgeVerdict };
+
+const judgeVerdictSchema = Type.Object(
+  {
+    judgeStatus: StringEnum(["converged", "continue", "escalate"] as const, { description: "Judge adjudication outcome discriminator." }),
+    fix: Type.Optional(
+      Type.Object(
+        { summary: Type.String({ minLength: 1, description: "Required remediation summary." }) },
+        { additionalProperties: false, description: "Remediation requested when adjudication must continue." },
+      ),
+    ),
+    classes: Type.Optional(Type.Array(Type.Object({
+      name: Type.String({ minLength: 1 }),
+      owner: Type.String({ minLength: 1 }),
+      boundary: Type.String({ minLength: 1 }),
+      disposition: Type.String({ minLength: 1 }),
+    }, { additionalProperties: false }), { minItems: 1, description: "Adjudicated finding classes with owner and repair boundary." })),
+    note: Type.Optional(Type.String({ minLength: 1, description: "Optional adjudication note." })),
+    evidence: Type.Optional(Type.Unknown({ description: "Retained adjudication evidence." })),
+    decisionGate: Type.Optional(
+      Type.Object(
+        {
+          question: Type.String({ minLength: 1 }),
+          options: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+        },
+        { additionalProperties: false, description: "Question and options requiring human authority." },
+      ),
+    ),
+  },
+  { additionalProperties: true },
+);
+(judgeVerdictSchema as unknown as { required: string[] }).required = [];
+
+type JudgeVerdictParameters = Static<typeof judgeVerdictSchema>;
+
+export type SoulAuditResult = ComplianceDecision;
+
+export type JudgeRoleDependencies = {
+  loadSoul(): Promise<string>;
+  auditSoulCompliance(
+    options: { context: ExtensionContext; signal?: AbortSignal },
+  ): Promise<SoulAuditResult>;
+};
+
+export type JudgeRoleHostActions = {
+  failInfrastructure(error: unknown, ctx: ExtensionContext, toolCallId?: string): never;
+};
+
+export function validateVerdict(verdict: JudgeVerdictParameters): JudgeVerdict {
+  return validateAcceptedJudgeDetails(verdict);
+}
+
+function requireSingletonSubmissionCall(
+  toolCallId: string,
+  ctx: ExtensionContext,
+): void {
+  const leaf = ctx.sessionManager.getLeafEntry();
+  if (leaf?.type !== "message" || leaf.message.role !== "assistant") {
+    throw new Error("Judge output must be the sole final tool call");
+  }
+  const calls = leaf.message.content.filter((part) => part.type === "toolCall");
+  const call = calls[0];
+  if (
+    calls.length !== 1 || call === undefined || call.id !== toolCallId ||
+    call.name !== JUDGE_OUTPUT_TOOL_NAME
+  ) {
+    throw new Error("Judge output must be the sole final tool call");
+  }
+}
+
+export function createJudgeRoleRuntime(
+  pi: ExtensionAPI,
+  dependencies: JudgeRoleDependencies,
+  hostActions: JudgeRoleHostActions,
+): { activate(): Promise<void> } {
+  let soul: string | undefined;
+  let lifecycleRegistered = false;
+
+  return {
+    async activate() {
+      soul = (await dependencies.loadSoul()).trim();
+      if (soul.length === 0) throw new Error("Judge soul is empty");
+      if (!lifecycleRegistered) {
+        lifecycleRegistered = true;
+        pi.registerTool({
+          name: JUDGE_OUTPUT_TOOL_NAME,
+          label: "Judge Output",
+          description:
+            "Submit the final judge verdict. Soul compliance is audited before acceptance.",
+          promptSnippet: "Submit the final judge verdict after adjudication",
+          promptGuidelines: [
+            `Use ${JUDGE_OUTPUT_TOOL_NAME} as the final action for the judge role.`,
+          ],
+          parameters: judgeVerdictSchema,
+          async execute(toolCallId, parameters, signal, _onUpdate, ctx): Promise<AgentToolResult<unknown>> {
+            if (soul === undefined) throw new Error("Judge soul was not loaded");
+            requireSingletonSubmissionCall(toolCallId, ctx);
+            const verdict = validateVerdict(parameters);
+            // Candidate verdict is already on the parent session books as this
+            // tool-call leaf (first-record-then-audit; run 019fea05 L61/L62).
+            let audit: SoulAuditResult;
+            try {
+              audit = await dependencies.auditSoulCompliance(
+                signal === undefined
+                  ? { context: ctx }
+                  : { context: ctx, signal },
+              );
+            } catch (error) {
+              hostActions.failInfrastructure(error, ctx, toolCallId);
+            }
+            return disposeComplianceDecision<AgentToolResult<unknown>>(
+              audit,
+              {
+                pass: (usage) => ({
+                  content: [{ type: "text" as const, text: "Judge verdict accepted" }],
+                  details: verdict,
+                  terminate: true as const,
+                  ...(usage === undefined ? {} : { usage }),
+                }),
+                revise: (violations) => {
+                  throw new Error(
+                    `Judge verdict violates its soul: ${violations.join("; ")}`,
+                  );
+                },
+                escalate: (result) => result,
+                auditIncomplete: (result) => result,
+              },
+              verdict,
+            );
+          },
+        });
+        pi.on("before_agent_start", (event) => {
+          if (soul === undefined) throw new Error("Judge soul was not loaded");
+          return {
+            systemPrompt:
+              `${event.systemPrompt}\n\n<judge_soul>\n${soul}\n</judge_soul>`,
+          };
+        });
+      }
+    },
+  };
+}

package/src/merger-contracts.ts

@@ -0,0 +1,71 @@
+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";
+
+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 }),
+  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 }),
+  authorizedChecks: Type.Array(checkSchema),
+}, { additionalProperties: false });
+const mergerOutputVariants = Type.Union([
+  Type.Object({ status: Type.Literal("completed", { description: "Merge attempt completed." }), attemptId: Type.String({ minLength: 1, description: "Identity of the admitted merge attempt." }), report: Type.String({ minLength: 1, description: "Truthful merge outcome report." }), mergeCommitId: Type.String({ pattern: oidPattern, description: "Verified completed merge commit object ID." }) }, { additionalProperties: false }),
+  Type.Object({ status: Type.Literal("escalate", { description: "Merge attempt requires human authority." }), attemptId: Type.String({ minLength: 1, description: "Identity of the admitted merge attempt." }), diagnosis: Type.String({ minLength: 1, description: "Reason merge completion requires escalation." }), report: Type.String({ minLength: 1, description: "Truthful merge outcome report." }) }, { additionalProperties: false }),
+]);
+export const mergerOutputSchema = 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>>;
+export type MergerInput = DeepReadonly<Static<typeof mergerInputSchema>>;
+export type MergerOutput =
+  | { status: "completed"; attemptId: string; report: string; mergeCommitId: string }
+  | { status: "escalate"; attemptId: string; diagnosis: string; report: string };
+export const MERGER_OUTPUT_TOOL_NAME = "ak_merger_output";
+export const MERGER_ACCEPTED_TEXT = "Merger output accepted";
+
+const record = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+const blank = (v: unknown) => typeof v !== "string" || v.trim().length === 0;
+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; }
+
+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);
+}
+
+export function validateMergerOutput(value: unknown, expectedAttemptId?: string): MergerOutput {
+  if (!record(value) || (expectedAttemptId !== undefined && value.attemptId !== expectedAttemptId)) throw new Error("Merger output attempt mismatch");
+  if (value.status === "completed" && isFullGitObjectId(value.mergeCommitId)) return structuredClone(value) as MergerOutput;
+  if (value.status === "escalate") return structuredClone(value) as MergerOutput;
+  throw new Error("Merger output has no recognized execution discriminator");
+}

package/src/merger-git-state.ts

@@ -0,0 +1,76 @@
+import { execFile } from "node:child_process";
+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 interface MergerGitState {
+  activeMerge(): Promise<ActiveMergerGitState>;
+  completedMerge(mergeCommitId: string, automaticMergeTreeId: string): Promise<CompletedMergerGitState>;
+}
+
+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 unmerged(cwd: string): Promise<string[]> {
+  const raw = exactUtf8(await git(cwd, ["ls-files", "-u", "-z"]), "Git unmerged index");
+  const paths = new Set<string>();
+  for (const row of raw.split("\0")) {
+    if (!row) continue;
+    const tab = row.indexOf("\t");
+    if (tab < 0 || tab === row.length - 1) throw new Error("Git returned a malformed unmerged index row");
+    paths.add(row.slice(tab + 1));
+  }
+  return [...paths].sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+}
+
+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");
+      }
+      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 };
+    },
+  };
+}

package/src/merger-role.ts

@@ -0,0 +1,60 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+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 { 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 const MERGER_ACTIVE_TOOLS = ["read", "grep", "find", "ls", "bash", "write", "edit", MERGER_OUTPUT_TOOL_NAME] as const;
+export type MergerRoleDependencies = { loadSoul(): Promise<string>; loadInput(path: string): Promise<unknown>; gitState: MergerGitState };
+export type MergerRoleHostActions = { failInfrastructure(error: unknown, ctx: ExtensionContext, toolCallId?: string): never };
+
+function same(a: readonly string[], b: readonly string[]): boolean { return a.length === b.length && a.every((value, i) => value === b[i]); }
+function singleton(id: string, ctx: ExtensionContext): void { const leaf = ctx.sessionManager.getLeafEntry(); if (leaf?.type !== "message" || leaf.message.role !== "assistant") throw new Error("Merger output must be the sole final tool call"); const calls = leaf.message.content.filter(part => part.type === "toolCall"); if (calls.length !== 1 || calls[0]?.id !== id || calls[0]?.name !== MERGER_OUTPUT_TOOL_NAME) throw new Error("Merger output must be the sole final tool call"); }
+function materialText(input: MergerInput, key: keyof MergerInput["materials"]): string { return exactUtf8(Buffer.from(input.materials[key].bytesBase64, "base64"), `Merger ${key}`); }
+
+export function createMergerRoleRuntime(pi: ExtensionAPI, dependencies: MergerRoleDependencies, host: MergerRoleHostActions) {
+  let activation: { soul: string; input: Readonly<MergerInput>; automaticMergeTreeId: string } | 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: "Merger Output", description: "Submit the sole completed merge candidate or genuine intent/authority escalation.", promptSnippet: "Submit the Merger result", promptGuidelines: [`Use ${MERGER_OUTPUT_TOOL_NAME} as the sole final action.`, "Infrastructure and Git failures abort; they are not escalations."], parameters: mergerOutputSchema,
+        async execute(id, params, _signal, _update, ctx) {
+          if (!activation) throw new Error("Merger is not activated");
+          if (accepted) throw new Error("Merger output already accepted");
+          let output;
+          try {
+            singleton(id, ctx);
+            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;
+          return { content: [{ type: "text" as const, text: MERGER_ACCEPTED_TEXT }], details: output, terminate: true as const };
+        } });
+      pi.on("before_agent_start", event => { if (!activation) throw new Error("Merger is not activated"); 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);
+    for (const name of MERGER_ACTIVE_TOOLS) if (all.filter(item => item === name).length !== 1) throw new Error(`Merger required tool collision or missing: ${name}`);
+    pi.setActiveTools([...MERGER_ACTIVE_TOOLS]);
+    const active = pi.getActiveTools?.() ?? [...MERGER_ACTIVE_TOOLS];
+    if (!same(active, MERGER_ACTIVE_TOOLS)) throw new Error("Merger active tool narrowing failed");
+  } };
+}