@telora/daemon 0.21.26 → 0.21.82

package/dist/delivery/operator-hold.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Operator-hold gate: a delivery carrying an unresolved operator-blocked
+ * escalation must not reach done.
+ *
+ * The verify->done gate historically had no vocabulary for "an operator is
+ * blocked ON this delivery". The observed failure (escalation 20f5c2fd): a
+ * delivery whose OWN escalation said its host work was NEVER EXECUTED still
+ * auto-approved to done, because every gate the system had -- all_issues_done, a
+ * clean review -- was satisfied. This module gives every verify->done write path
+ * that missing vocabulary: an open escalation of disposition needs_operator /
+ * external_wait, anchored to the delivery, holds it in verify.
+ *
+ * Sibling of the shortfall hold (completion/review-exit-shortfall.ts) -- the same
+ * shape: resolve the hold async, and gate the write DOWNSTREAM of the reconciler's
+ * target decision (the reconciler models neither hold; feeding it one would emit
+ * spurious [reconciler-divergence] logs). Two differences from the shortfall hold:
+ * it is per-DELIVERY (escalations anchor to a delivery, not a focus), and its
+ * failure direction is the inverse -- see resolveOperatorHold.
+ *
+ * @module operator-hold
+ */
+import type { findOpenOperatorHoldForDelivery, OperatorHoldEscalation } from '../queries/issues.js';
+import type { updateDeliveryStatus } from '../queries/deliveries.js';
+/** The resolved hold state for one delivery. */
+export interface OperatorHold {
+    /** True when the delivery is held: an open operator escalation OR a read failure. */
+    held: boolean;
+    /** The blocking escalation when known; null on a fail-closed read failure. */
+    escalation: OperatorHoldEscalation | null;
+    /** The read failed, so we hold WITHOUT knowing which escalation (fail-closed). */
+    readFailed: boolean;
+}
+/** The slice of deps this gate needs (structural, so no import cycle). */
+export interface OperatorHoldDeps {
+    findOpenOperatorHoldForDelivery: typeof findOpenOperatorHoldForDelivery;
+    updateDeliveryStatus: typeof updateDeliveryStatus;
+}
+/**
+ * Resolve whether a delivery is operator-held.
+ *
+ * FAILS CLOSED: on lookup error this returns `held: true` with `readFailed: true`.
+ * This is the ONE escalation lookup in the daemon that fails closed rather than
+ * open. The other escalation lookups (dedup / auto-close) fail open because a
+ * spurious park is cheaper than a missed dedup. Here the calculus inverts: a
+ * missed hold lets an operator-blocked delivery reach done -- the exact
+ * silent-bar-lowering this gate exists to stop -- so the safe direction is to
+ * hold. The cost of a false hold is one cycle; the cost of a false release is
+ * the failure this whole focus is about.
+ */
+export declare function resolveOperatorHold(deps: OperatorHoldDeps, deliveryId: string, focusId?: string): Promise<OperatorHold>;
+/**
+ * Surface an operator hold on the delivery row (gate_state) so the board can
+ * answer "why is this stuck" WITHOUT a second escalation being filed.
+ *
+ * Re-asserts `verify` rather than changing status, exactly like
+ * writeShortfallGateState: gate_state is written through
+ * daemon_update_delivery_status, which requires an executionStatus, so this is
+ * the "write the gate, leave the status where it is" shape. Best-effort: the hold
+ * is already decided by the caller; failing to render its reason must not turn a
+ * held delivery into a crashed advance path (a silent hold is bad; a crashed
+ * handler is worse).
+ */
+export declare function writeOperatorHoldGateState(deps: OperatorHoldDeps, deliveryId: string, hold: OperatorHold): Promise<void>;
+/** Human-readable hold reason for an exit/advance log line. */
+export declare function describeOperatorHold(hold: OperatorHold): string;
+//# sourceMappingURL=operator-hold.d.ts.map

