@pikku/core 0.12.74 → 0.12.78

package/src/wirings/virtual-user/prepare-virtual-user-run.ts

@@ -0,0 +1,95 @@
+import type { FunctionsMeta } from '../../types/core.types.js'
+import type { WorkflowsMeta } from '../workflow/workflow.types.js'
+import { flattenSystemRoleDefinitions } from '../role/validate-role-definitions.js'
+import type {
+  SystemRoleDefinitions,
+  SystemRoleDefinitionsMeta,
+} from '../role/role.types.js'
+import {
+  deriveCatalogue,
+  deriveIntents,
+  type SchemaMap,
+} from './virtual-user-derive.js'
+import {
+  reachableAgents,
+  type AgentReachability,
+  type ReachableAgent,
+} from './virtual-user-agents.js'
+import type { ApiCatalogueEntry, IntentSource } from './virtual-user.types.js'
+
+/**
+ * The scopes a persona holds, resolved through its roles.
+ *
+ * Roles are the only thing a persona declares; scopes are what a function
+ * checks. Narrowing a virtual user's catalogue needs the second, so the
+ * expansion happens once, here, against the same `defineSystemRole` definitions
+ * the seed grants from.
+ */
+export const personaScopes = (
+  persona: { roles?: readonly string[] },
+  roleScopes: Record<string, readonly string[]>
+): string[] => {
+  const scopes = new Set<string>()
+  for (const role of persona.roles ?? []) {
+    for (const scope of roleScopes[role] ?? []) {
+      scopes.add(scope)
+    }
+  }
+  return [...scopes].sort()
+}
+
+/** Everything a run needs that is derived rather than decided. */
+export interface VirtualUserPreparation {
+  /** Every RPC the app exposes, narrowed to what this persona can reach. */
+  catalogue: ApiCatalogueEntry[]
+  intents: IntentSource[]
+  scopes: string[]
+  agents: ReachableAgent[]
+}
+
+/**
+ * Derive what a virtual user needs from what the project already generates.
+ *
+ * Shared because there are two callers with the same problem and different
+ * sources for it: `pikku persona run` reads the inspector state at build time,
+ * and the scaffolded `runVirtualUser` RPC reads `metaService` at runtime. They
+ * must agree — a persona whose catalogue is narrower over RPC than on the CLI
+ * finds different things from the same seed, which is exactly the property a
+ * seed exists to give.
+ *
+ * Nothing here is authored for the virtual user's benefit: the function meta is
+ * the catalogue, the scenario meta is the intents, and the role definitions are
+ * what turn a persona's declared roles into the scopes a function checks.
+ */
+export const prepareVirtualUserRun = (input: {
+  persona: { roles?: readonly string[] }
+  functionsMeta: FunctionsMeta
+  schemas?: SchemaMap
+  workflowsMeta?: WorkflowsMeta
+  /**
+   * Either shape: the inspector holds an array, `metaService` hands back the
+   * same definitions keyed by name. Accepting both is what lets the CLI and the
+   * scaffolded RPC share this.
+   */
+  systemRoles?: SystemRoleDefinitions | SystemRoleDefinitionsMeta
+  agentsMeta?: Readonly<Record<string, AgentReachability>>
+}): VirtualUserPreparation => {
+  const catalogue = deriveCatalogue(input.functionsMeta, input.schemas ?? {})
+  const intents = deriveIntents(input.workflowsMeta ?? {}, input.functionsMeta)
+
+  const declared = input.systemRoles ?? []
+  const roleScopes: Record<string, string[]> = {}
+  for (const role of flattenSystemRoleDefinitions(
+    Array.isArray(declared) ? declared : Object.values(declared)
+  )) {
+    roleScopes[role.name] = role.scopes
+  }
+  const scopes = personaScopes(input.persona, roleScopes)
+
+  // Gated by the same scopes as the RPCs, because an agent is reached rather
+  // than declared: `CoreAIAgent.scopes` is checked against the session, so a
+  // persona finds the specialists its roles unlock and no others.
+  const agents = reachableAgents(input.agentsMeta ?? {}, scopes)
+
+  return { catalogue, intents, scopes, agents }
+}

package/src/wirings/virtual-user/virtual-user-run-store.ts

