openplanr 1.21.2 → 1.22.0

package/dist/services/operate/lifecycle-driver.js

@@ -0,0 +1,434 @@
+import { runMissionDispatchFanOut } from './mission-dispatch.js';
+import { OperateError } from './types.js';
+/** The four terminal states; a role in any of them never transitions again. */
+export const ADVISOR_LIFECYCLE_TERMINAL_STATES = Object.freeze([
+    'recorded',
+    'not_evaluated',
+    'failed',
+    'cancelled',
+]);
+export function isAdvisorLifecycleTerminal(state) {
+    return ADVISOR_LIFECYCLE_TERMINAL_STATES.includes(state);
+}
+/**
+ * The legal transition table. A `from` state maps to the events it accepts and
+ * the `to` state each yields. Any (state, event) pair absent from this table is
+ * an illegal transition and `advance` refuses it, which is what keeps the state
+ * space closed to exactly the eight declared states.
+ *
+ * `retry` re-opens a role from `running`/`returned`/`validating` back to
+ * `running`; the retry-budget accounting that decides WHETHER a retry is allowed
+ * lives in the driver (`stall`), not in the table.
+ */
+const LIFECYCLE_TRANSITIONS = Object.freeze({
+    pending: {
+        dispatch: 'running',
+        cancel: 'cancelled',
+        fail: 'failed',
+        'not-evaluated': 'not_evaluated',
+    },
+    running: {
+        return: 'returned',
+        retry: 'running',
+        fail: 'failed',
+        cancel: 'cancelled',
+        'not-evaluated': 'not_evaluated',
+    },
+    returned: {
+        validate: 'validating',
+        retry: 'running',
+        fail: 'failed',
+        cancel: 'cancelled',
+        'not-evaluated': 'not_evaluated',
+    },
+    validating: {
+        record: 'recorded',
+        retry: 'running',
+        fail: 'failed',
+        cancel: 'cancelled',
+        'not-evaluated': 'not_evaluated',
+    },
+    // Terminal states accept no events.
+    recorded: {},
+    not_evaluated: {},
+    failed: {},
+    cancelled: {},
+});
+/**
+ * A stall/timeout signal raised inside the driver's own dispatch wrapper. It is
+ * caught by the retry loop and never escapes to a sibling — a stalled role's
+ * failure is always converted to a governed terminal, so it cannot reject the
+ * fan-out or cancel another lens.
+ */
+export class AdvisorRoleStalledError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AdvisorRoleStalledError';
+    }
+}
+export class AdvisorLifecycleDriver {
+    roles = new Map();
+    order = [];
+    recordRole;
+    heartbeatFn;
+    now;
+    setTimer;
+    clearTimer;
+    heartbeatLeadMs;
+    concurrency;
+    roleTimeoutMs;
+    leaseExpiresAtMs;
+    heartbeatCount = 0;
+    timeline = [];
+    gaps = [];
+    constructor(options) {
+        this.recordRole = options.recordRole;
+        this.heartbeatFn = options.heartbeat;
+        this.now = options.now ?? Date.now;
+        this.setTimer =
+            options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer =
+            options.clearTimer ?? ((handle) => clearTimeout(handle));
+        this.heartbeatLeadMs = options.heartbeatLeadMs ?? 120_000;
+        this.concurrency = options.concurrency;
+        this.roleTimeoutMs = options.roleTimeoutMs;
+        this.leaseExpiresAtMs = options.leaseExpiresAtMs ?? Number.POSITIVE_INFINITY;
+        const defaultBudget = options.retryBudget ?? 1;
+        for (const plan of options.roles) {
+            if (this.roles.has(plan.roleId)) {
+                throw new OperateError('E_OPERATE_STATE_INVALID', `Advisor role ${plan.roleId} was prepared more than once.`);
+            }
+            const initial = plan.initialState ?? 'pending';
+            const record = {
+                plan: {
+                    roleId: plan.roleId,
+                    structurallyRequired: plan.structurallyRequired ?? false,
+                    retryBudget: Math.max(0, plan.retryBudget ?? defaultBudget),
+                },
+                state: initial,
+                attempts: 0,
+                retriesUsed: 0,
+                statusReason: plan.initialReason,
+            };
+            // A resume-seeded terminal role (e.g. already `recorded`) surfaces its
+            // governed gap so the Chair still sees a resumed not_evaluated perspective.
+            if (isAdvisorLifecycleTerminal(initial) && initial !== 'recorded') {
+                this.gaps.push({
+                    roleId: plan.roleId,
+                    outcome: initial === 'failed' ? 'failed' : 'not_evaluated',
+                    reason: plan.initialReason ?? `resumed as ${initial}`,
+                });
+            }
+            this.roles.set(plan.roleId, record);
+            this.order.push(plan.roleId);
+        }
+    }
+    /** The current state of a prepared role. */
+    state(roleId) {
+        return this.require(roleId).state;
+    }
+    /** The governed statusReason recorded on a terminal `not_evaluated`/`failed`, if any. */
+    statusReason(roleId) {
+        return this.require(roleId).statusReason;
+    }
+    /**
+     * Apply one validated lifecycle transition and return the new state. An illegal
+     * (state, event) pair — anything absent from `LIFECYCLE_TRANSITIONS` — is
+     * refused with `E_OPERATE_STATE_INVALID`, so a role can never reach a state
+     * outside the declared eight, and a terminal role can never be re-opened.
+     *
+     * `retry` additionally consults the role's retry budget; a retry beyond budget
+     * is refused here (the driver's `stall` decides retry-vs-terminate before ever
+     * calling this).
+     */
+    advance(roleId, event) {
+        const record = this.require(roleId);
+        const next = LIFECYCLE_TRANSITIONS[record.state][event.kind];
+        if (next === undefined) {
+            throw new OperateError('E_OPERATE_STATE_INVALID', `Advisor role ${roleId} cannot ${event.kind} from ${record.state}.`, { roleId, from: record.state, event: event.kind });
+        }
+        if (event.kind === 'retry') {
+            if (record.retriesUsed >= record.plan.retryBudget) {
+                throw new OperateError('E_OPERATE_STATE_INVALID', `Advisor role ${roleId} exhausted its retry budget of ${record.plan.retryBudget}.`, { roleId, retriesUsed: record.retriesUsed, retryBudget: record.plan.retryBudget });
+            }
+            record.retriesUsed += 1;
+            record.attempts += 1;
+            record.statusReason = event.reason;
+        }
+        if (event.kind === 'dispatch') {
+            record.attempts += 1;
+        }
+        if (event.kind === 'fail' || event.kind === 'cancel' || event.kind === 'not-evaluated') {
+            record.statusReason = event.reason;
+        }
+        record.state = next;
+        return next;
+    }
+    /** Whether the given role still has retry budget for another independent attempt. */
+    canRetry(roleId) {
+        const record = this.require(roleId);
+        return record.retriesUsed < record.plan.retryBudget;
+    }
+    /**
+     * Resolve a stalled/failed attempt: retry independently while budget remains,
+     * otherwise terminate. A structurally-required role terminates `failed`; an
+     * optional role terminates `not_evaluated` with a governed gap and the cycle
+     * continues. Returns the role's state after the decision (`running` on retry).
+     * Never throws for a legitimately dispatched role and never touches a sibling.
+     */
+    stall(roleId, reason) {
+        const record = this.require(roleId);
+        if (this.canRetry(roleId)) {
+            return this.advance(roleId, { kind: 'retry', reason });
+        }
+        if (record.plan.structurallyRequired) {
+            this.advance(roleId, { kind: 'fail', reason });
+            this.gaps.push({ roleId, outcome: 'failed', reason });
+            return 'failed';
+        }
+        this.advance(roleId, { kind: 'not-evaluated', reason });
+        this.gaps.push({ roleId, outcome: 'not_evaluated', reason });
+        return 'not_evaluated';
+    }
+    /**
+     * Drive ONE role's full lifecycle around a caller-supplied `dispatch` (the
+     * runtime's native-agent launch — the driver never dispatches itself). Owns the
+     * per-role retry loop, per-attempt timeout, immediate recording through T-002,
+     * and terminal classification. It resolves to the role's terminal state and
+     * NEVER rejects: a stall or hard failure becomes a governed terminal, so a
+     * sibling's fan-out slot is never rejected or cancelled by this role (FR3).
+     */
+    async executeRole(roleId, dispatch, signal) {
+        const record = this.require(roleId);
+        if (isAdvisorLifecycleTerminal(record.state)) {
+            // Resume: an already-terminal role (e.g. recorded in a prior session) is not
+            // re-dispatched — resume recovers recorded work without re-running it (FR2).
+            return record.state;
+        }
+        this.advance(roleId, { kind: 'dispatch' });
+        for (;;) {
+            try {
+                const output = await this.withTimeout(dispatch(signal), roleId);
+                this.advance(roleId, { kind: 'return' });
+                this.advance(roleId, { kind: 'validate' });
+                const outcome = await this.recordRole({ roleId, output });
+                this.updateLease(outcome.leaseExpiresAtMs);
+                if (outcome.recorded && !outcome.notEvaluated) {
+                    this.advance(roleId, { kind: 'record' });
+                    return 'recorded';
+                }
+                // T-002 durably committed a governed quiet/zero-grounding result. That is a
+                // TERMINAL not_evaluated outcome, not a stall — do not consume retry budget.
+                const reason = outcome.statusReason ?? 'recorded result grounded no resolvable evidence';
+                this.advance(roleId, { kind: 'not-evaluated', reason });
+                this.gaps.push({ roleId, outcome: 'not_evaluated', reason });
+                return 'not_evaluated';
+            }
+            catch (error) {
+                const reason = stallReason(error);
+                const state = this.stall(roleId, reason);
+                if (state === 'running')
+                    continue; // retried independently on its own budget
+                return state; // terminal not_evaluated/failed — siblings are untouched
+            }
+        }
+    }
+    /**
+     * Fan the prepared, non-terminal roles out through the shared bounded-concurrency
+     * primitive, driving each through `executeRole`. Already-terminal (resumed) roles
+     * are skipped. The fan-out's new lifecycle reporter records an observability
+     * timeline through the driver without owning any state transition — `executeRole`
+     * remains the single source of truth for the state machine.
+     */
+    async run(input) {
+        const items = this.order.filter((roleId) => !isAdvisorLifecycleTerminal(this.state(roleId)));
+        await runMissionDispatchFanOut({
+            items,
+            parallel: input.parallel,
+            ...(this.concurrency !== undefined ? { concurrency: this.concurrency } : {}),
+            ...(input.perRoleBudgetMs !== undefined ? { perRoleBudgetMs: input.perRoleBudgetMs } : {}),
+            now: this.now,
+            lifecycle: {
+                onDispatch: (roleId) => this.recordTimeline(roleId, 'dispatch'),
+                onReturn: (roleId) => this.recordTimeline(roleId, 'return'),
+                onError: (roleId) => this.recordTimeline(roleId, 'error'),
+            },
+            run: (roleId, signal) => this.executeRole(roleId, (s) => input.dispatch(roleId, s), signal),
+        });
+        return this.summary();
+    }
+    /**
+     * True once every non-structurally-required role has reached a terminal state,
+     * without requiring a structurally-optional role to have RECORDED — a governed
+     * `not_evaluated` optional role satisfies readiness because the Chair surfaces
+     * it as a gap (FR13). Structurally-required roles must reach `recorded`
+     * specifically: their missing analysis is a hard gap the Chair cannot synthesize
+     * around, so a required role that is `failed`/`not_evaluated`/`cancelled` — or
+     * still in flight — holds Chair readiness closed. The `chair` role itself is
+     * dispatched separately and is excluded here.
+     */
+    chairReady() {
+        for (const roleId of this.order) {
+            if (roleId === 'chair')
+                continue;
+            const record = this.require(roleId);
+            if (record.plan.structurallyRequired) {
+                if (record.state !== 'recorded')
+                    return false;
+            }
+            else if (!isAdvisorLifecycleTerminal(record.state)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Schedule automatic lease heartbeats independent of any role completing (FR2).
+     * Every `intervalMs` (injected timer) the scheduler checks the lease's remaining
+     * time against `heartbeatLeadMs`; when the window is approaching it renews
+     * through T-002's `heartbeat` action and carries the refreshed expiry forward.
+     * Returns a cancel function; the scheduler also stops on its own once every role
+     * is terminal (nothing left to keep alive). A slow lens can therefore hold the
+     * session open while siblings keep their recorded work, without raising the
+     * configured lease duration.
+     */
+    scheduleHeartbeat(intervalMs) {
+        if (!this.heartbeatFn) {
+            throw new OperateError('E_OPERATE_STATE_INVALID', 'Heartbeat scheduling requires a heartbeat action; none was injected.');
+        }
+        let cancelled = false;
+        let handle = null;
+        const stop = () => {
+            cancelled = true;
+            if (handle !== null)
+                this.clearTimer(handle);
+        };
+        const tick = async () => {
+            if (cancelled)
+                return;
+            if (this.allRolesTerminal()) {
+                stop();
+                return;
+            }
+            const remaining = this.leaseExpiresAtMs - this.now();
+            if (remaining <= this.heartbeatLeadMs) {
+                const snapshot = await this.heartbeatFn();
+                this.updateLease(snapshot.leaseExpiresAtMs);
+                this.heartbeatCount += 1;
+            }
+            if (!cancelled)
+                handle = this.setTimer(() => void tick(), intervalMs);
+        };
+        handle = this.setTimer(() => void tick(), intervalMs);
+        return stop;
+    }
+    /** How many heartbeats the scheduler has issued so far (observability/tests). */
+    heartbeatsIssued() {
+        return this.heartbeatCount;
+    }
+    /** The current lease expiry (ms epoch) the driver is tracking. */
+    leaseExpiry() {
+        return this.leaseExpiresAtMs;
+    }
+    /** Governed gaps for roles that terminated without a recorded analysis (FR13). */
+    governedGaps() {
+        return [...this.gaps];
+    }
+    /** The observability timeline recorded through the fan-out reporter. */
+    dispatchTimeline() {
+        return [...this.timeline];
+    }
+    /** A per-role snapshot in prepared order for `status`/`report` (FR5). */
+    snapshot() {
+        return this.order.map((roleId) => {
+            const record = this.require(roleId);
+            return {
+                roleId,
+                state: record.state,
+                attempts: record.attempts,
+                retriesUsed: record.retriesUsed,
+                retryBudget: record.plan.retryBudget,
+                structurallyRequired: record.plan.structurallyRequired,
+                ...(record.statusReason ? { statusReason: record.statusReason } : {}),
+            };
+        });
+    }
+    /**
+     * Cancel every still-in-flight role (bookkeeping only — the session cancel is
+     * the caller's concern). Already-terminal roles are left untouched, so a
+     * mid-cycle cancel preserves recorded work.
+     */
+    cancelInFlight(reason) {
+        for (const roleId of this.order) {
+            const record = this.require(roleId);
+            if (!isAdvisorLifecycleTerminal(record.state)) {
+                this.advance(roleId, { kind: 'cancel', reason });
+            }
+        }
+    }
+    summary() {
+        const collect = (state) => this.order.filter((roleId) => roleId !== 'chair' && this.state(roleId) === state);
+        return {
+            roles: this.snapshot(),
+            recorded: collect('recorded'),
+            notEvaluated: collect('not_evaluated'),
+            failed: collect('failed'),
+            cancelled: collect('cancelled'),
+            gaps: this.governedGaps(),
+            chairReady: this.chairReady(),
+            heartbeats: this.heartbeatCount,
+        };
+    }
+    allRolesTerminal() {
+        return this.order.every((roleId) => isAdvisorLifecycleTerminal(this.state(roleId)));
+    }
+    recordTimeline(roleId, event) {
+        this.timeline.push({ roleId, event, at: this.now() });
+    }
+    updateLease(expiresAtMs) {
+        if (expiresAtMs !== undefined && Number.isFinite(expiresAtMs)) {
+            this.leaseExpiresAtMs = expiresAtMs;
+        }
+    }
+    require(roleId) {
+        const record = this.roles.get(roleId);
+        if (!record) {
+            throw new OperateError('E_OPERATE_STATE_INVALID', `Advisor role ${roleId} was not prepared by this driver.`, { roleId });
+        }
+        return record;
+    }
+    /**
+     * Race a role's dispatch against its per-attempt timeout using the INJECTED
+     * timer, so timeout behaviour is deterministic under a test clock and never a
+     * wall-clock sleep. With no configured timeout the dispatch promise is returned
+     * as-is. A fired timeout rejects with `AdvisorRoleStalledError`, which the retry
+     * loop converts to a governed retry or terminal — it never escapes to a sibling.
+     */
+    withTimeout(promise, roleId) {
+        const timeoutMs = this.roleTimeoutMs;
+        if (!timeoutMs || timeoutMs <= 0)
+            return promise;
+        return new Promise((resolve, reject) => {
+            const handle = this.setTimer(() => {
+                reject(new AdvisorRoleStalledError(`Advisor role ${roleId} did not return within its ${timeoutMs}ms attempt budget.`));
+            }, timeoutMs);
+            promise.then((value) => {
+                this.clearTimer(handle);
+                resolve(value);
+            }, (error) => {
+                this.clearTimer(handle);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            });
+        });
+    }
+}
+function stallReason(error) {
+    if (error instanceof AdvisorRoleStalledError)
+        return error.message;
+    if (error instanceof OperateError)
+        return `${error.code}: ${error.message}`;
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+//# sourceMappingURL=lifecycle-driver.js.map

package/dist/services/operate/lifecycle-driver.js.map

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

package/dist/services/operate/maintenance.d.ts

@@ -17,6 +17,24 @@ export declare function purgeBoardMachineLocalCaches(input: {
     removedAdvisorSessions: number;
     removedIncrementalBaselines: number;
 }>;
+/**
+ * FR7 (T-006): sibling machine-local cleanup for OpenPlanr-owned scratch left
+ * behind by a session that never finalized. Deliberately NOT folded into
+ * `purgeBoardMachineLocalCaches` — scratch has its own narrower per-cycle
+ * lifecycle. Removes ONLY scratch a valid `openplanr-operate-scratch` manifest
+ * confirms this project wrote and whose lease window has lapsed; it never touches
+ * an unowned file found under the scratch root, nor any other machine-local
+ * cache. This is the owned-only removal the doctor's abandoned-scratch diagnostic
+ * points at, and the sibling `operate cache purge` invokes.
+ */
+export declare function purgeAbandonedOperatingScratch(input: {
+    projectRoot: string;
+    localRoot?: string;
+    now?: () => Date;
+}): Promise<{
+    removed: number;
+    cycles: string[];
+}>;
 export declare function operatingCacheAction(input: {
     projectRoot: string;
     action: 'status' | 'purge';
@@ -57,13 +75,18 @@ export declare function createOperatingAdapterStartHandoff(input: {
 }): Promise<OperatingAdapterHandoff>;
 export declare function operateAdapterLifecycle(input: {
     projectRoot: string;
-    action: 'prepare' | 'record' | 'resume' | 'finalize' | 'cancel';
+    action: 'prepare' | 'record' | 'resume' | 'finalize' | 'cancel' | 'heartbeat' | 'abandon';
     cycleId?: string;
     evidenceDigest?: string;
     lease?: string;
     idempotencyKey?: string;
     role?: string;
     stdin?: string;
+    /**
+     * SPEC-005 T-020: the governed reason a lens is abandoned terminal
+     * `not_evaluated`. Required for `action: 'abandon'`; unused otherwise.
+     */
+    reason?: string;
     localRoot?: string;
     /**
      * Injectable clock (FR10 / T-008). Defaults to wall-clock. Tests supply a
@@ -72,4 +95,45 @@ export declare function operateAdapterLifecycle(input: {
      */
     now?: () => Date;
 }): Promise<unknown>;
+/**
+ * SPEC-005 T-020 (FR13) — the OPERATOR escape, independent of a well-behaved
+ * runtime. When a runtime dispatched a lens and then reported nothing at all — it
+ * crashed, or does not implement `harness abandon` — the cycle is stranded at
+ * `phase: advisors` on every continuation: the stalled lens is never recorded, so
+ * it stays runnable-and-required and Chair is never assembled. The only prior
+ * recourse was `cycles cancel`, which discards the whole cycle including the
+ * siblings that DID record.
+ *
+ * This governed escape reaches a reviewable cycle without discarding it. It is
+ * gated on a LAPSED lease — the legitimate signal that no runtime is actively
+ * working the session — and an explicit operator confirmation. It never touches
+ * the runtime lifecycle (`harness abandon`/`record`/`finalize`), so it works when
+ * the runtime is gone. For each still-unrecorded advisor lens it commits the SAME
+ * governed terminal `not_evaluated` gap the runtime path commits
+ * (`governTerminalNotEvaluated`), so the next `run` continuation reconstructs the
+ * lens `not_evaluated` from committed state and consolidation proceeds. Recorded
+ * siblings are never read, re-dispatched, or altered. It fabricates nothing.
+ *
+ * It does not itself run consolidation — the operator reaches `reviewable` with a
+ * following `planr operate run` (offline when no runtime is available), so the
+ * choice of a real or offline Chair stays the operator's.
+ */
+export declare function reapStalledOperatingRoles(input: {
+    projectRoot: string;
+    cycleId: string;
+    role?: string;
+    reason?: string;
+    confirmed?: boolean;
+    localRoot?: string;
+    now?: () => Date;
+}): Promise<{
+    cycleId: string;
+    reaped: Array<{
+        roleId: string;
+        reason: string;
+        gapId: string;
+    }>;
+    alreadyRecorded: string[];
+    next: string[];
+}>;
 //# sourceMappingURL=maintenance.d.ts.map

package/dist/services/operate/maintenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../../src/services/operate/maintenance.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../../src/services/operate/maintenance.ts"],"names":[],"mappings":"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"}