@iflow-mcp/jkheadley-instar 0.26.2

package/dist/core/BranchManager.js

@@ -0,0 +1,413 @@
+/**
+ * BranchManager — Short-lived task branches with auto-merge.
+ *
+ * Non-trivial work (>N files, >N lines) goes on a task branch.
+ * Branches auto-merge when the task completes, using the tiered
+ * resolution system for conflicts. Trivial changes stay on main.
+ *
+ * From INTELLIGENT_SYNC_SPEC Section 6 (Branch Strategy) and
+ * Section 9 (Sync Lifecycle — Task Completion Merge).
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { DegradationReporter } from '../monitoring/DegradationReporter.js';
+// ── Constants ────────────────────────────────────────────────────────
+const DEFAULT_BASE_BRANCH = 'main';
+const DEFAULT_PREFIX = 'task/';
+const DEFAULT_MAX_LIFETIME = 4 * 60 * 60 * 1000; // 4 hours
+const DEFAULT_FILE_THRESHOLD = 2;
+const DEFAULT_LINE_THRESHOLD = 10;
+const STALE_THRESHOLD = 2 * 60 * 60 * 1000; // 2 hours without update
+const BRANCH_STATE_FILE = 'branches.json';
+// ── BranchManager ────────────────────────────────────────────────────
+export class BranchManager {
+    projectDir;
+    stateDir;
+    machineId;
+    baseBranch;
+    branchPrefix;
+    maxLifetimeMs;
+    fileCountThreshold;
+    lineCountThreshold;
+    autoMergeOnComplete;
+    mergeStrategy;
+    branchStateDir;
+    constructor(config) {
+        this.projectDir = config.projectDir;
+        this.stateDir = config.stateDir;
+        this.machineId = config.machineId;
+        this.baseBranch = config.baseBranch ?? DEFAULT_BASE_BRANCH;
+        this.branchPrefix = config.branchPrefix ?? DEFAULT_PREFIX;
+        this.maxLifetimeMs = config.maxLifetimeMs ?? DEFAULT_MAX_LIFETIME;
+        this.fileCountThreshold = config.fileCountThreshold ?? DEFAULT_FILE_THRESHOLD;
+        this.lineCountThreshold = config.lineCountThreshold ?? DEFAULT_LINE_THRESHOLD;
+        this.autoMergeOnComplete = config.autoMergeOnComplete ?? true;
+        this.mergeStrategy = config.mergeStrategy ?? 'no-ff';
+        this.branchStateDir = path.join(config.stateDir, 'state', 'branches');
+        if (!fs.existsSync(this.branchStateDir)) {
+            fs.mkdirSync(this.branchStateDir, { recursive: true });
+        }
+    }
+    // ── Decision ───────────────────────────────────────────────────────
+    /**
+     * Determine whether a task should use a branch or stay on main.
+     */
+    shouldBranch(opts) {
+        // If either threshold is exceeded, branch
+        if (opts.fileCount !== undefined && opts.fileCount >= this.fileCountThreshold) {
+            return true;
+        }
+        if (opts.lineCount !== undefined && opts.lineCount >= this.lineCountThreshold) {
+            return true;
+        }
+        return false;
+    }
+    // ── Branch Lifecycle ───────────────────────────────────────────────
+    /**
+     * Create a new task branch from the current base branch.
+     * Returns the branch metadata.
+     */
+    createBranch(opts) {
+        const branchName = `${this.branchPrefix}${this.machineId}/${opts.slug}`;
+        // Get current HEAD on base branch
+        const baseCommit = this.git('rev-parse', 'HEAD');
+        // Create and switch to the new branch
+        this.git('checkout', '-b', branchName);
+        const branch = {
+            name: branchName,
+            machineId: this.machineId,
+            sessionId: opts.sessionId,
+            task: opts.task,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            status: 'active',
+            baseBranch: this.baseBranch,
+            baseCommit,
+            commitCount: 0,
+        };
+        this.saveBranchState(branch);
+        return branch;
+    }
+    /**
+     * Update branch metadata (e.g., after a commit).
+     */
+    updateBranch(branchName, updates) {
+        const branch = this.loadBranchState(branchName);
+        if (!branch)
+            return false;
+        if (updates?.task !== undefined)
+            branch.task = updates.task;
+        branch.updatedAt = new Date().toISOString();
+        // Count commits since base
+        try {
+            const log = this.git('log', '--oneline', `${branch.baseCommit}..${branchName}`);
+            branch.commitCount = log.trim() ? log.trim().split('\n').length : 0;
+        }
+        catch {
+            // Branch or commit might not exist in test scenarios
+        }
+        this.saveBranchState(branch);
+        return true;
+    }
+    /**
+     * Complete a task branch — merge back to base and clean up.
+     *
+     * Steps (per spec Section 9):
+     * 1. Commit all changes on task branch
+     * 2. Switch to base branch
+     * 3. Fetch + rebase base from remote (if remote exists)
+     * 4. Merge task branch into base (--no-ff or rebase)
+     * 5. If conflicts → return them for tiered resolution
+     * 6. Delete task branch
+     */
+    completeBranch(branchName, opts) {
+        const branch = this.loadBranchState(branchName);
+        if (!branch) {
+            return { success: false, conflicts: [], error: `Branch state not found: ${branchName}` };
+        }
+        branch.status = 'merging';
+        this.saveBranchState(branch);
+        try {
+            // 1. Commit any pending changes on the task branch
+            this.commitPending(opts?.commitMessage ?? `task: ${branch.task}`);
+            // 2. Switch to base branch
+            this.git('checkout', this.baseBranch);
+            // 3. Try to update base from remote (non-fatal if no remote)
+            try {
+                this.git('fetch', 'origin');
+                this.git('rebase', `origin/${this.baseBranch}`);
+            }
+            catch {
+                // No remote or fetch failed — proceed with local merge
+            }
+            // 4. Merge task branch into base
+            const mergeResult = this.performMerge(branchName);
+            if (!mergeResult.success) {
+                // Conflicts detected — leave branch intact for tiered resolution
+                branch.status = 'active';
+                this.saveBranchState(branch);
+                return mergeResult;
+            }
+            // 5. Get merge commit
+            mergeResult.mergeCommit = this.git('rev-parse', 'HEAD');
+            // 6. Delete task branch
+            this.deleteBranch(branchName);
+            // Update state to merged
+            branch.status = 'merged';
+            branch.updatedAt = new Date().toISOString();
+            this.saveBranchState(branch);
+            return mergeResult;
+        }
+        catch (err) {
+            // Something went wrong — try to restore state
+            branch.status = 'active';
+            this.saveBranchState(branch);
+            try {
+                // Try to get back to the task branch if merge failed midway
+                const currentBranch = this.git('rev-parse', '--abbrev-ref', 'HEAD');
+                if (currentBranch === this.baseBranch) {
+                    // Abort any in-progress merge
+                    try {
+                        this.git('merge', '--abort');
+                    }
+                    catch { /* no merge in progress */ }
+                }
+            }
+            catch { /* best effort */ }
+            return {
+                success: false,
+                conflicts: [],
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    /**
+     * Abandon a task branch without merging.
+     * Switches back to base and deletes the branch.
+     */
+    abandonBranch(branchName) {
+        const branch = this.loadBranchState(branchName);
+        try {
+            // Switch to base if we're on the task branch
+            const current = this.getCurrentBranch();
+            if (current === branchName) {
+                this.git('checkout', this.baseBranch);
+            }
+            this.deleteBranch(branchName);
+            if (branch) {
+                branch.status = 'abandoned';
+                branch.updatedAt = new Date().toISOString();
+                this.saveBranchState(branch);
+            }
+            return true;
+        }
+        catch (err) {
+            DegradationReporter.getInstance().report({
+                feature: 'BranchManager.abandonBranch',
+                primary: 'Abandon task branch and update state',
+                fallback: 'Branch abandon failed silently',
+                reason: `Why: ${err instanceof Error ? err.message : String(err)}`,
+                impact: 'Stale branch may persist and not be cleaned up',
+            });
+            return false;
+        }
+    }
+    // ── Monitoring ─────────────────────────────────────────────────────
+    /**
+     * Check for branches that exceed lifetime or are stale.
+     */
+    checkBranchHealth() {
+        const warnings = [];
+        const now = Date.now();
+        const activeBranches = this.getActiveBranches();
+        for (const branch of activeBranches) {
+            const createdAge = now - new Date(branch.createdAt).getTime();
+            const updatedAge = now - new Date(branch.updatedAt).getTime();
+            if (createdAge > this.maxLifetimeMs) {
+                warnings.push({
+                    branch,
+                    type: 'lifetime-exceeded',
+                    message: `Branch "${branch.name}" has exceeded the ${this.maxLifetimeMs / (60 * 60 * 1000)}h lifetime cap. Consider merging or abandoning.`,
+                    ageMs: createdAge,
+                });
+            }
+            else if (updatedAge > STALE_THRESHOLD) {
+                warnings.push({
+                    branch,
+                    type: 'stale',
+                    message: `Branch "${branch.name}" has had no activity for ${Math.round(updatedAge / (60 * 60 * 1000))}h. It may be abandoned.`,
+                    ageMs: updatedAge,
+                });
+            }
+        }
+        // Check for orphaned git branches (exist in git but not in state)
+        try {
+            const gitBranches = this.listGitBranches();
+            const stateBranches = new Set(activeBranches.map(b => b.name));
+            for (const gitBranch of gitBranches) {
+                if (gitBranch.startsWith(this.branchPrefix) && !stateBranches.has(gitBranch)) {
+                    warnings.push({
+                        branch: {
+                            name: gitBranch,
+                            machineId: 'unknown',
+                            sessionId: 'unknown',
+                            task: 'unknown (orphaned)',
+                            createdAt: new Date().toISOString(),
+                            updatedAt: new Date().toISOString(),
+                            status: 'active',
+                            baseBranch: this.baseBranch,
+                            baseCommit: '',
+                            commitCount: 0,
+                        },
+                        type: 'orphaned',
+                        message: `Git branch "${gitBranch}" exists but has no state tracking. It may be orphaned.`,
+                        ageMs: 0,
+                    });
+                }
+            }
+        }
+        catch {
+            // @silent-fallback-ok — orphan detection is best-effort; git branch listing may fail in bare repos
+        }
+        return warnings;
+    }
+    /**
+     * Get all active branches for this machine.
+     */
+    getActiveBranches() {
+        return this.loadAllBranchStates()
+            .filter(b => b.status === 'active' && b.machineId === this.machineId);
+    }
+    /**
+     * Get all tracked branches across all machines.
+     */
+    getAllBranches() {
+        return this.loadAllBranchStates();
+    }
+    /**
+     * Get the current git branch name.
+     */
+    getCurrentBranch() {
+        return this.git('rev-parse', '--abbrev-ref', 'HEAD');
+    }
+    /**
+     * Check if we're currently on a task branch.
+     */
+    isOnTaskBranch() {
+        return this.getCurrentBranch().startsWith(this.branchPrefix);
+    }
+    // ── Private: Git Operations ────────────────────────────────────────
+    performMerge(branchName) {
+        try {
+            if (this.mergeStrategy === 'no-ff') {
+                this.git('merge', '--no-ff', branchName, '-m', `merge: ${branchName}`);
+            }
+            else {
+                // Rebase strategy
+                this.git('rebase', branchName);
+            }
+            return { success: true, conflicts: [] };
+        }
+        catch (err) {
+            // @silent-fallback-ok — merge failure is expected control flow; conflicts are returned to caller for resolution
+            const errMsg = err instanceof Error ? err.message : String(err);
+            if (errMsg.includes('CONFLICT') || errMsg.includes('Merge conflict')) {
+                const conflicts = this.detectConflicts();
+                return { success: false, conflicts };
+            }
+            return { success: false, conflicts: [], error: errMsg };
+        }
+    }
+    detectConflicts() {
+        try {
+            const status = this.git('diff', '--name-only', '--diff-filter=U');
+            return status.split('\n').filter(l => l.trim());
+        }
+        catch {
+            // @silent-fallback-ok — git diff for conflict detection is best-effort; empty list is safe default
+            return [];
+        }
+    }
+    commitPending(message) {
+        try {
+            const status = this.git('status', '--porcelain');
+            if (status.trim()) {
+                this.git('add', '-A');
+                this.git('commit', '-m', message);
+            }
+        }
+        catch {
+            // @silent-fallback-ok — nothing to commit or git not available; commit is best-effort
+        }
+    }
+    deleteBranch(branchName) {
+        try {
+            this.git('branch', '-D', branchName);
+        }
+        catch {
+            // @silent-fallback-ok — branch may not exist; deletion is best-effort cleanup
+        }
+        // Also try to delete remote tracking branch (non-fatal)
+        try {
+            this.git('push', 'origin', '--delete', branchName);
+        }
+        catch {
+            // @silent-fallback-ok — no remote configured or branch not pushed; remote cleanup is optional
+        }
+    }
+    listGitBranches() {
+        try {
+            const output = this.git('branch', '--list', `${this.branchPrefix}*`);
+            return output.split('\n')
+                .map(l => l.replace(/^\*?\s+/, '').trim())
+                .filter(l => l.length > 0);
+        }
+        catch {
+            // @silent-fallback-ok — git branch listing may fail if not in a repo; empty list is safe default
+            return [];
+        }
+    }
+    // ── Private: State Persistence ─────────────────────────────────────
+    branchStateFile() {
+        return path.join(this.branchStateDir, BRANCH_STATE_FILE);
+    }
+    loadAllBranchStates() {
+        const filePath = this.branchStateFile();
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const data = JSON.parse(content);
+            return data.branches ?? [];
+        }
+        catch {
+            // @silent-fallback-ok — state file may not exist yet; empty array is the natural initial state
+            return [];
+        }
+    }
+    loadBranchState(branchName) {
+        const all = this.loadAllBranchStates();
+        return all.find(b => b.name === branchName) ?? null;
+    }
+    saveBranchState(branch) {
+        const all = this.loadAllBranchStates();
+        const idx = all.findIndex(b => b.name === branch.name);
+        if (idx >= 0) {
+            all[idx] = branch;
+        }
+        else {
+            all.push(branch);
+        }
+        const filePath = this.branchStateFile();
+        fs.writeFileSync(filePath, JSON.stringify({ branches: all }, null, 2));
+    }
+    // ── Private: Git Helper ────────────────────────────────────────────
+    git(...args) {
+        return execFileSync('git', args, {
+            cwd: this.projectDir,
+            encoding: 'utf-8',
+            timeout: 30_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+}
+//# sourceMappingURL=BranchManager.js.map

package/dist/core/BranchManager.js.map

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

package/dist/core/CaffeinateManager.d.ts

@@ -0,0 +1,50 @@
+/**
+ * CaffeinateManager - Prevent macOS system sleep for Instar server lifetime.
+ *
+ * Maintains a `caffeinate -s` child process that prevents system sleep.
+ * A watchdog verifies it's alive every 30s and restarts if dead.
+ * PID is written to <stateDir>/caffeinate.pid for crash recovery.
+ *
+ * Only activates on macOS (process.platform === 'darwin').
+ * Uses EventEmitter pattern consistent with Instar conventions.
+ */
+import { EventEmitter } from 'node:events';
+export interface CaffeinateManagerConfig {
+    /** State directory for PID file storage */
+    stateDir: string;
+}
+export interface CaffeinateStatus {
+    running: boolean;
+    pid: number | null;
+    startedAt: string | null;
+    restartCount: number;
+    lastWatchdogCheck: string;
+}
+export declare class CaffeinateManager extends EventEmitter {
+    private process;
+    private watchdogInterval;
+    private pid;
+    private startedAt;
+    private restartCount;
+    private lastWatchdogCheck;
+    private stopping;
+    private pidFile;
+    constructor(config: CaffeinateManagerConfig);
+    /**
+     * Start caffeinate and the watchdog.
+     * Only activates on macOS.
+     */
+    start(): void;
+    /**
+     * Stop caffeinate and the watchdog cleanly.
+     */
+    stop(): void;
+    getStatus(): CaffeinateStatus;
+    private spawnCaffeinate;
+    private killCaffeinate;
+    private watchdog;
+    private cleanupStale;
+    private writePidFile;
+    private removePidFile;
+}
+//# sourceMappingURL=CaffeinateManager.d.ts.map

package/dist/core/CaffeinateManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CaffeinateManager.d.ts","sourceRoot":"","sources":["../../src/core/CaffeinateManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAO3C,MAAM,WAAW,uBAAuB;IACtC,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,iBAAkB,SAAQ,YAAY;IACjD,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,gBAAgB,CAA+C;IACvE,OAAO,CAAC,GAAG,CAAuB;IAClC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,iBAAiB,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,uBAAuB;IAK3C;;;OAGG;IACH,KAAK,IAAI,IAAI;IAiBb;;OAEG;IACH,IAAI,IAAI,IAAI;IAaZ,SAAS,IAAI,gBAAgB;IAU7B,OAAO,CAAC,eAAe;IAmCvB,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,QAAQ;IAsBhB,OAAO,CAAC,YAAY;IAkCpB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,aAAa;CAStB"}

package/dist/core/CaffeinateManager.js

@@ -0,0 +1,189 @@
+/**
+ * CaffeinateManager - Prevent macOS system sleep for Instar server lifetime.
+ *
+ * Maintains a `caffeinate -s` child process that prevents system sleep.
+ * A watchdog verifies it's alive every 30s and restarts if dead.
+ * PID is written to <stateDir>/caffeinate.pid for crash recovery.
+ *
+ * Only activates on macOS (process.platform === 'darwin').
+ * Uses EventEmitter pattern consistent with Instar conventions.
+ */
+import { EventEmitter } from 'node:events';
+import { spawn, spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+const WATCHDOG_INTERVAL_MS = 30_000; // 30 seconds
+export class CaffeinateManager extends EventEmitter {
+    process = null;
+    watchdogInterval = null;
+    pid = null;
+    startedAt = null;
+    restartCount = 0;
+    lastWatchdogCheck = new Date().toISOString();
+    stopping = false;
+    pidFile;
+    constructor(config) {
+        super();
+        this.pidFile = path.join(config.stateDir, 'caffeinate.pid');
+    }
+    /**
+     * Start caffeinate and the watchdog.
+     * Only activates on macOS.
+     */
+    start() {
+        if (this.watchdogInterval)
+            return;
+        if (process.platform !== 'darwin') {
+            console.log('[CaffeinateManager] Not macOS — skipping sleep prevention');
+            return;
+        }
+        this.stopping = false;
+        this.cleanupStale();
+        this.spawnCaffeinate();
+        this.watchdogInterval = setInterval(() => this.watchdog(), WATCHDOG_INTERVAL_MS);
+        this.watchdogInterval.unref(); // Don't prevent process exit
+        console.log(`[CaffeinateManager] Started (watchdog: ${WATCHDOG_INTERVAL_MS / 1000}s)`);
+    }
+    /**
+     * Stop caffeinate and the watchdog cleanly.
+     */
+    stop() {
+        this.stopping = true;
+        if (this.watchdogInterval) {
+            clearInterval(this.watchdogInterval);
+            this.watchdogInterval = null;
+        }
+        this.killCaffeinate();
+        this.removePidFile();
+        console.log('[CaffeinateManager] Stopped');
+    }
+    getStatus() {
+        return {
+            running: this.process !== null && this.pid !== null,
+            pid: this.pid,
+            startedAt: this.startedAt,
+            restartCount: this.restartCount,
+            lastWatchdogCheck: this.lastWatchdogCheck,
+        };
+    }
+    spawnCaffeinate() {
+        try {
+            const proc = spawn('caffeinate', ['-s'], {
+                detached: true,
+                stdio: 'ignore',
+            });
+            proc.unref();
+            this.process = proc;
+            this.pid = proc.pid ?? null;
+            this.startedAt = new Date().toISOString();
+            this.writePidFile();
+            proc.on('exit', (code, signal) => {
+                if (!this.stopping) {
+                    console.warn(`[CaffeinateManager] caffeinate exited (code: ${code}, signal: ${signal})`);
+                    this.emit('died', { code, signal });
+                }
+                this.process = null;
+                this.pid = null;
+            });
+            proc.on('error', (err) => {
+                console.error('[CaffeinateManager] caffeinate spawn error:', err.message);
+                this.process = null;
+                this.pid = null;
+            });
+            console.log(`[CaffeinateManager] caffeinate spawned (PID: ${this.pid})`);
+            this.emit('started', { pid: this.pid });
+        }
+        catch (err) {
+            console.error('[CaffeinateManager] Failed to spawn caffeinate:', err);
+        }
+    }
+    killCaffeinate() {
+        if (this.pid) {
+            try {
+                process.kill(this.pid, 'SIGTERM');
+            }
+            catch {
+                // @silent-fallback-ok — process already dead
+            }
+        }
+        this.process = null;
+        this.pid = null;
+    }
+    watchdog() {
+        this.lastWatchdogCheck = new Date().toISOString();
+        if (this.stopping)
+            return;
+        if (this.pid) {
+            try {
+                process.kill(this.pid, 0);
+                return; // Still alive
+            }
+            catch {
+                // @silent-fallback-ok — signal 0 detection
+                console.warn(`[CaffeinateManager] caffeinate PID ${this.pid} is dead`);
+                this.process = null;
+                this.pid = null;
+            }
+        }
+        this.restartCount++;
+        console.log(`[CaffeinateManager] Restarting caffeinate (restart #${this.restartCount})`);
+        this.spawnCaffeinate();
+        this.emit('restarted', { restartCount: this.restartCount });
+    }
+    cleanupStale() {
+        // Kill ALL orphaned caffeinate processes, not just the one in our PID file.
+        // Orphans accumulate when the server crashes without calling stop() — each
+        // restart spawns a new detached caffeinate but the old one keeps running.
+        // With repeated crash/restart cycles, dozens (or hundreds) of caffeinate
+        // processes pile up. We're about to spawn a fresh one, so kill them all.
+        try {
+            const result = spawnSync('pgrep', ['-x', 'caffeinate'], {
+                encoding: 'utf-8',
+                timeout: 5000,
+            });
+            const pids = (result.stdout ?? '').trim().split('\n').filter(Boolean);
+            let killed = 0;
+            for (const pidStr of pids) {
+                const pid = parseInt(pidStr, 10);
+                if (!isNaN(pid) && pid > 0) {
+                    try {
+                        process.kill(pid, 'SIGTERM');
+                        killed++;
+                    }
+                    catch {
+                        // Process already dead
+                    }
+                }
+            }
+            if (killed > 0) {
+                console.log(`[CaffeinateManager] Killed ${killed} orphaned caffeinate process${killed === 1 ? '' : 'es'}`);
+            }
+        }
+        catch {
+            // pgrep not found or no caffeinate processes — both fine
+        }
+        this.removePidFile();
+    }
+    writePidFile() {
+        if (!this.pid)
+            return;
+        try {
+            fs.mkdirSync(path.dirname(this.pidFile), { recursive: true });
+            fs.writeFileSync(this.pidFile, String(this.pid));
+        }
+        catch (err) {
+            console.error('[CaffeinateManager] Failed to write PID file:', err);
+        }
+    }
+    removePidFile() {
+        try {
+            if (fs.existsSync(this.pidFile)) {
+                fs.unlinkSync(this.pidFile);
+            }
+        }
+        catch {
+            // Not critical
+        }
+    }
+}
+//# sourceMappingURL=CaffeinateManager.js.map