@telora/daemon 0.19.47 → 0.19.82

package/dist/focus-stage-lifecycle/review-convergence.js

@@ -0,0 +1,235 @@
+/**
+ * Focus review-convergence transitions (extracted from focus-stage-lifecycle).
+ *
+ * Owns the two review-axis daemon-side transitions:
+ *   verify  -> review     (Issue 4: auto-enter review on verify-stage entry)
+ *   review  -> close_loop (Issue 2 + 3: state-based convergence / nonconvergent
+ *                          escalation)
+ *
+ * Plus the pure helpers (`hasReviewConverged`, `getReviewIterationCap`,
+ * `hasInFlightRemediations`) these transitions rely on.
+ *
+ * @module focus-stage-lifecycle/review-convergence
+ */
+import { getLatestCompletedFocusReview as defaultGetLatestCompletedFocusReview, getInFlightRemediationCount as defaultGetInFlightRemediationCount, getFocusReviewIterationCount as defaultGetFocusReviewIterationCount, updateFocusStage as defaultUpdateFocusStage, } from '../queries/focuses.js';
+import { createEscalation as defaultCreateEscalation } from '../queries/issues.js';
+import { ESCALATION_REASONS, ESCALATION_KINDS, ESCALATION_DISPOSITIONS, FOCUS_STAGE, } from '@telora/daemon-core';
+import { emitLoopTrigger } from '../loops/index.js';
+import { isReviewEnabled } from '../pipeline-config.js';
+// ── Constants ─────────────────────────────────────────────────────
+/**
+ * Default cap on review iterations before the daemon files a
+ * `review_nonconvergent` escalation and pauses the focus.
+ *
+ * Configurable per focus via `pipeline_config.review.maxIterations`.
+ */
+export const DEFAULT_REVIEW_MAX_ITERATIONS = 3;
+// ── Pure helpers (Issue 2 + Issue 3) ──────────────────────────────
+/**
+ * Decide whether a focus has converged out of review. Convergence is
+ * deterministic and state-based:
+ *
+ *   - If there are no in-flight remediation deliveries created during/after
+ *     the latest review pass, the focus has converged.
+ *
+ * Pure function: takes the in-flight count and returns the decision.
+ * Exported so tests can drive it with synthetic counts.
+ */
+export function hasReviewConverged(inFlightRemediationCount) {
+    return inFlightRemediationCount <= 0;
+}
+/**
+ * Compute the configured review iteration cap for a focus. Pulls
+ * `pipeline_config.review.maxIterations` and falls back to
+ * `DEFAULT_REVIEW_MAX_ITERATIONS` when unset or non-positive.
+ *
+ * Exported for unit testing.
+ */
+export function getReviewIterationCap(pipelineConfig) {
+    const raw = pipelineConfig?.review?.maxIterations;
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw <= 0) {
+        return DEFAULT_REVIEW_MAX_ITERATIONS;
+    }
+    return Math.floor(raw);
+}
+// ── Convergence check (Issue 2) ───────────────────────────────────
+/**
+ * Returns true when the focus has any in-flight remediation deliveries
+ * created during/after the latest review pass.
+ *
+ * "Latest review pass" is the `started_at` of the most recent focus_reviews
+ * row; when no review has run yet, this returns false (no remediation
+ * deliveries can exist before a review pass).
+ *
+ * In-flight means execution_status is NOT one of done/cancelled/verify.
+ *
+ * Exported for unit testing the convergence query independently of the
+ * surrounding transition logic.
+ */
+export async function hasInFlightRemediations(focusId, latestReviewPassTimestamp, deps = { getInFlightRemediationCount: defaultGetInFlightRemediationCount }) {
+    if (!latestReviewPassTimestamp) {
+        return false;
+    }
+    const count = await deps.getInFlightRemediationCount(focusId, latestReviewPassTimestamp);
+    return count > 0;
+}
+const defaultVerifyToReviewDeps = {
+    updateFocusStage: defaultUpdateFocusStage,
+    emitLoopTrigger,
+};
+/**
+ * When a focus's stage is `verify` and auto-review is enabled, advance it to
+ * `review`. Auto-review is default-on (`isReviewEnabled`): only an explicit
+ * `pipeline_config.review.enabled === false` keeps the focus at `verify` until
+ * a human signals review. A focus with no stored review key auto-advances.
+ *
+ * Returns true when an advance was performed.
+ */
+export async function advanceVerifyToReviewIfEnabled(focus, deps = defaultVerifyToReviewDeps) {
+    if (focus.stage !== FOCUS_STAGE.VERIFY)
+        return false;
+    // Default-on: only an explicit review.enabled === false keeps the focus at
+    // verify. Missing / undefined review reads as enabled (mirrors isCiEnabled).
+    if (!isReviewEnabled(focus.pipelineConfig))
+        return false;
+    try {
+        await deps.updateFocusStage(focus.focusId, 'review');
+        console.log(`[focus-stage-lifecycle] Focus "${focus.focusName}" stage verify -> review ` +
+            `(auto: pipeline_config.review.enabled)`);
+        deps.emitLoopTrigger({
+            type: 'focus_status_changed',
+            focusId: focus.focusId,
+            detail: 'stage:verify->review',
+        });
+        return true;
+    }
+    catch (err) {
+        console.warn(`[focus-stage-lifecycle] Failed to advance "${focus.focusName}" ` +
+            `verify -> review: ${err.message}`);
+        return false;
+    }
+}
+const defaultReviewConvergeDeps = {
+    getLatestCompletedFocusReview: defaultGetLatestCompletedFocusReview,
+    getInFlightRemediationCount: defaultGetInFlightRemediationCount,
+    getFocusReviewIterationCount: defaultGetFocusReviewIterationCount,
+    updateFocusStage: defaultUpdateFocusStage,
+    createEscalation: defaultCreateEscalation,
+    emitLoopTrigger,
+};
+/**
+ * Evaluate the review -> close_loop transition for a focus and apply the
+ * appropriate action. Returns a structured outcome so callers can log /
+ * test the decision path.
+ *
+ * Logic:
+ *   1. If stage is not `review`, do nothing.
+ *   2. If the review iteration count is >= the cap, file a
+ *      `review_nonconvergent` escalation (idempotent best-effort) and
+ *      LEAVE the focus stage at `review`. The focus is paused until a
+ *      human intervenes.
+ *   3. Otherwise, check in-flight remediations against the latest review
+ *      pass. If zero, advance stage `review -> close_loop`.
+ *   4. Otherwise, do nothing -- remediations are still in flight.
+ *
+ * Exported with injectable deps for unit testing.
+ */
+export async function advanceReviewToCloseLoopIfConverged(focus, deps = defaultReviewConvergeDeps) {
+    if (focus.stage !== FOCUS_STAGE.REVIEW) {
+        return { kind: 'no_action', reason: 'stage_not_review' };
+    }
+    const cap = getReviewIterationCap(focus.pipelineConfig);
+    let iterations = 0;
+    try {
+        iterations = await deps.getFocusReviewIterationCount(focus.focusId);
+    }
+    catch (err) {
+        console.warn(`[focus-stage-lifecycle] Failed to read review iteration count for ` +
+            `"${focus.focusName}": ${err.message}`);
+        // On read failure, fall through to the convergence check rather than
+        // false-escalating; if iterations were actually high the next tick
+        // will catch it.
+    }
+    if (iterations >= cap) {
+        // N-iteration cap exceeded -- file an escalation and leave the focus
+        // at review. The escalation is best-effort; downstream dedup keeps it
+        // from spamming via the agent_escalations idx_kind_status partial index
+        // (status in ('pending', 'in_review')).
+        try {
+            await deps.createEscalation({
+                organizationId: focus.organizationId,
+                sessionId: '',
+                issueId: null,
+                reasonType: ESCALATION_REASONS.DECISION_NEEDED,
+                // The intent owner must decide: descope, extend the cap, or close.
+                disposition: ESCALATION_DISPOSITIONS.NEEDS_INTENT,
+                anchor: { focusId: focus.focusId },
+                description: `Focus "${focus.focusName}" has not converged after ${iterations} ` +
+                    `review iteration(s) (cap: ${cap}). The review self-loop has been ` +
+                    `paused; a human must decide whether to descope remaining gaps, ` +
+                    `extend the cap via pipeline_config.review.maxIterations, or close ` +
+                    `the focus.`,
+                escalationKind: ESCALATION_KINDS.REVIEW_NONCONVERGENT,
+                // Evidence only -- focus provenance lives on the columns via the anchor.
+                metadata: {
+                    iterations,
+                    cap,
+                },
+            });
+            console.warn(`[focus-stage-lifecycle] review_nonconvergent escalation filed for ` +
+                `"${focus.focusName}" (iterations=${iterations}, cap=${cap}); focus ` +
+                `remains at stage=review.`);
+        }
+        catch (err) {
+            console.warn(`[focus-stage-lifecycle] Failed to file review_nonconvergent ` +
+                `escalation for "${focus.focusName}": ${err.message}`);
+        }
+        return { kind: 'nonconvergent', iterations, cap };
+    }
+    // Look up the latest completed review's started_at. If no review has
+    // completed yet, there are no remediations created against it; treat as
+    // "not yet converged" rather than "converged on zero" -- the agent must
+    // produce a review before we can claim convergence.
+    let latestReviewStartedAt = null;
+    try {
+        const latest = await deps.getLatestCompletedFocusReview(focus.focusId);
+        latestReviewStartedAt = latest?.startedAt ?? null;
+    }
+    catch (err) {
+        console.warn(`[focus-stage-lifecycle] Failed to read latest focus_review for ` +
+            `"${focus.focusName}": ${err.message}`);
+        return { kind: 'no_action', reason: 'review_read_failed' };
+    }
+    if (!latestReviewStartedAt) {
+        return { kind: 'no_action', reason: 'no_completed_review_yet' };
+    }
+    let inFlightCount = 0;
+    try {
+        inFlightCount = await deps.getInFlightRemediationCount(focus.focusId, latestReviewStartedAt);
+    }
+    catch (err) {
+        console.warn(`[focus-stage-lifecycle] Failed to count in-flight remediations for ` +
+            `"${focus.focusName}": ${err.message}`);
+        return { kind: 'no_action', reason: 'remediation_query_failed' };
+    }
+    if (!hasReviewConverged(inFlightCount)) {
+        return { kind: 'no_action', reason: 'remediations_in_flight' };
+    }
+    try {
+        await deps.updateFocusStage(focus.focusId, 'close_loop');
+        console.log(`[focus-stage-lifecycle] Focus "${focus.focusName}" stage review -> ` +
+            `close_loop (converged after ${iterations} iteration(s))`);
+        deps.emitLoopTrigger({
+            type: 'focus_status_changed',
+            focusId: focus.focusId,
+            detail: 'stage:review->close_loop',
+        });
+        return { kind: 'converged', from: 'review', to: 'close_loop' };
+    }
+    catch (err) {
+        console.warn(`[focus-stage-lifecycle] Failed to advance "${focus.focusName}" ` +
+            `review -> close_loop: ${err.message}`);
+        return { kind: 'no_action', reason: 'stage_write_failed' };
+    }
+}
+//# sourceMappingURL=review-convergence.js.map

