opentasks 0.0.6 → 0.0.7

package/dist/sessionlog/security/redaction.js

@@ -0,0 +1,221 @@
+/**
+ * Secret Redaction
+ *
+ * Multi-layered secret detection and redaction for transcripts.
+ * Uses both entropy-based detection and pattern matching
+ * for known secret formats.
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+const ENTROPY_THRESHOLD = 4.5;
+const MIN_SECRET_LENGTH = 10;
+const REDACTED_PLACEHOLDER = 'REDACTED';
+/** High-entropy alphanumeric pattern (potential secrets) */
+const HIGH_ENTROPY_PATTERN = /[A-Za-z0-9+_=-]{10,}/g;
+// ============================================================================
+// Known Secret Patterns (subset of gitleaks rules)
+// ============================================================================
+const SECRET_PATTERNS = [
+    // API Keys
+    { name: 'aws-access-key', pattern: /(?:A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}/g },
+    { name: 'aws-secret-key', pattern: /(?:aws_secret_access_key|aws_secret_key|secret_key)\s*[=:]\s*["']?([A-Za-z0-9/+=]{40})["']?/gi },
+    { name: 'github-token', pattern: /gh[pousr]_[A-Za-z0-9_]{36,255}/g },
+    { name: 'github-fine-grained', pattern: /github_pat_[A-Za-z0-9_]{22,255}/g },
+    { name: 'gitlab-token', pattern: /glpat-[A-Za-z0-9\-=_]{20,}/g },
+    { name: 'google-api-key', pattern: /AIza[A-Za-z0-9_\-]{35}/g },
+    { name: 'slack-token', pattern: /xox[baprs]-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}/g },
+    { name: 'slack-webhook', pattern: /https:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]{10}\/B[A-Z0-9]{10}\/[a-zA-Z0-9]{24}/g },
+    { name: 'stripe-key', pattern: /(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{10,99}/g },
+    { name: 'twilio-api-key', pattern: /SK[0-9a-fA-F]{32}/g },
+    { name: 'sendgrid-api-key', pattern: /SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}/g },
+    { name: 'npm-token', pattern: /npm_[A-Za-z0-9]{36}/g },
+    { name: 'pypi-token', pattern: /pypi-[A-Za-z0-9_-]{100,}/g },
+    // Cloud Providers
+    { name: 'azure-connection-string', pattern: /DefaultEndpointsProtocol=https;AccountName=[^;]+;AccountKey=[A-Za-z0-9+/=]{88};/g },
+    { name: 'gcp-service-account', pattern: /"private_key":\s*"-----BEGIN (?:RSA )?PRIVATE KEY-----/g },
+    // Generic Secrets
+    { name: 'private-key', pattern: /-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/g },
+    { name: 'jwt', pattern: /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g },
+    { name: 'basic-auth', pattern: /(?:basic|bearer)\s+[A-Za-z0-9+/=]{20,}/gi },
+    { name: 'password-in-url', pattern: /[a-zA-Z]{3,10}:\/\/[^/\s:@]{3,20}:[^/\s@]{3,20}@/g },
+    // Anthropic
+    { name: 'anthropic-api-key', pattern: /sk-ant-[A-Za-z0-9_-]{90,}/g },
+    // OpenAI
+    { name: 'openai-api-key', pattern: /sk-[A-Za-z0-9]{20}T3BlbkFJ[A-Za-z0-9]{20}/g },
+    // Database
+    { name: 'postgres-url', pattern: /postgres(?:ql)?:\/\/[^/\s:@]+:[^/\s@]+@[^/\s]+\/[^/\s]+/g },
+    { name: 'mysql-url', pattern: /mysql:\/\/[^/\s:@]+:[^/\s@]+@[^/\s]+\/[^/\s]+/g },
+    { name: 'mongodb-url', pattern: /mongodb(?:\+srv)?:\/\/[^/\s:@]+:[^/\s@]+@[^/\s]+/g },
+    // Hex-encoded secrets (generic)
+    { name: 'hex-secret', pattern: /(?:secret|token|key|password|api_key|apikey)\s*[=:]\s*["']?([0-9a-fA-F]{32,})["']?/gi },
+];
+// Fields that should be skipped during redaction
+const SAFE_FIELDS = new Set([
+    'signature',
+    'id',
+    'uuid',
+    'sessionId',
+    'session_id',
+    'checkpointId',
+    'checkpoint_id',
+    'nodeId',
+    'node_id',
+    'toolUseId',
+    'tool_use_id',
+    'file_path',
+    'filePath',
+    'path',
+    'name',
+    'type',
+    'role',
+]);
+// ============================================================================
+// Entropy Calculation
+// ============================================================================
+/**
+ * Calculate Shannon entropy of a string
+ */
+export function shannonEntropy(s) {
+    if (s.length === 0)
+        return 0;
+    const freq = new Map();
+    for (const ch of s) {
+        freq.set(ch, (freq.get(ch) ?? 0) + 1);
+    }
+    let entropy = 0;
+    for (const count of freq.values()) {
+        const p = count / s.length;
+        if (p > 0)
+            entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+/**
+ * Merge overlapping regions
+ */
+function mergeRegions(regions) {
+    if (regions.length === 0)
+        return [];
+    const sorted = [...regions].sort((a, b) => a.start - b.start);
+    const merged = [sorted[0]];
+    for (let i = 1; i < sorted.length; i++) {
+        const last = merged[merged.length - 1];
+        if (sorted[i].start <= last.end) {
+            last.end = Math.max(last.end, sorted[i].end);
+        }
+        else {
+            merged.push(sorted[i]);
+        }
+    }
+    return merged;
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Detect secret regions in a string
+ */
+export function detectSecrets(text) {
+    const regions = [];
+    // Entropy-based detection
+    for (const match of text.matchAll(HIGH_ENTROPY_PATTERN)) {
+        const value = match[0];
+        if (value.length < MIN_SECRET_LENGTH)
+            continue;
+        if (shannonEntropy(value) >= ENTROPY_THRESHOLD) {
+            regions.push({
+                start: match.index,
+                end: match.index + value.length,
+                source: 'entropy',
+            });
+        }
+    }
+    // Pattern-based detection
+    for (const { name, pattern } of SECRET_PATTERNS) {
+        // Reset regex state
+        pattern.lastIndex = 0;
+        for (const match of text.matchAll(pattern)) {
+            regions.push({
+                start: match.index,
+                end: match.index + match[0].length,
+                source: name,
+            });
+        }
+    }
+    return mergeRegions(regions);
+}
+/**
+ * Redact secrets from a plain string
+ */
+export function redactString(text) {
+    const regions = detectSecrets(text);
+    if (regions.length === 0)
+        return text;
+    let result = '';
+    let pos = 0;
+    for (const region of regions) {
+        result += text.slice(pos, region.start);
+        result += REDACTED_PLACEHOLDER;
+        pos = region.end;
+    }
+    result += text.slice(pos);
+    return result;
+}
+/**
+ * Redact secrets from a Buffer
+ */
+export function redactBuffer(buf) {
+    return Buffer.from(redactString(buf.toString('utf-8')));
+}
+/**
+ * Redact secrets from JSONL content (line by line)
+ * Preserves JSON structure and skips safe fields
+ */
+export function redactJSONL(content) {
+    const lines = content.split('\n');
+    const result = [];
+    for (const line of lines) {
+        if (!line.trim()) {
+            result.push(line);
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(line);
+            const redacted = redactJSONValue(parsed);
+            result.push(JSON.stringify(redacted));
+        }
+        catch {
+            // Not valid JSON, redact as plain text
+            result.push(redactString(line));
+        }
+    }
+    return result.join('\n');
+}
+/**
+ * Recursively redact values in a JSON object
+ */
+function redactJSONValue(value, key) {
+    // Skip safe fields
+    if (key && SAFE_FIELDS.has(key))
+        return value;
+    if (typeof value === 'string') {
+        return redactString(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => redactJSONValue(item));
+    }
+    if (value && typeof value === 'object') {
+        const obj = value;
+        // Skip image/base64 objects
+        if (obj.type === 'image' || obj.type === 'base64')
+            return value;
+        const result = {};
+        for (const [k, v] of Object.entries(obj)) {
+            result[k] = redactJSONValue(v, k);
+        }
+        return result;
+    }
+    return value;
+}
+//# sourceMappingURL=redaction.js.map

package/dist/sessionlog/security/redaction.js.map

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

package/dist/sessionlog/session/state-machine.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Session State Machine
+ *
+ * Pure-function state machine for session lifecycle transitions.
+ * Ported from Go: session/phase.go
+ *
+ * The state machine computes the next phase and required actions given the
+ * current phase and an event. ApplyTransition executes side effects.
+ */
+export type Phase = 'active' | 'idle' | 'ended';
+/**
+ * Normalize a phase string, treating empty or unknown values as 'idle'
+ * for backward compatibility with pre-state-machine session files.
+ */
+export declare function phaseFromString(s: string | undefined): Phase;
+export declare const enum StateMachineEvent {
+    TurnStart = 0,
+    TurnEnd = 1,
+    GitCommit = 2,
+    SessionStart = 3,
+    SessionStop = 4,
+    Compaction = 5
+}
+export declare function eventToString(e: StateMachineEvent): string;
+export declare const enum Action {
+    Condense = 0,
+    CondenseIfFilesTouched = 1,
+    DiscardIfNoFiles = 2,
+    WarnStaleSession = 3,
+    ClearEndedAt = 4,
+    UpdateLastInteraction = 5
+}
+export declare function actionToString(a: Action): string;
+export interface TransitionContext {
+    hasFilesTouched: boolean;
+    isRebaseInProgress: boolean;
+}
+export interface TransitionResult {
+    newPhase: Phase;
+    actions: Action[];
+}
+export declare function transition(current: Phase, event: StateMachineEvent, ctx: TransitionContext): TransitionResult;
+export interface ActionHandler {
+    handleCondense(state: StateMachineState): Promise<void>;
+    handleCondenseIfFilesTouched(state: StateMachineState): Promise<void>;
+    handleDiscardIfNoFiles(state: StateMachineState): Promise<void>;
+    handleWarnStaleSession(state: StateMachineState): Promise<void>;
+}
+export declare class NoOpActionHandler implements ActionHandler {
+    handleCondense(): Promise<void>;
+    handleCondenseIfFilesTouched(): Promise<void>;
+    handleDiscardIfNoFiles(): Promise<void>;
+    handleWarnStaleSession(): Promise<void>;
+}
+export interface StateMachineState {
+    sessionID: string;
+    phase: Phase;
+    filesTouched: string[];
+    lastInteractionTime?: string;
+    endedAt?: string;
+}
+/**
+ * Apply a TransitionResult to state: sets the new phase, then executes
+ * all actions. Common actions (UpdateLastInteraction, ClearEndedAt)
+ * always run. Strategy-specific handler actions stop on first error.
+ */
+export declare function applyTransition(state: StateMachineState, result: TransitionResult, handler: ActionHandler): Promise<Error | null>;
+/** Duration after which a session is considered stale (7 days) */
+export declare const STALE_SESSION_THRESHOLD_MS: number;
+/**
+ * Returns true when the session's last interaction exceeds the stale threshold.
+ */
+export declare function isStale(lastInteractionTime: string | undefined): boolean;
+/**
+ * Normalize session state after loading from disk.
+ * Migrates legacy phase values and deprecated transcript fields.
+ */
+export declare function normalizeAfterLoad(state: {
+    phase?: string;
+    checkpointTranscriptStart?: number;
+    condensedTranscriptLines?: number;
+    transcriptLinesAtStart?: number;
+    attributionBaseCommit?: string;
+    baseCommit?: string;
+}): void;
+/**
+ * Generate a Mermaid state diagram from the transition table.
+ */
+export declare function mermaidDiagram(): string;
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/sessionlog/session/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../../src/sessionlog/session/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,CAa5D;AAMD,0BAAkB,iBAAiB;IACjC,SAAS,IAAI;IACb,OAAO,IAAI;IACX,SAAS,IAAI;IACb,YAAY,IAAI;IAChB,WAAW,IAAI;IACf,UAAU,IAAI;CACf;AAWD,wBAAgB,aAAa,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAiB1D;AAMD,0BAAkB,MAAM;IACtB,QAAQ,IAAI;IACZ,sBAAsB,IAAI;IAC1B,gBAAgB,IAAI;IACpB,gBAAgB,IAAI;IACpB,YAAY,IAAI;IAChB,qBAAqB,IAAI;CAC1B;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAiBhD;AAMD,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,KAAK,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAMD,wBAAgB,UAAU,CACxB,OAAO,EAAE,KAAK,EACd,KAAK,EAAE,iBAAiB,EACxB,GAAG,EAAE,iBAAiB,GACrB,gBAAgB,CAalB;AA8HD,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,4BAA4B,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,sBAAsB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,sBAAsB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAED,qBAAa,iBAAkB,YAAW,aAAa;IAC/C,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAC/B,4BAA4B,IAAI,OAAO,CAAC,IAAI,CAAC;IAC7C,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IACvC,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;CAC9C;AAMD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAqDvB;AAMD,kEAAkE;AAClE,eAAO,MAAM,0BAA0B,QAA0B,CAAC;AAElE;;GAEG;AACH,wBAAgB,OAAO,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAGxE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,IAAI,CAoBP;AAQD;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CA8CvC"}

package/dist/sessionlog/session/state-machine.js

@@ -0,0 +1,347 @@
+/**
+ * Session State Machine
+ *
+ * Pure-function state machine for session lifecycle transitions.
+ * Ported from Go: session/phase.go
+ *
+ * The state machine computes the next phase and required actions given the
+ * current phase and an event. ApplyTransition executes side effects.
+ */
+/**
+ * Normalize a phase string, treating empty or unknown values as 'idle'
+ * for backward compatibility with pre-state-machine session files.
+ */
+export function phaseFromString(s) {
+    switch (s) {
+        case 'active':
+        case 'active_committed':
+            // "active_committed" was removed with the 1:1 checkpoint model.
+            return 'active';
+        case 'idle':
+            return 'idle';
+        case 'ended':
+            return 'ended';
+        default:
+            return 'idle';
+    }
+}
+const ALL_EVENTS = [
+    0 /* StateMachineEvent.TurnStart */,
+    1 /* StateMachineEvent.TurnEnd */,
+    2 /* StateMachineEvent.GitCommit */,
+    3 /* StateMachineEvent.SessionStart */,
+    4 /* StateMachineEvent.SessionStop */,
+    5 /* StateMachineEvent.Compaction */,
+];
+export function eventToString(e) {
+    switch (e) {
+        case 0 /* StateMachineEvent.TurnStart */:
+            return 'TurnStart';
+        case 1 /* StateMachineEvent.TurnEnd */:
+            return 'TurnEnd';
+        case 2 /* StateMachineEvent.GitCommit */:
+            return 'GitCommit';
+        case 3 /* StateMachineEvent.SessionStart */:
+            return 'SessionStart';
+        case 4 /* StateMachineEvent.SessionStop */:
+            return 'SessionStop';
+        case 5 /* StateMachineEvent.Compaction */:
+            return 'Compaction';
+        default:
+            return `Event(${e})`;
+    }
+}
+export function actionToString(a) {
+    switch (a) {
+        case 0 /* Action.Condense */:
+            return 'Condense';
+        case 1 /* Action.CondenseIfFilesTouched */:
+            return 'CondenseIfFilesTouched';
+        case 2 /* Action.DiscardIfNoFiles */:
+            return 'DiscardIfNoFiles';
+        case 3 /* Action.WarnStaleSession */:
+            return 'WarnStaleSession';
+        case 4 /* Action.ClearEndedAt */:
+            return 'ClearEndedAt';
+        case 5 /* Action.UpdateLastInteraction */:
+            return 'UpdateLastInteraction';
+        default:
+            return `Action(${a})`;
+    }
+}
+// ============================================================================
+// Transition — pure function, no side effects
+// ============================================================================
+export function transition(current, event, ctx) {
+    current = phaseFromString(current);
+    switch (current) {
+        case 'idle':
+            return transitionFromIdle(event, ctx);
+        case 'active':
+            return transitionFromActive(event, ctx);
+        case 'ended':
+            return transitionFromEnded(event, ctx);
+        default:
+            return { newPhase: 'idle', actions: [] };
+    }
+}
+function transitionFromIdle(event, ctx) {
+    switch (event) {
+        case 0 /* StateMachineEvent.TurnStart */:
+            return {
+                newPhase: 'active',
+                actions: [5 /* Action.UpdateLastInteraction */],
+            };
+        case 1 /* StateMachineEvent.TurnEnd */:
+            return { newPhase: 'idle', actions: [] };
+        case 2 /* StateMachineEvent.GitCommit */:
+            if (ctx.isRebaseInProgress) {
+                return { newPhase: 'idle', actions: [] };
+            }
+            return {
+                newPhase: 'idle',
+                actions: [0 /* Action.Condense */, 5 /* Action.UpdateLastInteraction */],
+            };
+        case 3 /* StateMachineEvent.SessionStart */:
+            return { newPhase: 'idle', actions: [] };
+        case 4 /* StateMachineEvent.SessionStop */:
+            return {
+                newPhase: 'ended',
+                actions: [5 /* Action.UpdateLastInteraction */],
+            };
+        case 5 /* StateMachineEvent.Compaction */:
+            return {
+                newPhase: 'idle',
+                actions: [1 /* Action.CondenseIfFilesTouched */, 5 /* Action.UpdateLastInteraction */],
+            };
+        default:
+            return { newPhase: 'idle', actions: [] };
+    }
+}
+function transitionFromActive(event, ctx) {
+    switch (event) {
+        case 0 /* StateMachineEvent.TurnStart */:
+            return {
+                newPhase: 'active',
+                actions: [5 /* Action.UpdateLastInteraction */],
+            };
+        case 1 /* StateMachineEvent.TurnEnd */:
+            return {
+                newPhase: 'idle',
+                actions: [5 /* Action.UpdateLastInteraction */],
+            };
+        case 2 /* StateMachineEvent.GitCommit */:
+            if (ctx.isRebaseInProgress) {
+                return { newPhase: 'active', actions: [] };
+            }
+            return {
+                newPhase: 'active',
+                actions: [0 /* Action.Condense */, 5 /* Action.UpdateLastInteraction */],
+            };
+        case 3 /* StateMachineEvent.SessionStart */:
+            return {
+                newPhase: 'active',
+                actions: [3 /* Action.WarnStaleSession */],
+            };
+        case 4 /* StateMachineEvent.SessionStop */:
+            return {
+                newPhase: 'ended',
+                actions: [5 /* Action.UpdateLastInteraction */],
+            };
+        case 5 /* StateMachineEvent.Compaction */:
+            return {
+                newPhase: 'active',
+                actions: [1 /* Action.CondenseIfFilesTouched */, 5 /* Action.UpdateLastInteraction */],
+            };
+        default:
+            return { newPhase: 'active', actions: [] };
+    }
+}
+function transitionFromEnded(event, ctx) {
+    switch (event) {
+        case 0 /* StateMachineEvent.TurnStart */:
+            return {
+                newPhase: 'active',
+                actions: [4 /* Action.ClearEndedAt */, 5 /* Action.UpdateLastInteraction */],
+            };
+        case 1 /* StateMachineEvent.TurnEnd */:
+            return { newPhase: 'ended', actions: [] };
+        case 2 /* StateMachineEvent.GitCommit */:
+            if (ctx.isRebaseInProgress) {
+                return { newPhase: 'ended', actions: [] };
+            }
+            if (ctx.hasFilesTouched) {
+                return {
+                    newPhase: 'ended',
+                    actions: [1 /* Action.CondenseIfFilesTouched */, 5 /* Action.UpdateLastInteraction */],
+                };
+            }
+            return {
+                newPhase: 'ended',
+                actions: [2 /* Action.DiscardIfNoFiles */, 5 /* Action.UpdateLastInteraction */],
+            };
+        case 3 /* StateMachineEvent.SessionStart */:
+            return {
+                newPhase: 'idle',
+                actions: [4 /* Action.ClearEndedAt */],
+            };
+        case 4 /* StateMachineEvent.SessionStop */:
+            return { newPhase: 'ended', actions: [] };
+        case 5 /* StateMachineEvent.Compaction */:
+            return { newPhase: 'ended', actions: [] };
+        default:
+            return { newPhase: 'ended', actions: [] };
+    }
+}
+export class NoOpActionHandler {
+    async handleCondense() { }
+    async handleCondenseIfFilesTouched() { }
+    async handleDiscardIfNoFiles() { }
+    async handleWarnStaleSession() { }
+}
+/**
+ * Apply a TransitionResult to state: sets the new phase, then executes
+ * all actions. Common actions (UpdateLastInteraction, ClearEndedAt)
+ * always run. Strategy-specific handler actions stop on first error.
+ */
+export async function applyTransition(state, result, handler) {
+    state.phase = result.newPhase;
+    let handlerErr = null;
+    for (const action of result.actions) {
+        switch (action) {
+            case 5 /* Action.UpdateLastInteraction */:
+                state.lastInteractionTime = new Date().toISOString();
+                break;
+            case 4 /* Action.ClearEndedAt */:
+                state.endedAt = undefined;
+                break;
+            case 0 /* Action.Condense */:
+                if (!handlerErr) {
+                    try {
+                        await handler.handleCondense(state);
+                    }
+                    catch (e) {
+                        handlerErr = e instanceof Error ? e : new Error(String(e));
+                    }
+                }
+                break;
+            case 1 /* Action.CondenseIfFilesTouched */:
+                if (!handlerErr) {
+                    try {
+                        await handler.handleCondenseIfFilesTouched(state);
+                    }
+                    catch (e) {
+                        handlerErr = e instanceof Error ? e : new Error(String(e));
+                    }
+                }
+                break;
+            case 2 /* Action.DiscardIfNoFiles */:
+                if (!handlerErr) {
+                    try {
+                        await handler.handleDiscardIfNoFiles(state);
+                    }
+                    catch (e) {
+                        handlerErr = e instanceof Error ? e : new Error(String(e));
+                    }
+                }
+                break;
+            case 3 /* Action.WarnStaleSession */:
+                if (!handlerErr) {
+                    try {
+                        await handler.handleWarnStaleSession(state);
+                    }
+                    catch (e) {
+                        handlerErr = e instanceof Error ? e : new Error(String(e));
+                    }
+                }
+                break;
+        }
+    }
+    return handlerErr;
+}
+// ============================================================================
+// Session State Helpers
+// ============================================================================
+/** Duration after which a session is considered stale (7 days) */
+export const STALE_SESSION_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Returns true when the session's last interaction exceeds the stale threshold.
+ */
+export function isStale(lastInteractionTime) {
+    if (!lastInteractionTime)
+        return false;
+    return Date.now() - new Date(lastInteractionTime).getTime() > STALE_SESSION_THRESHOLD_MS;
+}
+/**
+ * Normalize session state after loading from disk.
+ * Migrates legacy phase values and deprecated transcript fields.
+ */
+export function normalizeAfterLoad(state) {
+    // Normalize legacy phase values
+    state.phase = phaseFromString(state.phase);
+    // Migrate transcript fields
+    if (!state.checkpointTranscriptStart) {
+        if (state.condensedTranscriptLines && state.condensedTranscriptLines > 0) {
+            state.checkpointTranscriptStart = state.condensedTranscriptLines;
+        }
+        else if (state.transcriptLinesAtStart && state.transcriptLinesAtStart > 0) {
+            state.checkpointTranscriptStart = state.transcriptLinesAtStart;
+        }
+    }
+    // Clear deprecated fields
+    state.condensedTranscriptLines = 0;
+    state.transcriptLinesAtStart = 0;
+    // Backfill attributionBaseCommit
+    if (!state.attributionBaseCommit && state.baseCommit) {
+        state.attributionBaseCommit = state.baseCommit;
+    }
+}
+// ============================================================================
+// Mermaid Diagram
+// ============================================================================
+const ALL_PHASES = ['idle', 'active', 'ended'];
+/**
+ * Generate a Mermaid state diagram from the transition table.
+ */
+export function mermaidDiagram() {
+    const lines = ['stateDiagram-v2'];
+    lines.push('    state "IDLE" as idle');
+    lines.push('    state "ACTIVE" as active');
+    lines.push('    state "ENDED" as ended');
+    lines.push('');
+    for (const phase of ALL_PHASES) {
+        for (const event of ALL_EVENTS) {
+            let variants;
+            if (event === 2 /* StateMachineEvent.GitCommit */ && phase === 'ended') {
+                variants = [
+                    { label: '[files]', ctx: { hasFilesTouched: true, isRebaseInProgress: false } },
+                    { label: '[no files]', ctx: { hasFilesTouched: false, isRebaseInProgress: false } },
+                    { label: '[rebase]', ctx: { hasFilesTouched: false, isRebaseInProgress: true } },
+                ];
+            }
+            else if (event === 2 /* StateMachineEvent.GitCommit */) {
+                variants = [
+                    { label: '', ctx: { hasFilesTouched: false, isRebaseInProgress: false } },
+                    { label: '[rebase]', ctx: { hasFilesTouched: false, isRebaseInProgress: true } },
+                ];
+            }
+            else {
+                variants = [
+                    { label: '', ctx: { hasFilesTouched: false, isRebaseInProgress: false } },
+                ];
+            }
+            for (const v of variants) {
+                const result = transition(phase, event, v.ctx);
+                let label = eventToString(event);
+                if (v.label)
+                    label += ' ' + v.label;
+                if (result.actions.length > 0) {
+                    label += ' / ' + result.actions.map(actionToString).join(', ');
+                }
+                lines.push(`    ${phase} --> ${result.newPhase} : ${label}`);
+            }
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=state-machine.js.map