@namzu/sdk 38.0.0 → 38.2.1

package/src/manager/resident/delivery-window.ts

@@ -0,0 +1,93 @@
+import type { ResidentDeliveryGate } from './outbox.js'
+
+/** @experimental A daily allowed delivery window in an explicit named time zone. */
+export interface ResidentDeliveryWindowConfig {
+	readonly timeZone: string
+	/** Inclusive local minute of the day, from 0 through 1439. */
+	readonly startMinute: number
+	/** Exclusive local minute of the day; less than startMinute means overnight. */
+	readonly endMinute: number
+}
+
+const minuteMs = 60_000
+const searchMinutes = 72 * 60
+
+/**
+ * @experimental Admit delivery within a daily local-time window, without model
+ * calls. The start is inclusive and the end exclusive; equal boundaries are
+ * rejected. Omit this gate when no time restriction is wanted.
+ *
+ * Future admission searches actual UTC minute boundaries, so nonexistent local
+ * times are skipped and repeated times can open the window twice. The search
+ * is bounded to 72 hours and the Date range; no opening returns nextCheckAt:null.
+ * Historic time zones with second-based offsets may defer up to one extra minute.
+ * This gate does not schedule a timer, authorize a destination or send a message.
+ */
+export function createResidentDeliveryWindow(
+	config: ResidentDeliveryWindowConfig,
+): ResidentDeliveryGate {
+	if (
+		!config ||
+		typeof config.timeZone !== 'string' ||
+		config.timeZone.length === 0 ||
+		config.timeZone !== config.timeZone.trim() ||
+		/^[+-]/.test(config.timeZone) ||
+		!Number.isInteger(config.startMinute) ||
+		config.startMinute < 0 ||
+		config.startMinute > 1439 ||
+		!Number.isInteger(config.endMinute) ||
+		config.endMinute < 0 ||
+		config.endMinute > 1439 ||
+		config.startMinute === config.endMinute
+	) {
+		throw new TypeError('Delivery window requires a named time zone and distinct minutes 0–1439.')
+	}
+
+	let formatter: Intl.DateTimeFormat
+	try {
+		formatter = new Intl.DateTimeFormat('en-US', {
+			timeZone: config.timeZone,
+			hour: '2-digit',
+			minute: '2-digit',
+			hourCycle: 'h23',
+		})
+	} catch {
+		throw new TypeError('Delivery window requires a valid named time zone.')
+	}
+	const { startMinute, endMinute } = config
+	const timeZone = formatter.resolvedOptions().timeZone
+	const allowed = (at: number): boolean => {
+		const parts = formatter.formatToParts(at)
+		const hour = Number(parts.find((part) => part.type === 'hour')?.value)
+		const minute = Number(parts.find((part) => part.type === 'minute')?.value)
+		const localMinute = hour * 60 + minute
+		return startMinute < endMinute
+			? localMinute >= startMinute && localMinute < endMinute
+			: localMinute >= startMinute || localMinute < endMinute
+	}
+
+	return (_message, now) => {
+		if (!Number.isFinite(now) || !Number.isFinite(new Date(now).getTime())) {
+			throw new TypeError('Delivery window requires a finite timestamp within the Date range.')
+		}
+		if (allowed(now)) return { allow: true }
+
+		const firstMinute = (Math.floor(now / minuteMs) + 1) * minuteMs
+		for (let offset = 0; offset < searchMinutes; offset++) {
+			const candidate = firstMinute + offset * minuteMs
+			if (!Number.isFinite(new Date(candidate).getTime())) break
+			if (allowed(candidate)) {
+				return {
+					allow: false,
+					nextCheckAt: candidate,
+					reason: `Outside the allowed daily delivery window in ${timeZone}.`,
+				}
+			}
+		}
+		return {
+			allow: false,
+			nextCheckAt: null,
+			reason: `No allowed delivery minute found within the next 72 hours and Date range in ${timeZone}.`,
+		}
+	}
+}

package/src/manager/resident/host.ts