package/dist/focus-stage-lifecycle/review-convergence.js.map

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

package/dist/focus-stage-lifecycle/wedge-watchdog.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Planning-wedge watchdog + zero-actionable log (extracted from
+ * focus-stage-lifecycle).
+ *
+ * Owns the daemon-side mirror of the server ready-focus rank-walk
+ * (`classifyFocusActionability`), the per-focus wedge watchdog state, and the
+ * per-tick wedge evaluation (`evaluateFocusWedge`) that both logs a
+ * zero-actionable focus (D3) and escalates a persistent wedge (D2).
+ *
+ * @module focus-stage-lifecycle/wedge-watchdog
+ */
+import { getFocusDeliveries as defaultGetFocusDeliveries } from '../queries/focuses.js';
+import { createEscalation as defaultCreateEscalation, hasOpenWedgedFocusEscalation as defaultHasOpenWedgedFocusEscalation } from '../queries/issues.js';
+/** A delivery as seen by the actionability classifier (rank-ascending walk). */
+export interface WedgeBlockingDelivery {
+    id: string;
+    name: string;
+    status: string;
+    priorityRank: number;
+    /**
+     * The blocking delivery's last-updated timestamp (ISO), or null. Used by the
+     * watchdog as a RESTART-DURABLE proxy for how long the row has sat held -- so a
+     * daemon restart cannot reset the wedge clock (review finding, delivery 66c7d4d8).
+     */
+    updatedAt: string | null;
+}
+/** Pure classification of a focus's deliveries against the ready-focus walk. */
+export interface FocusActionability {
+    totalCount: number;
+    /** True iff the daemon would surface an actionable delivery (first non-terminal in rank order is actionable). */
+    surfacesActionable: boolean;
+    /** The first non-terminal, non-actionable delivery in rank order (planning/draft/paused), or null. */
+    blockingDelivery: WedgeBlockingDelivery | null;
+    /** True iff every delivery is terminal-ish (done/cancelled/verify) or there are none. */
+    allTerminal: boolean;
+}
+/**
+ * Replicate the server-side ready-focus rank-walk to decide whether a focus
+ * surfaces actionable work, and if not, which delivery blocks it.
+ *
+ * The walk (rank-ascending, matching the edge): skip terminal-ish deliveries;
+ * the FIRST non-terminal delivery decides -- actionable => the focus surfaces
+ * (not wedged); non-actionable (planning/draft/paused) => that delivery blocks
+ * the focus and everything behind it. This is why a low-rank 'planning' delivery
+ * wedges a focus even when a higher-rank 'queued' delivery exists.
+ *
+ * Pure and exported for unit testing. Expects deliveries pre-sorted by
+ * priorityRank ascending (as daemon_get_focus_deliveries returns them); it does
+ * not re-sort, mirroring the edge which relies on the query's ORDER BY.
+ */
+export declare function classifyFocusActionability(deliveries: ReadonlyArray<{
+    id: string;
+    name: string;
+    executionStatus: string | null;
+    priorityRank: number;
+    updatedAt?: string | null;
+}>): FocusActionability;
+/**
+ * Evict watchdog state for any focus NOT in `liveFocusIds`. A focus that goes
+ * terminal (complete/cancelled) or whose product is unclaimed simply stops being
+ * returned by getActiveFocuses, so `evaluateFocusWedge` never runs again to clear
+ * its entry -- leaving a slow unbounded leak keyed by focusId (review finding,
+ * delivery 66c7d4d8). The poll loop calls this once per run with the set of
+ * focusIds it actually saw, bounding both maps to currently-active focuses.
+ */
+export declare function pruneWedgeWatchdogState(liveFocusIds: ReadonlySet<string>): void;
+/** Test seam: reset all watchdog state between cases. */
+export declare function __resetWedgeWatchdogState(): void;
+/**
+ * Dependencies for `evaluateFocusWedge`. Defaults reach the real query modules
+ * and the canonical clock/threshold; tests inject stubs + a synthetic clock.
+ */
+export interface WedgeWatchdogDeps {
+    getFocusDeliveries: typeof defaultGetFocusDeliveries;
+    hasOpenWedgedFocusEscalation: typeof defaultHasOpenWedgedFocusEscalation;
+    createEscalation: typeof defaultCreateEscalation;
+    /** Kickoff-window discriminator: a running scoping team means "not a wedge". */
+    hasActiveTeam: (focusId: string) => boolean;
+    now: () => number;
+    thresholdMs: number;
+}
+/** Structured outcome of one wedge evaluation, for logging / tests. */
+export type WedgeOutcome = {
+    kind: 'skipped';
+    reason: string;
+} | {
+    kind: 'surfaces_actionable';
+} | {
+    kind: 'zero_actionable';
+    escalated: boolean;
+    wedged: boolean;
+    blockingStatus: string;
+};
+/**
+ * Per-focus, per-tick evaluation of the planning-wedge condition. Does two
+ * things off ONE actionability classification:
+ *
+ *   D3 (log): when an active, role-assigned focus surfaces zero actionable
+ *     deliveries, name the rank-0 blocking delivery + its state in the daemon
+ *     log -- so a wedge is visible in ~/.telora/daemon.log, not only the
+ *     edge-function log. Dampened to once per focus per state change.
+ *
+ *   D2 (escalate): when that focus is ALSO writable, the block is a WEDGE
+ *     (planning/draft, not a human pause), NO team is running, and the wedge
+ *     persists past the threshold, file a deduped wedged_focus escalation --
+ *     defense-in-depth for wedge classes the rank-respecting release (D1) does
+ *     not resolve (e.g. a 'draft' block, which D1 does not sweep).
+ *
+ * Runs AFTER the D1 release in the poll loop, so a focus D1 just unwedged is
+ * already surfacing actionable work here and neither logs nor escalates.
+ *
+ * Gating (escalation): status active + assigned_agent_role_id set + read_only
+ * false + wedge-held block + NO active team. The "no active team" check replaces
+ * the old (broken) isPostPlanning(stage) gate -- the stage column is stale and
+ * never reaches post-planning, so that gate never fired for the founding wedge
+ * (review finding, delivery 66c7d4d8). It is the same kickoff-window discriminator
+ * D1 uses: a running scoping team is shaping/releasing deliveries (don't escalate);
+ * no team means nothing can make progress (the rank-0 block stops the ready
+ * selector from spawning one) -- a true wedge. Zero-delivery focuses (planning
+ * teams) and all-paused focuses (human hold) are excluded by the classifier (no
+ * wedge-held blocking delivery).
+ */
+export declare function evaluateFocusWedge(focus: {
+    focusId: string;
+    focusName: string;
+    organizationId: string;
+    status: string;
+    assignedAgentRoleId: string | null;
+    readOnly?: boolean;
+    /** Display-only (logging); NOT used for gating -- the stage column is stale. */
+    stage?: string | null;
+}, deps?: WedgeWatchdogDeps): Promise<WedgeOutcome>;
+//# sourceMappingURL=wedge-watchdog.d.ts.map

