0xray 3.5.0 → 3.5.2

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

@@ -0,0 +1,88 @@
+/**
+ * Multi-host delegation gate SSOT — pending-delegations + spawn todo enforcement.
+ * Grok / Hermes / OpenCode adapters call evaluatePreToolGate via delegation-gate-runtime.
+ * Grok-only codex/surface checks remain in pre-tool-use.js after the SSOT gate.
+ */
+import { type PendingDelegation } from './pending-delegations.js';
+export { getActivePendingDelegations } from './pending-delegations.js';
+import { updatePlanTodoStatus, type SpawnToolInput } from './lead-dev-plan-persistence.js';
+export { validateSpawnMatchesTodo, updatePlanTodoStatus, savePersistedLeadDevPlan, } from './lead-dev-plan-persistence.js';
+export declare const updatePlanTodoStatusInPlace: typeof updatePlanTodoStatus;
+export type DelegationGateHost = 'grok' | 'hermes' | 'opencode' | 'openclaw' | 'generic';
+export interface DelegationGateFeatures {
+    lead_dev_mode: boolean;
+    auto_chain_delegations: boolean;
+}
+export interface ToolGateInput {
+    prompt?: string;
+    description?: string;
+    task?: string;
+    subagent_type?: string;
+    agent?: string;
+    delegationId?: string;
+    delegation_id?: string;
+    planTodoId?: string;
+    command?: string;
+    path?: string;
+    file_path?: string;
+    filePath?: string;
+    toolName?: string;
+    tool?: string;
+    name?: string;
+    server?: string;
+    mcpServer?: string;
+    arguments?: Record<string, unknown>;
+    args?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface PreToolGateContext {
+    projectRoot: string;
+    sessionId: string | null;
+    features: DelegationGateFeatures;
+    host?: DelegationGateHost;
+}
+export interface PreToolGateDeny {
+    allow: false;
+    reason: string;
+    gate: string;
+    hint?: Record<string, unknown>;
+    pendingCount?: number;
+    delegationId?: string;
+}
+export interface PreToolGateAllow {
+    allow: true;
+}
+export type PreToolGateResult = PreToolGateAllow | PreToolGateDeny;
+export interface PostToolSpawnResult {
+    satisfied: PendingDelegation[];
+    clearedAll: boolean;
+    expectedTodoId?: string | null;
+}
+export declare function loadDelegationGateFeatures(projectRoot?: string): DelegationGateFeatures;
+export declare function normalizeHostToolInput(toolInput: ToolGateInput): SpawnToolInput & {
+    command?: string;
+};
+export declare function isSubagentTool(toolName: string): boolean;
+export declare function isShellTool(toolName: string): boolean;
+export declare function isWriteTool(toolName: string, host?: DelegationGateHost): boolean;
+export declare function isReadOnlyTool(toolName: string): boolean;
+/** Spawn plan missing — applies before auto_chain opt-out for subagent tools. */
+export declare function evaluateSpawnPlanGate(toolName: string, toolInput: ToolGateInput, ctx: PreToolGateContext): PreToolGateResult;
+/** Block writes / spawns / shell while synthesis checkpoint is due. */
+export declare function evaluateSynthesisGate(toolName: string, toolInput: ToolGateInput, ctx: PreToolGateContext): PreToolGateResult;
+/** Block writes / unrelated work while pending delegations exist. */
+export declare function evaluatePendingDelegationGate(toolName: string, toolInput: ToolGateInput, ctx: PreToolGateContext): PreToolGateResult;
+/**
+ * Full pre-tool evaluation — synthesis gate first, slice recording, then
+ * pending gate, then spawn todo gate for subagent tools.
+ */
+export declare function evaluatePreToolGate(toolName: string, toolInput: ToolGateInput, ctx: PreToolGateContext): PreToolGateResult;
+export declare function evaluatePostToolSpawn(toolName: string, toolInput: ToolGateInput, projectRoot: string): PostToolSpawnResult;
+export declare function isOrchestrateToolEvent(toolName: string, toolInput?: ToolGateInput): boolean;
+/** Back-compat shims for Grok hook-utils and tests. */
+export declare function checkPendingDelegationGate(toolName: string, toolInput: ToolGateInput, features: DelegationGateFeatures, projectRoot: string, sessionId: string | null): PreToolGateDeny | null;
+export declare function checkSubagentGate(toolName: string, features: DelegationGateFeatures, projectRoot: string, sessionId: string | null, toolInput?: ToolGateInput): PreToolGateDeny | null;
+export declare function satisfyDelegationsFromToolInput(toolInput: ToolGateInput, projectRoot: string): {
+    satisfied: PendingDelegation[];
+    clearedAll: boolean;
+};

package/dist/nucleus/delegation-gate.js

@@ -0,0 +1,347 @@
+/**
+ * Multi-host delegation gate SSOT — pending-delegations + spawn todo enforcement.
+ * Grok / Hermes / OpenCode adapters call evaluatePreToolGate via delegation-gate-runtime.
+ * Grok-only codex/surface checks remain in pre-tool-use.js after the SSOT gate.
+ */
+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, hasValidLeadDevPlanForSpawn, isSynthesisRealignmentPlan, loadPersistedLeadDevPlan, getNextRequiredTodo, validateSpawnMatchesTodo, updatePlanTodoStatus, } from './lead-dev-plan-persistence.js';
+import { getSynthesisDueReason, isSynthesisCheckpointDue, recordExecutionSlice, } from './synthesis.js';
+export { validateSpawnMatchesTodo, updatePlanTodoStatus, savePersistedLeadDevPlan, } from './lead-dev-plan-persistence.js';
+export const updatePlanTodoStatusInPlace = updatePlanTodoStatus;
+const READ_TOOLS = new Set([
+    'read_file',
+    'Read',
+    'read',
+    'grep',
+    'Grep',
+    'glob',
+    'Glob',
+    'list_dir',
+    'ListDir',
+    'web_search',
+    'WebSearch',
+    'codebase_search',
+    'SemanticSearch',
+    'search_files',
+]);
+const SUBAGENT_TOOLS = new Set(['spawn_subagent', 'task', 'Task', 'delegate_task']);
+const ORCHESTRATOR_CONSULT_TOOLS = new Set([
+    'analyze-complexity',
+    'analyze_complexity',
+    'govern-and-apply',
+    'govern_and_apply',
+    'get-orchestration-status',
+    'get_orchestration_status',
+    'orchestrate-task',
+    'orchestrate_task',
+]);
+/** Allowed orchestrator MCP tools while synthesis checkpoint is due (govern-and-apply excluded). */
+const SYNTHESIS_ALLOWED_CONSULT_TOOLS = new Set([
+    'analyze-complexity',
+    'analyze_complexity',
+    'get-orchestration-status',
+    'get_orchestration_status',
+]);
+const HERMES_WRITE_TOOLS = new Set(['write_file', 'patch', 'write', 'edit']);
+const OPENCODE_WRITE_TOOLS = new Set(['write', 'edit', 'multiedit']);
+export function loadDelegationGateFeatures(projectRoot = process.cwd()) {
+    const featuresPath = path.join(projectRoot, '.xray', 'features.json');
+    if (!fs.existsSync(featuresPath)) {
+        return { lead_dev_mode: true, auto_chain_delegations: true };
+    }
+    try {
+        const data = JSON.parse(fs.readFileSync(featuresPath, 'utf8'));
+        const orch = data.multi_agent_orchestration ?? {};
+        return {
+            lead_dev_mode: orch.enabled !== false && orch.lead_dev_mode !== false,
+            auto_chain_delegations: orch.auto_chain_delegations !== false,
+        };
+    }
+    catch {
+        return { lead_dev_mode: true, auto_chain_delegations: true };
+    }
+}
+export function normalizeHostToolInput(toolInput) {
+    const normalized = {
+        prompt: String(toolInput.prompt ?? toolInput.description ?? toolInput.task ?? ''),
+        subagent_type: String(toolInput.subagent_type ?? toolInput.agent ?? ''),
+    };
+    if (toolInput.description != null)
+        normalized.description = String(toolInput.description);
+    if (toolInput.task != null)
+        normalized.task = String(toolInput.task);
+    if (toolInput.agent != null)
+        normalized.agent = String(toolInput.agent);
+    const delegationId = toolInput.delegationId ?? toolInput.delegation_id;
+    if (delegationId != null)
+        normalized.delegationId = String(delegationId);
+    if (toolInput.planTodoId != null)
+        normalized.planTodoId = String(toolInput.planTodoId);
+    if (toolInput.command != null)
+        normalized.command = String(toolInput.command);
+    return normalized;
+}
+export function isSubagentTool(toolName) {
+    return SUBAGENT_TOOLS.has(toolName) || /^task$/i.test(toolName) || toolName === 'spawn_subagent';
+}
+export function isShellTool(toolName) {
+    return /terminal|bash|shell|run_terminal/i.test(toolName);
+}
+export function isWriteTool(toolName, host = 'generic') {
+    if (host === 'hermes' && HERMES_WRITE_TOOLS.has(toolName))
+        return true;
+    if (host === 'opencode' && OPENCODE_WRITE_TOOLS.has(toolName))
+        return true;
+    return (/write|edit|replace|patch|notebook/i.test(toolName) &&
+        !isReadOnlyTool(toolName));
+}
+export function isReadOnlyTool(toolName) {
+    return READ_TOOLS.has(toolName) || /^(read|grep|glob|list|search_files)/i.test(toolName);
+}
+function extractMcpToolName(toolInput) {
+    const candidates = [
+        toolInput.toolName,
+        toolInput.tool,
+        toolInput.name,
+        toolInput.mcpToolName,
+    ];
+    for (const c of candidates) {
+        if (c)
+            return String(c);
+    }
+    const server = String(toolInput.server ?? toolInput.mcpServer ?? '');
+    const args = (toolInput.arguments ?? toolInput.args ?? {});
+    if (args.toolName)
+        return String(args.toolName);
+    if (server.includes('orchestrator') && args.name)
+        return String(args.name);
+    return '';
+}
+function isOrchestratorConsultMcp(toolName, toolInput) {
+    if (!/mcp|CallMcpTool/i.test(toolName))
+        return false;
+    const inner = extractMcpToolName(toolInput).toLowerCase();
+    if (!inner)
+        return false;
+    for (const t of ORCHESTRATOR_CONSULT_TOOLS) {
+        if (inner.includes(t) || inner.includes(t.replace(/-/g, '_')))
+            return true;
+    }
+    return false;
+}
+function isSynthesisAllowedOrchestratorConsult(toolName, toolInput) {
+    if (!/mcp|CallMcpTool/i.test(toolName))
+        return false;
+    const inner = extractMcpToolName(toolInput).toLowerCase();
+    if (!inner)
+        return false;
+    for (const t of SYNTHESIS_ALLOWED_CONSULT_TOOLS) {
+        if (inner.includes(t) || inner.includes(t.replace(/-/g, '_')))
+            return true;
+    }
+    return false;
+}
+function isFocusedTestCommand(cmd) {
+    const cmdText = (cmd || '').toLowerCase();
+    return (/\b(npm\s+(run\s+)?test|vitest\s+run|pnpm\s+test|yarn\s+test)\b/.test(cmdText) &&
+        (/--\s+\S+\.test/.test(cmdText) || /vitest\s+run\s+\S+\.test/.test(cmdText)));
+}
+function denyFromSpawnValidation(validation) {
+    const deny = {
+        allow: false,
+        reason: validation.reason ?? 'Spawn blocked by lead-dev plan',
+        gate: validation.gate ?? 'spawn-todo-persistence',
+    };
+    if (validation.hint)
+        deny.hint = validation.hint;
+    return deny;
+}
+function denyFromPending(primary, pendingCount) {
+    return {
+        allow: false,
+        reason: 'Pending implementation delegation — spawn host Task before other work',
+        gate: 'auto-chain-pending',
+        hint: { ...(primary.spawnHint ?? {
+                tool: 'Task',
+                subagent_type: primary.agent,
+                description: primary.taskDescription,
+                planTodoId: primary.planTodoId,
+                delegationId: primary.id,
+            }) },
+        pendingCount,
+        delegationId: primary.id,
+    };
+}
+/** Spawn plan missing — applies before auto_chain opt-out for subagent tools. */
+export function evaluateSpawnPlanGate(toolName, toolInput, ctx) {
+    if (!ctx.features.lead_dev_mode || !isSubagentTool(toolName)) {
+        return { allow: true };
+    }
+    if (!hasValidLeadDevPlanForSpawn(ctx.projectRoot, ctx.sessionId)) {
+        return {
+            allow: false,
+            reason: 'Codex 59/67: call xray-orchestrator analyze-complexity first — ' +
+                'writes .xray/state/lead-dev-plan.json required before spawn_subagent',
+            gate: 'spawn-plan-missing',
+        };
+    }
+    if (ctx.features.auto_chain_delegations === false) {
+        return { allow: true };
+    }
+    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
+        : null;
+    const validation = validateSpawnMatchesTodo(normalizeHostToolInput(toolInput), ctx.projectRoot, expectedTodo);
+    if (!validation.valid) {
+        return denyFromSpawnValidation(validation);
+    }
+    return { allow: true };
+}
+/** Block writes / spawns / shell while synthesis checkpoint is due. */
+export function evaluateSynthesisGate(toolName, toolInput, ctx) {
+    if (!ctx.sessionId || !isSynthesisCheckpointDue(ctx.projectRoot, ctx.sessionId)) {
+        return { allow: true };
+    }
+    if (isReadOnlyTool(toolName))
+        return { allow: true };
+    if (isSynthesisAllowedOrchestratorConsult(toolName, toolInput))
+        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);
+        if (validation.valid)
+            return { allow: true };
+    }
+    const dueReason = getSynthesisDueReason(ctx.projectRoot, ctx.sessionId);
+    const realignmentPending = plan && isSynthesisRealignmentPlan(plan) && !areSynthesisConsultTodosComplete(plan);
+    return {
+        allow: false,
+        reason: realignmentPending
+            ? 'Synthesis realignment in progress — complete mandatory consult todos (s.1–s.3) before other work'
+            : 'Synthesis checkpoint due — call xray-orchestrator analyze-complexity to reflect and realign before continuing',
+        gate: 'synthesis-checkpoint',
+        hint: {
+            tool: realignmentPending ? 'Task' : 'analyze-complexity',
+            dueReason,
+            primitive: 'synthesis',
+            sessionId: ctx.sessionId,
+            ...(realignmentPending && plan
+                ? { nextTodoId: getNextRequiredTodo(plan)?.id }
+                : {}),
+        },
+    };
+}
+/** Block writes / unrelated work while pending delegations exist. */
+export function evaluatePendingDelegationGate(toolName, toolInput, ctx) {
+    if (!ctx.features.lead_dev_mode || ctx.features.auto_chain_delegations === false) {
+        return { allow: true };
+    }
+    if (!ctx.sessionId)
+        return { allow: true };
+    const pending = getActivePendingDelegations(ctx.sessionId, ctx.projectRoot);
+    if (pending.length === 0)
+        return { allow: true };
+    if (isSubagentTool(toolName))
+        return { allow: true };
+    if (isReadOnlyTool(toolName))
+        return { allow: true };
+    if (isOrchestratorConsultMcp(toolName, toolInput))
+        return { allow: true };
+    if (isShellTool(toolName)) {
+        const cmd = String(toolInput.command ?? '');
+        if (isFocusedTestCommand(cmd))
+            return { allow: true };
+    }
+    return denyFromPending(pending[0], pending.length);
+}
+/**
+ * Full pre-tool evaluation — synthesis gate first, slice recording, then
+ * pending gate, then spawn todo gate for subagent tools.
+ */
+export function evaluatePreToolGate(toolName, toolInput, ctx) {
+    const synthesisBlock = evaluateSynthesisGate(toolName, toolInput, ctx);
+    if (!synthesisBlock.allow)
+        return synthesisBlock;
+    if (!isSynthesisCheckpointDue(ctx.projectRoot, ctx.sessionId)) {
+        recordExecutionSlice('gate', {
+            projectRoot: ctx.projectRoot,
+            sessionId: ctx.sessionId,
+        });
+    }
+    const pendingBlock = evaluatePendingDelegationGate(toolName, toolInput, ctx);
+    if (!pendingBlock.allow)
+        return pendingBlock;
+    const spawnBlock = evaluateSpawnPlanGate(toolName, toolInput, ctx);
+    if (!spawnBlock.allow)
+        return spawnBlock;
+    return { allow: true };
+}
+export function evaluatePostToolSpawn(toolName, toolInput, projectRoot) {
+    const normalized = normalizeHostToolInput(toolInput);
+    const spawnCheck = validateSpawnMatchesTodo(normalized, projectRoot);
+    const satisfyInput = {
+        toolPrompt: normalized.prompt ?? '',
+    };
+    if (normalized.delegationId)
+        satisfyInput.delegationId = normalized.delegationId;
+    const agent = normalized.subagent_type || normalized.agent;
+    if (agent)
+        satisfyInput.agent = agent;
+    if (normalized.planTodoId)
+        satisfyInput.planTodoId = normalized.planTodoId;
+    const result = satisfyDelegation(satisfyInput, projectRoot);
+    if (spawnCheck.valid && spawnCheck.expectedTodoId) {
+        updatePlanTodoStatus(spawnCheck.expectedTodoId, 'completed', projectRoot);
+    }
+    return {
+        ...result,
+        expectedTodoId: spawnCheck.expectedTodoId ?? null,
+    };
+}
+export function isOrchestrateToolEvent(toolName, toolInput = {}) {
+    const inner = extractMcpToolName(toolInput).toLowerCase();
+    if (/orchestrate[-_]?task/.test(inner))
+        return true;
+    const blob = JSON.stringify(toolInput).toLowerCase();
+    return /orchestrate[-_]?task/.test(blob);
+}
+/** Back-compat shims for Grok hook-utils and tests. */
+export function checkPendingDelegationGate(toolName, toolInput, features, projectRoot, sessionId) {
+    const result = evaluatePendingDelegationGate(toolName, toolInput, {
+        projectRoot,
+        sessionId,
+        features,
+    });
+    return result.allow ? null : result;
+}
+export function checkSubagentGate(toolName, features, projectRoot, sessionId, toolInput = {}) {
+    const result = evaluateSpawnPlanGate(toolName, toolInput, {
+        projectRoot,
+        sessionId,
+        features,
+    });
+    return result.allow ? null : result;
+}
+export function satisfyDelegationsFromToolInput(toolInput, projectRoot) {
+    const normalized = normalizeHostToolInput(toolInput);
+    const satisfyInput = {
+        toolPrompt: normalized.prompt ?? '',
+    };
+    if (normalized.delegationId)
+        satisfyInput.delegationId = normalized.delegationId;
+    const agent = normalized.subagent_type || normalized.agent;
+    if (agent)
+        satisfyInput.agent = agent;
+    if (normalized.planTodoId)
+        satisfyInput.planTodoId = normalized.planTodoId;
+    return satisfyDelegation(satisfyInput, projectRoot);
+}

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

