@akagilnc/pi-workflow-roles 0.1.1751

package/src/tool-execution-observation.ts

@@ -0,0 +1,168 @@
+import { writeSync } from "node:fs";
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+
+import { writeStderrJsonlRecord } from "./stderr-jsonl.ts";
+
+/** Mandatory coalesce window for tool_execution_update heartbeats (stderr is bounded). */
+export const TOOL_EXECUTION_UPDATE_THROTTLE_MS = 30_000;
+
+/**
+ * Heartbeat basis for downstream silence predicates.
+ *
+ * Production Pi `bash.js` calls `onUpdate` once with empty content at execute entry,
+ * then schedules output-driven updates at ~100 ms. This face skips non-producing
+ * (empty-content) updates so the first heartbeat is real child output, then
+ * coalesces at {@link TOOL_EXECUTION_UPDATE_THROTTLE_MS}.
+ *
+ * If a future host path stopped delivering output-driven updates, change this to
+ * `"duration-only"` and document that silence predicates degrade to pure duration.
+ */
+export const TOOL_EXECUTION_UPDATE_HEARTBEAT = "output-driven" as const;
+
+const observationBase = {
+  role: Type.String({ minLength: 1 }),
+  toolCallId: Type.String({ minLength: 1 }),
+  toolName: Type.String({ minLength: 1 }),
+  timestamp: Type.String({ format: "date-time" }),
+} as const;
+
+export const toolExecutionObservationRecordSchema = Type.Union([
+  Type.Object({
+    ...observationBase,
+    event: Type.Literal("tool_execution_start"),
+  }, { additionalProperties: true }),
+  Type.Object({
+    ...observationBase,
+    event: Type.Literal("tool_execution_update"),
+  }, { additionalProperties: true }),
+  Type.Object({
+    ...observationBase,
+    event: Type.Literal("tool_execution_end"),
+    isError: Type.Boolean(),
+  }, { additionalProperties: true }),
+]);
+
+export type ToolExecutionObservationRecord = Static<typeof toolExecutionObservationRecordSchema>;
+export type ToolExecutionObservationWriter = (record: ToolExecutionObservationRecord) => void | Promise<void>;
+
+export function validateToolExecutionObservationRecord(record: unknown): ToolExecutionObservationRecord {
+  if (!Value.Check(toolExecutionObservationRecordSchema, record)) {
+    throw new TypeError("Tool execution observation record does not match its contract");
+  }
+  return record as ToolExecutionObservationRecord;
+}
+
+export function writeToolExecutionObservationRecord(
+  record: ToolExecutionObservationRecord,
+  write: typeof writeSync = writeSync,
+): void {
+  writeStderrJsonlRecord(validateToolExecutionObservationRecord(record), write);
+}
+
+/** True when a tool_execution_update partialResult carries producing content (not bash's empty entry callback). */
+export function isProducingToolUpdate(partialResult: unknown): boolean {
+  if (partialResult == null) return false;
+  if (typeof partialResult !== "object") return true;
+  const content = (partialResult as { content?: unknown }).content;
+  if (!Array.isArray(content)) return true;
+  if (content.length === 0) return false;
+  return content.some((part) => {
+    if (typeof part !== "object" || part === null) return true;
+    const text = (part as { text?: unknown }).text;
+    if (typeof text === "string") return text.length > 0;
+    return true;
+  });
+}
+
+type CallObservationState = {
+  lastUpdateEmitMonoMs: number | undefined;
+};
+
+export type ToolExecutionObservationFace = {
+  onStart(event: { toolCallId: string; toolName: string }): void | Promise<void>;
+  onUpdate(event: { toolCallId: string; toolName: string; partialResult: unknown }): void | Promise<void>;
+  onEnd(event: { toolCallId: string; toolName: string; isError: boolean }): void | Promise<void>;
+  reset(): void;
+};
+
+/**
+ * Production throttle clock: genuinely monotonic milliseconds.
+ * Wall-clock Date.now() is not safe — NTP/slew can compress two heartbeats under 30s.
+ */
+export function systemToolExecutionObservationMonoNow(): number {
+  return performance.now();
+}
+
+export function createToolExecutionObservationFace(options: {
+  role: () => string | undefined;
+  admitted: () => boolean;
+  clock(): string;
+  monoNow(): number;
+  write(record: ToolExecutionObservationRecord): void | Promise<void>;
+}): ToolExecutionObservationFace {
+  const states = new Map<string, CallObservationState>();
+
+  async function emit(record: unknown): Promise<void> {
+    await options.write(validateToolExecutionObservationRecord(record));
+  }
+
+  function activeRole(): string | undefined {
+    if (!options.admitted()) return undefined;
+    const role = options.role();
+    return role === undefined || role === "" ? undefined : role;
+  }
+
+  return {
+    reset() {
+      states.clear();
+    },
+    async onStart(event) {
+      const role = activeRole();
+      if (role === undefined) return;
+      states.set(event.toolCallId, { lastUpdateEmitMonoMs: undefined });
+      await emit({
+        event: "tool_execution_start",
+        role,
+        toolCallId: event.toolCallId,
+        toolName: event.toolName,
+        timestamp: options.clock(),
+      });
+    },
+    async onUpdate(event) {
+      const role = activeRole();
+      if (role === undefined) return;
+      if (!isProducingToolUpdate(event.partialResult)) return;
+      const now = options.monoNow();
+      const state = states.get(event.toolCallId) ?? { lastUpdateEmitMonoMs: undefined };
+      if (
+        state.lastUpdateEmitMonoMs !== undefined
+        && now - state.lastUpdateEmitMonoMs < TOOL_EXECUTION_UPDATE_THROTTLE_MS
+      ) {
+        return;
+      }
+      state.lastUpdateEmitMonoMs = now;
+      states.set(event.toolCallId, state);
+      await emit({
+        event: "tool_execution_update",
+        role,
+        toolCallId: event.toolCallId,
+        toolName: event.toolName,
+        timestamp: options.clock(),
+      });
+    },
+    async onEnd(event) {
+      const role = activeRole();
+      if (role === undefined) return;
+      states.delete(event.toolCallId);
+      await emit({
+        event: "tool_execution_end",
+        role,
+        toolCallId: event.toolCallId,
+        toolName: event.toolName,
+        timestamp: options.clock(),
+        isError: event.isError,
+      });
+    },
+  };
+}

