@telora/daemon 0.21.26 → 0.21.82

package/dist/shell/control-state.js

@@ -0,0 +1,337 @@
+/**
+ * Control state handler for the daemon.
+ *
+ * Polls for focuses with non-running control states and dispatches
+ * to the appropriate handler:
+ * - human_control: SIGSTOP the team lead process
+ * - resuming: SIGCONT the team lead process, inject note, set running
+ * - stopped: graceful shutdown (message + SIGTERM)
+ *
+ * Called from the poll loop alongside existing checks.
+ */
+import { getActiveTeams, terminateTeam } from '../focus/focus-executor.js';
+import { getControlStateChanges, setControlStateRunning } from '../queries/control-state.js';
+import { getActiveFocuses } from '../queries/deliveries.js';
+import { sendMessage } from '@telora/daemon-core';
+import { createLogger } from './log.js';
+const log = createLogger({ module: 'control-state' });
+// Track focuses that have already been suspended to avoid repeated SIGSTOP.
+const suspendedFocuses = new Set();
+/**
+ * Grace period (ms) between the cooperative 'commit and exit' stdin message and
+ * the SIGTERM that follows. Mirrors the cockpit Stop grace so the team has time
+ * to safety-commit its work before being terminated.
+ */
+export const COOPERATIVE_STOP_GRACE_MS = 10000;
+/**
+ * Check for control state changes and dispatch to appropriate handlers.
+ *
+ * Called from the poll loop. Queries for focuses with non-running control
+ * states, then dispatches to the correct handler.
+ */
+export async function checkControlStateChanges(config) {
+    let changes;
+    try {
+        changes = await getControlStateChanges(config.productId);
+    }
+    catch (err) {
+        log.warn('Failed to check control state changes:', err.message);
+        return;
+    }
+    if (changes.length === 0) {
+        // Clean up suspended set: remove focuses that have returned to running
+        // (they won't appear in the changes list since the API only returns non-running)
+        const activeTeams = getActiveTeams();
+        for (const focusId of suspendedFocuses) {
+            if (!activeTeams.has(focusId)) {
+                suspendedFocuses.delete(focusId);
+            }
+        }
+        return;
+    }
+    for (const change of changes) {
+        // Focus is the only entity type with a control-state model (the factory
+        // engine is retired).
+        if (change.entityType !== 'focus')
+            continue;
+        try {
+            switch (change.controlState) {
+                case 'human_control':
+                    handleHumanControl(change);
+                    break;
+                case 'resuming':
+                    await handleResuming(change);
+                    break;
+                case 'stopped':
+                    handleStopped(change);
+                    break;
+                default:
+                    log.warn(`Unknown control state: ${change.controlState} for ${change.entityId}`);
+            }
+        }
+        catch (err) {
+            log.error(`[control-state] Failed to handle ${change.controlState} for ${change.entityType} ${change.entityId}:`, err.message);
+        }
+    }
+}
+/**
+ * Handle human_control: suspend the agent by sending SIGSTOP.
+ */
+export function handleHumanControl(change) {
+    const { entityId } = change;
+    const activeTeams = getActiveTeams();
+    const team = activeTeams.get(entityId);
+    if (!team) {
+        log.info(`No active team for focus ${entityId} -- acknowledging human_control`);
+        return;
+    }
+    // Avoid repeated SIGSTOP
+    if (suspendedFocuses.has(entityId)) {
+        return;
+    }
+    if (!team.leadPid) {
+        log.warn(`Team for "${team.focusName}" has no PID -- cannot suspend`);
+        return;
+    }
+    try {
+        process.kill(team.leadPid, 'SIGSTOP');
+        suspendedFocuses.add(entityId);
+        log.info(`[control-state] Suspended team "${team.focusName}" (PID: ${team.leadPid}) -- human_control`);
+    }
+    catch (err) {
+        log.error(`[control-state] Failed to SIGSTOP PID ${team.leadPid} for "${team.focusName}":`, err.message);
+    }
+}
+/**
+ * Handle resuming: send SIGCONT, inject operator note, update to running.
+ */
+export async function handleResuming(change) {
+    const { entityId, entityType, controlNote } = change;
+    const activeTeams = getActiveTeams();
+    const team = activeTeams.get(entityId);
+    if (!team) {
+        log.info(`No active team for focus ${entityId} -- setting to running`);
+        try {
+            await setControlStateRunning(entityType, entityId);
+        }
+        catch (err) {
+            log.warn(`Failed to set control state to running for focus ${entityId}:`, err.message);
+        }
+        suspendedFocuses.delete(entityId);
+        return;
+    }
+    if (!team.leadPid) {
+        log.warn(`Team for "${team.focusName}" has no PID -- setting to running`);
+        try {
+            await setControlStateRunning(entityType, entityId);
+        }
+        catch (err) {
+            log.warn(`Failed to set control state to running for "${team.focusName}":`, err.message);
+        }
+        suspendedFocuses.delete(entityId);
+        return;
+    }
+    // Send SIGCONT to resume the suspended process
+    try {
+        process.kill(team.leadPid, 'SIGCONT');
+        log.info(`[control-state] Resumed team "${team.focusName}" (PID: ${team.leadPid}) -- SIGCONT sent`);
+    }
+    catch (err) {
+        log.error(`[control-state] Failed to SIGCONT PID ${team.leadPid} for "${team.focusName}":`, err.message);
+    }
+    // Inject operator note if present
+    if (controlNote && team.leadStdin) {
+        try {
+            sendMessage(team.leadStdin, `Human operator note: ${controlNote}`);
+            log.info(`Injected operator note for "${team.focusName}"`);
+        }
+        catch (err) {
+            log.warn(`[control-state] Failed to inject operator note for "${team.focusName}":`, err.message);
+        }
+    }
+    // Update control state to running
+    try {
+        await setControlStateRunning(entityType, entityId);
+    }
+    catch (err) {
+        log.warn(`[control-state] Failed to set control state to running for "${team.focusName}":`, err.message);
+    }
+    suspendedFocuses.delete(entityId);
+}
+/**
+ * Handle stopped: graceful halt with message + SIGTERM (cockpit Stop path).
+ *
+ * Thin wrapper over the shared initiateCooperativeStop -- the cockpit Stop and
+ * the disarm reaper drive the same cooperative-stop -> SIGTERM mechanism.
+ */
+export function handleStopped(change) {
+    initiateCooperativeStop(change.entityId, {
+        shutdownReason: 'user_stopped',
+        message: 'Execution has been stopped by the operator. Commit your current work and exit.',
+    });
+}
+const defaultCooperativeStopDeps = { getActiveTeams, terminateTeam };
+/**
+ * Cooperatively stop a running team: resume it if it was SIGSTOP-suspended,
+ * send the 'commit your work and exit' message, stamp the shutdown reason so
+ * the exit classifier records a controlled stop (NOT a crash / team_failure),
+ * then SIGTERM via the existing terminateTeam flow after the grace period.
+ *
+ * Pure mechanism: NO idempotency guard here (the cockpit Stop is a one-shot
+ * control-state event; the reaper supplies its own per-poll dedup). The grace
+ * timer is unref'd so it never holds the process open on its own.
+ */
+export function initiateCooperativeStop(focusId, options, deps = defaultCooperativeStopDeps) {
+    const activeTeams = deps.getActiveTeams();
+    const team = activeTeams.get(focusId);
+    if (!team) {
+        log.info(`No active team for focus ${focusId} -- acknowledging stop`);
+        suspendedFocuses.delete(focusId);
+        return;
+    }
+    // If the team was SIGSTOP-suspended (human_control -> stop), resume first so
+    // it can process the cooperative message before SIGTERM.
+    if (suspendedFocuses.has(focusId) && team.leadPid) {
+        try {
+            process.kill(team.leadPid, 'SIGCONT');
+            log.info(`Sent SIGCONT before stop for "${team.focusName}" (was suspended)`);
+        }
+        catch (err) {
+            log.debug(`SIGCONT before stop failed (process may have exited):`, err.message);
+        }
+    }
+    // Send the cooperative shutdown message via stdin.
+    if (team.leadStdin) {
+        try {
+            sendMessage(team.leadStdin, options.message);
+            log.info(`Sent stop message to "${team.focusName}"`);
+        }
+        catch (err) {
+            log.warn(`[control-state] Failed to send stop message to "${team.focusName}":`, err.message);
+        }
+    }
+    // Mark the shutdown reason so handleTeamCompletion classifies the exit as a
+    // controlled stop and records the matching exit_category (no team_failure).
+    team.shutdownReason = options.shutdownReason;
+    // After the grace period, SIGTERM via the existing terminateTeam flow. The
+    // timer is unref'd: the poll loop keeps the daemon alive, so the timer never
+    // needs to on its own (and a leaked timer can't block process/test exit).
+    const graceMs = options.graceMs ?? COOPERATIVE_STOP_GRACE_MS;
+    const timer = setTimeout(() => {
+        if (deps.getActiveTeams().has(focusId)) {
+            log.info(`Grace period expired for "${team.focusName}" -- terminating`);
+            deps.terminateTeam(focusId, options.shutdownReason);
+        }
+    }, graceMs);
+    if (typeof timer.unref === 'function')
+        timer.unref();
+    suspendedFocuses.delete(focusId);
+}
+// ── Disarm reaper: clearing the role (dashboard Stop) stops the team ─────
+/**
+ * Focuses with a cooperative stop already in flight (message sent, SIGTERM
+ * scheduled). The reaper re-evaluates every poll, so without this a disarmed
+ * focus whose grace window spans a poll tick would re-send the stop. Pruned of
+ * entries whose team has left activeTeams at the top of each run.
+ */
+const pendingDisarmStops = new Set();
+const defaultReapDeps = {
+    getActiveTeams,
+    getActiveFocuses,
+    initiateCooperativeStop,
+};
+/**
+ * Stop running teams whose focus has been DISARMED via the dashboard Stop
+ * (clearing assigned_agent_role_id). Clearing the role only removes the focus
+ * from the spawn set; the in-flight team would otherwise run to natural
+ * completion. This reaper brings the role-clear toggle to parity with the
+ * cockpit Stop: stop means stop.
+ *
+ * getActiveFocuses returns ALL status='active' focuses REGARDLESS of role
+ * (daemon-focus-handlers handleDaemonGetActiveFocuses), so:
+ *   - a team whose focus is PRESENT with a null role -> disarmed -> reap it;
+ *   - PRESENT with a non-null role -> still armed (idle/in-review/paused) -> leave it;
+ *   - ABSENT -> the focus is no longer status='active' (genuine deactivation),
+ *     owned by checkForDeactivatedFocuses (which runs earlier in the poll and
+ *     does a full teardown incl. worktree removal). The reaper deliberately
+ *     does NOT double-handle that case, and never removes the worktree -- a
+ *     disarmed focus keeps its worktree so a re-arm can resume.
+ *
+ * Re-arm within the grace window: the chosen rule is "complete the stop, then
+ * allow a fresh spawn". The scheduled SIGTERM still fires (the team exits as a
+ * clean operator stop); if the focus has since been re-armed, the next poll's
+ * processReadyFocuses spawns a fresh team once the old one is gone. The stop is
+ * never cancelled mid-flight, which keeps the path deterministic.
+ */
+export async function reapDisarmedTeams(config, deps = defaultReapDeps) {
+    const activeTeams = deps.getActiveTeams();
+    if (activeTeams.size === 0) {
+        pendingDisarmStops.clear();
+        return;
+    }
+    // Prune dedup entries whose team has already left activeTeams (terminated).
+    for (const id of pendingDisarmStops) {
+        if (!activeTeams.has(id))
+            pendingDisarmStops.delete(id);
+    }
+    let activeFocuses;
+    try {
+        activeFocuses = await deps.getActiveFocuses(config.organizationId, config.productId);
+    }
+    catch (err) {
+        // If the active-focus read fails, leave teams running rather than reaping
+        // on incomplete information.
+        log.warn(`[disarm-reaper] Cannot determine armed focuses (skipping reap): ${err.message}`);
+        return;
+    }
+    // focusId -> armed? (status active AND role non-null). Only status='active'
+    // focuses are returned, so a present focus with a non-null role is armed.
+    const armed = new Map();
+    for (const f of activeFocuses) {
+        armed.set(f.focus_id, f.assigned_agent_role_id != null && f.status === 'active');
+    }
+    for (const [focusId, team] of activeTeams) {
+        // Multi-product safety: only act on THIS product's teams (the global map
+        // holds every product's teams).
+        if (team.productId !== config.productId)
+            continue;
+        // Already stopping (cockpit Stop, deactivation teardown, or a prior reap).
+        if (team.phase === 'shutting_down' || team.phase === 'terminated')
+            continue;
+        if (pendingDisarmStops.has(focusId))
+            continue;
+        // Absent -> non-active focus -> owned by checkForDeactivatedFocuses.
+        if (!armed.has(focusId))
+            continue;
+        // Still armed (idle-but-armed / in review / paused) -> not a disarm.
+        if (armed.get(focusId))
+            continue;
+        log.info(`[disarm-reaper] Focus "${team.focusName}" disarmed (agent role cleared) -- ` +
+            `cooperatively stopping the running team`);
+        pendingDisarmStops.add(focusId);
+        deps.initiateCooperativeStop(focusId, {
+            shutdownReason: 'user_stopped',
+            message: 'This focus has been disarmed (its agent role was cleared via the dashboard Stop). ' +
+                'Commit your current work and exit.',
+        });
+    }
+}
+/**
+ * Get the set of suspended focus IDs (for testing).
+ */
+export function getSuspendedFocuses() {
+    return suspendedFocuses;
+}
+/**
+ * Clear all tracked suspended focuses (for testing).
+ */
+export function clearSuspendedFocuses() {
+    suspendedFocuses.clear();
+}
+/**
+ * Clear the reaper's in-flight-stop dedup set (for testing).
+ */
+export function clearPendingDisarmStops() {
+    pendingDisarmStops.clear();
+}
+//# sourceMappingURL=control-state.js.map