package/dist/delivery/operator-hold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-hold.d.ts","sourceRoot":"","sources":["../../src/delivery/operator-hold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,+BAA+B,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACpG,OAAO,KAAK,EAAqB,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAaxF,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,IAAI,EAAE,OAAO,CAAC;IACd,8EAA8E;IAC9E,UAAU,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC1C,kFAAkF;IAClF,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B,EAAE,OAAO,+BAA+B,CAAC;IACxE,oBAAoB,EAAE,OAAO,oBAAoB,CAAC;CACnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,CAWvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAO/D"}

package/dist/delivery/operator-hold.js

@@ -0,0 +1,99 @@
+/**
+ * Operator-hold gate: a delivery carrying an unresolved operator-blocked
+ * escalation must not reach done.
+ *
+ * The verify->done gate historically had no vocabulary for "an operator is
+ * blocked ON this delivery". The observed failure (escalation 20f5c2fd): a
+ * delivery whose OWN escalation said its host work was NEVER EXECUTED still
+ * auto-approved to done, because every gate the system had -- all_issues_done, a
+ * clean review -- was satisfied. This module gives every verify->done write path
+ * that missing vocabulary: an open escalation of disposition needs_operator /
+ * external_wait, anchored to the delivery, holds it in verify.
+ *
+ * Sibling of the shortfall hold (completion/review-exit-shortfall.ts) -- the same
+ * shape: resolve the hold async, and gate the write DOWNSTREAM of the reconciler's
+ * target decision (the reconciler models neither hold; feeding it one would emit
+ * spurious [reconciler-divergence] logs). Two differences from the shortfall hold:
+ * it is per-DELIVERY (escalations anchor to a delivery, not a focus), and its
+ * failure direction is the inverse -- see resolveOperatorHold.
+ *
+ * @module operator-hold
+ */
+import { createLogger } from '../shell/log.js';
+const log = createLogger({ module: 'operator-hold' });
+// The `verify` status re-asserted by the hold write. A daemon-local literal (not
+// DELIVERY_STATUS.VERIFY from @telora/daemon-core) on purpose: this module is
+// pulled into listener tests that use the node:test module-mock loader, under
+// which a bare `@telora/*` VALUE import mis-resolves. Same daemon-local-literal
+// rule as OPERATOR_HOLD_DISPOSITIONS in queries/issues.ts. The DB CHECK on
+// execution_status is the real constraint; this string mirrors DELIVERY_STATUS.VERIFY.
+const VERIFY_STATUS = 'verify';
+/**
+ * Resolve whether a delivery is operator-held.
+ *
+ * FAILS CLOSED: on lookup error this returns `held: true` with `readFailed: true`.
+ * This is the ONE escalation lookup in the daemon that fails closed rather than
+ * open. The other escalation lookups (dedup / auto-close) fail open because a
+ * spurious park is cheaper than a missed dedup. Here the calculus inverts: a
+ * missed hold lets an operator-blocked delivery reach done -- the exact
+ * silent-bar-lowering this gate exists to stop -- so the safe direction is to
+ * hold. The cost of a false hold is one cycle; the cost of a false release is
+ * the failure this whole focus is about.
+ */
+export async function resolveOperatorHold(deps, deliveryId, focusId) {
+    try {
+        const escalation = await deps.findOpenOperatorHoldForDelivery(deliveryId, focusId);
+        return { held: escalation !== null, escalation, readFailed: false };
+    }
+    catch (err) {
+        log.warn(`[operator-hold] findOpenOperatorHoldForDelivery failed for delivery ${deliveryId} -- ` +
+            `holding verify->done (fail-closed): ${err.message}`);
+        return { held: true, escalation: null, readFailed: true };
+    }
+}
+/**
+ * Surface an operator hold on the delivery row (gate_state) so the board can
+ * answer "why is this stuck" WITHOUT a second escalation being filed.
+ *
+ * Re-asserts `verify` rather than changing status, exactly like
+ * writeShortfallGateState: gate_state is written through
+ * daemon_update_delivery_status, which requires an executionStatus, so this is
+ * the "write the gate, leave the status where it is" shape. Best-effort: the hold
+ * is already decided by the caller; failing to render its reason must not turn a
+ * held delivery into a crashed advance path (a silent hold is bad; a crashed
+ * handler is worse).
+ */
+export async function writeOperatorHoldGateState(deps, deliveryId, hold) {
+    const gateState = {
+        // No guard blocked -- `blocking` is guard-verdict data and must not be
+        // fabricated. The hold lives in its own field, like shortfallProposalIds.
+        blocking: [],
+        warnings: [],
+        evaluatedAt: new Date().toISOString(),
+        operatorHold: hold.escalation
+            ? {
+                escalationId: hold.escalation.id,
+                escalationKind: hold.escalation.escalationKind,
+                disposition: hold.escalation.disposition,
+            }
+            : { escalationId: null, escalationKind: null, disposition: null, readFailed: true },
+    };
+    try {
+        await deps.updateDeliveryStatus(deliveryId, VERIFY_STATUS, undefined, gateState, undefined, undefined);
+    }
+    catch (err) {
+        log.warn(`[operator-hold] failed to write operator-hold gate_state for delivery ${deliveryId} ` +
+            `(hold still applies, just unexplained on the card): ${err.message}`);
+    }
+}
+/** Human-readable hold reason for an exit/advance log line. */
+export function describeOperatorHold(hold) {
+    if (hold.readFailed)
+        return 'operator-hold read failed (fail-closed)';
+    if (hold.escalation) {
+        return `open ${hold.escalation.disposition} escalation ${hold.escalation.id}` +
+            (hold.escalation.escalationKind ? ` (${hold.escalation.escalationKind})` : '');
+    }
+    return 'not held';
+}
+//# sourceMappingURL=operator-hold.js.map