package/src/uuidv7.ts

@@ -0,0 +1 @@
+import{randomBytes}from"node:crypto";const UUIDV7=/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;export function isUuidV7(value:unknown):value is string{return typeof value==="string"&&UUIDV7.test(value)}export function uuidv7(now=Date.now()):string{const b=randomBytes(16);let n=BigInt(now);for(let i=5;i>=0;i--){b[i]=Number(n&255n);n>>=8n}b[6]=(b[6]!&15)|0x70;b[8]=(b[8]!&63)|0x80;const h=b.toString("hex");return`${h.slice(0,8)}-${h.slice(8,12)}-${h.slice(12,16)}-${h.slice(16,20)}-${h.slice(20)}`}

package/src/work-subject-identity.ts

@@ -0,0 +1,94 @@
+/**
+ * Single low-level work-subject identity owner.
+ * Navigator lifecycle and Terminal settlement both import this module so subject
+ * keys cannot drift across a duplicated helper. Depends only on path topology —
+ * never the Navigator preparation graph or public-cli bundle surface.
+ */
+import { resolve } from "node:path";
+
+import {
+  physicalPathIdentity,
+  physicallyContainedIn,
+  resolveActivationLedgerHome,
+} from "./activation-ledger-topology.ts";
+
+/**
+ * Issue-root segment under `.ak/work/issues/<id>` (optional `#…` suffix stripped).
+ * Single low-level owner — Navigator subject helpers must not reimplement this.
+ */
+export function issueRoot(value: string): string | undefined {
+  const normalized = value.replaceAll("\\", "/");
+  const marker = ".ak/work/issues/";
+  const index = normalized.indexOf(marker);
+  if (index < 0) return undefined;
+  const issue = normalized
+    .slice(index + marker.length)
+    .split("/")[0]
+    ?.split("#")[0];
+  return issue === undefined || issue === ""
+    ? undefined
+    : normalized.slice(0, index + marker.length) + issue;
+}
+
+function workIdentityFromCwd(cwd: string): string | undefined {
+  const resolvedCwd = resolve(cwd, ".");
+  const cwdIssue = issueRoot(resolvedCwd);
+  if (cwdIssue !== undefined) return cwdIssue;
+  if (resolvedCwd.includes("/.ak/work/")) return resolvedCwd;
+  return undefined;
+}
+
+/** Machine-ledger session paths are not work identity (ADR 0048 session-in-home). */
+function isMachineLedgerSessionPath(sessionPath: string): boolean {
+  // Physical containment under the package ledger home — never directory spelling,
+  // and stable across macOS /var ↔ /private/var realpath asymmetry.
+  return physicallyContainedIn(resolveActivationLedgerHome(), sessionPath);
+}
+
+/**
+ * Derive the durable work-subject key from a session directory and cwd.
+ * Session placement is an implementation detail; relative and absolute role
+ * invocations share one key.
+ */
+export function subjectPath(sessionDir: string, cwd = process.cwd()): string {
+  if (sessionDir === "") {
+    // Preserve prior fall-through: empty sessionDir with no work cwd → cwd/.ak/work.
+    return workIdentityFromCwd(cwd) ?? resolve(cwd, ".ak/work");
+  }
+  const resolvedSession = resolve(cwd, sessionDir || ".ak/work");
+  // Durable role sessions under the machine ledger home are not work roots.
+  // Derive subject from cwd (same as empty sessionDir / in-memory) so Navigator
+  // keeps issue-root identity when ignition places --session-dir under ADR 0048.
+  // Ordinary repository cwd with no explicit work identity uses the established
+  // cwd-derived `.ak/work` fallback — never the per-invocation ledger session path.
+  if (isMachineLedgerSessionPath(resolvedSession)) {
+    return workIdentityFromCwd(cwd) ?? resolve(cwd, ".ak/work");
+  }
+  const issue = issueRoot(resolvedSession);
+  if (issue !== undefined) return issue;
+  // Ad-hoc role sessions live below the same work root.  Remove the role's
+  // private run directory before deriving identity; the run/session spelling
+  // must not become a cross-role routing key.
+  const runsMarker = "/runs/";
+  const runsIndex = resolvedSession.indexOf(runsMarker);
+  if (runsIndex >= 0) {
+    return resolvedSession.slice(0, runsIndex);
+  }
+  return resolvedSession;
+}
+
+/**
+ * Project/cwd work identity used by public CLI / empty-sessionDir runs.
+ * Equivalent to subjectPath("", projectRoot).
+ */
+export function workSubjectKeyFromProjectRoot(projectRoot: string): string {
+  return subjectPath("", projectRoot);
+}
+
+/**
+ * Physical work-subject equality: collapses macOS /var ↔ /private/var (and any
+ * other realpath alias) so the same work root correlates across path spellings.
+ */
+export function workSubjectKeysEqual(left: string, right: string): boolean {
+  return physicalPathIdentity(left) === physicalPathIdentity(right);
+}