@@ -28,6 +28,9 @@ export declare function getNextRequiredTodo(plan: PersistedLeadDevPlan): LeadDev
  * - all todos complete and persistedAt within TTL
  */
 export declare function hasValidLeadDevPlanForSpawn(projectRoot?: string, _sessionId?: string | null): boolean;
+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 bindPlanToSession(sessionId: string, projectRoot?: string): PersistedLeadDevPlan | null;
 export interface SpawnToolInput {

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

@@ -4,7 +4,9 @@
  */
 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';
 export function leadDevPlanStatePath(projectRoot = process.cwd()) {
     return path.join(projectRoot, '.xray', 'state', 'lead-dev-plan.json');
 }
@@ -26,15 +28,15 @@ export function savePersistedLeadDevPlan(plan, projectRoot = process.cwd()) {
     return planPath;
 }
 export function allPlanTodos(plan) {
-    return plan.phases.flatMap((p) => p.todos);
+    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');
+    for (const phase of plan.phases ?? []) {
+        const next = (phase.todos ?? []).find((t) => t.status === 'pending' || t.status === 'in_progress');
         if (next)
             return next;
     }
@@ -64,6 +66,37 @@ export function hasValidLeadDevPlanForSpawn(projectRoot = process.cwd(), _sessio
     }
     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()) {
     const plan = loadPersistedLeadDevPlan(projectRoot);
     if (!plan)
@@ -77,8 +110,18 @@ export function updatePlanTodoStatus(todoId, status, projectRoot = process.cwd()
             }
         }
     }
