@herdctl/core 1.3.0 → 2.0.0

package/dist/state/session-validation.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Session validation utilities
+ *
+ * Provides timeout parsing and session expiration validation to prevent
+ * unexpected logouts when resuming expired sessions.
+ */
+import type { SessionInfo } from "./schemas/session-info.js";
+/**
+ * Result of session validation
+ */
+export interface SessionValidationResult {
+    /** Whether the session is valid (not expired) */
+    valid: boolean;
+    /** If invalid, the reason why */
+    reason?: "expired" | "missing" | "invalid_timeout" | "file_not_found" | "runtime_mismatch";
+    /** Human-readable message */
+    message?: string;
+    /** Age of the session in milliseconds */
+    ageMs?: number;
+    /** Configured timeout in milliseconds */
+    timeoutMs?: number;
+}
+/**
+ * Parse a timeout string into milliseconds
+ *
+ * Supports formats:
+ * - "30s" - 30 seconds
+ * - "5m" - 5 minutes
+ * - "1h" - 1 hour
+ * - "1d" - 1 day
+ * - "1w" - 1 week
+ *
+ * @param timeout - Timeout string (e.g., "30m", "1h")
+ * @returns Timeout in milliseconds, or null if invalid format
+ *
+ * @example
+ * ```typescript
+ * parseTimeout("30m"); // 1800000 (30 minutes in ms)
+ * parseTimeout("1h");  // 3600000 (1 hour in ms)
+ * parseTimeout("24h"); // 86400000 (24 hours in ms)
+ * parseTimeout("invalid"); // null
+ * ```
+ */
+export declare function parseTimeout(timeout: string): number | null;
+/**
+ * Default session timeout if not configured (24 hours)
+ * This is a reasonable default that prevents stale sessions from being resumed
+ * while still allowing long-running work sessions.
+ */
+export declare const DEFAULT_SESSION_TIMEOUT_MS: number;
+/**
+ * Check if a CLI session file exists on disk
+ *
+ * @param workingDirectory - Working directory for the session
+ * @param sessionId - Session ID to check
+ * @returns true if the session file exists
+ */
+export declare function cliSessionFileExists(workingDirectory: string, sessionId: string): Promise<boolean>;
+/**
+ * Check if a session has expired based on its last_used_at timestamp
+ *
+ * @param session - The session info to validate
+ * @param timeout - Timeout string (e.g., "30m", "1h") or undefined for default
+ * @returns Validation result with expiration details
+ *
+ * @example
+ * ```typescript
+ * const session = await getSessionInfo(sessionsDir, agentName);
+ * if (session) {
+ *   const validation = isSessionExpired(session, "1h");
+ *   if (!validation.valid) {
+ *     console.log(`Session expired: ${validation.message}`);
+ *     // Clear the session and start fresh
+ *   }
+ * }
+ * ```
+ */
+export declare function validateSession(session: SessionInfo | null, timeout?: string): SessionValidationResult;
+/**
+ * Validate a session including CLI session file existence check
+ *
+ * This async version of validateSession also checks if the CLI session file
+ * exists on disk (for CLI runtime sessions). Use this when validating sessions
+ * that will be resumed via CLI runtime.
+ *
+ * @param session - The session info to validate
+ * @param timeout - Timeout string (e.g., "30m", "1h") or undefined for default
+ * @returns Promise resolving to validation result
+ *
+ * @example
+ * ```typescript
+ * const session = await getSessionInfo(sessionsDir, agentName);
+ * if (session) {
+ *   const validation = await validateSessionWithFileCheck(session, "1h");
+ *   if (!validation.valid) {
+ *     console.log(`Session invalid: ${validation.message}`);
+ *     // Clear the session and start fresh
+ *   }
+ * }
+ * ```
+ */
+export declare function validateSessionWithFileCheck(session: SessionInfo | null, timeout?: string): Promise<SessionValidationResult>;
+/**
+ * Validate that a session's runtime context matches the current agent configuration
+ *
+ * Sessions are tied to a specific runtime configuration (SDK vs CLI, Docker vs native).
+ * If the runtime context changes, the session must be invalidated because:
+ * - CLI sessions use different session file locations than SDK sessions
+ * - Docker sessions are isolated from native sessions (different filesystems)
+ * - Session IDs are not portable across runtime contexts
+ *
+ * @param session - The session info to validate
+ * @param currentRuntimeType - Current runtime type from agent config ("sdk" or "cli")
+ * @param currentDockerEnabled - Current Docker enabled state from agent config
+ * @returns Validation result indicating if runtime context matches
+ *
+ * @example
+ * ```typescript
+ * const session = await getSessionInfo(sessionsDir, agentName);
+ * if (session) {
+ *   const validation = validateRuntimeContext(
+ *     session,
+ *     agent.runtime ?? "sdk",
+ *     agent.docker?.enabled ?? false
+ *   );
+ *   if (!validation.valid) {
+ *     console.log(`Runtime context mismatch: ${validation.message}`);
+ *     await clearSession(sessionsDir, agentName);
+ *   }
+ * }
+ * ```
+ */
+export declare function validateRuntimeContext(session: SessionInfo | null, currentRuntimeType: "sdk" | "cli", currentDockerEnabled: boolean): SessionValidationResult;
+/**
+ * Format a duration in milliseconds to a human-readable string
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Human-readable duration string
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Check if an error from the SDK indicates an expired or invalid session
+ *
+ * The SDK may return errors when trying to resume an expired session.
+ * This function helps identify such errors for proper handling.
+ *
+ * Common error patterns from Claude CLI/SDK:
+ * - "session expired" / "session_expired" - explicit expiration
+ * - "session not found" / "invalid session" - session doesn't exist on server
+ * - "resume failed" - generic resume failure
+ * - "conversation not found" / "no conversation" - conversation ID invalid
+ * - "cannot resume" / "unable to resume" - resume operation failed
+ * - "stale session" - session is too old
+ *
+ * Also checks error codes for structured error responses.
+ *
+ * @param error - The error to check
+ * @returns true if this appears to be a session expiration error
+ */
+export declare function isSessionExpiredError(error: Error): boolean;
+/**
+ * Result of cleaning up expired sessions
+ */
+export interface CleanupResult {
+    /** Number of sessions that were expired and removed */
+    removed: number;
+    /** Number of valid sessions that were kept */
+    kept: number;
+    /** Names of agents whose sessions were removed */
+    removedAgents: string[];
+}
+/**
+ * Clean up expired sessions from the sessions directory
+ *
+ * This function checks all sessions and removes those that have expired
+ * based on the provided timeout. Useful for periodic cleanup or startup.
+ *
+ * @param sessionsDir - Path to the sessions directory
+ * @param timeout - Timeout string (e.g., "24h") or undefined for default
+ * @param options - Additional options
+ * @returns Result containing counts and removed agent names
+ *
+ * @example
+ * ```typescript
+ * import { cleanupExpiredSessions } from "./state";
+ *
+ * // Clean up sessions older than 24 hours (default)
+ * const result = await cleanupExpiredSessions(sessionsDir);
+ * console.log(`Removed ${result.removed} expired sessions`);
+ *
+ * // Clean up sessions older than 1 hour
+ * const result = await cleanupExpiredSessions(sessionsDir, "1h");
+ * ```
+ */
+export declare function cleanupExpiredSessions(sessionsDir: string, timeout?: string, options?: {
+    logger?: {
+        info?: (msg: string) => void;
+        warn: (msg: string) => void;
+    };
+    dryRun?: boolean;
+}): Promise<CleanupResult>;
+//# sourceMappingURL=session-validation.d.ts.map