package/dist/focus-stage-lifecycle/wedge-watchdog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wedge-watchdog.d.ts","sourceRoot":"","sources":["../../src/focus-stage-lifecycle/wedge-watchdog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,kBAAkB,IAAI,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACxF,OAAO,EACL,gBAAgB,IAAI,uBAAuB,EAC3C,4BAA4B,IAAI,mCAAmC,EAEpE,MAAM,sBAAsB,CAAC;AA0D9B,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,iHAAiH;IACjH,kBAAkB,EAAE,OAAO,CAAC;IAC5B,sGAAsG;IACtG,gBAAgB,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC/C,yFAAyF;IACzF,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,aAAa,CAAC;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC,GACD,kBAAkB,CAwBpB;AAsED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAE/E;AAED,yDAAyD;AACzD,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAeD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,kBAAkB,EAAE,OAAO,yBAAyB,CAAC;IACrD,4BAA4B,EAAE,OAAO,mCAAmC,CAAC;IACzE,gBAAgB,EAAE,OAAO,uBAAuB,CAAC;IACjD,gFAAgF;IAChF,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAaD,uEAAuE;AACvE,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,qBAAqB,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE;IACL,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,EACD,IAAI,GAAE,iBAA8C,GACnD,OAAO,CAAC,YAAY,CAAC,CAuJvB"}