-    if (updated)
+    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()) {

package/dist/nucleus/synthesis-completion.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Post-checkpoint side effects — meta-inference refresh + repertoire feedback.
+ */
+import type { PersistedLeadDevPlan } from './lead-dev-plan-persistence.js';
+import type { SynthesisCheckpointState } from './synthesis.js';
+export declare function runSynthesisCheckpointSideEffects(projectRoot: string, sessionId: string, plan: PersistedLeadDevPlan | null, completedState: SynthesisCheckpointState): Promise<void>;

package/dist/nucleus/synthesis-completion.js

@@ -0,0 +1,29 @@
+/**
+ * Post-checkpoint side effects — meta-inference refresh + repertoire feedback.
+ */
+import { getMemoryRoutingProvider } from '../memory-routing/index.js';
+import { getSynthesisConsultTodos, isSynthesisRealignmentPlan } from './lead-dev-plan-persistence.js';
+export async function runSynthesisCheckpointSideEffects(projectRoot, sessionId, plan, completedState) {
+    try {
+        const provider = await getMemoryRoutingProvider();
+        if (provider.refreshMetaInference) {
+            await provider.refreshMetaInference().catch(() => undefined);
+        }
+        if (provider.ingestFeedback && plan && isSynthesisRealignmentPlan(plan)) {
+            const consultTodos = getSynthesisConsultTodos(plan);
+            provider.ingestFeedback({
+                timestamp: new Date().toISOString(),
+                sessionId,
+                taskId: `synthesis-checkpoint-${completedState.synthesisCount}`,
+                assignedAgent: 'orchestrator',
+                memorySignals: ['synthesis', ...consultTodos.map((t) => t.subagent)],
+                complexity: 30,
+                success: true,
+                durationMs: 0,
+            });
+        }
+    }
+    catch {
+        // non-blocking — checkpoint already cleared
+    }
+}

package/dist/nucleus/synthesis-context.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Collocated context for synthesis Aside — delegates to memory routing provider SSOT.
+ */
+export interface SynthesisCollocatedContext {
+    primitive: 'synthesis';
+    dueReason: string | null;
+    collatedText: string;
+    matchedSignals?: Array<{
+        name: string;
+        definition: string;
+        priority: string;
+    }>;
+    codexTermCount?: number;
+    codexExcerpt?: string;
+    planExcerpt?: string;
+    synthesisExcerpt?: string;
+}
+export declare function buildSynthesisCollocatedContext(projectRoot?: string, dueReason?: string | null): Promise<SynthesisCollocatedContext>;
+/** Refresh meta-inference before collation so synthesis.md is current for reflect. */
+export declare function prepareSynthesisCollocatedContext(projectRoot?: string, dueReason?: string | null): Promise<SynthesisCollocatedContext>;
+export declare function isAnalyzeComplexitySuccess(content: Array<{
+    type: string;
+    text: string;
+}>): boolean;
+export declare function appendSynthesisContextToResponse(content: Array<{
+    type: string;
+    text: string;
+}>, collatedText: string): Array<{
+    type: string;
+    text: string;
+}>;