dual-brain 0.2.30 → 0.3.0

package/dist/src/routing-advisor.js

@@ -0,0 +1,221 @@
+// routing-advisor.ts — EMA + epsilon-greedy routing advisor
+// Learns which model works best for which task type from outcome signals.
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { checkFileSurvival } from './outcome.js';
+import { join } from 'node:path';
+const ALPHA = 0.3;
+const MIN_EPSILON = 0.1;
+const MIN_OBSERVATIONS = 5;
+const PRIOR_WEIGHT = 5;
+const STATIC_PRIORS = {
+    'search:haiku': 0.85, 'search:sonnet': 0.70, 'search:opus': 0.50,
+    'execute:haiku': 0.55, 'execute:sonnet': 0.80, 'execute:opus': 0.85,
+    'think:haiku': 0.30, 'think:sonnet': 0.70, 'think:opus': 0.90,
+    'review:haiku': 0.40, 'review:sonnet': 0.75, 'review:opus': 0.85,
+};
+const VALID_MODELS = {
+    search: ['haiku', 'sonnet'],
+    execute: ['haiku', 'sonnet', 'opus'],
+    think: ['sonnet', 'opus'],
+    review: ['sonnet', 'opus'],
+};
+function stateFile(cwd) {
+    return join(cwd || process.cwd(), '.dualbrain', 'routing-state.json');
+}
+function loadState(cwd) {
+    try {
+        const p = stateFile(cwd);
+        if (!existsSync(p))
+            return {};
+        const raw = readFileSync(p, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+function saveState(state, cwd) {
+    try {
+        const dir = join(cwd || process.cwd(), '.dualbrain');
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const p = stateFile(cwd), tmp = p + '.tmp';
+        writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf8');
+        renameSync(tmp, p);
+    }
+    catch { /* non-throwing */ }
+}
+/** Cross-cell bias: average EMA from same-tier cells that have >= 8 observations. */
+function getCrossCellBias(state, cellKey, model) {
+    const [tier] = cellKey.split(':');
+    let biasSum = 0, biasCount = 0;
+    for (const [key, models] of Object.entries(state)) {
+        if (key.startsWith('_'))
+            continue;
+        if (key.startsWith(tier + ':') && key !== cellKey && models[model]) {
+            const entry = models[model];
+            if ((entry.observations ?? 0) >= 8) {
+                biasSum += entry.ema;
+                biasCount++;
+            }
+        }
+    }
+    return biasCount > 0 ? biasSum / biasCount : null;
+}
+const staticPrior = (tier, model) => STATIC_PRIORS[`${tier}:${model}`] ?? 0.5;
+const cellObs = (state, key) => Object.values(state[key] ?? {}).reduce((s, m) => s + (m.observations ?? 0), 0);
+const blended = (ema, n, tier, model) => (n / (n + PRIOR_WEIGHT)) * ema + (PRIOR_WEIGHT / (n + PRIOR_WEIGHT)) * staticPrior(tier, model);
+// taskProfile: { intent, tier, risk, files?, complexity? }
+// Returns: { model, reason, confidence, explored }
+export function adviseModel(taskProfile, cwd) {
+    try {
+        const { tier, intent } = taskProfile ?? {};
+        const validTier = tier && VALID_MODELS[tier] ? tier : 'execute';
+        const cellKey = `${validTier}:${intent ?? 'implement'}`;
+        const models = VALID_MODELS[validTier];
+        const state = loadState(cwd);
+        const totalObs = cellObs(state, cellKey);
+        const grandTotal = Object.entries(state)
+            .filter(([k]) => !k.startsWith('_'))
+            .reduce((s, [, cell]) => s + Object.values(cell).reduce((t, e) => t + (e.observations ?? 0), 0), 0);
+        if (totalObs < MIN_OBSERVATIONS) {
+            // When enough global data exists, blend cross-cell bias with static prior
+            if (grandTotal > 100) {
+                let bestModel = models[0], bestScore = -Infinity;
+                for (const m of models) {
+                    const xbias = getCrossCellBias(state, cellKey, m);
+                    const prior = staticPrior(validTier, m);
+                    const score = xbias != null ? (xbias + prior) / 2 : prior;
+                    if (score > bestScore) {
+                        bestScore = score;
+                        bestModel = m;
+                    }
+                }
+                return { model: bestModel, reason: 'cross-cell bias', confidence: 0.4, explored: false };
+            }
+            const best = models.reduce((a, b) => staticPrior(validTier, a) >= staticPrior(validTier, b) ? a : b);
+            return { model: best, reason: 'insufficient data, using heuristic', confidence: 0.3, explored: false };
+        }
+        const epsilon = Math.max(MIN_EPSILON, 0.5 * Math.pow(0.9, totalObs));
+        const explored = Math.random() < epsilon;
+        if (explored) {
+            const model = models[Math.floor(Math.random() * models.length)];
+            return { model, reason: 'exploration', confidence: epsilon, explored: true };
+        }
+        // Exploitation: pick highest blended score
+        const cell = state[cellKey] ?? {};
+        let bestModel = models[0];
+        let bestScore = -Infinity;
+        for (const m of models) {
+            const entry = cell[m];
+            const ema = entry?.ema ?? staticPrior(validTier, m);
+            const n = entry?.observations ?? 0;
+            const score = blended(ema, n, validTier, m);
+            if (score > bestScore) {
+                bestScore = score;
+                bestModel = m;
+            }
+        }
+        return { model: bestModel, reason: 'exploitation', confidence: 1 - epsilon, explored: false };
+    }
+    catch {
+        return { model: 'sonnet', reason: 'error fallback', confidence: 0.1, explored: false };
+    }
+}
+// reward: number in [0, 1]
+export function recordReward(cellKey, model, reward, cwd) {
+    try {
+        const state = loadState(cwd);
+        if (!state[cellKey])
+            state[cellKey] = {};
+        const entry = state[cellKey][model] ?? { ema: reward, observations: 0 };
+        entry.ema = ALPHA * reward + (1 - ALPHA) * entry.ema;
+        entry.observations = (entry.observations ?? 0) + 1;
+        entry.lastUpdated = new Date().toISOString();
+        entry.lastReward = reward;
+        state[cellKey][model] = entry;
+        saveState(state, cwd);
+    }
+    catch {
+        // non-throwing
+    }
+}
+export function getRoutingStats(cwd) {
+    try {
+        const state = loadState(cwd);
+        const cells = {};
+        const flat = [];
+        let totalObservations = 0;
+        for (const [cellKey, models] of Object.entries(state)) {
+            if (cellKey.startsWith('_'))
+                continue;
+            cells[cellKey] ??= {};
+            for (const [model, entry] of Object.entries(models)) {
+                const obs = entry.observations ?? 0;
+                cells[cellKey][model] = { ema: entry.ema, observations: obs };
+                totalObservations += obs;
+                flat.push({ cell: cellKey, model, ema: entry.ema, observations: obs });
+            }
+        }
+        flat.sort((a, b) => b.ema - a.ema);
+        return { cells, totalObservations, topPerformers: flat.slice(0, 5), worstPerformers: flat.slice(-5).reverse() };
+    }
+    catch {
+        return { cells: {}, totalObservations: 0, topPerformers: [], worstPerformers: [] };
+    }
+}
+/**
+ * Loads cross-session routing state. If the state was last updated in a prior session,
+ * applies a mild decay (x0.95) to all EMA scores to account for staleness.
+ */
+export function loadCrossSessionPriors(cwd) {
+    try {
+        const state = loadState(cwd);
+        const sessionStart = state._sessionStart;
+        if (!sessionStart)
+            return state; // no prior session marker
+        const lastMs = new Date(sessionStart).getTime();
+        if (isNaN(lastMs))
+            return state;
+        const stale = (Date.now() - lastMs) > 60_000; // more than 1 min old = different session
+        if (!stale)
+            return state;
+        for (const [cellKey, models] of Object.entries(state)) {
+            if (cellKey.startsWith('_'))
+                continue;
+            for (const entry of Object.values(models)) {
+                if (typeof entry.ema === 'number')
+                    entry.ema = entry.ema * 0.95;
+            }
+        }
+        return state;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Records session start timestamp and triggers file survival checks.
+ * Call once at CLI session start.
+ */
+export async function markSessionStart(cwd) {
+    try {
+        const state = loadState(cwd);
+        state._sessionStart = new Date().toISOString();
+        saveState(state, cwd);
+        await checkFileSurvival(cwd ?? process.cwd()).catch(() => { });
+    }
+    catch { /* non-throwing */ }
+}
+export function resetAdvisor(cwd) {
+    try {
+        saveState({}, cwd);
+    }
+    catch {
+        // non-throwing
+    }
+}
+//# sourceMappingURL=routing-advisor.js.map

package/dist/src/routing-advisor.js.map

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

package/dist/src/self-correct.d.ts

@@ -0,0 +1,40 @@
+import type { FailureClassification, FailureType, RetryStrategyName, DispatchDecision } from './types.ts';
+interface FailureResult {
+    error?: string;
+    stderr?: string;
+    output?: string;
+    stdout?: string;
+    durationMs?: number;
+    timeoutMs?: number;
+    quality?: number;
+    score?: number;
+}
+export declare function classifyFailure(result: FailureResult): FailureClassification;
+interface StrategyResult {
+    strategy: RetryStrategyName;
+    reason: string;
+    newDecision?: DispatchDecision;
+}
+export declare function selectStrategy(failure: FailureClassification, originalDecision: DispatchDecision, attemptNumber: number): StrategyResult;
+interface RetryDecision extends DispatchDecision {
+    _retryAttempt: number;
+    _retryReason: FailureType | string;
+    _retryStrategy: RetryStrategyName;
+    _contextBudget?: number;
+    _delayMs?: number;
+    _retryAsThink?: boolean;
+    _shouldDecompose?: boolean;
+}
+export declare function buildRetryDecision(originalDecision: DispatchDecision & {
+    _retryAttempt?: number;
+}, strategy: RetryStrategyName, failure: FailureClassification): RetryDecision;
+interface ShouldRetryResult {
+    retry: boolean;
+    reason: string;
+    strategy: RetryStrategyName;
+    decision?: RetryDecision;
+}
+export declare function shouldRetry(result: FailureResult, originalDecision: DispatchDecision & {
+    _retryAttempt?: number;
+}, attemptNumber?: number): ShouldRetryResult;
+export {};

package/dist/src/self-correct.js

@@ -0,0 +1,137 @@
+// self-correct.ts — Failure analysis and retry strategy selection
+const MODEL_TIER = { 'haiku': 1, 'sonnet': 2, 'opus': 3 };
+const TIER_MODEL = { 1: 'haiku', 2: 'sonnet', 3: 'opus' };
+const MAX_ATTEMPTS = 3;
+function modelTier(model = '') {
+    const m = model.toLowerCase();
+    if (m.includes('haiku'))
+        return 1;
+    if (m.includes('opus'))
+        return 3;
+    return 2; // sonnet default
+}
+function matchesAny(text, keywords) {
+    const t = text.toLowerCase();
+    return keywords.some(k => t.includes(k));
+}
+// Export 1: classifyFailure(result)
+export function classifyFailure(result) {
+    try {
+        const err = String(result?.error || result?.stderr || '');
+        const out = String(result?.output || result?.stdout || '');
+        const combined = err + ' ' + out;
+        const duration = result?.durationMs ?? 0;
+        const timeoutThreshold = result?.timeoutMs ?? 60_000;
+        if (matchesAny(combined, ['rate limit', 'ratelimit', '429', 'quota exceeded', 'capacity'])) {
+            return { type: 'rate-limit', confidence: 0.95, retryable: true };
+        }
+        if (matchesAny(combined, ['timeout', 'timed out']) || duration > timeoutThreshold) {
+            return { type: 'timeout', confidence: 0.9, retryable: true };
+        }
+        if (matchesAny(combined, ['context length', 'token limit', 'too long', 'maximum context', 'context window'])) {
+            return { type: 'context-overflow', confidence: 0.9, retryable: true };
+        }
+        if (matchesAny(combined, ['ambiguous', 'unclear', 'did you mean', 'which one', 'could you clarify', 'please clarify'])) {
+            return { type: 'specification', confidence: 0.85, retryable: false };
+        }
+        if (matchesAny(combined, ['unable to', "i don't know how", 'beyond my', 'cannot complete', 'incomplete'])) {
+            return { type: 'capability', confidence: 0.8, retryable: true };
+        }
+        // Heuristic: low quality output without explicit error signals capability gap
+        const quality = result?.quality ?? result?.score ?? null;
+        if (quality !== null && quality !== undefined && quality < 0.5) {
+            return { type: 'capability', confidence: 0.7, retryable: true };
+        }
+        return { type: 'unknown', confidence: 0.5, retryable: true };
+    }
+    catch {
+        return { type: 'unknown', confidence: 0, retryable: true };
+    }
+}
+// Export 2: selectStrategy(failure, originalDecision, attemptNumber)
+export function selectStrategy(failure, originalDecision, attemptNumber) {
+    try {
+        if (!failure.retryable) {
+            return { strategy: 'give-up', reason: `failure type '${failure.type}' requires user input` };
+        }
+        if (attemptNumber >= MAX_ATTEMPTS) {
+            return { strategy: 'give-up', reason: `max attempts (${MAX_ATTEMPTS}) reached` };
+        }
+        const tier = modelTier(originalDecision?.model);
+        if (attemptNumber === 1) {
+            switch (failure.type) {
+                case 'capability':
+                    if (tier >= 3)
+                        return { strategy: 'split', newDecision: originalDecision, reason: 'already at max tier; decompose task' };
+                    return { strategy: 'escalate', newDecision: originalDecision, reason: 'model lacked capability; escalating tier' };
+                case 'timeout':
+                    return { strategy: 'wait-retry', newDecision: originalDecision, reason: 'timed out; retrying with delay' };
+                case 'rate-limit':
+                    return { strategy: 'wait-retry', newDecision: originalDecision, reason: 'rate limited; retrying after delay' };
+                case 'context-overflow':
+                    return { strategy: 'compress', newDecision: originalDecision, reason: 'context too large; compressing' };
+                case 'specification':
+                    return { strategy: 'give-up', reason: 'ambiguous specification; user clarification needed' };
+                default: // unknown
+                    if (tier >= 3)
+                        return { strategy: 'split', newDecision: originalDecision, reason: 'unknown failure at max tier; decomposing' };
+                    return { strategy: 'escalate', newDecision: originalDecision, reason: 'unknown failure; escalating as precaution' };
+            }
+        }
+        if (attemptNumber === 2) {
+            if (tier >= 3) {
+                return { strategy: 'split', newDecision: originalDecision, reason: 'max tier reached; splitting task' };
+            }
+            return { strategy: 'escalate', newDecision: originalDecision, reason: 'retry failed; escalating one final tier' };
+        }
+        return { strategy: 'give-up', reason: 'exhausted retry budget' };
+    }
+    catch {
+        return { strategy: 'give-up', reason: 'internal error in strategy selection' };
+    }
+}
+// Export 3: buildRetryDecision(originalDecision, strategy, failure)
+export function buildRetryDecision(originalDecision, strategy, failure) {
+    try {
+        const base = {
+            ...originalDecision,
+            _retryAttempt: (originalDecision?._retryAttempt ?? 0) + 1,
+            _retryReason: failure.type,
+            _retryStrategy: strategy,
+        };
+        switch (strategy) {
+            case 'escalate': {
+                const tier = modelTier(originalDecision?.model);
+                const nextTier = Math.min(tier + 1, 3);
+                return { ...base, model: TIER_MODEL[nextTier] };
+            }
+            case 'compress':
+                return { ...base, _contextBudget: 0.5 };
+            case 'wait-retry':
+                return { ...base, _delayMs: 5000 };
+            default:
+                return base;
+        }
+    }
+    catch {
+        return { ...originalDecision, _retryAttempt: 1, _retryReason: 'error', _retryStrategy: strategy };
+    }
+}
+// Export 4: shouldRetry(result, originalDecision, attemptNumber)
+export function shouldRetry(result, originalDecision, attemptNumber = 1) {
+    try {
+        if (attemptNumber >= MAX_ATTEMPTS)
+            return { retry: false, reason: `max attempts (${MAX_ATTEMPTS}) reached`, strategy: 'give-up' };
+        const failure = classifyFailure(result);
+        const { strategy, newDecision, reason } = selectStrategy(failure, originalDecision, attemptNumber);
+        if (strategy === 'give-up') {
+            return { retry: false, reason, strategy };
+        }
+        const decision = buildRetryDecision(newDecision ?? originalDecision, strategy, failure);
+        return { retry: true, decision, reason, strategy };
+    }
+    catch {
+        return { retry: false, reason: 'internal error in shouldRetry', strategy: 'give-up' };
+    }
+}
+//# sourceMappingURL=self-correct.js.map

package/dist/src/self-correct.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-correct.js","sourceRoot":"","sources":["../../src/self-correct.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAIlE,MAAM,UAAU,GAA2B,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AAClF,MAAM,UAAU,GAA2B,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;AAClF,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB,SAAS,SAAS,CAAC,KAAK,GAAG,EAAE;IAC3B,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAC9B,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,CAAC,CAAC;IACjC,OAAO,CAAC,CAAC,CAAC,iBAAiB;AAC7B,CAAC;AAED,SAAS,UAAU,CAAC,IAAY,EAAE,QAAkB;IAClD,MAAM,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IAC7B,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3C,CAAC;AAaD,oCAAoC;AACpC,MAAM,UAAU,eAAe,CAAC,MAAqB;IACnD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,MAAM,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,MAAM,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC;QAC3D,MAAM,QAAQ,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;QACjC,MAAM,QAAQ,GAAG,MAAM,EAAE,UAAU,IAAI,CAAC,CAAC;QACzC,MAAM,gBAAgB,GAAG,MAAM,EAAE,SAAS,IAAI,MAAM,CAAC;QAErD,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC;YAC3F,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QACnE,CAAC;QACD,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,IAAI,QAAQ,GAAG,gBAAgB,EAAE,CAAC;YAClF,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAC/D,CAAC;QACD,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,iBAAiB,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC;YAC7G,OAAO,EAAE,IAAI,EAAE,kBAAkB,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QACxE,CAAC;QACD,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,mBAAmB,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC;YACvH,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QACvE,CAAC;QACD,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,kBAAkB,EAAE,WAAW,EAAE,iBAAiB,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC;YAC1G,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAClE,CAAC;QACD,8EAA8E;QAC9E,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,MAAM,EAAE,KAAK,IAAI,IAAI,CAAC;QACzD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,GAAG,GAAG,EAAE,CAAC;YAC/D,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAClE,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC7D,CAAC;AACH,CAAC;AAQD,qEAAqE;AACrE,MAAM,UAAU,cAAc,CAAC,OAA8B,EAAE,gBAAkC,EAAE,aAAqB;IACtH,IAAI,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YACvB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,iBAAiB,OAAO,CAAC,IAAI,uBAAuB,EAAE,CAAC;QAC/F,CAAC;QACD,IAAI,aAAa,IAAI,YAAY,EAAE,CAAC;YAClC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,iBAAiB,YAAY,WAAW,EAAE,CAAC;QACnF,CAAC;QAED,MAAM,IAAI,GAAG,SAAS,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;QAEhD,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;YACxB,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;gBACrB,KAAK,YAAY;oBACf,IAAI,IAAI,IAAI,CAAC;wBAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,qCAAqC,EAAE,CAAC;oBAC1H,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,0CAA0C,EAAE,CAAC;gBACrH,KAAK,SAAS;oBACZ,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,gCAAgC,EAAE,CAAC;gBAC7G,KAAK,YAAY;oBACf,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,oCAAoC,EAAE,CAAC;gBACjH,KAAK,kBAAkB;oBACrB,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,gCAAgC,EAAE,CAAC;gBAC3G,KAAK,eAAe;oBAClB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,oDAAoD,EAAE,CAAC;gBAC/F,SAAS,UAAU;oBACjB,IAAI,IAAI,IAAI,CAAC;wBAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,0CAA0C,EAAE,CAAC;oBAC/H,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,2CAA2C,EAAE,CAAC;YACxH,CAAC;QACH,CAAC;QAED,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;YACxB,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;gBACd,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,kCAAkC,EAAE,CAAC;YAC1G,CAAC;YACD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,yCAAyC,EAAE,CAAC;QACpH,CAAC;QAED,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,sCAAsC,EAAE,CAAC;IACjF,CAAC;AACH,CAAC;AAYD,oEAAoE;AACpE,MAAM,UAAU,kBAAkB,CAAC,gBAA+D,EAAE,QAA2B,EAAE,OAA8B;IAC7J,IAAI,CAAC;QACH,MAAM,IAAI,GAAkB;YAC1B,GAAG,gBAAgB;YACnB,aAAa,EAAE,CAAC,gBAAgB,EAAE,aAAa,IAAI,CAAC,CAAC,GAAG,CAAC;YACzD,YAAY,EAAE,OAAO,CAAC,IAAI;YAC1B,cAAc,EAAE,QAAQ;SACzB,CAAC;QAEF,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,UAAU,CAAC,CAAC,CAAC;gBAChB,MAAM,IAAI,GAAG,SAAS,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;gBAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;gBACvC,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClD,CAAC;YACD,KAAK,UAAU;gBACb,OAAO,EAAE,GAAG,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC;YAC1C,KAAK,YAAY;gBACf,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;YACrC;gBACE,OAAO,IAAI,CAAC;QAChB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,GAAG,gBAAgB,EAAE,aAAa,EAAE,CAAC,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAmB,CAAC;IACrH,CAAC;AACH,CAAC;AASD,iEAAiE;AACjE,MAAM,UAAU,WAAW,CAAC,MAAqB,EAAE,gBAA+D,EAAE,aAAa,GAAG,CAAC;IACnI,IAAI,CAAC;QACH,IAAI,aAAa,IAAI,YAAY;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,YAAY,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;QAClI,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC,OAAO,EAAE,gBAAgB,EAAE,aAAa,CAAC,CAAC;QAEnG,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;QAC5C,CAAC;QAED,MAAM,QAAQ,GAAG,kBAAkB,CAAC,WAAW,IAAI,gBAAgB,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACxF,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,+BAA+B,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;IACxF,CAAC;AACH,CAAC"}

package/dist/src/session-lock.d.ts

@@ -0,0 +1,35 @@
+export interface LockResult {
+    acquired: boolean;
+    sessionId: string;
+    existingSession: string | null;
+    mode: 'primary' | 'takeover' | 'readonly';
+}
+export interface LockStatus {
+    active: boolean;
+    sessionId: string | null;
+    age: number | null;
+}
+/**
+ * Attempt to acquire the session lock.
+ * - If no lock exists or lock is stale: acquire as primary
+ * - If lock is fresh and held by another: return readonly
+ */
+export declare function acquire({ force }?: {
+    force?: boolean | undefined;
+}): LockResult;
+/**
+ * Release the session lock (called at session end).
+ */
+export declare function release(): void;
+/**
+ * Check if this session currently holds the lock.
+ */
+export declare function isOwner(): boolean;
+/**
+ * Get current lock status without modifying it.
+ */
+export declare function status(): LockStatus;
+/**
+ * Manually heartbeat (useful if the automatic timer isn't running).
+ */
+export declare function heartbeat(): void;

package/dist/src/session-lock.js

@@ -0,0 +1,134 @@
+// session-lock.ts — Ensures one active HEAD session at a time.
+// If two shells/chats open, only one owns the cognitive state.
+// The other gets read-only access (can observe but not dispatch).
+//
+// "One ring rules them all" — no split-brain.
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+const STATE_DIR = join(process.cwd(), '.dualbrain');
+const LOCK_FILE = join(STATE_DIR, 'session.lock');
+const STALE_THRESHOLD_MS = 90_000; // 90 seconds without heartbeat = stale
+const HEARTBEAT_INTERVAL_MS = 30_000;
+let _heartbeatTimer = null;
+let _sessionId = null;
+/**
+ * Attempt to acquire the session lock.
+ * - If no lock exists or lock is stale: acquire as primary
+ * - If lock is fresh and held by another: return readonly
+ */
+export function acquire({ force = false } = {}) {
+    mkdirSync(STATE_DIR, { recursive: true });
+    _sessionId = _generateSessionId();
+    const existing = _readLock();
+    if (!existing) {
+        // No lock — claim it
+        _writeLock(_sessionId);
+        _startHeartbeat();
+        return { acquired: true, sessionId: _sessionId, existingSession: null, mode: 'primary' };
+    }
+    // Same process (re-entry within same session) — always grant
+    if (existing.pid === process.pid) {
+        _sessionId = existing.sessionId;
+        return { acquired: true, sessionId: _sessionId, existingSession: null, mode: 'primary' };
+    }
+    const age = Date.now() - existing.heartbeat;
+    if (age > STALE_THRESHOLD_MS || force) {
+        // Stale or forced takeover
+        _writeLock(_sessionId);
+        _startHeartbeat();
+        return { acquired: true, sessionId: _sessionId, existingSession: existing.sessionId, mode: 'takeover' };
+    }
+    // Another session is active — go readonly
+    return { acquired: false, sessionId: _sessionId, existingSession: existing.sessionId, mode: 'readonly' };
+}
+/**
+ * Release the session lock (called at session end).
+ */
+export function release() {
+    if (_heartbeatTimer) {
+        clearInterval(_heartbeatTimer);
+        _heartbeatTimer = null;
+    }
+    try {
+        const existing = _readLock();
+        if (existing && existing.sessionId === _sessionId) {
+            unlinkSync(LOCK_FILE);
+        }
+    }
+    catch { /* non-fatal */ }
+}
+/**
+ * Check if this session currently holds the lock.
+ */
+export function isOwner() {
+    const existing = _readLock();
+    return existing?.sessionId === _sessionId;
+}
+/**
+ * Get current lock status without modifying it.
+ */
+export function status() {
+    const existing = _readLock();
+    if (!existing)
+        return { active: false, sessionId: null, age: null };
+    return {
+        active: (Date.now() - existing.heartbeat) < STALE_THRESHOLD_MS,
+        sessionId: existing.sessionId,
+        age: Date.now() - existing.heartbeat,
+    };
+}
+/**
+ * Manually heartbeat (useful if the automatic timer isn't running).
+ */
+export function heartbeat() {
+    if (!_sessionId)
+        return;
+    const existing = _readLock();
+    if (existing && existing.sessionId === _sessionId) {
+        _writeLock(_sessionId);
+    }
+}
+// ── Internal ──────────────────────────────────────────────────────────────────
+function _generateSessionId() {
+    return Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 8);
+}
+function _readLock() {
+    try {
+        if (!existsSync(LOCK_FILE))
+            return null;
+        return JSON.parse(readFileSync(LOCK_FILE, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function _writeLock(sessionId) {
+    const lock = {
+        sessionId,
+        heartbeat: Date.now(),
+        pid: process.pid,
+    };
+    writeFileSync(LOCK_FILE, JSON.stringify(lock));
+}
+function _startHeartbeat() {
+    if (_heartbeatTimer)
+        clearInterval(_heartbeatTimer);
+    _heartbeatTimer = setInterval(() => {
+        try {
+            const existing = _readLock();
+            if (existing && existing.sessionId === _sessionId) {
+                _writeLock(_sessionId);
+            }
+            else {
+                // Someone else took over — stop heartbeating
+                clearInterval(_heartbeatTimer);
+                _heartbeatTimer = null;
+            }
+        }
+        catch { /* non-fatal */ }
+    }, HEARTBEAT_INTERVAL_MS);
+    // Don't keep the process alive just for heartbeats
+    if (_heartbeatTimer.unref)
+        _heartbeatTimer.unref();
+}
+//# sourceMappingURL=session-lock.js.map

package/dist/src/session-lock.js.map

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