@telora/daemon 0.22.245 → 0.22.290

package/dist/completion/team-teardown/session-hold.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Bounded session holds: every daemon decision that KEEPS a team alive (or
+ * defers the queued directive that would replace it) records a hold here, and
+ * the poll loop sweeps the holds each tick. A hold carries its own bound and the
+ * outcome its expiry fires -- teardown or escalation -- so no keep is open-ended.
+ *
+ * Why: two individually reasonable unbounded keeps (a review-window
+ * 'leave_running' and a 'defer_young_divergence' directive deferral) can wait on
+ * each other forever; a bound on every hold breaks that deadlock.
+ *
+ * History: docs/daemon/history-team-lifecycle.md (completion/team-teardown/session-hold.ts).
+ *
+ * A hold is keyed to the focus AND the team identity (team.startedAtMs) it was
+ * recorded against, so a hold never outlives its team: the sweep drops a hold
+ * whose team exited or was replaced. Re-recording a hold for the same team keeps
+ * the original clock -- a kept team emitting result after result cannot extend
+ * its own bound.
+ *
+ * Expiry policy per kind (resolveSessionHoldExpiry):
+ *   - young_team_directive_deferral: teardown (shutdownReason 'handoff', the same
+ *     outcome the past-window 'respawn' decision takes) iff the deferred directive
+ *     is still queued; a consumed/replaced directive drops the hold silently.
+ *   - merge_resolution: teardown iff resolvingMergeConflict is STILL set past
+ *     requestTeamLeadResolution's own bounded wait; else drop.
+ *   - review_window_keep_alive / first_result_teardown_demoted (keep-alives):
+ *     no movement on the ONE team-progress record since the hold was recorded
+ *     (SessionHoldSweepDeps.getLastProgressAt) -> teardown. Moved -> ONE
+ *     escalation, and the hold re-windows; its next expiry ends in teardown.
+ *
+ * A teardown that cannot signal the lead (terminateTeam returns false: no lead
+ * pid, or the signal threw) does NOT drop the hold -- a dropped hold would leave
+ * the stale active-team entry excluding the focus from the pending-spawn pass
+ * with nothing bounding it. The hold re-windows by SESSION_HOLD_TEARDOWN_RETRY_MS
+ * and retries; the SESSION_HOLD_TEARDOWN_MAX_ATTEMPTS-th failure clears the hold,
+ * force-reaps the registration (team-lifecycle forceReapTeam: the reapers' own
+ * reclamation), and files ONE escalation.
+ *
+ * Every fired expiry logs exactly:
+ *   [session-hold] <kind> hold on focus <id8> expired after <N>s -- fired: teardown|escalation (<reason>)
+ * and a teardown that could not signal the lead follows it with:
+ *   [session-hold] <kind> hold on focus <id8> teardown attempt <n>/<max> found no signalable lead -- fired: teardown_retry|forced_cleanup (...)
+ *
+ * Pure registry + sweep: collaborators arrive through SessionHoldSweepDeps (the
+ * production wiring lives in session-hold-sweep-deps.ts) so this module stays a
+ * leaf the directive dispatcher and the completion iterator can both import.
+ */
+import type { FocusTeamState } from '../../types/index.js';
+import type { SessionHoldBound, SessionHoldExpiry, SessionHoldKind } from './session-hold-bounds.js';
+/**
+ * What a sweep actually did for an expired hold: its expiry outcome, or -- when
+ * the teardown could not signal the lead -- a bounded retry or the terminal
+ * forced cleanup (registration reaped + one escalation).
+ */
+export type SessionHoldFired = SessionHoldExpiry | 'teardown_retry' | 'forced_cleanup';
+/** Teardown attempts an expired hold makes before it force-reaps the team registration. */
+export declare const SESSION_HOLD_TEARDOWN_MAX_ATTEMPTS = 3;
+/** Re-window between teardown attempts whose lead could not be signalled. */
+export declare const SESSION_HOLD_TEARDOWN_RETRY_MS = 60000;
+/** Grace past the spawn-guard window before a deferred directive tears the young team down. */
+export declare const YOUNG_TEAM_DEFERRAL_GRACE_MS = 5000;
+/** The shutdown reason each kind's teardown stamps (read by the exit classifier + cooldown). */
+export declare const SESSION_HOLD_TEARDOWN_REASON: Readonly<Record<SessionHoldKind, FocusTeamState['shutdownReason']>>;
+/** A recorded hold. */
+export interface SessionHold extends SessionHoldBound {
+    focusId: string;
+    reason: string;
+    /** Team identity the hold was recorded against (team.startedAtMs). */
+    teamStartedAtMs: number;
+    recordedAtMs: number;
+    /** young_team_directive_deferral only: the deferred directive's contentHash. */
+    directiveHash?: string;
+    /** Set once the hold's expiry filed its one escalation; the next expiry tears down. */
+    escalated?: boolean;
+    /**
+     * Teardown attempts that could not signal the lead so far. Each re-windows the
+     * hold by SESSION_HOLD_TEARDOWN_RETRY_MS; the attempt that reaches
+     * SESSION_HOLD_TEARDOWN_MAX_ATTEMPTS force-reaps instead.
+     */
+    teardownAttempts?: number;
+}
+export interface RecordSessionHoldInput extends SessionHoldBound {
+    focusId: string;
+    reason: string;
+    /** The team's identity: its FocusTeamState.startedAtMs. */
+    teamStartedAtMs: number;
+    nowMs: number;
+    directiveHash?: string;
+}
+/**
+ * Record (or refresh) a hold. Re-recording for the SAME team identity keeps the
+ * original clock, bound, and escalation state -- a re-record can never extend a
+ * bound. A different team identity replaces the hold with a fresh one.
+ */
+export declare function recordSessionHold(input: RecordSessionHoldInput): SessionHold;
+/**
+ * Record the bounded young-team directive deferral: the directive waits for the
+ * young team only until the spawn-guard window (measured from team.startedAtMs)
+ * lapses, plus a small grace.
+ */
+export declare function recordYoungTeamDeferralHold(args: {
+    focusId: string;
+    teamStartedAtMs: number;
+    contentHash: string;
+    nowMs: number;
+}): SessionHold;
+/** Clear one kind of hold for a focus, or every hold on it when kind is omitted. */
+export declare function clearSessionHold(focusId: string, kind?: SessionHoldKind): void;
+/** Read the holds currently recorded for a focus (snapshot copies). */
+export declare function getSessionHolds(focusId: string): SessionHold[];
+/** Test-only: drop every recorded hold. */
+export declare function __resetSessionHoldsForTesting(): void;
+/** The team facts the expiry policy reads (structural slice of FocusTeamState). */
+export type SessionHoldTeam = Pick<FocusTeamState, 'startedAtMs' | 'resolvingMergeConflict' | 'organizationId' | 'focusName' | 'leadSessionId' | 'leadPid'>;
+/**
+ * Why an expiry files an escalation: the kept team is still active past its
+ * bound, or its teardown could not signal the lead and the registration was
+ * force-reaped.
+ */
+export type SessionHoldEscalationCause = 'still_active' | 'teardown_unsignalable';
+/** What an expiry that files an escalation hands the filer. */
+export interface ExpiredSessionHold {
+    hold: SessionHold;
+    team: SessionHoldTeam;
+    elapsedMs: number;
+    reason: string;
+    cause: SessionHoldEscalationCause;
+}
+export interface SessionHoldSweepDeps {
+    getActiveTeam: (focusId: string) => SessionHoldTeam | undefined;
+    terminateTeam: (focusId: string, shutdownReason: FocusTeamState['shutdownReason']) => boolean;
+    /** Force-reclaim a registration whose teardown could not signal the lead; true iff one was reaped. */
+    forceReapTeam: (focusId: string, shutdownReason: FocusTeamState['shutdownReason']) => Promise<boolean>;
+    fileEscalation: (expired: ExpiredSessionHold) => Promise<void>;
+    /** True while a pending spawn directive with this contentHash is still queued for the focus. */
+    isDirectiveStillQueued: (focusId: string, contentHash: string) => boolean;
+    /**
+     * When the team last moved on the ONE team-progress record
+     * (completion/team-progress/team-stillness.ts readTeamLastProgressAt), or null
+     * when no readable reading exists. A keep-alive asks "did the team move since
+     * the hold was recorded" of this record, never of the raw activity clock.
+     */
+    getLastProgressAt: (focusId: string) => number | null;
+}
+/** The reads an expiry decision takes beyond the hold and the team. */
+export type SessionHoldExpiryReads = Pick<SessionHoldSweepDeps, 'isDirectiveStillQueued' | 'getLastProgressAt'>;
+export interface FiredSessionHold {
+    focusId: string;
+    kind: SessionHoldKind;
+    fired: SessionHoldFired;
+    elapsedMs: number;
+    reason: string;
+}
+/**
+ * Decide what an expired hold fires, re-checking the condition that justified
+ * it. The decision is the stop registry's session_hold_expiry row
+ * (supervision/stop-rows-team-session.ts). Pure; exported for test.
+ */
+export declare function resolveSessionHoldExpiry(hold: SessionHold, team: SessionHoldTeam, reads: SessionHoldExpiryReads): {
+    outcome: SessionHoldExpiry | 'drop';
+    detail: string;
+};
+/**
+ * Sweep every recorded hold once. A hold whose team exited or was replaced is
+ * dropped; an expired hold fires its (re-checked) outcome. Returns what fired.
+ */
+export declare function sweepExpiredSessionHolds(nowMs: number, deps: SessionHoldSweepDeps): Promise<FiredSessionHold[]>;
+//# sourceMappingURL=session-hold.d.ts.map

