harnery 0.36.0 → 0.38.0

package/src/core/workflow/admission.ts

@@ -0,0 +1,215 @@
+import { buildDiagnosticAdvice } from "../diagnostics/advice.ts";
+import type { DiagnosticAdvice } from "../diagnostics/contract.ts";
+import {
+  type EnsureSupervisorResult,
+  ensureSupervisorRunning,
+  readSupervisorFindings,
+  readSupervisorStatus,
+  registerSupervisorConsumer,
+  type SupervisorCapability,
+  type SupervisorFinding,
+  type SupervisorFindings,
+  type SupervisorStatus,
+  unregisterSupervisorConsumer,
+} from "../supervisor/index.ts";
+import type { WorkflowDiagnosticAdmissionObservation } from "./types.ts";
+
+const DEFAULT_FRESH_CYCLE_WAIT_MS = 4_000;
+const POLL_INTERVAL_MS = 50;
+
+export interface WorkflowDiagnosticAdmissionRuntime {
+  now: () => Date;
+  wait: (milliseconds: number) => Promise<void>;
+  registerConsumer: (coordRoot: string, input: { id: string; pid?: number }) => unknown;
+  unregisterConsumer: (coordRoot: string, id: string) => void;
+  ensureSupervisor: (coordRoot: string) => Promise<EnsureSupervisorResult>;
+  readStatus: (coordRoot: string, nowMs?: number) => SupervisorStatus;
+  readFindings: (coordRoot: string) => SupervisorFindings | undefined;
+}
+
+export interface ObserveWorkflowDiagnosticAdmissionInput {
+  coordRoot: string;
+  runId: string;
+  freshCycleWaitMs?: number;
+  runtime?: Partial<WorkflowDiagnosticAdmissionRuntime>;
+}
+
+export async function observeWorkflowDiagnosticAdmission(
+  input: ObserveWorkflowDiagnosticAdmissionInput,
+): Promise<WorkflowDiagnosticAdmissionObservation> {
+  const runtime = admissionRuntime(input.runtime);
+  const requested = runtime.now();
+  const requestedAt = requested.toISOString();
+  const startedMs = requested.getTime();
+  const consumerId = `workflow-${input.runId}`;
+  let serviceState: WorkflowDiagnosticAdmissionObservation["service_state"] = "unavailable";
+
+  try {
+    runtime.registerConsumer(input.coordRoot, { id: consumerId });
+    const ensured = await runtime.ensureSupervisor(input.coordRoot);
+    serviceState = ensured.state;
+    if (ensured.state === "unavailable") {
+      return unavailableObservation(
+        runtime,
+        requestedAt,
+        startedMs,
+        serviceState,
+        "error",
+        "supervisor_unavailable",
+        ensured.error,
+      );
+    }
+
+    const deadlineMs = runtime.now().getTime() + normalizeWait(input.freshCycleWaitMs);
+    while (runtime.now().getTime() <= deadlineMs) {
+      const status = runtime.readStatus(input.coordRoot, runtime.now().getTime());
+      const sampledAt = status.record?.last_cycle_at;
+      if (status.running && sampledAt && Date.parse(sampledAt) >= requested.getTime()) {
+        const report = runtime.readFindings(input.coordRoot);
+        if (!report) {
+          return unavailableObservation(
+            runtime,
+            requestedAt,
+            startedMs,
+            serviceState,
+            "unsupported",
+            "source_missing",
+          );
+        }
+        const observedAt = runtime.now().toISOString();
+        return {
+          requested_at: requestedAt,
+          observed_at: observedAt,
+          wait_ms: elapsedMs(runtime, startedMs),
+          service_state: serviceState,
+          freshness: "fresh",
+          sampled_at: sampledAt,
+          advice: buildDiagnosticAdvice({
+            findings: mergeFindings(report),
+            sourceCapability: supportedCapability(),
+            evaluatedAt: observedAt,
+          }),
+        };
+      }
+      const remainingMs = deadlineMs - runtime.now().getTime();
+      if (remainingMs <= 0) break;
+      await runtime.wait(Math.min(POLL_INTERVAL_MS, remainingMs));
+    }
+    return unavailableObservation(
+      runtime,
+      requestedAt,
+      startedMs,
+      serviceState,
+      "expired",
+      "fresh_cycle_timeout",
+    );
+  } catch (error) {
+    return unavailableObservation(
+      runtime,
+      requestedAt,
+      startedMs,
+      serviceState,
+      "error",
+      "observation_failed",
+      error instanceof Error ? error.message : String(error),
+    );
+  } finally {
+    try {
+      runtime.unregisterConsumer(input.coordRoot, consumerId);
+    } catch {
+      // Admission is observer-only. Cleanup failure cannot affect dispatch.
+    }
+  }
+}
+
+export function failedWorkflowDiagnosticAdmissionObservation(
+  error: unknown,
+  requestedAt: Date,
+  observedAt = new Date(),
+): WorkflowDiagnosticAdmissionObservation {
+  const capability: SupervisorCapability = {
+    source_kind: "supervisor.findings",
+    state: "error",
+    reason_code: "observation_failed",
+    detail: (error instanceof Error ? error.message : String(error)).slice(0, 500),
+  };
+  return {
+    requested_at: requestedAt.toISOString(),
+    observed_at: observedAt.toISOString(),
+    wait_ms: Math.max(0, observedAt.getTime() - requestedAt.getTime()),
+    service_state: "unavailable",
+    freshness: "unavailable",
+    advice: buildDiagnosticAdvice({
+      findings: [],
+      sourceCapability: capability,
+      evaluatedAt: observedAt.toISOString(),
+    }),
+  };
+}
+
+function unavailableObservation(
+  runtime: WorkflowDiagnosticAdmissionRuntime,
+  requestedAt: string,
+  startedMs: number,
+  serviceState: WorkflowDiagnosticAdmissionObservation["service_state"],
+  state: Exclude<SupervisorCapability["state"], "supported">,
+  reasonCode: string,
+  detail?: string,
+): WorkflowDiagnosticAdmissionObservation {
+  const observedAt = runtime.now().toISOString();
+  const capability: SupervisorCapability = {
+    source_kind: "supervisor.findings",
+    state,
+    reason_code: reasonCode,
+    ...(detail ? { detail: detail.slice(0, 500) } : {}),
+  };
+  const advice: DiagnosticAdvice = buildDiagnosticAdvice({
+    findings: [],
+    sourceCapability: capability,
+    evaluatedAt: observedAt,
+  });
+  return {
+    requested_at: requestedAt,
+    observed_at: observedAt,
+    wait_ms: elapsedMs(runtime, startedMs),
+    service_state: serviceState,
+    freshness: "unavailable",
+    advice,
+  };
+}
+
+function mergeFindings(report: SupervisorFindings): SupervisorFinding[] {
+  const byId = new Map<string, SupervisorFinding>();
+  for (const finding of report.transitions) byId.set(finding.id, finding);
+  for (const finding of report.active) byId.set(finding.id, finding);
+  return [...byId.values()];
+}
+
+function supportedCapability(): SupervisorCapability {
+  return { source_kind: "supervisor.findings", state: "supported" };
+}
+
+function normalizeWait(value: number | undefined): number {
+  if (value === undefined) return DEFAULT_FRESH_CYCLE_WAIT_MS;
+  if (!Number.isFinite(value) || value < 0) return DEFAULT_FRESH_CYCLE_WAIT_MS;
+  return Math.min(Math.floor(value), 30_000);
+}
+
+function elapsedMs(runtime: WorkflowDiagnosticAdmissionRuntime, startedMs: number): number {
+  return Math.max(0, runtime.now().getTime() - startedMs);
+}
+
+function admissionRuntime(
+  overrides: Partial<WorkflowDiagnosticAdmissionRuntime> | undefined,
+): WorkflowDiagnosticAdmissionRuntime {
+  return {
+    now: () => new Date(),
+    wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+    registerConsumer: registerSupervisorConsumer,
+    unregisterConsumer: unregisterSupervisorConsumer,
+    ensureSupervisor: ensureSupervisorRunning,
+    readStatus: readSupervisorStatus,
+    readFindings: readSupervisorFindings,
+    ...overrides,
+  };
+}

