agent-scenario-loop 0.1.2 → 0.1.4

package/README.md

@@ -14,12 +14,14 @@ Execution tools can change. The scenario and evidence contract should not.
 | --- | --- |
 | Understand the idea in plain language | [Concepts](docs/concepts.md) |
 | Understand the project doctrine | [Principles](docs/principles.md) |
-| Write your first scenario | [Scenario Authoring](docs/authoring.md) |
-| Rehearse adoption in an existing app | [Consumer App Rehearsal](docs/consumer-rehearsal.md) |
+| Understand why ASL is a protocol, not a TypeScript-only library | [Architecture](docs/architecture.md) |
+| Implement or evaluate an out-of-process adapter in any language | [External Adapter Protocol](docs/external-adapter-protocol.md) |
 | Inspect artifacts, schemas, and supported surfaces | [Contracts](docs/contracts.md) |
-| Use the package from code | [Public API](docs/api.md) |
+| Write your first scenario | [Scenario Authoring](docs/authoring.md) |
 | Add a runner or evidence provider | [Adapter Onboarding](docs/adapters.md) |
+| Rehearse adoption in an existing app | [Consumer App Rehearsal](docs/consumer-rehearsal.md) |
 | Run fixture, Android, or iOS proofs | [Live Proofs](docs/live-proofs.md) |
+| Use the package from code | [Public API](docs/api.md) |
 | Inspect runner behavior and limits | [Runner docs](runner/README.md) |
 | Explore the neutral dogfood app | [examples/mobile-app](examples/mobile-app/README.md) |
 | See runner and provider fixtures | [examples/runners](examples/runners/README.md) |
@@ -73,12 +75,6 @@ No simulator or device available yet? Run the fixture loop:
 pnpm demo:loop -- --out artifacts/demo-loop
 ```
 
-Read next:
-
-- [Scenario Authoring](docs/authoring.md) for scenario shape and truth events
-- [Consumer App Rehearsal](docs/consumer-rehearsal.md) for adoption in an existing app
-- [Live Proofs](docs/live-proofs.md) for Android, iOS, comparison, and release-proof paths
-
 ## Package Surface
 
 The root package exports stable core contracts:
@@ -123,3 +119,7 @@ pnpm release:check
 ```
 
 The package should remain product-neutral. Product-specific selectors, routes, auth assumptions, accounts, and scenario data belong in the consuming app, not in this repository.
+
+## Read next
+
+- [Concepts](docs/concepts.md) for the plain-language model

package/app/profile-session.ts

