openplanr 1.21.2 → 1.22.0

package/dist/services/operate/interaction/question-registry.js

@@ -62,6 +62,23 @@ const PRODUCT_STAGE_CHOICES = [
 function effectiveDetectedRuntime(context) {
     return (KNOWN_CODING_RUNTIMES.find((runtime) => runtime === context.runtime) ?? context.detectedRuntime);
 }
+/**
+ * FR10 / T-009: the profile suggestion reason. When the detected profile file
+ * carries fields the current CLI would reject, the reason names them and points
+ * to the migration command so the operator can reconcile the profile instead of
+ * being handed a suggestion the tool will refuse to reuse as-is.
+ */
+function existingProfileSuggestionReason(unsupportedFields) {
+    const base = 'Suggested from the existing .planr/operate-profile.json; confirm or choose another.';
+    if (!unsupportedFields || unsupportedFields.length === 0)
+        return base;
+    const names = [...unsupportedFields]
+        .sort()
+        .map((field) => `\`${field}\``)
+        .join(', ');
+    const noun = unsupportedFields.length === 1 ? 'field is' : 'fields are';
+    return `${base} Note: this profile's ${names} ${noun} not recognized by the current operating configuration and will not be reused as-is — run \`planr operate profiles migrate inspect\` to review.`;
+}
 const question = (questionId, type, label, explanation, options = {}) => ({
     kind: 'guided-question',
     schemaVersion: '1.0.0',
@@ -117,12 +134,14 @@ export function operatingInitQuestionRegistry(context) {
             required: true,
             // Detect-don't-ask: when a `.planr/operate-profile.json` already names a
             // profile, surface it as the confirmable suggestion so the operator does
-            // not have to re-pick it; otherwise fall back to the SaaS default.
+            // not have to re-pick it; otherwise fall back to the SaaS default. When
+            // that file carries values the CLI would reject, the suggestion names
+            // the unsupported fields (FR10 / T-009) instead of hiding them.
             ...(context.existingProfileId
                 ? {
                     valueSemantics: 'suggestion',
                     suggestedValue: context.existingProfileId,
-                    suggestionReason: 'Suggested from the existing .planr/operate-profile.json; confirm or choose another.',
+                    suggestionReason: existingProfileSuggestionReason(context.existingProfileUnsupportedFields),
                 }
                 : {
                     valueSemantics: 'default',

package/dist/services/operate/interaction/question-registry.js.map

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

package/dist/services/operate/lifecycle-driver.d.ts

@@ -0,0 +1,309 @@
+import { type MissionDispatchBudgetSignal } from './mission-dispatch.js';
+import { type OperatingRoleId } from './types.js';
+/**
+ * Deterministic advisor lifecycle driver (FR3, SPEC-005 T-003).
+ *
+ * SPEC-005 lost a full credentialed run because lifecycle correctness — result
+ * transport, per-role completion handling, incremental recording, lease timing
+ * and renewal, retry/timeout behaviour, and Chair readiness — lived in prose
+ * delegated to the orchestrating language model. This module moves that
+ * bookkeeping into an explicit, externally observable per-role state machine.
+ *
+ * It owns ONLY bookkeeping around the durable primitives T-002 already built. Its
+ * only side-effecting calls are into T-002's `operateAdapterLifecycle`
+ * `record`/`heartbeat` actions, injected here as `recordRole`/`heartbeat`. It
+ * never re-implements lease or session persistence, and it never dispatches an
+ * agent: runtime skills still perform the actual native-agent dispatch (passed in
+ * as the `dispatch` callback), and the driver orchestrates the state around it —
+ * bounded concurrency, per-role retry budgets, timeouts, automatic heartbeats,
+ * cancellation, resume, and the `chairReady()` predicate.
+ *
+ * Lifecycle: `pending → running → returned → validating → recorded`, with terminal
+ * alternatives `not_evaluated`, `failed`, `cancelled`. A stalled role retries
+ * independently on its own budget; after its budget is exhausted the cycle
+ * continues with an explicit `not_evaluated` role and a governed gap — never
+ * blocking or cancelling siblings — unless that role is structurally required, in
+ * which case it terminates `failed`.
+ */
+/**
+ * The eight per-role lifecycle states. `advance` only ever moves a role between
+ * these via a validated transition, so a role's state is ALWAYS exactly one of
+ * them — there is no representable "unknown" or half-transitioned state.
+ */
+export type AdvisorLifecycleState = 'pending' | 'running' | 'returned' | 'validating' | 'recorded' | 'not_evaluated' | 'failed' | 'cancelled';
+/** The four terminal states; a role in any of them never transitions again. */
+export declare const ADVISOR_LIFECYCLE_TERMINAL_STATES: readonly ["recorded", "not_evaluated", "failed", "cancelled"];
+export type AdvisorLifecycleTerminalState = (typeof ADVISOR_LIFECYCLE_TERMINAL_STATES)[number];
+export declare function isAdvisorLifecycleTerminal(state: AdvisorLifecycleState): state is AdvisorLifecycleTerminalState;
+/**
+ * A lifecycle transition event. The three terminal events (`fail`, `cancel`,
+ * `not-evaluated`) carry a required `reason`, which becomes the role's
+ * `statusReason` — the governed record that justifies the outcome. A role is
+ * never rendered `not_evaluated`/`failed` without one (FR5).
+ */
+export type AdvisorLifecycleEvent = {
+    kind: 'dispatch';
+} | {
+    kind: 'return';
+} | {
+    kind: 'validate';
+} | {
+    kind: 'record';
+} | {
+    kind: 'retry';
+    reason: string;
+} | {
+    kind: 'fail';
+    reason: string;
+} | {
+    kind: 'cancel';
+    reason: string;
+} | {
+    kind: 'not-evaluated';
+    reason: string;
+};
+/**
+ * A governed gap emitted when a structurally-optional role terminates without a
+ * recorded analysis. It is NOT the full persisted `operating-data-gap` protocol
+ * artifact (that is minted by the record/finalize path); it is the driver's
+ * explicit, machine-readable statement that this perspective is missing and WHY,
+ * so the Chair surfaces it as a gap rather than inventing the role's conclusions
+ * (FR13) and `status`/`report` never render the role quietly (FR5).
+ */
+export interface AdvisorGovernedGap {
+    roleId: OperatingRoleId;
+    outcome: 'not_evaluated' | 'failed';
+    reason: string;
+}
+/** A single prepared advisor role and its per-role policy. */
+export interface AdvisorRolePlan {
+    roleId: OperatingRoleId;
+    /**
+     * A structurally-required role's missing analysis is a hard gap the Chair
+     * cannot synthesize around: on retry-budget exhaustion it terminates `failed`
+     * (blocking chair readiness) rather than `not_evaluated`. A structurally
+     * OPTIONAL role terminates `not_evaluated` with a governed gap and the cycle
+     * continues. Defaults to optional.
+     */
+    structurallyRequired?: boolean;
+    /**
+     * Max INDEPENDENT re-dispatches after the first attempt. Exhausting it yields a
+     * terminal `not_evaluated`/`failed`. Defaults to the driver's `retryBudget`.
+     */
+    retryBudget?: number;
+    /**
+     * Resume seeding (FR3): a role already recorded in a prior session starts
+     * terminal `recorded` and is never re-dispatched. `not_evaluated`/`failed`/
+     * `cancelled` seed the matching terminal.
+     */
+    initialState?: AdvisorLifecycleState;
+    /** The governed statusReason to seed alongside a terminal `initialState`. */
+    initialReason?: string;
+}
+/**
+ * The outcome of T-002's `record` action, projected to exactly what the driver
+ * needs. `recorded: true` with `notEvaluated` unset is a committed analysis;
+ * `notEvaluated: true` is T-002 committing a governed quiet/zero-grounding result
+ * (still durable, but a not-evaluated outcome). `leaseExpiresAtMs` carries the
+ * lease forward from the record's refresh so the heartbeat scheduler stays in
+ * step with the freshest window.
+ */
+export interface AdvisorRecordOutcome {
+    recorded: boolean;
+    notEvaluated?: boolean;
+    statusReason?: string;
+    leaseExpiresAtMs?: number;
+}
+/** The refreshed lease window returned by T-002's `heartbeat` action. */
+export interface AdvisorLeaseSnapshot {
+    leaseExpiresAtMs: number;
+}
+/** Injected timer handle; opaque so a test harness can queue and fire deterministically. */
+export type LifecycleTimerHandle = unknown;
+export interface AdvisorLifecycleDriverOptions {
+    roles: readonly AdvisorRolePlan[];
+    /**
+     * Side-effecting: wraps `operateAdapterLifecycle({ action: 'record', ... })`.
+     * The ONLY per-role side effect the driver performs — it never validates,
+     * persists, or leases itself.
+     */
+    recordRole: (input: {
+        roleId: OperatingRoleId;
+        output: unknown;
+    }) => Promise<AdvisorRecordOutcome>;
+    /**
+     * Side-effecting: wraps `operateAdapterLifecycle({ action: 'heartbeat', ... })`.
+     * Called by the heartbeat scheduler to renew the cycle lease independent of any
+     * role completing. Absent means heartbeats are disabled.
+     */
+    heartbeat?: () => Promise<AdvisorLeaseSnapshot>;
+    /** Injected clock (ms epoch). Defaults to `Date.now`. */
+    now?: () => number;
+    /** Injected timer scheduler. Defaults to `setTimeout`/`clearTimeout`. */
+    setTimer?: (fn: () => void, ms: number) => LifecycleTimerHandle;
+    clearTimer?: (handle: LifecycleTimerHandle) => void;
+    /** Current lease expiry (ms epoch); updated by every record/heartbeat outcome. */
+    leaseExpiresAtMs?: number;
+    /** Renew the lease when its remaining time drops to/below this. Defaults to 120_000ms. */
+    heartbeatLeadMs?: number;
+    /** Default per-role retry budget when a role plan omits its own. Defaults to 1. */
+    retryBudget?: number;
+    /** Bounded fan-out concurrency across dispatched roles. Absent/`<= 0` = unbounded. */
+    concurrency?: number;
+    /**
+     * Per-attempt dispatch timeout (ms). A dispatch that has not returned within it
+     * is treated as a stall (retried on budget, else terminal). Absent = no timeout.
+     */
+    roleTimeoutMs?: number;
+}
+/** An observability timeline entry recorded through the fan-out reporter. */
+export interface AdvisorLifecycleTimelineEntry {
+    roleId: OperatingRoleId;
+    event: 'dispatch' | 'return' | 'error';
+    at: number;
+}
+/** A per-role snapshot for `status`/`report` surfaces (FR5). */
+export interface AdvisorRoleSnapshot {
+    roleId: OperatingRoleId;
+    state: AdvisorLifecycleState;
+    attempts: number;
+    retriesUsed: number;
+    retryBudget: number;
+    structurallyRequired: boolean;
+    statusReason?: string;
+}
+/** The result of running the whole prepared board through the driver. */
+export interface AdvisorLifecycleRunSummary {
+    roles: AdvisorRoleSnapshot[];
+    recorded: OperatingRoleId[];
+    notEvaluated: OperatingRoleId[];
+    failed: OperatingRoleId[];
+    cancelled: OperatingRoleId[];
+    gaps: AdvisorGovernedGap[];
+    chairReady: boolean;
+    heartbeats: number;
+}
+/**
+ * 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 declare class AdvisorRoleStalledError extends Error {
+    constructor(message: string);
+}
+export declare class AdvisorLifecycleDriver {
+    private readonly roles;
+    private readonly order;
+    private readonly recordRole;
+    private readonly heartbeatFn?;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readonly heartbeatLeadMs;
+    private readonly concurrency?;
+    private readonly roleTimeoutMs?;
+    private leaseExpiresAtMs;
+    private heartbeatCount;
+    private readonly timeline;
+    private readonly gaps;
+    constructor(options: AdvisorLifecycleDriverOptions);
+    /** The current state of a prepared role. */
+    state(roleId: OperatingRoleId): AdvisorLifecycleState;
+    /** The governed statusReason recorded on a terminal `not_evaluated`/`failed`, if any. */
+    statusReason(roleId: OperatingRoleId): string | undefined;
+    /**
+     * 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: OperatingRoleId, event: AdvisorLifecycleEvent): AdvisorLifecycleState;
+    /** Whether the given role still has retry budget for another independent attempt. */
+    canRetry(roleId: OperatingRoleId): boolean;
+    /**
+     * 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: OperatingRoleId, reason: string): AdvisorLifecycleState;
+    /**
+     * 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).
+     */
+    executeRole(roleId: OperatingRoleId, dispatch: (signal: MissionDispatchBudgetSignal) => Promise<unknown>, signal: MissionDispatchBudgetSignal): Promise<AdvisorLifecycleState>;
+    /**
+     * 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.
+     */
+    run(input: {
+        parallel: boolean;
+        dispatch: (roleId: OperatingRoleId, signal: MissionDispatchBudgetSignal) => Promise<unknown>;
+        perRoleBudgetMs?: number;
+    }): Promise<AdvisorLifecycleRunSummary>;
+    /**
+     * 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(): boolean;
+    /**
+     * 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: number): () => void;
+    /** How many heartbeats the scheduler has issued so far (observability/tests). */
+    heartbeatsIssued(): number;
+    /** The current lease expiry (ms epoch) the driver is tracking. */
+    leaseExpiry(): number;
+    /** Governed gaps for roles that terminated without a recorded analysis (FR13). */
+    governedGaps(): AdvisorGovernedGap[];
+    /** The observability timeline recorded through the fan-out reporter. */
+    dispatchTimeline(): AdvisorLifecycleTimelineEntry[];
+    /** A per-role snapshot in prepared order for `status`/`report` (FR5). */
+    snapshot(): AdvisorRoleSnapshot[];
+    /**
+     * 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: string): void;
+    private summary;
+    private allRolesTerminal;
+    private recordTimeline;
+    private updateLease;
+    private require;
+    /**
+     * 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.
+     */
+    private withTimeout;
+}
+//# sourceMappingURL=lifecycle-driver.d.ts.map

package/dist/services/operate/lifecycle-driver.d.ts.map

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