@atolis-hq/wake 0.1.12 → 0.1.14

package/dist/src/core/event-builders.js

@@ -0,0 +1,139 @@
+import { createEventEnvelope } from '../lib/event-log.js';
+import { extractTokenCount, formatCostUsd, formatDuration, formatTokenCount, } from '../lib/format.js';
+function isReviewThreadResourceUri(resourceUri) {
+    return resourceUri.split(':')[1] === 'pr-review-thread';
+}
+// `latestComment` is a sticky, per-work-item field: projection-updater.ts's
+// comment fold overwrites it unconditionally on every inbound comment
+// (any surface) and nothing ever resets it. So it means "the last comment
+// this work item has ever received," not "the comment that triggered the
+// currently completing run." Several needsWakeAction trigger paths (first
+// run, quota-failure retry, first workflow-stage pass) complete a run
+// with no fresh comment driving it at all — in those cases latestComment
+// may still be pointing at an older, already-handled comment from a
+// different surface (e.g. a PR) and must not be trusted as this run's
+// trigger. This mirrors policy-engine.ts's needsWakeAction "is there an
+// unhandled human comment" check exactly, so a comment is only treated as
+// having driven this run when it's human-authored and not yet the
+// candidate's own lastHandledCommentId (read from the pre-completion
+// projection passed in as `candidate`/`projection`, since the completion
+// event that would update lastHandledCommentId for *this* run hasn't been
+// folded yet at the point this runs).
+function isFreshTriggeringComment(candidate) {
+    const context = candidate.context;
+    const handledCommentId = typeof context.lastHandledCommentId === 'string' ? context.lastHandledCommentId : undefined;
+    return (candidate.latestComment !== undefined &&
+        !candidate.latestComment.isBotAuthored &&
+        candidate.latestComment.id !== handledCommentId);
+}
+export function createPublishIntentEvent(input) {
+    const tokenCount = extractTokenCount(input.runnerResult.tokenUsage);
+    const duration = formatDuration(input.startedAt, input.occurredAt);
+    return createEventEnvelope({
+        eventId: `${input.runId}-publish-intent`,
+        workItemKey: input.projection.workItemKey,
+        streamScope: 'work-item',
+        direction: 'outbound',
+        sourceSystem: 'wake',
+        sourceEventType: 'wake.publish.intent.requested',
+        sourceRefs: {
+            repo: input.projection.issue.repo,
+            issueNumber: input.projection.issue.number,
+            runId: input.runId,
+            // Carries the triggering comment's surface (set only when the human
+            // reply that woke this run came from a correlated PR/review-thread
+            // resource, per the ad1cf45 comment fold) through to the sink
+            // router, so createOutboundSinkRouter's kind-based routing (Task 11,
+            // sink-router.ts) can send the reply back to that surface instead of
+            // defaulting to the issue thread. Without this, every reply landed
+            // on the origin sink regardless of which surface triggered the run.
+            //
+            // Gated on isFreshTriggeringComment: latestComment is sticky (see
+            // that function's comment) and several run-completion paths (first
+            // run, quota retry, first workflow-stage pass) have no fresh
+            // comment behind them at all — for those, threading the stale
+            // latestComment.resourceUri would misroute the reply to whatever
+            // surface last happened to comment, even long after that comment
+            // was already replied to.
+            //
+            // Never threads a pr-review-thread surface specifically: this is
+            // Wake's own status, approval-request, or question card: a milestone
+            // message, not a targeted reply to one inline comment — burying it
+            // as a reply deep in a single review thread makes it easy to miss.
+            // Omitting resourceUri here falls back to sourceOrigin in
+            // sink-router.ts, landing it on the correlated issue (or, for a
+            // standalone PR-only work item, GitHub's shared issue/PR comments
+            // endpoint posts it as a top-level PR comment instead). Replies to
+            // individual review threads are the agent's own job now — see
+            // prompts/revise.md — via `gh api .../replies`, not this card.
+            ...(input.projection.latestComment?.resourceUri === undefined ||
+                !isFreshTriggeringComment(input.projection) ||
+                isReviewThreadResourceUri(input.projection.latestComment.resourceUri)
+                ? {}
+                : { resourceUri: input.projection.latestComment.resourceUri }),
+        },
+        occurredAt: input.occurredAt,
+        ingestedAt: input.occurredAt,
+        trigger: 'context-only',
+        payload: {
+            kind: input.sentinel === 'BLOCKED'
+                ? 'question'
+                : input.sentinel === 'AWAITING_APPROVAL'
+                    ? 'approval-request'
+                    : input.sentinel === 'FAILED'
+                        ? 'failure'
+                        : 'status-update',
+            origin: input.projection.origin ?? 'github',
+            body: input.parsedRunnerResult.body,
+            action: input.action,
+            sentinel: input.sentinel,
+            runId: input.runId,
+            ...(input.runnerResult.session_id === undefined
+                ? {}
+                : { sessionId: input.runnerResult.session_id }),
+            model: input.runnerResult.model,
+            cli: input.runnerResult.cli,
+            ...(input.runnerResult.routing === undefined
+                ? {}
+                : {
+                    runnerName: input.runnerResult.routing.runnerName,
+                    runnerKind: input.runnerResult.routing.runnerKind,
+                    runnerTier: input.runnerResult.routing.tier,
+                    runnerReason: input.runnerResult.routing.reason,
+                }),
+            ...(duration === undefined ? {} : { duration }),
+            ...(tokenCount === undefined ? {} : { tokens: formatTokenCount(tokenCount) }),
+            ...(input.runnerResult.tokenUsage?.costUsd === undefined
+                ? {}
+                : { cost: formatCostUsd(input.runnerResult.tokenUsage.costUsd) }),
+            ...(input.workspacePath === undefined ? {} : { workspacePath: input.workspacePath }),
+        },
+        derivedHints: {
+            stage: input.sentinel === 'DONE' ? 'done' : input.projection.wake.stage,
+        },
+    });
+}
+export function createLabelsEvent(input) {
+    return createEventEnvelope({
+        eventId: `${input.runId}-labels-${input.statusLabel.replace(/[^a-z0-9]+/gi, '-')}-${input.stageLabel.replace(/[^a-z0-9]+/gi, '-')}-${input.workflowLabel.replace(/[^a-z0-9]+/gi, '-')}`,
+        workItemKey: input.projection.workItemKey,
+        streamScope: 'work-item',
+        direction: 'outbound',
+        sourceSystem: 'wake',
+        sourceEventType: 'wake.labels.requested',
+        sourceRefs: {
+            repo: input.projection.issue.repo,
+            issueNumber: input.projection.issue.number,
+            runId: input.runId,
+        },
+        occurredAt: input.occurredAt,
+        ingestedAt: input.occurredAt,
+        trigger: 'context-only',
+        payload: {
+            statusLabel: input.statusLabel,
+            stageLabel: input.stageLabel,
+            workflowLabel: input.workflowLabel,
+            origin: input.projection.origin ?? 'github',
+        },
+    });
+}

