0xray 3.5.1 → 3.5.3

package/scripts/node/postinstall.cjs

@@ -7,6 +7,7 @@ const {
   resolveConsumerTargetDir,
   isConsumerInstall,
 } = require("./install-bridges.cjs");
+const { applyConsumerGitignore } = require("./consumer-gitignore.cjs");
 
 function structuredLog(component, action, status, details) {
   const ts = new Date().toISOString();
@@ -39,12 +40,14 @@ if (fs.existsSync(agentsConsumer) && isConsumerInstall(resolvedPackage, resolved
   }
 }
 
-// Copy .gitignore.default → .gitignore (never overwrite existing)
-const gitignoreSource = path.join(packageRoot, ".gitignore.default");
-const gitignoreDest = path.join(targetDir, ".gitignore");
-if (!fs.existsSync(gitignoreDest) && isConsumerInstall(resolvedPackage, resolvedTarget)) {
-  fs.copyFileSync(gitignoreSource, gitignoreDest);
-  structuredLog("postinstall", "Created .gitignore from template", "info");
+// .gitignore: full template when absent; merge suit block when existing
+if (isConsumerInstall(resolvedPackage, resolvedTarget)) {
+  const gitignoreResult = applyConsumerGitignore(targetDir, packageRoot);
+  if (gitignoreResult === "created") {
+    structuredLog("postinstall", "Created .gitignore from template", "info");
+  } else if (gitignoreResult === "merged") {
+    structuredLog("postinstall", "Merged 0xray suit entries into .gitignore", "info");
+  }
 }
 
 // Unified 4-platform bridge install (OpenCode, Grok, Hermes, OpenClaw)

package/src/integrations/grok/plugin/0xray/hooks/hooks.json

@@ -36,7 +36,8 @@
             "type": "command",
             "command": "node",
             "args": [
-              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js"
+              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js",
+              "--hook-event=user_prompt_submit"
             ],
             "timeout": 15000
           }

package/src/mcps/orchestrator/handlers/complexity-handler.ts

@@ -7,6 +7,7 @@
 import { frameworkLogger } from '../../../core/framework-logger.js';
 import {
   buildLeadDevPlan,
+  buildSynthesisCheckpointPlan,
   isLeadDevModeActive,
   persistLeadDevPlan,
 } from '../../../nucleus/autonomy-kernel.js';
@@ -67,9 +68,14 @@ export class ComplexityHandler {
    * Handle analyze-complexity request
    */
   async handleAnalyzeComplexity(
-    args: { tasks: AnalyzeComplexityInput[]; sessionId?: string },
+    args: {
+      tasks: AnalyzeComplexityInput[];
+      sessionId?: string;
+      synthesisCheckpoint?: boolean;
+      synthesisDueReason?: string | null;
+    },
     asideId?: string,
-  ): Promise<{ content: Array<{ type: string; text: string }> }> {
+  ): Promise<{ content: Array<{ type: string; text: string }>; ok: boolean }> {
     const tasks = normalizeAnalyzeTasks(args.tasks ?? []);
 
     await frameworkLogger.log(
@@ -92,8 +98,10 @@ export class ComplexityHandler {
       const planTaskInputs = tasks
         .filter((t) => t.description?.trim())
         .map((t) => ({ description: t.description, type: t.type }));
-      const leadDevPlan =
-        isLeadDevModeActive() && (primaryDescription || planTaskInputs.length > 0)
+      const synthesisCheckpoint = args.synthesisCheckpoint === true;
+      const leadDevPlan = synthesisCheckpoint
+        ? buildSynthesisCheckpointPlan(args.synthesisDueReason ?? null)
+        : isLeadDevModeActive() && (primaryDescription || planTaskInputs.length > 0)
           ? buildLeadDevPlan(
               primaryDescription,
               taskTypes.length ? taskTypes : ['implement'],
@@ -102,15 +110,20 @@ export class ComplexityHandler {
             )
           : null;
 
+      let planPersisted = synthesisCheckpoint ? leadDevPlan !== null : !leadDevPlan;
+
       if (leadDevPlan) {
         try {
           const sessionId = args.sessionId ?? `analyze-${Date.now()}`;
-          clearPendingDelegations();
+          if (!synthesisCheckpoint) {
+            clearPendingDelegations();
+          }
           const planPath = persistLeadDevPlan(leadDevPlan);
           const bound = bindPlanToSession(sessionId);
+          planPersisted = true;
           await frameworkLogger.log(
             'orchestrator.server',
-            'lead-dev-plan-persisted',
+            synthesisCheckpoint ? 'synthesis-plan-persisted' : 'lead-dev-plan-persisted',
             'info',
             {
               planPath,
@@ -118,19 +131,24 @@ export class ComplexityHandler {
               planGeneration: bound?.planGeneration,
               phaseCount: leadDevPlan.phases.length,
               todoCount: leadDevPlan.phases.reduce((n, p) => n + p.todos.length, 0),
+              synthesisCheckpoint,
             },
           );
         } catch (err) {
+          planPersisted = false;
           await frameworkLogger.log(
             'orchestrator.server',
-            'lead-dev-plan-persist-failed',
+            synthesisCheckpoint ? 'synthesis-plan-persist-failed' : 'lead-dev-plan-persist-failed',
             'warning',
             { error: err instanceof Error ? err.message : String(err) },
           );
         }
       }
 
+      const ok = planPersisted;
+
       return {
+        ok,
         content: [
           {
             type: 'text',
@@ -139,12 +157,14 @@ export class ComplexityHandler {
               recommendations,
               tasks.length,
               leadDevPlan,
+              synthesisCheckpoint,
             ),
           },
         ],
       };
     } catch (error) {
       return {
+        ok: false,
         content: [
           {
             type: 'text',
@@ -195,6 +215,7 @@ export class ComplexityHandler {
     recommendations: string[],
     taskCount: number,
     leadDevPlan: ReturnType<typeof buildLeadDevPlan> = null,
+    synthesisCheckpoint = false,
   ): string {
     const leadDevSection = leadDevPlan
       ? `
@@ -216,7 +237,11 @@ ${JSON.stringify(leadDevPlan, null, 2)}
 \`\`\``
       : '';
 
-    return `🔍 Complexity Analysis Results
+    const header = synthesisCheckpoint
+      ? '🔄 Synthesis Checkpoint — Reflect & Realign'
+      : '🔍 Complexity Analysis Results';
+
+    return `${header}
 
 **Tasks Analyzed:** ${taskCount}
 **Overall Complexity:** ${analysis.overallComplexity}/100

package/src/mcps/orchestrator/server.ts

@@ -140,10 +140,15 @@ export class OrchestratorServer {
           {
             name: 'analyze-complexity',
             description:
-              'Analyze task complexity and recommend orchestration strategy. When lead_dev_mode is on (features.json), includes phased plan + todos + subagent routes.',
+              'Analyze task complexity and recommend orchestration strategy. When lead_dev_mode is on (features.json), includes phased plan + todos + subagent routes. During synthesis checkpoint, returns collocated context and mandatory-consult realignment plan — pass sessionId from the active session.',
             inputSchema: {
               type: 'object',
               properties: {
+                sessionId: {
+                  type: 'string',
+                  description:
+                    'Active session id (required to clear synthesis checkpoint; inferred from checkpoint state when omitted)',
+                },
                 tasks: {
                   type: 'array',
                   items: {
@@ -276,12 +281,140 @@ export class OrchestratorServer {
             }
           }
           case 'analyze-complexity': {
-            const complexityArgs = args as { tasks: OrchestrationTask[] };
+            const complexityArgs = args as {
+              tasks: OrchestrationTask[];
+              sessionId?: string;
+            };
+            const projectRoot = process.cwd();
+            const {
+              isSynthesisCheckpointDue,
+              getSynthesisDueReason,
+              getSynthesisCheckpointSessionId,
+            } = await import('../../nucleus/synthesis.js');
+            const { appendSynthesisContextToResponse, prepareSynthesisCollocatedContext } =
+              await import('../../nucleus/synthesis-context.js');
+            const {
+              loadPersistedLeadDevPlan,
+              isSynthesisRealignmentPlan,
+              areSynthesisConsultTodosComplete,
+              getSynthesisConsultTodos,
+              getNextRequiredTodo,
+            } = await import('../../nucleus/lead-dev-plan-persistence.js');
+
+            const checkpointSession = getSynthesisCheckpointSessionId(projectRoot);
+            if (
+              checkpointSession &&
+              complexityArgs.sessionId &&
+              complexityArgs.sessionId !== checkpointSession
+            ) {
+              return {
+                content: [
+                  {
+                    type: 'text' as const,
+                    text:
+                      `❌ Synthesis sessionId mismatch — expected \`${checkpointSession}\` ` +
+                      `(from synthesis-checkpoint.json), got \`${complexityArgs.sessionId}\`.`,
+                  },
+                ],
+              };
+            }
+
+            const sessionId = checkpointSession ?? complexityArgs.sessionId ?? null;
+            const synthesisDue = checkpointSession
+              ? isSynthesisCheckpointDue(projectRoot, checkpointSession)
+              : false;
+            const dueReason = synthesisDue
+              ? getSynthesisDueReason(projectRoot, sessionId)
+              : null;
+
+            if (synthesisDue && !sessionId) {
+              return {
+                content: [
+                  {
+                    type: 'text' as const,
+                    text:
+                      '❌ Synthesis checkpoint due but sessionId could not be resolved. ' +
+                      'Pass sessionId matching .xray/state/synthesis-checkpoint.json.',
+                  },
+                ],
+              };
+            }
+
+            const existingPlan = loadPersistedLeadDevPlan(projectRoot);
+            const realignmentInProgress =
+              synthesisDue &&
+              existingPlan &&
+              isSynthesisRealignmentPlan(existingPlan) &&
+              !areSynthesisConsultTodosComplete(existingPlan);
+
+            if (realignmentInProgress) {
+              const collocated = await prepareSynthesisCollocatedContext(projectRoot, dueReason);
+              const nextTodo = getNextRequiredTodo(existingPlan);
+              const consultTodos = getSynthesisConsultTodos(existingPlan);
+              const todoList = consultTodos
+                .map(
+                  (t) =>
+                    `- [${t.status === 'completed' ? 'x' : ' '}] ${t.id} (${t.subagent}): ${t.task}`,
+                )
+                .join('\n');
+              let text =
+                '🔄 Synthesis realignment in progress — consult todos preserved (analyze-complexity no-op).\n\n' +
+                `**Next required todo:** ${nextTodo?.id ?? 'none'} (${nextTodo?.subagent ?? ''})\n\n` +
+                `${todoList}\n\n` +
+                'Complete mandatory consult todos via Task spawns before other gated work.';
+              if (collocated.collatedText) {
+                text = appendSynthesisContextToResponse(
+                  [{ type: 'text', text }],
+                  collocated.collatedText,
+                )[0]!.text;
+              }
+              return { content: [{ type: 'text' as const, text }] };
+            }
+
+            const collocated = synthesisDue
+              ? await prepareSynthesisCollocatedContext(projectRoot, dueReason)
+              : null;
+            const inheritedContext = synthesisDue && collocated
+              ? { synthesis: true, ...collocated }
+              : { taskCount: complexityArgs.tasks.length };
+
             const aside = await spawnAside({
-              description: `Complexity analysis: ${complexityArgs.tasks.length} tasks`,
+              description: synthesisDue
+                ? 'Synthesis checkpoint: reflect & realign'
+                : `Complexity analysis: ${complexityArgs.tasks.length} tasks`,
+              ...(sessionId ? { sessionId } : {}),
+              inheritedContext,
             });
             try {
-              return await this.complexityHandler.handleAnalyzeComplexity(complexityArgs, aside.asideId);
+              const result = await this.complexityHandler.handleAnalyzeComplexity(
+                {
+                  ...complexityArgs,
+                  ...(sessionId ? { sessionId } : {}),
+                  ...(synthesisDue
+                    ? { synthesisCheckpoint: true, synthesisDueReason: dueReason }
+                    : {}),
+                },
+                aside.asideId,
+              );
+
+              let content = result.content;
+              if (synthesisDue && collocated?.collatedText) {
+                content = appendSynthesisContextToResponse(content, collocated.collatedText);
+              }
+
+              if (synthesisDue && result.ok) {
+                content = content.map((block, index) =>
+                  index === 0
+                    ? {
+                        ...block,
+                        text:
+                          `${block.text}\n\n**Synthesis checkpoint remains active** until mandatory consult todos (s.1–s.3) are completed via Task spawns.`,
+                      }
+                    : block,
+                );
+              }
+
+              return { content };
             } finally {
               closeAside(aside.asideId);
             }
@@ -356,13 +489,51 @@ export class OrchestratorServer {
     skipApply?: boolean;
   }): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
     try {
+      const projectRoot = process.cwd();
+      const {
+        isSynthesisCheckpointDue,
+        getSynthesisDueReason,
+        getSynthesisCheckpointSessionId,
+        recordExecutionSlice,
+      } = await import('../../nucleus/synthesis.js');
+      const {
+        loadPersistedLeadDevPlan,
+        isSynthesisRealignmentPlan,
+        areSynthesisConsultTodosComplete,
+      } = await import('../../nucleus/lead-dev-plan-persistence.js');
+
+      const checkpointSession = getSynthesisCheckpointSessionId(projectRoot);
+      const sessionId = checkpointSession ?? null;
+      if (sessionId && isSynthesisCheckpointDue(projectRoot, sessionId)) {
+        const dueReason = getSynthesisDueReason(projectRoot, sessionId);
+        const plan = loadPersistedLeadDevPlan(projectRoot);
+        const realignmentPending =
+          plan && isSynthesisRealignmentPlan(plan) && !areSynthesisConsultTodosComplete(plan);
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              blocked: true,
+              gate: 'synthesis-checkpoint',
+              dueReason,
+              primitive: 'synthesis',
+              realignmentPending,
+              hint: realignmentPending
+                ? 'Complete mandatory consult todos (s.1–s.3) before govern-and-apply'
+                : 'Run analyze-complexity to reflect and realign before govern-and-apply',
+            }, null, 2),
+          }],
+        };
+      }
+
       const { InferenceCycle } = await import('../../inference/inference-cycle.js');
-      const cycle = InferenceCycle.getInstance(process.cwd(), {
+      const cycle = InferenceCycle.getInstance(projectRoot, {
         skipApply: args.skipApply ?? false,
       });
 
       const aside = await spawnAside({
         description: `Governance cycle: ${args.proposals.length} proposals`,
+        ...(sessionId ? { sessionId } : {}),
         priorVerdictContext: { proposalCount: args.proposals.length },
       });
 
@@ -377,12 +548,17 @@ export class OrchestratorServer {
       const approved = result!.votes.filter((v) => v.decision === 'approve').length;
       const rejected = result!.votes.length - approved;
 
+      if (sessionId) {
+        recordExecutionSlice('gate', { projectRoot, sessionId });
+      }
+
       return {
         content: [{
           type: 'text' as const,
           text: JSON.stringify({
             cycleId: result!.cycleId,
             asideId: aside.asideId,
+            synthesisBridged: Boolean(sessionId),
             approved,
             rejected,
             votes: result!.votes,

package/xray/features.json

@@ -141,6 +141,12 @@
     "module_path": "",
     "config": {}
   },
+  "synthesis": {
+    "enabled": false,
+    "every_n_gates": 12,
+    "every_n_turns": 0,
+    "every_n_todos_completed": 0
+  },
   "inference_governance": {
     "enabled": false,
     "request_timeout_ms": 10000,

package/xray/features.schema.json

@@ -27,6 +27,23 @@
       "then": {
         "required": ["module_path"]
       }
+    },
+    "synthesis": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "every_n_gates": { "type": "integer", "minimum": 0 },
+        "every_n_turns": { "type": "integer", "minimum": 0 },
+        "every_n_todos_completed": { "type": "integer", "minimum": 0 },
+        "reflection": {
+          "type": "object",
+          "properties": {
+            "mode": { "type": "string", "enum": ["full", "minimal", "off"] },
+            "triggers": { "type": "object" },
+            "thresholds": { "type": "object" }
+          }
+        }
+      }
     }
   },
   "additionalProperties": true