@akagilnc/pi-workflow-roles 0.1.1751

package/src/package-contracts/fixer-packet.ts

@@ -0,0 +1,93 @@
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+
+export const FIXER_PREREQUISITE_ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9._-]*$";
+
+export const fixerPrerequisiteSchema = Type.Object({
+  id: Type.String({ pattern: FIXER_PREREQUISITE_ID_PATTERN }),
+  requirement: Type.String({ pattern: "\\S" }),
+}, { additionalProperties: false });
+
+export const fixerPrerequisitesSchema = Type.Array(fixerPrerequisiteSchema);
+export type FixerPrerequisite = Readonly<Static<typeof fixerPrerequisiteSchema>>;
+export type FixerInvocationInput = Readonly<{
+  instructions: string;
+  prerequisites: readonly FixerPrerequisite[];
+}>;
+
+function causeMessage(cause: unknown): string {
+  if (cause instanceof Error) return cause.message;
+  if (typeof cause === "string") return cause;
+  try {
+    return JSON.stringify(cause) ?? String(cause);
+  } catch {
+    return String(cause);
+  }
+}
+
+export class FixerPacketValidationError extends Error {
+  readonly code = "AK_INVALID_FIX_PACKET";
+
+  constructor(cause?: unknown) {
+    const prefix = "Fixer prerequisites or instructions violate the invocation contract";
+    super(
+      cause === undefined ? prefix : `${prefix}: ${causeMessage(cause)}`,
+      cause === undefined ? undefined : { cause },
+    );
+    this.name = "FixerPacketValidationError";
+  }
+}
+
+function fail(cause: unknown): never {
+  throw new FixerPacketValidationError(cause);
+}
+
+function parseFailure(value: unknown): never {
+  if (!Array.isArray(value)) fail(new Error("Fixer prerequisites must be a JSON array"));
+  for (const entry of value) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      fail(new Error("Fixer prerequisite entry must be an object with id and requirement fields"));
+    }
+    const keys = Object.keys(entry);
+    if (keys.length !== 2 || !keys.includes("id") || !keys.includes("requirement")) {
+      fail(new Error("Fixer prerequisite entry fields must be exactly id and requirement"));
+    }
+    if (
+      typeof (entry as Record<string, unknown>).id !== "string" ||
+      !(new RegExp(FIXER_PREREQUISITE_ID_PATTERN)).test((entry as { id: string }).id)
+    ) {
+      fail(new Error(`Fixer prerequisite id violates pattern ${FIXER_PREREQUISITE_ID_PATTERN}`));
+    }
+    if (
+      typeof (entry as Record<string, unknown>).requirement !== "string" ||
+      !/\S/.test((entry as { requirement: string }).requirement)
+    ) {
+      fail(new Error("Fixer prerequisite requirement must be nonblank"));
+    }
+  }
+  fail(new Error("Fixer prerequisites violate the attachment schema"));
+}
+
+export function validateFixerPrerequisites(value: unknown): readonly FixerPrerequisite[] {
+  if (!Value.Check(fixerPrerequisitesSchema, value)) parseFailure(value);
+  const entries = value as Static<typeof fixerPrerequisitesSchema>;
+  const ids = new Set<string>();
+  const prerequisites = entries.map((entry) => {
+    if (ids.has(entry.id)) {
+      fail(new Error(`Fixer prerequisites contain duplicate id: ${entry.id}`));
+    }
+    ids.add(entry.id);
+    return Object.freeze({ id: entry.id, requirement: entry.requirement });
+  });
+  return Object.freeze(prerequisites);
+}
+
+export function parseFixerPrerequisites(source: string): readonly FixerPrerequisite[] {
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(source);
+  } catch (error) {
+    fail(error);
+  }
+  return validateFixerPrerequisites(decoded);
+}

package/src/package-contracts/judge-output.ts