package/dist/src/core/event-resolver.js

@@ -0,0 +1,249 @@
+import { createWorkId } from '../lib/work-id.js';
+import { CORRELATION_REGISTERED_EVENT, UNRESOLVED_WORK_ITEM_KEY, WORK_ITEM_CREATED_EVENT, } from '../domain/schema.js';
+import { createEventEnvelope } from '../lib/event-log.js';
+// How an unkeyed source event becomes a work item — the correlation-resolution
+// subsystem described in docs/adrs/0001-correlating-external-resources-to-work-items.md.
+export function createEventResolver(deps) {
+    // Events are stamped by reading the clock at the moment of stamping, never
+    // from a frozen tick-start snapshot. `tickStartedAt` is the tick's *decision*
+    // clock (policy/staleness), and reusing it to date events inverts them
+    // against the work source's own poll-time ingestedAt — pollEvents() runs
+    // after tickStartedAt is captured, so in production every polled upsert is
+    // LATER than the tick's start. An event dated before the upsert that creates
+    // the projection it folds into sorts ahead of it in rebuildFromEvents' global
+    // replay, folds against `current === null`, and is silently dropped. Reading
+    // per event also stays correct once ticks work items in parallel, where a
+    // shared per-tick snapshot would tie every concurrent event on ingestedAt and
+    // leave append order as the only discriminator.
+    function eventStampNow() {
+        return deps.clock.now().toISOString();
+    }
+    // Returns whichever of the two timestamps is unambiguously later, defaulting
+    // to `left`. `right` wins only if it is later by BOTH the actual instant and
+    // the lexicographic order rebuildFromEvents sorts on — the envelope schema is
+    // `z.string().datetime({ offset: true })`, so a timestamp may legally carry a
+    // non-UTC offset or differing sub-second precision, and lexicographic order
+    // alone is not a reliable proxy for chronology across those formats. Falling
+    // back to `left` (the source event's own exact string) is always safe: it
+    // ties with that event under localeCompare, and the stable sort then preserves
+    // append order, which puts the mint events after it — exactly what we need.
+    function laterTimestamp(left, right) {
+        const isLater = Date.parse(right) > Date.parse(left) && right.localeCompare(left) > 0;
+        return isLater ? right : left;
+    }
+    // The two internal events a mint (or a heal) appends after the source event
+    // that founded a work item: wake.workitem.created, then the
+    // wake.correlation.registered that claims the originating resource as this
+    // work item's primary representation. Their ids are derived from the work id,
+    // so re-emitting them is idempotent — appendEventEnvelope dedups on the id.
+    //
+    // Ordering and timestamps matter, and not only for readability. Both fold
+    // against the projection the source event creates, and applyEvent drops
+    // anything that folds while `current === null`. So they must never sort
+    // *before* that source event in rebuildFromEvents' globally-ordered replay —
+    // if they did, replay would silently discard the registration, leaving
+    // correlatedResources[] empty and the index unpopulated, while the events
+    // still on record stop any later tick from re-registering. Permanent,
+    // self-concealing loss (Task 5, round 3). Reading the clock here is already
+    // after pollEvents(), but that alone is not a guarantee: the source event's
+    // ingestedAt comes from the *source's* clock, which for a real source is
+    // another machine's and can legitimately run ahead of ours. Anchoring on the
+    // source event's own timestamp makes the ordering hold by construction rather
+    // than by clock agreement; appending the source event first means a tie
+    // resolves in its favour (the sort is stable, so equal timestamps keep append
+    // order).
+    function buildOriginCorrelationEvents(workItemKey, unkeyed, resourceUri) {
+        const mintedAt = laterTimestamp(unkeyed.ingestedAt, eventStampNow());
+        const sourceRefs = {
+            ...unkeyed.sourceRefs,
+            resourceUri,
+        };
+        const createdEvent = createEventEnvelope({
+            eventId: `${workItemKey}-created`,
+            workItemKey,
+            streamScope: 'work-item',
+            direction: 'internal',
+            sourceSystem: 'wake',
+            sourceEventType: WORK_ITEM_CREATED_EVENT,
+            sourceRefs,
+            occurredAt: mintedAt,
+            ingestedAt: mintedAt,
+            trigger: 'context-only',
+            // The envelope's workItemKey already carries the identity.
+            payload: {},
+        });
+        const registeredEvent = createEventEnvelope({
+            eventId: `${workItemKey}-origin-correlation`,
+            workItemKey,
+            streamScope: 'work-item',
+            direction: 'internal',
+            sourceSystem: 'wake',
+            sourceEventType: CORRELATION_REGISTERED_EVENT,
+            sourceRefs,
+            occurredAt: mintedAt,
+            ingestedAt: mintedAt,
+            trigger: 'context-only',
+            payload: {
+                resourceUri,
+                role: 'representation',
+                relation: 'primary',
+                provenance: 'wake-created',
+            },
+        });
+        return [createdEvent, registeredEvent];
+    }
+    // The central resolver (spec D1): sources name the *resource* an event came
+    // from and never the work item, so between pollEvents() and the append every
+    // inbound event's sourceRefs.resourceUri is resolved through the reverse
+    // index to the canonical workItemKey, minting a work item on a miss. This is
+    // the one mechanism — there is no founding-surface special case, and no
+    // resolution is ever cached in process memory between ticks (CLAUDE.md: the
+    // tick is a pure function of durable state; the index on disk *is* that
+    // state).
+    //
+    // Each resolved event carries whether it is already `persisted`, so the
+    // caller can skip re-appending it (appendEventEnvelope would only re-read it
+    // and hand back the same envelope). Minting *is* registration, so a freshly
+    // minted work item's correlatedResources[] is complete from its first event.
+    async function resolveInboundEvent(unkeyed) {
+        const { resourceUri } = unkeyed.sourceRefs;
+        if (resourceUri === undefined) {
+            // A programming error in the adapter, not a runtime condition to absorb.
+            // Guessing an identity here would silently fork a duplicate work item
+            // for work already in flight — exactly the corruption the reverse index
+            // exists to prevent — so fail loudly instead.
+            throw new Error(`cannot resolve inbound event ${unkeyed.eventId} from ${unkeyed.sourceSystem}: ` +
+                'sourceRefs.resourceUri is required for every unkeyed source event');
+        }
+        // An event we have already persisted was already resolved, on some earlier
+        // tick, and its stamped key is the durable answer. Re-resolving it through
+        // the index would be wrong as well as wasteful: if that work item has since
+        // retracted this resource, the index no longer holds it, the lookup misses,
+        // and a miss means mint — so a re-polled event (sources legitimately
+        // re-emit the same eventId, e.g. an unchanged issue) would fork a duplicate
+        // work item. Reusing the persisted key keeps resolution idempotent per
+        // event id, which is what the append-only log already promises.
+        const persisted = await deps.stateStore.readEventEnvelope(unkeyed.eventId);
+        if (persisted !== null) {
+            // Heal a partially minted work item. The index entry for a resource is
+            // written only when its origin wake.correlation.registered event is
+            // *folded*, several appends after the founding source event. A crash in
+            // that window leaves the source event durable — so this branch suppresses
+            // re-minting — while the index has no entry, and a later event on the
+            // same resource would miss the index and fork a duplicate work item
+            // (crash/restart safety, CLAUDE.md). If the index does not credit this
+            // event's work item *and* its origin correlation never landed, re-emit
+            // the mint tail (idempotent by id). The guard is the missing origin
+            // event, not merely an empty index: a deliberately *retracted* resource
+            // also resolves to undefined but keeps its origin-correlation event on
+            // record, and must not be silently re-registered.
+            const owner = await deps.resourceIndex.resolve(resourceUri);
+            if (persisted.workItemKey !== UNRESOLVED_WORK_ITEM_KEY &&
+                owner === undefined &&
+                (await deps.stateStore.readEventEnvelope(`${persisted.workItemKey}-origin-correlation`)) ===
+                    null) {
+                return [
+                    { envelope: persisted, persisted: true },
+                    ...buildOriginCorrelationEvents(persisted.workItemKey, unkeyed, resourceUri).map((envelope) => ({ envelope, persisted: false })),
+                ];
+            }
+            return [{ envelope: persisted, persisted: true }];
+        }
+        const existingWorkItemKey = await deps.resourceIndex.resolve(resourceUri);
+        if (existingWorkItemKey !== undefined) {
+            return [
+                {
+                    envelope: createEventEnvelope({ ...unkeyed, workItemKey: existingWorkItemKey }),
+                    persisted: false,
+                },
+            ];
+        }
+        // resourceUri itself misses the index (e.g. a review-thread comment's
+        // resourceUri is unique per thread, never registered on its own), but the
+        // adapter may have named a parent resource this one belongs to. Resolve
+        // through that instead of minting — and register this exact resourceUri
+        // as a secondary correlation so it's on record on the work item, even
+        // though (being secondary) it still won't shortcut future lookups via the
+        // index itself (ADR 0001 §5: the index is primary-only).
+        if (unkeyed.sourceRefs.parentResourceUri !== undefined) {
+            const parentWorkItemKey = await deps.resourceIndex.resolve(unkeyed.sourceRefs.parentResourceUri);
+            if (parentWorkItemKey !== undefined) {
+                const mintedAt = laterTimestamp(unkeyed.ingestedAt, eventStampNow());
+                return [
+                    {
+                        envelope: createEventEnvelope({ ...unkeyed, workItemKey: parentWorkItemKey }),
+                        persisted: false,
+                    },
+                    {
+                        envelope: createEventEnvelope({
+                            eventId: `${parentWorkItemKey}-correlation-${resourceUri.replace(/[^a-z0-9]+/gi, '-')}`,
+                            workItemKey: parentWorkItemKey,
+                            streamScope: 'work-item',
+                            direction: 'internal',
+                            sourceSystem: 'wake',
+                            sourceEventType: CORRELATION_REGISTERED_EVENT,
+                            sourceRefs: unkeyed.sourceRefs,
+                            occurredAt: mintedAt,
+                            ingestedAt: mintedAt,
+                            trigger: 'context-only',
+                            payload: {
+                                resourceUri,
+                                role: 'review',
+                                relation: 'secondary',
+                                provenance: 'detected',
+                            },
+                        }),
+                        persisted: false,
+                    },
+                ];
+            }
+        }
+        if (!deps.qualifiesForMint(unkeyed, deps.config)) {
+            return [
+                {
+                    envelope: createEventEnvelope({ ...unkeyed, workItemKey: UNRESOLVED_WORK_ITEM_KEY }),
+                    persisted: false,
+                },
+            ];
+        }
+        const workItemKey = createWorkId();
+        const keyed = createEventEnvelope({ ...unkeyed, workItemKey });
+        return [
+            { envelope: keyed, persisted: false },
+            ...buildOriginCorrelationEvents(workItemKey, unkeyed, resourceUri).map((envelope) => ({
+                envelope,
+                persisted: false,
+            })),
+        ];
+    }
+    async function ingestInboundEvents(unkeyedEvents) {
+        const ingested = [];
+        for (const unkeyed of unkeyedEvents) {
+            const resolved = await resolveInboundEvent(unkeyed);
+            // Fold what was actually persisted, never the in-memory copy:
+            // appendEventEnvelope is id-deduplicated and returns the *existing*
+            // envelope when one is already on record. Folding our own copy instead
+            // would let state/ diverge from events/ — and replay is defined by
+            // events/, so the divergence would only surface after a rebuild. An event
+            // already flagged `persisted` needs no second append: appendEventEnvelope
+            // would only re-read it off disk and hand back the same envelope, and
+            // every unchanged issue is re-polled every tick, so that read is the
+            // dominant redundant cost this branch avoids.
+            const events = [];
+            for (const { envelope, persisted } of resolved) {
+                events.push(persisted ? envelope : await deps.stateStore.appendEventEnvelope(envelope));
+            }
+            // Folded before the next event is resolved, because it is the fold of
+            // the registration event that writes the index entry the *next* event on
+            // the same resource resolves through. Deferring the fold to the end of
+            // the batch would let a second event for the same ticket miss and mint a
+            // duplicate work item. Every event in a poll batch shares the source's
+            // one ingestedAt, so folding per event preserves exactly the order a
+            // single batched fold would have produced.
+            await deps.projectionUpdater.rebuildFromEvents(events);
+            ingested.push(...events);
+        }
+        return ingested;
+    }
+    return { ingestInboundEvents };
+}