package/dist/completion/team-teardown/session-hold.d.ts.map

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

package/dist/completion/team-teardown/session-hold.js

@@ -0,0 +1,221 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/completion/completion-event/merge-resolution-hold.test.ts,
+//   packages/daemon/src/completion/completion-event/review-window-idle-coding-lead-regression.test.ts,
+//   packages/daemon/src/completion/completion-event/review-window-no-premature-teardown.test.ts,
+//   packages/daemon/src/completion/completion-event/teardown-demotion-gate.test.ts,
+//   packages/daemon/src/completion/completion-event/unclaimed-migration-notice.test.ts,
+//   packages/daemon/src/completion/team-outcome/apply.test.ts,
+//   packages/daemon/src/completion/team-outcome/team-outcome-characterization.test.ts,
+//   packages/daemon/src/completion/team-teardown/session-hold.test.ts,
+//   packages/daemon/src/spawn/review-during-hold-terminates-coding.test.ts
+// PINNED-BY-END
+import { SPAWN_GUARD_WINDOW_MS } from '../../directive/directive-queue.js';
+import { createLogger } from '../../log/daemon-log.js';
+import { evaluateStop } from '../../supervision/stop-registry.js';
+const log = createLogger({ module: 'session-hold' });
+/** Teardown attempts an expired hold makes before it force-reaps the team registration. */
+export const SESSION_HOLD_TEARDOWN_MAX_ATTEMPTS = 3;
+/** Re-window between teardown attempts whose lead could not be signalled. */
+export const SESSION_HOLD_TEARDOWN_RETRY_MS = 60_000;
+/** Grace past the spawn-guard window before a deferred directive tears the young team down. */
+export const YOUNG_TEAM_DEFERRAL_GRACE_MS = 5_000;
+/** The shutdown reason each kind's teardown stamps (read by the exit classifier + cooldown). */
+export const SESSION_HOLD_TEARDOWN_REASON = {
+    young_team_directive_deferral: 'handoff',
+    merge_resolution: 'teardown',
+    review_window_keep_alive: 'teardown',
+    first_result_teardown_demoted: 'no_actionable_work',
+    // The work the team was kept for is done (it was told); an expiry here is an
+    // ordinary end of the turn, not a failure.
+    unclaimed_migration_notice: 'work_complete',
+};
+const holds = new Map();
+/**
+ * Record (or refresh) a hold. Re-recording for the SAME team identity keeps the
+ * original clock, bound, and escalation state -- a re-record can never extend a
+ * bound. A different team identity replaces the hold with a fresh one.
+ */
+export function recordSessionHold(input) {
+    const byKind = holds.get(input.focusId) ?? new Map();
+    const { teamStartedAtMs } = input;
+    const prior = byKind.get(input.kind);
+    const hold = prior !== undefined && prior.teamStartedAtMs === teamStartedAtMs
+        ? { ...prior, reason: input.reason, ...(input.directiveHash !== undefined ? { directiveHash: input.directiveHash } : {}) }
+        : {
+            focusId: input.focusId,
+            kind: input.kind,
+            reason: input.reason,
+            maxMs: input.maxMs,
+            onExpire: input.onExpire,
+            teamStartedAtMs,
+            recordedAtMs: input.nowMs,
+            ...(input.directiveHash !== undefined ? { directiveHash: input.directiveHash } : {}),
+        };
+    byKind.set(input.kind, hold);
+    holds.set(input.focusId, byKind);
+    return hold;
+}
+/**
+ * Record the bounded young-team directive deferral: the directive waits for the
+ * young team only until the spawn-guard window (measured from team.startedAtMs)
+ * lapses, plus a small grace.
+ */
+export function recordYoungTeamDeferralHold(args) {
+    const deadlineMs = args.teamStartedAtMs + SPAWN_GUARD_WINDOW_MS + YOUNG_TEAM_DEFERRAL_GRACE_MS;
+    return recordSessionHold({
+        focusId: args.focusId,
+        kind: 'young_team_directive_deferral',
+        maxMs: Math.max(0, deadlineMs - args.nowMs),
+        onExpire: 'teardown',
+        reason: 'a divergent spawn directive was deferred behind a young team',
+        teamStartedAtMs: args.teamStartedAtMs,
+        nowMs: args.nowMs,
+        directiveHash: args.contentHash,
+    });
+}
+/** Clear one kind of hold for a focus, or every hold on it when kind is omitted. */
+export function clearSessionHold(focusId, kind) {
+    if (kind === undefined) {
+        holds.delete(focusId);
+        return;
+    }
+    const byKind = holds.get(focusId);
+    if (!byKind)
+        return;
+    byKind.delete(kind);
+    if (byKind.size === 0)
+        holds.delete(focusId);
+}
+/** Read the holds currently recorded for a focus (snapshot copies). */
+export function getSessionHolds(focusId) {
+    return [...(holds.get(focusId)?.values() ?? [])].map((h) => ({ ...h }));
+}
+/** Test-only: drop every recorded hold. */
+export function __resetSessionHoldsForTesting() {
+    holds.clear();
+}
+/**
+ * Decide what an expired hold fires, re-checking the condition that justified
+ * it. The decision is the stop registry's session_hold_expiry row
+ * (supervision/stop-rows-team-session.ts). Pure; exported for test.
+ */
+export function resolveSessionHoldExpiry(hold, team, reads) {
+    const { outcome, detail } = evaluateSessionHold(hold, team, hold.recordedAtMs + hold.maxMs, reads);
+    return { outcome, detail };
+}
+/** The hold's verdict at `nowMs`, decided by the stop registry's session_hold_expiry row. */
+function evaluateSessionHold(hold, team, nowMs, reads) {
+    return evaluateStop('session_hold_expiry', {
+        kind: hold.kind,
+        elapsedMs: nowMs - hold.recordedAtMs,
+        maxMs: hold.maxMs,
+        onExpire: hold.onExpire,
+        recordedAtMs: hold.recordedAtMs,
+        directiveStillQueued: hold.kind === 'young_team_directive_deferral' &&
+            hold.directiveHash !== undefined && reads.isDirectiveStillQueued(hold.focusId, hold.directiveHash),
+        resolvingMergeConflict: team.resolvingMergeConflict,
+        teardownAttempts: hold.teardownAttempts ?? 0,
+        escalated: hold.escalated === true,
+        lastProgressMs: reads.getLastProgressAt(hold.focusId),
+    });
+}
+function holdTag(hold) {
+    return `[session-hold] ${hold.kind} hold on focus ${hold.focusId.slice(0, 8)}`;
+}
+async function fireExpiredHold(hold, team, nowMs, deps, verdict) {
+    const elapsedMs = nowMs - hold.recordedAtMs;
+    const { outcome, detail } = verdict;
+    if (outcome === 'drop') {
+        clearSessionHold(hold.focusId, hold.kind);
+        log.debug(`${holdTag(hold)} dropped at expiry (${detail})`);
+        return null;
+    }
+    const reason = `${hold.reason}; ${detail}`;
+    log.warn(`${holdTag(hold)} expired after ${Math.round(elapsedMs / 1000)}s -- fired: ${outcome} (${reason})`);
+    const expired = { hold, team, elapsedMs, reason, cause: 'still_active' };
+    const fired = outcome === 'teardown'
+        ? await fireTeardown(expired, nowMs, deps)
+        : await fireEscalation(expired, nowMs, deps);
+    return { focusId: hold.focusId, kind: hold.kind, fired, elapsedMs, reason };
+}
+async function fileHoldEscalation(expired, deps) {
+    try {
+        await deps.fileEscalation(expired);
+    }
+    catch (err) {
+        log.warn(`${holdTag(expired.hold)} escalation filing failed: ${err.message}`);
+    }
+}
+/**
+ * One filing per expiry, never repeated for this hold: re-window it so the NEXT
+ * expiry ends in teardown rather than a second escalation.
+ */
+async function fireEscalation(expired, nowMs, deps) {
+    const { hold } = expired;
+    holds.get(hold.focusId)?.set(hold.kind, { ...hold, escalated: true, recordedAtMs: nowMs });
+    await fileHoldEscalation(expired, deps);
+    return 'escalation';
+}
+/**
+ * Tear the held team down. A teardown that cannot signal the lead keeps the hold
+ * and re-windows it for a bounded retry; the last allowed attempt force-reaps.
+ */
+async function fireTeardown(expired, nowMs, deps) {
+    const { hold } = expired;
+    if (deps.terminateTeam(hold.focusId, SESSION_HOLD_TEARDOWN_REASON[hold.kind])) {
+        clearSessionHold(hold.focusId, hold.kind);
+        return 'teardown';
+    }
+    const attempts = (hold.teardownAttempts ?? 0) + 1;
+    const attemptNote = `teardown attempt ${attempts}/${SESSION_HOLD_TEARDOWN_MAX_ATTEMPTS} found no signalable lead`;
+    if (attempts >= SESSION_HOLD_TEARDOWN_MAX_ATTEMPTS)
+        return forceCleanup(expired, attemptNote, deps);
+    holds.get(hold.focusId)?.set(hold.kind, {
+        ...hold, teardownAttempts: attempts, recordedAtMs: nowMs, maxMs: SESSION_HOLD_TEARDOWN_RETRY_MS,
+    });
+    log.warn(`${holdTag(hold)} ${attemptNote} -- fired: teardown_retry ` +
+        `(hold re-windowed for ${Math.round(SESSION_HOLD_TEARDOWN_RETRY_MS / 1000)}s)`);
+    return 'teardown_retry';
+}
+/**
+ * Terminal outcome of a teardown that never reached the lead: clear the hold,
+ * force-reap the stale registration (so the pending-spawn pass stops excluding
+ * the focus), and file ONE escalation naming the forced cleanup.
+ */
+async function forceCleanup(expired, attemptNote, deps) {
+    const { hold } = expired;
+    clearSessionHold(hold.focusId, hold.kind);
+    let registration;
+    try {
+        registration = await deps.forceReapTeam(hold.focusId, SESSION_HOLD_TEARDOWN_REASON[hold.kind]) ? 'reaped' : 'already gone';
+    }
+    catch (err) {
+        registration = `reap failed: ${err.message}`;
+    }
+    log.warn(`${holdTag(hold)} ${attemptNote} -- fired: forced_cleanup (registration ${registration}; escalated; ${expired.reason})`);
+    await fileHoldEscalation({ ...expired, cause: 'teardown_unsignalable' }, deps);
+    return 'forced_cleanup';
+}
+/**
+ * Sweep every recorded hold once. A hold whose team exited or was replaced is
+ * dropped; an expired hold fires its (re-checked) outcome. Returns what fired.
+ */
+export async function sweepExpiredSessionHolds(nowMs, deps) {
+    const fired = [];
+    const snapshot = [...holds.values()].flatMap((byKind) => [...byKind.values()]);
+    for (const hold of snapshot) {
+        const team = deps.getActiveTeam(hold.focusId);
+        if (!team || team.startedAtMs !== hold.teamStartedAtMs) {
+            clearSessionHold(hold.focusId, hold.kind);
+            continue;
+        }
+        const verdict = evaluateSessionHold(hold, team, nowMs, deps);
+        if (!verdict.expired)
+            continue;
+        const result = await fireExpiredHold(hold, team, nowMs, deps, verdict);
+        if (result)
+            fired.push(result);
+    }
+    return fired;
+}
+//# sourceMappingURL=session-hold.js.map