package/src/core/workflow/engine.ts

@@ -35,6 +35,10 @@ import {
   policyDigest,
   summarizePolicyRequest,
 } from "../policy/index.ts";
+import {
+  failedWorkflowDiagnosticAdmissionObservation,
+  observeWorkflowDiagnosticAdmission,
+} from "./admission.ts";
 import { assertWorkflowRunId, createWorkflowApproval } from "./approvals.ts";
 import { freezeWorkflowAttemptContext } from "./attempt-context.ts";
 import { type BillingProbe, probeBilling } from "./billing.ts";
@@ -52,6 +56,7 @@ import {
   acquireWorkflowResumeLease,
   assertWorkflowRunResumable,
   assertWorkflowScriptUnchanged,
+  WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION,
   workflowScriptDigest,
   writeWorkflowRunManifest,
 } from "./run-state.ts";
@@ -71,12 +76,16 @@ import type {
   WorkflowAgentProof,
   WorkflowAttemptContext,
   WorkflowContext,
+  WorkflowDiagnosticAdmissionConfig,
+  WorkflowDiagnosticAdmissionObservation,
+  WorkflowDiagnosticAdmissionProof,
   WorkflowEvidenceRecord,
   WorkflowModule,
   WorkflowProof,
   WorkflowSandboxProjectionEvidence,
   WorkflowWorkContext,
 } from "./types.ts";