@@ -0,0 +1,39 @@
+/** Package-owned Judge output leaf — no role registration surface. */
+
+export const JUDGE_OUTPUT_TOOL_NAME = "ak_judge_output";
+export const JUDGE_ACCEPTED_TEXT = "Judge verdict accepted";
+
+export type JudgeClass = {
+  name: string;
+  owner: string;
+  boundary: string;
+  disposition: string;
+};
+
+export type JudgeVerdict =
+  | { judgeStatus: "converged"; note?: string; evidence?: unknown }
+  | {
+    judgeStatus: "continue";
+    fix: { summary: string };
+    classes: JudgeClass[];
+    note?: string;
+    evidence?: unknown;
+  }
+  | {
+    judgeStatus: "escalate";
+    decisionGate: { question: string; options: string[] };
+    note?: string;
+    evidence?: unknown;
+  };
+
+export function validateAcceptedJudgeDetails(verdict: unknown): JudgeVerdict {
+  if (verdict === null || typeof verdict !== "object" || Array.isArray(verdict)) throw new Error("Judge verdict has no execution discriminator");
+  let judgeStatus: unknown;
+  try {
+    judgeStatus = (verdict as Record<string, unknown>).judgeStatus;
+  } catch {
+    throw new Error("Judge verdict has no execution discriminator");
+  }
+  if (["converged", "continue", "escalate"].includes(String(judgeStatus))) return verdict as JudgeVerdict;
+  throw new Error("Judge verdict has no execution discriminator");
+}

package/src/package-contracts/reviewer-output.ts

