smol-symphony 0.2.0 → 0.3.0

package/dist/src/shell/orchestrator-image.js

@@ -0,0 +1,167 @@
+// FCIS rewrite — the one-time OCI→gondolin image-build tracker (kind: shell helper, issue 206).
+//
+// Sliced out of the orchestrator loop (which sits at its max-lines budget) so the
+// loop stays a thin rind. Owns the transient image-build state the poll gate + the
+// dashboard banner read: the in-flight build, the last failed digest/ref (which
+// suppresses an auto-retry storm), and a memoised read-only probe. The loop fires
+// `ensure()` on the reducer's `ensure_image` effect and folds `readiness()` onto each
+// snapshot; core decides whether to HOLD dispatch off that readiness.
+//
+// Readiness is DIGEST-based, not ref-string-based (issue 206 review rework): every
+// `readiness()` re-runs the injected read-only `probeImage` to resolve the ref's
+// CURRENT local digest + look up its cached selector. So a moving tag (`repo:latest`)
+// whose underlying image changed reports not-ready until the new digest is
+// reconverted — the tracker never reports "ready" off a ref string that succeeded
+// once. The probe never pulls/builds (the build itself is the injected `ensureImage`).
+//
+// Shell rule: imports from src/types ONLY (no IO module — the conversion + probe are
+// the injected `deps.ensureImage` / `deps.probeImage`, wired to the converter adapter).
+export class ImageBuildTracker {
+    deps;
+    building = null;
+    // The last failed build, keyed by the resolved digest when known (else null = the
+    // pull/resolve itself failed, keyed by ref). Suppresses an auto-retry storm for THAT
+    // digest only — a moving tag that resolves to a NEW digest is retried (issue 206).
+    failure = null;
+    // The most recent read-only probe, refreshed by `readiness()`. `resolvedSelector`
+    // reads it so the selector dispatch boots agrees with the gate decision this tick.
+    lastProbe = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Project the live build state into the readiness the poll reducer gates on. Each
+     * call re-probes the ref's CURRENT digest + cached selector (cheap, read-only, no
+     * pull) so readiness tracks the live digest, not a ref string that converted once:
+     *
+     *   - oci_image unset → auto-convert path inactive.
+     *   - a build in flight → hold (don't probe mid-write); `building`.
+     *   - a cached asset resolves for the current digest → `ready` (dispatch may boot it).
+     *   - no cached asset → not ready; `failed` when THIS digest's last build failed
+     *     (suppresses re-emit until the operator fixes the ref / the tag moves).
+     */
+    readiness(ref) {
+        const ociConfigured = ref !== null && ref.length > 0;
+        if (!ociConfigured) {
+            this.lastProbe = null;
+            // oci_image cleared/unset ⇒ the auto-convert path is off; drop any stale failure
+            // so the dashboard stops surfacing a banner for a ref no longer in play.
+            this.failure = null;
+            return { ociConfigured: false, ref: null, ready: false, building: this.building !== null, failed: false };
+        }
+        if (this.building !== null) {
+            // A build is in flight (the store is mid-write): hold without probing. The
+            // freshly-converted asset shows as ready on the NEXT tick once `ensure` clears.
+            return { ociConfigured: true, ref, ready: false, building: true, failed: false };
+        }
+        const probe = this.probe(ref);
+        this.lastProbe = probe;
+        const ready = probe.selector !== null;
+        const failed = !ready && this.matchesFailure(ref, probe.digest);
+        // A recorded failure that no longer gates THIS digest is superseded — the tag
+        // moved to a fresh digest (`failed` false, gate re-emits `ensure_image`) or the
+        // asset is now cached (`ready`). Drop it so the dashboard banner clears and the
+        // failure-suppression doesn't outlive the digest it was recorded for (issue 206).
+        if (this.failure !== null && !failed)
+            this.failure = null;
+        return { ociConfigured: true, ref, ready, building: false, failed };
+    }
+    /**
+     * The runtime image selector the converted asset boots with for the ref's CURRENT
+     * digest, or null when it isn't cached (not configured, not yet converted, or the
+     * tag moved to a digest that hasn't been reconverted). Dispatch threads this into
+     * `buildVmPlan` so a workflow that sets only `gondolin.oci_image` boots the cached
+     * asset instead of an empty `imagePath` (issue 206). Reads the readiness memo when
+     * it matches `ref` so it agrees with the same-tick gate decision; else re-probes.
+     */
+    resolvedSelector(ref) {
+        if (ref === null || ref.length === 0)
+            return null;
+        if (this.lastProbe !== null && this.lastProbe.ref === ref)
+            return this.lastProbe.selector;
+        return this.probe(ref).selector;
+    }
+    /** The in-flight build for the dashboard banner, or null. */
+    state() {
+        return this.building;
+    }
+    /**
+     * The last FAILED conversion for the dashboard banner, or null (issue 206 review).
+     * Surfaced ONLY while it still gates dispatch — the build threw, but the reconcile
+     * gate keeps holding VM dispatch and suppresses an auto-retry for this digest, so
+     * the operator needs a visible "why is nothing dispatching" answer. Returns null
+     * while a (re)build is in flight (the in-flight {@link state} banner wins) and once
+     * `readiness()` drops a superseded failure (tag moved / asset cached) or a
+     * successful `ensure()` clears it.
+     */
+    failureState() {
+        if (this.building !== null)
+            return null;
+        if (this.failure === null)
+            return null;
+        return { ref: this.failure.ref, since: this.failure.since, message: this.failure.message };
+    }
+    /** Drop the in-flight build state (shutdown). */
+    reset() {
+        this.building = null;
+    }
+    /**
+     * Run the one-time conversion off the tick. Idempotent against re-emits: a no-op
+     * while a build is already in flight (the readiness gate keeps a cached digest from
+     * re-emitting). On success clears any prior failure — the next tick's probe finds
+     * the freshly-tagged asset and reports ready; on failure records the error keyed by
+     * the resolved digest (so the gate stops re-emitting for THAT digest) and logs the
+     * remediation. The converter itself is idempotent (a cached digest is a cheap hit).
+     */
+    async ensure(ref) {
+        if (!this.deps.ensureImage)
+            return;
+        if (this.building !== null)
+            return;
+        this.building = { ref, since: this.deps.clock.iso() };
+        try {
+            await this.deps.ensureImage(ref);
+            this.failure = null;
+        }
+        catch (err) {
+            const message = err.message;
+            this.failure = { ref, digest: this.probe(ref).digest, message, since: this.deps.clock.iso() };
+            void this.deps.interpreter
+                .execute({
+                family: 'log',
+                kind: 'emit',
+                level: 'error',
+                message: 'one-time microVM image conversion failed; VM dispatch held',
+                fields: { oci_image: ref, error: message },
+            })
+                .catch(() => undefined);
+        }
+        finally {
+            this.building = null;
+        }
+    }
+    /** Read-only digest+cache probe via the injected adapter; null-safe (no probe wired,
+     *  or the resolve threw ⇒ unresolvable, which the gate treats as not-ready). */
+    probe(ref) {
+        if (!this.deps.probeImage)
+            return { ref, digest: null, selector: null };
+        try {
+            const p = this.deps.probeImage(ref);
+            return { ref, digest: p.digest, selector: p.selector };
+        }
+        catch {
+            return { ref, digest: null, selector: null };
+        }
+    }
+    /** Whether the current (ref, digest) matches the recorded failure — suppressing an
+     *  auto-retry storm for that exact digest (or the un-resolvable ref when pull failed). */
+    matchesFailure(ref, digest) {
+        const f = this.failure;
+        if (f === null)
+            return false;
+        if (f.digest !== null)
+            return digest === f.digest;
+        return f.ref === ref && digest === null;
+    }
+}
+//# sourceMappingURL=orchestrator-image.js.map