@@ -0,0 +1,98 @@
+import type {
+  VirtualUserDisposition,
+  VirtualUserFinding,
+  VirtualUserTally,
+} from './virtual-user.types.js'
+
+/**
+ * One recorded run: who ran, what they were told, and what came back.
+ *
+ * A run is dispatched and answered for later, so the record is created before
+ * the work starts and is the thing the returned `runId` addresses.
+ *
+ * This record is a run's ONLY trace. A virtual user is not a workflow — it
+ * explores, so no two attempts take the same steps and there is nothing to
+ * replay — and it is not queued either, because the record already carries the
+ * progress a queue would only be holding on the way here.
+ *
+ * The cost of that is the one thing to know when reading `status`: a restart
+ * mid-run leaves a record at `running` with nothing left to finish it. A run
+ * older than its budget window and still `running` is dead, not working.
+ */
+export interface VirtualUserRunRecord {
+  runId: string
+  persona: string
+  disposition: VirtualUserDisposition
+  /** What makes a run replayable at all — a finding without it is an anecdote. */
+  seed: number
+  /**
+   * `running` until the engine returns. Not derived from `finishedAt` being
+   * unset: a crashed run has no finish time either, and the two are not the
+   * same result.
+   */
+  status: 'running' | 'completed' | 'failed'
+  /** The caller's situational goals, run alongside the derived intents. */
+  goals: string[]
+  /**
+   * Ids and slugs the user carried in, and whatever it learned on the way out.
+   * Kept because a finding only reproduces alongside the notes that produced it.
+   */
+  memory: Record<string, string>
+  findings: VirtualUserFinding[]
+  tally: VirtualUserTally | null
+  /** Which budget or stopping rule ended the run. */
+  stoppedBy: string | null
+  /**
+   * Why the run itself failed, as opposed to what it found. A run that could
+   * not start has no findings and is not a clean empty result.
+   */
+  error: string | null
+  /** The session that started it, where the host tracks one. */
+  startedBy: string | null
+  createdAt: Date
+  finishedAt: Date | null
+}
+
+/** What a run is created with — everything else is filled in by the outcome. */
+export interface VirtualUserRunStart {
+  persona: string
+  disposition: VirtualUserDisposition
+  seed: number
+  goals?: readonly string[]
+  memory?: Record<string, string>
+  startedBy?: string | null
+}
+
+/** The outcome of a run that reached the end of its budget without throwing. */
+export interface VirtualUserRunOutcome {
+  findings: readonly VirtualUserFinding[]
+  tally: VirtualUserTally
+  memory: Record<string, string>
+  stoppedBy: string | null
+}
+
+/**
+ * Where runs are kept. Declared here rather than in a database package so the
+ * scaffolded RPCs depend on the shape and not on kysely — `@pikku/kysely` ships
+ * one implementation, and an app with its own store satisfies this instead.
+ *
+ * SECURITY: findings from an `adversarial` run are working exploits carrying
+ * live ids. An implementation is a privileged store; the scaffold gates every
+ * read behind a scope for that reason, and a host exposing these records more
+ * widely is publishing its own exploits.
+ */
+export interface VirtualUserRunStore {
+  /** Records a run as `running` and returns its id. */
+  start(run: VirtualUserRunStart): Promise<string>
+  /** Marks a run `completed` and stores what it found. */
+  complete(runId: string, outcome: VirtualUserRunOutcome): Promise<void>
+  /** Marks a run `failed`. The run itself broke; it has no findings. */
+  fail(runId: string, error: string): Promise<void>
+  get(runId: string): Promise<VirtualUserRunRecord | null>
+  /** Newest first. `persona` narrows to one persona's history. */
+  list(options?: {
+    persona?: string
+    limit?: number
+    offset?: number
+  }): Promise<VirtualUserRunRecord[]>
+}

package/src/wirings/workflow/dsl/workflow-dsl.types.ts

@@ -85,7 +85,7 @@ export type WorkflowWireDoInline = <T>(
 ) => Promise<T>
 
 /**
- * Type signature for scenario.step/given/when/then - used by inspector.
+ * Type signature for scenario.given/when/then - used by inspector.
  *
  * Deliberately mirrors WorkflowWireDoRPC's shape: the target is a string, not
  * an imported symbol, so the extractor reads it as a literal.
@@ -199,7 +199,7 @@ export interface RpcStepMeta {
 }
 
 /**
- * Scenario step metadata — a call to `scenario.step/given/when/then`.
+ * Scenario step metadata — a call to `scenario.given/when/then`.
  *
  * Distinct from RpcStepMeta on purpose: a step runs locally through
  * runPikkuFunc and must never be treated as dispatchable on the queue/replay
@@ -212,7 +212,7 @@ export interface ScenarioStepMeta {
   stepName: string
   /** Registered name of the step function being run */
   stepFunc: string
