0xray 3.5.4 → 3.5.5

package/dist/nucleus/confer.js

@@ -0,0 +1,308 @@
+/**
+ * Confer — mandatory 3-agent quorum SSOT (researcher / architect-tools / code-review).
+ * Triggered automatically at synthesis checkpoint; records consult receipts + plan todos.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { MANDATORY_MAJOR_CONSULTS } from './autonomy-kernel.js';
+import { areSynthesisConsultTodosComplete, getNextRequiredTodo, getSynthesisConsultTodos, isSynthesisRealignmentPlan, loadPersistedLeadDevPlan, updatePlanTodoStatus, } from './lead-dev-plan-persistence.js';
+import { buildReceiptFromConsultOutput, tryRecordSynthesisConsultReceipt, parseConsultVerdictFromText, } from './synthesis-consult-receipt.js';
+import { isSynthesisCheckpointDue } from './synthesis.js';
+export const CONFER_AGENTS = [...MANDATORY_MAJOR_CONSULTS];
+const STATE_VERSION = 1;
+export function conferCheckpointPath(projectRoot = process.cwd()) {
+    return path.join(projectRoot, '.xray', 'state', 'confer-checkpoint.json');
+}
+export function defaultConferConfig() {
+    return { enabled: true, on_synthesis: true };
+}
+export function loadConferConfig(projectRoot = process.cwd()) {
+    const featuresPath = path.join(projectRoot, '.xray', 'features.json');
+    if (!fs.existsSync(featuresPath))
+        return defaultConferConfig();
+    try {
+        const data = JSON.parse(fs.readFileSync(featuresPath, 'utf8'));
+        const orch = data.multi_agent_orchestration ?? {};
+        const raw = orch.confer ?? {};
+        return {
+            enabled: raw.enabled !== false && orch.confer_on_synthesis !== false,
+            on_synthesis: raw.on_synthesis !== false && orch.confer_on_synthesis !== false,
+        };
+    }
+    catch {
+        return defaultConferConfig();
+    }
+}
+export function isConferEnabled(projectRoot = process.cwd()) {
+    return loadConferConfig(projectRoot).enabled;
+}
+export function loadConferCheckpoint(projectRoot = process.cwd()) {
+    const statePath = conferCheckpointPath(projectRoot);
+    if (!fs.existsSync(statePath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveConferCheckpoint(state, projectRoot = process.cwd()) {
+    const statePath = conferCheckpointPath(projectRoot);
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+    return statePath;
+}
+export function triggerConferCheckpoint(sessionId, dueReason, projectRoot = process.cwd()) {
+    const state = {
+        version: STATE_VERSION,
+        sessionId,
+        triggeredAt: new Date().toISOString(),
+        dueReason,
+        status: 'pending',
+        completedAgents: [],
+    };
+    saveConferCheckpoint(state, projectRoot);
+    return state;
+}
+export function isConferPending(projectRoot = process.cwd(), sessionId) {
+    const plan = loadPersistedLeadDevPlan(projectRoot);
+    if (!plan || !isSynthesisRealignmentPlan(plan))
+        return false;
+    if (areSynthesisConsultTodosComplete(plan))
+        return false;
+    if (sessionId && isSynthesisCheckpointDue(projectRoot, sessionId))
+        return true;
+    const state = loadConferCheckpoint(projectRoot);
+    if (!state || state.status === 'completed')
+        return false;
+    if (sessionId && state.sessionId !== sessionId)
+        return false;
+    return true;
+}
+export function buildConferPrompt(subagent, todoTask, collocatedText, dueReason) {
+    const reasonLine = dueReason ? `Due: ${dueReason}\n\n` : '';
+    return `${reasonLine}## Confer quorum — ${subagent}
+
+${todoTask}
+
+Review the collocated synthesis context and return a structured verdict.
+
+**Required in your response:**
+- Verdict: PASS | CONDITIONAL | FAIL
+- Top risks (bulleted)
+- Hardening note / recommendations
+
+---
+
+${collocatedText}`;
+}
+/** Map confer subagent → MCP server + tool. */
+export function conferAgentMcpTarget(subagent) {
+    switch (subagent) {
+        case 'architect-tools':
+            return {
+                server: 'architect-tools',
+                tool: 'architecture-assessment',
+                args: (prompt, projectRoot) => ({
+                    projectRoot,
+                    assessmentType: 'comprehensive',
+                    focusMetrics: ['complexity', 'coupling', 'cohesion', 'testability', 'scalability'],
+                    conferPrompt: prompt,
+                }),
+            };
+        case 'researcher':
+            return {
+                server: 'researcher',
+                tool: 'analyze_proposal',
+                args: (prompt) => ({
+                    proposalTitle: 'Synthesis confer — researcher',
+                    proposalDescription: prompt,
+                    proposalType: 'synthesis-confer',
+                    evidence: [],
+                }),
+            };
+        case 'code-review':
+        default:
+            return {
+                server: 'code-review',
+                tool: 'analyze_proposal',
+                args: (prompt) => ({
+                    proposalTitle: 'Synthesis confer — code-review',
+                    proposalDescription: prompt,
+                    proposalType: 'synthesis-confer',
+                    evidence: [],
+                }),
+            };
+    }
+}
+function extractMcpText(result) {
+    const content = result?.content;
+    if (Array.isArray(content)) {
+        return content.map((c) => c.text ?? '').join('\n');
+    }
+    if (typeof result === 'string')
+        return result;
+    try {
+        return JSON.stringify(result);
+    }
+    catch {
+        return String(result);
+    }
+}
+export async function invokeConferAgent(subagent, prompt, projectRoot = process.cwd()) {
+    const { mcpClientManager } = await import('../mcps/mcp-client.js');
+    const target = conferAgentMcpTarget(subagent);
+    const args = target.args(prompt, projectRoot);
+    const result = await mcpClientManager.callServerTool(target.server, target.tool, args);
+    const text = extractMcpText(result);
+    if (!text.trim()) {
+        throw new Error(`Empty confer response from ${subagent}`);
+    }
+    if (!parseConsultVerdictFromText(text)) {
+        throw new Error(`Confer response from ${subagent} missing parseable verdict (expected Verdict: PASS|CONDITIONAL|FAIL or DECISION: approve|reject|abstain)`);
+    }
+    return text;
+}
+export function applyConferConsultResult(todoId, subagent, sessionId, outputText, projectRoot = process.cwd()) {
+    const receipt = tryRecordSynthesisConsultReceipt(todoId, subagent, sessionId, outputText, projectRoot);
+    let todoCompleted = false;
+    if (receipt && receipt.verdict !== 'FAIL') {
+        todoCompleted = updatePlanTodoStatus(todoId, 'completed', projectRoot);
+    }
+    return {
+        todoId,
+        subagent,
+        outputText,
+        receiptRecorded: receipt != null,
+        todoCompleted,
+        verdict: receipt?.verdict ?? buildReceiptFromConsultOutput(todoId, subagent, sessionId, outputText)?.verdict ?? null,
+    };
+}
+export function writeFixtureConferReceipt(todoId, subagent, sessionId, projectRoot = process.cwd()) {
+    const output = `Verdict: PASS\nTop risks: none\nHardening: confer fixture quorum for ${subagent}`;
+    return applyConferConsultResult(todoId, subagent, sessionId, output, projectRoot);
+}
+export async function runConferQuorum(projectRoot = process.cwd(), sessionId, options = {}) {
+    const cfg = loadConferConfig(projectRoot);
+    if (!cfg.enabled || !cfg.on_synthesis) {
+        return {
+            status: 'skipped',
+            agents: [],
+            message: 'Confer disabled in features.json',
+        };
+    }
+    const plan = loadPersistedLeadDevPlan(projectRoot);
+    if (!plan || !isSynthesisRealignmentPlan(plan)) {
+        return {
+            status: 'skipped',
+            agents: [],
+            message: 'No synthesis realignment plan — confer not applicable',
+        };
+    }
+    if (areSynthesisConsultTodosComplete(plan)) {
+        return {
+            status: 'completed',
+            agents: [],
+            message: 'Confer already complete — all consult todos finished',
+        };
+    }
+    const state = triggerConferCheckpoint(sessionId, options.dueReason ?? null, projectRoot);
+    state.status = 'in_progress';
+    saveConferCheckpoint(state, projectRoot);
+    const collocated = options.collocatedText?.trim() ||
+        '# Synthesis confer\n\nReview checkpoint context and realign plan.';
+    const agents = [];
+    for (const todo of getSynthesisConsultTodos(plan)) {
+        if (todo.status === 'completed')
+            continue;
+        try {
+            let agentResult;
+            if (options.fixture) {
+                agentResult = writeFixtureConferReceipt(todo.id, todo.subagent, sessionId, projectRoot);
+            }
+            else {
+                const prompt = buildConferPrompt(todo.subagent, todo.task, collocated, options.dueReason ?? null);
+                const outputText = await invokeConferAgent(todo.subagent, prompt, projectRoot);
+                agentResult = applyConferConsultResult(todo.id, todo.subagent, sessionId, outputText, projectRoot);
+            }
+            agents.push(agentResult);
+            if (agentResult.receiptRecorded && agentResult.todoCompleted) {
+                state.completedAgents.push(todo.subagent);
+                saveConferCheckpoint(state, projectRoot);
+            }
+            else {
+                state.status = 'failed';
+                state.lastError = `Receipt or todo completion failed for ${todo.id}`;
+                saveConferCheckpoint(state, projectRoot);
+                return {
+                    status: 'partial',
+                    agents,
+                    message: state.lastError,
+                };
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            state.status = 'failed';
+            state.lastError = message;
+            saveConferCheckpoint(state, projectRoot);
+            agents.push({
+                todoId: todo.id,
+                subagent: todo.subagent,
+                outputText: '',
+                receiptRecorded: false,
+                todoCompleted: false,
+                verdict: null,
+                error: message,
+            });
+            return { status: 'failed', agents, message };
+        }
+    }
+    const refreshed = loadPersistedLeadDevPlan(projectRoot);
+    const done = refreshed &&
+        isSynthesisRealignmentPlan(refreshed) &&
+        areSynthesisConsultTodosComplete(refreshed);
+    state.status = done ? 'completed' : 'failed';
+    if (!done)
+        state.lastError = 'Consult todos remain after confer loop';
+    saveConferCheckpoint(state, projectRoot);
+    return {
+        status: done ? 'completed' : 'partial',
+        agents,
+        message: done
+            ? 'Confer quorum complete — researcher, architect-tools, code-review consulted'
+            : (state.lastError ?? 'Confer incomplete'),
+    };
+}
+const CONFER_AGENT_EMOJI = {
+    researcher: '🔍',
+    'architect-tools': '🏗️',
+    'code-review': '✅',
+    'code-reviewer': '✅',
+    architect: '🏗️',
+    strategist: '🎯',
+};
+function conferAgentEmoji(subagent) {
+    return CONFER_AGENT_EMOJI[subagent] ?? '🤖';
+}
+export function formatConferQuorumReport(result) {
+    if (result.status === 'skipped') {
+        return `ℹ️ Confer skipped: ${result.message}`;
+    }
+    const lines = [
+        `## Confer quorum — ${result.status.toUpperCase()}`,
+        result.message,
+        '',
+    ];
+    for (const agent of result.agents) {
+        const emoji = conferAgentEmoji(agent.subagent);
+        lines.push(`- ${emoji} **${agent.todoId}** (${agent.subagent}): verdict=${agent.verdict ?? 'n/a'} receipt=${agent.receiptRecorded} todo=${agent.todoCompleted}${agent.error ? ` error=${agent.error}` : ''}`);
+    }
+    const plan = loadPersistedLeadDevPlan();
+    const next = plan ? getNextRequiredTodo(plan) : null;
+    if (next) {
+        lines.push('', `**Next todo:** ${next.id} (${next.subagent})`);
+    }
+    return lines.join('\n');
+}

package/dist/nucleus/delegation-gate.d.ts

@@ -6,6 +6,7 @@
 import { type PendingDelegation } from './pending-delegations.js';
 export { getActivePendingDelegations } from './pending-delegations.js';
 import { updatePlanTodoStatus, type SpawnToolInput } from './lead-dev-plan-persistence.js';
+export { extractSpawnCwd, validateAsideWorktreeCwd, provisionGitWorktree } from './aside-worktree.js';
 export { validateSpawnMatchesTodo, updatePlanTodoStatus, savePersistedLeadDevPlan, } from './lead-dev-plan-persistence.js';
 export { buildReceiptFromConsultOutput, hasValidSynthesisConsultReceipt, isSynthesisConsultTodoId, loadSynthesisConsultReceipt, parseConsultVerdictFromText, tryRecordSynthesisConsultReceipt, writeSynthesisConsultReceipt, type SynthesisConsultReceipt, type SynthesisConsultVerdict, } from './synthesis-consult-receipt.js';
 export declare const updatePlanTodoStatusInPlace: typeof updatePlanTodoStatus;
@@ -52,6 +53,9 @@ export interface PreToolGateDeny {
 }
 export interface PreToolGateAllow {
     allow: true;
+    reason?: string;
+    gate?: string;
+    hint?: Record<string, unknown>;
 }
 export type PreToolGateResult = PreToolGateAllow | PreToolGateDeny;
 export interface PostToolSpawnResult {

package/dist/nucleus/delegation-gate.js

@@ -7,9 +7,29 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { getActivePendingDelegations, satisfyDelegation, } from './pending-delegations.js';
 export { getActivePendingDelegations } from './pending-delegations.js';
-import { allPlanTodos, areSynthesisConsultTodosComplete, getSynthesisConsultTodos, hasValidLeadDevPlanForSpawn, isSynthesisRealignmentPlan, loadPersistedLeadDevPlan, getNextRequiredTodo, validateSpawnMatchesTodo, updatePlanTodoStatus, } from './lead-dev-plan-persistence.js';
+import { allPlanTodos, areSynthesisConsultTodosComplete, findRecentStalePlanArchive, getSynthesisConsultTodos, isLeadDevPlanStale, isSynthesisRealignmentPlan, loadPersistedLeadDevPlan, getNextRequiredTodo, validateSpawnMatchesTodo, updatePlanTodoStatus, } from './lead-dev-plan-persistence.js';
 import { getSynthesisDueReason, isSynthesisCheckpointDue, recordExecutionSlice, } from './synthesis.js';
 import { isSynthesisConsultTodoId, tryRecordSynthesisConsultReceipt, } from './synthesis-consult-receipt.js';
+import { resolveSpawnPlan, hasValidSpawnPlanContext } from './spawn-plan-resolution.js';
+import { isUserAsidesEnabled, isUserAsideTodoId, loadActiveAsidePointer, loadActiveUserAside, } from './user-aside.js';
+import { validateAsideWorktreeCwd, } from './aside-worktree.js';
+export { extractSpawnCwd, validateAsideWorktreeCwd, provisionGitWorktree } from './aside-worktree.js';
+function denyAsideWorktreeCwd(cwdCheck) {
+    const base = {
+        allow: false,
+        reason: cwdCheck.reason ?? 'Aside spawn cwd must match worktree',
+        gate: cwdCheck.gate ?? 'aside-worktree-cwd-missing',
+    };
+    return cwdCheck.hint ? { ...base, hint: cwdCheck.hint } : base;
+}
+function asideWorktreeCwdDenyIfNeeded(activeAside, toolInput, projectRoot) {
+    if (!activeAside?.worktree)
+        return undefined;
+    const cwdCheck = validateAsideWorktreeCwd(activeAside.worktree, toolInput, projectRoot);
+    if (!cwdCheck.valid)
+        return denyAsideWorktreeCwd(cwdCheck);
+    return undefined;
+}
 export { validateSpawnMatchesTodo, updatePlanTodoStatus, savePersistedLeadDevPlan, } from './lead-dev-plan-persistence.js';
 export { buildReceiptFromConsultOutput, hasValidSynthesisConsultReceipt, isSynthesisConsultTodoId, loadSynthesisConsultReceipt, parseConsultVerdictFromText, tryRecordSynthesisConsultReceipt, writeSynthesisConsultReceipt, } from './synthesis-consult-receipt.js';
 export const updatePlanTodoStatusInPlace = updatePlanTodoStatus;
@@ -182,7 +202,29 @@ export function evaluateSpawnPlanGate(toolName, toolInput, ctx) {
     if (!ctx.features.lead_dev_mode || !isSubagentTool(toolName)) {
         return { allow: true };
     }
-    if (!hasValidLeadDevPlanForSpawn(ctx.projectRoot, ctx.sessionId)) {
+    const activeAside = isUserAsidesEnabled(ctx.projectRoot)
+        ? loadActiveUserAside(ctx.projectRoot, ctx.sessionId)
+        : null;
+    const plan = loadPersistedLeadDevPlan(ctx.projectRoot);
+    if (!activeAside && plan && isLeadDevPlanStale(plan, ctx.projectRoot)) {
+        return {
+            allow: false,
+            reason: 'Lead-dev plan is stale (unstarted todos exceeded TTL) — ' +
+                're-run xray-orchestrator analyze-complexity to refresh the plan',
+            gate: 'spawn-plan-stale',
+            hint: { tool: 'analyze-complexity', mcp: 'xray-orchestrator' },
+        };
+    }
+    if (!hasValidSpawnPlanContext(ctx.projectRoot, ctx.sessionId)) {
+        if (findRecentStalePlanArchive(ctx.projectRoot)) {
+            return {
+                allow: false,
+                reason: 'Lead-dev plan was stale and archived — ' +
+                    're-run xray-orchestrator analyze-complexity to refresh the plan',
+                gate: 'spawn-plan-stale',
+                hint: { tool: 'analyze-complexity', mcp: 'xray-orchestrator' },
+            };
+        }
         return {
             allow: false,
             reason: 'Codex 59/67: call xray-orchestrator analyze-complexity first — ' +
@@ -191,17 +233,26 @@ export function evaluateSpawnPlanGate(toolName, toolInput, ctx) {
         };
     }
     if (ctx.features.auto_chain_delegations === false) {
+        const cwdDeny = asideWorktreeCwdDenyIfNeeded(activeAside, toolInput, ctx.projectRoot);
+        if (cwdDeny)
+            return cwdDeny;
         return { allow: true };
     }
+    const normalized = normalizeHostToolInput(toolInput);
+    const resolved = isUserAsidesEnabled(ctx.projectRoot)
+        ? resolveSpawnPlan(normalized, ctx.projectRoot, ctx.sessionId)
+        : { source: 'main', plan: loadPersistedLeadDevPlan(ctx.projectRoot) };
     const pending = getActivePendingDelegations(ctx.sessionId, ctx.projectRoot);
-    const plan = loadPersistedLeadDevPlan(ctx.projectRoot);
-    const expectedTodo = pending[0]?.planTodoId && plan
-        ? allPlanTodos(plan).find((t) => t.id === pending[0].planTodoId) ?? null
+    const expectedTodo = pending[0]?.planTodoId && resolved.plan
+        ? allPlanTodos(resolved.plan).find((t) => t.id === pending[0].planTodoId) ?? null
         : null;
-    const validation = validateSpawnMatchesTodo(normalizeHostToolInput(toolInput), ctx.projectRoot, expectedTodo);
+    const validation = validateSpawnMatchesTodo(normalized, ctx.projectRoot, expectedTodo, ctx.sessionId);
     if (!validation.valid) {
         return denyFromSpawnValidation(validation);
     }
+    const cwdDeny = asideWorktreeCwdDenyIfNeeded(activeAside, toolInput, ctx.projectRoot);
+    if (cwdDeny)
+        return cwdDeny;
     return { allow: true };
 }
 /** Block writes / spawns / shell while synthesis checkpoint is due. */
@@ -213,13 +264,32 @@ export function evaluateSynthesisGate(toolName, toolInput, ctx) {
         return { allow: true };
     if (isSynthesisAllowedOrchestratorConsult(toolName, toolInput))
         return { allow: true };
+    // Active user aside: allow aside-track subagent spawns during main synthesis checkpoint.
+    if (isUserAsidesEnabled(ctx.projectRoot)) {
+        const normalized = normalizeHostToolInput(toolInput);
+        const resolved = resolveSpawnPlan(normalized, ctx.projectRoot, ctx.sessionId);
+        if (resolved.source === 'aside' &&
+            isSubagentTool(toolName) &&
+            (normalized.planTodoId
+                ? isUserAsideTodoId(normalized.planTodoId)
+                : Boolean(resolved.asideId))) {
+            const validation = validateSpawnMatchesTodo(normalized, ctx.projectRoot, undefined, ctx.sessionId);
+            if (validation.valid) {
+                const activeAside = loadActiveUserAside(ctx.projectRoot, ctx.sessionId);
+                const cwdDeny = asideWorktreeCwdDenyIfNeeded(activeAside, toolInput, ctx.projectRoot);
+                if (cwdDeny)
+                    return cwdDeny;
+                return { allow: true };
+            }
+        }
+    }
     const plan = loadPersistedLeadDevPlan(ctx.projectRoot);
     if (plan &&
         isSynthesisRealignmentPlan(plan) &&
         !areSynthesisConsultTodosComplete(plan) &&
         isSubagentTool(toolName)) {
         const nextTodo = getNextRequiredTodo(plan);
-        const validation = validateSpawnMatchesTodo(normalizeHostToolInput(toolInput), ctx.projectRoot, nextTodo);
+        const validation = validateSpawnMatchesTodo(normalizeHostToolInput(toolInput), ctx.projectRoot, nextTodo, ctx.sessionId);
         if (validation.valid)
             return { allow: true };
     }
@@ -252,6 +322,13 @@ export function evaluatePendingDelegationGate(toolName, toolInput, ctx) {
     const pending = getActivePendingDelegations(ctx.sessionId, ctx.projectRoot);
     if (pending.length === 0)
         return { allow: true };
+    // Aside-track work: pending main delegations do not block aside spawns.
+    if (isUserAsidesEnabled(ctx.projectRoot) && isSubagentTool(toolName)) {
+        const normalized = normalizeHostToolInput(toolInput);
+        const resolved = resolveSpawnPlan(normalized, ctx.projectRoot, ctx.sessionId);
+        if (resolved.source === 'aside')
+            return { allow: true };
+    }
     if (isSubagentTool(toolName))
         return { allow: true };
     if (isReadOnlyTool(toolName))
@@ -285,11 +362,14 @@ export function evaluatePreToolGate(toolName, toolInput, ctx) {
     const spawnBlock = evaluateSpawnPlanGate(toolName, toolInput, ctx);
     if (!spawnBlock.allow)
         return spawnBlock;
-    return { allow: true };
+    return spawnBlock;
 }
 export function evaluatePostToolSpawn(toolName, toolInput, projectRoot, options = {}) {
     const normalized = normalizeHostToolInput(toolInput);
-    const spawnCheck = validateSpawnMatchesTodo(normalized, projectRoot);
+    const pointer = loadActiveAsidePointer(projectRoot);
+    const mainPlan = loadPersistedLeadDevPlan(projectRoot);
+    const sessionId = options.sessionId ?? mainPlan?.sessionId ?? pointer?.sessionId ?? null;
+    const spawnCheck = validateSpawnMatchesTodo(normalized, projectRoot, undefined, sessionId);
     const satisfyInput = {
         toolPrompt: normalized.prompt ?? '',
     };
@@ -306,7 +386,6 @@ export function evaluatePostToolSpawn(toolName, toolInput, projectRoot, options
     const expectedTodoId = spawnCheck.expectedTodoId ?? null;
     if (spawnCheck.valid && expectedTodoId) {
         const plan = loadPersistedLeadDevPlan(projectRoot);
-        const sessionId = options.sessionId ?? plan?.sessionId ?? null;
         const consultTodo = plan
             ? getSynthesisConsultTodos(plan).find((t) => t.id === expectedTodoId)
             : undefined;
@@ -317,7 +396,7 @@ export function evaluatePostToolSpawn(toolName, toolInput, projectRoot, options
             const receipt = tryRecordSynthesisConsultReceipt(expectedTodoId, consultTodo.subagent, sessionId, options.toolOutput, projectRoot);
             receiptRecorded = receipt != null;
         }
-        if (updatePlanTodoStatus(expectedTodoId, 'completed', projectRoot)) {
+        if (updatePlanTodoStatus(expectedTodoId, 'completed', projectRoot, sessionId)) {
             todoCompleted = true;
         }
     }

package/dist/nucleus/lead-dev-plan-persistence.d.ts

@@ -15,7 +15,31 @@ export interface SpawnTodoValidation {
     hint?: Record<string, unknown>;
     expectedTodoId?: string | null;
 }
+export declare const DEFAULT_PLAN_STALE_MS: number;
+export declare const DEFAULT_PLAN_ARCHIVE_MARKER_MS: number;
 export declare function leadDevPlanStatePath(projectRoot?: string): string;
+export declare function loadLeadDevPlanStaleMs(projectRoot?: string): number;
+export declare function loadLeadDevPlanArchiveMarkerMs(projectRoot?: string): number;
+/**
+ * Mandatory synthesis consults (s.1–s.3) must stay spawnable until complete —
+ * never treat an active realignment plan as stale while consult todos remain.
+ */
+export declare function isProtectedSynthesisRealignmentPlan(plan: PersistedLeadDevPlan): boolean;
+/**
+ * Stale when every outstanding todo is still pending and plan age exceeds TTL.
+ * In-progress or completed todos imply active work — plan stays valid.
+ */
+export declare function isLeadDevPlanStale(plan: PersistedLeadDevPlan, projectRoot?: string): boolean;
+export declare function archiveStaleLeadDevPlan(projectRoot?: string): {
+    archived: boolean;
+    archivePath?: string;
+    reason?: string;
+};
+/** Recent stale archival — keeps spawn-plan-stale gate after session-start cleanup. */
+export declare function findRecentStalePlanArchive(projectRoot?: string, maxAgeMs?: number): {
+    archivePath: string;
+    archivedAt: string;
+} | null;
 export declare function loadPersistedLeadDevPlan(projectRoot?: string): PersistedLeadDevPlan | null;
 export declare function savePersistedLeadDevPlan(plan: PersistedLeadDevPlan, projectRoot?: string): string;
 export declare function allPlanTodos(plan: PersistedLeadDevPlan): LeadDevTodo[];
@@ -31,7 +55,7 @@ export declare function hasValidLeadDevPlanForSpawn(projectRoot?: string, _sessi
 export declare function isSynthesisRealignmentPlan(plan: PersistedLeadDevPlan): boolean;
 export declare function getSynthesisConsultTodos(plan: PersistedLeadDevPlan): LeadDevTodo[];
 export declare function areSynthesisConsultTodosComplete(plan: PersistedLeadDevPlan): boolean;
-export declare function updatePlanTodoStatus(todoId: string, status: LeadDevTodo['status'], projectRoot?: string): boolean;
+export declare function updatePlanTodoStatus(todoId: string, status: LeadDevTodo['status'], projectRoot?: string, sessionId?: string | null): boolean;
 export declare function bindPlanToSession(sessionId: string, projectRoot?: string): PersistedLeadDevPlan | null;
 export interface SpawnToolInput {
     prompt?: string;
@@ -42,5 +66,5 @@ export interface SpawnToolInput {
     delegationId?: string;
     planTodoId?: string;
 }
-export declare function validateSpawnMatchesTodo(toolInput: SpawnToolInput, projectRoot?: string, expectedTodo?: LeadDevTodo | null): SpawnTodoValidation;
-export declare function markTodoInProgressOnSpawn(toolInput: SpawnToolInput, projectRoot?: string): string | null;
+export declare function validateSpawnMatchesTodo(toolInput: SpawnToolInput, projectRoot?: string, expectedTodo?: LeadDevTodo | null, sessionId?: string | null): SpawnTodoValidation;
+export declare function markTodoInProgressOnSpawn(toolInput: SpawnToolInput, projectRoot?: string, sessionId?: string | null): string | null;