instar 0.28.83 → 0.28.85

package/dist/core/InitiativeTracker.js

@@ -5,26 +5,99 @@
  * scheduled Jobs (recurring cron task). An Initiative represents a
  * bounded-but-multi-week effort with phases, each advancing in order.
  *
- * Persistence: `.instar/initiatives.json` (atomic rename pattern).
+ * Storage:
+ *   - When TaskFlow is wired (`setTaskFlowRegistry`), TaskFlow is the
+ *     **single source of truth** (per OPENCLAW-IMPORT-TASKFLOW-SPEC.md
+ *     § Phase 4, lines 645–648). Each initiative is one TaskFlow record:
+ *     `controllerId="InitiativeTracker"`, `ownerKey="initiative:<id>"`,
+ *     `idempotencyKey="initiative:<id>"`. The full Initiative shape is
+ *     persisted in `stateJson`. The active phase id maps to `currentStep`;
+ *     `needsUser` / blockers map to `setFlowWaiting({kind:"human-review"})`.
+ *   - When TaskFlow is NOT wired, behavior falls back to legacy
+ *     `.instar/initiatives.json`. This keeps the disabled-feature path
+ *     working for installs where `taskFlow.enabled` is false.
+ *
+ * Migration:
+ *   - On startup, the server calls `migrateExistingToTaskFlow()` once when
+ *     TaskFlow is enabled. It backfills any initiatives present in the
+ *     legacy JSON file into TaskFlow. Idempotent via `findIdempotent` on
+ *     `(controllerId, ownerKey, idempotencyKey)` — running twice produces
+ *     no duplicates.
+ *
+ * API shape:
+ *   - All public mutators are `async` to allow TaskFlow's promise-based
+ *     write API to complete before returning. Reads are `sync` (TaskFlow's
+ *     read API uses `better-sqlite3` synchronously through the in-memory
+ *     cache).
+ *
  * Consumers: HTTP routes (`/initiatives/*`), dashboard "Initiatives" tab,
  * daily digest job (alerts when initiatives go stale / need user input /
  * are ready to advance).
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { TaskFlowError } from '../tasks/task-flow-types.js';
 /**
  * Staleness threshold for the digest scan (7 days without an update on an
  * active initiative triggers a 'stale' flag).
  */
 export const STALE_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * TaskFlow controller identity for InitiativeTracker (Phase 4 migration).
