@telora/daemon 0.21.178 → 0.21.192

package/dist/completion/completion-phase-registry.d.ts

@@ -0,0 +1,214 @@
+/**
+ * COMPLETION_PHASE_REGISTRY -- the team-completion flow as a declarative table.
+ *
+ * `handleTeamCompletion` (team-completion.ts) used to carry the whole exit
+ * sequence as one ~280-line imperative body whose phase order lived only in
+ * comments. This registry lifts that sequence into an ordered array of
+ * `CompletionPhaseDescriptor`s that the sequencer iterates, exactly as
+ * `LOOP_REGISTRY` (focus/focus-loop-registry.ts) did for the engine's
+ * start() loops. The phase bodies are extracted VERBATIM into named
+ * functions; order, gating, and short-circuit semantics are preserved
+ * exactly and pinned by completion-phase-registry.test.ts.
+ *
+ * Control-flow semantics are declared, not ad-hoc:
+ *   - `gate`     -- when the phase runs relative to the exit classification
+ *                   ('always' | 'succeeded' | 'not-succeeded'); enforced by
+ *                   the sequencer's iterator.
+ *   - `canHalt`  -- whether run() may return 'halt', ending the whole
+ *                   completion flow (only the read-only guard does).
+ *   - `accumulatesExitReason` -- whether the phase appends to
+ *                   ctx.exitReason (merge + CI merge-to-main).
+ *
+ * Phases communicate through a single mutable `CompletionPhaseContext`
+ * threaded by the sequencer: classify writes the classification + initial
+ * exit reason; report-git-state derives workedDeliveryIds; merge records
+ * mergeSucceeded; session-finalize records finalizedPassId + exitCategory
+ * for pass-close.
+ */
+import type { DaemonConfig, FocusTeamState, ExitCategory } from '../types/index.js';
+import { type TeamExitClassification } from './exit-classification.js';
+/**
+ * The mutable state threaded through every completion phase. Inputs are
+ * readonly; derived facts are written by the phase that owns them and read
+ * by later phases.
+ */
+export interface CompletionPhaseContext {
+    readonly config: DaemonConfig;
+    readonly teamState: FocusTeamState;
+    readonly sessionId: string;
+    readonly code: number | null;
+    readonly signal: string | null;
+    /** Written by 'classify'; every later phase reads it via requireClassification. */
+    classification: TeamExitClassification | undefined;
+    /** Initialized by 'classify'; appended to by 'merge' + 'ci-merge-to-main'. */
+    exitReason: string;
+    /** Written by 'report-git-state'. */
+    workedDeliveryIds: string[];
+    /** Written by 'merge'. */
+    mergeSucceeded: boolean;
+    /** Written by 'session-finalize'; read by 'pass-close'. */
+    finalizedPassId: string | null;
+    /** Written by 'session-finalize'; read by 'pass-close'. */
+    exitCategory: ExitCategory | null;
+}
+/** Build the initial (pre-classify) phase context from the sequencer params. */
+export declare function createCompletionPhaseContext(params: {
+    config: DaemonConfig;
+    teamState: FocusTeamState;
+    sessionId: string;
+    code: number | null;
+    signal: string | null;
+}): CompletionPhaseContext;
+/** 'halt' ends the whole completion flow; 'continue' proceeds to the next phase. */
+export type CompletionPhaseOutcome = 'continue' | 'halt';
+/** When a phase runs relative to the exit classification's `succeeded`. */
+export type CompletionPhaseGate = 'always' | 'succeeded' | 'not-succeeded';
+export interface CompletionPhaseDescriptor {
+    /** Stable phase name; order + names pinned by the structure test. */
+    name: string;
+    /** Enforced by the sequencer's iterator (see runCompletionPhases). */
+    gate: CompletionPhaseGate;
+    /** True only for phases whose run() may return 'halt'. */
+    canHalt: boolean;
+    /** True for phases that append to ctx.exitReason. */
+    accumulatesExitReason: boolean;
+    run(ctx: CompletionPhaseContext): Promise<CompletionPhaseOutcome>;
+}
+/** Build the initial exit reason from the exit classification. */
+export declare function buildInitialExitReason(teamState: FocusTeamState, classification: {
+    exitCode: number;
+    proactivelyTerminated: boolean;
+    succeeded: boolean;
+    controlledStop: boolean;
+}, signal: string | null): string;
+/**
+ * Phase: classify exit.
+ * A lifecycle teardown (shutdownReason='work_complete') SIGTERM is treated
+ * as a success, NOT a review failure -- see classifyTeamExit.
+ */
+export declare function runClassifyPhase(ctx: CompletionPhaseContext): Promise<CompletionPhaseOutcome>;
+/**
+ * Phase: report git state.
+ * Report git state for deliveries the team plausibly worked on or finished.
+ * See REPORTABLE_DELIVERY_STATUSES — including 'done' ensures focuses whose
+ * deliveries all reached done before the team exit still attempt the merge.
+ */
+export declare function runReportGitStatePhase(ctx: CompletionPhaseContext): Promise<CompletionPhaseOutcome>;
+/**
+ * Phase: read-only guard (the one halting phase).
+ * Read-only audit safety net: revert any uncommitted modifications, and if
+ * the agent somehow committed despite the pre-commit hook, mark the session
+ * failed and tear the team down WITHOUT merging.
+ *
+ * Returns 'halt' when the completion flow must abort (violation handled).
+ */
+export declare function runReadOnlyGuardPhase(ctx: CompletionPhaseContext): Promise<CompletionPhaseOutcome>;
+/**
+ * Phase: WIP preserve (gate: not-succeeded).
+ * Commit any uncommitted WIP changes left by the agent (crash, kill, timeout).
+ * Only needed when the agent didn't exit cleanly — a clean exit means the
+ * agent committed its own work.
+ */
+export declare function runWipPreservePhase(ctx: CompletionPhaseContext): Promise<CompletionPhaseOutcome>;
+/**
+ * Phase: status advance (gate: succeeded).
+ * Advance delivery statuses based on issue completion.
+ */
+export declare function runStatusAdvancePhase(ctx: CompletionPhaseContext): Promise<CompletionPhaseOutcome>;
+/**
+ * Phase: reality-pole capture (gate: succeeded).
+ * Anchor the focus's assertional loop items to the code footprint the
+ * focus branch touched (files = churn-clock scope, reality embedding = the
+ * pole). Runs BEFORE the merge below, while the branch still diverges from
+ * the integration base, so the footprint is non-empty. NOT gated behind the
+ * LLM opt-in -- anchoring is cheap and feeds the per-item tripwire. Wrapped
+ * so a failure never breaks completion.
+ */
+export declare function runRealityPoleCapturePhase(ctx: CompletionPhaseContext): Promise<CompletionPhaseOutcome>;
+/**
+ * Phase: merge (accumulates exitReason).
+ * Merge focus branch to integration if the branch has committed work.
+ * Decoupled from team-exit success: a team that exits via review SIGTERM,
+ * role-clear, daemon crash, or manual termination still gets its committed
+ * work propagated as long as the branch has commits ahead of integration.
+ *
+ * For proactive terminations, this is typically a no-op merge since all
+ * deliveries were already merged mid-flight. The merge still runs for
+ * safety (handles any commits the team lead made after the last
+ * incremental merge).
+ *
+ * Passes workedDeliveryIds so git state is only reported for deliveries
+ * that were plausibly worked on (coding/verify/done — see
+ * REPORTABLE_DELIVERY_STATUSES), not queued or planning deliveries that
+ * never started.
+ *
+ * Planning-phase and read-only audit guards stay in shouldAttemptMerge.
+ */
+export declare function runMergePhase(ctx: CompletionPhaseContext): Promise<CompletionPhaseOutcome>;
+/**
+ * Phase: CI merge-to-main (accumulates exitReason).
+ * CI: merge integration -> main (CD optionally pushes).
+ */
+export declare function runCiMergeToMainPhase(ctx: CompletionPhaseContext): Promise<CompletionPhaseOutcome>;
+/**
+ * Phase: session finalize.
+ * Compute git output from all commits on this branch since the integration
+ * tip AT SPAWN. The lines added/removed AND the changed-file list + commit
+ * SHAs are persisted on the session row so the Usage analytics work-output
+ * cards (Files Modified / Commits) reflect real git output.
+ *
+ * The base MUST be the spawn-time integration SHA (teamState.integrationBaseSha),
+ * not the live integration ref: by finalize the focus branch has been merged
+ * into integration (here AND mid-flight per delivery), and real merges preserve
+ * ancestry, so `integration..branch` is empty and the cards would read 0.
+ * Falls back to the live ref only when the spawn-time SHA is unavailable.
+ */
+export declare function runSessionFinalizePhase(ctx: CompletionPhaseContext): Promise<CompletionPhaseOutcome>;
+/**
+ * Phase: pass close.
+ * Close this (focus, lineage) pass only when the lineage genuinely ends, so a
+ * later re-code opens a FRESH pass while a same-lineage respawn keeps appending
+ * segments to the still-open pass. The deciding signal is the queued respawn:
+ *  - a pending spawn for a DIFFERENT lineage (e.g. coding -> review) ends this
+ *    lineage -> close.
+ *  - a pending spawn for the SAME lineage (a continuation handoff) -> keep open
+ *    so find-or-open reattaches the next segment.
+ *  - no pending spawn + a terminal disposition (work done / teardown /
+ *    deactivated / user stopped) -> close.
+ *  - no pending spawn + a benign handoff/error (the poll loop or
+ *    --resume-failure will respawn the same lineage) -> keep open.
+ */
+export declare function runPassClosePhase(ctx: CompletionPhaseContext): Promise<CompletionPhaseOutcome>;
+/**
+ * Phase: review exit (escalate / handoff).
+ * See runReviewExitHandler for the routing rules.
+ *
+ * Coverage evidence for the review-exit gate. The SPAWN-tip (what the review
+ * actually saw, carried on the team state from spawn) is what gets stamped as
+ * the coverage watermark; the EXIT-tip (resolved now) is compared against it
+ * to detect mid-review drift. Equal => clean coverage (auto-approve may fire);
+ * unequal => the branch advanced during the review (below coverage). Exit-tip
+ * is best-effort; on failure the handler falls back to spawn-tip for the stamp
+ * and withholds auto-approve (the safe direction).
+ */
+export declare function runReviewExitPhase(ctx: CompletionPhaseContext): Promise<CompletionPhaseOutcome>;
+/**
+ * Phase: terminate.
+ * Heartbeat, team-state cleanup, model-host release, re-poll trigger.
+ */
+export declare function runTerminatePhase(ctx: CompletionPhaseContext): Promise<CompletionPhaseOutcome>;
+/**
+ * The team-completion flow, in execution order. The sequencer
+ * (handleTeamCompletion) iterates this table; the structure test pins its
+ * length, names, order, and declared control-flow shape.
+ */
+export declare const COMPLETION_PHASE_REGISTRY: CompletionPhaseDescriptor[];
+/**
+ * Iterate the registry over a phase context: apply each phase's declared
+ * gate, run it, and stop the whole flow on 'halt'. The classification is
+ * written by the first phase; gates before it evaluate against
+ * "not yet classified" = not succeeded (only 'classify' itself runs there,
+ * and it is 'always').
+ */
+export declare function runCompletionPhases(ctx: CompletionPhaseContext, registry?: CompletionPhaseDescriptor[]): Promise<void>;
+//# sourceMappingURL=completion-phase-registry.d.ts.map

package/dist/completion/completion-phase-registry.d.ts.map

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