package/dist/delivery/operator-hold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-hold.js","sourceRoot":"","sources":["../../src/delivery/operator-hold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,GAAG,GAAG,YAAY,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;AAEtD,iFAAiF;AACjF,8EAA8E;AAC9E,8EAA8E;AAC9E,gFAAgF;AAChF,2EAA2E;AAC3E,uFAAuF;AACvF,MAAM,aAAa,GAAG,QAAQ,CAAC;AAkB/B;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAAsB,EACtB,UAAkB,EAClB,OAAgB;IAEhB,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,+BAA+B,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACnF,OAAO,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACtE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,IAAI,CACN,uEAAuE,UAAU,MAAM;YACvF,uCAAwC,GAAa,CAAC,OAAO,EAAE,CAChE,CAAC;QACF,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC5D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,IAAsB,EACtB,UAAkB,EAClB,IAAkB;IAElB,MAAM,SAAS,GAAsB;QACnC,uEAAuE;QACvE,0EAA0E;QAC1E,QAAQ,EAAE,EAAE;QACZ,QAAQ,EAAE,EAAE;QACZ,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrC,YAAY,EAAE,IAAI,CAAC,UAAU;YAC3B,CAAC,CAAC;gBACE,YAAY,EAAE,IAAI,CAAC,UAAU,CAAC,EAAE;gBAChC,cAAc,EAAE,IAAI,CAAC,UAAU,CAAC,cAAc;gBAC9C,WAAW,EAAE,IAAI,CAAC,UAAU,CAAC,WAAW;aACzC;YACH,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE;KACtF,CAAC;IACF,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,oBAAoB,CAC7B,UAAU,EACV,aAAa,EACb,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,CACV,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,IAAI,CACN,yEAAyE,UAAU,GAAG;YACtF,uDAAwD,GAAa,CAAC,OAAO,EAAE,CAChF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,oBAAoB,CAAC,IAAkB;IACrD,IAAI,IAAI,CAAC,UAAU;QAAE,OAAO,yCAAyC,CAAC;IACtE,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,OAAO,QAAQ,IAAI,CAAC,UAAU,CAAC,WAAW,eAAe,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE;YAC3E,CAAC,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/directive/close-loop-dispatcher.d.ts