@@ -0,0 +1,115 @@
+/** Package-owned Reviewer intent and runtime-receipt leaves — no role registration surface. */
+
+import type { ReviewerAcceptedEvidence, ReviewerFailureClassification, ReviewerWorkspaceDisposition } from "../reviewer-execution-ledger.ts";
+
+export const REVIEWER_OUTPUT_TOOL_NAME = "ak_reviewer_output";
+export const REVIEWER_ACCEPTED_TEXT = "Reviewer report accepted";
+
+export type ReviewerIntent =
+  | Readonly<{ status: "completed" }>
+  | Readonly<{ status: "refused"; diagnostic: string }>;
+/** Child report is plain text — no length/digest identity shell (ADR 0031). */
+export type VerbatimChildReport = Readonly<{ text: string }>;
+/** Prompt projection on the receipt face is plain text (ADR 0031). */
+export type ReviewerReceiptPrompt = Readonly<{ text: string }>;
+/** Canonical Skill content on the receipt face is plain text (ADR 0031/0032). */
+export type ReviewerReceiptSkillContent = Readonly<{ text: string }>;
+type RuntimeReviewerOutcomeCommon = Readonly<{
+  prompt: ReviewerReceiptPrompt;
+  workspaceDisposition: ReviewerWorkspaceDisposition;
+}>;
+export type RuntimeReviewerOutcome = RuntimeReviewerOutcomeCommon & (
+  | Readonly<{ status: "successful"; failure?: never }>
+  | Readonly<{ status: "failed"; failure: ReviewerFailureClassification; diagnostic: string }>
+);
+export type RuntimeReviewerAcceptedBatch = Readonly<{
+  identity: string;
+  legs: readonly Readonly<{ axis: "standards" | "spec"; prompt: ReviewerReceiptPrompt }>[];
+}>;
+export type RuntimeReviewerReceiptV2 = Readonly<{
+  version: 2;
+  status: "completed" | "refused";
+  diagnostic?: string;
+  acceptedBatch?: RuntimeReviewerAcceptedBatch;
+  reports: Readonly<Partial<Record<"standards" | "spec", VerbatimChildReport>>>;
+  outcomes: Readonly<Partial<Record<"standards" | "spec", RuntimeReviewerOutcome>>>;
+  identities: Readonly<{
+    canonicalSkill: ReviewerReceiptSkillContent;
+    construction?: Readonly<{ recipe: ReviewerAcceptedEvidence["recipe"] }>;
+    target?: ReviewerAcceptedEvidence["target"];
+  }>;
+}>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function read(value: unknown, key: string): unknown {
+  if (!isRecord(value)) return undefined;
+  try { return value[key]; } catch { return undefined; }
+}
+
+export function validateReviewerIntent(output: unknown): ReviewerIntent {
+  const status = read(output, "status");
+  if (status === "completed") return { status };
+  if (status === "refused") return { status, diagnostic: read(output, "diagnostic") as string };
+  throw new Error("Reviewer output has no recognized execution intent");
+}
+
+/** Validate runtime-owned facts at their real identity seams (target pins + plain text). */
+export function validateRuntimeReviewerReceipt(output: unknown): RuntimeReviewerReceiptV2 {
+  const acceptedBatch = read(output, "acceptedBatch");
+  const identities = read(output, "identities");
+  const construction = read(identities, "construction");
+  const target = read(identities, "target");
+  const reports = read(output, "reports");
+  const outcomes = read(output, "outcomes");
+  const legs = read(acceptedBatch, "legs");
+
+  // A recognizable accepted batch must remain bound to its exact target pin.
+  if (acceptedBatch !== undefined || construction !== undefined || target !== undefined) {
+    if (!isRecord(acceptedBatch) || !isRecord(construction) || !isRecord(target) || !Array.isArray(legs))
+      throw new Error("Incomplete Reviewer accepted-batch identity");
+    const objectFormat = read(target, "objectFormat");
+    const objectId = (value: unknown): boolean => typeof value === "string" && new RegExp(objectFormat === "sha1" ? "^[0-9a-f]{40}$" : "^[0-9a-f]{64}$").test(value);
+    const refs = read(target, "refs");
+    const skillText = read(read(identities, "canonicalSkill"), "text");
+    if (typeof skillText !== "string" ||
+        read(construction, "recipe") !== "reviewer-common-bundle-v1" ||
+        (objectFormat !== "sha1" && objectFormat !== "sha256") || !objectId(read(target, "targetHead")) || !isRecord(refs) ||
+        Object.values(refs).some((ref) => !isRecord(ref) || !objectId(read(ref, "objectId")) || (read(ref, "peeledCommitId") !== null && !objectId(read(ref, "peeledCommitId")))))
+      throw new Error("Invalid Reviewer construction or target identity");
+
+    const expectedAxes = legs.map((leg) => read(leg, "axis"));
+    if (expectedAxes[0] !== "standards" || (expectedAxes.length === 2 && expectedAxes[1] !== "spec") || expectedAxes.length < 1 || expectedAxes.length > 2)
+      throw new Error("Invalid Reviewer accepted-leg projection");
+    if (!isRecord(outcomes) || !isRecord(reports)) throw new Error("Accepted Reviewer batch lacks outcomes or reports");
+    const outcomeAxes = Object.keys(outcomes).filter(axis => axis === "standards" || axis === "spec");
+    if (outcomeAxes.length !== expectedAxes.length || outcomeAxes.some((axis, index) => axis !== expectedAxes[index]))
+      throw new Error("Reviewer outcomes must exactly cover accepted legs in canonical order");
+
+    for (const [index, axisValue] of expectedAxes.entries()) {
+      const axis = axisValue as "standards" | "spec";
+      const outcome = read(outcomes, axis);
+      if (!isRecord(outcome)) throw new Error("Reviewer accepted leg lacks outcome");
+      const expectedPrompt = read(read(legs[index], "prompt"), "text");
+      const actualPrompt = read(read(outcome, "prompt"), "text");
+      if (expectedPrompt !== actualPrompt) throw new Error("Reviewer outcome prompt disagrees with accepted leg");
+      const status = read(outcome, "status");
+      const report = read(reports, axis);
+      if (status === "successful" && report === undefined)
+        throw new Error("Successful Reviewer outcome lacks report");
+      if (status === "failed" && report !== undefined) throw new Error("Failed Reviewer outcome cannot bind a report");
+    }
+  }
+  return output as RuntimeReviewerReceiptV2;
+}
+
+/** Project thin submitted intent onto runtime enrichment without comparing runtime-owned fields. */
+export function projectReviewerIntentToReceipt(intentValue: unknown, receiptValue: unknown): RuntimeReviewerReceiptV2 {
+  const intent = validateReviewerIntent(intentValue);
+  const receipt = validateRuntimeReviewerReceipt(receiptValue);
+  if (receipt.status !== intent.status || (intent.status === "completed" ? receipt.diagnostic !== undefined : receipt.diagnostic !== intent.diagnostic)) {
+    throw new Error("Reviewer intent and runtime receipt disagree");
+  }
+  return receipt;
+}