package/src/worker-role.ts

@@ -0,0 +1,434 @@
+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 { openToolObjectFromUnion } from "./open-tool-schema.ts";
+
+import type {
+  AnyCanonicalSkillBinding,
+  CanonicalSkillBinding,
+} from "./canonical-skill-binding.ts";
+import {
+  CODER_OUTPUT_TOOL_NAME,
+  FIXER_OUTPUT_TOOL_NAME,
+  validateAcceptedWorkerDetails,
+  type CoderOutput,
+  type FixerOutput,
+  type WorkerOutput,
+  type WorkerRoleLabel,
+} from "./package-contracts/worker-output.ts";
+import { fixerOutputSchema, validateFixerOutput, validateFixerOutputForPacket, type FixerPhase } from "./package-contracts/fixer-output.ts";
+import {
+  FixerPacketValidationError,
+  parseFixerPrerequisites,
+  type FixerInvocationInput,
+} from "./package-contracts/fixer-packet.ts";
+import { createWorkerSubmissionGate } from "./worker-submission-gates.ts";
+
+export {
+  CODER_OUTPUT_TOOL_NAME,
+  FIXER_OUTPUT_TOOL_NAME,
+  validateAcceptedWorkerDetails,
+};
+export type { WorkerOutput };
+
+/** Exact case-sensitive substring literals blocked on Fixer bash only. */
+const FIXER_BASH_FORBIDDEN_LITERALS = [
+  "rm -rf",
+  "git reset --hard",
+  "git clean",
+  "git checkout --",
+] as const;
+
+function matchFixerBashForbiddenLiteral(
+  command: string,
+): (typeof FIXER_BASH_FORBIDDEN_LITERALS)[number] | undefined {
+  return FIXER_BASH_FORBIDDEN_LITERALS.find((literal) =>
+    command.includes(literal)
+  );
+}
+
+const coderOutputVariants = Type.Union([
+  Type.Object({
+    status: StringEnum(["planned"] as const, { description: "Plan-phase proposal outcome." }),
+    report: Type.String({ minLength: 1, description: "Truthful Coder outcome report." }),
+  }, { additionalProperties: false }),
+  Type.Object({
+    status: StringEnum(["completed", "refused"] as const, { description: "Completed or lawfully refused apply outcome." }),
+    report: Type.String({ minLength: 1, description: "Truthful Coder outcome report." }),
+  }, { additionalProperties: false }),
+  Type.Object({
+    status: StringEnum(["unfinished"] as const, { description: "Honest unfinished apply outcome." }),
+    report: Type.String({ minLength: 1, description: "Truthful Coder outcome report." }),
+    remainingScope: Type.String({ minLength: 1, description: "Work remaining after this invocation." }),
+  }, { additionalProperties: false }),
+]);
+const coderOutputSchema = openToolObjectFromUnion(coderOutputVariants);
+type WorkerOutputParameters = CoderOutput | FixerOutput;
+export type { FixerOutput, CoderOutput };
+export const FIXER_FLAG_DEFINITIONS = {
+  packet: {
+    name: "ak-fix-packet",
+    definition: {
+      description: "Path to opaque prose instructions for the Fixer",
+      type: "string" as const,
+    },
+  },
+  prerequisites: {
+    name: "ak-fixer-prerequisites",
+    definition: {
+      description: "Optional path to a JSON array of typed Fixer prerequisites",
+      type: "string" as const,
+    },
+  },
+  phase: {
+    name: "ak-fixer-phase",
+    definition: {
+      description:
+        "Fixer phase: plan (inspect and propose a repair plan; no edits or commits) or apply (execute the approved plan, verify, and commit when repaired)",
+      type: "string" as const,
+    },
+  },
+} as const;
+
+export const FIXER_PHASES = ["plan", "apply"] as const satisfies readonly FixerPhase[];
+type WorkerPhase = (typeof FIXER_PHASES)[number];
+
+function isWorkerPhase(value: unknown): value is WorkerPhase {
+  return typeof value === "string" && (FIXER_PHASES as readonly string[]).includes(value);
+}
+
+export type WorkerRoleHostActions = {
+  failInfrastructure(error: unknown, ctx: ExtensionContext, toolCallId?: string): never;
+};
+
+export type FixerRoleDependencies = {
+  loadSoul(): Promise<string>;
+  loadPacket(path: string): Promise<string>;
+};
+
+export type CoderRoleDependencies = {
+  loadSoul(): Promise<string>;
+  loadTask(path: string): Promise<string>;
+  loadCanonicalSkillBinding?(
+    name: "tdd",
+  ): Promise<AnyCanonicalSkillBinding>;
+};
+
+export type WorkerRoleRuntime = {
+  activate(ctx?: ExtensionContext): Promise<void>;
+  /** Arm gate ① baseline after envelope places the worktree (coder/fixer). Parent feeds sitian durability. */
+  armSubmissionGate(cwd: string, parent?: { getSessionFile(): string | undefined }): void;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function deepFreeze<T>(value: T): T {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+export function validateWorkerOutput(
+  output: unknown,
+  phase: WorkerPhase,
+  roleLabel: WorkerRoleLabel,
+): WorkerOutput {
+  if (roleLabel === "Fixer") return validateFixerOutput(output, phase);
+  return validateAcceptedWorkerDetails(output, "Coder") as CoderOutput;
+}
+
+function requireSingletonSubmissionCall(
+  toolCallId: string,
+  expectedToolName: string,
+  roleLabel: WorkerRoleLabel,
+  ctx: ExtensionContext,
+): void {
+  const leaf = ctx.sessionManager.getLeafEntry();
+  if (leaf?.type !== "message" || leaf.message.role !== "assistant") {
+    throw new Error(`${roleLabel} 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 !== expectedToolName
+  ) {
+    throw new Error(`${roleLabel} output must be the sole final tool call`);
+  }
+}
+
+export function createFixerRoleRuntime(
+  pi: ExtensionAPI,
+  dependencies: FixerRoleDependencies,
+): WorkerRoleRuntime {
+  let soul: string | undefined;
+  let packet: FixerInvocationInput | undefined;
+  let phase: WorkerPhase | undefined;
+  let lifecycleRegistered = false;
+  const submissionGate = createWorkerSubmissionGate();
+
+  pi.registerFlag(
+    FIXER_FLAG_DEFINITIONS.packet.name,
+    FIXER_FLAG_DEFINITIONS.packet.definition,
+  );
+  pi.registerFlag(
+    FIXER_FLAG_DEFINITIONS.prerequisites.name,
+    FIXER_FLAG_DEFINITIONS.prerequisites.definition,
+  );
+  pi.registerFlag(
+    FIXER_FLAG_DEFINITIONS.phase.name,
+    FIXER_FLAG_DEFINITIONS.phase.definition,
+  );
+
+  return {
+    async activate() {
+      soul = (await dependencies.loadSoul()).trim();
+      if (soul.length === 0) throw new Error("Fixer soul is empty");
+      const selectedPhase = pi.getFlag(FIXER_FLAG_DEFINITIONS.phase.name);
+      if (!isWorkerPhase(selectedPhase)) {
+        throw new Error(
+          "Fixer role requires --ak-fixer-phase plan|apply; no other phase is supported",
+        );
+      }
+      phase = selectedPhase;
+      const packetPath = pi.getFlag(FIXER_FLAG_DEFINITIONS.packet.name);
+      if (typeof packetPath !== "string" || packetPath.trim().length === 0) {
+        throw new Error("Fixer role requires --ak-fix-packet");
+      }
+      const instructions = await dependencies.loadPacket(packetPath);
+      if (instructions.trim().length === 0) {
+        throw new FixerPacketValidationError(
+          new Error("Fixer instructions must be nonblank"),
+        );
+      }
+      const prerequisitesPath = pi.getFlag(FIXER_FLAG_DEFINITIONS.prerequisites.name);
+      if (prerequisitesPath !== undefined && (typeof prerequisitesPath !== "string" || prerequisitesPath.trim().length === 0)) {
+        throw new Error("Fixer --ak-fixer-prerequisites path must be nonblank when supplied");
+      }
+      const prerequisites = typeof prerequisitesPath === "string"
+        ? parseFixerPrerequisites(await dependencies.loadPacket(prerequisitesPath))
+        : Object.freeze([]);
+      packet = Object.freeze({ instructions, prerequisites });
+
+      if (!lifecycleRegistered) {
+        lifecycleRegistered = true;
+        pi.registerTool({
+          name: FIXER_OUTPUT_TOOL_NAME,
+          label: "Fixer Output",
+          description:
+            "Submit the plan refusal, apply settlement, or honest unfinished handover.",
+          promptSnippet: "Submit the final fixer report",
+          promptGuidelines: [
+            `Use ${FIXER_OUTPUT_TOOL_NAME} as the final action for the fixer role.`,
+            `${FIXER_OUTPUT_TOOL_NAME} reports only lawful assignment blockers; infrastructure failures abort.`,
+            "plan permits planned|refused; apply permits completed|refused|partially_completed|unfinished.",
+            "When the diff includes test changes, submit testEvidence: contract proven, one-line minimum necessary cost, measured duration.",
+          ],
+          parameters: fixerOutputSchema,
+          async execute(toolCallId, parameters, _signal, _onUpdate, ctx): Promise<AgentToolResult<unknown>> {
+            if (packet === undefined || phase === undefined) {
+              throw new Error("Fixer repair packet and phase were not loaded");
+            }
+            requireSingletonSubmissionCall(
+              toolCallId,
+              FIXER_OUTPUT_TOOL_NAME,
+              "Fixer",
+              ctx,
+            );
+            const output = deepFreeze(validateFixerOutputForPacket(parameters, phase, packet));
+            submissionGate.assertAcceptable(output.status);
+            return {
+              content: [{ type: "text" as const, text: "Fixer report accepted" }],
+              details: output,
+              terminate: true as const,
+            };
+          },
+        });
+        pi.on("tool_call", (event) => {
+          if (event.toolName !== "bash") return;
+          const command = event.input["command"];
+          if (typeof command !== "string") return;
+          const matched = matchFixerBashForbiddenLiteral(command);
+          if (matched === undefined) return;
+          return {
+            block: true,
+            reason:
+              `Fixer blocked bash command containing forbidden literal: ${matched}`,
+          };
+        });
+        pi.on("before_agent_start", (event) => {
+          if (soul === undefined) throw new Error("Fixer soul was not loaded");
+          return {
+            systemPrompt:
+              `${event.systemPrompt}\n\n<fixer_soul>\n${soul}\n</fixer_soul>\n\n<fixer_phase>\n${phase ?? ""}\n</fixer_phase>\n\n<fix_packet>\n${packet?.instructions ?? ""}\n</fix_packet>\n\n<fixer_prerequisites>\n${JSON.stringify(packet?.prerequisites ?? [])}\n</fixer_prerequisites>`,
+          };
+        });
+      }
+    },
+    armSubmissionGate(cwd: string, parent?: { getSessionFile(): string | undefined }) {
+      submissionGate.arm(cwd, parent);
+    },
+  };
+}
+
+export function createCoderRoleRuntime(
+  pi: ExtensionAPI,
+  dependencies: CoderRoleDependencies,
+  hostActions: WorkerRoleHostActions,
+): WorkerRoleRuntime {
+  let soul: string | undefined;
+  let task: string | undefined;
+  let phase: WorkerPhase | undefined;
+  let binding: CanonicalSkillBinding<"tdd"> | undefined;
+  let tddInvocationInjected = false;
+  let originalRequest: string | undefined;
+  let expansionPending = false;
+  let expansionCaptured = false;
+  let lifecycleRegistered = false;
+  const submissionGate = createWorkerSubmissionGate();
+
+  pi.registerFlag("ak-coder-task", {
+    description: "Markdown task assigned to the coder role",
+    type: "string",
+  });
+  pi.registerFlag("ak-coder-phase", {
+    description:
+      "Coder phase: plan (inspect and propose an implementation plan; no edits or commits) or apply (execute the approved plan and verify the first implementation)",
+    type: "string",
+  });
+
+  return {
+    async activate(ctx) {
+      soul = (await dependencies.loadSoul()).trim();
+      if (soul.length === 0) throw new Error("Coder soul is empty");
+      const selectedPhase = pi.getFlag("ak-coder-phase");
+      if (selectedPhase !== "plan" && selectedPhase !== "apply") {
+        throw new Error(
+          "Coder role requires --ak-coder-phase plan|apply; no other phase is supported",
+        );
+      }
+      phase = selectedPhase;
+      const taskPath = pi.getFlag("ak-coder-task");
+      if (typeof taskPath !== "string" || taskPath.trim().length === 0) {
+        throw new Error("Coder role requires --ak-coder-task");
+      }
+      task = (await dependencies.loadTask(taskPath)).trim();
+      if (task.length === 0) throw new Error("Coder task is empty");
+      binding = undefined;
+      if (phase === "apply") {
+        if (dependencies.loadCanonicalSkillBinding === undefined) {
+          throw new Error("Coder canonical Skill binding loader is not configured");
+        }
+        try {
+          const loaded = await dependencies.loadCanonicalSkillBinding("tdd");
+          if (loaded.name !== "tdd") {
+            throw new Error(
+              "Canonical Skill binding loader returned code-review for tdd",
+            );
+          }
+          binding = loaded;
+        } catch (error) {
+          if (ctx === undefined) throw error;
+          hostActions.failInfrastructure(error, ctx);
+        }
+      }
+
+      if (!lifecycleRegistered) {
+        lifecycleRegistered = true;
+        pi.registerTool({
+          name: CODER_OUTPUT_TOOL_NAME,
+          label: "Coder Output",
+          description:
+            "Submit a plan, completion, unfinished handoff, or evidence-bearing refusal for the active coder phase.",
+          promptSnippet: "Submit the final coder report",
+          promptGuidelines: [
+            `Use ${CODER_OUTPUT_TOOL_NAME} as the final action for the coder role.`,
+            `${CODER_OUTPUT_TOOL_NAME} never escalates; explain authority or task conflicts in report for the caller to dispose.`,
+            "plan permits planned|refused; apply permits completed|unfinished|refused. unfinished requires a non-blank remainingScope.",
+            "A completed apply report must preserve evidence for TDD, the same-pattern check, introduced-regression check, and behavior-fact check.",
+          ],
+          parameters: coderOutputSchema,
+          async execute(toolCallId, parameters, _signal, _onUpdate, ctx) {
+            if (task === undefined || phase === undefined) {
+              throw new Error("Coder task and phase were not loaded");
+            }
+            requireSingletonSubmissionCall(
+              toolCallId,
+              CODER_OUTPUT_TOOL_NAME,
+              "Coder",
+              ctx,
+            );
+            const output = validateWorkerOutput(parameters, phase, "Coder");
+            if (
+              phase === "apply" && output.status === "completed" &&
+              !expansionCaptured
+            ) {
+              throw new Error(
+                "Coder completed requires the Matt tdd skill to be expanded through Pi /skill:tdd",
+              );
+            }
+            submissionGate.assertAcceptable(output.status);
+            return {
+              content: [{ type: "text" as const, text: "Coder report accepted" }],
+              details: output,
+              terminate: true as const,
+            };
+          },
+        });
+        pi.on("input", (event) => {
+          if (phase !== "apply" || tddInvocationInjected) {
+            return { action: "continue" as const };
+          }
+          tddInvocationInjected = true;
+          expansionPending = true;
+          const isNativeTdd =
+            event.text === "/skill:tdd" ||
+            event.text.startsWith("/skill:tdd ");
+          if (isNativeTdd) {
+            originalRequest = event.text.slice("/skill:tdd".length).trim();
+            return { action: "continue" as const };
+          }
+          originalRequest = event.text.trim();
+          return {
+            action: "transform" as const,
+            text: binding?.invocation(event.text) ?? `/skill:tdd ${event.text}`,
+            ...(event.images === undefined ? {} : { images: event.images }),
+          };
+        });
+        pi.on("before_agent_start", (event, ctx) => {
+          if (soul === undefined) throw new Error("Coder soul was not loaded");
+          if (phase === "apply") {
+            if (binding === undefined) {
+              hostActions.failInfrastructure(
+                new Error("Coder canonical tdd Skill binding was not initialized"),
+                ctx,
+              );
+            }
+            if (expansionPending) {
+              expansionPending = false;
+              if (originalRequest !== undefined) {
+                expansionCaptured = binding.captureExpansion(
+                  event.prompt,
+                  originalRequest,
+                ) !== undefined;
+              }
+            }
+          }
+          return {
+            systemPrompt:
+              `${event.systemPrompt}\n\n<coder_soul>\n${soul}\n</coder_soul>\n\n<coder_phase>\n${phase ?? ""}\n</coder_phase>\n\n<coder_task>\n${task ?? ""}\n</coder_task>`,
+          };
+        });
+      }
+    },
+    armSubmissionGate(cwd: string, parent?: { getSessionFile(): string | undefined }) {
+      submissionGate.arm(cwd, parent);
+    },
+  };
+}