+import { WORKFLOW_DIAGNOSTIC_ADMISSION_SCHEMA_VERSION } from "./types.ts";
 import { parseStageOutput, validateAgainstSchema } from "./validate.ts";
 import { freezeWorkflowWorkContext } from "./work-context.ts";
 import {
@@ -317,6 +326,11 @@ async function executeWorkflow(
   const approvalAddressee = frozen?.approval_addressee ?? opts.approvalAddressee ?? "operator";
   const subscriptionOnly = frozen?.subscription_only ?? Boolean(opts.subscriptionOnly);
   const allowApiBilling = frozen?.allow_api_billing ?? Boolean(opts.allowApiBilling);
+  const diagnosticAdmissionConfig = frozen?.diagnostic_admission
+    ? normalizeDiagnosticAdmissionConfig(frozen.diagnostic_admission)
+    : resumeState
+      ? undefined
+      : normalizeDiagnosticAdmissionConfig(opts.diagnosticAdmission);
   const startedAt = resumeState?.manifest.started_at ?? new Date().toISOString();
   const t0 = resumeState ? Date.parse(startedAt) : Date.now();
   const scriptSha256 = resumeState?.manifest.script.sha256 ?? workflowScriptDigest(absScript);
@@ -386,6 +400,7 @@ async function executeWorkflow(
         after: resumeState.manifest.repository_before,
         agents: [],
         evidence: [],
+        diagnosticAdmission: initialDiagnosticAdmissionProof(diagnosticAdmissionConfig),
         adapterEvidence: opts.adapterEvidence,
         adapterAttestations: opts.adapterAttestations,
         sandboxProjection: sandboxProjectionEvidence(
@@ -454,7 +469,7 @@ async function executeWorkflow(
     writeWorkflowRunManifest({
       coordRoot: opts.coordRoot,
       manifest: {
-        schema_version: 1,
+        schema_version: WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION,
         run_id: runId,
         work_item_id: opts.workItemId,
         work_context: workContext,
@@ -468,6 +483,7 @@ async function executeWorkflow(
           default_adapter: defaultAdapter,
           max_agents: maxAgents,
           concurrency,
+          diagnostic_admission: diagnosticAdmissionConfig,
           subscription_only: subscriptionOnly,
           allow_api_billing: allowApiBilling,
           approval_mode: approvalMode,
@@ -581,6 +597,8 @@ async function executeWorkflow(
     history?.policyDecisions.map((decision) => [decision.id, decision]),
   );
   const acceptanceIds = new Set(meta.acceptance.map((criterion) => criterion.id));
+  let diagnosticAdmission = initialDiagnosticAdmissionProof(diagnosticAdmissionConfig);
+  let diagnosticAdmissionPromise: Promise<void> | undefined;
 
   const transcript = (event: string, data: Record<string, unknown>): void => {
     appendWorkflowTranscriptEvent(opts.coordRoot, runId, event, { stage: currentStage, ...data });
@@ -601,6 +619,46 @@ async function executeWorkflow(
     });
   };
 
+  const ensureDiagnosticAdmissionObserved = async (): Promise<void> => {
+    if (!diagnosticAdmissionConfig) return;
+    diagnosticAdmissionPromise ??= (async () => {
+      const requestedAt = new Date();
+      let observation: WorkflowDiagnosticAdmissionObservation;
+      try {
+        observation = await (
+          opts.observeDiagnosticAdmission ??
+          ((coordRoot, observationRunId) =>
+            observeWorkflowDiagnosticAdmission({
+              coordRoot,
+              runId: observationRunId,
+            }))
+        )(opts.coordRoot, runId);
+      } catch (error) {
+        observation = failedWorkflowDiagnosticAdmissionObservation(error, requestedAt);
+      }
+      diagnosticAdmission = {
+        schema_version: WORKFLOW_DIAGNOSTIC_ADMISSION_SCHEMA_VERSION,
+        mode: "shadow",
+        trigger: "before-first-dispatch",
+        state: "observed",
+        action: "none",
+        observation,
+      };
+      transcript("diagnostic.admission", {
+        schema_version: diagnosticAdmission.schema_version,
+        mode: diagnosticAdmission.mode,
+        trigger: diagnosticAdmission.trigger,
+        action: diagnosticAdmission.action,
+        observation,
+      });
+      log(
+        `[admission] shadow pressure=${observation.advice.pressure} ` +
+          `recommendation=${observation.advice.fan_out_recommendation}; dispatch unchanged`,
+      );
+    })();
+    await diagnosticAdmissionPromise;
+  };
+
   // Bounded concurrency gate shared by every spawn in the run — direct
   // `agent()` calls and `parallel()` thunks draw from the same slot pool, so
   // the cap holds even when a script nests parallel() inside loops.
@@ -936,6 +994,7 @@ async function executeWorkflow(
 
     await acquire();
     try {
+      await ensureDiagnosticAdmissionObserved();
       transcript("agent.start", {
         id,
         label,
@@ -1227,6 +1286,7 @@ async function executeWorkflow(
         after: snapshotRepo(executionCwd),
         agents: Array.from(agentProofs.values()),
         evidence: evidenceRecords,
+        diagnosticAdmission,
         adapterEvidence: opts.adapterEvidence,
         adapterAttestations: opts.adapterAttestations,
         sandboxProjection: sandboxProjectionEvidence(filesystemPolicy, gitWrite),
@@ -1270,6 +1330,7 @@ async function executeWorkflow(
         mode: subscriptionOnly ? "subscription" : p.mode,
       })),
       policy: proof.policy?.summary,
+      diagnosticAdmission,
       workspaceBinding,
     };
     return report;
@@ -1308,6 +1369,7 @@ async function executeWorkflow(
         after: snapshotRepo(executionCwd),
         agents: Array.from(agentProofs.values()),
         evidence: evidenceRecords,
+        diagnosticAdmission,
         adapterEvidence: opts.adapterEvidence,
         adapterAttestations: opts.adapterAttestations,
         sandboxProjection: sandboxProjectionEvidence(filesystemPolicy, gitWrite),
@@ -1485,6 +1547,36 @@ function round4(n: number): number {
   return Math.round(n * 10_000) / 10_000;
 }
 
+function normalizeDiagnosticAdmissionConfig(
+  value: WorkflowDiagnosticAdmissionConfig | undefined,
+): WorkflowDiagnosticAdmissionConfig | undefined {
+  if (value === undefined) return undefined;
+  if (
+    value.schema_version !== WORKFLOW_DIAGNOSTIC_ADMISSION_SCHEMA_VERSION ||
+    value.mode !== "shadow"
+  ) {
+    throw new Error("diagnosticAdmission must use schema_version 1 and mode shadow");
+  }
+  return {
+    schema_version: WORKFLOW_DIAGNOSTIC_ADMISSION_SCHEMA_VERSION,
+    mode: "shadow",
+  };
+}
+
+function initialDiagnosticAdmissionProof(
+  config: WorkflowDiagnosticAdmissionConfig | undefined,
+): WorkflowDiagnosticAdmissionProof | undefined {
+  if (!config) return undefined;
+  return {
+    schema_version: WORKFLOW_DIAGNOSTIC_ADMISSION_SCHEMA_VERSION,
+    mode: "shadow",
+    trigger: "before-first-dispatch",
+    state: "not-needed",
+    action: "none",
+    reason_code: "no-dispatch",
+  };
+}
+
 function assertAgentCapacity(agentsSpawned: number, maxAgents: number): void {
   if (agentsSpawned >= maxAgents) {
     throw new Error(

package/src/core/workflow/index.ts

@@ -1,3 +1,9 @@
+export {
+  failedWorkflowDiagnosticAdmissionObservation,
+  type ObserveWorkflowDiagnosticAdmissionInput,
+  observeWorkflowDiagnosticAdmission,
+  type WorkflowDiagnosticAdmissionRuntime,
+} from "./admission.ts";
 export type {
   CreateWorkflowApprovalInput,
   ResolveWorkflowApprovalInput,
@@ -72,6 +78,9 @@ export type {
   WorkflowAttemptPriorContext,
   WorkflowAttemptUnresolvedCriterion,
   WorkflowContext,
+  WorkflowDiagnosticAdmissionConfig,
+  WorkflowDiagnosticAdmissionObservation,
+  WorkflowDiagnosticAdmissionProof,
   WorkflowEvidenceInput,
   WorkflowEvidenceRecord,
   WorkflowMeta,
@@ -87,6 +96,7 @@ export type {
 } from "./types.ts";
 export {
   WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION,
+  WORKFLOW_DIAGNOSTIC_ADMISSION_SCHEMA_VERSION,
   WORKFLOW_PROOF_SCHEMA_VERSION,
   WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION,
 } from "./types.ts";

package/src/core/workflow/proof.ts

@@ -24,6 +24,7 @@ import type {
   SpawnFailureClass,
   WorkflowAgentProof,
   WorkflowAttemptContext,
+  WorkflowDiagnosticAdmissionProof,
   WorkflowEvidenceInput,
   WorkflowEvidenceRecord,
   WorkflowMeta,
@@ -35,7 +36,11 @@ import type {
   WorkflowSandboxProjectionEvidence,
   WorkflowWorkContext,
 } from "./types.ts";
-import { EVIDENCE_KINDS, WORKFLOW_PROOF_SCHEMA_VERSION } from "./types.ts";
+import {
+  EVIDENCE_KINDS,
+  WORKFLOW_DIAGNOSTIC_ADMISSION_SCHEMA_VERSION,
+  WORKFLOW_PROOF_SCHEMA_VERSION,
+} from "./types.ts";
 import { isCanonicalWorkflowWorkContext } from "./work-context.ts";
 import type {
   WorkspaceAttestation,
@@ -84,6 +89,7 @@ export interface BuildWorkflowProofInput {
   after: RepoSnapshot;
   agents: WorkflowAgentProof[];
   evidence: WorkflowEvidenceRecord[];
+  diagnosticAdmission?: WorkflowDiagnosticAdmissionProof;
   adapterEvidence?: Readonly<Record<string, AdapterEvidenceCapability | undefined>>;
   /** Filesystem policy actually projected into children (ADR 0039). */
   sandboxProjection?: WorkflowSandboxProjectionEvidence;
@@ -299,6 +305,7 @@ export function buildWorkflowProof(input: BuildWorkflowProofInput): WorkflowProo
     agents,
     evidence: input.evidence,
     policy: input.policy ? buildPolicyProof(input.policy) : undefined,
+    ...(input.diagnosticAdmission ? { diagnostic_admission: input.diagnosticAdmission } : {}),
     execution:
       input.workspaceBinding && input.workspaceAttestation
         ? buildExecutionEvidence(input.status, input.workspaceBinding, input.workspaceAttestation)
@@ -385,6 +392,7 @@ export function readWorkflowProof(coordRoot: string, runId: string): WorkflowPro
       (!proof.run.work_item_id ||
         !proof.run.work_context ||
         !isCanonicalWorkflowAttemptContext(proof.run.attempt_context))) ||
+    !validDiagnosticAdmissionProof(proof.diagnostic_admission) ||
     (proof.execution !== undefined &&
       !isWorkspaceExecutionEvidence(proof.execution, runId, proof.run.status))
   ) {
@@ -410,6 +418,42 @@ export function readWorkflowProof(coordRoot: string, runId: string): WorkflowPro
   return proof;
 }
 
+function validDiagnosticAdmissionProof(
+  value: WorkflowDiagnosticAdmissionProof | undefined,
+): boolean {
+  if (value === undefined) return true;
+  if (
+    value.schema_version !== WORKFLOW_DIAGNOSTIC_ADMISSION_SCHEMA_VERSION ||
+    value.mode !== "shadow" ||
+    value.trigger !== "before-first-dispatch" ||
+    value.action !== "none" ||
+    (value.state !== "not-needed" && value.state !== "observed")
+  ) {
+    return false;
+  }
+  if (value.state === "not-needed") {
+    return value.reason_code === "no-dispatch" && value.observation === undefined;
+  }
+  const observation = value.observation;
+  return (
+    value.reason_code === undefined &&
+    observation !== undefined &&
+    validTimestamp(observation.requested_at) &&
+    validTimestamp(observation.observed_at) &&
+    Number.isSafeInteger(observation.wait_ms) &&
+    observation.wait_ms >= 0 &&
+    ["running", "started", "unavailable"].includes(observation.service_state) &&
+    ["fresh", "unavailable"].includes(observation.freshness) &&
+    (observation.sampled_at === undefined || validTimestamp(observation.sampled_at)) &&
+    observation.advice?.schema_version === 1 &&
+    observation.advice.observer_only === true
+  );
+}
+
+function validTimestamp(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && Number.isFinite(Date.parse(value));
+}
+
 function buildExecutionEvidence(
   workflowStatus: "succeeded" | "failed",
   binding: WorkspaceBinding,
@@ -458,6 +502,15 @@ export function renderWorkflowProof(proof: WorkflowProof): string {
         `${proof.policy.summary.denied} denied, ${proof.policy.summary.asked} asked`,
     );
   }
+  if (proof.diagnostic_admission) {
+    const observation = proof.diagnostic_admission.observation;
+    lines.push(
+      observation
+        ? `admission: shadow ${observation.advice.pressure}; ` +
+            `${observation.advice.fan_out_recommendation}; action none`
+        : "admission: shadow not needed; no real child dispatch",
+    );
+  }
   const repo = proof.repository;
   const drift = repo.drift;
   lines.push(

package/src/core/workflow/run-state.ts

@@ -26,9 +26,11 @@ import { readJsonRecord, writeImmutableJson } from "./durable-record.ts";
 import { normalizeWorkflowSpecialists } from "./specialists.ts";
 import type {
   WorkflowAttemptContext,
+  WorkflowDiagnosticAdmissionConfig,
   WorkflowSpecialistProfile,
   WorkflowWorkContext,
 } from "./types.ts";
+import { WORKFLOW_DIAGNOSTIC_ADMISSION_SCHEMA_VERSION } from "./types.ts";
 import { isCanonicalWorkflowWorkContext } from "./work-context.ts";
 import type {
   WorkspaceAllocationRequest,
@@ -41,7 +43,7 @@ import {
   isWorkspaceCompatibilityExecutionEvidence,
 } from "./workspaces/validate.ts";
 
-export const WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION = 1 as const;
+export const WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION = 2 as const;
 
 const MANIFEST_LIMIT_BYTES = 256 * 1024;
 const FOREIGN_LEASE_STALE_MS = 24 * 60 * 60 * 1_000;
@@ -61,6 +63,7 @@ export interface WorkflowRunManifest {
     default_adapter: string;
     max_agents: number;
     concurrency: number;
+    diagnostic_admission?: WorkflowDiagnosticAdmissionConfig;
     subscription_only: boolean;
     allow_api_billing: boolean;
     approval_mode: "deny" | "park";
@@ -274,6 +277,7 @@ function validExecution(value: WorkflowRunManifest["execution"]): boolean {
     value.default_adapter.length > 0 &&
     positiveSafeInteger(value.max_agents) &&
     positiveSafeInteger(value.concurrency) &&
+    validDiagnosticAdmission(value.diagnostic_admission) &&
     typeof value.subscription_only === "boolean" &&
     typeof value.allow_api_billing === "boolean" &&
     (value.approval_mode === "deny" || value.approval_mode === "park") &&
@@ -292,6 +296,14 @@ function validExecution(value: WorkflowRunManifest["execution"]): boolean {
   );
 }
 
+function validDiagnosticAdmission(value: WorkflowDiagnosticAdmissionConfig | undefined): boolean {
+  return (
+    value === undefined ||
+    (value.schema_version === WORKFLOW_DIAGNOSTIC_ADMISSION_SCHEMA_VERSION &&
+      value.mode === "shadow")
+  );
+}
+
 function readManifestWorkspaceRequest(
   coordRoot: string,
   runId: string,

package/src/core/workflow/types.ts

@@ -7,6 +7,7 @@
  * Design record: decision 0015 (portable coordination-aware workflows).
  */
 
+import type { DiagnosticAdvice } from "../diagnostics/contract.ts";
 import type {
   DispatchCostEstimator,
   ExternalMutationRequest,
@@ -24,7 +25,8 @@ import type {
   WorkspaceProvider,
 } from "./workspaces/index.ts";
 
-export const WORKFLOW_PROOF_SCHEMA_VERSION = 1 as const;
+export const WORKFLOW_PROOF_SCHEMA_VERSION = 2 as const;
+export const WORKFLOW_DIAGNOSTIC_ADMISSION_SCHEMA_VERSION = 1 as const;
 export const WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION = 1 as const;
 export const WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION = 1 as const;
 
@@ -46,6 +48,31 @@ export type AcceptanceStatus = "satisfied" | "unsatisfied" | "unknown";
 export type WorkflowRunStatus = "succeeded" | "failed";
 export type WorkflowApprovalMode = "deny" | "park";
 
+export interface WorkflowDiagnosticAdmissionConfig {
+  schema_version: typeof WORKFLOW_DIAGNOSTIC_ADMISSION_SCHEMA_VERSION;
+  mode: "shadow";
+}
+
+export interface WorkflowDiagnosticAdmissionObservation {
+  requested_at: string;
+  observed_at: string;
+  wait_ms: number;
+  service_state: "running" | "started" | "unavailable";
+  freshness: "fresh" | "unavailable";
+  sampled_at?: string;
+  advice: DiagnosticAdvice;
+}
+
+export interface WorkflowDiagnosticAdmissionProof {
+  schema_version: typeof WORKFLOW_DIAGNOSTIC_ADMISSION_SCHEMA_VERSION;
+  mode: "shadow";
+  trigger: "before-first-dispatch";
+  state: "not-needed" | "observed";
+  action: "none";
+  reason_code?: "no-dispatch";
+  observation?: WorkflowDiagnosticAdmissionObservation;
+}
+
 export interface AcceptanceCriterion {
   /** Stable identifier referenced by evidence, for example `tests-pass`. */
   id: string;
@@ -221,6 +248,8 @@ export interface WorkflowProof {
   agents: WorkflowAgentProof[];
   evidence: WorkflowEvidenceRecord[];
   policy?: WorkflowPolicyProof;
+  /** Observer-only local pressure recorded before the first real child dispatch. */
+  diagnostic_admission?: WorkflowDiagnosticAdmissionProof;
   /** Immutable terminal provider evidence for isolated execution. */
   execution?: WorkspaceExecutionEvidence;
   repository: WorkflowRepoEvidence;
@@ -557,6 +586,13 @@ export interface EngineOpts {
   maxAgents?: number;
   /** Concurrent-subagent cap for parallel() (default 4). */
   concurrency?: number;
+  /** Opt-in observer-only pressure sample before the first real child dispatch. */
+  diagnosticAdmission?: WorkflowDiagnosticAdmissionConfig;
+  /** Admission observer override for tests. */
+  observeDiagnosticAdmission?: (
+    coordRoot: string,
+    runId: string,
+  ) => Promise<WorkflowDiagnosticAdmissionObservation>;
   /** Working directory children spawn in (default: coordRoot). */
   cwd?: string;
   /** Progress sink (default: process.stderr). */
@@ -639,6 +675,8 @@ export interface RunReport {
   billing: Array<{ adapter: AdapterName; mode: BillingMode }>;
   /** Policy verdict totals when the host supplied a policy. */
   policy?: WorkflowPolicyProof["summary"];
+  /** Observer-only pressure sample. Never changes dispatch in shadow mode. */
+  diagnosticAdmission?: WorkflowDiagnosticAdmissionProof;
   /** Isolated workspace binding when this run requested a provider capability. */
   workspaceBinding?: WorkspaceBinding;
 }