package/src/package-contracts/terminating-tools.ts

@@ -0,0 +1,259 @@
+/**
+ * Package-owned terminating tool registry.
+ * Package roles share these terminating leaves.
+ */
+
+import {
+  COLLECTOR_ACCEPTED_TEXT,
+  COLLECTOR_OUTPUT_TOOL,
+  validateAcceptedCollectorReceipt,
+  type CollectorReceipt,
+} from "./collector-output.ts";
+import {
+  JUDGE_ACCEPTED_TEXT,
+  JUDGE_OUTPUT_TOOL_NAME,
+  validateAcceptedJudgeDetails,
+  type JudgeVerdict,
+} from "./judge-output.ts";
+import {
+  REVIEWER_ACCEPTED_TEXT,
+  REVIEWER_OUTPUT_TOOL_NAME,
+  projectReviewerIntentToReceipt,
+  validateReviewerIntent,
+  validateRuntimeReviewerReceipt,
+  type ReviewerIntent,
+  type RuntimeReviewerReceiptV2,
+} from "./reviewer-output.ts";
+import { isAuditEscalationResult } from "../audit-escalation.ts";
+import { DOCTOR_OUTPUT_TOOL_NAME, validateDoctorSubmissionShape, validateRecordedDoctorOutput, type DoctorOutput, type DoctorSubmission } from "../doctor-contracts.ts";
+import { MERGER_ACCEPTED_TEXT, MERGER_OUTPUT_TOOL_NAME, validateMergerOutput, type MergerOutput } from "../merger-contracts.ts";
+import {
+  CODER_ACCEPTED_TEXT,
+  CODER_OUTPUT_TOOL_NAME,
+  FIXER_ACCEPTED_TEXT,
+  FIXER_OUTPUT_TOOL_NAME,
+  validateAcceptedWorkerDetails,
+  type WorkerOutput,
+} from "./worker-output.ts";
+
+export {
+  CODER_ACCEPTED_TEXT,
+  CODER_OUTPUT_TOOL_NAME,
+  COLLECTOR_ACCEPTED_TEXT,
+  COLLECTOR_OUTPUT_TOOL,
+  FIXER_ACCEPTED_TEXT,
+  FIXER_OUTPUT_TOOL_NAME,
+  JUDGE_ACCEPTED_TEXT,
+  JUDGE_OUTPUT_TOOL_NAME,
+  REVIEWER_ACCEPTED_TEXT,
+  REVIEWER_OUTPUT_TOOL_NAME,
+  MERGER_ACCEPTED_TEXT,
+  MERGER_OUTPUT_TOOL_NAME,
+  validateAcceptedCollectorReceipt,
+  validateAcceptedJudgeDetails,
+  projectReviewerIntentToReceipt,
+  validateReviewerIntent,
+  validateRuntimeReviewerReceipt,
+  validateAcceptedWorkerDetails,
+  validateDoctorSubmissionShape,
+  validateRecordedDoctorOutput,
+  validateMergerOutput,
+};
+export type {
+  CollectorReceipt,
+  JudgeVerdict,
+  ReviewerIntent,
+  RuntimeReviewerReceiptV2,
+  WorkerOutput,
+  DoctorOutput,
+  DoctorSubmission,
+  MergerOutput,
+};
+
+export const TERMINATING_TOOL_NAMES = [
+  CODER_OUTPUT_TOOL_NAME,
+  FIXER_OUTPUT_TOOL_NAME,
+  REVIEWER_OUTPUT_TOOL_NAME,
+  JUDGE_OUTPUT_TOOL_NAME,
+  COLLECTOR_OUTPUT_TOOL,
+  DOCTOR_OUTPUT_TOOL_NAME,
+  MERGER_OUTPUT_TOOL_NAME,
+] as const;
+
+export type TerminatingToolName = (typeof TERMINATING_TOOL_NAMES)[number];
+
+export type AcceptedDetails =
+  | WorkerOutput
+  | RuntimeReviewerReceiptV2
+  | JudgeVerdict
+  | CollectorReceipt
+  | DoctorOutput
+  | MergerOutput;
+
+export function isTerminatingToolName(
+  name: string,
+): name is TerminatingToolName {
+  return (TERMINATING_TOOL_NAMES as readonly string[]).includes(name);
+}
+
+export function acceptedTextFor(toolName: TerminatingToolName): string {
+  switch (toolName) {
+    case CODER_OUTPUT_TOOL_NAME:
+      return CODER_ACCEPTED_TEXT;
+    case FIXER_OUTPUT_TOOL_NAME:
+      return FIXER_ACCEPTED_TEXT;
+    case REVIEWER_OUTPUT_TOOL_NAME:
+      return REVIEWER_ACCEPTED_TEXT;
+    case JUDGE_OUTPUT_TOOL_NAME:
+      return JUDGE_ACCEPTED_TEXT;
+    case COLLECTOR_OUTPUT_TOOL:
+      return COLLECTOR_ACCEPTED_TEXT;
+    case DOCTOR_OUTPUT_TOOL_NAME:
+      return "Doctor output accepted";
+    case MERGER_OUTPUT_TOOL_NAME:
+      return MERGER_ACCEPTED_TEXT;
+  }
+}
+
+export class AcceptedDetailsContractError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "AcceptedDetailsContractError";
+  }
+}
+
+function safeProperty(candidate: Record<string, unknown> | undefined, property: string): unknown {
+  try {
+    return candidate?.[property];
+  } catch {
+    return undefined;
+  }
+}
+
+export function validateAcceptedDetails(
+  toolName: TerminatingToolName,
+  details: unknown,
+): AcceptedDetails {
+  const candidate = details !== null && typeof details === "object" && !Array.isArray(details)
+    ? details as Record<string, unknown>
+    : undefined;
+  let auditEscalation = false;
+  try {
+    auditEscalation = isAuditEscalationResult(details);
+  } catch {
+    // Hostile getters are not recognizable audit escalation evidence.
+  }
+  if (auditEscalation || safeProperty(candidate, "kind") === "audit_escalation") {
+    throw new AcceptedDetailsContractError(
+      "audit escalation is not an accepted role receipt",
+    );
+  }
+  const discriminator = safeProperty(candidate, toolName === JUDGE_OUTPUT_TOOL_NAME ? "judgeStatus" : "status");
+  const lawfulStatuses: Readonly<Record<TerminatingToolName, readonly string[]>> = {
+    [CODER_OUTPUT_TOOL_NAME]: ["planned", "completed", "refused", "unfinished"],
+    [FIXER_OUTPUT_TOOL_NAME]: ["planned", "completed", "refused", "partially_completed", "unfinished"],
+    [REVIEWER_OUTPUT_TOOL_NAME]: ["completed", "refused"],
+    [JUDGE_OUTPUT_TOOL_NAME]: ["converged", "continue", "escalate"],
+    [COLLECTOR_OUTPUT_TOOL]: [],
+    [DOCTOR_OUTPUT_TOOL_NAME]: ["completed", "refused"],
+    [MERGER_OUTPUT_TOOL_NAME]: ["completed", "escalate"],
+  };
+  const collectorDiscriminator = toolName === COLLECTOR_OUTPUT_TOOL && Array.isArray(candidate?.groups);
+  const runtimeBindingMissing =
+    (toolName === DOCTOR_OUTPUT_TOOL_NAME && discriminator === "completed" && !(candidate?.cost !== null && typeof candidate?.cost === "object")) ||
+    (toolName === REVIEWER_OUTPUT_TOOL_NAME && candidate?.version !== 2);
+  if (runtimeBindingMissing || (!collectorDiscriminator && (typeof discriminator !== "string" || !lawfulStatuses[toolName].includes(discriminator)))) {
+    throw new AcceptedDetailsContractError("terminating receipt has no recognized execution discriminator");
+  }
+  try {
+    switch (toolName) {
+    case CODER_OUTPUT_TOOL_NAME:
+      return validateAcceptedWorkerDetails(details, "Coder");
+    case FIXER_OUTPUT_TOOL_NAME:
+      return validateAcceptedWorkerDetails(details, "Fixer");
+    case REVIEWER_OUTPUT_TOOL_NAME:
+      return validateRuntimeReviewerReceipt(details);
+    case JUDGE_OUTPUT_TOOL_NAME:
+      return validateAcceptedJudgeDetails(details);
+    case COLLECTOR_OUTPUT_TOOL:
+      return validateAcceptedCollectorReceipt(details);
+    case DOCTOR_OUTPUT_TOOL_NAME:
+      return validateRecordedDoctorOutput(details);
+    case MERGER_OUTPUT_TOOL_NAME:
+      return validateMergerOutput(details);
+    }
+  } catch (error) {
+    if (error instanceof Error && error.constructor === Error) throw new AcceptedDetailsContractError(error.message, { cause: error });
+    throw error;
+  }
+}
+
+export function validateAcceptedLifecycle(
+  toolName: TerminatingToolName,
+  argumentsValue: unknown,
+  detailsValue: unknown,
+): AcceptedDetails {
+  const details = validateAcceptedDetails(toolName, detailsValue);
+  if (toolName === DOCTOR_OUTPUT_TOOL_NAME) {
+    const testimony = validateDoctorSubmissionShape(argumentsValue);
+    if (testimony.status === "refused") {
+      if (!deepEqual(testimony, details)) throw new Error("accepted tool lifecycle details mismatch");
+      return details;
+    }
+    const receipt = details as DoctorOutput;
+    if (receipt.status !== "completed") throw new Error("accepted tool lifecycle details mismatch");
+    const { cost: _runtimeCost, ...projected } = receipt;
+    if (!deepEqual(testimony, projected)) throw new Error("accepted tool lifecycle details mismatch");
+    return details;
+  }
+  const argumentsDetails = validateAcceptedDetails(toolName, argumentsValue);
+  if (!deepEqual(argumentsDetails, details)) throw new Error("accepted tool lifecycle details mismatch");
+  return details;
+}
+
+/** Machine-facing facts from an accepted terminating receipt. No presentation joins. */
+export type AcceptedFacts = {
+  status?: string;
+  commit?: string;
+};
+
+export function acceptedFacts(toolName: TerminatingToolName, details: AcceptedDetails): AcceptedFacts {
+  switch (toolName) {
+    case CODER_OUTPUT_TOOL_NAME:
+    case FIXER_OUTPUT_TOOL_NAME:
+    case REVIEWER_OUTPUT_TOOL_NAME:
+    case DOCTOR_OUTPUT_TOOL_NAME: return { status: (details as { status: string }).status };
+    case JUDGE_OUTPUT_TOOL_NAME: return { status: (details as { judgeStatus: string }).judgeStatus };
+    case MERGER_OUTPUT_TOOL_NAME: {
+      const output = details as unknown as Record<string, unknown>;
+      return { status: output.status as string, ...(output.status === "completed" && typeof output.mergeCommitId === "string" ? { commit: output.mergeCommitId } : {}) };
+    }
+    case COLLECTOR_OUTPUT_TOOL:
+      return { status: "collected" };
+  }
+}
+
+/** Deep structural equality for lifecycle agreement checks. */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return a === b;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, index) => deepEqual(item, b[index]));
+  }
+  if (typeof a === "object") {
+    if (typeof b !== "object" || b === null || Array.isArray(b)) return false;
+    const aKeys = Object.keys(a as object).sort();
+    const bKeys = Object.keys(b as object).sort();
+    if (aKeys.length !== bKeys.length) return false;
+    if (!aKeys.every((key, index) => key === bKeys[index])) return false;
+    return aKeys.every((key) =>
+      deepEqual(
+        (a as Record<string, unknown>)[key],
+        (b as Record<string, unknown>)[key],
+      )
+    );
+  }
+  return false;
+}