@@ -0,0 +1,356 @@
+import { setTimeout as sleep } from 'node:timers/promises'
+import type { ResidentAgendaState, ResidentAgendaStore, ResidentPursuit } from './agenda.js'
+import {
+	type ResidentObservation,
+	type ResidentSelection,
+	type ResidentSelector,
+	residentObservationSchema,
+} from './initiative.js'
+import { type ResidentLearningState, freezeResidentLearning } from './learning.js'
+import { type ResidentStep, stepResident } from './loop.js'
+import { type ResidentMessageInput, residentMessageInputSchema } from './outbox.js'
+import { ResidentConflictError, type ResidentDecision, residentDecisionSchema } from './store.js'
+
+/** @experimental Host result describes execution, not external-effect rollback. */
+export interface ResidentHostResult {
+	readonly status: 'idle' | 'paused' | 'unresolved' | 'cancelled' | 'limit' | 'contended'
+	readonly stepsSettled: number
+	readonly nextWakeAt: number | null
+	readonly selection?: ResidentSelection
+}
+
+/** @experimental Explicit authorization to drive a finite number of background steps. */
+export interface ResidentHostRunOptions {
+	readonly signal: AbortSignal
+	readonly maxSteps: number
+	/** Maximum single idle wait; with keepAlive, also bounds local agenda polling. */
+	readonly maxIdleMs?: number
+	/** Keep waiting for useful work within this invocation's finite step cap. Default false. */
+	readonly keepAlive?: boolean
+}
+
+/** @experimental Immutable context from the agenda snapshot that authorized this admission. */
+export interface ResidentStepContext {
+	readonly agendaRevision: number
+	readonly learning?: ResidentLearningState
+}
+
+/** @experimental A developer callback may bind a different SDK run for each pursuit. */
+export type ResidentPursuitStep = (
+	pursuit: ResidentPursuit,
+	signal: AbortSignal,
+) => ReturnType<ResidentStep>
+
+/** @experimental Context-aware callback; existing two-argument steps remain assignable. */
+export type ResidentContextualStep = (
+	pursuit: ResidentPursuit,
+	signal: AbortSignal,
+	context: ResidentStepContext,
+) => ReturnType<ResidentStep>
+
+/** @experimental Inspect actual outcomes and resource receipts independently of model prose. */
+export type ResidentObserver = (
+	pursuit: ResidentPursuit,
+	decision: ResidentDecision,
+	signal: AbortSignal,
+) => Promise<ResidentObservation>
+
+/** @experimental Host validates content and destination; null means no communication. */
+export type ResidentMessageFactory = (
+	pursuit: ResidentPursuit,
+	decision: ResidentDecision,
+	signal: AbortSignal,
+) => Promise<ResidentMessageInput | null>
+
+/** @experimental Opt-in local selection, observed settlement and atomic outbound intent. */
+export interface ResidentHostOptions {
+	readonly select?: ResidentSelector
+	readonly observe?: ResidentObserver
+	readonly prepareMessage?: ResidentMessageFactory
+	/** Bind approved learning to the exact admission snapshot. Default false. */
+	readonly learning?: boolean
+}
+
+/**
+ * @experimental Local driver for one durable agenda. Shared agenda admission
+ * prevents overlapping pursuits across processes. Notifications are local;
+ * opt-in keepAlive also rereads durable state on bounded idle timers.
+ */
+export class ResidentHost {
+	private controller: AbortController | undefined
+	private active: Promise<ResidentHostResult> | undefined
+	private idle: AbortController | undefined
+	private generation = 0
+	private controls: Promise<void> = Promise.resolve()
+	private controlsPending = 0
+	private readonly options: ResidentHostOptions
+
+	constructor(
+		private readonly agenda: ResidentAgendaStore,
+		private readonly step: ResidentContextualStep,
+		options: ResidentHostOptions = {},
+	) {
+		if (options.learning !== undefined && typeof options.learning !== 'boolean')
+			throw new TypeError('Resident learning must be explicitly enabled with a boolean.')
+		if ((options.select || options.learning) && !agenda.executionAt)
+			throw new TypeError('Resident selection or learning requires atomic executionAt support.')
+		if (options.observe && !agenda.settleObserved)
+			throw new TypeError('Resident observation requires atomic settleObserved support.')
+		if (options.prepareMessage && !agenda.settleWithMessage)
+			throw new TypeError('Resident messages require atomic settleWithMessage support.')
+		this.options = Object.freeze({ ...options })
+	}
+
+	/** Interrupt local idle waiting after the host learns of new durable state. */
+	notify(): void {
+		this.generation++
+		this.idle?.abort()
+	}
+
+	private async snapshot(): Promise<ResidentAgendaState> {
+		const state = await this.agenda.read()
+		if (!state) throw new Error('Create the resident agenda before running the host.')
+		return state
+	}
+
+	private async paused(value: boolean): Promise<void> {
+		for (let attempt = 0; attempt < 8; attempt++) {
+			const state = await this.snapshot()
+			if (state.paused === value) return
+			try {
+				await this.agenda.setPaused(state, value)
+				return
+			} catch (error) {
+				if (!(error instanceof ResidentConflictError) || attempt === 7) throw error
+			}
+		}
+	}
+
+	private control(update: () => Promise<void>): Promise<void> {
+		this.controlsPending++
+		const pending = this.controls.then(update)
+		this.controls = pending.catch(() => {})
+		return pending.finally(() => {
+			this.controlsPending--
+		})
+	}
+
+	/**
+	 * Signal current work and durably close future admission. Resolving this method
+	 * is NOT quiescence: await the run promise before claiming the callback stopped.
+	 * An interrupted admitted pursuit remains unresolved until reconciled explicitly.
+	 */
+	async pause(): Promise<void> {
+		this.controller?.abort()
+		this.notify()
+		await this.control(() => this.paused(true))
+	}
+
+	/** Reauthorize future work only after this host's previous invocation drained. */
+	async resume(): Promise<void> {
+		if (this.controlsPending) throw new Error('Wait for pending resident controls before resuming.')
+		if (this.active)
+			throw new Error('Wait for the active resident invocation to drain before resuming.')
+		await this.control(() => this.paused(false))
+		this.notify()
+	}
+
+	/** Persist fresh evidence and interrupt this host's idle timer. */
+	async wake(id: string, reason: string): Promise<void> {
+		const state = await this.snapshot()
+		const pursuit = state.pursuits.find((p) => p.id === id)
+		if (!pursuit) throw new Error('Unknown resident pursuit.')
+		await this.agenda.wake(id, pursuit.state, reason, Date.now())
+		this.notify()
+	}
+
+	run(options: ResidentHostRunOptions): Promise<ResidentHostResult> {
+		if (this.controlsPending) throw new Error('Wait for pending resident controls before running.')
+		if (this.active) throw new Error('A resident host invocation is already active.')
+		const maxIdleMs = options.maxIdleMs ?? 60_000
+		const keepAlive = options.keepAlive ?? false
+		if (options.keepAlive !== undefined && typeof options.keepAlive !== 'boolean')
+			throw new TypeError('Resident keepAlive must be explicitly enabled with a boolean.')
+		if (
+			!Number.isSafeInteger(options.maxSteps) ||
+			options.maxSteps < 1 ||
+			!Number.isSafeInteger(maxIdleMs) ||
+			maxIdleMs < 0 ||
+			maxIdleMs > 2_147_483_647 ||
+			(keepAlive && maxIdleMs === 0)
+		)
+			throw new TypeError('Invalid resident host limits.')
+		const controller = new AbortController()
+		this.controller = controller
+		const signal = AbortSignal.any([controller.signal, options.signal])
+		this.active = this.drive(options.maxSteps, maxIdleMs, keepAlive, signal).finally(() => {
+			this.active = undefined
+			this.controller = undefined
+			this.idle = undefined
+		})
+		return this.active
+	}
+
+	private async drive(
+		maxSteps: number,
+		maxIdleMs: number,
+		keepAlive: boolean,
+		signal: AbortSignal,
+	): Promise<ResidentHostResult> {
+		let stepsSettled = 0
+		try {
+			while (true) {
+				signal.throwIfAborted()
+				const observed = this.generation
+				const state = await this.snapshot()
+				signal.throwIfAborted()
+				if (state.paused) return { status: 'paused', stepsSettled, nextWakeAt: null }
+				if (state.pursuits.some((p) => p.state.phase === 'running'))
+					return { status: 'unresolved', stepsSettled, nextWakeAt: null }
+				const waiting = state.pursuits.filter(
+					(p) => p.state.phase === 'waiting' && p.state.wakeAt !== null,
+				)
+				const now = Date.now()
+				// Fair, deterministic baseline; this is not model-authored initiative.
+				let due = waiting
+					.filter((p) => (p.state.wakeAt ?? 0) <= now)
+					.sort(
+						(a, b) =>
+							a.state.stepsAdmitted - b.state.stepsAdmitted ||
+							(a.state.wakeAt ?? 0) - (b.state.wakeAt ?? 0) ||
+							a.id.localeCompare(b.id),
+					)[0]
+				let selection: ResidentSelection | undefined
+				if (due && this.options.select) {
+					selection = this.options.select(state, now)
+					signal.throwIfAborted()
+					if (selection.agendaRevision !== state.revision)
+						throw new Error('Resident selector returned a stale agenda revision.')
+					if (selection.pursuitId === null) due = undefined
+					else {
+						const selectedId = selection.pursuitId
+						due = waiting.find((p) => p.id === selectedId && (p.state.wakeAt ?? 0) <= now)
+						if (!due) throw new Error('Resident selector chose an ineligible pursuit.')
+					}
+				}
+
+				if (due) {
+					const selected = due
+					const context: ResidentStepContext = Object.freeze({
+						agendaRevision: state.revision,
+						...(this.options.learning && state.learning
+							? { learning: freezeResidentLearning(state.learning) }
+							: {}),
+					})
+					const execution =
+						this.options.select || this.options.learning
+							? this.agenda.executionAt?.(selected.id, state)
+							: this.agenda.execution(selected.id)
+					if (!execution) throw new Error('Resident executionAt support was removed.')
+					const observe = this.options.observe
+					const prepareMessage = this.options.prepareMessage
+					const observedExecution =
+						observe || prepareMessage
+							? {
+									read: () => execution.read(),
+									claim: (...args: Parameters<typeof execution.claim>) => execution.claim(...args),
+									settle: async (
+										current: Parameters<typeof execution.settle>[0],
+										decision: ResidentDecision,
+										at: number,
+									) => {
+										const disposition = Object.freeze(residentDecisionSchema.parse(decision))
+										const observed = await observe?.(
+											{ ...selected, state: current },
+											disposition,
+											signal,
+										)
+										signal.throwIfAborted()
+										const observation = observe
+											? Object.freeze(residentObservationSchema.parse(observed))
+											: undefined
+										const prepared = await prepareMessage?.(
+											{ ...selected, state: current },
+											disposition,
+											signal,
+										)
+										signal.throwIfAborted()
+										const message =
+											prepareMessage && prepared !== null
+												? Object.freeze(residentMessageInputSchema.parse(prepared))
+												: null
+										if (message !== null) {
+											if (!this.agenda.settleWithMessage)
+												throw new Error('Resident settleWithMessage support was removed.')
+											return this.agenda.settleWithMessage(
+												selected.id,
+												current,
+												disposition,
+												message,
+												at,
+												observation,
+											)
+										}
+										if (observation) {
+											if (!this.agenda.settleObserved)
+												throw new Error('Resident settleObserved support was removed.')
+											return this.agenda.settleObserved(
+												selected.id,
+												current,
+												disposition,
+												observation,
+												at,
+											)
+										}
+										return execution.settle(current, disposition, at)
+									},
+								}
+							: execution
+					const result = await stepResident(
+						observedExecution,
+						(current, abort) => this.step({ ...selected, state: current }, abort, context),
+						signal,
+					)
+					if (result.status === 'idle')
+						return {
+							status: result.reason === 'unresolved' ? 'unresolved' : 'contended',
+							stepsSettled,
+							nextWakeAt: null,
+						}
+					stepsSettled++
+					if (stepsSettled >= maxSteps) return { status: 'limit', stepsSettled, nextWakeAt: null }
+					continue
+				}
+				const scheduled =
+					selection?.pursuitId === null
+						? waiting.filter((p) => (p.state.wakeAt ?? 0) > now)
+						: waiting
+				const nextWakeAt =
+					scheduled.length === 0 ? null : Math.min(...scheduled.map((p) => p.state.wakeAt ?? now))
+				if (observed !== this.generation) continue
+				if (!keepAlive && (nextWakeAt === null || nextWakeAt - now > maxIdleMs))
+					return { status: 'idle', stepsSettled, nextWakeAt, ...(selection ? { selection } : {}) }
+				const delay =
+					nextWakeAt === null
+						? maxIdleMs
+						: keepAlive
+							? Math.min(maxIdleMs, nextWakeAt - now)
+							: nextWakeAt - now
+				const idle = new AbortController()
+				this.idle = idle
+				try {
+					await sleep(Math.max(1, delay), undefined, {
+						signal: AbortSignal.any([signal, idle.signal]),
+					})
+				} catch (error) {
+					if (!idle.signal.aborted || signal.aborted) throw error
+				} finally {
+					if (this.idle === idle) this.idle = undefined
+				}
+			}
+		} catch (error) {
+			if (!signal.aborted) throw error
+			return { status: 'cancelled', stepsSettled, nextWakeAt: null }
+		}
+	}
+}

