@akagilnc/pi-workflow-roles 0.1.1883 → 0.1.1918

package/src/public-cli/settlement.ts

@@ -13,6 +13,13 @@ import { DOCTOR_AUDIT_TOOL_NAME } from "../doctor-auditor.ts";
 import { JUDGE_AUDIT_TOOL_NAME } from "../judge-auditor.ts";
 import { REVIEWER_AUDIT_TOOL_NAME } from "../reviewer-auditor.ts";
 import { knownFailureFromProviderStop, type ExplicitInternalKnownFailure, readReviewerDispatchRejection } from "./explicit-internal.ts";
+import {
+  isV1ResumableProvider,
+  readLatestTypedProviderHttpObservation,
+  readTypedHttp429Observation,
+  type TypedHttp429Observation,
+  type TypedProviderHttpObservation,
+} from "./run-lifecycle.ts";
 import {
   AUDITOR_COMPLIANCE_FAILURE_ENTRY_TYPE,
   AUDITOR_PARENT_ATTEMPT_BINDING_ENTRY_TYPE,
@@ -367,14 +374,16 @@ export function classifyPostAdmissionFailure(input: {
       input.knownDiagnostic !== undefined && input.knownDiagnostic.trim() !== ""
         ? input.knownDiagnostic
         : conciseChildDiagnostic(input.stderr, fallback);
-    const { code: _knownCode, timedOut: _knownTimedOut, ...knownDetails } =
+    const { timedOut: _knownTimedOut, ...knownDetails } =
       input.knownDetails ?? {};
+    const remoteCode = knownDetails.code;
     return {
       cause: input.knownCause,
       diagnostic,
       details: {
         ...knownDetails,
-        code: input.code,
+        ...(remoteCode === undefined ? {} : { code: remoteCode }),
+        exitCode: input.code,
         ...(input.timedOut ? { timedOut: true as const } : {}),
       },
       ...(input.knownIdentity === undefined
@@ -386,7 +395,7 @@ export function classifyPostAdmissionFailure(input: {
     return {
       cause: "timeout",
       diagnostic: "role run timed out",
-      details: { timedOut: true, code: input.code },
+      details: { timedOut: true, exitCode: input.code },
     };
   }
   if (input.code !== 0) {
@@ -394,27 +403,27 @@ export function classifyPostAdmissionFailure(input: {
     return {
       cause: "activation",
       diagnostic: conciseChildDiagnostic(input.stderr, fallback),
-      details: { code: input.code },
+      details: { exitCode: input.code },
     };
   }
   if (input.session?.state === "missing") {
     return {
       cause: "session",
       diagnostic: "role run left no readable session transcript",
-      details: { code: input.code, session: "missing" },
+      details: { exitCode: input.code, session: "missing" },
     };
   }
   if (input.session?.state === "unreadable") {
     return {
       cause: "session",
       diagnostic: input.session.diagnostic,
-      details: { code: input.code, session: "unreadable" },
+      details: { exitCode: input.code, session: "unreadable" },
     };
   }
   return {
     cause: "output",
     diagnostic: "role run completed without a lawful typed terminal result",
-    details: { code: input.code },
+    details: { exitCode: input.code },
   };
 }
 
@@ -448,6 +457,15 @@ type SessionMessage = {
   provider?: string;
   model?: string;
   api?: string;
+  rawStopReason?: string;
+  diagnostics?: unknown;
+  /** Typed HTTP / SDK structured fields when held on the call surface. */
+  statusCode?: number;
+  status?: number;
+  httpStatus?: number;
+  body?: unknown;
+  code?: unknown;
+  errno?: unknown;
 };
 
 type SessionEntry = {
@@ -546,19 +564,65 @@ async function readBoundSessionEntries(
 }
 
 /**
- * Latest native assistant provider-stop in a session (stopReason === "error").
+ * Latest native assistant provider-stop in a session (stopReason error|aborted).
  * Only the final assistant turn decides terminality — an older error followed by a
  * later non-error stop is not a provider failure (would wash a no-lawful-output path).
  * Typed production source for provider cause — not child stderr prose.
  */
-export function extractSessionProviderStop(
-  entries: readonly SessionEntry[],
-): {
-  stopReason: "error";
+type SessionProviderStop = {
+  stopReason: "error" | "aborted";
   errorMessage?: string;
   provider?: string;
   model?: string;
-} | undefined {
+  api?: string;
+  rawStopReason?: string;
+  diagnostics?: unknown;
+  httpStatus?: number;
+  body?: unknown;
+  code?: unknown;
+  errno?: unknown;
+};
+
+function typedHttpStatusFromMessage(message: SessionMessage): number | undefined {
+  for (const candidate of [message.httpStatus, message.statusCode, message.status]) {
+    if (typeof candidate === "number" && (candidate < 200 || candidate >= 300)) return candidate;
+  }
+  return undefined;
+}
+
+function sessionProviderStopFromAssistant(message: SessionMessage | undefined): SessionProviderStop | undefined {
+  if (message?.role !== "assistant") return undefined;
+  if (message.stopReason !== "error" && message.stopReason !== "aborted") return undefined;
+  const httpStatus = typedHttpStatusFromMessage(message);
+  return {
+    stopReason: message.stopReason,
+    // Preserve held errorMessage bytes — emptiness check must not rewrite.
+    ...(typeof message.errorMessage === "string" && message.errorMessage.trim() !== ""
+      ? { errorMessage: message.errorMessage }
+      : {}),
+    ...(typeof message.provider === "string" && message.provider.trim() !== ""
+      ? { provider: message.provider }
+      : {}),
+    ...(typeof message.model === "string" && message.model.trim() !== ""
+      ? { model: message.model }
+      : {}),
+    ...(typeof message.api === "string" && message.api.trim() !== ""
+      ? { api: message.api }
+      : {}),
+    ...(typeof message.rawStopReason === "string" && message.rawStopReason.trim() !== ""
+      ? { rawStopReason: message.rawStopReason }
+      : {}),
+    ...(message.diagnostics === undefined ? {} : { diagnostics: message.diagnostics }),
+    ...(httpStatus === undefined ? {} : { httpStatus }),
+    ...(message.body === undefined ? {} : { body: message.body }),
+    ...(message.code === undefined ? {} : { code: message.code }),
+    ...(message.errno === undefined ? {} : { errno: message.errno }),
+  };
+}
+
+export function extractSessionProviderStop(
+  entries: readonly SessionEntry[],
+): SessionProviderStop | undefined {
   // A resumed dispatch appends a typed top-level user turn to the same session.
   // Retained audit state from an older attempt must not replace the newer attempt's
   // native provider stop. Sessions without a user turn are the initial attempt.
@@ -578,14 +642,8 @@ export function extractSessionProviderStop(
     const entry = entries[i];
     if (entry?.type !== "custom" || entry.customType !== COMPLIANCE_RESPONSE_ENTRY_TYPE) continue;
     const response = isRecord(entry.data) && isRecord(entry.data.response) ? entry.data.response : undefined;
-    if (response?.role === "assistant" && response.stopReason === "error") {
-      return {
-        stopReason: "error",
-        ...(typeof response.errorMessage === "string" && response.errorMessage.trim() !== "" ? { errorMessage: response.errorMessage } : {}),
-        ...(typeof response.provider === "string" && response.provider.trim() !== "" ? { provider: response.provider } : {}),
-        ...(typeof response.model === "string" && response.model.trim() !== "" ? { model: response.model } : {}),
-      };
-    }
+    const stop = sessionProviderStopFromAssistant(response);
+    if (stop !== undefined) return stop;
     break;
   }
   for (let i = entries.length - 1; i >= attemptStart; i -= 1) {
@@ -594,19 +652,7 @@ export function extractSessionProviderStop(
     const message = entry.message;
     if (message?.role !== "assistant") continue;
     // Latest assistant in the current attempt only (reviewer-child-executor lastAssistant pattern).
-    if (message.stopReason !== "error") return undefined;
-    return {
-      stopReason: "error",
-      ...(typeof message.errorMessage === "string" && message.errorMessage.trim() !== ""
-        ? { errorMessage: message.errorMessage }
-        : {}),
-      ...(typeof message.provider === "string" && message.provider.trim() !== ""
-        ? { provider: message.provider }
-        : {}),
-      ...(typeof message.model === "string" && message.model.trim() !== ""
-        ? { model: message.model }
-        : {}),
-    };
+    return sessionProviderStopFromAssistant(message);
   }
   return undefined;
 }
@@ -614,15 +660,7 @@ export function extractSessionProviderStop(
 /** Read the bound session principal and extract a typed provider-stop, if any. */
 export async function readSessionProviderStop(
   sessionFile: string,
-): Promise<
-  | {
-      stopReason: "error";
-      errorMessage?: string;
-      provider?: string;
-      model?: string;
-    }
-  | undefined
-> {
+): Promise<SessionProviderStop | undefined> {
   try {
     const entries = await readBoundSessionEntries(sessionFile);
     return extractSessionProviderStop(entries);
@@ -662,8 +700,7 @@ export async function readBoundEvidenceChildKnownFailure(
     return {
       ...primary,
       details: {
-        ...(stop.provider === undefined ? {} : { provider: stop.provider }),
-        ...(stop.model === undefined ? {} : { model: stop.model }),
+        ...(primary.details ?? {}),
         secondaryEvidence: "evidence-child",
       },
     };
@@ -721,10 +758,10 @@ export async function readBoundAuditorKnownFailure(
       if (entry?.type !== "custom" || entry.customType !== AUDITOR_COMPLIANCE_FAILURE_ENTRY_TYPE || !isRecord(entry.data)) continue;
       const parent = isRecord(entry.data.parent) ? entry.data.parent : undefined;
       const failure = isRecord(entry.data.failure) ? entry.data.failure : undefined;
-      if (parent?.sessionId !== parentId || parent.sessionFile !== sessionFile || parent.attemptEntryId !== attemptEntryId || failure?.cause !== "provider") continue;
+      if (parent?.sessionId !== parentId || parent.sessionFile !== sessionFile || parent.attemptEntryId !== attemptEntryId || (failure?.cause !== "provider" && failure?.cause !== "unrecognized")) continue;
       const identity = isRecord(failure.identity) ? failure.identity : undefined;
       return {
-        cause: "provider",
+        cause: failure.cause === "provider" ? "provider" : "unrecognized",
         ...(identity === undefined ? {} : { identity: {
           ...(typeof identity.name === "string" ? { name: identity.name } : {}),
           ...(typeof identity.code === "string" || typeof identity.code === "number" ? { code: identity.code } : {}),
@@ -737,8 +774,7 @@ export async function readBoundAuditorKnownFailure(
     return {
       ...primary,
       details: {
-        ...(stop.provider === undefined ? {} : { provider: stop.provider }),
-        ...(stop.model === undefined ? {} : { model: stop.model }),
+        ...(primary.details ?? {}),
         secondaryEvidence: "unavailable",
       },
     };
@@ -778,26 +814,57 @@ function typedFailedTerminatingToolKnownFailure(
   return undefined;
 }
 
+/**
+ * One audited-runner resolution: knownFailure plus the typed-HTTP sidecar outcome
+ * from the same read. Callers that also decide v1 resume must consume this once —
+ * never re-read the sidecar in presentControlledFailure.
+ */
+export type AuditedRunnerFailureResolution = {
+  readonly knownFailure?: ExplicitInternalKnownFailure;
+  /** Successful sidecar read (not absence). */
+  readonly typedHttpObservation?: TypedProviderHttpObservation;
+  /**
+   * True when this resolution already performed the typed-HTTP sidecar read
+   * (success, absence, or non-absence failure folded into knownFailure).
+   * False when an earlier evidence tier short-circuited before the sidecar.
+   */
+  readonly typedHttpObservationSettled: boolean;
+};
+
+function resolutionOf(
+  knownFailure: ExplicitInternalKnownFailure | undefined,
+  typedHttp: {
+    readonly settled: boolean;
+    readonly observation?: TypedProviderHttpObservation;
+  } = { settled: false },
+): AuditedRunnerFailureResolution {
+  return {
+    ...(knownFailure === undefined ? {} : { knownFailure }),
+    ...(typedHttp.observation === undefined ? {} : { typedHttpObservation: typedHttp.observation }),
+    typedHttpObservationSettled: typedHttp.settled,
+  };
+}
+
 /** Sole evidence-priority owner for public runners with Soul auditors. */
-export async function resolveAuditedRunnerKnownFailure(input: {
+export async function resolveAuditedRunnerFailureResolution(input: {
   runner: ExplicitInternalKnownFailure | undefined;
   sessionFile: string;
   credential: ExplicitInternalKnownFailure | undefined;
   /** Reviewer only: recover child-written rejection page into knownFailure.details. */
   runDirectory?: string;
-}): Promise<ExplicitInternalKnownFailure | undefined> {
-  if (input.runner !== undefined) return input.runner;
+}): Promise<AuditedRunnerFailureResolution> {
+  if (input.runner !== undefined) return resolutionOf(input.runner);
   if (input.runDirectory !== undefined) {
     try {
       const rejection = await readReviewerDispatchRejection(input.runDirectory);
-      if (rejection !== undefined) return rejection;
+      if (rejection !== undefined) return resolutionOf(rejection);
     } catch (error) {
       const failure = error instanceof Error ? error : new Error(String(error));
-      return {
+      return resolutionOf({
         cause: "activation",
         identity: thrownIdentity(failure),
         diagnostic: failure.message || failure.name,
-      };
+      });
     }
   }
   // Bound auditor evidence outranks a parent failure that the auditor path itself
@@ -805,24 +872,28 @@ export async function resolveAuditedRunnerKnownFailure(input: {
   // it outranks provider/credential and nonzero fallbacks, but not its recorded cause.
   try {
     const auditorFailure = await readBoundAuditorKnownFailure(input.sessionFile);
-    if (auditorFailure !== undefined) return auditorFailure;
+    if (auditorFailure !== undefined) return resolutionOf(auditorFailure);
   } catch (error) {
     const failure = sessionReadFailure(error, "failed to recover bound auditor failure");
-    return {
+    return resolutionOf({
       cause: "session",
       identity: thrownIdentity(failure),
       diagnostic: failure.message || failure.name,
-    };
+    });
   }
   try {
     const terminatingFailure = typedFailedTerminatingToolKnownFailure(
       await readBoundSessionEntries(input.sessionFile),
     );
-    if (terminatingFailure !== undefined) return terminatingFailure;
+    if (terminatingFailure !== undefined) return resolutionOf(terminatingFailure);
   } catch (error) {
     if (!isMissingPathError(error)) {
       const failure = sessionReadFailure(error, "failed to recover typed terminating-tool failure");
-      return { cause: "session", identity: thrownIdentity(failure), diagnostic: failure.message || failure.name };
+      return resolutionOf({
+        cause: "session",
+        identity: thrownIdentity(failure),
+        diagnostic: failure.message || failure.name,
+      });
     }
   }
   // Reviewer axis evidence-children are next: fixed two-axis dispatch fails
@@ -830,19 +901,138 @@ export async function resolveAuditedRunnerKnownFailure(input: {
   // fallback; credential is last.
   try {
     const evidenceChildFailure = await readBoundEvidenceChildKnownFailure(input.sessionFile);
-    if (evidenceChildFailure !== undefined) return evidenceChildFailure;
+    if (evidenceChildFailure !== undefined) return resolutionOf(evidenceChildFailure);
   } catch (error) {
     const failure = sessionReadFailure(error, "failed to recover bound evidence-child failure");
-    return {
+    return resolutionOf({
       cause: "session",
       identity: thrownIdentity(failure),
       diagnostic: failure.message || failure.name,
-    };
+    });
   }
   const parentStop = await readSessionProviderStop(input.sessionFile);
-  return parentStop === undefined
-    ? input.credential
-    : knownFailureFromProviderStop(parentStop);
+  // Typed HTTP observation: ENOENT=absence; other read/parse/shape failures keep real cause.
+  // This is the single sidecar read for both knownFailure projection and v1 resume.
+  let httpObservation: TypedProviderHttpObservation | undefined;
+  if (input.runDirectory !== undefined) {
+    try {
+      httpObservation = await readLatestTypedProviderHttpObservation(input.runDirectory);
+    } catch (error) {
+      const failure = error instanceof Error ? error : new Error(String(error));
+      return resolutionOf(
+        {
+          cause: "session",
+          identity: thrownIdentity(failure),
+          diagnostic: failure.message || failure.name,
+        },
+        { settled: true },
+      );
+    }
+  }
+  const typedHttp = {
+    settled: input.runDirectory !== undefined,
+    ...(httpObservation === undefined ? {} : { observation: httpObservation }),
+  };
+  if (parentStop === undefined) {
+    if (input.credential !== undefined) return resolutionOf(input.credential, typedHttp);
+    if (httpObservation === undefined) return resolutionOf(undefined, typedHttp);
+    // Project the HTTP observation's status + provider/source association.
+    return resolutionOf(
+      knownFailureFromProviderStop({
+        stopReason: "error",
+        httpStatus: httpObservation.httpStatus,
+        provider: httpObservation.provider,
+      }),
+      typedHttp,
+    );
+  }
+  return resolutionOf(
+    knownFailureFromProviderStop({
+      ...parentStop,
+      ...(httpObservation === undefined
+        ? {}
+        : {
+          httpStatus: httpObservation.httpStatus,
+          // Observation association outranks session-configured provider name alone.
+          provider: httpObservation.provider,
+        }),
+    }),
+    typedHttp,
+  );
+}
+
+/** Sole evidence-priority owner for public runners with Soul auditors. */
+export async function resolveAuditedRunnerKnownFailure(input: {
+  runner: ExplicitInternalKnownFailure | undefined;
+  sessionFile: string;
+  credential: ExplicitInternalKnownFailure | undefined;
+  /** Reviewer only: recover child-written rejection page into knownFailure.details. */
+  runDirectory?: string;
+}): Promise<ExplicitInternalKnownFailure | undefined> {
+  return (await resolveAuditedRunnerFailureResolution(input)).knownFailure;
+}
+
+/**
+ * v1 resume observation for controlled-failure settlement — at most one sidecar read.
+ * Prefer the pre-resolved outcome from resolveAuditedRunnerFailureResolution.
+ * Non-absence failures never throw: they return observationReadFailure for the
+ * existing controlled-failure → error.json chain.
+ */
+export async function resolveControlledFailureResumeObservation(input: {
+  readonly runDirectory: string;
+  readonly typedHttpObservationSettled?: boolean;
+  readonly typedHttpObservation?: TypedProviderHttpObservation;
+}): Promise<{
+  readonly typedHttp429?: TypedHttp429Observation;
+  readonly observationReadFailure?: ExplicitInternalKnownFailure;
+}> {
+  if (input.typedHttpObservationSettled === true) {
+    const observation = input.typedHttpObservation;
+    if (
+      observation !== undefined &&
+      observation.httpStatus === 429 &&
+      isV1ResumableProvider(observation.provider)
+    ) {
+      return {
+        typedHttp429: { httpStatus: 429, provider: observation.provider },
+      };
+    }
+    return {};
+  }
+  try {
+    const typedHttp429 = await readTypedHttp429Observation(input.runDirectory);
+    return typedHttp429 === undefined ? {} : { typedHttp429 };
+  } catch (error) {
+    const failure = error instanceof Error ? error : new Error(String(error));
+    return {
+      observationReadFailure: {
+        cause: "session",
+        identity: thrownIdentity(failure),
+        diagnostic: failure.message || failure.name,
+      },
+    };
+  }
+}
+
+/** Spread into presentControlledFailure failureInput from one audited resolution. */
+export function controlledFailureInputFromResolution(
+  resolution: AuditedRunnerFailureResolution,
+): {
+  knownFailure?: ExplicitInternalKnownFailure;
+  typedHttpObservationSettled?: true;
+  typedHttpObservation?: TypedProviderHttpObservation;
+} {
+  return {
+    ...(resolution.knownFailure === undefined ? {} : { knownFailure: resolution.knownFailure }),
+    ...(resolution.typedHttpObservationSettled
+      ? {
+        typedHttpObservationSettled: true as const,
+        ...(resolution.typedHttpObservation === undefined
+          ? {}
+          : { typedHttpObservation: resolution.typedHttpObservation }),
+      }
+      : {}),
+  };
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {

package/src/reviewer-child-executor.ts

@@ -14,7 +14,7 @@ export type ReviewerChildExecuteOptions = Readonly<{
 export function projectSharedChildFailure(error: unknown): unknown {
   if (typeof error === "object" && error !== null && "evidenceChildFailure" in error) {
     const classification = (error as { evidenceChildFailure?: unknown }).evidenceChildFailure;
-    if (classification === "provider" || classification === "child") {
+    if (classification === "provider" || classification === "child" || classification === "unknown") {
       Object.assign(error, { reviewerFailure: classification });
     }
   }

package/src/role-runtime.ts

@@ -44,7 +44,7 @@ import {
   NAVIGATOR_INVOCATION_ENTRY,
   resolveLifecycleInvocationPrincipal,
 } from "./navigator-invocation-identity.ts";
-import { recordTypedProviderHttpStatus } from "./public-cli/run-lifecycle.ts";
+import { recordTypedProviderHttpStatus } from "./typed-provider-http.ts";
 import {
   ExplicitInternalActivationError,
   recordReviewerDispatchRejectionSync,
@@ -807,22 +807,32 @@ export function createRoleRuntimeExtension(
       await observe(() => observationFace.onEnd(event), ctx);
     });
 
-    // Public Role run: record typed provider HTTP status for v1 resume (#108).
-    // Latest typed response is authoritative; only a current Codex/xAI 429 is
-    // retained — never prose classification or an earlier within-attempt 429.
+    // Public Role run: record typed non-success HTTP for error evidence + v1 resume.
+    // 2xx clears prior observation (see recordTypedProviderHttpStatus). Non-success
+    // write failure must surface — never silently drop authorized error evidence.
     pi.on("after_provider_response", async (event, ctx) => {
       const runDir = process.env.AK_ROLE_RUN_DIR;
       if (typeof runDir !== "string" || runDir.trim() === "") return;
       const provider = ctx.model?.provider;
       if (typeof provider !== "string" || provider.trim() === "") return;
+      const status = event.status;
+      if (typeof status !== "number") return;
       try {
         await recordTypedProviderHttpStatus(runDir, {
-          httpStatus: event.status,
+          httpStatus: status,
           provider,
         });
-      } catch {
-        // Observation is best-effort relative to the live provider stream;
-        // settlement still owns failure presentation.
+      } catch (error) {
+        if (
+          status >= 200 &&
+          status < 300 &&
+          error instanceof Error &&
+          "code" in error &&
+          (error as { code?: unknown }).code === "ENOENT"
+        ) {
+          return;
+        }
+        failInfrastructure(error, ctx);
       }
     });
 

package/src/ticket-frontmatter.ts

@@ -0,0 +1,94 @@
+/**
+ * Typed ticket face contract (#176 option A).
+ *
+ * Machine field lives in YAML frontmatter only:
+ *   ---
+ *   ticketNumber: <positive integer>
+ *   ---
+ *
+ * Admission reads frozen attachment bytes for this field alone.
+ * No filename, path, or free-text inference. Absent / invalid / conflicting
+ * values are unbound (undefined) — never a reject gate.
+ *
+ * Buffer bodies use strict UTF-8 (decode failure → unbound). Opening and
+ * closing fences must each be an exclusive line of exactly `---`.
+ */
+
+import { exactUtf8 } from "./exact-utf8.ts";
+
+/** Positive integer GitHub/issue identity carried on a typed ticket face. */
+export type TicketIdentity = number;
+
+/**
+ * Parse one attachment body for the typed frontmatter ticketNumber field.
+ * Returns undefined when the contract is absent or not well-formed.
+ */
+export function parseTicketNumberFrontmatter(
+  bytes: Buffer | string,
+): TicketIdentity | undefined {
+  let text: string;
+  if (typeof bytes === "string") {
+    text = bytes;
+  } else {
+    try {
+      text = exactUtf8(bytes, "ticket face");
+    } catch {
+      return undefined;
+    }
+  }
+
+  // Opening fence must be an exclusive first line of exactly `---`.
+  let cursor: number;
+  if (text.startsWith("---\n")) {
+    cursor = 4;
+  } else if (text.startsWith("---\r\n")) {
+    cursor = 5;
+  } else {
+    return undefined;
+  }
+
+  // Closing fence must likewise be an exclusive line of exactly `---`.
+  const fmLines: string[] = [];
+  let closed = false;
+  while (cursor < text.length) {
+    const nl = text.indexOf("\n", cursor);
+    const lineEnd = nl === -1 ? text.length : nl;
+    let line = text.slice(cursor, lineEnd);
+    if (line.endsWith("\r")) line = line.slice(0, -1);
+    if (line === "---") {
+      closed = true;
+      break;
+    }
+    fmLines.push(line);
+    if (nl === -1) break;
+    cursor = nl + 1;
+  }
+  if (!closed) return undefined;
+
+  let found: number | undefined;
+  for (const line of fmLines) {
+    const match = /^[ \t]*ticketNumber[ \t]*:[ \t]*(\d+)[ \t]*$/.exec(line);
+    if (match === null) continue;
+    const value = Number(match[1]);
+    if (!Number.isInteger(value) || value < 1) return undefined;
+    if (found !== undefined && found !== value) return undefined;
+    found = value;
+  }
+  return found;
+}
+
+/**
+ * Resolve at most one ticketNumber across frozen attachment bodies.
+ * Zero matches → unbound. Multiple distinct values → unbound (do not guess).
+ */
+export function resolveTicketNumberFromAttachmentBodies(
+  bodies: readonly (Buffer | string)[],
+): TicketIdentity | undefined {
+  const found = new Set<number>();
+  for (const body of bodies) {
+    const value = parseTicketNumberFrontmatter(body);
+    if (value !== undefined) found.add(value);
+  }
+  if (found.size !== 1) return undefined;
+  return found.values().next().value;
+}