package/dist/completion/team-teardown/session-hold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-hold.js","sourceRoot":"","sources":["../../../src/completion/team-teardown/session-hold.ts"],"names":[],"mappings":"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"}

package/dist/completion/team-teardown/team-lifecycle.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Focus team lifecycle management - terminate, wait, detect deactivated.
+ *
+ * These functions manage the lifecycle of running focus teams (shutdown,
+ * deactivation detection, merge checks).
+ *
+ * History: docs/daemon/history-team-lifecycle.md (completion/team-teardown/team-lifecycle.ts).
+ */
+import type { DaemonConfig, FocusTeamState } from '../../types/index.js';
+import type { ResourceGovernor } from '@telora/daemon-core';
+import type { MergeFocusBranch } from '../../merge/focus-merge.js';
+import type { MergeGateDecision, MergeGateTarget } from '../../merge/merge-gate-coverage.js';
+import type { MergeConflictParams } from '../../merge/merge-conflict-escalation.js';
+import { type RunCiMergeToMainDeps } from '../team-exit/merge-phase.js';
+import type { getFocusDeliveries } from '../../queries/focuses/focuses.js';
+import { type ProcessGroupKillDeps } from '../../daemon-state/process-group-kill.js';
+/** Grace a torn-down team's process group gets on SIGTERM before SIGKILL. */
+export declare const TEAM_TEARDOWN_GRACE_MS = 30000;
+/** Ending focus teams: the teardown, the wait for the lead to exit, and the teardown of every team. */
+export interface TeamTermination {
+    /** Terminate a focus team (see terminateTeamWith). Returns whether the lead's group was signalled. */
+    terminateTeam(focusId: string, shutdownReason?: FocusTeamState['shutdownReason'], graceMs?: number): boolean;
+    /** Wait for a team to leave activeTeams, SIGKILLing its group past the timeout; true when it exited in time. */
+    waitForTeamExit(focusId: string, timeoutMs?: number): Promise<boolean>;
+    /** Terminate all active teams. */
+    terminateAllTeams(): void;
+}
+/**
+ * The team termination bound to the kill ladder's seams (the composition root
+ * binds the real OS). The functions are defined in this module on purpose:
+ * shutdown attribution names the first stack frame OUTSIDE this module
+ * (daemon-state/shutdown-attribution.ts), so the caller that asked is named,
+ * never this binding.
+ */
+export declare function createTeamTermination(processGroupKill: ProcessGroupKillDeps): TeamTermination;
+/**
+ * Result of one stuck-shutdown watchdog pass.
+ */
+export interface StuckShutdownReapResult {
+    /** Number of teams that were past the threshold and got reaped. */
+    reaped: number;
+    /** Focus IDs that were reaped this pass. */
+    reapedFocusIds: string[];
+}
+/**
+ * Dependencies for the stuck-shutdown watchdog. Injected so tests can supply a
+ * fake clock and a kill spy without touching the real process or governor.
+ */
+export interface ReapStuckShutdownDeps {
+    /** Governor whose slot is force-released for a reaped team (null = no release). */
+    governor: ResourceGovernor | null;
+    /** Threshold in ms a team may sit in `shutting_down` before being reaped. */
+    thresholdMs: number;
+    /** Current time (epoch ms). Defaults to Date.now(); injected in tests. */
+    now?: number;
+    /** The kill ladder's seams (production: the real OS, bound at the composition root). */
+    processGroupKill: ProcessGroupKillDeps;
+}
+/** Dependencies for forceReapTeam. */
+export interface ForceReapTeamDeps {
+    /** Governor whose slot is force-released for the reaped team (null = no release). */
+    governor: ResourceGovernor | null;
+    /** The kill ladder's seams (production: the real OS, bound at the composition root). */
+    processGroupKill: ProcessGroupKillDeps;
+}
+/**
+ * Force-reclaim ONE focus's team registration after the normal teardown could
+ * not signal its lead (terminateTeam returned false: no lead pid, or the signal
+ * threw). Without it such a registration pins the focus: the pending-spawn pass
+ * skips any focus with an active team, and neither reaper covers an `executing`
+ * team that has no pid. Performs the same reclamation the dead-process and
+ * stuck-shutdown reapers do (reclaimTeamRegistration), after stamping the
+ * controlled-stop reason and cancelling a pending re-drive -- so a late close
+ * event classifies as a stop, and the slot release cannot double-decrement.
+ * Returns false when no team is registered for the focus.
+ */
+export declare function forceReapTeam(focusId: string, shutdownReason: FocusTeamState['shutdownReason'], deps: ForceReapTeamDeps): boolean;
+/**
+ * Stuck-team watchdog: reap teams wedged in `shutting_down`.
+ *
+ * A team that entered `shutting_down` but whose lead process never exited
+ * pins its governor slot indefinitely (one root of the spawn-loop wedge: slots
+ * never free, so no new team can spawn). This watchdog scans active teams and,
+ * for any team in `shutting_down` longer than `thresholdMs`:
+ *   1. SIGKILLs the lead's process group immediately (terminateTeam only escalates to
+ *      SIGKILL after its own 30s timer, which a wedged team may outlast),
+ *   2. force-releases the governor slot (guarded against double-release),
+ *   3. marks the team `terminated` and removes it from activeTeams,
+ *   4. clears its shutdown side-state.
+ *
+ * Defense-in-depth and independent of the merge-back crash that triggers the
+ * wedge: even if some future shutdown path stalls, no slot is pinned forever.
+ *
+ * @returns counts of reaped teams for caller logging.
+ */
+export declare function reapStuckShuttingDownTeams(deps: ReapStuckShutdownDeps): StuckShutdownReapResult;
+/**
+ * Dependencies for the dead-process reaper (TEL-2). Injected so tests supply a
+ * fake clock, a liveness spy, and a kill spy without touching real processes.
+ */
+export interface ReapDeadProcessDeps {
+    /** Governor whose slot is force-released for a reaped team (null = no release). */
+    governor: ResourceGovernor | null;
+    /**
+     * How long a team may sit in `initializing` with NO lead pid (never reached a
+     * running process) before it is reclaimed. A team that DID reach a running
+     * process is reclaimed as soon as that process is gone, independent of age.
+     */
+    initStallMs: number;
+    /** Current time (epoch ms). Defaults to Date.now(); injected in tests. */
+    now?: number;
+    /** PID liveness probe: daemon-state/process-liveness.ts isProcessAlive in production; a test injects one. */
+    isAlive: (pid: number) => boolean;
+    /** The kill ladder's seams (production: the real OS, bound at the composition root). */
+    processGroupKill: ProcessGroupKillDeps;
+}
+/**
+ * Dead-process reaper: the memory->reality reconcile checkSessionHealth lacks.
+ *
+ * checkSessionHealth maps DB sessions -> in-memory teams (marks a DB session
+ * failed when no team tracks it). It never does the REVERSE: an in-memory team
+ * whose lead process is gone -- but whose `'close'` handler never fired to remove
+ * it -- lingers in activeTeams forever. Because the spawn gate treats any
+ * activeTeams entry as a live team, that ghost registration blocks every future
+ * spawn for the focus, and none of the presence-reading recovery paths can act
+ * (the team "exists"). This reaper scans the teams that are SUPPOSED to be live
+ * (`initializing` / `executing` -- `shutting_down` is owned by
+ * reapStuckShuttingDownTeams) and reclaims:
+ *   1. a team whose leadPid is set but whose process is no longer alive (a missed
+ *      close event), and
+ *   2. a team stuck in `initializing` with NO leadPid past `initStallMs` -- a
+ *      registration that names a process which never started (defence in depth
+ *      for any registration path that does not go through spawnFocusTeam's
+ *      release-on-throw finally, TEL-1).
+ * Reclamation force-releases the governor slot (once), marks the team terminated,
+ * and drops it from activeTeams so a fresh team can spawn -- no operator act.
+ */
+export declare function reapDeadProcessTeams(deps: ReapDeadProcessDeps): StuckShutdownReapResult;
+/** Injected seams of the mid-flight merge pass; production binds the product-api and git (composition/team-lifecycle-context.ts). */
+export interface MidFlightMergeDeps {
+    getFocusDeliveries: typeof getFocusDeliveries;
+    mergeFocusBranch: MergeFocusBranch;
+    /** Hold (an ungated commit or unreadable coverage, with why) or admit (with the anchors that admitted the merge). */
+    readMergeGate: (target: MergeGateTarget) => Promise<MergeGateDecision>;
+    /** The eager integration -> main CI merge once every delivery is merged (merge-phase.ts runCiMergeToMain). */
+    ciMerge: RunCiMergeToMainDeps;
+    /** The merge-conflict escalation a failed mid-flight merge files (merge/merge-conflict-escalation.ts). */
+    escalateMergeConflict: (params: MergeConflictParams) => Promise<void>;
+}
+/**
+ * Check active teams for newly completed deliveries and merge
+ * the focus branch to integration incrementally.
+ *
+ * Called from the poll loop. For each active team, queries delivery
+ * statuses and triggers a merge when any delivery reaches verify/done
+ * that hasn't already been merged mid-flight -- unless a commit on the branch
+ * has not passed the focus's review or verify gate (mergeCompletedMidFlight).
+ *
+ * After processing merges, checks if ALL active deliveries are terminal
+ * and merged. If so, terminates the team proactively since no more work
+ * remains. The focus stays active in the DB -- if new deliveries
+ * arrive later, the next poll cycle spawns a fresh team.
+ */
+export declare function checkAndMergeCompletedDeliveries(config: DaemonConfig, deps: MidFlightMergeDeps): Promise<void>;
+//# sourceMappingURL=team-lifecycle.d.ts.map

package/dist/completion/team-teardown/team-lifecycle.d.ts.map

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