package/src/manager/resident/initiative.ts

@@ -0,0 +1,195 @@
+import { z } from 'zod'
+import type { ResidentAgendaState } from './agenda.js'
+
+const boundedText = z.string().trim().min(1).max(256)
+const cost = z.number().finite().nonnegative()
+export const residentObservationSchema = z.object({
+	evidenceKey: boundedText,
+	source: boundedText,
+	progress: z.number().finite().min(0).max(1),
+	/** All observations and policy costs use the same host-defined resource unit. */
+	costUnits: cost.nullable(),
+})
+
+/** @experimental Host-validated outcome and measured resource use, never model self-confidence. */
+export type ResidentObservation = Readonly<z.infer<typeof residentObservationSchema>>
+
+export const residentFeedbackSchema = z.object({
+	bestProgress: z.number().finite().min(0).max(1),
+	hasUnobservedSteps: z.boolean().default(false),
+	stagnantSteps: z.number().int().nonnegative().safe(),
+	observations: z
+		.array(
+			residentObservationSchema.extend({
+				gain: z.number().finite().min(0).max(1),
+				step: z.number().int().positive().safe(),
+			}),
+		)
+		.min(1)
+		.max(8),
+})
+
+/** @experimental Last eight observations; best progress and stagnation survive eviction. */
+export type ResidentFeedback = Readonly<
+	Omit<z.infer<typeof residentFeedbackSchema>, 'observations'>
+> & {
+	readonly observations: readonly Readonly<
+		z.infer<typeof residentFeedbackSchema>['observations'][number]
+	>[]
+}
+
+export function observeResidentStep(
+	previous: ResidentFeedback | undefined,
+	input: ResidentObservation,
+	step: number,
+): ResidentFeedback {
+	const observation = residentObservationSchema.parse(input)
+	const best = previous?.bestProgress ?? 0
+	const duplicate = previous?.observations.some(
+		(item) => item.evidenceKey === observation.evidenceKey,
+	)
+	// Rewording evidence, regression and recovery to an old best earn no credit.
+	const gain = duplicate ? 0 : Math.max(0, observation.progress - best)
+	return freezeResidentFeedback(
+		residentFeedbackSchema.parse({
+			bestProgress: best + gain,
+			hasUnobservedSteps:
+				(previous?.hasUnobservedSteps ?? false) ||
+				step !== (previous?.observations.at(-1)?.step ?? 0) + 1,
+			stagnantSteps: gain > 0 ? 0 : (previous?.stagnantSteps ?? 0) + 1,
+			observations: [...(previous?.observations ?? []), { ...observation, gain, step }].slice(-8),
+		}),
+	)
+}
+
+export function freezeResidentFeedback(value: ResidentFeedback): ResidentFeedback {
+	return Object.freeze({
+		...value,
+		observations: Object.freeze(value.observations.map((item) => Object.freeze({ ...item }))),
+	})
+}
+
+/** @experimental Policy units are chosen by the host; scores are heuristics, not probabilities. */
+export interface ResidentSelectionConfig {
+	readonly progressValue: number
+	readonly initialExpectedProgress: number
+	readonly initialExpectedCost: number
+	readonly maxStagnantSteps?: number
+}
+
+/** @experimental Explainable inputs for a single selection; unknown cost is not zero. */
+export interface ResidentCandidate {
+	readonly pursuitId: string
+	readonly reason:
+		| 'eligible'
+		| 'not-due'
+		| 'missing-observation'
+		| 'stalled'
+		| 'unknown-cost'
+		| 'nonpositive-value'
+	readonly expectedGain: number | null
+	readonly expectedCost: number | null
+	readonly score: number | null
+}
+
+/** @experimental Choice is bound to the whole agenda revision used to compute it. */
+export interface ResidentSelection {
+	readonly agendaRevision: number
+	readonly pursuitId: string | null
+	readonly reason: 'selected' | 'paused' | 'unresolved' | 'no-useful-work'
+	readonly candidates: readonly ResidentCandidate[]
+}
+
+/** @experimental Pure local selection; perform inference inside budgeted steps, not here. */
+export type ResidentSelector = (agenda: ResidentAgendaState, now: number) => ResidentSelection
+
+/**
+ * @experimental Cost-aware continuation with an explicit abstention choice.
+ * This is a measured-progress heuristic, not Bayesian value of computation.
+ * A finite bootstrap allowance permits delayed payoffs but may stop too early.
+ */
+export function createResidentSelector(config: ResidentSelectionConfig): ResidentSelector {
+	const policy = z
+		.object({
+			progressValue: z.number().finite().positive(),
+			initialExpectedProgress: z.number().finite().positive().max(1),
+			initialExpectedCost: cost,
+			maxStagnantSteps: z.number().int().min(1).max(32).default(2),
+		})
+		.parse(config)
+	return (agenda, now) => {
+		z.number().int().nonnegative().safe().parse(now)
+		const finish = (
+			pursuitId: string | null,
+			reason: ResidentSelection['reason'],
+			candidates: ResidentCandidate[],
+		): ResidentSelection =>
+			Object.freeze({
+				agendaRevision: agenda.revision,
+				pursuitId,
+				reason,
+				candidates: Object.freeze(candidates.map((candidate) => Object.freeze(candidate))),
+			})
+		if (agenda.paused) return finish(null, 'paused', [])
+		if (agenda.pursuits.some((p) => p.state.phase === 'running'))
+			return finish(null, 'unresolved', [])
+		const candidates = agenda.pursuits.map((p): ResidentCandidate => {
+			const reject = (reason: ResidentCandidate['reason']): ResidentCandidate => ({
+				pursuitId: p.id,
+				reason,
+				expectedGain: null,
+				expectedCost: null,
+				score: null,
+			})
+			if (p.state.phase !== 'waiting' || p.state.wakeAt === null || p.state.wakeAt > now)
+				return reject('not-due')
+			if (
+				p.state.stepsAdmitted > 0 &&
+				(!p.feedback ||
+					p.feedback.hasUnobservedSteps ||
+					p.feedback.observations.at(-1)?.step !== p.state.stepsAdmitted)
+			)
+				return reject('missing-observation')
+			const feedback = p.feedback
+			if (feedback && feedback.stagnantSteps >= policy.maxStagnantSteps) return reject('stalled')
+			if (feedback?.observations.some((item) => item.costUnits === null))
+				return reject('unknown-cost')
+			const recent = feedback?.observations ?? []
+			const totalGain = recent.reduce((total, item) => total + item.gain, 0)
+			const bootstrap = p.state.stepsAdmitted < policy.maxStagnantSteps && totalGain === 0
+			const expectedGain =
+				recent.length === 0 || bootstrap
+					? policy.initialExpectedProgress
+					: (totalGain + policy.initialExpectedProgress) / (recent.length + 1)
+			const expectedCost =
+				recent.length === 0
+					? policy.initialExpectedCost
+					: recent.reduce((total, item) => total + (item.costUnits ?? 0), 0) / recent.length
+			const score = policy.progressValue * expectedGain - expectedCost
+			return {
+				pursuitId: p.id,
+				reason: score > 0 ? 'eligible' : 'nonpositive-value',
+				expectedGain,
+				expectedCost,
+				score,
+			}
+		})
+		const eligible = candidates.filter((candidate) => candidate.reason === 'eligible')
+		eligible.sort((a, b) => {
+			const left = agenda.pursuits.find((p) => p.id === a.pursuitId)
+			const right = agenda.pursuits.find((p) => p.id === b.pursuitId)
+			if (!left || !right) throw new Error('Resident candidate is missing.')
+			return (
+				(b.score ?? 0) - (a.score ?? 0) ||
+				left.state.stepsAdmitted - right.state.stepsAdmitted ||
+				(left.state.wakeAt ?? 0) - (right.state.wakeAt ?? 0) ||
+				a.pursuitId.localeCompare(b.pursuitId)
+			)
+		})
+		return finish(
+			eligible[0]?.pursuitId ?? null,
+			eligible.length ? 'selected' : 'no-useful-work',
+			candidates,
+		)
+	}
+}