-  /** Which keyword the reporter prefixes — given/when/then, or none for `step` */
+  /** Which keyword the reporter prefixes — Given, When or Then */
   phase: ScenarioStepPhase
   /** Output variable name (if assigned) */
   outputVar?: string
@@ -557,20 +557,14 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
   ) => Promise<void>
 
   /**
-   * Run a registered scenario step. Shaped exactly like `do`'s RPC form —
-   * `(stepName, target, data, options)` — so the inspector reads the target as
-   * a string literal rather than resolving an imported symbol.
+   * Run a registered scenario step, as the setup the scenario starts from.
+   *
+   * Shaped exactly like `do`'s RPC form — `(stepName, target, data, options)` —
+   * so the inspector reads the target as a string literal rather than resolving
+   * an imported symbol.
    *
    * The generated `TypedScenario` narrows these over `FlattenedScenarioStepMap`.
    */
-  step(
-    stepName: string,
-    stepFunc: string,
-    data?: any,
-    options?: ScenarioStepOptions
-  ): Promise<any>
-
-  /** `step` with a "Given" prefix in the rendered prose */
   given(
     stepName: string,
     stepFunc: string,
@@ -578,7 +572,7 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
     options?: ScenarioStepOptions
   ): Promise<any>
 
-  /** `step` with a "When" prefix in the rendered prose */
+  /** `when`: the same call as `given`, rendered as the action under test */
   when(
     stepName: string,
     stepFunc: string,
@@ -586,7 +580,11 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
     options?: ScenarioStepOptions
   ): Promise<any>
 
-  /** `step` with a "Then" prefix in the rendered prose */
+  /**
+   * `then`: a claim about what the action left behind. Unlike `given`/`when`
+   * this is not prose alone — the step's bindings become witnesses, so every
+   * declared surface is observed and the observations must agree.
+   */
   then(
     stepName: string,
     stepFunc: string,

package/src/wirings/workflow/pikku-scenario-service.ts

@@ -649,20 +649,11 @@ export class PikkuScenarioService implements WorkflowRunExtension {
       },
 
       // Scenario steps: a named `pikkuScenarioStep` run as one durable step.
-      // `given`/`when`/`step` are sugar for each other, differing only in the
+      // `given`/`when` are sugar for each other, differing only in the
       // prose a reporter renders. `then` is not: the phase is what decides
       // whether the step's bindings are alternatives or witnesses, so the same
       // step function called two ways runs differently. See
       // {@link resolveScenarioSurfaces}.
-      step: (stepName, stepFunc, data, options) =>
-        this.scenarioStep(
-          'step',
-          scenarioStepContext(),
-          stepName,
-          stepFunc,
-          data,
-          options
-        ),
       given: (stepName, stepFunc, data, options) =>
         this.scenarioStep(
           'given',

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -275,6 +275,12 @@ const WORKFLOW_TERMINAL_STATES: ReadonlySet<string> = new Set([
   'cancelled',
 ])
 
+/** Idle window before a `running` run with nothing in flight is treated as stalled. */
+const DEFAULT_STALLED_RUN_MS = 5 * 60_000
+
+/** Runs re-driven per `recoverStalledRuns` call, so one sweep is bounded. */
+const DEFAULT_STALLED_RUN_LIMIT = 100
+
 const WORKFLOW_POLL_MIN_MS = 10
 
 const WORKFLOW_POLL_FACTOR = 1.6
@@ -908,6 +914,67 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     )
   }
 