@@ -12,11 +12,17 @@ export type ProfileSessionState = {
 
 export type ProfileSessionCommand = {
   id: string;
+  commandId?: string;
   scenario?: string;
   runId?: string;
   command: string;
+  queueId?: string;
+  sequence?: number;
   source?: 'deeplink' | 'storage';
   timestamp: number;
+  waitForMilestone?: string;
+  waitMs?: number;
+  waitTimeoutMs?: number;
 };
 
 export type ProfileSignalKind = 'js' | 'memory' | 'network';
@@ -62,13 +68,35 @@ type StoredProfileSessionEntry = {
   scenario: string;
   runId: string;
   timestamp: number;
+  atMs?: number;
   startedAt?: number;
   stoppedAt?: number;
   command?: string;
+  commandId?: string;
   id?: string;
+  queueId?: string;
+  reason?: string;
+  result?: string;
+  sequence?: number;
+  source?: 'deeplink' | 'storage';
+  status?: 'received' | 'queued' | 'delivered' | 'completed' | 'skipped';
+  waitForMilestone?: string;
+  waitMs?: number;
+  waitTimeoutMs?: number;
 };
 
 type StoredProfileSignals = Record<ProfileSignalKind, Record<string, unknown>>;
+type ProfileCommandMilestoneGate = {
+  commandId?: string;
+  id: string;
+  milestone: string;
+  queueId?: string;
+  runId?: string;
+  scenario?: string;
+  sequence?: number;
+  timeoutId?: ReturnType<typeof setTimeout>;
+  waitMs?: number;
+};
 
 const INITIAL_STATE: ProfileSessionState = {
   active: false,
@@ -97,9 +125,15 @@ const listeners = new Set<() => void>();
 const profileCommandListeners = new Set<(command: ProfileSessionCommand) => void>();
 const profileCommandTargetHandlers = new Map<string, () => void>();
 const pendingProfileCommands: ProfileSessionCommand[] = [];
+const sequencedProfileCommands: ProfileSessionCommand[] = [];
+const observedProfileEvents: StoredProfileEvent[] = [];
 const processedProfileCommandIds = new Set<string>();
 let lastProfileCommandSignature: string | null = null;
 let lastProfileCommandTimestamp = 0;
+let profileCommandMilestoneGate: ProfileCommandMilestoneGate | null = null;
+let profileCommandProcessingScheduled = false;
+let profileCommandProcessingTimeoutId: ReturnType<typeof setTimeout> | null = null;
+let profileCommandProcessingAvailableAt = 0;
 
 function writeProfileLog(line: string) {
   if (Platform.OS === 'ios') {
@@ -191,6 +225,7 @@ function appendStoredProfileEvent(event: StoredProfileEvent) {
 }
 
 function resetStoredProfileArtifacts() {
+  observedProfileEvents.length = 0;
   queueProfileStorageMutation(async () => {
     await Promise.all([
       AsyncStorage.removeItem(PROFILE_EVENT_STORAGE_KEY),
@@ -202,6 +237,9 @@ function resetStoredProfileArtifacts() {
 
 function clearPendingProfileCommands() {
   pendingProfileCommands.length = 0;
+  sequencedProfileCommands.length = 0;
+  clearProfileCommandMilestoneGate();
+  clearProfileCommandProcessingSchedule();
   queueProfileStorageMutation(async () => {
     await AsyncStorage.removeItem(PROFILE_COMMAND_STORAGE_KEY);
   });
@@ -285,7 +323,21 @@ export function isProfileSessionFresh(
 }
 
 function logProfileSession(kind: 'start' | 'stop' | 'command', payload: Record<string, unknown>) {
-  writeProfileLog(buildLogLine('profile-session', { kind, ...payload }));
+  const timestamp = Date.now();
+  const sessionStartedAt = readProfileSessionStartedAt(profileSessionState);
+  const atMs =
+    typeof payload.atMs === 'number' && Number.isFinite(payload.atMs)
+      ? payload.atMs
+      : sessionStartedAt !== null
+        ? Math.max(0, timestamp - sessionStartedAt)
+        : undefined;
+  const logPayload = {
+    kind,
+    ...payload,
+    timestamp,
+    ...(atMs !== undefined ? { atMs } : {}),
+  };
+  writeProfileLog(buildLogLine('profile-session', logPayload));
 
   const scenario = typeof payload.scenario === 'string' ? payload.scenario : null;
   const runId = typeof payload.runId === 'string' ? payload.runId : null;
@@ -293,12 +345,12 @@ function logProfileSession(kind: 'start' | 'stop' | 'command', payload: Record<s
     return;
   }
 
-  const timestamp = Date.now();
   const entry: StoredProfileSessionEntry = {
     kind,
     scenario,
     runId,
     timestamp,
+    ...(atMs !== undefined ? { atMs } : {}),
   };
 
   if (kind === 'start' && typeof payload.startedAt === 'number') {
@@ -316,6 +368,44 @@ function logProfileSession(kind: 'start' | 'stop' | 'command', payload: Record<s
     if (typeof payload.id === 'string') {
       entry.id = payload.id;
     }
+    if (typeof payload.commandId === 'string') {
+      entry.commandId = payload.commandId;
+    } else if (typeof payload.id === 'string') {
+      entry.commandId = payload.id;
+    }
+    if (typeof payload.queueId === 'string') {
+      entry.queueId = payload.queueId;
+    }
+    if (typeof payload.sequence === 'number') {
+      entry.sequence = payload.sequence;
+    }
+    if (payload.source === 'deeplink' || payload.source === 'storage') {
+      entry.source = payload.source;
+    }
+    if (
+      payload.status === 'received' ||
+      payload.status === 'queued' ||
+      payload.status === 'delivered' ||
+      payload.status === 'completed' ||
+      payload.status === 'skipped'
+    ) {
+      entry.status = payload.status;
+    }
+    if (typeof payload.reason === 'string') {
+      entry.reason = payload.reason;
+    }
+    if (typeof payload.result === 'string') {
+      entry.result = payload.result;
+    }
+    if (typeof payload.waitForMilestone === 'string') {
+      entry.waitForMilestone = payload.waitForMilestone;
+    }
+    if (typeof payload.waitMs === 'number') {
+      entry.waitMs = payload.waitMs;
+    }
+    if (typeof payload.waitTimeoutMs === 'number') {
+      entry.waitTimeoutMs = payload.waitTimeoutMs;
+    }
   }
 
   appendStoredProfileSessionEntry(entry);
@@ -326,6 +416,12 @@ function getProfileSessionRoute(url: string): {
   scenario?: string;
   runId?: string;
   command?: string;
+  commandId?: string;
+  queueId?: string;
+  sequence?: number;
+  waitForMilestone?: string;
+  waitMs?: number;
+  waitTimeoutMs?: number;
 } | null {
   const parsed = ExpoLinking.parse(url);
   const segments = [parsed.hostname, parsed.path]
@@ -347,8 +443,26 @@ function getProfileSessionRoute(url: string): {
     typeof parsed.queryParams?.runId === 'string' ? parsed.queryParams.runId : undefined;
   const command =
     typeof parsed.queryParams?.command === 'string' ? parsed.queryParams.command : undefined;
-
-  return { action, scenario, runId, command };
+  const commandId =
+    typeof parsed.queryParams?.commandId === 'string' ? parsed.queryParams.commandId : undefined;
+  const sequence =
+    typeof parsed.queryParams?.sequence === 'string' && Number.isInteger(Number(parsed.queryParams.sequence))
+      ? Number(parsed.queryParams.sequence)
+      : undefined;
+  const queueId =
+    typeof parsed.queryParams?.queueId === 'string' ? parsed.queryParams.queueId : undefined;
+  const waitForMilestone =
+    typeof parsed.queryParams?.waitForMilestone === 'string' ? parsed.queryParams.waitForMilestone : undefined;
+  const waitTimeoutMs =
+    typeof parsed.queryParams?.waitTimeoutMs === 'string' && Number.isInteger(Number(parsed.queryParams.waitTimeoutMs))
+      ? Number(parsed.queryParams.waitTimeoutMs)
+      : undefined;
+  const waitMs =
+    typeof parsed.queryParams?.waitMs === 'string' && Number.isInteger(Number(parsed.queryParams.waitMs))
+      ? Number(parsed.queryParams.waitMs)
+      : undefined;
+
+  return { action, scenario, runId, command, commandId, queueId, sequence, waitForMilestone, waitMs, waitTimeoutMs };
 }
 
 function queuePendingProfileCommand(command: ProfileSessionCommand) {
@@ -440,6 +554,132 @@ function markProfileCommandIdProcessed(command: ProfileSessionCommand) {
   }
 }
 
+function compareProfileCommands(left: ProfileSessionCommand, right: ProfileSessionCommand): number {
+  const leftSequence = typeof left.sequence === 'number' ? left.sequence : Number.POSITIVE_INFINITY;
+  const rightSequence = typeof right.sequence === 'number' ? right.sequence : Number.POSITIVE_INFINITY;
+  if (leftSequence !== rightSequence) {
+    return leftSequence - rightSequence;
+  }
+
+  return left.timestamp - right.timestamp;
+}
+
+function shouldQueueProfileCommand(command: ProfileSessionCommand): boolean {
+  return !hasProcessedProfileCommandId(command) &&
+    !sequencedProfileCommands.some((queuedCommand) => queuedCommand.id === command.id);
+}
+
+function buildProfileCommandMilestoneGate(command: ProfileSessionCommand): ProfileCommandMilestoneGate | null {
+  if (typeof command.waitForMilestone !== 'string' || command.waitForMilestone.length === 0) {
+    return null;
+  }
+
+  return {
+    id: command.id,
+    milestone: command.waitForMilestone,
+    ...(typeof command.commandId === 'string' ? { commandId: command.commandId } : {}),
+    ...(typeof command.queueId === 'string' ? { queueId: command.queueId } : {}),
+    ...(typeof command.runId === 'string' ? { runId: command.runId } : {}),
+    ...(typeof command.scenario === 'string' ? { scenario: command.scenario } : {}),
+    ...(typeof command.sequence === 'number' ? { sequence: command.sequence } : {}),
+    ...(typeof command.waitMs === 'number' && command.waitMs > 0 ? { waitMs: command.waitMs } : {}),
+  };
+}
+
+function hasObservedProfileCommandMilestone(command: ProfileSessionCommand): boolean {
+  if (typeof command.waitForMilestone !== 'string' || command.waitForMilestone.length === 0) {
+    return false;
+  }
+  if (typeof command.sequence === 'number' && command.sequence > 1) {
+    return false;
+  }
+
+  return observedProfileEvents.some((eventPayload) => (
+    eventPayload.event === command.waitForMilestone &&
+    (!command.runId || eventPayload.runId === command.runId) &&
+    (!command.scenario || eventPayload.scenario === command.scenario)
+  ));
+}
+
+function clearProfileCommandMilestoneGate() {
+  if (profileCommandMilestoneGate?.timeoutId) {
+    clearTimeout(profileCommandMilestoneGate.timeoutId);
+  }
+  profileCommandMilestoneGate = null;
+}
+
+function clearProfileCommandProcessingSchedule() {
+  if (profileCommandProcessingTimeoutId) {
+    clearTimeout(profileCommandProcessingTimeoutId);
+  }
+  profileCommandProcessingTimeoutId = null;
+  profileCommandProcessingScheduled = false;
+  profileCommandProcessingAvailableAt = 0;
+}
+
+function startProfileCommandMilestoneTimeout(command: ProfileSessionCommand) {
+  if (
+    !profileCommandMilestoneGate ||
+    typeof command.waitTimeoutMs !== 'number' ||
+    command.waitTimeoutMs <= 0
+  ) {
+    return;
+  }
+
+  profileCommandMilestoneGate.timeoutId = setTimeout(() => {
+    if (!profileCommandMilestoneGate || profileCommandMilestoneGate.id !== command.id) {
+      return;
+    }
+
+    logProfileSession('command', {
+      ...command,
+      status: 'skipped',
+      reason: 'wait-for-milestone-timeout',
+    });
+    clearProfileCommandMilestoneGate();
+    processSequencedProfileCommands();
+  }, command.waitTimeoutMs);
+}
+
+function scheduleProfileCommandProcessing(waitMs = 0) {
+  const availableAt = waitMs > 0 ? Date.now() + waitMs : 0;
+  if (availableAt > profileCommandProcessingAvailableAt) {
+    profileCommandProcessingAvailableAt = availableAt;
+  }
+
+  const delayMs = Math.max(0, profileCommandProcessingAvailableAt - Date.now());
+  if (profileCommandProcessingTimeoutId) {
+    clearTimeout(profileCommandProcessingTimeoutId);
+    profileCommandProcessingTimeoutId = null;
+  }
+
+  profileCommandProcessingScheduled = true;
+  const run = () => {
+    profileCommandProcessingTimeoutId = null;
+    const remainingMs = Math.max(0, profileCommandProcessingAvailableAt - Date.now());
+    if (remainingMs > 0) {
+      profileCommandProcessingScheduled = false;
+      scheduleProfileCommandProcessing(remainingMs);
+      return;
+    }
+    profileCommandProcessingAvailableAt = 0;
+    profileCommandProcessingScheduled = false;
+    processSequencedProfileCommands();
+  };
+
+  if (delayMs > 0) {
+    profileCommandProcessingTimeoutId = setTimeout(run, delayMs);
+    return;
+  }
+
+  if (typeof queueMicrotask === 'function') {
+    queueMicrotask(run);
+    return;
+  }
+
+  Promise.resolve().then(run);
+}
+
 function notifyProfileCommandListeners(command: ProfileSessionCommand) {
   const commandTimestamp = Number.isFinite(command.timestamp) ? command.timestamp : Date.now();
   if (shouldSkipProfileCommandForDuplicateWindow(command, commandTimestamp)) {
@@ -456,17 +696,108 @@ function notifyProfileCommandListeners(command: ProfileSessionCommand) {
 
   const targetDispatched = dispatchProfileCommandTarget(command);
   if (targetDispatched) {
+    logProfileSession('command', {
+      ...command,
+      status: 'completed',
+      result: 'target-dispatched',
+    });
     return;
   }
 
   if (profileCommandListeners.size === 0) {
     queuePendingProfileCommand(command);
+    logProfileSession('command', {
+      ...command,
+      status: 'queued',
+      reason: 'no-command-listener',
+    });
     return;
   }
 
   for (const listener of profileCommandListeners) {
     listener(command);
   }
+  logProfileSession('command', {
+    ...command,
+    status: 'delivered',
+    result: 'listener-notified',
+  });
+}
+
+function processSequencedProfileCommands() {
+  if (profileCommandProcessingScheduled) {
+    return;
+  }
+  const remainingMs = Math.max(0, profileCommandProcessingAvailableAt - Date.now());
+  if (remainingMs > 0) {
+    scheduleProfileCommandProcessing(remainingMs);
+    return;
+  }
+  if (profileCommandMilestoneGate) {
+    return;
+  }
+
+  while (sequencedProfileCommands.length > 0) {
+    const command = sequencedProfileCommands.shift();
+    if (!command || hasProcessedProfileCommandId(command)) {
+      continue;
+    }
+
+    markProfileCommandIdProcessed(command);
+    const nextGate = hasObservedProfileCommandMilestone(command)
+      ? null
+      : buildProfileCommandMilestoneGate(command);
+    profileCommandMilestoneGate = nextGate;
+    logProfileSession('command', {
+      ...command,
+      status: 'received',
+    });
+    startProfileCommandMilestoneTimeout(command);
+    notifyProfileCommandListeners(command);
+
+    if (profileCommandMilestoneGate) {
+      return;
+    }
+    if (typeof command.waitMs === 'number' && command.waitMs > 0) {
+      scheduleProfileCommandProcessing(command.waitMs);
+      return;
+    }
+  }
+}
+
+function enqueueSequencedProfileCommands(commands: ProfileSessionCommand[]) {
+  const nextCommands = commands.filter(shouldQueueProfileCommand);
+  if (nextCommands.length === 0) {
+    return;
+  }
+
+  sequencedProfileCommands.push(...nextCommands);
+  sequencedProfileCommands.sort(compareProfileCommands);
+  processSequencedProfileCommands();
+}
+
+function releaseProfileCommandMilestoneGate(eventPayload: StoredProfileEvent) {
+  if (!profileCommandMilestoneGate || profileCommandMilestoneGate.milestone !== eventPayload.event) {
+    return;
+  }
+  if (
+    profileCommandMilestoneGate.runId &&
+    profileCommandMilestoneGate.runId !== eventPayload.runId
+  ) {
+    return;
+  }
+  if (
+    profileCommandMilestoneGate.scenario &&
+    profileCommandMilestoneGate.scenario !== eventPayload.scenario
+  ) {
+    return;
+  }
+
+  const waitMs = typeof profileCommandMilestoneGate.waitMs === 'number'
+    ? profileCommandMilestoneGate.waitMs
+    : 0;
+  clearProfileCommandMilestoneGate();
+  scheduleProfileCommandProcessing(waitMs);
 }
 
 function flushPendingProfileCommands(listener: (command: ProfileSessionCommand) => void) {
@@ -560,11 +891,16 @@ export function applyProfileSessionUrl(url: string | null | undefined): boolean
       scenario: route.scenario,
       runId: route.runId,
       command: route.command,
+      ...(route.commandId ? { commandId: route.commandId } : {}),
+      ...(route.queueId ? { queueId: route.queueId } : {}),
+      ...(typeof route.sequence === 'number' ? { sequence: route.sequence } : {}),
       source: 'deeplink' as const,
       timestamp,
+      ...(route.waitForMilestone ? { waitForMilestone: route.waitForMilestone } : {}),
+      ...(typeof route.waitMs === 'number' ? { waitMs: route.waitMs } : {}),
+      ...(typeof route.waitTimeoutMs === 'number' ? { waitTimeoutMs: route.waitTimeoutMs } : {}),
     };
-    logProfileSession('command', command);
-    notifyProfileCommandListeners(command);
+    enqueueSequencedProfileCommands([command]);
     return true;
   }
 
@@ -607,7 +943,12 @@ export function emitProfileEvent(event: string, metadata?: ProfileEventMetadata)
   };
 
   writeProfileLog(buildLogLine('profile-event', eventPayload));
+  observedProfileEvents.push(eventPayload);
+  while (observedProfileEvents.length > MAX_STORED_PROFILE_EVENTS) {
+    observedProfileEvents.shift();
+  }
   appendStoredProfileEvent(eventPayload);
+  releaseProfileCommandMilestoneGate(eventPayload);
 }
 
 /**
@@ -747,7 +1088,7 @@ export function useProfileSessionBootstrap(): void {
         return;
       }
 
-      clearPendingProfileCommands();
+      const nextCommands: ProfileSessionCommand[] = [];
       for (const command of storedCommands) {
         if (
           !command ||
@@ -760,8 +1101,7 @@ export function useProfileSessionBootstrap(): void {
 
         if (
           command.scenario !== activeSession.scenario ||
-          command.runId !== activeSession.runId ||
-          (typeof activeSession.startedAt === 'number' && command.timestamp < activeSession.startedAt)
+          command.runId !== activeSession.runId
         ) {
           continue;
         }
@@ -775,10 +1115,10 @@ export function useProfileSessionBootstrap(): void {
           continue;
         }
 
-        markProfileCommandIdProcessed(storageCommand);
-        logProfileSession('command', storageCommand);
-        notifyProfileCommandListeners(storageCommand);
+        nextCommands.push(storageCommand);
       }
+
+      enqueueSequencedProfileCommands(nextCommands);
     };
 
     syncStoredProfileState()

package/dist/core/agent-summary.d.ts

@@ -1,10 +1,10 @@
 /**
  * Builds the minimum agent-facing markdown summary for a run.
  *
- * @param {{health: Record<string, unknown>, verdict: Record<string, unknown>, comparison?: Record<string, unknown> | null}} options
+ * @param {{health: Record<string, unknown>, verdict: Record<string, unknown>, comparison?: Record<string, unknown> | null, manifest?: Record<string, unknown> | null}} options
  * @returns {string}
  */
-declare function buildAgentSummaryMarkdown({ health, verdict, comparison }: AgentSummaryInput): string;
+declare function buildAgentSummaryMarkdown({ health, verdict, comparison, manifest }: AgentSummaryInput): string;
 export { buildAgentSummaryMarkdown, };
 export type { AgentSummaryInput, SummaryRecord, };
 type SummaryRecord = Record<string, unknown>;
@@ -12,4 +12,5 @@ type AgentSummaryInput = {
     health: SummaryRecord;
     verdict: SummaryRecord;
     comparison?: SummaryRecord | null;
+    manifest?: SummaryRecord | null;
 };

package/dist/core/agent-summary.js

@@ -122,13 +122,54 @@ function formatComparisonBasis(comparison) {
     }
     return lines;
 }
+/**
+ * Formats attempt terminal semantics for agent-readable summaries.
+ *
+ * @param {SummaryRecord | null | undefined} manifest
+ * @returns {string[]}
+ */
+function formatAttempt(manifest) {
+    const attempt = manifest?.attempt;
+    if (!attempt || typeof attempt !== 'object' || Array.isArray(attempt)) {
+        return [];
+    }
+    const attemptRecord = attempt;
+    const classification = attemptRecord.classification && typeof attemptRecord.classification === 'object' && !Array.isArray(attemptRecord.classification)
+        ? attemptRecord.classification
+        : {};
+    const cleanup = attemptRecord.cleanup && typeof attemptRecord.cleanup === 'object' && !Array.isArray(attemptRecord.cleanup)
+        ? attemptRecord.cleanup
+        : {};
+    const partialArtifacts = attemptRecord.partialArtifacts && typeof attemptRecord.partialArtifacts === 'object' && !Array.isArray(attemptRecord.partialArtifacts)
+        ? attemptRecord.partialArtifacts
+        : {};
+    const retryOfAttemptId = firstString([attemptRecord.retryOfAttemptId], '');
+    const retryReason = firstString([attemptRecord.retryReason], '');
+    const lines = [
+        '',
+        '## attempt',
+        '',
+        `- Attempt: ${code(firstString([attemptRecord.attemptId], 'unknown-attempt'))} (${attemptRecord.attemptNumber ?? 'unknown'}/${attemptRecord.maxAttempts ?? 'unknown'})`,
+        `- Terminal state: ${code(firstString([attemptRecord.terminalState], 'unknown'))}`,
+        `- Classification: ${code(firstString([classification.category], 'unknown'))}${classification.code ? ` ${code(classification.code)}` : ''}`,
+        `- Cleanup: ${code(firstString([cleanup.status], 'unknown'))}`,
+        `- Partial artifacts valid: ${partialArtifacts.valid === true ? 'true' : 'false'} - ${firstString([partialArtifacts.reason], 'no reason recorded')}`,
+    ];
+    if (retryOfAttemptId || retryReason) {
+        lines.push(`- Retry lineage: previous=${code(retryOfAttemptId || 'unknown')} reason=${retryReason || 'not recorded'}`);
+    }
+    if (Array.isArray(partialArtifacts.paths) && partialArtifacts.paths.length > 0) {
+        lines.push(`- Partial artifact paths: ${partialArtifacts.paths.map((item) => code(item)).join(', ')}`);
+    }
+    return lines;
+}
 /**
  * Builds the minimum agent-facing markdown summary for a run.
  *
- * @param {{health: Record<string, unknown>, verdict: Record<string, unknown>, comparison?: Record<string, unknown> | null}} options
+ * @param {{health: Record<string, unknown>, verdict: Record<string, unknown>, comparison?: Record<string, unknown> | null, manifest?: Record<string, unknown> | null}} options
  * @returns {string}
  */
-function buildAgentSummaryMarkdown({ health, verdict, comparison = null }) {
+function buildAgentSummaryMarkdown({ health, verdict, comparison = null, manifest = null }) {
     const scenarioId = firstString([health?.scenarioId, verdict?.scenarioId], 'unknown-scenario');
     const runId = firstString([health?.runId, verdict?.runId], 'unknown-run');
     const healthStatus = firstString([health?.healthStatus], 'failed');
@@ -169,6 +210,7 @@ function buildAgentSummaryMarkdown({ health, verdict, comparison = null }) {
     if (failedBudgets.length > 0) {
         lines.push('', '## failed budgets', '', ...failedBudgets);
     }
+    lines.push(...formatAttempt(manifest));
     if (comparison) {
         lines.push('', '## comparison', '', firstString([comparison.summary], 'No comparison summary provided.'));
         lines.push(...formatComparisonBasis(comparison));