package/dist/src/core/outbox.js

@@ -0,0 +1,123 @@
+import { randomUUID } from 'node:crypto';
+import { createEventEnvelope } from '../lib/event-log.js';
+const outboxMaxAttempts = 3;
+const outboundIntentEventTypes = new Set([
+    'wake.publish.intent.requested',
+    'wake.labels.requested',
+]);
+const outboundConfirmationEventTypes = new Set([
+    'ticket.reply.published',
+    'ticket.labels.updated',
+    'wake.publish.confirmed',
+    'pr.comment.reply.published',
+    'pr.review-comment.reply.published',
+]);
+// The outbox: outbound delivery (comments, labels) attempted independently of
+// run-outcome recording, with a durable, bounded retry trace. Extracted from
+// tick-runner.ts so it can be exercised in isolation; it has the cleanest
+// boundary of the tick's collaborators — no dependency on candidate selection.
+export function createOutbox(deps) {
+    async function recordDeliveryFailure(intentEvent, err) {
+        const occurredAt = deps.clock.now().toISOString();
+        const failureEvent = createEventEnvelope({
+            eventId: `${intentEvent.eventId}-delivery-failed-${randomUUID()}`,
+            workItemKey: intentEvent.workItemKey,
+            streamScope: 'work-item',
+            direction: 'internal',
+            sourceSystem: 'wake',
+            sourceEventType: 'wake.publish.failed',
+            sourceRefs: intentEvent.sourceRefs,
+            occurredAt,
+            ingestedAt: occurredAt,
+            trigger: 'context-only',
+            payload: {
+                intentEventId: intentEvent.eventId,
+                intentEventType: intentEvent.sourceEventType,
+                error: err instanceof Error ? err.message : String(err),
+            },
+        });
+        await deps.stateStore.appendEventEnvelope(failureEvent);
+        await deps.projectionUpdater.rebuildFromEvents([failureEvent]);
+    }
+    // Outbound delivery (comments, labels) is attempted independently of run-outcome
+    // recording: a delivery failure must never rewrite an already-recorded run result
+    // (S1), and must always leave a durable, retryable trace instead of being lost
+    // (E5). This never throws — failures become a `wake.publish.failed` event.
+    async function attemptDelivery(event) {
+        if (deps.outboundSink === undefined) {
+            return;
+        }
+        try {
+            const deliveryEvents = await deps.outboundSink.deliverIntent({ event });
+            for (const deliveryEvent of deliveryEvents) {
+                await deps.stateStore.appendEventEnvelope(deliveryEvent);
+            }
+            await deps.projectionUpdater.rebuildFromEvents(deliveryEvents);
+            if (deliveryEvents.length === 0) {
+                // No confirmation event was produced (e.g. a no-op label update) but the
+                // sink did not throw. Record that delivery was attempted successfully so
+                // the outbox scan below does not retry it indefinitely.
+                const confirmedAt = deps.clock.now().toISOString();
+                const confirmedEvent = createEventEnvelope({
+                    eventId: `${event.eventId}-confirmed`,
+                    workItemKey: event.workItemKey,
+                    streamScope: 'work-item',
+                    direction: 'internal',
+                    sourceSystem: 'wake',
+                    sourceEventType: 'wake.publish.confirmed',
+                    sourceRefs: event.sourceRefs,
+                    occurredAt: confirmedAt,
+                    ingestedAt: confirmedAt,
+                    trigger: 'context-only',
+                    payload: { intentEventId: event.eventId },
+                });
+                await deps.stateStore.appendEventEnvelope(confirmedEvent);
+            }
+        }
+        catch (err) {
+            await recordDeliveryFailure(event, err);
+        }
+    }
+    async function deliverOutboundEvent(event) {
+        await deps.stateStore.appendEventEnvelope(event);
+        await deps.projectionUpdater.rebuildFromEvents([event]);
+        await attemptDelivery(event);
+    }
+    // Adopts the outbox pattern: an intent is only considered delivered once a
+    // matching confirmation event exists. Anything left unconfirmed by a prior tick
+    // (e.g. the process crashed mid-delivery) is retried here, bounded so a
+    // permanently failing sink dead-letters instead of retrying forever.
+    async function retryUnconfirmedDeliveries() {
+        if (deps.outboundSink === undefined) {
+            return;
+        }
+        const events = await deps.stateStore.listEventEnvelopes();
+        const confirmedIntentIds = new Set();
+        const failureAttempts = new Map();
+        for (const event of events) {
+            const intentEventId = event.payload.intentEventId;
+            if (typeof intentEventId !== 'string') {
+                continue;
+            }
+            if (outboundConfirmationEventTypes.has(event.sourceEventType)) {
+                confirmedIntentIds.add(intentEventId);
+            }
+            if (event.sourceEventType === 'wake.publish.failed') {
+                failureAttempts.set(intentEventId, (failureAttempts.get(intentEventId) ?? 0) + 1);
+            }
+        }
+        for (const intent of events) {
+            if (!outboundIntentEventTypes.has(intent.sourceEventType)) {
+                continue;
+            }
+            if (confirmedIntentIds.has(intent.eventId)) {
+                continue;
+            }
+            if ((failureAttempts.get(intent.eventId) ?? 0) >= outboxMaxAttempts) {
+                continue;
+            }
+            await attemptDelivery(intent);
+        }
+    }
+    return { attemptDelivery, deliverOutboundEvent, retryUnconfirmedDeliveries };
+}

