0xray 4.0.13 → 4.0.14

package/dist/nucleus/user-aside.js

@@ -0,0 +1,393 @@
+/**
+ * User aside — parallel work tracks (worktree-like) declared by the user.
+ * SSOT: `.xray/state/asides/{id}.json` + `_active.json`.
+ * Todo ids: `{asideId}.a.{phase}.{todo}` — globally unique per aside.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { buildLeadDevPlan, isLeadDevModeActive, } from './autonomy-kernel.js';
+import { allPlanTodos, getNextRequiredTodo, getOutstandingTodos, } from './lead-dev-plan-persistence.js';
+export const USER_ASIDE_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+/** Namespaced aside todo: `suit-nft.a.1.1` */
+export const USER_ASIDE_TODO_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}\.a\.\d+\.\d+$/;
+export const USER_ASIDE_STATE_VERSION = 1;
+export class UserAsideValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UserAsideValidationError';
+    }
+}
+export function assertSafeAsideId(asideId) {
+    const trimmed = asideId.trim();
+    if (!trimmed || !USER_ASIDE_ID_PATTERN.test(trimmed)) {
+        throw new UserAsideValidationError(`Invalid aside id "${asideId}" — use [a-zA-Z0-9][a-zA-Z0-9._-]{0,63}`);
+    }
+    if (trimmed.includes('..') || trimmed.includes('/') || trimmed.includes('\\')) {
+        throw new UserAsideValidationError(`Invalid aside id "${asideId}" — path characters forbidden`);
+    }
+    return trimmed;
+}
+export function asideTodoId(asideId, phaseIndex, todoIndex) {
+    return `${assertSafeAsideId(asideId)}.a.${phaseIndex + 1}.${todoIndex + 1}`;
+}
+export function isUserAsideTodoId(todoId) {
+    return USER_ASIDE_TODO_PATTERN.test(todoId);
+}
+export function parseAsideIdFromTodoId(todoId) {
+    if (!isUserAsideTodoId(todoId))
+        return null;
+    const dotA = todoId.indexOf('.a.');
+    if (dotA <= 0)
+        return null;
+    const asideId = todoId.slice(0, dotA);
+    try {
+        return assertSafeAsideId(asideId);
+    }
+    catch {
+        return null;
+    }
+}
+export function userAsidesDir(projectRoot = process.cwd()) {
+    return path.join(projectRoot, '.xray', 'state', 'asides');
+}
+export function userAsidePath(asideId, projectRoot = process.cwd()) {
+    const safe = assertSafeAsideId(asideId);
+    const resolved = path.resolve(userAsidesDir(projectRoot), `${safe}.json`);
+    const base = path.resolve(userAsidesDir(projectRoot));
+    if (!resolved.startsWith(base + path.sep) && resolved !== base) {
+        throw new UserAsideValidationError(`Aside path escapes asides directory: ${asideId}`);
+    }
+    return resolved;
+}
+export function activeAsidePointerPath(projectRoot = process.cwd()) {
+    return path.join(userAsidesDir(projectRoot), '_active.json');
+}
+export function isUserAsidesEnabled(projectRoot = process.cwd()) {
+    const featuresPath = path.join(projectRoot, '.xray', 'features.json');
+    if (!fs.existsSync(featuresPath))
+        return isLeadDevModeActive();
+    try {
+        const data = JSON.parse(fs.readFileSync(featuresPath, 'utf8'));
+        const raw = data.multi_agent_orchestration?.user_asides;
+        if (raw?.enabled === false)
+            return false;
+        return isLeadDevModeActive();
+    }
+    catch {
+        return isLeadDevModeActive();
+    }
+}
+function validateLoadedAside(parsed, expectedId) {
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const row = parsed;
+    if (row.version !== USER_ASIDE_STATE_VERSION)
+        return null;
+    if (!row.id || !row.title || !row.description || !row.plan)
+        return null;
+    if (!Array.isArray(row.plan.phases))
+        return null;
+    try {
+        assertSafeAsideId(row.id);
+    }
+    catch {
+        return null;
+    }
+    if (expectedId && row.id !== expectedId)
+        return null;
+    for (const phase of row.plan.phases) {
+        if (!phase?.todos || !Array.isArray(phase.todos))
+            return null;
+    }
+    return row;
+}
+function remapPhasesToAsidePrefix(asideId, phases) {
+    const safeId = assertSafeAsideId(asideId);
+    return phases.map((phase, phaseIndex) => ({
+        ...phase,
+        id: phase.id.startsWith('phase-') ? `aside-phase-${phaseIndex + 1}` : phase.id,
+        todos: phase.todos.map((todo, todoIndex) => ({
+            ...todo,
+            id: asideTodoId(safeId, phaseIndex, todoIndex),
+            status: todo.status ?? 'pending',
+        })),
+    }));
+}
+/** Build a phased aside plan from task intake (mirrors lead-dev plan, namespaced todo ids). */
+export function buildUserAsidePlan(asideId, title, description, taskInputs = [], mcpOverallComplexity, projectRoot = process.cwd()) {
+    if (!isUserAsidesEnabled(projectRoot))
+        return null;
+    const safeId = assertSafeAsideId(asideId);
+    const taskTypes = taskInputs.map((t) => t.type ?? 'implement');
+    const basePlan = buildLeadDevPlan(description, taskTypes, taskInputs, mcpOverallComplexity, projectRoot);
+    if (!basePlan)
+        return null;
+    return {
+        version: USER_ASIDE_STATE_VERSION,
+        id: safeId,
+        title,
+        status: 'active',
+        description,
+        persistedAt: new Date().toISOString(),
+        plan: {
+            ...basePlan,
+            description: `[Aside ${safeId}] ${description}`,
+            phases: remapPhasesToAsidePrefix(safeId, basePlan.phases),
+        },
+    };
+}
+/** Merge new task intake into an existing aside (re-intake). */
+export function mergeUserAsideIntake(existing, description, taskInputs, mcpOverallComplexity, projectRoot = process.cwd()) {
+    const fresh = buildUserAsidePlan(existing.id, existing.title, description || existing.description, taskInputs.length > 0 ? taskInputs : [{ description: existing.description, type: 'implement' }], mcpOverallComplexity, projectRoot);
+    if (!fresh)
+        return existing;
+    const mergedPhases = [...existing.plan.phases];
+    for (const phase of fresh.plan.phases) {
+        const match = mergedPhases.find((p) => p.id === phase.id);
+        if (match) {
+            const existingIds = new Set(match.todos.map((t) => t.id));
+            for (const todo of phase.todos) {
+                if (!existingIds.has(todo.id))
+                    match.todos.push(todo);
+            }
+        }
+        else {
+            mergedPhases.push(phase);
+        }
+    }
+    return {
+        ...existing,
+        description: description || existing.description,
+        status: existing.status === 'completed' ? 'active' : existing.status,
+        plan: { ...existing.plan, phases: mergedPhases },
+    };
+}
+export function loadUserAside(asideId, projectRoot = process.cwd()) {
+    try {
+        const filePath = userAsidePath(asideId, projectRoot);
+        if (!fs.existsSync(filePath))
+            return null;
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        return validateLoadedAside(parsed, assertSafeAsideId(asideId));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveUserAside(aside, projectRoot = process.cwd()) {
+    assertSafeAsideId(aside.id);
+    const dir = userAsidesDir(projectRoot);
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = userAsidePath(aside.id, projectRoot);
+    const payload = {
+        ...aside,
+        version: USER_ASIDE_STATE_VERSION,
+        persistedAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(filePath, JSON.stringify(payload, null, 2));
+    return filePath;
+}
+export function listUserAsideIds(projectRoot = process.cwd()) {
+    const dir = userAsidesDir(projectRoot);
+    if (!fs.existsSync(dir))
+        return [];
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.json') && f !== '_active.json')
+        .map((f) => f.replace(/\.json$/, ''))
+        .filter((id) => USER_ASIDE_ID_PATTERN.test(id));
+}
+export function loadActiveAsidePointer(projectRoot = process.cwd()) {
+    const pointerPath = activeAsidePointerPath(projectRoot);
+    if (!fs.existsSync(pointerPath))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(pointerPath, 'utf8'));
+        if (!parsed?.asideId)
+            return null;
+        assertSafeAsideId(parsed.asideId);
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function getActiveAsideId(projectRoot = process.cwd(), sessionId) {
+    if (!isUserAsidesEnabled(projectRoot))
+        return null;
+    const pointer = loadActiveAsidePointer(projectRoot);
+    if (!pointer)
+        return null;
+    if (pointer.sessionId) {
+        if (!sessionId || pointer.sessionId !== sessionId)
+            return null;
+    }
+    const aside = loadUserAside(pointer.asideId, projectRoot);
+    if (!aside || aside.status !== 'active')
+        return null;
+    return pointer.asideId;
+}
+export function setActiveAsideId(asideId, projectRoot = process.cwd(), sessionId) {
+    const safeId = assertSafeAsideId(asideId);
+    const aside = loadUserAside(safeId, projectRoot);
+    if (!aside) {
+        throw new UserAsideValidationError(`Cannot activate aside "${safeId}" — file not found at .xray/state/asides/${safeId}.json`);
+    }
+    if (aside.status !== 'active' && aside.status !== 'paused') {
+        throw new UserAsideValidationError(`Cannot activate aside "${safeId}" — status is ${aside.status}`);
+    }
+    if (aside.status === 'paused') {
+        aside.status = 'active';
+        saveUserAside(aside, projectRoot);
+    }
+    const dir = userAsidesDir(projectRoot);
+    fs.mkdirSync(dir, { recursive: true });
+    const pointer = {
+        asideId: safeId,
+        activatedAt: new Date().toISOString(),
+        ...(sessionId ? { sessionId } : {}),
+    };
+    fs.writeFileSync(activeAsidePointerPath(projectRoot), JSON.stringify(pointer, null, 2));
+    return pointer;
+}
+export function clearActiveAside(projectRoot = process.cwd()) {
+    const pointerPath = activeAsidePointerPath(projectRoot);
+    if (!fs.existsSync(pointerPath))
+        return false;
+    fs.unlinkSync(pointerPath);
+    return true;
+}
+export function loadActiveUserAside(projectRoot = process.cwd(), sessionId) {
+    const id = getActiveAsideId(projectRoot, sessionId);
+    if (!id) {
+        const pointer = loadActiveAsidePointer(projectRoot);
+        if (pointer) {
+            const aside = loadUserAside(pointer.asideId, projectRoot);
+            if (aside && aside.status !== 'active')
+                clearActiveAside(projectRoot);
+        }
+        return null;
+    }
+    const aside = loadUserAside(id, projectRoot);
+    if (!aside || aside.status !== 'active') {
+        clearActiveAside(projectRoot);
+        return null;
+    }
+    return aside;
+}
+/** PersistedLeadDevPlan view of an aside for spawn-gate reuse. */
+export function asideToSpawnPlan(aside) {
+    const plan = { ...aside.plan };
+    if (aside.persistedAt)
+        plan.persistedAt = aside.persistedAt;
+    if (aside.sessionId)
+        plan.sessionId = aside.sessionId;
+    return plan;
+}
+/** Aside routable when active for session, or pointer is unscoped (accepted exception). */
+export function isAsideActiveForSession(asideId, projectRoot = process.cwd(), sessionId) {
+    const activeId = getActiveAsideId(projectRoot, sessionId);
+    if (activeId === asideId)
+        return true;
+    const pointer = loadActiveAsidePointer(projectRoot);
+    if (!pointer || pointer.asideId !== asideId)
+        return false;
+    if (!pointer.sessionId)
+        return true;
+    return Boolean(sessionId && pointer.sessionId === sessionId);
+}
+export function findAsideContainingTodo(todoId, projectRoot = process.cwd(), preferredAsideId) {
+    if (!isUserAsideTodoId(todoId))
+        return null;
+    if (preferredAsideId) {
+        const direct = loadUserAside(preferredAsideId, projectRoot);
+        if (direct) {
+            const hit = allPlanTodos(asideToSpawnPlan(direct)).some((t) => t.id === todoId);
+            if (hit)
+                return direct;
+        }
+    }
+    const parsedId = parseAsideIdFromTodoId(todoId);
+    if (parsedId) {
+        const aside = loadUserAside(parsedId, projectRoot);
+        if (aside) {
+            const hit = allPlanTodos(asideToSpawnPlan(aside)).some((t) => t.id === todoId);
+            if (hit)
+                return aside;
+        }
+    }
+    return null;
+}
+export function updateUserAsideTodoStatus(todoId, status, projectRoot = process.cwd(), sessionId) {
+    const parsedId = parseAsideIdFromTodoId(todoId);
+    let aside = parsedId
+        ? findAsideContainingTodo(todoId, projectRoot, parsedId)
+        : null;
+    if (aside && parsedId && !isAsideActiveForSession(parsedId, projectRoot, sessionId)) {
+        aside = null;
+    }
+    if (!aside)
+        aside = loadActiveUserAside(projectRoot, sessionId);
+    if (!aside)
+        return false;
+    let updated = false;
+    for (const phase of aside.plan.phases) {
+        for (const todo of phase.todos) {
+            if (todo.id === todoId) {
+                todo.status = status;
+                updated = true;
+            }
+        }
+    }
+    if (!updated)
+        return false;
+    const outstanding = getOutstandingTodos(asideToSpawnPlan(aside));
+    if (outstanding.length === 0) {
+        aside.status = 'completed';
+        clearActiveAside(projectRoot);
+    }
+    saveUserAside(aside, projectRoot);
+    return true;
+}
+export function getNextAsideTodo(aside) {
+    return getNextRequiredTodo(asideToSpawnPlan(aside));
+}
+export function formatUserAsideSummary(aside) {
+    const todos = allPlanTodos(asideToSpawnPlan(aside));
+    const done = todos.filter((t) => t.status === 'completed').length;
+    const lines = [
+        `**Aside \`${aside.id}\`** — ${aside.title}`,
+        `Status: ${aside.status} | Todos: ${done}/${todos.length}`,
+        aside.worktree ? `Worktree: \`${aside.worktree}\`` : null,
+        aside.branch ? `Branch: \`${aside.branch}\`` : null,
+        '',
+        ...todos.map((t) => `- [${t.status === 'completed' ? 'x' : ' '}] ${t.id} (${t.subagent}): ${t.task}`),
+    ].filter(Boolean);
+    return lines.join('\n');
+}
+export function getUserAsideBootHints(projectRoot = process.cwd(), sessionId) {
+    if (!isUserAsidesEnabled(projectRoot))
+        return null;
+    const aside = loadActiveUserAside(projectRoot, sessionId);
+    if (!aside)
+        return null;
+    const hints = {
+        activeAside: aside.id,
+        asideTitle: aside.title,
+        asideStatus: aside.status,
+        asideTodoPrefix: `${aside.id}.a.*`,
+        asideHint: 'Spawns route to active aside todos; orchestrate-task clearActiveAside to resume main',
+    };
+    if (aside.worktree)
+        hints.asideWorktree = aside.worktree;
+    if (aside.branch)
+        hints.asideBranch = aside.branch;
+    if (aside.governance?.trapSignals?.length) {
+        hints.asideTrapSignals = aside.governance.trapSignals;
+    }
+    if (aside.governance?.conferOnPhaseStart) {
+        hints.asideConferRecommended = true;
+        hints.asideConferTrigger = 'orchestrate-task { confer: true } or synthesis analyze-complexity';
+    }
+    return hints;
+}

package/dist/orchestrator/agent-spawn-governor.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Agent Spawn Governor
+ *
+ * Critical governance component that prevents infinite agent spawning
+ * and enforces spawn limits across the multi-agent orchestration system.
+ *
+ * @since 2026-01-23
+ */
+export interface SpawnContext {
+    agentType: string;
+    parentAgent?: string;
+    operation?: string;
+    triggeredBy?: string;
+    sessionId?: string;
+    priority?: "high" | "medium" | "low";
+}
+export interface SpawnRecord {
+    id: string;
+    agentType: string;
+    parentAgent?: string | undefined;
+    timestamp: number;
+    status: "active" | "completed" | "failed" | "terminated";
+    context: SpawnContext;
+}
+export interface SpawnLimits {
+    perAgentType: Record<string, number>;
+    totalConcurrent: number;
+    spawnRateLimit: {
+        maxPerMinute: number;
+        windowMs: number;
+    };
+    memoryLimit: {
+        maxMemoryMB: number;
+        emergencyThresholdMB: number;
+        cleanupIntervalMs: number;
+    };
+}
+export interface SpawnAuthorization {
+    authorized: boolean;
+    trackingId?: string;
+    reason?: string;
+    warnings?: string[];
+}
+export declare class AgentSpawnGovernor {
+    private limits;
+    private activeAgents;
+    private spawnHistory;
+    private readonly maxHistorySize;
+    private readonly cleanupInterval;
+    private readonly persistenceTimeout;
+    private readonly maxRetries;
+    private readonly retryDelay;
+    private cleanupTimer?;
+    private memoryMonitorInterval?;
+    private authorizationQueue;
+    private isProcessingAuthorization;
+    private getDefaultLimits;
+    private readonly defaultLimits;
+    constructor(limits?: Partial<SpawnLimits>, autoStart?: boolean);
+    private startPeriodicCleanup;
+    private startMemoryMonitoring;
+    private checkMemoryBudget;
+    private emergencyMemoryCleanup;
+    private aggressiveCleanup;
+    private deepCleanupContexts;
+    private sanitizeContext;
+    /**
+     * Authorize a new agent spawn
+     */
+    authorizeSpawn(context: SpawnContext): Promise<SpawnAuthorization>;
+    private processNextAuthorization;
+    private performAuthorization;
+    private checkAgentLimitsWithRetry;
+    private getTotalActiveWithRetry;
+    private registerSpawnWithRetry;
+    private handleAuthorizationError;
+    private categorizeError;
+    private emergencyCleanup;
+    /**
+     * Complete an agent spawn (mark as completed)
+     */
+    completeSpawn(trackingId: string, result?: boolean): Promise<void>;
+    /**
+     * Fail an agent spawn
+     */
+    failSpawn(trackingId: string, error?: Error): Promise<void>;
+    /**
+     * Terminate an agent spawn (force stop)
+     */
+    terminateSpawn(trackingId: string, reason?: string): Promise<void>;
+    /**
+     * Get current active count for agent type
+     */
+    getActiveCount(agentType: string): number;
+    /**
+     * Get total active agents system-wide
+     */
+    getTotalActive(): number;
+    /**
+     * Get spawn statistics
+     */
+    getSpawnStats(): {
+        perAgentType: Record<string, {
+            active: number;
+            total: number;
+        }>;
+        totalActive: number;
+        totalHistory: number;
+    };
+    /**
+     * Emergency: Terminate all active agents
+     */
+    emergencyShutdown(reason?: string): Promise<void>;
+    private registerSpawn;
+    private checkSpawnRateLimit;
+    private detectInfiniteSpawn;
+    private getRecentSpawns;
+    private findRecord;
+    private generateTrackingId;
+    private cleanupOldRecords;
+    private withTimeout;
+    private withRetry;
+    start(): void;
+    destroy(): void;
+}
+export declare const agentSpawnGovernor: AgentSpawnGovernor;