package/dist/state/session-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-validation.d.ts","sourceRoot":"","sources":["../../src/state/session-validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAM7D;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,KAAK,EAAE,OAAO,CAAC;IACf,iCAAiC;IACjC,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;IAC3F,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuB3D;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,QAAsB,CAAC;AAM9D;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,gBAAgB,EAAE,MAAM,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAQlB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,OAAO,CAAC,EAAE,MAAM,GACf,uBAAuB,CAuEzB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,uBAAuB,CAAC,CA0BlC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,kBAAkB,EAAE,KAAK,GAAG,KAAK,EACjC,oBAAoB,EAAE,OAAO,GAC5B,uBAAuB,CAiCzB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAgBjD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAsC3D;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE;IACP,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IACvE,MAAM,CAAC,EAAE,OAAO,CAAC;CACb,GACL,OAAO,CAAC,aAAa,CAAC,CA4CxB"}

package/dist/state/session-validation.js

@@ -0,0 +1,407 @@
+/**
+ * Session validation utilities
+ *
+ * Provides timeout parsing and session expiration validation to prevent
+ * unexpected logouts when resuming expired sessions.
+ */
+import { access } from "node:fs/promises";
+import { getCliSessionFile } from "../runner/runtime/cli-session-path.js";
+// =============================================================================
+// Timeout Parsing
+// =============================================================================
+/**
+ * Parse a timeout string into milliseconds
+ *
+ * Supports formats:
+ * - "30s" - 30 seconds
+ * - "5m" - 5 minutes
+ * - "1h" - 1 hour
+ * - "1d" - 1 day
+ * - "1w" - 1 week
+ *
+ * @param timeout - Timeout string (e.g., "30m", "1h")
+ * @returns Timeout in milliseconds, or null if invalid format
+ *
+ * @example
+ * ```typescript
+ * parseTimeout("30m"); // 1800000 (30 minutes in ms)
+ * parseTimeout("1h");  // 3600000 (1 hour in ms)
+ * parseTimeout("24h"); // 86400000 (24 hours in ms)
+ * parseTimeout("invalid"); // null
+ * ```
+ */
+export function parseTimeout(timeout) {
+    const match = timeout.match(/^(\d+(?:\.\d+)?)(s|m|h|d|w)$/);
+    if (!match) {
+        return null;
+    }
+    const value = parseFloat(match[1]);
+    const unit = match[2];
+    switch (unit) {
+        case "s":
+            return value * 1000;
+        case "m":
+            return value * 60 * 1000;
+        case "h":
+            return value * 60 * 60 * 1000;
+        case "d":
+            return value * 24 * 60 * 60 * 1000;
+        case "w":
+            return value * 7 * 24 * 60 * 60 * 1000;
+        default:
+            return null;
+    }
+}
+/**
+ * Default session timeout if not configured (24 hours)
+ * This is a reasonable default that prevents stale sessions from being resumed
+ * while still allowing long-running work sessions.
+ */
+export const DEFAULT_SESSION_TIMEOUT_MS = 24 * 60 * 60 * 1000; // 24 hours
+// =============================================================================
+// Session Validation
+// =============================================================================
+/**
+ * Check if a CLI session file exists on disk
+ *
+ * @param workingDirectory - Working directory for the session
+ * @param sessionId - Session ID to check
+ * @returns true if the session file exists
+ */
+export async function cliSessionFileExists(workingDirectory, sessionId) {
+    try {
+        const sessionFile = getCliSessionFile(workingDirectory, sessionId);
+        await access(sessionFile);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a session has expired based on its last_used_at timestamp
+ *
+ * @param session - The session info to validate
+ * @param timeout - Timeout string (e.g., "30m", "1h") or undefined for default
+ * @returns Validation result with expiration details
+ *
+ * @example
+ * ```typescript
+ * const session = await getSessionInfo(sessionsDir, agentName);
+ * if (session) {
+ *   const validation = isSessionExpired(session, "1h");
+ *   if (!validation.valid) {
+ *     console.log(`Session expired: ${validation.message}`);
+ *     // Clear the session and start fresh
+ *   }
+ * }
+ * ```
+ */
+export function validateSession(session, timeout) {
+    // Handle missing session
+    if (!session) {
+        return {
+            valid: false,
+            reason: "missing",
+            message: "No session found",
+        };
+    }
+    // Parse timeout or use default
+    let timeoutMs;
+    if (timeout) {
+        const parsed = parseTimeout(timeout);
+        if (parsed === null) {
+            return {
+                valid: false,
+                reason: "invalid_timeout",
+                message: `Invalid timeout format: "${timeout}". Expected format like "30m", "1h", "24h"`,
+            };
+        }
+        timeoutMs = parsed;
+    }
+    else {
+        timeoutMs = DEFAULT_SESSION_TIMEOUT_MS;
+    }
+    // Calculate session age from last_used_at
+    const lastUsedAt = new Date(session.last_used_at).getTime();
+    const now = Date.now();
+    const ageMs = now - lastUsedAt;
+    // Handle invalid date parsing (NaN) - treat as expired to force a fresh session
+    // This prevents unexpected behavior from corrupted session files
+    if (Number.isNaN(ageMs)) {
+        return {
+            valid: false,
+            reason: "expired",
+            message: `Session has invalid last_used_at timestamp: "${session.last_used_at}"`,
+            timeoutMs,
+        };
+    }
+    // Handle future timestamps (negative age) - could indicate clock skew or timezone issues
+    // Treat as valid but log the unusual state; the session will be refreshed on next use
+    if (ageMs < 0) {
+        return {
+            valid: true,
+            ageMs: 0, // Report as just used
+            timeoutMs,
+        };
+    }
+    // Check if expired
+    if (ageMs > timeoutMs) {
+        const ageMinutes = Math.round(ageMs / (60 * 1000));
+        const timeoutMinutes = Math.round(timeoutMs / (60 * 1000));
+        return {
+            valid: false,
+            reason: "expired",
+            message: `Session expired: last used ${formatDuration(ageMs)} ago, timeout is ${formatDuration(timeoutMs)}`,
+            ageMs,
+            timeoutMs,
+        };
+    }
+    return {
+        valid: true,
+        ageMs,
+        timeoutMs,
+    };
+}
+/**
+ * Validate a session including CLI session file existence check
+ *
+ * This async version of validateSession also checks if the CLI session file
+ * exists on disk (for CLI runtime sessions). Use this when validating sessions
+ * that will be resumed via CLI runtime.
+ *
+ * @param session - The session info to validate
+ * @param timeout - Timeout string (e.g., "30m", "1h") or undefined for default
+ * @returns Promise resolving to validation result
+ *
+ * @example
+ * ```typescript
+ * const session = await getSessionInfo(sessionsDir, agentName);
+ * if (session) {
+ *   const validation = await validateSessionWithFileCheck(session, "1h");
+ *   if (!validation.valid) {
+ *     console.log(`Session invalid: ${validation.message}`);
+ *     // Clear the session and start fresh
+ *   }
+ * }
+ * ```
+ */
+export async function validateSessionWithFileCheck(session, timeout) {
+    // First do basic validation (expiration, etc.)
+    const basicValidation = validateSession(session, timeout);
+    if (!basicValidation.valid) {
+        return basicValidation;
+    }
+    // If session exists and isn't expired, check if CLI session file exists
+    if (session && session.working_directory) {
+        const fileExists = await cliSessionFileExists(session.working_directory, session.session_id);
+        if (!fileExists) {
+            return {
+                valid: false,
+                reason: "file_not_found",
+                message: `CLI session file not found for session ${session.session_id}`,
+                ageMs: basicValidation.ageMs,
+                timeoutMs: basicValidation.timeoutMs,
+            };
+        }
+    }
+    return basicValidation;
+}
+/**
+ * Validate that a session's runtime context matches the current agent configuration
+ *
+ * Sessions are tied to a specific runtime configuration (SDK vs CLI, Docker vs native).
+ * If the runtime context changes, the session must be invalidated because:
+ * - CLI sessions use different session file locations than SDK sessions
+ * - Docker sessions are isolated from native sessions (different filesystems)
+ * - Session IDs are not portable across runtime contexts
+ *
+ * @param session - The session info to validate
+ * @param currentRuntimeType - Current runtime type from agent config ("sdk" or "cli")
+ * @param currentDockerEnabled - Current Docker enabled state from agent config
+ * @returns Validation result indicating if runtime context matches
+ *
+ * @example
+ * ```typescript
+ * const session = await getSessionInfo(sessionsDir, agentName);
+ * if (session) {
+ *   const validation = validateRuntimeContext(
+ *     session,
+ *     agent.runtime ?? "sdk",
+ *     agent.docker?.enabled ?? false
+ *   );
+ *   if (!validation.valid) {
+ *     console.log(`Runtime context mismatch: ${validation.message}`);
+ *     await clearSession(sessionsDir, agentName);
+ *   }
+ * }
+ * ```
+ */
+export function validateRuntimeContext(session, currentRuntimeType, currentDockerEnabled) {
+    // Handle missing session
+    if (!session) {
+        return {
+            valid: false,
+            reason: "missing",
+            message: "No session found",
+        };
+    }
+    // Check runtime type mismatch
+    if (session.runtime_type !== currentRuntimeType) {
+        return {
+            valid: false,
+            reason: "runtime_mismatch",
+            message: `Runtime type changed from "${session.runtime_type}" to "${currentRuntimeType}". Session must be recreated for the new runtime.`,
+        };
+    }
+    // Check Docker enabled mismatch
+    if (session.docker_enabled !== currentDockerEnabled) {
+        const oldContext = session.docker_enabled ? "Docker" : "native";
+        const newContext = currentDockerEnabled ? "Docker" : "native";
+        return {
+            valid: false,
+            reason: "runtime_mismatch",
+            message: `Docker context changed from ${oldContext} to ${newContext}. Session must be recreated for the new context.`,
+        };
+    }
+    return {
+        valid: true,
+    };
+}
+/**
+ * Format a duration in milliseconds to a human-readable string
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Human-readable duration string
+ */
+export function formatDuration(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0) {
+        return `${days}d ${hours % 24}h`;
+    }
+    if (hours > 0) {
+        return `${hours}h ${minutes % 60}m`;
+    }
+    if (minutes > 0) {
+        return `${minutes}m`;
+    }
+    return `${seconds}s`;
+}
+/**
+ * Check if an error from the SDK indicates an expired or invalid session
+ *
+ * The SDK may return errors when trying to resume an expired session.
+ * This function helps identify such errors for proper handling.
+ *
+ * Common error patterns from Claude CLI/SDK:
+ * - "session expired" / "session_expired" - explicit expiration
+ * - "session not found" / "invalid session" - session doesn't exist on server
+ * - "resume failed" - generic resume failure
+ * - "conversation not found" / "no conversation" - conversation ID invalid
+ * - "cannot resume" / "unable to resume" - resume operation failed
+ * - "stale session" - session is too old
+ *
+ * Also checks error codes for structured error responses.
+ *
+ * @param error - The error to check
+ * @returns true if this appears to be a session expiration error
+ */
+export function isSessionExpiredError(error) {
+    const message = error.message.toLowerCase();
+    // Check error codes for structured errors (e.g., from SDK responses)
+    const errorCode = error.code?.toLowerCase() ?? "";
+    if (errorCode === "session_expired" ||
+        errorCode === "invalid_session" ||
+        errorCode === "session_not_found" ||
+        errorCode === "conversation_expired" ||
+        errorCode === "conversation_not_found") {
+        return true;
+    }
+    return (
+    // Explicit session expiration
+    message.includes("session expired") ||
+        message.includes("session_expired") ||
+        message.includes("has expired") ||
+        message.includes("stale session") ||
+        // Session not found on server
+        message.includes("session not found") ||
+        message.includes("invalid session") ||
+        message.includes("session does not exist") ||
+        message.includes("session id") && message.includes("not found") ||
+        // Conversation/context issues (Claude CLI uses these)
+        message.includes("conversation not found") ||
+        message.includes("no conversation") ||
+        message.includes("conversation does not exist") ||
+        message.includes("invalid conversation") ||
+        // Resume operation failures
+        message.includes("resume failed") ||
+        message.includes("cannot resume") ||
+        message.includes("unable to resume") ||
+        message.includes("failed to resume") ||
+        message.includes("could not resume"));
+}
+/**
+ * Clean up expired sessions from the sessions directory
+ *
+ * This function checks all sessions and removes those that have expired
+ * based on the provided timeout. Useful for periodic cleanup or startup.
+ *
+ * @param sessionsDir - Path to the sessions directory
+ * @param timeout - Timeout string (e.g., "24h") or undefined for default
+ * @param options - Additional options
+ * @returns Result containing counts and removed agent names
+ *
+ * @example
+ * ```typescript
+ * import { cleanupExpiredSessions } from "./state";
+ *
+ * // Clean up sessions older than 24 hours (default)
+ * const result = await cleanupExpiredSessions(sessionsDir);
+ * console.log(`Removed ${result.removed} expired sessions`);
+ *
+ * // Clean up sessions older than 1 hour
+ * const result = await cleanupExpiredSessions(sessionsDir, "1h");
+ * ```
+ */
+export async function cleanupExpiredSessions(sessionsDir, timeout, options = {}) {
+    const { logger = console, dryRun = false } = options;
+    // Import dynamically to avoid circular dependencies
+    const { listSessions, clearSession } = await import("./session.js");
+    const result = {
+        removed: 0,
+        kept: 0,
+        removedAgents: [],
+    };
+    // List all sessions
+    const sessions = await listSessions(sessionsDir, { logger });
+    for (const session of sessions) {
+        const validation = validateSession(session, timeout);
+        if (!validation.valid && validation.reason === "expired") {
+            if (!dryRun) {
+                try {
+                    await clearSession(sessionsDir, session.agent_name);
+                    result.removed++;
+                    result.removedAgents.push(session.agent_name);
+                    logger.info?.(`Cleaned up expired session for ${session.agent_name}`);
+                }
+                catch (error) {
+                    logger.warn(`Failed to clean up session for ${session.agent_name}: ${error.message}`);
+                }
+            }
+            else {
+                // Dry run - just count
+                result.removed++;
+                result.removedAgents.push(session.agent_name);
+                logger.info?.(`[DRY RUN] Would clean up expired session for ${session.agent_name}`);
+            }
+        }
+        else {
+            result.kept++;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=session-validation.js.map

package/dist/state/session-validation.js.map

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

package/dist/state/session.d.ts

@@ -11,6 +11,18 @@ import { type SessionInfo } from "./schemas/session-info.js";
 export interface SessionOptions {
     /** Logger for warnings */
     logger?: SessionLogger;
+    /**
+     * Session expiry timeout string (e.g., "24h", "30m").
+     * If provided, expired sessions will be treated as non-existent and automatically cleared.
+     * This prevents stale session IDs from being used for resume attempts.
+     */
+    timeout?: string;
+    /**
+     * Runtime type ("cli" or "sdk").
+     * If "cli", validates that CLI session files exist on disk.
+     * If "sdk" or undefined, only validates expiration (no file check).
+     */
+    runtime?: "cli" | "sdk";
 }
 /**
  * Logger interface for session operations
@@ -25,21 +37,29 @@ export type SessionInfoUpdates = Partial<Omit<SessionInfo, "agent_name" | "creat
 /**
  * Get session info for an agent
  *
- * Returns null if no session exists (handles missing file gracefully).
+ * Returns null if no session exists, is corrupted, or has expired.
+ * When a timeout is provided, expired sessions are automatically cleared
+ * to prevent stale session IDs from being used for resume attempts.
  *
  * @param sessionsDir - Path to the sessions directory
  * @param agentName - Name of the agent
- * @param options - Optional operation options
- * @returns The session info, or null if not found
+ * @param options - Optional operation options including timeout for expiry validation
+ * @returns The session info, or null if not found/expired
  *
  * @example
  * ```typescript
+ * // Get session without expiry validation
  * const session = await getSessionInfo('/path/to/.herdctl/sessions', 'my-agent');
  * if (session) {
  *   console.log(`Session ${session.session_id} has ${session.job_count} jobs`);
  * } else {
  *   console.log('No existing session');
  * }
+ *
+ * // Get session with 24-hour expiry validation (prevents unexpected logouts)
+ * const session = await getSessionInfo('/path/to/.herdctl/sessions', 'my-agent', {
+ *   timeout: '24h'  // Sessions older than 24 hours will be treated as expired
+ * });
  * ```
  */
 export declare function getSessionInfo(sessionsDir: string, agentName: string, options?: SessionOptions): Promise<SessionInfo | null>;