0xray 4.0.11 → 4.0.13

package/dist/nucleus/lead-dev-plan-persistence.js

@@ -1,402 +0,0 @@
-/**
- * Todo-level lead-dev plan persistence — spawn gate survives beyond 4h mtime
- * while outstanding todos remain. SSOT for plan todo status sync.
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import { SYNTHESIS_REALIGNMENT_PHASE_ID } from './autonomy-kernel.js';
-import { DEFAULT_PENDING_TTL_MS } from './pending-delegations.js';
-import { completeSynthesisCheckpoint, getSynthesisCheckpointSessionId, isSynthesisCheckpointDue, recordExecutionSlice, } from './synthesis.js';
-import { hasValidSynthesisConsultReceipt, isSynthesisConsultTodoId, loadSynthesisConsultReceipt, } from './synthesis-consult-receipt.js';
-import { resolveSpawnPlan } from './spawn-plan-resolution.js';
-import { isAsideActiveForSession, isUserAsideTodoId, isUserAsidesEnabled, parseAsideIdFromTodoId, findAsideContainingTodo, updateUserAsideTodoStatus, } from './user-aside.js';
-export const DEFAULT_PLAN_STALE_MS = 8 * 60 * 60 * 1000;
-export const DEFAULT_PLAN_ARCHIVE_MARKER_MS = 24 * 60 * 60 * 1000;
-export function leadDevPlanStatePath(projectRoot = process.cwd()) {
-    return path.join(projectRoot, '.xray', 'state', 'lead-dev-plan.json');
-}
-export function loadLeadDevPlanStaleMs(projectRoot = process.cwd()) {
-    const featuresPath = path.join(projectRoot, '.xray', 'features.json');
-    if (!fs.existsSync(featuresPath))
-        return DEFAULT_PLAN_STALE_MS;
-    try {
-        const data = JSON.parse(fs.readFileSync(featuresPath, 'utf8'));
-        const hours = data.multi_agent_orchestration?.plan_stale_hours;
-        if (typeof hours === 'number' && hours > 0) {
-            return hours * 60 * 60 * 1000;
-        }
-    }
-    catch {
-        /* keep default */
-    }
-    return DEFAULT_PLAN_STALE_MS;
-}
-export function loadLeadDevPlanArchiveMarkerMs(projectRoot = process.cwd()) {
-    const featuresPath = path.join(projectRoot, '.xray', 'features.json');
-    if (!fs.existsSync(featuresPath))
-        return DEFAULT_PLAN_ARCHIVE_MARKER_MS;
-    try {
-        const data = JSON.parse(fs.readFileSync(featuresPath, 'utf8'));
-        const hours = data.multi_agent_orchestration?.plan_archive_marker_hours;
-        if (typeof hours === 'number' && hours > 0) {
-            return hours * 60 * 60 * 1000;
-        }
-    }
-    catch {
-        /* keep default */
-    }
-    return DEFAULT_PLAN_ARCHIVE_MARKER_MS;
-}
-function planAgeMs(plan, projectRoot) {
-    const persistedAt = plan.persistedAt;
-    if (persistedAt) {
-        const age = Date.now() - new Date(persistedAt).getTime();
-        if (Number.isFinite(age))
-            return age;
-    }
-    try {
-        const stat = fs.statSync(leadDevPlanStatePath(projectRoot));
-        return Date.now() - stat.mtimeMs;
-    }
-    catch {
-        return Number.POSITIVE_INFINITY;
-    }
-}
-/**
- * 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 function isProtectedSynthesisRealignmentPlan(plan) {
-    return isSynthesisRealignmentPlan(plan) && !areSynthesisConsultTodosComplete(plan);
-}
-/**
- * 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 function isLeadDevPlanStale(plan, projectRoot = process.cwd()) {
-    if (!plan.active)
-        return false;
-    if (isProtectedSynthesisRealignmentPlan(plan))
-        return false;
-    const outstanding = getOutstandingTodos(plan);
-    if (outstanding.length === 0)
-        return false;
-    const allStillPending = outstanding.every((t) => t.status === 'pending');
-    if (!allStillPending)
-        return false;
-    return planAgeMs(plan, projectRoot) > loadLeadDevPlanStaleMs(projectRoot);
-}
-export function archiveStaleLeadDevPlan(projectRoot = process.cwd()) {
-    const plan = loadPersistedLeadDevPlan(projectRoot);
-    if (!plan) {
-        return { archived: false };
-    }
-    if (isProtectedSynthesisRealignmentPlan(plan)) {
-        return { archived: false, reason: 'synthesis-realignment-active' };
-    }
-    if (!isLeadDevPlanStale(plan, projectRoot)) {
-        return { archived: false };
-    }
-    const stateDir = path.dirname(leadDevPlanStatePath(projectRoot));
-    fs.mkdirSync(stateDir, { recursive: true });
-    const archivePath = path.join(stateDir, `lead-dev-plan.archived-${Date.now()}.json`);
-    const payload = {
-        ...plan,
-        active: false,
-        archivedAt: new Date().toISOString(),
-        archiveReason: 'stale-unstarted-todos',
-    };
-    fs.writeFileSync(archivePath, JSON.stringify(payload, null, 2));
-    fs.unlinkSync(leadDevPlanStatePath(projectRoot));
-    return { archived: true, archivePath, reason: 'stale-unstarted-todos' };
-}
-/** Recent stale archival — keeps spawn-plan-stale gate after session-start cleanup. */
-export function findRecentStalePlanArchive(projectRoot = process.cwd(), maxAgeMs = loadLeadDevPlanArchiveMarkerMs(projectRoot)) {
-    const stateDir = path.join(projectRoot, '.xray', 'state');
-    if (!fs.existsSync(stateDir))
-        return null;
-    const candidates = fs
-        .readdirSync(stateDir)
-        .filter((name) => name.startsWith('lead-dev-plan.archived-') && name.endsWith('.json'))
-        .map((name) => {
-        const archivePath = path.join(stateDir, name);
-        return { archivePath, mtimeMs: fs.statSync(archivePath).mtimeMs };
-    })
-        .sort((a, b) => b.mtimeMs - a.mtimeMs);
-    for (const candidate of candidates) {
-        try {
-            const data = JSON.parse(fs.readFileSync(candidate.archivePath, 'utf8'));
-            if (data.archiveReason !== 'stale-unstarted-todos')
-                continue;
-            const archivedAtMs = data.archivedAt
-                ? new Date(data.archivedAt).getTime()
-                : candidate.mtimeMs;
-            if (!Number.isFinite(archivedAtMs))
-                continue;
-            if (Date.now() - archivedAtMs > maxAgeMs)
-                continue;
-            return {
-                archivePath: candidate.archivePath,
-                archivedAt: data.archivedAt ?? new Date(archivedAtMs).toISOString(),
-            };
-        }
-        catch {
-            /* skip corrupt archive */
-        }
-    }
-    return null;
-}
-export function loadPersistedLeadDevPlan(projectRoot = process.cwd()) {
-    const planPath = leadDevPlanStatePath(projectRoot);
-    if (!fs.existsSync(planPath))
-        return null;
-    try {
-        return JSON.parse(fs.readFileSync(planPath, 'utf8'));
-    }
-    catch {
-        return null;
-    }
-}
-export function savePersistedLeadDevPlan(plan, projectRoot = process.cwd()) {
-    const planPath = leadDevPlanStatePath(projectRoot);
-    fs.mkdirSync(path.dirname(planPath), { recursive: true });
-    fs.writeFileSync(planPath, JSON.stringify(plan, null, 2));
-    return planPath;
-}
-export function allPlanTodos(plan) {
-    return (plan.phases ?? []).flatMap((p) => p.todos ?? []);
-}
-export function getOutstandingTodos(plan) {
-    return allPlanTodos(plan).filter((t) => t.status === 'pending' || t.status === 'in_progress');
-}
-/** First outstanding todo in phase order */
-export function getNextRequiredTodo(plan) {
-    for (const phase of plan.phases ?? []) {
-        const next = (phase.todos ?? []).find((t) => t.status === 'pending' || t.status === 'in_progress');
-        if (next)
-            return next;
-    }
-    return null;
-}
-/**
- * Plan valid for spawn when active and either:
- * - outstanding todos remain (ignores 4h mtime), or
- * - all todos complete and persistedAt within TTL
- */
-export function hasValidLeadDevPlanForSpawn(projectRoot = process.cwd(), _sessionId) {
-    const plan = loadPersistedLeadDevPlan(projectRoot);
-    if (!plan?.active)
-        return false;
-    if (isLeadDevPlanStale(plan, projectRoot))
-        return false;
-    const outstanding = getOutstandingTodos(plan);
-    if (outstanding.length > 0)
-        return true;
-    const persistedAt = plan.persistedAt;
-    if (!persistedAt) {
-        try {
-            const stat = fs.statSync(leadDevPlanStatePath(projectRoot));
-            return Date.now() - stat.mtimeMs <= DEFAULT_PENDING_TTL_MS;
-        }
-        catch {
-            return false;
-        }
-    }
-    return Date.now() - new Date(persistedAt).getTime() <= DEFAULT_PENDING_TTL_MS;
-}
-export function isSynthesisRealignmentPlan(plan) {
-    return (plan.phases ?? []).some((p) => p.id === SYNTHESIS_REALIGNMENT_PHASE_ID);
-}
-export function getSynthesisConsultTodos(plan) {
-    const phase = (plan.phases ?? []).find((p) => p.id === SYNTHESIS_REALIGNMENT_PHASE_ID);
-    return phase?.todos ?? [];
-}
-export function areSynthesisConsultTodosComplete(plan) {
-    const todos = getSynthesisConsultTodos(plan);
-    return todos.length > 0 && todos.every((t) => t.status === 'completed');
-}
-function shouldRecordGeneralTodoSlice(plan, todoId) {
-    if (!isSynthesisRealignmentPlan(plan))
-        return true;
-    const consultIds = new Set(getSynthesisConsultTodos(plan).map((t) => t.id));
-    return !consultIds.has(todoId);
-}
-function tryCompleteSynthesisCheckpointAfterTodo(projectRoot, sessionId) {
-    const sid = sessionId ?? getSynthesisCheckpointSessionId(projectRoot);
-    if (!sid || !isSynthesisCheckpointDue(projectRoot, sid))
-        return;
-    const plan = loadPersistedLeadDevPlan(projectRoot);
-    if (!plan || !isSynthesisRealignmentPlan(plan))
-        return;
-    if (!areSynthesisConsultTodosComplete(plan))
-        return;
-    const completed = completeSynthesisCheckpoint(projectRoot, sid);
-    if (completed) {
-        void import('./synthesis-completion.js').then(({ runSynthesisCheckpointSideEffects }) => runSynthesisCheckpointSideEffects(projectRoot, sid, plan, completed));
-    }
-}
-export function updatePlanTodoStatus(todoId, status, projectRoot = process.cwd(), sessionId) {
-    if (isUserAsidesEnabled(projectRoot) && isUserAsideTodoId(todoId)) {
-        return updateUserAsideTodoStatus(todoId, status, projectRoot, sessionId);
-    }
-    const plan = loadPersistedLeadDevPlan(projectRoot);
-    if (!plan)
-        return false;
-    let targetTodo;
-    for (const phase of plan.phases) {
-        for (const todo of phase.todos) {
-            if (todo.id === todoId) {
-                targetTodo = todo;
-                break;
-            }
-        }
-        if (targetTodo)
-            break;
-    }
-    if (status === 'completed' && isSynthesisConsultTodoId(todoId)) {
-        const receiptExpected = {};
-        if (plan.sessionId !== undefined)
-            receiptExpected.sessionId = plan.sessionId;
-        if (targetTodo?.subagent)
-            receiptExpected.subagent = targetTodo.subagent;
-        if (!hasValidSynthesisConsultReceipt(todoId, projectRoot, receiptExpected)) {
-            return false;
-        }
-        const receipt = loadSynthesisConsultReceipt(todoId, projectRoot);
-        if (receipt?.verdict === 'FAIL') {
-            return false;
-        }
-    }
-    let updated = false;
-    for (const phase of plan.phases) {
-        for (const todo of phase.todos) {
-            if (todo.id === todoId) {
-                todo.status = status;
-                updated = true;
-            }
-        }
-    }
-    if (updated) {
-        savePersistedLeadDevPlan(plan, projectRoot);
-        if (status === 'completed') {
-            if (shouldRecordGeneralTodoSlice(plan, todoId)) {
-                const sid = plan.sessionId ?? getSynthesisCheckpointSessionId(projectRoot);
-                if (sid) {
-                    recordExecutionSlice('todo_completed', { projectRoot, sessionId: sid });
-                }
-            }
-            tryCompleteSynthesisCheckpointAfterTodo(projectRoot, plan.sessionId);
-        }
-    }
-    return updated;
-}
-export function bindPlanToSession(sessionId, projectRoot = process.cwd()) {
-    const plan = loadPersistedLeadDevPlan(projectRoot);
-    if (!plan)
-        return null;
-    const generation = (plan.planGeneration ?? 0) + 1;
-    const next = {
-        ...plan,
-        sessionId,
-        planGeneration: generation,
-        persistedAt: new Date().toISOString(),
-    };
-    savePersistedLeadDevPlan(next, projectRoot);
-    return next;
-}
-function normalizeAgent(agent) {
-    const key = agent.toLowerCase().trim();
-    const aliases = {
-        'bug-triage-specialist': 'bug-triage',
-        'code-reviewer': 'code-review',
-    };
-    return aliases[key] ?? key;
-}
-function agentsAlign(expected, actual) {
-    const e = normalizeAgent(expected);
-    const a = normalizeAgent(actual);
-    return e === a || e.includes(a) || a.includes(e);
-}
-export function validateSpawnMatchesTodo(toolInput, projectRoot = process.cwd(), expectedTodo, sessionId) {
-    const explicitTodo = toolInput.planTodoId;
-    if (explicitTodo &&
-        isUserAsideTodoId(explicitTodo) &&
-        isUserAsidesEnabled(projectRoot)) {
-        const parsedId = parseAsideIdFromTodoId(explicitTodo);
-        const targetAside = parsedId
-            ? findAsideContainingTodo(explicitTodo, projectRoot, parsedId)
-            : null;
-        if (targetAside && !isAsideActiveForSession(targetAside.id, projectRoot, sessionId)) {
-            return {
-                valid: false,
-                reason: `Aside \`${targetAside.id}\` is not active for this session`,
-                gate: 'aside-session-mismatch',
-                expectedTodoId: explicitTodo,
-                hint: {
-                    tool: 'orchestrate-task',
-                    userAsideId: targetAside.id,
-                    track: 'user-aside',
-                },
-            };
-        }
-    }
-    const resolved = isUserAsidesEnabled(projectRoot)
-        ? resolveSpawnPlan(toolInput, projectRoot, sessionId)
-        : { source: 'main', plan: loadPersistedLeadDevPlan(projectRoot) };
-    const plan = resolved.plan;
-    const nextTodo = expectedTodo ?? (plan ? getNextRequiredTodo(plan) : null);
-    if (!nextTodo) {
-        return { valid: true };
-    }
-    const prompt = String(toolInput.prompt || toolInput.description || toolInput.task || '').toLowerCase();
-    const subagent = String(toolInput.subagent_type || toolInput.agent || '');
-    const explicitMatch = toolInput.planTodoId || toolInput.delegationId;
-    if (explicitMatch && explicitMatch === nextTodo.id) {
-        return { valid: true, expectedTodoId: nextTodo.id };
-    }
-    if (prompt.includes(nextTodo.id.toLowerCase())) {
-        return { valid: true, expectedTodoId: nextTodo.id };
-    }
-    if (prompt.includes(nextTodo.task.toLowerCase().slice(0, 30))) {
-        return { valid: true, expectedTodoId: nextTodo.id };
-    }
-    if (subagent && agentsAlign(nextTodo.subagent, subagent) && prompt.length > 20) {
-        return { valid: true, expectedTodoId: nextTodo.id };
-    }
-    const hint = {
-        tool: 'Task',
-        subagent_type: nextTodo.subagent,
-        planTodoId: nextTodo.id,
-        description: `Lead-dev todo ${nextTodo.id}: ${nextTodo.task}. ` +
-            `Include plan todo id in Task prompt.`,
-    };
-    if (resolved.source === 'aside' && resolved.asideId) {
-        hint.asideId = resolved.asideId;
-        hint.track = 'user-aside';
-        if (resolved.worktree)
-            hint.worktree = resolved.worktree;
-        if (resolved.branch)
-            hint.branch = resolved.branch;
-    }
-    return {
-        valid: false,
-        reason: resolved.source === 'aside'
-            ? `Spawn must target aside todo ${nextTodo.id} (aside ${resolved.asideId}) before other work`
-            : `Spawn must target plan todo ${nextTodo.id} before other work`,
-        gate: resolved.source === 'aside' ? 'aside-spawn-todo' : 'spawn-todo-persistence',
-        expectedTodoId: nextTodo.id,
-        hint,
-    };
-}
-export function markTodoInProgressOnSpawn(toolInput, projectRoot = process.cwd(), sessionId) {
-    const resolved = isUserAsidesEnabled(projectRoot)
-        ? resolveSpawnPlan(toolInput, projectRoot, sessionId)
-        : { source: 'main', plan: loadPersistedLeadDevPlan(projectRoot) };
-    if (!resolved.plan)
-        return null;
-    const validation = validateSpawnMatchesTodo(toolInput, projectRoot, undefined, sessionId);
-    if (!validation.valid || !validation.expectedTodoId)
-        return null;
-    updatePlanTodoStatus(validation.expectedTodoId, 'in_progress', projectRoot);
-    return validation.expectedTodoId;
-}