@@ -0,0 +1,325 @@
+/**
+ * Close-loop stage dispatcher.
+ *
+ * Handles focuses entering the `close_loop` workflow stage. Three asymmetric
+ * checks are delegated to the spawned bookkeeper team via the assembled
+ * directive; the dispatcher itself is responsible for the deterministic
+ * pre- and post-conditions:
+ *
+ *   - **Short-circuit on no anchors.** If the focus has no anchoring
+ *     injections, close_loop is a no-op: the dispatcher advances the focus
+ *     directly to `done`. No team is spawned. This matches the
+ *     `no_anchoring_injections_short_circuit` soft guard on
+ *     `verify -> close_loop` in the focus workflow.
+ *
+ *   - **Otherwise, spawn a fresh bookkeeper team** (Sonnet model, fresh
+ *     session) with the close_loop assembly recipe:
+ *         loop.persona(variant=close_loop)
+ *         focus.context
+ *         focus.anchoring_injections
+ *         git.diff_against_base
+ *         delivery.acceptance_criteria
+ *         review.outcomes
+ *     The team handles the per-injection sweep (verified | escalated, no
+ *     third option), the incomplete-planning check, and the tree-drift
+ *     check skeleton (D5 wires `focus.description` through into the
+ *     drift-check prompt section).
+ *
+ *   - **Monitor termination.** Once every anchored injection has reached a
+ *     terminal state (`verified` or has an open `injection_unverified`
+ *     escalation), the dispatcher advances the focus to `done`. While any
+ *     injection is still non-terminal, the focus stays at `close_loop`.
+ *
+ * The dispatcher is intentionally split into small pure helpers so each
+ * deterministic check (terminal classification, short-circuit detection,
+ * directive composition) is unit-testable without DB or process spawning.
+ */
+import type { DaemonConfig, StageDirective } from '../types/index.js';
+import type { FocusDeliveryInfo } from '../types/index.js';
+/**
+ * Model used by close_loop bookkeeper teams. Sonnet because the bookkeeper
+ * is a careful, deterministic role (sweep injections, file escalations);
+ * Opus would be overkill and slower.
+ */
+export declare const CLOSE_LOOP_MODEL = "claude-sonnet-4-6";
+/**
+ * Assembly recipe for the close_loop stage. Composed in dispatcher when
+ * the close_loop directive is synthesized. Persisted nowhere -- the
+ * stage's stored `agent_directive` (if any) is ignored in favor of this
+ * canonical recipe so the bookkeeper framing is deterministic regardless
+ * of how the workflow stage row was seeded.
+ */
+export declare const CLOSE_LOOP_ASSEMBLY_RECIPE: readonly string[];
+/**
+ * Terminal injection statuses for close_loop. An injection is considered
+ * terminal when it is either verified (the bookkeeper called
+ * reality_tree_injection_verify) or has an `injection_unverified`
+ * escalation filed against it. The first is detected by `injectionStatus`;
+ * the second is detected by walking the agent_escalations table -- see
+ * `isInjectionEscalated`.
+ */
+export declare const TERMINAL_INJECTION_STATUSES: readonly string[];
+/**
+ * Return the deliveries in the focus that anchor an injection.
+ *
+ * A delivery anchors an injection when `injection_id` (a column on
+ * org_nodes rows of type='delivery', see migration
+ * 20260510152110_add_injection_id_to_product_deliveries.sql) points at a
+ * reality_tree_nodes row.
+ */
+export declare function getAnchoringDeliveries(deliveries: FocusDeliveryInfo[]): FocusDeliveryInfo[];
+/**
+ * Pure short-circuit predicate -- "does this focus have any anchoring
+ * injections?". If false, close_loop is a no-op and the focus can advance
+ * directly to `done`.
+ */
+export declare function shouldShortCircuitToDone(deliveries: FocusDeliveryInfo[]): boolean;
+/**
+ * Per-injection summary used by termination checks. The dispatcher composes
+ * one of these per anchored injection from a snapshot of:
+ *
+ *   - the injection node's `injectionStatus` (from reality_tree_nodes)
+ *   - whether there is an open `injection_unverified` escalation with
+ *     metadata.injection_id == this injection id (from agent_escalations)
+ */
+export interface InjectionTerminalState {
+    injectionId: string;
+    /** From reality_tree_nodes.injection_status (or null for non-injection nodes). */
+    injectionStatus: string | null;
+    /** Whether an open injection_unverified escalation targets this injection. */
+    hasOpenUnverifiedEscalation: boolean;
+}
+/**
+ * Pure classifier. An injection is terminal for close_loop when:
+ *
+ *   - injectionStatus is `verified`, OR
+ *   - there is an open `injection_unverified` escalation for it
+ *     (this is the "escalated" outcome -- the bookkeeper filed the
+ *     escalation and the focus is now blocked on a human).
+ *
+ * The "open escalation" case keeps the focus at close_loop (status='pending'
+ * or 'in_review') -- this function classifies the escalation as terminal
+ * for the dispatcher's perspective so the daemon does not loop forever
+ * re-spawning the bookkeeper. A human must resolve or dismiss the
+ * escalation; once resolved, the bookkeeper can be re-triggered.
+ */
+export declare function isInjectionTerminal(state: InjectionTerminalState): boolean;
+/**
+ * Pure aggregate predicate -- "are ALL anchored injections terminal?".
+ * Returns true on an empty list (the short-circuit branch handles the
+ * empty case separately, but this is safe to call after the short-circuit
+ * filter).
+ */
+export declare function allInjectionsTerminal(states: InjectionTerminalState[]): boolean;
+/**
+ * One entry in the planned sweep: an injection that should be verified and
+ * the evidence text to persist with the verify call.
+ */
+export interface InjectionSweepEntry {
+    injectionId: string;
+    evidence: string;
+}
+/**
+ * Pure planner. Given the focus's anchored deliveries and a snapshot of each
+ * injection's current status, return the list of injections to verify and
+ * the evidence text to attach.
+ *
+ * An injection is swept when ALL of:
+ *   - its current `injectionStatus` is NOT 'verified'
+ *   - at least one delivery anchoring it has executionStatus in the
+ *     "closed successfully" set ('done', forward-compat 'verified').
+ *
+ * Injections backed only by cancelled / in-flight deliveries -- or with no
+ * anchoring delivery in `anchored` at all -- are skipped (criterion 3 of the
+ * close-loop sweep contract).
+ *
+ * Evidence text cites the first closed-and-successful anchoring delivery's
+ * name and id so future audit reads can trace which delivery realized the
+ * injection.
+ */
+export declare function planInjectionSweep(anchored: FocusDeliveryInfo[], statusByInjectionId: ReadonlyMap<string, string | null>): InjectionSweepEntry[];
+/**
+ * Outcome of running the planned sweep against a `verify` callable. Pure
+ * with respect to side effects -- the `verify` argument owns the actual
+ * I/O so tests can pass a stub.
+ *
+ * `ok === true` means every entry verified; `ok === false` means the loop
+ * stopped at `failedAt.injectionId`. The dispatcher MUST NOT advance the
+ * focus to 'done' when `ok` is false -- a partial sweep means the tree is
+ * still in an inconsistent state and the next poll cycle should retry.
+ */
+export interface SweepRunOutcome {
+    ok: boolean;
+    verified: string[];
+    failedAt?: {
+        injectionId: string;
+        error: Error;
+    };
+}
+/**
+ * Execute a planned sweep in order. Short-circuits on the first failure --
+ * the dispatcher returns the original `advance_to_done` decision without
+ * calling `updateFocusStage`, so the failed verify is retried on the next
+ * close_loop poll cycle.
+ */
+export declare function executeSweep(entries: readonly InjectionSweepEntry[], verify: (injectionId: string, evidence: string) => Promise<void>): Promise<SweepRunOutcome>;
+/**
+ * Dependencies for advancing a focus from close_loop -> done with a
+ * preceding injection sweep. Both are owned by callers so tests can stub
+ * them without mocking the daemon's I/O layer.
+ */
+export interface AdvanceToDoneDeps {
+    verify: (injectionId: string, evidence: string) => Promise<void>;
+    updateFocusStage: (focusId: string, stage: 'done') => Promise<void>;
+}
+/**
+ * Outcome of `advanceFocusToDoneWithSweep`. The dispatcher reads this to
+ * decide whether to clear the bookkeeper-spawned flag (which is cleared
+ * only when the focus actually leaves close_loop, success or terminal
+ * failure).
+ *
+ *  - `advanced=true`  -- updateFocusStage was called and returned
+ *  - `sweepFailure` set -- the sweep failed; updateFocusStage was NOT
+ *    called; the focus is held at close_loop for the next poll cycle to
+ *    retry. This is the explicit "focus does not advance" semantics from
+ *    AC-6 of the focus-closure-correctness focus.
+ *  - `advanceError` set -- the sweep succeeded (or was empty) but
+ *    updateFocusStage threw. The focus did not advance, but the failure
+ *    is on the stage-update side, not the sweep side.
+ */
+export interface AdvanceToDoneOutcome {
+    advanced: boolean;
+    verifiedCount: number;
+    planSize: number;
+    sweepFailure?: {
+        injectionId: string;
+        error: Error;
+    };
+    advanceError?: Error;
+}
+/**
+ * Run the close_loop sweep, then advance the focus to `done`. Pure with
+ * respect to side effects -- callers inject `verify` and
+ * `updateFocusStage` via `deps`.
+ *
+ * Order of operations is part of the contract:
+ *   1. Build the sweep plan from `anchored` + `statusByInjectionId`.
+ *   2. If non-empty, run the sweep. On failure: log + return early WITHOUT
+ *      calling `deps.updateFocusStage`. This is the "focus does not
+ *      advance" invariant — the failed verify is retried on the next poll
+ *      cycle when the focus is re-evaluated.
+ *   3. On sweep success (or empty plan), call `deps.updateFocusStage`.
+ *
+ * The dispatcher (`dispatchCloseLoopStage`) delegates the entire
+ * advance_to_done branch to this function so the sweep-failure path is
+ * unit-testable without DB or process mocking.
+ */
+export declare function advanceFocusToDoneWithSweep(focus: {
+    focus_id: string;
+    focus_name: string;
+}, anchored: FocusDeliveryInfo[], statusByInjectionId: ReadonlyMap<string, string | null>, deps: AdvanceToDoneDeps): Promise<AdvanceToDoneOutcome>;
+/**
+ * Compose the synthetic close_loop StageDirective. Used by the dispatcher
+ * to seed the pending spawn directive map; pure for testability.
+ */
+export declare function buildCloseLoopDirective(): StageDirective;
+/**
+ * Query: are there any pending or in_review injection_unverified escalations
+ * for the given injection ids? Returns the set of injection ids that have
+ * an open escalation.
+ *
+ * Looks at agent_escalations with:
+ *   - escalation_kind = 'injection_unverified'
+ *   - status IN ('pending', 'in_review')
+ *   - metadata->>'injection_id' IN (...)
+ *
+ * The dispatcher uses this to classify "escalated" injections as terminal
+ * for advancement purposes.
+ */
+export interface OpenInjectionEscalationLookup {
+    (params: {
+        organizationId: string;
+        injectionIds: string[];
+    }): Promise<Set<string>>;
+}
+/**
+ * Top-level result of inspecting a focus for close_loop termination.
+ * Tells the caller exactly what to do: short-circuit, spawn, advance to
+ * done, or hold.
+ */
+export type CloseLoopDecision = {
+    kind: 'short_circuit_to_done';
+} | {
+    kind: 'spawn_bookkeeper';
+    directive: StageDirective;
+} | {
+    kind: 'advance_to_done';
+} | {
+    kind: 'hold';
+    reason: string;
+};
+/**
+ * Compute the close_loop decision for a focus given a snapshot of its
+ * deliveries and the terminal state of each anchored injection.
+ *
+ * Pure -- no DB access. Tests pass snapshots in.
+ *
+ * Semantics:
+ *
+ *   - No anchored injections                -> short_circuit_to_done
+ *   - Anchored injections, none yet sweeped -> spawn_bookkeeper
+ *   - All anchored injections terminal      -> advance_to_done
+ *   - Some terminal, some not               -> hold (waiting on bookkeeper)
+ *
+ * The "spawn_bookkeeper" branch is gated on "no sweep has happened yet"
+ * which the caller communicates via `bookkeeperHasRun`. Without this gate
+ * every poll cycle would respawn the bookkeeper while it's still working
+ * (or before a stuck injection's escalation is filed).
+ */
+export declare function decideCloseLoop(deliveries: FocusDeliveryInfo[], injectionStates: InjectionTerminalState[], bookkeeperHasRun: boolean): CloseLoopDecision;
+/**
+ * Sentinel returned by the dispatcher when no action was taken (focus is
+ * not in close_loop stage, or already processed this cycle). Caller can
+ * log it but should not act on it.
+ */
+export interface CloseLoopDispatchOutcome {
+    decision: CloseLoopDecision;
+    /** Anchored injection ids that were inspected (empty on short-circuit). */
+    anchoredInjectionIds: string[];
+}
+/**
+ * Re-exported constant set so tests can assert the kind names used by the
+ * dispatcher in the agent_escalations rows. Keeps the kind string under
+ * a single source of truth in daemon-core.
+ */
+export declare const CLOSE_LOOP_ESCALATION_KINDS: {
+    readonly INJECTION_UNVERIFIED: "injection_unverified";
+    readonly TREE_DRIFT: "tree_drift";
+    readonly INCOMPLETE_PLANNING: "incomplete_planning";
+};
+/**
+ * Configuration knobs accepted by the dispatcher entry point. Exposed so
+ * tests can inject a no-op spawner.
+ */
+export interface CloseLoopDispatcherDeps {
+    /**
+     * Set the pending spawn directive for the focus so the next spawn cycle
+     * delivers the close_loop directive. In production this is the export
+     * from directive-executor; in tests this is a stub.
+     */
+    setPendingSpawnDirective: (focusId: string, directive: {
+        message: string;
+        model: string | null;
+        sessionType: 'coding' | 'review';
+        contentHash: string;
+    }) => void;
+    /** Advance the focus stage on product_focuses.stage. */
+    updateFocusStage: (focusId: string, stage: string) => Promise<void>;
+    /** Lookup open injection_unverified escalations. */
+    lookupOpenInjectionEscalations: OpenInjectionEscalationLookup;
+    /** Build the directive content (assembly resolution + prompt). */
+    assembleDirectiveContent: (config: DaemonConfig, focusId: string, directive: StageDirective, worktreePath: string | null) => Promise<string>;
+    /** Compute the content hash for the synthesized directive. */
+    computeDirectiveHash: (directive: StageDirective) => string;
+}
+//# sourceMappingURL=close-loop-dispatcher.d.ts.map

package/dist/directive/close-loop-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"close-loop-dispatcher.d.ts","sourceRoot":"","sources":["../../src/directive/close-loop-dispatcher.ts"],"names":[],"mappings":"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"}