+  /**
+   * Ids of runs that are stalled: still `running`, with no step in a state that
+   * something is expected to complete (`running`, `scheduled`, `suspended`),
+   * and no step activity since `before`.
+   *
+   * Returns nothing by default so a store that cannot express the query keeps
+   * working unchanged; a store that overrides it gains crash recovery through
+   * `recoverStalledRuns`.
+   */
+  protected async findStalledRunIds(
+    _before: Date,
+    _limit: number
+  ): Promise<string[]> {
+    return []
+  }
+
+  /**
+   * Re-drive runs whose next move was lost, and report which were resumed.
+   *
+   * Arming a step is two writes to two systems — the step row, then the queue
+   * or scheduler job — so a process that dies between them leaves a run that is
+   * `running` with nothing in flight. Nothing notices: the run parks on a step
+   * that will never complete and never error, so it neither finishes nor fails.
+   * (Seen on a `workflow.sleep()`: a deploy restart landed between the sleep
+   * step's insert and its timer, parking the run permanently.)
+   *
+   * Replay is the recovery — `resumeWorkflow` re-orchestrates from persisted
+   * step state, and every settled step is memoized, so resuming a run that was
+   * not actually stuck costs an orchestration pass and changes nothing. That
+   * idempotence is what makes an idle-time heuristic safe here; a run that is
+   * legitimately mid-sleep is excluded anyway, since its step is `scheduled`.
+   *
+   * This is not self-starting. Call it from a scheduled task at whatever
+   * interval suits the workload.
+   */
+  public async recoverStalledRuns(options?: {
+    stalledAfterMs?: number
+    limit?: number
+  }): Promise<{ resumed: string[] }> {
+    const before = new Date(
+      Date.now() - (options?.stalledAfterMs ?? DEFAULT_STALLED_RUN_MS)
+    )
+    const runIds = await this.findStalledRunIds(
+      before,
+      options?.limit ?? DEFAULT_STALLED_RUN_LIMIT
+    )
+    const resumed: string[] = []
+    for (const runId of runIds) {
+      try {
+        await this.resumeWorkflow(runId)
+        resumed.push(runId)
+      } catch (err) {
+        // One unresumable run must not stop the sweep from recovering the rest.
+        getSingletonServices()?.logger?.error(
+          `Failed to resume stalled workflow run ${runId}: ${err instanceof Error ? err.message : String(err)}`
+        )
+      }
+    }
+    return { resumed }
+  }
+
   protected resolveStepJobOptions(
     stepOptions?: WorkflowStepOptions
   ): JobOptions {

package/src/wirings/workflow/scenario-prose.test.ts

@@ -110,14 +110,14 @@ describe('composeStepProse basics', () => {
     )
   })
 
