@namzu/sdk 43.0.0 → 44.1.0

package/src/turn/command-gate.ts

@@ -0,0 +1,294 @@
+/**
+ * A {@link ReviewAnswer} that runs shell commands and hands the failure back.
+ *
+ * `reviewAnswer` was the seam for exactly this — judge the answer at the point
+ * the model stops calling tools, and return it with feedback instead of
+ * settling — and nothing shipped supplied one, so an operator who wanted
+ * "don't finish until the build passes" had to write TypeScript. This is the
+ * supplier. With it, `--gate 'pnpm test'` is the whole unattended story: the
+ * model works, stops, the tests run, and a failure comes back as the next user
+ * turn rather than as a green run somebody discovers in CI.
+ *
+ * The kernel already bounds it. The reviewer is consulted only when the model
+ * stopped calling tools, never on the forced-final turn, and a rejection
+ * budget stops the turn with `answer_rejected` — a stop reason that names the
+ * reviewer rather than blaming a token budget. None of that is re-implemented
+ * here.
+ *
+ * ## The part that is not just "run a command"
+ *
+ * **Before re-running a command that already failed, the workspace is
+ * fingerprinted, and an identical fingerprint means the command is NOT run.**
+ *
+ * This is the difference between a bounded loop and one that spends its whole
+ * budget. A model that has run out of ideas answers again without editing
+ * anything; re-running the suite then costs a full execution — often the most
+ * expensive thing in the loop — to produce a failure already known character
+ * for character. Worse, the feedback is identical, so the model is handed the
+ * same prompt that just failed to help it. Saying instead "the workspace has
+ * not changed since that failure; edit something before trying to finish"
+ * is both cheaper and a different instruction.
+ *
+ * The attempt still advances. Skipping the command is a saving, not a pardon:
+ * an answer that changed nothing has been rejected, and the turn's budget must
+ * see that or a stuck model loops forever for free.
+ *
+ * And it fails open on the cheap side. No fingerprint — a git invocation that
+ * errored, a timeout, output past the cap, a tree with no commits — means the
+ * command runs. See {@link fingerprintWorkspace}: the cost of re-running
+ * unnecessarily is one execution; the cost of wrongly skipping is a
+ * verification that silently did not happen.
+ */
+
+import { LocalExecutionContext } from '../execution/local.js'
+import type { CommandOptions, CommandResult } from '../types/execution/index.js'
+import type { AnswerReview, ReviewAnswer } from '../types/session/answer-review.js'
+import { fingerprintWorkspace } from './workspace-fingerprint.js'
+
+/** How the gate runs a command. Injected so a test needs no shell. */
+export type GateExec = (
+	command: string,
+	args: string[],
+	options?: CommandOptions,
+) => Promise<CommandResult>
+
+/** Default per-command deadline. A test suite is allowed to be slow. */
+export const DEFAULT_GATE_TIMEOUT_MS = 600_000
+
+/** How many attempts the gate will EXECUTE its commands for, by default. */
+export const DEFAULT_GATE_MAX_RETRIES = 3
+
+/**
+ * Model-visible characters of a failing command's output.
+ *
+ * Head and tail, not head alone: a compiler names the file at the top and a
+ * test runner names the failure at the bottom, and a gate that only ever kept
+ * one end would be useless for one of them.
+ */
+export const DEFAULT_GATE_OUTPUT_CHARS = 4_000
+
+export interface CommandGateOptions {
+	/**
+	 * Shell command lines, run in order, stopping at the first failure.
+	 *
+	 * In order and short-circuiting because that is what a person means by
+	 * "typecheck then test": a type error makes the test output noise about
+	 * the same cause, and handing the model both invites it to fix the
+	 * symptom.
+	 */
+	readonly commands: readonly string[]
+	/** Directory the commands run in, and the tree that is fingerprinted. */
+	readonly cwd: string
+	/**
+	 * How many attempts will actually EXECUTE the commands.
+	 *
+	 * Past it the gate rejects without running anything, naming the
+	 * exhaustion. It does not accept: an answer that never passed the gate
+	 * has not passed the gate, and a reviewer that gave up by accepting would
+	 * hand back a green run over a red build — the exact outcome the gate
+	 * exists to prevent. What ENDS the turn is the kernel's rejection budget,
+	 * so set that to the same number (the CLI does).
+	 */
+	readonly maxRetries?: number
+	/** Per-command deadline. See {@link DEFAULT_GATE_TIMEOUT_MS}. */
+	readonly timeoutMs?: number
+	/** Override the executor. Defaults to a local shell in `cwd`. */
+	readonly exec?: GateExec
+	/** See {@link DEFAULT_GATE_OUTPUT_CHARS}. */
+	readonly maxOutputChars?: number
+	/**
+	 * Override the change detector. Defaults to
+	 * {@link fingerprintWorkspace} over `cwd`.
+	 *
+	 * Returning `null` means "cannot tell", and the gate then runs its
+	 * commands. A detector that returned a constant would silence the gate
+	 * after its first failure, so this seam exists for tests and for a host
+	 * whose workspace is not a git tree — not as a way to turn the check off.
+	 */
+	readonly fingerprint?: () => Promise<string | null>
+}
+
+/** Head and tail of a command's output, with the middle marked as dropped. */
+export function clipOutput(text: string, max: number): string {
+	if (!Number.isSafeInteger(max) || max < 0) {
+		throw new RangeError('maxOutputChars must be a nonnegative safe integer.')
+	}
+	const trimmed = text.trimEnd()
+	if (trimmed.length <= max) return trimmed
+	const markerBudget = `\n… ${trimmed.length} characters omitted …\n`.length
+	if (max < markerBudget) return max === 0 ? '' : '…'
+	const retained = max - markerBudget
+	const head = Math.ceil(retained / 2)
+	const tail = retained - head
+	const marker = `\n… ${trimmed.length - retained} characters omitted …\n`
+	return `${trimmed.slice(0, head)}${marker}${tail > 0 ? trimmed.slice(-tail) : ''}`
+}
+
+interface LastFailure {
+	readonly command: string
+	/** The tree as it stood when this failed. `null` = could not be taken. */
+	readonly fingerprint: string | null
+}
+
+function failureFeedback(
+	command: string,
+	attempt: number,
+	result: CommandResult,
+	maxOutputChars: number,
+): string {
+	const output = clipOutput(`${result.stdout}\n${result.stderr}`, maxOutputChars)
+	const truncatedStreams = [
+		result.stdoutTruncated === true ? 'stdout' : undefined,
+		result.stderrTruncated === true ? 'stderr' : undefined,
+	].filter((stream): stream is string => stream !== undefined)
+	const truncationWarning =
+		truncatedStreams.length === 0
+			? []
+			: [
+					'',
+					`Retained output is incomplete: ${truncatedStreams.join(' and ')} ${truncatedStreams.length === 1 ? 'was' : 'were'} truncated by the execution context. Re-run with a narrower command or filter to recover the missing diagnostics.`,
+				]
+	return [
+		`The answer was not accepted: \`${command}\` failed (attempt ${attempt}, exit ${result.exitCode}${result.termination ? `, terminated: ${result.termination.origin}` : ''}).`,
+		'',
+		'Output:',
+		'```',
+		output || '(no output)',
+		'```',
+		...truncationWarning,
+		'',
+		'Fix the cause and then finish. Do not restate the failure back to me; change the code so the command passes.',
+	].join('\n')
+}
+
+function unchangedFeedback(command: string, attempt: number): string {
+	return [
+		`The answer was not accepted, and \`${command}\` was NOT re-run (attempt ${attempt}).`,
+		'',
+		'The configured change detector reports the same state as after the last failure. The default detector covers the Git commit and Git-visible working state; ignored files and external inputs may have changed.',
+		'',
+		'Check that the intended fix is present and addresses the reported failure. If verification depends on state outside the detector, the host should supply a matching fingerprint or return null to re-run checks.',
+	].join('\n')
+}
+
+function exhaustedFeedback(command: string, maxRetries: number): string {
+	return [
+		`The answer was not accepted: \`${command}\` has failed and this gate has spent its ${maxRetries} attempts.`,
+		'',
+		'No further command will be run.',
+	].join('\n')
+}
+
+/**
+ * Build a reviewer that accepts an answer only when every command passes.
+ *
+ * Stateful across calls within one turn, deliberately: the whole point is that
+ * attempt N+1 can be compared with attempt N. Build one gate per turn.
+ */
+export function createCommandGate(options: CommandGateOptions): ReviewAnswer {
+	const { commands, cwd } = options
+	const timeoutMs = options.timeoutMs ?? DEFAULT_GATE_TIMEOUT_MS
+	const maxRetries = options.maxRetries ?? DEFAULT_GATE_MAX_RETRIES
+	const maxOutputChars = options.maxOutputChars ?? DEFAULT_GATE_OUTPUT_CHARS
+	// Validate before a reviewer is installed: malformed limits cannot turn
+	// a formatting exception during verification into an unreviewed answer.
+	clipOutput('', maxOutputChars)
+
+	// Built once and reused: constructing a context per attempt would re-stat
+	// the directory for no gain, and the context holds nothing per-turn.
+	const context = new LocalExecutionContext({ id: 'namzu-command-gate', cwd })
+	const exec: GateExec =
+		options.exec ?? ((command, args, opts) => context.executeCommand(command, args, opts))
+	const readFingerprint = async (signal?: AbortSignal): Promise<string | null> => {
+		if (signal?.aborted) return null
+		try {
+			return options.fingerprint
+				? await options.fingerprint()
+				: await fingerprintWorkspace({
+						cwd,
+						timeoutMs: 20_000,
+						exec: (command, args, commandOptions) =>
+							exec(command, args, { ...commandOptions, ...(signal ? { signal } : {}) }),
+					})
+		} catch {
+			return null
+		}
+	}
+
+	let attempt = 0
+	let last: LastFailure | undefined
+	let executions = 0
+
+	return async (_answer, reviewContext): Promise<AnswerReview> => {
+		const signal = reviewContext.signal
+		if (signal?.aborted)
+			return { accept: false, feedback: 'Verification was cancelled before admission.' }
+		attempt += 1
+
+		// A gate that already failed, over a tree nothing has touched since.
+		// The command is skipped, and the attempt still counts.
+		//
+		// The comparison is a bare `===` rather than `now !== null && now ===
+		// …`. The guard above already establishes that the recorded
+		// fingerprint is non-null, so a `null` from this call cannot match it,
+		// and the extra clause was a branch nothing could reach — a mutation
+		// that deleted it killed no test, which is what a dead condition looks
+		// like from the outside.
+		if (last && last.fingerprint !== null) {
+			const now = await readFingerprint(signal)
+			if (now === last.fingerprint) {
+				return { accept: false, feedback: unchangedFeedback(last.command, attempt) }
+			}
+		}
+
+		if (last && executions >= maxRetries) {
+			return { accept: false, feedback: exhaustedFeedback(last.command, maxRetries) }
+		}
+
+		executions += 1
+		for (const command of commands) {
+			if (signal?.aborted)
+				return { accept: false, feedback: 'Verification was cancelled before admission.' }
+			// `shell: true` because the operator handed over a command LINE —
+			// `pnpm test -- --run`, with its flags and its quoting — and taking
+			// that as an executable name plus literal arguments would fail on
+			// every gate anyone would actually write. Explicit, per the note on
+			// `LocalExecutionContext.executeCommand`: shell interpretation is
+			// opt-in, and this is the opt-in.
+			let result: CommandResult
+			try {
+				result = await exec(command, [], {
+					cwd,
+					timeoutMs,
+					shell: true,
+					...(signal ? { signal } : {}),
+				})
+			} catch (error) {
+				// A command that could not be observed completing is not a pass.
+				// Keep this inside the builtin reviewer: generic review callbacks
+				// historically fail open on throws. No fabricated exit status.
+				last = { command, fingerprint: null }
+				return {
+					accept: false,
+					feedback: `The answer was not accepted: verification with \`${command}\` could not complete (attempt ${attempt}).\n${clipOutput(error instanceof Error ? error.message : String(error), maxOutputChars)}\nCheck the execution problem and any partial effects before retrying. Do not claim verification passed.`,
+				}
+			}
+			if (signal?.aborted) return { accept: false, feedback: 'Verification was cancelled.' }
+			if (result.exitCode === 0 && result.termination === undefined) continue
+
+			// Taken AFTER the failure, not before the turn: the comparison next
+			// time is against the tree this verdict was formed over. A snapshot
+			// from before the command would miss anything the command itself
+			// wrote — a formatter, a snapshot updater, a lockfile.
+			// Interrupted verification is not a stable failure of these source
+			// bytes. Allow another check even when no tracked file has changed.
+			last = { command, fingerprint: result.termination ? null : await readFingerprint(signal) }
+			return { accept: false, feedback: failureFeedback(command, attempt, result, maxOutputChars) }
+		}
+
+		// Cleared, so a later rejection by a DIFFERENT command is not compared
+		// against a tree this one failed over.
+		last = undefined
+		return { accept: true }
+	}
+}

