0xray 3.5.4 → 3.5.5

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

@@ -7,10 +7,145 @@ 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, } from './synthesis-consult-receipt.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))
@@ -52,6 +187,8 @@ export function hasValidLeadDevPlanForSpawn(projectRoot = process.cwd(), _sessio
     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;
@@ -98,7 +235,10 @@ function tryCompleteSynthesisCheckpointAfterTodo(projectRoot, sessionId) {
         void import('./synthesis-completion.js').then(({ runSynthesisCheckpointSideEffects }) => runSynthesisCheckpointSideEffects(projectRoot, sid, plan, completed));
     }
 }
-export function updatePlanTodoStatus(todoId, status, projectRoot = process.cwd()) {
+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;
@@ -122,6 +262,10 @@ export function updatePlanTodoStatus(todoId, status, projectRoot = process.cwd()
         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) {
@@ -173,16 +317,41 @@ function agentsAlign(expected, actual) {
     const a = normalizeAgent(actual);
     return e === a || e.includes(a) || a.includes(e);
 }
-export function validateSpawnMatchesTodo(toolInput, projectRoot = process.cwd(), expectedTodo) {
-    const plan = loadPersistedLeadDevPlan(projectRoot);
+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 explicitTodo = toolInput.planTodoId || toolInput.delegationId;
-    if (explicitTodo && explicitTodo === nextTodo.id) {
+    const explicitMatch = toolInput.planTodoId || toolInput.delegationId;
+    if (explicitMatch && explicitMatch === nextTodo.id) {
         return { valid: true, expectedTodoId: nextTodo.id };
     }
     if (prompt.includes(nextTodo.id.toLowerCase())) {
@@ -194,25 +363,38 @@ export function validateSpawnMatchesTodo(toolInput, projectRoot = process.cwd(),
     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: `Spawn must target plan todo ${nextTodo.id} before other work`,
-        gate: 'spawn-todo-persistence',
+        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: {
-            tool: 'Task',
-            subagent_type: nextTodo.subagent,
-            planTodoId: nextTodo.id,
-            description: `Lead-dev todo ${nextTodo.id}: ${nextTodo.task}. ` +
-                `Include plan todo id in Task prompt.`,
-        },
+        hint,
     };
 }
-export function markTodoInProgressOnSpawn(toolInput, projectRoot = process.cwd()) {
-    const plan = loadPersistedLeadDevPlan(projectRoot);
-    if (!plan)
+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);
+    const validation = validateSpawnMatchesTodo(toolInput, projectRoot, undefined, sessionId);
     if (!validation.valid || !validation.expectedTodoId)
         return null;
     updatePlanTodoStatus(validation.expectedTodoId, 'in_progress', projectRoot);

package/dist/nucleus/spawn-plan-resolution.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Spawn plan resolution SSOT — main lead-dev plan vs active user aside.
+ * Extracted to avoid circular imports between user-aside and lead-dev-plan-persistence.
+ */
+import { type PersistedLeadDevPlan } from './lead-dev-plan-persistence.js';
+export interface SpawnPlanResolution {
+    source: 'main' | 'aside' | 'none';
+    asideId?: string;
+    plan: PersistedLeadDevPlan | null;
+    worktree?: string;
+    branch?: string;
+}
+export interface SpawnPlanToolInput {
+    planTodoId?: string;
+    prompt?: string;
+    description?: string;
+    task?: string;
+}
+export declare function resolveSpawnPlan(toolInput: SpawnPlanToolInput, projectRoot?: string, sessionId?: string | null): SpawnPlanResolution;
+export declare function hasValidSpawnPlanContext(projectRoot?: string, sessionId?: string | null): boolean;

package/dist/nucleus/spawn-plan-resolution.js

@@ -0,0 +1,42 @@
+/**
+ * Spawn plan resolution SSOT — main lead-dev plan vs active user aside.
+ * Extracted to avoid circular imports between user-aside and lead-dev-plan-persistence.
+ */
+import { getOutstandingTodos, hasValidLeadDevPlanForSpawn, loadPersistedLeadDevPlan, } from './lead-dev-plan-persistence.js';
+import { asideToSpawnPlan, findAsideContainingTodo, isAsideActiveForSession, isUserAsideTodoId, isUserAsidesEnabled, loadActiveUserAside, parseAsideIdFromTodoId, } from './user-aside.js';
+export function resolveSpawnPlan(toolInput, projectRoot = process.cwd(), sessionId) {
+    const explicitTodo = toolInput.planTodoId;
+    if (explicitTodo && isUserAsideTodoId(explicitTodo)) {
+        const parsedAsideId = parseAsideIdFromTodoId(explicitTodo);
+        const aside = findAsideContainingTodo(explicitTodo, projectRoot, parsedAsideId ?? undefined);
+        if (aside && isAsideActiveForSession(aside.id, projectRoot, sessionId)) {
+            return asideResolution(aside);
+        }
+    }
+    const active = loadActiveUserAside(projectRoot, sessionId);
+    if (active) {
+        return asideResolution(active);
+    }
+    const main = loadPersistedLeadDevPlan(projectRoot);
+    if (main?.active) {
+        return { source: 'main', plan: main };
+    }
+    return { source: 'none', plan: null };
+}
+function asideResolution(aside) {
+    return {
+        source: 'aside',
+        asideId: aside.id,
+        plan: asideToSpawnPlan(aside),
+        ...(aside.worktree ? { worktree: aside.worktree } : {}),
+        ...(aside.branch ? { branch: aside.branch } : {}),
+    };
+}
+export function hasValidSpawnPlanContext(projectRoot = process.cwd(), sessionId) {
+    const active = loadActiveUserAside(projectRoot, sessionId);
+    if (active && isUserAsidesEnabled(projectRoot)) {
+        const plan = asideToSpawnPlan(active);
+        return getOutstandingTodos(plan).length > 0 || plan.active;
+    }
+    return hasValidLeadDevPlanForSpawn(projectRoot, sessionId);
+}

package/dist/nucleus/synthesis-consult-receipt.js

@@ -74,11 +74,27 @@ export function hasValidSynthesisConsultReceipt(todoId, projectRoot = process.cw
 }
 export function parseConsultVerdictFromText(text) {
     const normalized = text.toUpperCase();
+    const decisionMatch = text.match(/\bDECISION:\s*(\w+)/i);
+    if (decisionMatch) {
+        const decision = decisionMatch[1].toLowerCase();
+        if (decision === 'approve' || decision === 'approved' || decision === 'pass') {
+            return 'PASS';
+        }
+        if (decision === 'reject' || decision === 'rejected' || decision === 'fail') {
+            return 'FAIL';
+        }
+        if (decision === 'abstain' ||
+            decision === 'needs_revision' ||
+            decision === 'conditional' ||
+            decision === 'revise') {
+            return 'CONDITIONAL';
+        }
+    }
     if (/\bCONDITIONAL(\s+PASS)?\b/.test(normalized))
         return 'CONDITIONAL';
-    if (/\b(?:PASS|SHIP)\b/.test(normalized))
+    if (/\b(?:PASS|SHIP|APPROVE)\b/.test(normalized))
         return 'PASS';
-    if (/\bFAIL\b/.test(normalized))
+    if (/\b(?:FAIL|REJECT)\b/.test(normalized))
         return 'FAIL';
     return null;
 }

package/dist/nucleus/synthesis-context.js

@@ -78,7 +78,7 @@ export function appendSynthesisContextToResponse(content, collatedText) {
 
 ${collatedText}
 
-**Next:** Spawn Task for each mandatory consult todo (s.1 researcher, s.2 architect-tools, s.3 code-review). Checkpoint clears only when all consult todos complete.`;
+**Next:** Confer quorum runs automatically via analyze-complexity (researcher → architect-tools → code-review). If confer partial-fails, spawn Task for the next consult todo (s.1–s.3). Checkpoint clears when all consult todos complete.`;
     if (content.length === 0) {
         return [{ type: 'text', text: synthesisSection.trim() }];
     }

package/dist/nucleus/user-aside.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 { type LeadDevPlan, type LeadDevPlanTaskInput, type LeadDevTodo } from './autonomy-kernel.js';
+import { type PersistedLeadDevPlan } from './lead-dev-plan-persistence.js';
+export declare const USER_ASIDE_ID_PATTERN: RegExp;
+/** Namespaced aside todo: `suit-nft.a.1.1` */
+export declare const USER_ASIDE_TODO_PATTERN: RegExp;
+export declare const USER_ASIDE_STATE_VERSION: 1;
+export type UserAsideStatus = 'active' | 'paused' | 'completed' | 'archived';
+export interface UserAsideGovernance {
+    /** Session-boot hint to run confer before aside phase work (manual MCP — not auto confer). */
+    conferOnPhaseStart?: boolean;
+    /** Repertoire trap signal names surfaced in session-boot for aside work. */
+    trapSignals?: string[];
+}
+export interface UserAside {
+    version: typeof USER_ASIDE_STATE_VERSION;
+    id: string;
+    title: string;
+    status: UserAsideStatus;
+    owner?: string;
+    description: string;
+    definitionOfDone?: string;
+    worktree?: string;
+    branch?: string;
+    persistedAt?: string;
+    sessionId?: string;
+    governance?: UserAsideGovernance;
+    plan: LeadDevPlan;
+}
+export interface ActiveAsidePointer {
+    asideId: string;
+    activatedAt: string;
+    sessionId?: string;
+}
+export declare class UserAsideValidationError extends Error {
+    constructor(message: string);
+}
+export declare function assertSafeAsideId(asideId: string): string;
+export declare function asideTodoId(asideId: string, phaseIndex: number, todoIndex: number): string;
+export declare function isUserAsideTodoId(todoId: string): boolean;
+export declare function parseAsideIdFromTodoId(todoId: string): string | null;
+export declare function userAsidesDir(projectRoot?: string): string;
+export declare function userAsidePath(asideId: string, projectRoot?: string): string;
+export declare function activeAsidePointerPath(projectRoot?: string): string;
+export declare function isUserAsidesEnabled(projectRoot?: string): boolean;
+/** Build a phased aside plan from task intake (mirrors lead-dev plan, namespaced todo ids). */
+export declare function buildUserAsidePlan(asideId: string, title: string, description: string, taskInputs?: LeadDevPlanTaskInput[], mcpOverallComplexity?: number, projectRoot?: string): UserAside | null;
+/** Merge new task intake into an existing aside (re-intake). */
+export declare function mergeUserAsideIntake(existing: UserAside, description: string, taskInputs: LeadDevPlanTaskInput[], mcpOverallComplexity?: number, projectRoot?: string): UserAside;
+export declare function loadUserAside(asideId: string, projectRoot?: string): UserAside | null;
+export declare function saveUserAside(aside: UserAside, projectRoot?: string): string;
+export declare function listUserAsideIds(projectRoot?: string): string[];
+export declare function loadActiveAsidePointer(projectRoot?: string): ActiveAsidePointer | null;
+export declare function getActiveAsideId(projectRoot?: string, sessionId?: string | null): string | null;
+export declare function setActiveAsideId(asideId: string, projectRoot?: string, sessionId?: string | null): ActiveAsidePointer;
+export declare function clearActiveAside(projectRoot?: string): boolean;
+export declare function loadActiveUserAside(projectRoot?: string, sessionId?: string | null): UserAside | null;
+/** PersistedLeadDevPlan view of an aside for spawn-gate reuse. */
+export declare function asideToSpawnPlan(aside: UserAside): PersistedLeadDevPlan;
+/** Aside routable when active for session, or pointer is unscoped (accepted exception). */
+export declare function isAsideActiveForSession(asideId: string, projectRoot?: string, sessionId?: string | null): boolean;
+export declare function findAsideContainingTodo(todoId: string, projectRoot?: string, preferredAsideId?: string): UserAside | null;
+export declare function updateUserAsideTodoStatus(todoId: string, status: LeadDevTodo['status'], projectRoot?: string, sessionId?: string | null): boolean;
+export declare function getNextAsideTodo(aside: UserAside): LeadDevTodo | null;
+export declare function formatUserAsideSummary(aside: UserAside): string;
+export declare function getUserAsideBootHints(projectRoot?: string, sessionId?: string | null): Record<string, unknown> | null;