package/dist/nucleus/pending-delegations.d.ts

@@ -1,71 +0,0 @@
-/**
- * Pending delegations SSOT — written by task-handler on delegate-deferred.
- * Grok hooks read the same file; PostToolUse never re-parses MCP output.
- */
-import type { LeadDevPlan, LeadDevTodo } from './autonomy-kernel.js';
-export declare const DEFAULT_PENDING_TTL_MS: number;
-export type DelegationMatchMethod = 'taskId' | 'description' | 'agent-only' | 'none';
-export interface SpawnHint {
-    tool: 'Task';
-    subagent_type: string;
-    description: string;
-    planTodoId: string | null;
-    delegationId: string;
-}
-export interface PendingDelegation {
-    id: string;
-    taskId: string;
-    agent: string;
-    taskDescription: string;
-    taskType: string;
-    sessionId: string;
-    planTodoId: string | null;
-    planTodoTask: string | null;
-    matchMethod: DelegationMatchMethod;
-    matchConfidence: number;
-    status: 'pending' | 'satisfied';
-    createdAt: string;
-    satisfiedAt: string | null;
-    spawnHint: SpawnHint;
-}
-export interface PendingDelegationsState {
-    sessionId: string;
-    createdAt: string;
-    ttlMs: number;
-    delegations: PendingDelegation[];
-}
-export interface DeferredTaskRecord {
-    taskId: string;
-    agent: string;
-    description: string;
-    type?: string;
-}
-export declare function pendingDelegationsPath(projectRoot?: string): string;
-export declare function leadDevPlanPath(projectRoot?: string): string;
-export declare function isAutoChainDelegationsEnabled(projectRoot?: string): boolean;
-export declare function matchPlanTodo(agent: string, taskDescription: string, taskId: string, plan: LeadDevPlan | null): {
-    todo: LeadDevTodo | null;
-    method: DelegationMatchMethod;
-    confidence: number;
-};
-export declare function mapSubagentToTaskType(agent: string): string;
-export declare function buildSpawnHint(delegation: Pick<PendingDelegation, 'id' | 'agent' | 'taskDescription' | 'planTodoId' | 'planTodoTask'>): SpawnHint;
-export declare function loadPendingDelegationsState(projectRoot?: string): PendingDelegationsState | null;
-export declare function savePendingDelegationsState(state: PendingDelegationsState, projectRoot?: string): string;
-export declare function recordDeferredDelegations(sessionId: string, deferrals: DeferredTaskRecord[], projectRoot?: string): PendingDelegation[];
-export declare function isPendingStateActive(state: PendingDelegationsState | null, sessionId: string | null | undefined): boolean;
-export declare function getActivePendingDelegations(sessionId: string | null | undefined, projectRoot?: string): PendingDelegation[];
-export interface SatisfyDelegationInput {
-    delegationId?: string;
-    taskId?: string;
-    planTodoId?: string;
-    agent?: string;
-    toolPrompt?: string;
-}
-export declare function satisfyDelegation(input: SatisfyDelegationInput, projectRoot?: string): {
-    satisfied: PendingDelegation[];
-    clearedAll: boolean;
-};
-export declare function clearPendingDelegations(projectRoot?: string): boolean;
-export declare function clearPendingDelegationsForSessionChange(newSessionId: string | null | undefined, projectRoot?: string): boolean;
-export declare function delegationSummaryForResponse(delegations: PendingDelegation[]): Array<Record<string, unknown>>;