package/src/turn/drain.ts

@@ -0,0 +1,324 @@
+/**
+ * One pass over a queue of durable turns: list what nobody holds, take it,
+ * hand it to a worker, give it back.
+ *
+ * Every primitive this composes already exists — `SessionIndex` lists the
+ * parked turns (`listPendingDecisions`) and the sessions whose turn is
+ * still open, a session's lease arbitrates between processes, and
+ * `resumeSession` carries the lease's fence into every record. This
+ * composes them, so an approval inbox and a crash sweeper do not each have
+ * to get the release into a `finally` and the `null` claim out of the error
+ * path.
+ *
+ * ## What this deliberately is NOT
+ *
+ * A supervisor, a daemon, or a scheduler. There is no timer here, no
+ * process spawn, no retry backoff and no `while (true)`. `drainParkedTurns` makes
+ * ONE bounded pass and returns what happened; running it again is the
+ * caller's decision, made wherever that caller already has a scheduler. A
+ * per-platform supervisor is the same trade the deployment-adapter matrix
+ * was rejected for: one seam beats N adapters.
+ *
+ * Read the scope of that narrowly. This paragraph has been cited as the
+ * kernel's refusal of a model-facing "remind me tomorrow" capability, and
+ * it is not one: it says a HOST brings the timer, which presumes the host
+ * has one rather than ruling the capability out. Whether such a capability
+ * should exist -- and if so, as a store plus a host-driven sweep rather
+ * than a daemon here -- is open. `directory/types.ts` records the adjacent
+ * decision that cut a declarative `schedules/` slot, on grounds of
+ * double-fire and timezone; that is a different question from a runtime
+ * tool, and neither text settles the other.
+ *
+ * The unit of work is a callback, so this module never needs a provider, a
+ * tool registry or a sandbox — the half of a turn that cannot be serialized
+ * stays with the caller, exactly as `resumeSession` already splits it.
+ */
+
+import { readParks } from '../runtime/query/checkpoint.js'
+import type { SessionIndex } from '../store/session-index/index.js'
+import { DiskSessionLog, type SessionLease, type SessionLog } from '../store/session-log/index.js'
+import type { NamzuErrorCode } from '../types/errors/index.js'
+import { NamzuError } from '../types/errors/index.js'
+import type { CheckpointId, ProjectId, SessionId, TenantId, TurnId } from '../types/ids/index.js'
+import type { DurableTurnEntry, ParkState, ParkSummary } from '../types/session/durable.js'
+
+/** Turns handled per pass when the caller names no page size. */
+export const DEFAULT_DRAIN_PAGE_SIZE = 100
+
+/**
+ * What a drainer does with one turn it successfully took.
+ *
+ * Receives the lease, not just its fence: the holder and expiry are what a
+ * worker needs to decide whether it still has time to start. The intended
+ * body is a resume under that lease:
+ *
+ * ```ts
+ * onTurn: (entry, lease) =>
+ *   resumeSession({ ...yourQueryParams, scope: { ...entry, topicId }, sessionLog, checkpointStore, lease })
+ * ```
+ *
+ * A throw is recorded against that turn and the pass continues.
+ */
+export type DrainTurn = (entry: DurableTurnEntry, lease: SessionLease) => void | Promise<void>
+
+export interface DrainTurnsParams {
+	/** Where the durable turns are listed from. */
+	readonly index: SessionIndex
+	/** Attribution of every entry; the index is per `NAMZU_HOME`, which is per tenant. */
+	readonly tenantId: TenantId
+	/** Narrow to one project. */
+	readonly projectId?: ProjectId
+	/** Narrow to one session. */
+	readonly sessionId?: SessionId
+	/**
+	 * Opens the log of a listed session. Default: the disk log at the path
+	 * the index files it under.
+	 */
+	readonly openLog?: (sessionId: SessionId, logPath: string) => SessionLog
+	/**
+	 * Who is taking the turns. Per-PROCESS, never per-deployment: two drainers
+	 * sharing a string would wait on each other's leases as their own.
+	 */
+	readonly holder: string
+	/** Lease length in ms. Long enough that the slowest turn finishes inside it. */
+	readonly ttlMs: number
+	/** The work. See {@link DrainTurn}. */
+	readonly onTurn: DrainTurn
+	/**
+	 * Keep only turns whose park is in one of these states.
+	 *
+	 * **Absent means every open turn nobody holds, parked or not**: what a
+	 * crash sweep wants, because a turn that died mid-flight never parked. An
+	 * approval inbox passes `['outstanding']`; a reclamation sweep passes
+	 * `['expired']`.
+	 */
+	readonly park?: readonly ParkState[]
+	/** Stop taking new turns. Work already in flight is not interrupted. */
+	readonly signal?: AbortSignal
+	/** How many turns may be in flight at once. Defaults to 1. */
+	readonly maxConcurrent?: number
+	/** Candidates handled per pass. See {@link DEFAULT_DRAIN_PAGE_SIZE}. */
+	readonly pageSize?: number
+	/** Clock for expiry, so one pass judges every lease and park against one instant. */
+	readonly now?: number
+}
+
+/** A turn a pass could not finish, and why. */
+export interface DrainFailure {
+	readonly turnId: TurnId
+	readonly error: string
+}
+
+/** What one pass did. */
+export interface DrainTurnsResult {
+	/** Candidates listed, before any of them were contended for. */
+	readonly listed: number
+	/** Turns whose `onTurn` returned. */
+	readonly drained: readonly TurnId[]
+	/** Turns whose session another worker held. Not failures. */
+	readonly skipped: readonly TurnId[]
+	/**
+	 * Turns that stopped matching between the listing and the claim (another
+	 * drainer finished them, or their park changed state), given straight back.
+	 */
+	readonly stale: readonly TurnId[]
+	/** Turns whose `onTurn` threw. */
+	readonly failed: readonly DrainFailure[]
+	/** Turns that finished but whose lease could not be handed back. */
+	readonly unreleased: readonly DrainFailure[]
+	/** Whether the pass stopped early because the signal aborted. */
+	readonly stopped: boolean
+}
+
+function refuse(code: NamzuErrorCode, message: string, details: Record<string, unknown>): never {
+	throw new NamzuError({ code, message, details })
+}
+
+function toMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err)
+}
+
+interface Candidate {
+	readonly sessionId: SessionId
+	readonly projectId: ProjectId
+	readonly logPath: string
+}
+
+/**
+ * The durable facts of one open turn, from its session log: its checkpoints
+ * (written and not pruned) and its newest park. `undefined` when the turn is
+ * no longer the session's active turn.
+ */
+async function describeTurn(
+	log: SessionLog,
+	tenantId: TenantId,
+	projectId: ProjectId,
+	lease: SessionLease,
+	now: number,
+): Promise<DurableTurnEntry | undefined> {
+	const active = await log.activeTurn({ lease, now })
+	if (!active) return undefined
+	const checkpoints = new Map<string, number>()
+	for await (const { record } of log.read({ mode: 'tolerant' })) {
+		if (record.type === 'checkpoint_written' && record.turnId === active.turnId) {
+			checkpoints.set(record.checkpointId, Date.parse(record.ts))
+		}
+		if (record.type === 'checkpoint_pruned') {
+			for (const id of record.checkpointIds) checkpoints.delete(id)
+		}
+	}
+	const latest = [...checkpoints.entries()].at(-1)
+	if (!latest) return undefined
+	const park = (await readParks(log, { turnId: active.turnId })).at(-1)
+	const summary: ParkSummary | undefined = park
+		? {
+				state:
+					park.pending.resolvedAt !== undefined
+						? 'resolved'
+						: park.pending.deadlineAt !== undefined && now >= park.pending.deadlineAt
+							? 'expired'
+							: 'outstanding',
+				checkpointId: park.checkpointId,
+				requestType: park.pending.request.type,
+				parkedAt: park.pending.parkedAt,
+				...(park.pending.deadlineAt !== undefined ? { deadlineAt: park.pending.deadlineAt } : {}),
+				...(park.pending.resolvedAt !== undefined ? { resolvedAt: park.pending.resolvedAt } : {}),
+			}
+		: undefined
+	return {
+		tenantId,
+		projectId,
+		sessionId: log.sessionId,
+		turnId: active.turnId,
+		turnCreatedAt: Date.parse(active.startedAt),
+		checkpointCount: checkpoints.size,
+		latestCheckpointId: latest[0] as CheckpointId,
+		latestCheckpointAt: latest[1],
+		...(summary ? { park: summary } : {}),
+	}
+}
+
+/**
+ * Take every open turn nobody holds, one bounded pass, and give each one
+ * back when its work returns.
+ *
+ * The shape is: list → claim the session's lease → re-read the turn under
+ * the lease → work → release in a `finally`. Only under the lease is the
+ * re-read stable, and a turn that no longer matches (settled, resumed by
+ * another drainer, or its park answered) is given straight back as
+ * {@link DrainTurnsResult.stale}. An inbox drain whose work answers the park
+ * is therefore exactly-once: doing the work removes the turn from the queue.
+ *
+ * @throws NamzuError `invalid_config` on a lease or concurrency that cannot
+ *   mean what it says.
+ */
+export async function drainParkedTurns(params: DrainTurnsParams): Promise<DrainTurnsResult> {
+	const { index, tenantId, holder, ttlMs, onTurn, park, signal } = params
+
+	if (holder.trim().length === 0) {
+		refuse(
+			'invalid_config',
+			'drainParkedTurns: `holder` is empty. Use something per-process — a worker id, a pod name plus a pid.',
+			{ holder },
+		)
+	}
+	if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+		refuse(
+			'invalid_config',
+			`drainParkedTurns: ttlMs must be a positive number of milliseconds, got ${String(ttlMs)}. A lease that expires immediately is a lease every worker can take at once.`,
+			{ ttlMs },
+		)
+	}
+	const maxConcurrent = params.maxConcurrent ?? 1
+	if (!Number.isInteger(maxConcurrent) || maxConcurrent < 1) {
+		refuse(
+			'invalid_config',
+			`drainParkedTurns: maxConcurrent must be a positive integer, got ${String(params.maxConcurrent)}.`,
+			{ maxConcurrent: params.maxConcurrent },
+		)
+	}
+	const pageSize = params.pageSize ?? DEFAULT_DRAIN_PAGE_SIZE
+	const openLog =
+		params.openLog ??
+		((sessionId: SessionId, logPath: string) =>
+			new DiskSessionLog({ sessionId, file: logPath, sessionDir: logPath.replace(/\.jsonl$/, '') }))
+
+	const drained: TurnId[] = []
+	const skipped: TurnId[] = []
+	const stale: TurnId[] = []
+	const failed: DrainFailure[] = []
+	const unreleased: DrainFailure[] = []
+	let stopped = false
+
+	// Candidates: sessions with an unresolved decision, and — with no park
+	// filter — every session whose turn is still open (running, paused or
+	// interrupted); a running one is held, and its claim below is refused.
+	const sessions = new Map<SessionId, Candidate>()
+	const pending = await index.listPendingDecisions(
+		params.sessionId ? { sessionId: params.sessionId } : {},
+	)
+	const consider = async (sessionId: SessionId): Promise<void> => {
+		if (sessions.has(sessionId)) return
+		const session = await index.getSession(sessionId)
+		if (!session) return
+		if (params.projectId && session.projectId !== params.projectId) return
+		sessions.set(sessionId, { sessionId, projectId: session.projectId, logPath: session.logPath })
+	}
+	for (const decision of pending) await consider(decision.sessionId)
+	if (!park) {
+		for (const session of await index.listSessions()) {
+			if (params.sessionId && session.id !== params.sessionId) continue
+			if (session.status !== 'idle') await consider(session.id)
+		}
+	}
+	const candidates = [...sessions.values()].slice(0, pageSize)
+
+	const handle = async (candidate: Candidate): Promise<void> => {
+		const log = openLog(candidate.sessionId, candidate.logPath)
+		const now = params.now ?? Date.now()
+		const lease = await log.claim({ holder, ttlMs, now })
+		const active = await log.activeTurn()
+		const turnId = active?.turnId ?? ('' as TurnId)
+		if (!lease) {
+			if (active) skipped.push(active.turnId)
+			return
+		}
+		let entry: DurableTurnEntry | undefined
+		try {
+			entry = await describeTurn(log, tenantId, candidate.projectId, lease, now)
+		} catch (err) {
+			failed.push({ turnId, error: toMessage(err) })
+		}
+		const matches =
+			entry !== undefined &&
+			(!park || (entry.park !== undefined && park.includes(entry.park.state)))
+		try {
+			if (!entry || !matches) {
+				if (entry || active) stale.push(entry?.turnId ?? turnId)
+				return
+			}
+			try {
+				await onTurn(entry, lease)
+				drained.push(entry.turnId)
+			} catch (err) {
+				failed.push({ turnId: entry.turnId, error: toMessage(err) })
+			}
+		} finally {
+			try {
+				await log.release(lease)
+			} catch (err) {
+				unreleased.push({ turnId: entry?.turnId ?? turnId, error: toMessage(err) })
+			}
+		}
+	}
+
+	for (let i = 0; i < candidates.length; i += maxConcurrent) {
+		if (signal?.aborted) {
+			stopped = true
+			break
+		}
+		await Promise.all(candidates.slice(i, i + maxConcurrent).map(handle))
+	}
+
+	return { listed: candidates.length, drained, skipped, stale, failed, unreleased, stopped }
+}