package/dist/src/core/policy-engine.js

@@ -1,6 +1,6 @@
 import { awaitingApprovalRunnerSentinel, failedRunnerSentinel } from '../domain/stages.js';
 import { resolveCustomCommand } from '../domain/custom-commands.js';
-import { builtInDefaultWorkflowDefinition, chooseAction as chooseWorkflowAction, selectWorkflowForEvent, } from '../domain/workflows.js';
+import { builtInDefaultWorkflowDefinition, chooseAction as chooseWorkflowAction, isKnownWorkflowStage, selectWorkflowForEvent, workflowForProjection, } from '../domain/workflows.js';
 function isAwaitingApproval(issue) {
     const context = issue.context;
     return context.lastRunSentinel === awaitingApprovalRunnerSentinel;
@@ -186,6 +186,44 @@ export function createPolicyEngine() {
         resolveCustomCommandRequest(issue, config) {
             return resolveCustomCommand(issue, config);
         },
+        // The single eligibility predicate: is this issue open, on a known workflow
+        // stage, and does it have a next action Wake should run? Returns the
+        // resolved action plus the workflow it belongs to, or null when there is
+        // nothing to do. This used to be duplicated as two independently-drifting
+        // copies (the pending-label marker and the runner's candidate `find`), which
+        // is exactly the class of "a rule change didn't propagate everywhere" that
+        // caused the #258 incident — keep it as the one source of truth.
+        resolveNextEligibleAction(issue, config) {
+            if (!this.isEligible(issue, config)) {
+                return null;
+            }
+            const workflow = workflowForProjection(issue, config);
+            if (workflow === null || !isKnownWorkflowStage(issue.wake.stage, workflow)) {
+                return null;
+            }
+            if (isAwaitingApproval(issue)) {
+                const customCommand = resolveCustomCommand(issue, config);
+                if (customCommand !== null) {
+                    return { action: customCommand.action, workflow };
+                }
+                const approval = this.resolveApprovalTransition(issue);
+                if (approval !== null) {
+                    return { action: approval.pendingAction, workflow };
+                }
+                const reviewAction = this.resolvePendingReviewFeedback(issue);
+                if (reviewAction !== null) {
+                    return { action: reviewAction, workflow };
+                }
+                return null;
+            }
+            const nextAction = resolveCustomCommand(issue, config)?.action ??
+                this.chooseAction(issue, workflow) ??
+                this.chooseRetryActionAfterHumanReply(issue, workflow);
+            if (nextAction === null || !this.needsWakeAction(issue, workflow)) {
+                return null;
+            }
+            return { action: nextAction, workflow };
+        },
         qualifiesForMint(unresolved, config) {
             const resourceUri = unresolved.sourceRefs.resourceUri;
             if (resourceUri === undefined) {

package/dist/src/core/stale-run-reconciler.js

@@ -0,0 +1,102 @@
+import { createLabelsEvent } from './event-builders.js';
+import { stageLabelForStage } from '../domain/stages.js';
+import { workflowLabelForWorkflowName, workflowNameForProjection } from '../domain/workflows.js';
+import { createEventEnvelope } from '../lib/event-log.js';
+// Reconciles run records still marked `running` past the runner timeout: a
+// record whose work item has already moved on is superseded, otherwise it is
+// failed and a completion event replayed so the projection stops waiting on it.
+// `deliverOutboundEvent` is injected rather than imported so this module does
+// not depend on the outbox module directly.
+export function createStaleRunReconciler(deps) {
+    function isStaleRunningRecord(record, now) {
+        if (record.status !== 'running') {
+            return false;
+        }
+        const startedAtMs = Date.parse(record.startedAt);
+        if (!Number.isFinite(startedAtMs)) {
+            return true;
+        }
+        return now.getTime() - startedAtMs >= deps.runnerTimeoutMs();
+    }
+    async function reconcileStaleRunningRecords(now) {
+        const finishedAt = now.toISOString();
+        const runRecords = await deps.stateStore.listRunRecords();
+        const staleRecords = runRecords.filter((record) => isStaleRunningRecord(record, now));
+        for (const record of staleRecords) {
+            // Run records carry the work item they belong to, so this is a direct
+            // O(1) read — no scan, no index, no source ambiguity. The record's
+            // repo/issueNumber are representation content and take no part in it.
+            const projection = await deps.stateStore.readIssueState(record.workItemKey);
+            const newerCompletedRun = runRecords.some((candidate) => candidate.workItemKey === record.workItemKey &&
+                candidate.runId !== record.runId &&
+                candidate.status !== 'running' &&
+                Date.parse(candidate.startedAt) > Date.parse(record.startedAt));
+            // Equivalent to the previous `projection?.wake.lastRunId !== record.runId`,
+            // spelled out so the non-null projection is available below for its
+            // workItemKey.
+            if (projection === null || projection.wake.lastRunId !== record.runId || newerCompletedRun) {
+                await deps.stateStore.writeRunRecord({
+                    ...record,
+                    status: 'superseded',
+                    finishedAt,
+                    summary: 'Stale running record was superseded by a newer run.',
+                    metadata: {
+                        ...record.metadata,
+                        reconciledBy: 'stale-running-record',
+                        supersededBy: projection?.wake.lastRunId,
+                    },
+                });
+                continue;
+            }
+            await deps.stateStore.writeRunRecord({
+                ...record,
+                status: 'failed',
+                finishedAt,
+                sentinel: 'FAILED',
+                summary: `Run exceeded timeout while marked running and was reconciled by a later tick.`,
+                metadata: {
+                    ...record.metadata,
+                    reconciledBy: 'stale-running-record',
+                    timeoutMs: deps.runnerTimeoutMs(),
+                },
+            });
+            const runCompletedEvent = createEventEnvelope({
+                eventId: `${record.runId}-stale-reconciled`,
+                workItemKey: projection.workItemKey,
+                streamScope: 'work-item',
+                direction: 'internal',
+                sourceSystem: 'wake',
+                sourceEventType: 'wake.run.completed',
+                sourceRefs: {
+                    repo: record.repo,
+                    issueNumber: record.issueNumber,
+                    runId: record.runId,
+                },
+                occurredAt: finishedAt,
+                ingestedAt: finishedAt,
+                trigger: 'immediate',
+                payload: {
+                    action: record.action,
+                    sentinel: 'FAILED',
+                    runId: record.runId,
+                    reason: 'runner:stale-timeout',
+                    ...(record.routing === undefined ? {} : { routing: record.routing }),
+                },
+            });
+            await deps.stateStore.appendEventEnvelope(runCompletedEvent);
+            await deps.projectionUpdater.rebuildFromEvents([runCompletedEvent]);
+            const updatedProjection = await deps.stateStore.readIssueState(projection.workItemKey);
+            if (updatedProjection !== null) {
+                await deps.deliverOutboundEvent(createLabelsEvent({
+                    projection: updatedProjection,
+                    runId: record.runId,
+                    statusLabel: 'wake:status.failed',
+                    stageLabel: stageLabelForStage(updatedProjection.wake.stage),
+                    workflowLabel: workflowLabelForWorkflowName(workflowNameForProjection(updatedProjection, deps.config)),
+                    occurredAt: finishedAt,
+                }));
+            }
+        }
+    }
+    return { reconcileStaleRunningRecords };
+}