package/src/package-contracts/worker-output.ts

@@ -0,0 +1,36 @@
+/** Package-owned independent Coder and Fixer output leaves. */
+
+export {
+  FIXER_ACCEPTED_TEXT,
+  FIXER_OUTPUT_TOOL_NAME,
+  fixerOutputSchema,
+  validateFixerOutput,
+  validateFixerOutputForPacket,
+} from "./fixer-output.ts";
+export type {
+  FixerBlocker,
+  FixerClassResult,
+  FixerOutput,
+  FixerPhase,
+} from "./fixer-output.ts";
+export { fixerPrerequisiteSchema, fixerPrerequisitesSchema, parseFixerPrerequisites, validateFixerPrerequisites } from "./fixer-packet.ts";
+export type { FixerInvocationInput, FixerPrerequisite } from "./fixer-packet.ts";
+import { validateFixerOutput, type FixerOutput } from "./fixer-output.ts";
+
+export const CODER_OUTPUT_TOOL_NAME = "ak_coder_output";
+export const CODER_ACCEPTED_TEXT = "Coder report accepted";
+export type WorkerRoleLabel = "Coder" | "Fixer";
+export type CoderOutput =
+  | { status: "planned"; report: string }
+  | { status: "completed" | "refused"; report: string }
+  | { status: "unfinished"; report: string; remainingScope: string };
+export type WorkerOutput = CoderOutput | FixerOutput;
+
+export function validateAcceptedCoderDetails(output: unknown): CoderOutput {
+  return output as CoderOutput;
+}
+
+/** Structural production validator for an accepted current leaf. */
+export function validateAcceptedWorkerDetails(output: unknown, roleLabel: WorkerRoleLabel = "Coder"): WorkerOutput {
+  return roleLabel === "Fixer" ? validateFixerOutput(output) : validateAcceptedCoderDetails(output);
+}