package/dist/src/shell/orchestrator-image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-image.js","sourceRoot":"","sources":["../../../src/shell/orchestrator-image.ts"],"names":[],"mappings":"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"}

package/dist/src/shell/orchestrator-loop.js

@@ -0,0 +1,468 @@
+// FCIS rewrite — the orchestrator poll-and-dispatch LOOP DRIVER (imperative shell).
+//
+// REF (read-only): src/orchestrator.ts — `tick()` / `dispatchSorted()` /
+// `onWorkerExit()` / `onRetryTimer()` / `scheduleRetry()` / `maybeArmSleepCycle()`
+// / `terminateRunning()` / `reportRuntimeEvent()` / `reportTurnStarted()`.
+//
+// This file owns the SHELL's mutable runtime state that core never touches:
+//   • `running`         — live RunningEntry map (carries the `cancel` closure +
+//                         the `active_tool_calls` Set — the two live handles core
+//                         must not hold).
+//   • `claimed`         — issue ids claimed for dispatch / pending retry.
+//   • `retryAttempts`   — live retry-timer handles (TimerPort owns the actual fire).
+//   • circuit-breaker streaks + the sleep-cycle counter + the clamp flag.
+//
+// Each tick it MATERIALISES a plain-data snapshot from those live maps, calls the
+// injected PURE reducer (`core/schedule/tick` — wired in by the composition root,
+// since the shell may not import core), then APPLIES the returned next-state
+// deltas to its live maps and DRAINS the returned Effect[] through the single
+// EffectInterpreter. It also drives the imperative bits the reducer leaves to the
+// shell: spawning the worker per DispatchPlan, and the success-gated sleep-cycle
+// counter reset around the recurring-reflection mint.
+//
+// Async + IO live here. All scheduling DECISIONS live in core; this driver only
+// moves data between the live maps, the reducer, and the interpreter. Imports
+// from src/types ONLY (the reducer's shape is injected, kept structurally typed).
+import { applyRuntimeEvent, applyTurnStarted, applyTokenUsage, detectStalledIssues } from './orchestrator-feedback.js';
+import { reconcileRunningEntries } from './orchestrator-reconcile.js';
+import { ImageBuildTracker } from './orchestrator-image.js';
+// The stable poll-timer id + the sleep-cycle spawn actor are the CORE constants
+// (`core/schedule/tick.ts:POLL_TIMER_ID` / `SPAWN_CYCLE_ACTOR`), injected on
+// `deps` so the loop's `setTimer`/`effect.id ===`/`effect.actor ===` checks match
+// the ids/actors core stamps on its emitted Effects — no hardcoded twin (§4b).
+const RETRY_TIMER_PREFIX = 'retry:';
+/**
+ * The imperative shell of the poll-and-dispatch tick. Holds the live maps + cancel
+ * closures + active_tool_calls Sets; folds runtime events through the injected pure
+ * reducer; drives the returned Effects through the interpreter.
+ */
+export class OrchestratorLoop {
+    deps;
+    running = new Map();
+    claimed = new Set();
+    retryAttempts = new Map();
+    circuitBreakers = new Map();
+    doneSinceReflect = 0;
+    // Sleep-cycle mints in flight: a `write_issue` create the loop has STARTED but
+    // whose disk write hasn't settled yet. Surfaced on the snapshot so the reducer's
+    // `max_in_flight` guard counts an emitted-but-not-yet-landed mint (the on-disk
+    // candidate scan + running set can't see it) — without it a worker exit + poll
+    // racing between emit and landing could mint a SECOND reflection.
+    pendingSpawnMints = 0;
+    clampActive = false;
+    stopped = false;
+    lastPollAt = null;
+    // One-time OCI→gondolin image conversion state (issue 206) lives in a companion so
+    // the loop stays under its max-lines budget; the loop only fires + projects it.
+    imageTracker;
+    constructor(deps) {
+        this.deps = deps;
+        this.imageTracker = new ImageBuildTracker(deps);
+    }
+    /** Live read for the IntendedVmProvider / dashboard snapshot (shell-owned state). */
+    runningEntries() {
+        return [...this.running.values()];
+    }
+    retryEntries() {
+        return [...this.retryAttempts.values()];
+    }
+    claimedIds() {
+        return this.claimed;
+    }
+    lastPollAtIso() { return this.lastPollAt; }
+    /** Kick the first poll (REF: `start()` → `scheduleTick(0)`). */
+    start() {
+        this.deps.timers.setTimer(this.deps.pollTimerId, 0, () => void this.poll());
+    }
+    /** Tear down: cancel running, clear retry timers, drop claims (REF: `stop()`). */
+    stop() {
+        this.stopped = true;
+        this.deps.timers.clearTimer(this.deps.pollTimerId);
+        for (const e of this.retryAttempts.values()) {
+            this.deps.timers.clearTimer(RETRY_TIMER_PREFIX + e.issue_id);
+        }
+        this.retryAttempts.clear();
+        for (const e of this.running.values())
+            e.cancel();
+        this.running.clear();
+        this.claimed.clear();
+        this.circuitBreakers.clear();
+        this.imageTracker.reset();
+    }
+    /** The single operator-event write door (REF: the `triggerRefresh` side-door, now an event): build the snapshot, fold via the reducer, apply deltas + drain its Effect[] — same public pattern as {@link onWorkerExit}. An `operator_nudge` re-arms the poll at 0ms, coalescing an immediate poll exactly as `triggerRefresh` did. */
+    dispatch(event) {
+        if (this.stopped)
+            return;
+        this.applyResult(this.deps.tick(event, this.buildSnapshot()));
+    }
+    /** Build the plain-data snapshot the reducer folds over (no live handles leak). */
+    buildSnapshot() {
+        const cfg = this.deps.readConfig();
+        return {
+            cfg,
+            running: [...this.running.values()].map((e) => ({
+                issue_id: e.issue_id,
+                state: e.issue.state,
+            })),
+            claimed: this.claimed,
+            retries: [...this.retryAttempts.values()].map((r) => ({
+                issue_id: r.issue_id,
+                kind: r.kind,
+                target_state: r.target_state,
+            })),
+            circuitBreakers: this.circuitBreakers,
+            doneSinceReflect: this.doneSinceReflect,
+            pendingSpawnMints: this.pendingSpawnMints,
+            previousClampActive: this.clampActive,
+            memoryProbe: { memAvailableMib: this.deps.memProbe.read() },
+            now: this.deps.clock.now(),
+            nowIso: this.deps.clock.iso(),
+            // oci_image OR the managed prebuilt-image ref (issue 224) — same tracker path.
+            image: this.imageTracker.readiness(cfg.ociImage ?? cfg.managedImageRef ?? null),
+        };
+    }
+    /** Live reads for the dashboard's one-time-build banners (shell-owned state): the
+     *  in-flight build, and the FAILED build that keeps dispatch held (issue 206). */
+    imageBuildState() { return this.imageTracker.state(); }
+    imageFailureState() { return this.imageTracker.failureState(); }
+    /**
+     * The runtime image selector the asset auto-converted from `gondolin.oci_image`
+     * boots with (issue 206), or null when inactive / not yet ready. The runner threads
+     * it into `buildVmPlan` so a workflow that sets only `oci_image` boots the cached
+     * asset; core lets the `gondolin.image` escape hatch win when it is also set.
+     */
+    // oci_image OR the managed prebuilt-image ref (issue 224); same resolved-selector path.
+    effectiveImageSelector() { const c = this.deps.readConfig(); return this.imageTracker.resolvedSelector(c.ociImage ?? c.managedImageRef ?? null); }
+    // ── poll tick (REF: tick()) ────────────────────────────────────────────────
+    async poll() {
+        if (this.stopped)
+            return;
+        // Stall reconcile runs every poll BEFORE dispatch (REF: reconcile()) so a
+        // wedged running entry frees its slot before fresh candidates are admitted.
+        this.reconcileStalls();
+        // Cancel-on-move safety net (issue 211): reconcile every LIVE running entry against
+        // its FRESH tracker state, so a disk `mv`/external move out of an active state
+        // cancels the in-flight attempt even when no dashboard move-event fired (the shared
+        // decider keeps it from drifting from the operator-move path). Runs before dispatch
+        // so a terminated entry frees its slot this same poll.
+        await reconcileRunningEntries(this.running, this.deps, (id, cleanup) => this.terminateRunning(id, cleanup));
+        const fetched = await this.deps.fetchCandidates();
+        if (!fetched) {
+            // Tracker miss — reschedule the backstop poll and bail (REF: fetch error path).
+            this.deps.timers.setTimer(this.deps.pollTimerId, this.deps.readConfig().pollIntervalMs, () => void this.poll());
+            return;
+        }
+        const result = this.deps.tick({ kind: 'poll', candidates: fetched.issues, trackerRoot: fetched.root }, this.buildSnapshot());
+        this.applyResult(result);
+    }
+    /**
+     * Worker exit (REF: onWorkerExit). Removing the exited entry from `running` is
+     * part of applying the exit: drop it FIRST (so the snapshot the reducer folds
+     * over — and thus its slot accounting — excludes it), then fold the exit through
+     * core for the breaker + retry/continuation decision. The caller hands us the
+     * exit event and nothing else; it no longer pre-pulls the entry via a separate
+     * `removeRunning` poke.
+     */
+    onWorkerExit(event) {
+        this.running.delete(event.issueId);
+        if (this.stopped) {
+            // stop() raced the unwind: drop the claim, do not arm a new retry (REF guard).
+            this.claimed.delete(event.issueId);
+            this.circuitBreakers.delete(event.issueId);
+            return;
+        }
+        this.applyResult(this.deps.tick(event, this.buildSnapshot()));
+    }
+    /** Retry timer firing (REF: onRetryTimer) — re-poll, re-check, redispatch/release. */
+    async onRetryTimer(issueId) {
+        if (this.stopped)
+            return;
+        const entry = this.retryAttempts.get(issueId);
+        if (!entry)
+            return;
+        this.retryAttempts.delete(issueId);
+        const fetched = await this.deps.fetchCandidates();
+        if (!fetched) {
+            // Re-poll failed — reschedule a failure backoff for THIS issue (REF: fetchRetryCandidates).
+            // The delay comes from the INJECTED core `backoffDelayMs` (pinned at the core
+            // FAILURE_BASE_MS) so this poll-failure backoff can't diverge from the normal-
+            // failure backoff core schedules for the same attempt (§4a). The attempt being
+            // scheduled is `entry.attempt + 1`.
+            const cfg = this.deps.readConfig();
+            const delayMs = this.deps.backoff(entry.attempt + 1, cfg.maxRetryBackoffMs);
+            this.scheduleRetry({
+                issueId,
+                identifier: entry.identifier,
+                plan: {
+                    attempt: entry.attempt + 1,
+                    delayMs,
+                    error: 'retry poll failed',
+                    kind: 'failure',
+                    target_state: entry.target_state,
+                },
+            });
+            return;
+        }
+        this.applyResult(this.deps.tick({
+            kind: 'retry_timer',
+            issueId,
+            identifier: entry.identifier,
+            attempt: entry.attempt,
+            targetState: entry.target_state,
+            candidates: fetched.issues,
+            trackerRoot: fetched.root,
+        }, this.buildSnapshot()));
+    }
+    // ── apply the reducer's next-state deltas + drain its effects ───────────────
+    applyResult(result) {
+        // Snapshot the counter BEFORE the optimistic reset below, so the guarded mint
+        // can restore it if the create fails (the reset delta is applied at step 1).
+        const priorDoneSinceReflect = this.doneSinceReflect;
+        // 1. Persisted scalar deltas (REF: the orchestrator's instance-field writes).
+        if (result.lastPollAt !== undefined)
+            this.lastPollAt = result.lastPollAt;
+        if (result.clampActive !== undefined)
+            this.clampActive = result.clampActive;
+        if (result.doneSinceReflect !== undefined)
+            this.doneSinceReflect = result.doneSinceReflect;
+        if (result.breaker) {
+            if (result.breaker.op === 'set') {
+                this.circuitBreakers.set(result.breaker.issueId, result.breaker.state);
+            }
+            else {
+                this.circuitBreakers.delete(result.breaker.issueId);
+            }
+        }
+        // 2. Claims first so a dispatched issue is claimed before its worker spawns.
+        for (const id of result.claim)
+            this.claimed.add(id);
+        for (const id of result.release)
+            this.releaseClaim(id);
+        // 3. Spawn the workers for each dispatch plan (REF: dispatchIssue → runWorker).
+        for (const plan of result.dispatch)
+            this.dispatchPlan(plan);
+        // 4. Drain the side effects through the single interpreter seam.
+        for (const effect of result.effects)
+            this.executeEffect(effect, priorDoneSinceReflect);
+    }
+    /**
+     * Execute one effect. Timer/schedule_retry effects are wired to the live timer
+     * port HERE (they carry the loop's own callbacks); everything else goes straight
+     * to the central interpreter (REF: scheduleTick / scheduleRetry use the live
+     * setTimeout, all other IO routes through the adapters).
+     */
+    executeEffect(effect, priorDoneSinceReflect) {
+        // Timer/schedule_retry effects carry the loop's own callbacks — handled in a
+        // sibling method so this dispatcher stays under the shell complexity budget.
+        if (effect.family === 'timer') {
+            this.executeTimerEffect(effect);
+            return;
+        }
+        // worker.cancel is the ONE effect the loop interprets itself: the reducer
+        // decided to cancel a live attempt (operator move — issue 199) but core holds
+        // no live handles, so it emitted the decision and we perform it here via our
+        // OWN terminateRunning — the same path the stall reaper drives. cleanupWorkspace
+        // carries the reducer's terminal-vs-active cleanup decision.
+        if (effect.family === 'worker' && effect.kind === 'cancel') {
+            this.terminateRunning(effect.issueId, effect.cleanupWorkspace);
+            return;
+        }
+        // image.ensure is the other effect the loop interprets itself (issue 206): the
+        // reducer decided to convert + cache `gondolin.oci_image`, but the in-flight
+        // build state + the tracked async are shell-owned (core holds no live handles).
+        // The tracker runs the converter off the tick so the poll loop never blocks; the
+        // next poll's snapshot reads the updated readiness.
+        if (effect.family === 'image' && effect.kind === 'ensure')
+            return void this.imageTracker.ensure(effect.ref);
+        // tracker.write_issue from the sleep-cycle spawn needs the success-gated counter
+        // reset: core optimistically reset the counter to 0 this tick, so restore the
+        // prior value if the mint fails. Route it through the guarded mint path instead
+        // of firing it blind.
+        if (effect.family === 'tracker' &&
+            effect.kind === 'write_issue' &&
+            effect.actor === this.deps.spawnActor) {
+            void this.spawnReflection(effect, priorDoneSinceReflect);
+            return;
+        }
+        // Everything else: fire-and-forget through the central interpreter. Failures are
+        // surfaced via the interpreter's own EffectResult; the loop does not re-decide on
+        // log/runlog/move effects here (REF: those were best-effort side calls).
+        void this.deps.interpreter.execute(effect).catch(() => undefined);
+    }
+    /**
+     * Interpret a timer-family effect: the named timer's `fire` callback is the loop's
+     * OWN (the poll re-arm runs `poll()`, schedule_retry arms the retry timer), so the
+     * loop wires them here rather than routing through the central interpreter (REF:
+     * scheduleTick / scheduleRetry used the live setTimeout).
+     */
+    executeTimerEffect(effect) {
+        switch (effect.kind) {
+            case 'set_timer':
+                if (effect.id === this.deps.pollTimerId) {
+                    this.deps.timers.setTimer(this.deps.pollTimerId, effect.ms, () => void this.poll());
+                }
+                else {
+                    this.deps.timers.setTimer(effect.id, effect.ms, () => undefined);
+                }
+                return;
+            case 'clear_timer':
+                this.deps.timers.clearTimer(effect.id);
+                return;
+            case 'schedule_retry':
+                this.scheduleRetry({ issueId: effect.issueId, identifier: effect.identifier, plan: effect.plan });
+                return;
+            case 'sleep':
+                // No loop-driver sleep effects today; route to the interpreter for completeness.
+                return void this.deps.interpreter.execute(effect);
+        }
+    }
+    /**
+     * Mint the recurring reflection issue under the success-gated counter reset.
+     * Core already emitted the create effect + optimistically reset the counter to 0
+     * this tick (so a poll that fires the create can't re-fire it before the write
+     * lands). If the mint fails we RESTORE the counter to its PRE-reset value
+     * (`priorDoneSinceReflect`, captured before applyResult applied the reset) so a
+     * failed spawn doesn't silently discard the accumulated terminal count.
+     *
+     * The in-flight guard the immortal-ticket latch used to provide now lives in
+     * core's `max_in_flight` check — but that check counts issues VISIBLE in the
+     * on-disk candidate scan + the running set, and a write that's been emitted but
+     * not yet landed is in neither. So we bump `pendingSpawnMints` for the lifetime of
+     * the async write (it rides onto the next snapshot's in-flight count) and drop it
+     * once the write settles: a worker exit + poll racing between emit and landing then
+     * still sees the mint and can't slip a second one past `max_in_flight`.
+     */
+    async spawnReflection(createEffect, priorDoneSinceReflect) {
+        // Make the in-flight mint visible to the reducer's max_in_flight guard the moment
+        // the create is started (this runs synchronously within applyResult, before the
+        // next poll can build a snapshot), and drop it once the write settles.
+        this.pendingSpawnMints++;
+        try {
+            const r = await this.deps.interpreter.execute(createEffect);
+            if ('ok' in r && r.ok === false) {
+                // Mint declined — undo the optimistic reset core applied this tick.
+                this.doneSinceReflect = priorDoneSinceReflect;
+            }
+        }
+        catch {
+            this.doneSinceReflect = priorDoneSinceReflect;
+        }
+        finally {
+            this.pendingSpawnMints--;
+        }
+    }
+    // ── dispatch one plan: claim + build entry + spawn the worker ───────────────
+    dispatchPlan(plan) {
+        if (this.running.has(plan.issue.id))
+            return;
+        this.claimed.add(plan.issue.id);
+        // Replace any pending retry (its timer is cleared) — this dispatch supersedes it.
+        const existingRetry = this.retryAttempts.get(plan.issue.id);
+        if (existingRetry) {
+            this.deps.timers.clearTimer(RETRY_TIMER_PREFIX + plan.issue.id);
+            this.retryAttempts.delete(plan.issue.id);
+        }
+        const cancel = { cancelled: false };
+        const entry = this.deps.buildEntry(plan, () => {
+            cancel.cancelled = true;
+        });
+        this.running.set(plan.issue.id, entry);
+        void this.deps
+            .runWorker(plan, entry, cancel)
+            .catch(() => undefined)
+            .finally(() => {
+            // The worker fully unwound; the composition root is responsible for calling
+            // back into onWorkerExit with the attempt outcome. onWorkerExit removes the
+            // entry itself (so the reducer's slot accounting excludes it). Nothing to do
+            // in the happy path here — this .finally only backstops a thrown runWorker so
+            // a stuck claim can't leak if the caller forgot to report the exit.
+            if (this.running.get(plan.issue.id) === entry)
+                this.running.delete(plan.issue.id);
+        });
+    }
+    /**
+     * Arm a retry/continuation timer (REF: scheduleRetry). Clears any prior timer for
+     * the issue, records the live RetryEntry, claims the issue (so the eligibility gate
+     * still blocks a fresh dispatch during the backoff), and fires onRetryTimer.
+     */
+    scheduleRetry(input) {
+        if (this.stopped)
+            return;
+        const existing = this.retryAttempts.get(input.issueId);
+        if (existing)
+            this.deps.timers.clearTimer(RETRY_TIMER_PREFIX + input.issueId);
+        const dueAt = this.deps.clock.now() + input.plan.delayMs;
+        this.retryAttempts.set(input.issueId, {
+            issue_id: input.issueId,
+            identifier: input.identifier,
+            attempt: input.plan.attempt,
+            due_at_ms: dueAt,
+            timer_handle: null,
+            error: input.plan.error,
+            kind: input.plan.kind,
+            target_state: input.plan.target_state,
+        });
+        this.claimed.add(input.issueId);
+        this.deps.timers.setTimer(RETRY_TIMER_PREFIX + input.issueId, input.plan.delayMs, () => void this.onRetryTimer(input.issueId));
+    }
+    /** Release a claim + drop the breaker streak (REF: releaseRetryClaim / claimed.delete). */
+    releaseClaim(issueId) {
+        this.claimed.delete(issueId);
+        this.circuitBreakers.delete(issueId);
+        const retry = this.retryAttempts.get(issueId);
+        if (retry) {
+            this.deps.timers.clearTimer(RETRY_TIMER_PREFIX + issueId);
+            this.retryAttempts.delete(issueId);
+        }
+    }
+    // ── runner feedback the shell mutates directly on the live entry ─────────────
+    // (REF: reportRuntimeEvent / reportTurnStarted — the active_tool_calls Set is a
+    // live shell handle core never holds, so the loop applies the PURE core folds
+    // — core/schedule/token-fold, injected — and writes the result back here.)
+    /** REF: reportRuntimeEvent — track in-flight tool calls (stall-reaper suppression). */
+    reportRuntimeEvent(issueId, ev) {
+        const e = this.running.get(issueId);
+        if (e)
+            applyRuntimeEvent(e, ev, this.deps.tokenFold);
+    }
+    /** REF: reportTurnStarted — turn boundary clears the in-flight tool set. */
+    reportTurnStarted(issueId, turnNumber) {
+        const e = this.running.get(issueId);
+        if (e)
+            applyTurnStarted(e, turnNumber, this.deps.tokenFold);
+    }
+    /** REF: reportTokenUsage — fold absolute ACP token totals onto the live entry (§2c). */
+    reportTokenUsage(issueId, usage) {
+        const e = this.running.get(issueId);
+        if (e)
+            applyTokenUsage(e, usage, this.deps.tokenFold);
+    }
+    /** REF: detectStalls — terminate every running entry the core stall reaper flags (§2c). */
+    reconcileStalls() {
+        for (const issueId of detectStalledIssues(this.running, this.deps.stall, this.deps.clock.now())) {
+            this.terminateRunning(issueId, false);
+        }
+    }
+    /**
+     * Cancel a running attempt out of band (REF: terminateRunning — stall reaper /
+     * reconcile terminate; operator move via the reducer's `worker.cancel` effect).
+     * Sets the optional workspace-cleanup flag, fires the live cancel closure; the
+     * worker unwinds and reports its exit through onWorkerExit. Internal-only now —
+     * the move-time cancel is driven by the reducer through `executeEffect`, not an
+     * external poke (issue 199), so a pending retry's move-time release rides the
+     * reducer's `release` delta (→ releaseClaim) instead of a sibling mutator.
+     */
+    terminateRunning(issueId, cleanupWorkspace) {
+        const entry = this.running.get(issueId);
+        if (!entry)
+            return;
+        if (cleanupWorkspace)
+            entry.cleanup_workspace_on_exit = true;
+        entry.cancel();
+    }
+    /** Lookup a live running entry (dashboard detail / reconcile state refresh). */
+    getRunning(issueId) {
+        return this.running.get(issueId);
+    }
+}
+//# sourceMappingURL=orchestrator-loop.js.map