+ * Every initiative's flow is owned by this controllerId; the registry uses
+ * it for OCC scope checks. Single instance per server process.
+ */
+export const INITIATIVE_TASKFLOW_CONTROLLER_ID = 'InitiativeTracker';
+function ownerKeyForInitiative(initiativeId) {
+    return `initiative:${initiativeId}`;
+}
+function idempotencyKeyForInitiative(initiativeId) {
+    return `initiative:${initiativeId}`;
+}
 export class InitiativeTracker {
     filePath;
+    /** In-process cache. Authoritative when TaskFlow is not wired; otherwise
+     * a read-side projection of TaskFlow's stateJson. */
     initiatives = new Map();
+    // ── TaskFlow Phase 4 wiring ────────────────────────────────────
+    taskFlowRegistry = null;
+    taskFlowControllerInstanceId = null;
     constructor(stateDir) {
         this.filePath = path.join(stateDir, 'initiatives.json');
-        this.load();
+        this.loadFromDisk();
+    }
+    /**
+     * Wire a TaskFlow registry to make TaskFlow the source of truth.
+     * Idempotent — safe to call multiple times. After wiring, all reads come
+     * from TaskFlow and all writes go through TaskFlow APIs. The legacy JSON
+     * file is no longer written.
+     *
+     * Callers are expected to call `migrateExistingToTaskFlow()` after this
+     * to backfill any initiatives that were loaded from the legacy file.
+     */
+    setTaskFlowRegistry(registry, controllerInstanceId) {
+        this.taskFlowRegistry = registry;
+        this.taskFlowControllerInstanceId = controllerInstanceId;
+        // Layer existing TaskFlow records over legacy-loaded data without
+        // clearing the cache: any legacy initiatives still need to be backfilled
+        // via `migrateExistingToTaskFlow()`. TaskFlow records win on collision.
+        this.layerCacheFromTaskFlow();
+    }
+    /** True when TaskFlow is wired and authoritative. */
+    isTaskFlowEnabled() {
+        return this.taskFlowRegistry !== null && this.taskFlowControllerInstanceId !== null;
+    }
+    taskFlowPrincipal() {
+        if (!this.taskFlowRegistry || !this.taskFlowControllerInstanceId)
+            return null;
+        return {
+            scope: 'controller',
+            controllerId: INITIATIVE_TASKFLOW_CONTROLLER_ID,
+            controllerInstanceId: this.taskFlowControllerInstanceId,
+        };
     }
-    load() {
+    // ── Legacy JSON storage (used until TaskFlow is wired) ─────────
+    loadFromDisk() {
         try {
             if (!fs.existsSync(this.filePath))
                 return;
@@ -41,7 +114,9 @@ export class InitiativeTracker {
             console.error(`[initiatives] Failed to load: ${err instanceof Error ? err.message : err}`);
         }
     }
-    save() {
+    saveToDisk() {
+        if (this.isTaskFlowEnabled())
+            return; // TaskFlow's SQLite is the durable store.
         const dir = path.dirname(this.filePath);
         fs.mkdirSync(dir, { recursive: true });
         const payload = { initiatives: Array.from(this.initiatives.values()) };
@@ -49,24 +124,362 @@ export class InitiativeTracker {
         fs.writeFileSync(tmp, JSON.stringify(payload, null, 2));
         fs.renameSync(tmp, this.filePath);
     }
+    // ── TaskFlow ↔ Initiative serialization ─────────────────────────
+    initiativeFromFlow(flow) {
+        const state = flow.stateJson;
+        if (!state || typeof state !== 'object' || !state.initiative)
+            return null;
+        return state.initiative;
+    }
+    refreshCacheFromTaskFlow() {
+        if (!this.taskFlowRegistry)
+            return;
+        const flows = this.taskFlowRegistry.findByControllerId(INITIATIVE_TASKFLOW_CONTROLLER_ID);
+        this.initiatives.clear();
+        for (const f of flows) {
+            const init = this.initiativeFromFlow(f);
+            // Tombstone-removed initiatives are filtered out so callers can't
+            // see them via list() / get() after remove().
+            if (init && !this.isTombstoned(f)) {
+                this.initiatives.set(init.id, init);
+            }
+        }
+    }
+    /**
+     * Layer TaskFlow data on top of the existing cache without clearing it.
+     * Used during `setTaskFlowRegistry` so legacy-loaded initiatives are
+     * preserved as backfill candidates while any pre-existing TaskFlow
+     * records take precedence.
+     */
+    layerCacheFromTaskFlow() {
+        if (!this.taskFlowRegistry)
+            return;
+        const flows = this.taskFlowRegistry.findByControllerId(INITIATIVE_TASKFLOW_CONTROLLER_ID);
+        for (const f of flows) {
+            const init = this.initiativeFromFlow(f);
+            if (init && !this.isTombstoned(f)) {
+                this.initiatives.set(init.id, init);
+            }
+            else if (this.isTombstoned(f) && init) {
+                // Tombstoned flows shadow legacy entries.
+                this.initiatives.delete(init.id);
+            }
+        }
+    }
+    /**
+     * A flow is "tombstoned" when remove() marked it as removed before
+     * cancelling. The marker lives in stateJson._removed and is the
+     * single signal that a flow's owning Initiative should be hidden from
+     * list() / get(). We can't delete TaskFlow records from this layer, so
+     * the marker is the durable equivalent of deletion.
+     */
+    isTombstoned(flow) {
+        const state = flow.stateJson;
+        return state?._removed === true;
+    }
+    waitJsonForInitiative(init) {
+        const blocked = init.needsUser || init.blockers.length > 0;
+        if (!blocked)
+            return null;
+        const reason = init.needsUser
+            ? init.needsUserReason ?? 'Initiative needs user decision'
+            : init.blockers.join('; ');
+        const question = (reason || 'Initiative blocked').slice(0, 2000);
+        return { kind: 'human-review', question };
+    }
+    /** Determine the desired TaskFlow status for an Initiative. */
+    desiredFlowStatus(init) {
+        const phase = init.phases[init.currentPhaseIndex];
+        const step = phase ? phase.id : 'unknown';
+        if (init.status === 'completed')
+            return { kind: 'succeeded', step };
+        if (init.status === 'abandoned')
+            return { kind: 'failed', step };
+        if (init.status === 'archived')
+            return { kind: 'cancelled', step };
+        const wait = this.waitJsonForInitiative(init);
+        if (wait)
+            return { kind: 'waiting', step, waitJson: wait };
+        return { kind: 'running', step };
+    }
+    /**
+     * Persist an Initiative through TaskFlow. Walks the flow state machine
+     * to the desired target (running / waiting / succeeded / failed /
+     * cancelled), updating `stateJson` along the way so reads see the latest
+     * shape. Returns the Initiative as projected from TaskFlow after
+     * transitions settle.
+     */
+    async persistThroughTaskFlow(init) {
+        const registry = this.taskFlowRegistry;
+        const principal = this.taskFlowPrincipal();
+        if (!registry || !principal || principal.scope !== 'controller')
+            return init;
+        const ownerKey = ownerKeyForInitiative(init.id);
+        const idemKey = idempotencyKeyForInitiative(init.id);
+        const desired = this.desiredFlowStatus(init);
+        const stateJson = { initiative: init };
+        let existing = registry.findByIdempotency(INITIATIVE_TASKFLOW_CONTROLLER_ID, ownerKey, idemKey);
+        if (!existing) {
+            const r = await registry.createFlow({
+                controllerId: INITIATIVE_TASKFLOW_CONTROLLER_ID,
+                controllerInstanceId: principal.controllerInstanceId,
+                ownerKey,
+                idempotencyKey: idemKey,
+                goal: init.title.slice(0, 1024),
+                currentStep: desired.step,
+                stateJson,
+            });
+            existing = r.flow;
+        }
+        let cur = registry.getFlow(existing.flowId, { bypassCache: true }) ?? existing;
+        try {
+            // Already terminal? Accept and stop — terminal flows are immutable
+            // per TaskFlow contract. The Initiative's local terminal state stays
+            // in sync via the cache, but we never re-mutate the flow.
+            if (cur.status === 'succeeded' ||
+                cur.status === 'failed' ||
+                cur.status === 'cancelled' ||
+                cur.status === 'lost') {
+                return this.initiativeFromFlow(cur) ?? init;
+            }
+            // queued → running (always; a fresh create lands in queued).
+            if (cur.status === 'queued') {
+                const r = await registry.startStep({
+                    flowId: cur.flowId,
+                    expectedRevision: cur.revision,
+                    principal,
+                    currentStep: desired.step,
+                });
+                cur = r.flow;
+            }
+            // waiting → running (resume), in case desired wait is different or
+            // we're moving to running/terminal. resumeFlow accepts statePatch so
+            // we update stateJson here too.
+            if (cur.status === 'waiting') {
+                if (cur.waitInstanceId) {
+                    const r = await registry.resumeFlow({
+                        flowId: cur.flowId,
+                        expectedRevision: cur.revision,
+                        principal,
+                        waitInstanceId: cur.waitInstanceId,
+                        currentStep: desired.step,
+                        statePatch: stateJson,
+                    });
+                    cur = r.flow;
+                }
+            }
+            // Now cur.status === 'running'. Drive to the desired terminal state.
+            if (cur.status === 'running') {
+                if (desired.kind === 'running') {
+                    // Re-startStep when currentStep changed; this updates the step.
+                    if (cur.currentStep !== desired.step) {
+                        const r = await registry.startStep({
+                            flowId: cur.flowId,
+                            expectedRevision: cur.revision,
+                            principal,
+                            currentStep: desired.step,
+                        });
+                        cur = r.flow;
+                    }
+                    // Always patch stateJson to reflect the latest Initiative shape.
+                    cur = await this.patchStateJson(cur, stateJson);
+                }
+                else if (desired.kind === 'waiting') {
+                    const r = await registry.setFlowWaiting({
+                        flowId: cur.flowId,
+                        expectedRevision: cur.revision,
+                        principal,
+                        waitJson: desired.waitJson,
+                        currentStep: desired.step,
+                        statePatch: stateJson,
+                    });
+                    cur = r.flow;
+                }
+                else if (desired.kind === 'succeeded') {
+                    cur = await this.patchStateJson(cur, stateJson);
+                    const r = await registry.finishFlow({
+                        flowId: cur.flowId,
+                        expectedRevision: cur.revision,
+                        principal,
+                    });
+                    cur = r.flow;
+                }
+                else if (desired.kind === 'failed') {
+                    cur = await this.patchStateJson(cur, stateJson);
+                    const r = await registry.failFlow({
+                        flowId: cur.flowId,
+                        expectedRevision: cur.revision,
+                        principal,
+                        failureReason: 'abandoned',
+                    });
+                    cur = r.flow;
+                }
+                else if (desired.kind === 'cancelled') {
+                    cur = await this.patchStateJson(cur, stateJson);
+                    const cr = await registry.requestFlowCancel({
+                        flowId: cur.flowId,
+                        expectedRevision: cur.revision,
+                        requesterOrigin: { kind: 'system', id: 'InitiativeTracker' },
+                    });
+                    const r = await registry.cancelFlow({
+                        flowId: cur.flowId,
+                        expectedRevision: cr.flow.revision,
+                        principal,
+                    });
+                    cur = r.flow;
+                }
+            }
+        }
+        catch (err) {
+            this.logTaskFlowError('persist', init.id, err);
+        }
+        const fresh = registry.getFlow(cur.flowId, { bypassCache: true }) ?? cur;
+        const persisted = this.initiativeFromFlow(fresh) ?? init;
+        this.initiatives.set(persisted.id, persisted);
+        return persisted;
+    }
+    /**
+     * Patch a running flow's stateJson without changing its observable
+     * status. Uses a brief setFlowWaiting → resumeFlow round-trip (the only
+     * atomic state-bearing transitions for `running` flows that accept
+     * `statePatch`). The wait kind `'human-review'` with a sentinel question
+     * is used; the wait is consumed in the same call, so no external
+     * observer sees `waiting`.
+     */
+    async patchStateJson(flow, stateJson) {
+        const registry = this.taskFlowRegistry;
+        const principal = this.taskFlowPrincipal();
+        if (!registry || !principal || principal.scope !== 'controller')
+            return flow;
+        if (flow.status !== 'running')
+            return flow;
+        try {
+            const w = await registry.setFlowWaiting({
+                flowId: flow.flowId,
+                expectedRevision: flow.revision,
+                principal,
+                waitJson: { kind: 'human-review', question: '__statePatch__' },
+                statePatch: stateJson,
+            });
+            const r = await registry.resumeFlow({
+                flowId: w.flow.flowId,
+                expectedRevision: w.flow.revision,
+                principal,
+                waitInstanceId: w.flow.waitInstanceId,
+                statePatch: stateJson,
+            });
+            return r.flow;
+        }
+        catch (err) {
+            this.logTaskFlowError('patchStateJson', flow.flowId, err);
+            return flow;
+        }
+    }
+    findFlowIdForInitiative(id) {
+        const registry = this.taskFlowRegistry;
+        if (!registry)
+            return null;
+        const f = registry.findByIdempotency(INITIATIVE_TASKFLOW_CONTROLLER_ID, ownerKeyForInitiative(id), idempotencyKeyForInitiative(id));
+        return f?.flowId ?? null;
+    }
+    logTaskFlowError(op, key, err) {
+        if (err instanceof TaskFlowError) {
+            console.warn(`[InitiativeTracker] taskflow ${op} for ${key} skipped: ${err.code} (${err.message})`);
+        }
+        else {
+            console.warn(`[InitiativeTracker] taskflow ${op} for ${key} unexpected error:`, err instanceof Error ? err.message : err);
+        }
+    }
+    /**
+     * Backfill all initiatives currently in the in-memory cache (loaded from
+     * legacy JSON in the constructor) into TaskFlow. Idempotent via
+     * `findIdempotent`. Safe to call multiple times.
+     */
+    async migrateExistingToTaskFlow() {
+        const registry = this.taskFlowRegistry;
+        const principal = this.taskFlowPrincipal();
+        if (!registry || !principal || principal.scope !== 'controller') {
+            return { created: 0, alreadyExisted: 0, advanced: 0, skipped: 0 };
+        }
+        let created = 0;
+        let alreadyExisted = 0;
+        let advanced = 0;
+        let skipped = 0;
+        const candidates = Array.from(this.initiatives.values());
+        for (const init of candidates) {
+            try {
+                const ownerKey = ownerKeyForInitiative(init.id);
+                const idemKey = idempotencyKeyForInitiative(init.id);
+                const existing = registry.findByIdempotency(INITIATIVE_TASKFLOW_CONTROLLER_ID, ownerKey, idemKey);
+                if (existing) {
+                    alreadyExisted++;
+                }
+                else {
+                    await registry.createFlow({
+                        controllerId: INITIATIVE_TASKFLOW_CONTROLLER_ID,
+                        controllerInstanceId: principal.controllerInstanceId,
+                        ownerKey,
+                        idempotencyKey: idemKey,
+                        goal: init.title.slice(0, 1024),
+                        currentStep: init.phases[init.currentPhaseIndex]?.id ?? 'start',
+                        stateJson: { initiative: init },
+                    });
+                    created++;
+                }
+                const persisted = await this.persistThroughTaskFlow(init);
+                if (persisted)
+                    advanced++;
+            }
+            catch (err) {
+                skipped++;
+                this.logTaskFlowError('migrate', init.id, err);
+            }
+        }
+        this.refreshCacheFromTaskFlow();
+        return { created, alreadyExisted, advanced, skipped };
+    }
+    // ── Public API ─────────────────────────────────────────────────
     list(filter) {
+        if (this.isTaskFlowEnabled())
+            this.refreshCacheFromTaskFlow();
         const all = Array.from(this.initiatives.values());
         const filtered = filter?.status ? all.filter((i) => i.status === filter.status) : all;
         return filtered.sort((a, b) => b.lastTouchedAt.localeCompare(a.lastTouchedAt));
     }
     get(id) {
+        if (this.isTaskFlowEnabled()) {
+            const fid = this.findFlowIdForInitiative(id);
+            if (!fid)
+                return undefined;
+            const f = this.taskFlowRegistry.getFlow(fid, { bypassCache: true });
+            if (!f)
+                return undefined;
+            if (this.isTombstoned(f)) {
+                this.initiatives.delete(id);
+                return undefined;
+            }
+            const init = this.initiativeFromFlow(f);
+            if (init)
+                this.initiatives.set(id, init);
+            return init ?? undefined;
+        }
         return this.initiatives.get(id);
     }
-    create(input) {
-        if (this.initiatives.has(input.id)) {
-            throw new Error(`Initiative "${input.id}" already exists`);
-        }
+    async create(input) {
         if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(input.id)) {
             throw new Error('Initiative id must be lowercase kebab-case, 1–63 chars');
         }
         if (!input.phases.length) {
             throw new Error('Initiative must have at least one phase');
         }
+        if (this.isTaskFlowEnabled()) {
+            if (this.findFlowIdForInitiative(input.id)) {
+                throw new Error(`Initiative "${input.id}" already exists`);
+            }
+        }
+        else if (this.initiatives.has(input.id)) {
+            throw new Error(`Initiative "${input.id}" already exists`);
+        }
         const now = new Date().toISOString();
         const phases = input.phases.map((p) => ({
             id: p.id,
@@ -74,7 +487,6 @@ export class InitiativeTracker {
             summary: p.summary,
             status: p.status ?? 'pending',
         }));
-        // currentPhaseIndex: first non-'done' phase, else last phase.
         const firstOpen = phases.findIndex((p) => p.status !== 'done');
         const currentPhaseIndex = firstOpen === -1 ? phases.length - 1 : firstOpen;
         const allDone = phases.every((p) => p.status === 'done');
@@ -95,11 +507,14 @@ export class InitiativeTracker {
             updatedAt: now,
         };
         this.initiatives.set(initiative.id, initiative);
-        this.save();
+        if (this.isTaskFlowEnabled()) {
+            return await this.persistThroughTaskFlow(initiative);
+        }
+        this.saveToDisk();
         return initiative;
     }
-    update(id, input) {
-        const existing = this.initiatives.get(id);
+    async update(id, input) {
+        const existing = this.get(id);
         if (!existing)
             throw new Error(`Initiative "${id}" not found`);
         const now = new Date().toISOString();
@@ -123,17 +538,14 @@ export class InitiativeTracker {
         if (input.links !== undefined)
             next.links = input.links;
         this.initiatives.set(id, next);
-        this.save();
+        if (this.isTaskFlowEnabled()) {
+            return await this.persistThroughTaskFlow(next);
+        }
+        this.saveToDisk();
         return next;
     }
-    /**
-     * Transition a phase's status. Updates currentPhaseIndex to point to the
-     * earliest non-done phase; marks the whole initiative 'completed' when
-     * all phases are 'done'. Sets startedAt/completedAt the first time a
-     * phase reaches 'in-progress' / 'done' respectively.
-     */
-    setPhaseStatus(id, phaseId, status) {
-        const existing = this.initiatives.get(id);
+    async setPhaseStatus(id, phaseId, status) {
+        const existing = this.get(id);
         if (!existing)
             throw new Error(`Initiative "${id}" not found`);
         const phases = existing.phases.map((p) => ({ ...p }));
@@ -157,21 +569,84 @@ export class InitiativeTracker {
             lastTouchedAt: now,
         };
         this.initiatives.set(id, next);
-        this.save();
+        if (this.isTaskFlowEnabled()) {
+            return await this.persistThroughTaskFlow(next);
+        }
+        this.saveToDisk();
         return next;
     }
-    remove(id) {
+    async remove(id) {
+        if (this.isTaskFlowEnabled()) {
+            const fid = this.findFlowIdForInitiative(id);
+            if (!fid) {
+                return this.initiatives.delete(id);
+            }
+            const registry = this.taskFlowRegistry;
+            const principal = this.taskFlowPrincipal();
+            let flow = registry.getFlow(fid, { bypassCache: true });
+            if (flow && principal && principal.scope === 'controller') {
+                try {
+                    if (flow.status === 'queued') {
+                        const r = await registry.startStep({
+                            flowId: flow.flowId,
+                            expectedRevision: flow.revision,
+                            principal,
+                            currentStep: flow.currentStep ?? 'remove',
+                        });
+                        flow = r.flow;
+                    }
+                    if (flow.status === 'waiting' && flow.waitInstanceId) {
+                        const r = await registry.resumeFlow({
+                            flowId: flow.flowId,
+                            expectedRevision: flow.revision,
+                            principal,
+                            waitInstanceId: flow.waitInstanceId,
+                        });
+                        flow = r.flow;
+                    }
+                    // Stamp the tombstone marker into stateJson so subsequent reads
+                    // hide the initiative. Done before cancel because terminal flows
+                    // are immutable.
+                    const init = this.initiativeFromFlow(flow);
+                    if (flow.status === 'running' && init) {
+                        const tomb = await this.patchStateJson(flow, { initiative: init, _removed: true });
+                        flow = tomb;
+                    }
+                    if (flow.status !== 'succeeded' &&
+                        flow.status !== 'failed' &&
+                        flow.status !== 'cancelled' &&
+                        flow.status !== 'lost') {
+                        const cr = await registry.requestFlowCancel({
+                            flowId: flow.flowId,
+                            expectedRevision: flow.revision,
+                            requesterOrigin: { kind: 'system', id: 'InitiativeTracker' },
+                        });
+                        await registry.cancelFlow({
+                            flowId: flow.flowId,
+                            expectedRevision: cr.flow.revision,
+                            principal,
+                        });
+                    }
+                }
+                catch (err) {
+                    this.logTaskFlowError('remove', id, err);
+                }
+            }
+            this.initiatives.delete(id);
+            return true;
+        }
         const removed = this.initiatives.delete(id);
         if (removed)
-            this.save();
+            this.saveToDisk();
         return removed;
     }
     /**
-     * Scan active initiatives for anything actionable. The digest job uses
-     * this to decide whether to send a push notification. Empty items[]
-     * means "quiet day, don't spam the user."
+     * Scan active initiatives for anything actionable. Empty items[] means
+     * "quiet day, don't spam the user."
      */
     digest(now = new Date()) {
+        if (this.isTaskFlowEnabled())
+            this.refreshCacheFromTaskFlow();
         const items = [];
         const nowMs = now.getTime();
         for (const initiative of this.initiatives.values()) {
@@ -198,10 +673,6 @@ export class InitiativeTracker {
                     continue;
                 }
             }
-            // Ready-to-advance: the previous phase is done AND the current
-            // phase is still untouched ('pending'). Once the current phase
-            // is 'in-progress' or 'blocked', the advance has already begun,
-            // so we stop emitting this signal.
             const current = initiative.phases[initiative.currentPhaseIndex];
             const previous = initiative.currentPhaseIndex > 0
                 ? initiative.phases[initiative.currentPhaseIndex - 1]