package/src/package-owned-tool-idle.ts

@@ -0,0 +1,134 @@
+/**
+ * #102 package-owned tool idle backstop.
+ *
+ * Fixed 183000ms silence clock on package-owned tool execute only.
+ * Real producing onUpdate resets; final resolve/reject clears; timeout throws so
+ * Pi settles the current call as an LLM-visible isError tool result. No retry,
+ * role failure, process termination, signal abort, config, or Pi built-in coverage.
+ */
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+import {
+  DEFAULT_STREAM_IDLE_TIMEOUT_MS,
+  createStreamIdleGuard,
+} from "./stream-idle-guard.ts";
+import { isProducingToolUpdate } from "./tool-execution-observation.ts";
+
+export const PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS = DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+export const PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_CODE = "AK_PACKAGE_OWNED_TOOL_IDLE_TIMEOUT" as const;
+
+const WRAPPED = Symbol.for("ak.packageOwnedToolIdleWrapped");
+
+export class PackageOwnedToolIdleTimeoutError extends Error {
+  readonly code = PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_CODE;
+  readonly idleTimeoutMs = PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS;
+
+  constructor() {
+    super(`package-owned tool idle timeout after ${PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS}ms`);
+    this.name = "PackageOwnedToolIdleTimeoutError";
+  }
+}
+
+/** Minimal executable tool shape accepted by the shared idle wrapper. */
+export type PackageOwnedToolLike = {
+  readonly name: string;
+  execute: (...args: never[]) => Promise<unknown>;
+};
+
+/**
+ * Package-tool activity includes content production and host-only details
+ * progress. Keep the observation-plane oracle separate: its stderr heartbeat
+ * contract remains content-driven. Pi's known execute-entry placeholder
+ * (`content: [], details: undefined`) is not activity.
+ */
+function isPackageOwnedToolActivityUpdate(partialResult: unknown): boolean {
+  if (isProducingToolUpdate(partialResult)) return true;
+  if (typeof partialResult !== "object" || partialResult === null) return false;
+  const details = (partialResult as { details?: unknown }).details;
+  if (details === undefined || details === null) return false;
+  if (typeof details === "string") return details.length > 0;
+  if (Array.isArray(details)) return details.length > 0;
+  if (typeof details === "object") return Reflect.ownKeys(details).length > 0;
+  return true;
+}
+
+/**
+ * Single shared execute wrapper for package-owned tool definitions.
+ * Idempotent: wrapping twice returns the same protected definition.
+ */
+export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(tool: T): T {
+  // Mark the execute function, not the tool object — callers may spread tool fields
+  // onto a new definition with a different execute (e.g. auditor customTools).
+  if ((tool.execute as { [WRAPPED]?: boolean })[WRAPPED] === true) return tool;
+
+  const originalExecute = tool.execute.bind(tool) as (
+    ...args: unknown[]
+  ) => Promise<unknown>;
+
+  const wrappedExecute = function packageOwnedToolIdleExecute(
+    ...args: unknown[]
+  ): Promise<unknown> {
+    const signal = args[2] as AbortSignal | undefined;
+    const onUpdate = args[3] as ((partialResult: unknown) => void) | undefined;
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const idle = createStreamIdleGuard({
+        idleTimeoutMs: PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS,
+      });
+
+      const settle = (deliver: () => void): void => {
+        if (settled) return;
+        settled = true;
+        idle.signal.removeEventListener("abort", onIdle);
+        idle.dispose();
+        deliver();
+      };
+      const onIdle = (): void => {
+        settle(() => reject(new PackageOwnedToolIdleTimeoutError()));
+      };
+      idle.signal.addEventListener("abort", onIdle, { once: true });
+
+      const guardedOnUpdate = onUpdate === undefined
+        ? undefined
+        : (partialResult: unknown) => {
+            if (settled) return;
+            if (isPackageOwnedToolActivityUpdate(partialResult)) idle.poke();
+            onUpdate(partialResult);
+          };
+
+      const callArgs = args.slice();
+      // Preserve the original signal at args[2]; timeout must not abort it.
+      callArgs[2] = signal;
+      callArgs[3] = guardedOnUpdate;
+
+      void Promise.resolve()
+        .then(() => originalExecute(...callArgs))
+        .then(
+          (result) => settle(() => resolve(result)),
+          (error: unknown) => settle(() => reject(error)),
+        );
+    });
+  };
+  (wrappedExecute as { [WRAPPED]?: boolean })[WRAPPED] = true;
+
+  return {
+    ...tool,
+    execute: wrappedExecute as T["execute"],
+  };
+}
+
+/**
+ * Install the shared registration surface on an ExtensionAPI once.
+ * All subsequent pi.registerTool calls for package-owned tools are wrapped.
+ */
+export function installPackageOwnedToolRegistration(pi: ExtensionAPI): void {
+  const current = pi.registerTool;
+  if ((current as { [WRAPPED]?: boolean })[WRAPPED] === true) return;
+
+  const original = current.bind(pi);
+  const installed = ((tool: ToolDefinition<any, any, any>) => {
+    original(wrapPackageOwnedToolDefinition(tool) as ToolDefinition<any, any, any>);
+  }) as typeof pi.registerTool;
+  (installed as { [WRAPPED]?: boolean })[WRAPPED] = true;
+  pi.registerTool = installed;
+}