package/dist/shell/control-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-state.js","sourceRoot":"","sources":["../../src/shell/control-state.ts"],"names":[],"mappings":"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"}

package/dist/shell/crash-recovery.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Crash recovery: orphaned worktree cleanup and stale branch pruning.
+ *
+ * When the daemon crashes (SIGKILL, OOM, power loss), worktrees and branches
+ * persist on disk with no in-memory tracking. On restart this module scans
+ * the filesystem, reconciles against DB session state, and cleans up.
+ *
+ * Runs after initGit() and before startListeners() so the daemon starts clean.
+ */
+import type { DaemonConfig, AgentSession } from '../types/index.js';
+import { type CreateEscalationParams } from '../queries/issues.js';
+export interface OrphanedWorktree {
+    /** Absolute path to the worktree directory. */
+    worktreePath: string;
+    /** Git branch name (e.g. agent/developer/my-delivery). */
+    branchName: string;
+    /** DB session that was still marked active, if any. */
+    session: AgentSession | null;
+    /**
+     * True when this is UNREGISTERED residue: a directory under the worktree dir
+     * with no `git worktree list` entry (its branch name is INFERRED from the dir
+     * name and usually has no ref). There is no branch to diff, so its reap safety
+     * is judged by content reachability from integration, not the unmerged-commit
+     * check the registered-orphan path uses.
+     */
+    unregistered?: boolean;
+}
+export interface CleanupAction {
+    worktreePath: string;
+    branchName: string;
+    action: 'removed' | 'preserved' | 'safety-committed' | 'safety-committed-and-removed';
+    /** Set when a safety commit was created. */
+    commitHash?: string;
+    /** Set when the orphan was preserved due to unmerged commits. */
+    unmergedCommitCount?: number;
+    /**
+     * True when the worktree DIRECTORY was removed from disk. For an unmerged
+     * orphan the branch ref is preserved (cheap, recoverable) while the worktree
+     * dir is dropped (no detritus) -- so a preserved action can still have the
+     * worktree removed.
+     */
+    worktreeRemoved?: boolean;
+    /** True when the branch ref was preserved (kept, not deleted). */
+    branchPreserved?: boolean;
+    /**
+     * The 8-char focus-key suffix parsed from the branch name
+     * (agent/<role>/<slug>-<8hexfocuskey>). Used to anchor any residual signal to
+     * the owning focus.
+     */
+    focusKey?: string;
+    /**
+     * Full focus id resolved from `focusKey` (where resolvable). Filled in by the
+     * async cleanup pass so housekeeping records / escalations carry a real anchor.
+     */
+    resolvedFocusId?: string;
+    /**
+     * True only in the unrecoverable corner: the worktree was dirty and the safety
+     * commit FAILED, so the work is on no ref. The worktree is kept (dropping it
+     * would lose the work). */
+    workUncaptured?: boolean;
+}
+export interface RecoveryResult {
+    orphansDetected: number;
+    orphansCleaned: number;
+    orphansPreserved: number;
+    branchesPruned: number;
+    branchesPreserved: number;
+    actions: CleanupAction[];
+    errors: string[];
+}
+/**
+ * Injectable dependencies for testing.
+ * Production code uses the defaults (real DB queries).
+ */
+export interface RecoveryDeps {
+    getActiveSessions: () => Promise<AgentSession[]>;
+    getActiveFocuses: (organizationId: string, productId?: string) => Promise<Array<{
+        focus_id: string;
+        focus_name: string;
+        assigned_agent_role_id: string | null;
+    }>>;
+    updateSession: (sessionId: string, updates: Record<string, unknown>) => Promise<unknown>;
+    createEscalation: (params: CreateEscalationParams) => Promise<{
+        escalationId: string | null;
+    } | void>;
+    /**
+     * Best-effort resolution of an 8-char focus-key prefix (parsed from an orphan
+     * branch name) to a full focus id, so a residual housekeeping record /
+     * escalation can be anchored to the owning focus. Returns null when the focus
+     * cannot be resolved (e.g. the focus was deleted) -- anchoring then degrades
+     * to the always-known productId plus the focus_key carried in metadata.
+     */
+    resolveFocusByKeyPrefix: (keyPrefix: string, productId?: string) => Promise<{
+        focusId: string;
+        productId: string | null;
+    } | null>;
+    /**
+     * Remove a worktree directory (force) while leaving the branch ref intact.
+     * Defaults to `reapWorktreeAtomically` (base removal + a verified post-
+     * condition that no directory survives without its registration); injectable
+     * so the leftover-detritus path (returns false) is testable. False = dir not
+     * removed.
+     */
+    removeWorktreeDir: (repoPath: string, worktreePath: string) => boolean;
+}
+/**
+ * Parse `git worktree list --porcelain` to build a map of
+ * worktree path -> branch name for all registered worktrees.
+ */
+export declare function parseWorktreeList(repoPath: string): Map<string, string>;
+/**
+ * Scan the worktree directory and reconcile against active DB sessions
+ * to classify each worktree as active or orphaned.
+ */
+export declare function detectOrphanedWorktrees(config: DaemonConfig, deps?: RecoveryDeps): Promise<OrphanedWorktree[]>;
+/**
+ * Clean up all orphaned worktrees. Returns actions taken and
+ * any preserved orphans that need escalation.
+ */
+export declare function cleanupOrphanedWorktrees(orphans: OrphanedWorktree[], config: DaemonConfig, deps?: RecoveryDeps): Promise<CleanupAction[]>;
+/**
+ * Prune stale agent branches that have no worktree and no unmerged commits.
+ *
+ * Same housekeeping policy as the orphaned-worktree path: a branch with
+ * unmerged commits is PRESERVED and LOGGED (the commits are recoverable from
+ * the ref), never escalated. A merged branch with no worktree is safe to delete.
+ * No path here files a needs_operator escalation -- branch-only orphans are
+ * reality-side housekeeping the daemon owns.
+ */
+export declare function pruneStaleAgentBranches(config: DaemonConfig): {
+    pruned: string[];
+    preserved: string[];
+};
+/**
+ * Run full crash recovery: detect orphans, clean up, prune branches.
+ *
+ * Safe to call multiple times — idempotent by design. A second run
+ * with no new crashes finds nothing to clean.
+ */
+export declare function recoverFromCrash(config: DaemonConfig, deps?: RecoveryDeps): Promise<RecoveryResult>;
+//# sourceMappingURL=crash-recovery.d.ts.map

package/dist/shell/crash-recovery.d.ts.map

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