-  test('the neutral `step` phase adds no keyword', () => {
+  test('every phase renders its keyword', () => {
     assert.equal(
       composeStepProse({
-        phase: 'step',
+        phase: 'when',
         description: 'refreshes the dashboard',
         actor: 'admin',
       }),
-      'the admin refreshes the dashboard'
+      'When the admin refreshes the dashboard'
     )
   })
 
@@ -127,7 +127,6 @@ describe('composeStepProse basics', () => {
         { phase: 'given', description: 'buys an apple' },
         { phase: 'when', description: 'checks out' },
         { phase: 'then', description: 'sees a receipt' },
-        { phase: 'step', description: 'waits' },
       ] as const
     ).map((step) =>
       composeStepProse({ ...step, actor: 'shopper', keywordWidth: 5 })
@@ -137,7 +136,6 @@ describe('composeStepProse basics', () => {
       'Given the shopper buys an apple',
       'When  the shopper checks out',
       'Then  the shopper sees a receipt',
-      '      the shopper waits',
     ])
     const columns = new Set(rendered.map((line) => line.indexOf('the shopper')))
     assert.equal(columns.size, 1, 'every sentence starts in the same column')
@@ -145,8 +143,8 @@ describe('composeStepProse basics', () => {
 
   test('prose degrades to just the description when nothing else is known', () => {
     assert.equal(
-      composeStepProse({ phase: 'step', description: 'does the thing' }),
-      'does the thing'
+      composeStepProse({ phase: 'when', description: 'does the thing' }),
+      'When does the thing'
     )
   })
 })

package/src/wirings/workflow/scenario-prose.ts

@@ -37,7 +37,7 @@ export const composeStepProse = ({
   actor?: string
   keywordWidth?: number
 }): string => {
-  const keyword = phase === 'step' ? '' : capitalise(phase)
+  const keyword = capitalise(phase)
   const subject = actor ? `the ${actor}` : ''
   const rendered = template ? renderStepTemplate(template, input) : description
   const sentence = [subject, rendered].filter(Boolean).join(' ')

package/src/wirings/workflow/scenario-service.test.ts

@@ -21,7 +21,6 @@ const SCENARIO_MEMBERS = [
 ]
 
 const SCENARIO_WIRE_MEMBERS = [
-  'step',
   'given',
   'when',
   'then',

package/src/wirings/workflow/scenario-step.test.ts

@@ -155,7 +155,7 @@ const registerStep = (
   } as any
 }
 
-describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
+describe('pikkuScenarioStep (scenario.given/when/then)', () => {
   beforeEach(() => resetPikkuState())
 
   test('the step func is called with the phase, step identity and data on the wire', async () => {
@@ -202,12 +202,11 @@ describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
 
     const runId = await setup(ws)
     const wire = ws.createWorkflowWire('scenarioTest', runId, {})
-    await wire.step('a', 'noop')
     await wire.given('b', 'noop')
     await wire.when('c', 'noop')
     await wire.then('d', 'noop')
 
-    assert.deepEqual(phases, ['step', 'given', 'when', 'then'])
+    assert.deepEqual(phases, ['given', 'when', 'then'])
   })
 
   test('the actor is handed to the step rather than used to dispatch it', async () => {
@@ -291,7 +290,7 @@ describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
 
     const runId = await setup(ws)
     const wire = ws.createWorkflowWire('scenarioTest', runId, {})
-    const result = await wire.step('waits for the page', 'flaky', undefined, {
+    const result = await wire.when('waits for the page', 'flaky', undefined, {
       retries: 3,
       retryDelay: 1,
     })
@@ -509,7 +508,7 @@ describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
     const wire = ws.createWorkflowWire('scenarioTest', runId, {})
 
     await assert.rejects(
-      (wire.step as any)('a name', async () => 'inline'),
+      (wire.when as any)('a name', async () => 'inline'),
       /string/i
     )
   })

package/src/wirings/workflow/scenario-step.types.ts

@@ -4,15 +4,21 @@ import type { ScenarioPersona } from '../../services/personas-service.js'
  * Scenario steps: named, typed units of scenario behaviour.
  *
  * A step's body is an ordinary pikku function, so it may drive a browser, call
- * an RPC as its actor, or run a workflow. `given`/`when`/`then` are sugar over
- * `step` — they only change the prose the reporter renders.
+ * an RPC as its actor, or run a workflow. `given` and `when` differ only in the
+ * prose the reporter renders; `then` also changes what runs, because its
+ * bindings are witnesses — every declared surface is observed and the
+ * observations must agree. See {@link ScenarioSurfaceResolution}.
  */
 
 /**
- * Which Gherkin-style keyword the reporter prefixes this step with. `step`
- * renders no prefix at all.
+ * Which Gherkin-style keyword the reporter prefixes this step with.
+ *
+ * Every step takes one. A scenario is read by people deciding whether it
+ * describes the behaviour they wanted, and a step that says only what it does
+ * without saying whether it is setup, action or claim is the one nobody can
+ * check — which is also why PKU680 can tell a scenario that never asserts.
  */
-export type ScenarioStepPhase = 'step' | 'given' | 'when' | 'then'
+export type ScenarioStepPhase = 'given' | 'when' | 'then'
 
 /**
  * Who acts in a step.
@@ -51,7 +57,7 @@ export const SCENARIO_SURFACES: readonly ScenarioSurface[] = [
 /**
  * How a step's declared surfaces resolve for one run.
  *
- * `given`/`when`/`step` bindings are **alternatives** — clicking Buy and calling
+ * `given`/`when` bindings are **alternatives** — clicking Buy and calling
  * `createOrder` are two ways to cause one effect, so exactly one runs.
  *
  * `then` bindings are **witnesses** — "the order row says paid" and "the
@@ -86,7 +92,7 @@ export type ScenarioSurfaceResolution =
     }
 
 /**
- * Options accepted by `scenario.step/given/when/then`.
+ * Options accepted by `scenario.given/when/then`.
  *
  * Note the retry default differs from an ordinary workflow step: retrying a
  * failed assertion is the wrong behaviour for a test primitive, so steps

package/src/wirings/workflow/scenario-surface.test.ts

@@ -22,11 +22,12 @@ describe('action steps pick exactly one binding', () => {
     })
   })
 
-  test('given and step resolve like when, not like then', () => {
-    for (const phase of ['given', 'step'] as const) {
-      const resolution = resolveScenarioSurfaces(phase, ALL, 'cli')
-      assert.equal(resolution.kind, 'action')
-    }
+  test('given resolves like when, not like then', () => {
+    assert.deepEqual(resolveScenarioSurfaces('given', ALL, 'cli'), {
+      kind: 'action',
+      surface: 'cli',
+      fellBack: false,
+    })
   })
 
   test('a default run never counts as a fallback', () => {

package/src/wirings/workflow/workflow-stalled-recovery.test.ts

@@ -0,0 +1,106 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
+import { pikkuState } from '../../pikku-state.js'
+
+const silentLogger = { error() {}, info() {}, warn() {}, debug() {} }
+
+/**
+ * `recoverStalledRuns` re-drives a run by putting it back on the orchestrator
+ * queue, so the queue is the observation point.
+ */
+function trackResumes(): { runIds: string[] } {
+  const seen: string[] = []
+  pikkuState(null, 'package', 'singletonServices', {
+    queueService: {
+      add: async (_queue: string, data: { runId: string }) => {
+        seen.push(data.runId)
+      },
+    },
+    logger: silentLogger,
+  } as any)
+  return { runIds: seen }
+}
+
+/** Backdates every persisted timestamp so the run reads as idle. */
+async function backdate(
+  ws: InMemoryWorkflowService,
+  runId: string,
+  ms: number
+): Promise<void> {
+  const past = new Date(Date.now() - ms)
+  const run = await ws.getRun(runId)
+  ;(run as any).updatedAt = past
+  for (const step of await ws.getRunHistory(runId)) {
+    ;(step as any).updatedAt = past
+  }
+}
+
+describe('stalled run recovery', () => {
+  test('resumes a running run left with a pending step and nothing in flight', async () => {
+    const resumes = trackResumes()
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+    // A sleep whose timer was never armed: the step row exists, nothing will
+    // ever complete it.
+    await ws.insertStepState(runId, 'Wait 15s', null, { duration: 15000 })
+    await backdate(ws, runId, 10 * 60_000)
+
+    const { resumed } = await ws.recoverStalledRuns()
+
+    assert.deepEqual(resumed, [runId], 'the orphaned run is resumed')
+    assert.deepEqual(resumes.runIds, [runId], 'it is put back on the queue')
+  })
+
+  test('leaves a run alone while a step is still scheduled', async () => {
+    trackResumes()
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+    const step = await ws.insertStepState(runId, 'Wait 1h', null, {
+      duration: 3_600_000,
+    })
+    await ws.setStepScheduled(step.stepId)
+    await backdate(ws, runId, 10 * 60_000)
+
+    const { resumed } = await ws.recoverStalledRuns()
+
+    assert.deepEqual(
+      resumed,
+      [],
+      'a legitimately sleeping run is not a stalled run'
+    )
+  })
+
+  test('leaves a run alone until it has actually gone idle', async () => {
+    trackResumes()
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+    await ws.insertStepState(runId, 'Wait 15s', null, { duration: 15000 })
+
+    const { resumed } = await ws.recoverStalledRuns()
+
+    assert.deepEqual(resumed, [], 'a run that just moved is not swept')
+  })
+
+  test('leaves a finished run alone', async () => {
+    trackResumes()
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+    await ws.insertStepState(runId, 'Wait 15s', null, { duration: 15000 })
+    await ws.updateRunStatus(runId, 'completed')
+    await backdate(ws, runId, 10 * 60_000)
+
+    const { resumed } = await ws.recoverStalledRuns()
+
+    assert.deepEqual(resumed, [], 'only running runs are swept')
+  })
+})

package/src/wirings/workflow/workflow.types.ts

@@ -302,6 +302,13 @@ export type WorkflowsMeta = Record<
     dsl?: boolean
     expose?: boolean
     scenario?: boolean
+    /**
+     * The flow asserts through an expectation helper — `expectService`,
+     * `expectError`, `expectEventually` — rather than a `then` step. Those are
+     * inline steps and carry no phase, so without this PKU680 reads a scenario
+     * whose only witness is a recorded service call as asserting nothing.
+     */
+    asserts?: boolean
     skip?: string
     actors?: string[]
   }