reflectt-node 0.1.0

package/dist/pause-controls.js

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: Apache-2.0
+// Pause/sleep controls: pause individual agents or the whole team
+// When paused, /tasks/next refuses to assign new work.
+import { getDb } from './db.js';
+// ── DB ──
+function ensurePauseTable() {
+    const db = getDb();
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS pause_controls (
+      target TEXT PRIMARY KEY,
+      paused INTEGER NOT NULL DEFAULT 0,
+      paused_at INTEGER NOT NULL,
+      paused_until INTEGER,
+      paused_by TEXT NOT NULL,
+      reason TEXT NOT NULL DEFAULT ''
+    );
+  `);
+}
+// ── Core ──
+const TEAM_TARGET = '__team__';
+function getEntry(target) {
+    ensurePauseTable();
+    const db = getDb();
+    const row = db.prepare('SELECT * FROM pause_controls WHERE target = ?').get(target);
+    if (!row)
+        return null;
+    return {
+        target: String(row.target),
+        paused: Boolean(row.paused),
+        pausedAt: Number(row.paused_at) || 0,
+        pausedUntil: row.paused_until ? Number(row.paused_until) : null,
+        pausedBy: String(row.paused_by || ''),
+        reason: String(row.reason || ''),
+    };
+}
+function upsertPause(target, opts) {
+    ensurePauseTable();
+    const db = getDb();
+    const now = Date.now();
+    db.prepare(`
+    INSERT INTO pause_controls (target, paused, paused_at, paused_until, paused_by, reason)
+    VALUES (?, 1, ?, ?, ?, ?)
+    ON CONFLICT(target) DO UPDATE SET
+      paused = 1,
+      paused_at = excluded.paused_at,
+      paused_until = excluded.paused_until,
+      paused_by = excluded.paused_by,
+      reason = excluded.reason
+  `).run(target, now, opts.pausedUntil ?? null, opts.pausedBy, opts.reason);
+    return getEntry(target);
+}
+function removePause(target) {
+    ensurePauseTable();
+    const db = getDb();
+    const result = db.prepare('UPDATE pause_controls SET paused = 0 WHERE target = ?').run(target);
+    return result.changes > 0;
+}
+// ── Auto-expire check ──
+function isExpired(entry) {
+    if (!entry.paused)
+        return true;
+    if (!entry.pausedUntil)
+        return false; // indefinite
+    return Date.now() >= entry.pausedUntil;
+}
+// ── Public API ──
+/** Pause an agent or the team */
+export function pauseTarget(target, opts) {
+    const key = target === 'team' ? TEAM_TARGET : target.toLowerCase();
+    return upsertPause(key, opts);
+}
+/** Unpause an agent or the team */
+export function unpauseTarget(target) {
+    const key = target === 'team' ? TEAM_TARGET : target.toLowerCase();
+    return { success: removePause(key) };
+}
+/** Check if an agent is paused (directly or via team pause) */
+export function checkPauseStatus(agent) {
+    const agentKey = agent.toLowerCase();
+    // Check team-wide pause first
+    const teamEntry = getEntry(TEAM_TARGET);
+    if (teamEntry && teamEntry.paused && !isExpired(teamEntry)) {
+        const remainingMs = teamEntry.pausedUntil ? teamEntry.pausedUntil - Date.now() : null;
+        return {
+            paused: true,
+            entry: teamEntry,
+            remainingMs,
+            message: `Team paused by ${teamEntry.pausedBy}: ${teamEntry.reason}${remainingMs ? ` (${Math.ceil(remainingMs / 60000)}m remaining)` : ' (indefinite)'}`,
+        };
+    }
+    // Auto-expire team pause
+    if (teamEntry && teamEntry.paused && isExpired(teamEntry)) {
+        removePause(TEAM_TARGET);
+    }
+    // Check agent-specific pause
+    const agentEntry = getEntry(agentKey);
+    if (agentEntry && agentEntry.paused && !isExpired(agentEntry)) {
+        const remainingMs = agentEntry.pausedUntil ? agentEntry.pausedUntil - Date.now() : null;
+        return {
+            paused: true,
+            entry: agentEntry,
+            remainingMs,
+            message: `${agent} paused by ${agentEntry.pausedBy}: ${agentEntry.reason}${remainingMs ? ` (${Math.ceil(remainingMs / 60000)}m remaining)` : ' (indefinite)'}`,
+        };
+    }
+    // Auto-expire agent pause
+    if (agentEntry && agentEntry.paused && isExpired(agentEntry)) {
+        removePause(agentKey);
+    }
+    return { paused: false, entry: null, remainingMs: null, message: 'Active' };
+}
+/** List all pause entries (active + expired) */
+export function listPauseEntries() {
+    ensurePauseTable();
+    const db = getDb();
+    const rows = db.prepare('SELECT * FROM pause_controls ORDER BY paused_at DESC').all();
+    return rows.map(row => ({
+        target: String(row.target),
+        paused: Boolean(row.paused),
+        pausedAt: Number(row.paused_at) || 0,
+        pausedUntil: row.paused_until ? Number(row.paused_until) : null,
+        pausedBy: String(row.paused_by || ''),
+        reason: String(row.reason || ''),
+    }));
+}
+/** Get team pause status specifically */
+export function getTeamPauseStatus() {
+    return checkPauseStatus(TEAM_TARGET);
+}
+//# sourceMappingURL=pause-controls.js.map

package/dist/pause-controls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pause-controls.js","sourceRoot":"","sources":["../src/pause-controls.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,kEAAkE;AAClE,uDAAuD;AAEvD,OAAO,EAAE,KAAK,EAAoC,MAAM,SAAS,CAAA;AAoBjE,WAAW;AAEX,SAAS,gBAAgB;IACvB,MAAM,EAAE,GAAG,KAAK,EAAE,CAAA;IAClB,EAAE,CAAC,IAAI,CAAC;;;;;;;;;GASP,CAAC,CAAA;AACJ,CAAC;AAED,aAAa;AAEb,MAAM,WAAW,GAAG,UAAU,CAAA;AAE9B,SAAS,QAAQ,CAAC,MAAc;IAC9B,gBAAgB,EAAE,CAAA;IAClB,MAAM,EAAE,GAAG,KAAK,EAAE,CAAA;IAClB,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,+CAA+C,CAAC,CAAC,GAAG,CAAC,MAAM,CAAwC,CAAA;IAC1H,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAA;IAErB,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;QAC1B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;QAC3B,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC;QACpC,WAAW,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI;QAC/D,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC;QACrC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC;KACjC,CAAA;AACH,CAAC;AAED,SAAS,WAAW,CAAC,MAAc,EAAE,IAAuE;IAC1G,gBAAgB,EAAE,CAAA;IAClB,MAAM,EAAE,GAAG,KAAK,EAAE,CAAA;IAClB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IAEtB,EAAE,CAAC,OAAO,CAAC;;;;;;;;;GASV,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,WAAW,IAAI,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IAEzE,OAAO,QAAQ,CAAC,MAAM,CAAE,CAAA;AAC1B,CAAC;AAED,SAAS,WAAW,CAAC,MAAc;IACjC,gBAAgB,EAAE,CAAA;IAClB,MAAM,EAAE,GAAG,KAAK,EAAE,CAAA;IAClB,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CAAC,uDAAuD,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAC9F,OAAO,MAAM,CAAC,OAAO,GAAG,CAAC,CAAA;AAC3B,CAAC;AAED,0BAA0B;AAE1B,SAAS,SAAS,CAAC,KAAiB;IAClC,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IAC9B,IAAI,CAAC,KAAK,CAAC,WAAW;QAAE,OAAO,KAAK,CAAA,CAAC,aAAa;IAClD,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,KAAK,CAAC,WAAW,CAAA;AACxC,CAAC;AAED,mBAAmB;AAEnB,iCAAiC;AACjC,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,IAAuE;IACjH,MAAM,GAAG,GAAG,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,CAAA;IAClE,OAAO,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;AAC/B,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,MAAM,GAAG,GAAG,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,CAAA;IAClE,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,CAAA;AACtC,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,EAAE,CAAA;IAEpC,8BAA8B;IAC9B,MAAM,SAAS,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAA;IACvC,IAAI,SAAS,IAAI,SAAS,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3D,MAAM,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;QACrF,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,KAAK,EAAE,SAAS;YAChB,WAAW;YACX,OAAO,EAAE,kBAAkB,SAAS,CAAC,QAAQ,KAAK,SAAS,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,eAAe,EAAE;SACzJ,CAAA;IACH,CAAC;IAED,yBAAyB;IACzB,IAAI,SAAS,IAAI,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1D,WAAW,CAAC,WAAW,CAAC,CAAA;IAC1B,CAAC;IAED,6BAA6B;IAC7B,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAA;IACrC,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9D,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;QACvF,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,KAAK,EAAE,UAAU;YACjB,WAAW;YACX,OAAO,EAAE,GAAG,KAAK,cAAc,UAAU,CAAC,QAAQ,KAAK,UAAU,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,eAAe,EAAE;SAC/J,CAAA;IACH,CAAC;IAED,0BAA0B;IAC1B,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,IAAI,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7D,WAAW,CAAC,QAAQ,CAAC,CAAA;IACvB,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAA;AAC7E,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,gBAAgB;IAC9B,gBAAgB,EAAE,CAAA;IAClB,MAAM,EAAE,GAAG,KAAK,EAAE,CAAA;IAClB,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,sDAAsD,CAAC,CAAC,GAAG,EAAoC,CAAA;IACvH,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtB,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;QAC1B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;QAC3B,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC;QACpC,WAAW,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI;QAC/D,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC;QACrC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC;KACjC,CAAC,CAAC,CAAA;AACL,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,kBAAkB;IAChC,OAAO,gBAAgB,CAAC,WAAW,CAAC,CAAA;AACtC,CAAC"}

package/dist/pidlock.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Get port-specific PID path to avoid cross-port lockfile conflicts.
+ * Production (4445) uses the default path for backward compatibility.
+ */
+export declare function getPidPath(port: number): string;
+export interface PidLockResult {
+    previousPid: number | null;
+    killedPrevious: boolean;
+    portConflictPids: number[];
+    killedPortConflicts: boolean;
+}
+/**
+ * Acquire the PID lock. Call this before starting the server.
+ *
+ * 1. Reads existing lockfile and kills that process if alive
+ * 2. Checks for port conflicts from unmanaged processes
+ * 3. Writes current PID to lockfile
+ */
+export declare function acquirePidLock(port: number, pidPath?: string): PidLockResult;
+/**
+ * Release the PID lock. Call this on shutdown.
+ * Only removes the lockfile if it still contains our PID (avoid race).
+ */
+export declare function releasePidLock(pidPath?: string): void;
+//# sourceMappingURL=pidlock.d.ts.map

package/dist/pidlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pidlock.d.ts","sourceRoot":"","sources":["../src/pidlock.ts"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,cAAc,EAAE,OAAO,CAAA;IACvB,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,mBAAmB,EAAE,OAAO,CAAA;CAC7B;AAsED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAyB,GAAG,aAAa,CAgE9F;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,MAAyB,GAAG,IAAI,CAcvE"}

package/dist/pidlock.js

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) Reflectt AI
+/**
+ * PID Lockfile Manager
+ *
+ * Ensures only one instance of reflectt-node runs at a time.
+ * On startup: reads lockfile, kills stale process, writes new PID.
+ * On shutdown: cleans up lockfile.
+ *
+ * Also detects port conflicts from processes NOT managed by our lockfile.
+ */
+import { readFileSync, writeFileSync, unlinkSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+const DEFAULT_PID_PATH = '/tmp/reflectt-node.pid';
+/**
+ * Get port-specific PID path to avoid cross-port lockfile conflicts.
+ * Production (4445) uses the default path for backward compatibility.
+ */
+export function getPidPath(port) {
+    return port === 4445 ? DEFAULT_PID_PATH : `/tmp/reflectt-node-${port}.pid`;
+}
+/**
+ * Check if a process is alive
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0); // signal 0 = just check existence
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Kill a process with escalation: SIGTERM → wait → SIGKILL
+ */
+function killProcess(pid, label) {
+    if (!isProcessAlive(pid))
+        return false;
+    console.log(`  ⚠ Killing ${label} (pid ${pid})...`);
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        return false;
+    }
+    // Wait up to 3 seconds for graceful shutdown
+    const deadline = Date.now() + 3000;
+    while (Date.now() < deadline && isProcessAlive(pid)) {
+        // busy-wait in 100ms increments (startup only, acceptable)
+        const waitUntil = Date.now() + 100;
+        while (Date.now() < waitUntil) { /* spin */ }
+    }
+    // Force kill if still alive
+    if (isProcessAlive(pid)) {
+        console.log(`  ⚠ Force-killing ${label} (pid ${pid})...`);
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            return false;
+        }
+        // Brief wait for SIGKILL to take effect
+        const killDeadline = Date.now() + 1000;
+        while (Date.now() < killDeadline && isProcessAlive(pid)) {
+            const waitUntil = Date.now() + 50;
+            while (Date.now() < waitUntil) { /* spin */ }
+        }
+    }
+    return !isProcessAlive(pid);
+}
+/**
+ * Find PIDs listening on a given port (via lsof)
+ */
+function findPortPids(port) {
+    try {
+        const output = execSync(`lsof -i :${port} -t 2>/dev/null`, { encoding: 'utf8', timeout: 5000 });
+        return output
+            .trim()
+            .split('\n')
+            .map(s => parseInt(s, 10))
+            .filter(n => !isNaN(n) && n > 0 && n !== process.pid);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Acquire the PID lock. Call this before starting the server.
+ *
+ * 1. Reads existing lockfile and kills that process if alive
+ * 2. Checks for port conflicts from unmanaged processes
+ * 3. Writes current PID to lockfile
+ */
+export function acquirePidLock(port, pidPath = DEFAULT_PID_PATH) {
+    const result = {
+        previousPid: null,
+        killedPrevious: false,
+        portConflictPids: [],
+        killedPortConflicts: false,
+    };
+    console.log('🔒 Acquiring PID lock...');
+    // Step 1: Check existing lockfile
+    if (existsSync(pidPath)) {
+        try {
+            const content = readFileSync(pidPath, 'utf8').trim();
+            const previousPid = parseInt(content, 10);
+            if (!isNaN(previousPid) && previousPid > 0) {
+                result.previousPid = previousPid;
+                if (isProcessAlive(previousPid)) {
+                    console.log(`  Found previous instance (pid ${previousPid}) from lockfile`);
+                    result.killedPrevious = killProcess(previousPid, 'previous instance');
+                    if (result.killedPrevious) {
+                        console.log(`  ✅ Previous instance killed`);
+                    }
+                    else {
+                        console.warn(`  ⚠ Could not kill previous instance (pid ${previousPid})`);
+                    }
+                }
+                else {
+                    console.log(`  Stale lockfile found (pid ${previousPid} not running), cleaning up`);
+                }
+            }
+        }
+        catch (err) {
+            console.warn(`  ⚠ Could not read lockfile: ${err}`);
+        }
+    }
+    // Step 2: Check for port conflicts (processes not in our lockfile)
+    const portPids = findPortPids(port);
+    if (portPids.length > 0) {
+        result.portConflictPids = portPids;
+        console.log(`  Found ${portPids.length} process(es) on port ${port}: ${portPids.join(', ')}`);
+        let allKilled = true;
+        for (const pid of portPids) {
+            if (!killProcess(pid, `port conflict`)) {
+                allKilled = false;
+                console.warn(`  ⚠ Could not kill port conflict (pid ${pid})`);
+            }
+        }
+        result.killedPortConflicts = allKilled;
+        if (allKilled && portPids.length > 0) {
+            console.log(`  ✅ All port conflicts resolved`);
+            // Brief pause to let ports release
+            const waitUntil = Date.now() + 1000;
+            while (Date.now() < waitUntil) { /* spin */ }
+        }
+    }
+    // Step 3: Write current PID
+    try {
+        writeFileSync(pidPath, String(process.pid), 'utf8');
+        console.log(`  ✅ PID lock acquired (pid ${process.pid}, lockfile ${pidPath})`);
+    }
+    catch (err) {
+        console.warn(`  ⚠ Could not write lockfile: ${err}`);
+    }
+    return result;
+}
+/**
+ * Release the PID lock. Call this on shutdown.
+ * Only removes the lockfile if it still contains our PID (avoid race).
+ */
+export function releasePidLock(pidPath = DEFAULT_PID_PATH) {
+    try {
+        if (existsSync(pidPath)) {
+            const content = readFileSync(pidPath, 'utf8').trim();
+            const lockPid = parseInt(content, 10);
+            if (lockPid === process.pid) {
+                unlinkSync(pidPath);
+                console.log(`🔓 PID lock released (pid ${process.pid})`);
+            }
+            // If PID doesn't match, a newer instance has taken over — don't delete
+        }
+    }
+    catch {
+        // Best effort cleanup
+    }
+}
+//# sourceMappingURL=pidlock.js.map

package/dist/pidlock.js.map

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

package/dist/policy.d.ts

@@ -0,0 +1,139 @@
+export interface PolicyConfig {
+    /** Global quiet hours — suppresses all watchdog/board-health actions */
+    quietHours: {
+        enabled: boolean;
+        startHour: number;
+        endHour: number;
+        timezone: string;
+    };
+    /** Idle nudge: warn/escalate agents with no activity */
+    idleNudge: {
+        enabled: boolean;
+        warnMin: number;
+        escalateMin: number;
+        cooldownMin: number;
+        suppressRecentMin: number;
+        shipCooldownMin: number;
+        activeTaskMaxAgeMin: number;
+        excluded: string[];
+    };
+    /** Cadence watchdog: trio silence + stale working alerts */
+    cadenceWatchdog: {
+        enabled: boolean;
+        silenceMin: number;
+        workingStaleMin: number;
+        workingTaskMaxAgeMin: number;
+        alertCooldownMin: number;
+    };
+    /** Stale doing threshold (for health endpoint) */
+    staleDoingThresholdMin: number;
+    /** Mention rescue: nudge trio when Ryan mentions them and nobody responds */
+    mentionRescue: {
+        enabled: boolean;
+        delayMin: number;
+        cooldownMin: number;
+        globalCooldownMin: number;
+    };
+    /** Board health worker: automated board hygiene */
+    boardHealth: {
+        enabled: boolean;
+        intervalMs: number;
+        staleDoingThresholdMin: number;
+        suggestCloseThresholdMin: number;
+        rollbackWindowMs: number;
+        digestIntervalMs: number;
+        digestChannel: string;
+        dryRun: boolean;
+        maxActionsPerTick: number;
+    };
+    /** Ready-queue floor: ensure engineering agents always have specced tasks */
+    readyQueueFloor: {
+        enabled: boolean;
+        minReady: number;
+        agents: string[];
+        escalateAfterMin: number;
+        cooldownMin: number;
+        channel: string;
+        enforceBlock?: boolean;
+    };
+    /** Reflection automation nudges */
+    reflectionNudge: {
+        enabled: boolean;
+        postTaskDelayMin: number;
+        idleReflectionHours: number;
+        cooldownMin: number;
+        agents: string[];
+        channel: string;
+        roleCadenceHours: Record<string, number>;
+        excludeAgents?: string[];
+        nudgeNeverReflected?: boolean;
+    };
+    /** Working contract enforcement: hard gates instead of nudges */
+    workingContract: {
+        enabled: boolean;
+        /** Max minutes a task can stay in 'doing' with no status comment before auto-requeue */
+        staleAutoRequeueMin: number;
+        /** Minutes of grace after first warning before auto-requeue fires */
+        graceAfterWarningMin: number;
+        /** Require at least one reflection before claiming a new doing task (if overdue) */
+        reflectionGateOnClaim: boolean;
+        /** Agents subject to enforcement (empty = all active agents) */
+        agents: string[];
+        /** Channel for enforcement notifications */
+        channel: string;
+        /** Dry-run mode: log but don't actually requeue */
+        dryRun: boolean;
+    };
+    /** Insight:promoted listener — auto-create tasks from promoted insights */
+    insightListener: {
+        enabled: boolean;
+        autoCreateSeverities: string[];
+        defaultReviewer: string;
+        defaultEta: string;
+        clusterCooldownMs: number;
+    };
+    /** Escalation channels for different severity levels */
+    escalation: {
+        defaultChannel: string;
+        criticalChannel: string;
+        digestChannel: string;
+    };
+    /**
+     * Status heartbeat discipline: agents must post task comment updates
+     * during long work windows (>30m). Prevents stale-working false positives.
+     *
+     * Format: progress, confidence, ETA → task comment first, #general only if action-relevant.
+     */
+    statusHeartbeat: {
+        enabled: boolean;
+        intervalMin: number;
+        graceMin: number;
+        escalationChannel: string;
+    };
+}
+export declare const DEFAULT_POLICY: PolicyConfig;
+declare class PolicyManager {
+    private config;
+    private filePath;
+    private loaded;
+    constructor();
+    /** Load policy from disk, then overlay env vars. Call once at startup. */
+    load(): PolicyConfig;
+    /** Get current policy (immutable copy) */
+    get(): PolicyConfig;
+    /** Patch policy at runtime — merges, validates, persists */
+    patch(update: DeepPartial<PolicyConfig>): PolicyConfig;
+    /** Reset to defaults + re-apply env */
+    reset(): PolicyConfig;
+    /** Get file path for display */
+    getFilePath(): string;
+    private persist;
+    private merge;
+    private applyEnvOverrides;
+}
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends Record<string, unknown> ? DeepPartial<T[P]> : T[P];
+};
+export declare const policyManager: PolicyManager;
+export {};
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

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