0xray 3.5.3 → 3.5.5

package/dist/mcps/orchestrator/handlers/complexity-handler.d.ts

@@ -29,6 +29,13 @@ export declare class ComplexityHandler {
         sessionId?: string;
         synthesisCheckpoint?: boolean;
         synthesisDueReason?: string | null;
+        collocatedText?: string | null;
+        conferFixture?: boolean;
+        userAsideId?: string;
+        userAsideTitle?: string;
+        worktree?: string;
+        branch?: string;
+        setActiveAside?: boolean;
     }, asideId?: string): Promise<{
         content: Array<{
             type: string;

package/dist/mcps/orchestrator/handlers/complexity-handler.js

@@ -5,8 +5,11 @@
  */
 import { frameworkLogger } from '../../../core/framework-logger.js';
 import { buildLeadDevPlan, buildSynthesisCheckpointPlan, isLeadDevModeActive, persistLeadDevPlan, } from '../../../nucleus/autonomy-kernel.js';
+import { formatConferQuorumReport, isConferEnabled, runConferQuorum, } from '../../../nucleus/confer.js';
 import { bindPlanToSession } from '../../../nucleus/lead-dev-plan-persistence.js';
 import { clearPendingDelegations } from '../../../nucleus/pending-delegations.js';
+import { isAutoProvisionWorktreeEnabled, provisionGitWorktree, } from '../../../nucleus/aside-worktree.js';
+import { buildUserAsidePlan, formatUserAsideSummary, isUserAsidesEnabled, loadUserAside, mergeUserAsideIntake, saveUserAside, setActiveAsideId, UserAsideValidationError, } from '../../../nucleus/user-aside.js';
 import { getExecutionPlanner } from '../execution/execution-planner.js';
 import { addObservations, extractComplexityObservations } from '../aside-context.js';
 function normalizeAnalyzeTasks(raw) {
@@ -61,13 +64,89 @@ export class ComplexityHandler {
                 .filter((t) => t.description?.trim())
                 .map((t) => ({ description: t.description, type: t.type }));
             const synthesisCheckpoint = args.synthesisCheckpoint === true;
-            const leadDevPlan = synthesisCheckpoint
+            const projectRoot = process.cwd();
+            const userAsideIntake = !synthesisCheckpoint &&
+                Boolean(args.userAsideId?.trim()) &&
+                isUserAsidesEnabled(projectRoot);
+            let userAsideReport = '';
+            let leadDevPlan = synthesisCheckpoint
                 ? buildSynthesisCheckpointPlan(args.synthesisDueReason ?? null)
-                : isLeadDevModeActive() && (primaryDescription || planTaskInputs.length > 0)
-                    ? buildLeadDevPlan(primaryDescription, taskTypes.length ? taskTypes : ['implement'], planTaskInputs, analysis.overallComplexity)
-                    : null;
-            let planPersisted = synthesisCheckpoint ? leadDevPlan !== null : !leadDevPlan;
-            if (leadDevPlan) {
+                : userAsideIntake
+                    ? null
+                    : isLeadDevModeActive() && (primaryDescription || planTaskInputs.length > 0)
+                        ? buildLeadDevPlan(primaryDescription, taskTypes.length ? taskTypes : ['implement'], planTaskInputs, analysis.overallComplexity)
+                        : null;
+            let planPersisted = synthesisCheckpoint
+                ? leadDevPlan !== null
+                : userAsideIntake
+                    ? false
+                    : !leadDevPlan;
+            if (userAsideIntake && args.userAsideId) {
+                try {
+                    const asideId = args.userAsideId.trim();
+                    const title = args.userAsideTitle?.trim() || asideId;
+                    const existing = loadUserAside(asideId, projectRoot);
+                    const userAside = existing
+                        ? mergeUserAsideIntake(existing, primaryDescription || existing.description, planTaskInputs, analysis.overallComplexity, projectRoot)
+                        : buildUserAsidePlan(asideId, title, primaryDescription || title, planTaskInputs, analysis.overallComplexity, projectRoot);
+                    if (!userAside) {
+                        planPersisted = false;
+                    }
+                    else {
+                        if (args.worktree)
+                            userAside.worktree = args.worktree;
+                        if (args.branch)
+                            userAside.branch = args.branch;
+                        if (args.sessionId)
+                            userAside.sessionId = args.sessionId;
+                        if (args.userAsideTitle)
+                            userAside.title = title;
+                        let worktreeProvisionNote = '';
+                        if (args.worktree?.trim() &&
+                            args.branch?.trim() &&
+                            isAutoProvisionWorktreeEnabled(projectRoot)) {
+                            const provision = provisionGitWorktree({
+                                projectRoot,
+                                worktree: args.worktree.trim(),
+                                branch: args.branch.trim(),
+                            });
+                            if (!provision.ok) {
+                                throw new UserAsideValidationError(`Worktree auto-provision failed: ${provision.message}`);
+                            }
+                            worktreeProvisionNote = provision.created
+                                ? `\n\n**Worktree provisioned:** \`${provision.path}\` (branch \`${args.branch.trim()}\`)`
+                                : `\n\n**Worktree ready:** \`${provision.path}\``;
+                        }
+                        const asidePath = saveUserAside(userAside, projectRoot);
+                        const activate = args.setActiveAside !== false;
+                        if (activate) {
+                            clearPendingDelegations(projectRoot);
+                            setActiveAsideId(asideId, projectRoot, args.sessionId ?? null);
+                        }
+                        planPersisted = true;
+                        userAsideReport = `\n\n## User aside\n\n${formatUserAsideSummary(userAside)}${worktreeProvisionNote}`;
+                        if (activate) {
+                            userAsideReport += `\n\n**Active aside:** \`${asideId}\` — spawns route to \`${asideId}.a.*\` todos.`;
+                        }
+                        await frameworkLogger.log('orchestrator.server', 'user-aside-persisted', 'info', {
+                            asidePath,
+                            asideId,
+                            todoCount: userAside.plan.phases.reduce((n, p) => n + p.todos.length, 0),
+                            activated: activate,
+                        });
+                    }
+                }
+                catch (err) {
+                    planPersisted = false;
+                    const message = err instanceof Error ? err.message : String(err);
+                    userAsideReport = `\n\n❌ User aside intake failed: ${message}`;
+                    await frameworkLogger.log('orchestrator.server', 'user-aside-persist-failed', 'warning', {
+                        error: message,
+                        validation: err instanceof UserAsideValidationError,
+                    });
+                }
+            }
+            else if (leadDevPlan) {
                 try {
                     const sessionId = args.sessionId ?? `analyze-${Date.now()}`;
                     if (!synthesisCheckpoint) {
@@ -90,13 +169,33 @@ export class ComplexityHandler {
                     await frameworkLogger.log('orchestrator.server', synthesisCheckpoint ? 'synthesis-plan-persist-failed' : 'lead-dev-plan-persist-failed', 'warning', { error: err instanceof Error ? err.message : String(err) });
                 }
             }
+            let conferReport = '';
+            if (synthesisCheckpoint &&
+                leadDevPlan &&
+                planPersisted &&
+                isConferEnabled() &&
+                args.sessionId) {
+                const conferOpts = {
+                    dueReason: args.synthesisDueReason ?? null,
+                    fixture: args.conferFixture === true,
+                };
+                if (args.collocatedText)
+                    conferOpts.collocatedText = args.collocatedText;
+                const conferResult = await runConferQuorum(process.cwd(), args.sessionId, conferOpts);
+                conferReport = `\n\n${formatConferQuorumReport(conferResult)}`;
+                await frameworkLogger.log('orchestrator.server', 'confer-quorum', conferResult.status === 'completed' ? 'info' : 'warning', {
+                    status: conferResult.status,
+                    agentCount: conferResult.agents.length,
+                    sessionId: args.sessionId,
+                });
+            }
             const ok = planPersisted;
             return {
                 ok,
                 content: [
                     {
                         type: 'text',
-                        text: this.formatComplexityResponse(analysis, recommendations, tasks.length, leadDevPlan, synthesisCheckpoint),
+                        text: this.formatComplexityResponse(analysis, recommendations, tasks.length, leadDevPlan, synthesisCheckpoint) + conferReport + userAsideReport,
                     },
                 ],
             };

package/dist/mcps/orchestrator/handlers/task-handler.d.ts

@@ -31,6 +31,12 @@ export declare class TaskHandler {
         sessionId?: string;
         executionMode?: string;
         timeout?: number;
+        confer?: boolean;
+        conferFixture?: boolean;
+        collocatedText?: string;
+        userAsideId?: string;
+        setActiveAside?: boolean;
+        clearActiveAside?: boolean;
     }, deps: TaskHandlerDeps): Promise<{
         content: Array<{
             type: string;

package/dist/mcps/orchestrator/handlers/task-handler.js

@@ -19,6 +19,81 @@ export class TaskHandler {
      * Handle orchestrate-task request
      */
     async handleOrchestrateTask(args, deps) {
+        if (args.clearActiveAside === true) {
+            const projectRoot = process.cwd();
+            const { clearActiveAside, getActiveAsideId } = await import('../../../nucleus/user-aside.js');
+            const prior = getActiveAsideId(projectRoot, args.sessionId ?? null);
+            clearActiveAside(projectRoot);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: prior
+                            ? `✅ Cleared active aside \`${prior}\` — spawns resume main lead-dev plan.`
+                            : 'ℹ️ No active aside was set.',
+                    },
+                ],
+            };
+        }
+        if (args.userAsideId?.trim()) {
+            const projectRoot = process.cwd();
+            const { setActiveAsideId, loadUserAside, formatUserAsideSummary, isUserAsidesEnabled, UserAsideValidationError, } = await import('../../../nucleus/user-aside.js');
+            const { clearPendingDelegations } = await import('../../../nucleus/pending-delegations.js');
+            if (!isUserAsidesEnabled(projectRoot)) {
+                return {
+                    content: [{ type: 'text', text: '❌ User asides disabled in features.json' }],
+                };
+            }
+            const asideId = args.userAsideId.trim();
+            const aside = loadUserAside(asideId, projectRoot);
+            if (!aside) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `❌ User aside \`${asideId}\` not found — run analyze-complexity with userAsideId first.`,
+                        },
+                    ],
+                };
+            }
+            if (args.setActiveAside !== false) {
+                try {
+                    clearPendingDelegations(projectRoot);
+                    setActiveAsideId(asideId, projectRoot, args.sessionId ?? null);
+                }
+                catch (err) {
+                    const message = err instanceof UserAsideValidationError ? err.message : String(err);
+                    return { content: [{ type: 'text', text: `❌ ${message}` }] };
+                }
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `✅ Active aside: \`${asideId}\`\n\n${formatUserAsideSummary(aside)}`,
+                    },
+                ],
+            };
+        }
+        if (args.confer === true) {
+            const { runConferQuorum, formatConferQuorumReport, isConferEnabled } = await import('../../../nucleus/confer.js');
+            const sid = args.sessionId ?? `confer_${Date.now()}`;
+            if (!isConferEnabled()) {
+                return {
+                    content: [{ type: 'text', text: '❌ Confer disabled in features.json' }],
+                };
+            }
+            const conferOpts = {
+                dueReason: args.description,
+                fixture: args.conferFixture === true,
+            };
+            if (args.collocatedText)
+                conferOpts.collocatedText = args.collocatedText;
+            const result = await runConferQuorum(process.cwd(), sid, conferOpts);
+            return {
+                content: [{ type: 'text', text: formatConferQuorumReport(result) }],
+            };
+        }
         const { description, tasks = [], sessionId = `session_${Date.now()}`, executionMode = 'optimized', timeout = 300000 } = args;
         await frameworkLogger.log('orchestrator.server', 'orchestrate-task-start', 'info', { description, taskCount: tasks.length, sessionId, executionMode });
         const orchestrationResult = {

package/dist/mcps/orchestrator/server.js

@@ -99,13 +99,37 @@ export class OrchestratorServer {
                                     default: 'optimized',
                                 },
                                 timeout: { type: 'number', default: 300000 },
+                                confer: {
+                                    type: 'boolean',
+                                    description: 'Run mandatory 3-agent confer quorum (researcher, architect-tools, code-review) instead of task execution',
+                                },
+                                conferFixture: {
+                                    type: 'boolean',
+                                    description: 'Use fixture confer receipts (CI/verify)',
+                                },
+                                collocatedText: {
+                                    type: 'string',
+                                    description: 'Collocated synthesis context for confer prompts',
+                                },
+                                userAsideId: {
+                                    type: 'string',
+                                    description: 'Activate an existing user aside for spawn routing',
+                                },
+                                setActiveAside: {
+                                    type: 'boolean',
+                                    description: 'Set userAsideId as the active aside (default true)',
+                                },
+                                clearActiveAside: {
+                                    type: 'boolean',
+                                    description: 'Clear active aside — resume main lead-dev plan spawns',
+                                },
                             },
-                            required: ['description', 'tasks'],
+                            required: ['description'],
                         },
                     },
                     {
                         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. During synthesis checkpoint, returns collocated context and mandatory-consult realignment plan — pass sessionId from the active session.',
+                        description: 'Analyze task complexity and recommend orchestration strategy. When lead_dev_mode is on (features.json), includes phased plan + todos + subagent routes. Pass userAsideId to intake a parallel user aside ({asideId}.a.* namespaced todos, worktree-like). During synthesis checkpoint, returns collocated context and mandatory-consult realignment plan — pass sessionId from the active session.',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -113,6 +137,26 @@ export class OrchestratorServer {
                                     type: 'string',
                                     description: 'Active session id (required to clear synthesis checkpoint; inferred from checkpoint state when omitted)',
                                 },
+                                userAsideId: {
+                                    type: 'string',
+                                    description: 'User aside id — persists .xray/state/asides/{id}.json with {asideId}.a.* todos (parallel track)',
+                                },
+                                userAsideTitle: {
+                                    type: 'string',
+                                    description: 'Display title for the user aside (defaults to userAsideId)',
+                                },
+                                worktree: {
+                                    type: 'string',
+                                    description: 'Optional worktree path for aside isolation',
+                                },
+                                branch: {
+                                    type: 'string',
+                                    description: 'Optional git branch for the aside',
+                                },
+                                setActiveAside: {
+                                    type: 'boolean',
+                                    description: 'Activate aside for spawn routing (default true when userAsideId set)',
+                                },
                                 tasks: {
                                     type: 'array',
                                     items: {
@@ -308,18 +352,23 @@ export class OrchestratorServer {
                                 ...complexityArgs,
                                 ...(sessionId ? { sessionId } : {}),
                                 ...(synthesisDue
-                                    ? { synthesisCheckpoint: true, synthesisDueReason: dueReason }
+                                    ? {
+                                        synthesisCheckpoint: true,
+                                        synthesisDueReason: dueReason,
+                                        collocatedText: collocated?.collatedText ?? null,
+                                        conferFixture: process.env.XRAY_CONFER_FIXTURE === '1',
+                                    }
                                     : {}),
                             }, aside.asideId);
                             let content = result.content;
                             if (synthesisDue && collocated?.collatedText) {
                                 content = appendSynthesisContextToResponse(content, collocated.collatedText);
                             }
-                            if (synthesisDue && result.ok) {
+                            if (synthesisDue && result.ok && !result.content[0]?.text?.includes('Confer quorum')) {
                                 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.`,
+                                        text: `${block.text}\n\n**Confer** runs automatically at synthesis checkpoint (researcher → architect-tools → code-review). Checkpoint clears when all consult todos complete.`,
                                     }
                                     : block);
                             }

package/dist/memory-routing/provider-loader.js

@@ -4,6 +4,21 @@ import { pathToFileURL } from 'node:url';
 import { frameworkLogger } from '../core/framework-logger.js';
 import { createMemoryRoutingProvider as createNullProvider } from './null-provider.js';
 import { validateMemoryRoutingConfig } from './validate-config.js';
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function resolveUnavailableReason(provider) {
+    const statusProvider = provider;
+    if (typeof statusProvider.getAvailabilityStatus !== 'function') {
+        return null;
+    }
+    try {
+        return statusProvider.getAvailabilityStatus().reason ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 const REPERTOIRE_CANDIDATE_PATHS = [
     '../repertoire/dist/provider/memory-routing-provider.js',
     '../../repertoire/dist/provider/memory-routing-provider.js',
@@ -68,13 +83,26 @@ export async function loadMemoryRoutingProvider(config, cwd = process.cwd()) {
         if (!provider?.id || typeof provider.isAvailable !== 'function') {
             throw new Error(`Invalid memory routing provider from ${modulePath}`);
         }
+        const availabilityReason = resolveUnavailableReason(provider);
         if (!provider.isAvailable()) {
             await frameworkLogger.log('memory-routing', 'provider-unavailable', 'error', {
                 providerId: provider.id,
                 modulePath,
-                message: `Provider "${provider.id}" loaded but isAvailable() returned false. Falling back to null provider.`,
+                unavailableReason: availabilityReason,
+                message: `Provider "${provider.id}" loaded but isAvailable() returned false (${availabilityReason ?? 'unknown'}). Falling back to null provider.`,
             });
-            return createNullProvider();
+            if (availabilityReason === 'empty_registry') {
+                await sleep(100);
+                if (provider.isAvailable()) {
+                    await frameworkLogger.log('memory-routing', 'provider-retry-ok', 'info', { providerId: provider.id, modulePath });
+                }
+                else {
+                    return createNullProvider();
+                }
+            }
+            else {
+                return createNullProvider();
+            }
         }
         await frameworkLogger.log('memory-routing', 'provider-loaded', 'info', { providerId: provider.id, name: provider.name, modulePath });
         return provider;

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

@@ -0,0 +1,41 @@
+/**
+ * User-aside worktree path resolution, spawn cwd validation, optional git provision.
+ */
+/** Minimal spawn tool input for cwd extraction (avoids circular import with delegation-gate). */
+export interface SpawnCwdToolInput {
+    cwd?: string;
+    working_directory?: string;
+    workingDirectory?: string;
+    isolation?: string;
+    isolation_mode?: string;
+    worktree_path?: string;
+    worktreePath?: string;
+    worktree?: string;
+    [key: string]: unknown;
+}
+export interface AsideWorktreeCwdResult {
+    valid: boolean;
+    gate?: 'aside-worktree-cwd-missing' | 'aside-worktree-cwd-mismatch';
+    reason?: string;
+    hint?: Record<string, unknown>;
+}
+export interface WorktreeProvisionResult {
+    ok: boolean;
+    path: string;
+    created: boolean;
+    message: string;
+}
+export declare function normalizeWorktreePath(worktree: string, projectRoot: string): string;
+export declare function isAutoProvisionWorktreeEnabled(projectRoot?: string): boolean;
+/** Extract spawn cwd from host Task / spawn_subagent tool input. */
+export declare function extractSpawnCwd(toolInput: SpawnCwdToolInput, projectRoot: string): string | null;
+export declare function validateAsideWorktreeCwd(worktree: string | undefined, toolInput: SpawnCwdToolInput, projectRoot: string): AsideWorktreeCwdResult;
+/**
+ * Guarded `git worktree add` when auto_provision_worktree is enabled.
+ * Creates branch with -b when it does not exist locally.
+ */
+export declare function provisionGitWorktree(opts: {
+    projectRoot: string;
+    worktree: string;
+    branch: string;
+}): WorktreeProvisionResult;

package/dist/nucleus/aside-worktree.js

@@ -0,0 +1,164 @@
+/**
+ * User-aside worktree path resolution, spawn cwd validation, optional git provision.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { isUserAsidesEnabled } from './user-aside.js';
+export function normalizeWorktreePath(worktree, projectRoot) {
+    const trimmed = worktree.trim().replace(/\/$/, '');
+    const resolved = path.isAbsolute(trimmed) ? trimmed : path.resolve(projectRoot, trimmed);
+    return resolved.replace(/\/$/, '');
+}
+export function isAutoProvisionWorktreeEnabled(projectRoot = process.cwd()) {
+    if (!isUserAsidesEnabled(projectRoot))
+        return false;
+    const featuresPath = path.join(projectRoot, '.xray', 'features.json');
+    if (!fs.existsSync(featuresPath))
+        return false;
+    try {
+        const data = JSON.parse(fs.readFileSync(featuresPath, 'utf8'));
+        const raw = data.multi_agent_orchestration?.user_asides;
+        if (raw?.enabled === false)
+            return false;
+        return raw?.auto_provision_worktree === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Extract spawn cwd from host Task / spawn_subagent tool input. */
+export function extractSpawnCwd(toolInput, projectRoot) {
+    const isolation = toolInput.isolation ?? toolInput.isolation_mode;
+    if (isolation === 'worktree' || isolation === 'git_worktree') {
+        const wt = toolInput.worktree_path ??
+            toolInput.worktreePath ??
+            toolInput.worktree ??
+            toolInput.cwd ??
+            toolInput.working_directory ??
+            toolInput.workingDirectory;
+        if (wt != null && String(wt).trim() !== '') {
+            return normalizeWorktreePath(String(wt), projectRoot);
+        }
+    }
+    const raw = toolInput.cwd ??
+        toolInput.working_directory ??
+        toolInput.workingDirectory;
+    if (raw == null || String(raw).trim() === '')
+        return null;
+    return normalizeWorktreePath(String(raw), projectRoot);
+}
+export function validateAsideWorktreeCwd(worktree, toolInput, projectRoot) {
+    if (!worktree?.trim())
+        return { valid: true };
+    const expected = normalizeWorktreePath(worktree, projectRoot);
+    const projectNorm = path.resolve(projectRoot).replace(/\/$/, '');
+    if (projectNorm === expected || projectNorm.startsWith(`${expected}/`)) {
+        return { valid: true };
+    }
+    const spawnCwd = extractSpawnCwd(toolInput, projectRoot);
+    if (!spawnCwd) {
+        return {
+            valid: false,
+            gate: 'aside-worktree-cwd-missing',
+            reason: `Aside worktree is ${expected} but project root is ${projectNorm} — ` +
+                'spawn must set cwd / working_directory / isolation:worktree to the aside worktree',
+            hint: {
+                worktree: expected,
+                projectRoot: projectNorm,
+                required: ['cwd', 'working_directory', 'isolation:worktree'],
+            },
+        };
+    }
+    if (spawnCwd !== expected && !spawnCwd.startsWith(`${expected}/`)) {
+        return {
+            valid: false,
+            gate: 'aside-worktree-cwd-mismatch',
+            reason: `Spawn cwd ${spawnCwd} does not match aside worktree ${expected}`,
+            hint: { worktree: expected, spawnCwd, projectRoot: projectNorm },
+        };
+    }
+    return { valid: true };
+}
+function gitBranchExists(projectRoot, branch) {
+    try {
+        execFileSync('git', ['rev-parse', '--verify', branch], {
+            cwd: projectRoot,
+            stdio: 'pipe',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolvePathForCompare(p) {
+    try {
+        return fs.realpathSync.native(p).replace(/\/$/, '');
+    }
+    catch {
+        return path.resolve(p).replace(/\/$/, '');
+    }
+}
+function isGitWorktreePath(wtPath, projectRoot) {
+    try {
+        const out = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+            cwd: projectRoot,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const normalized = resolvePathForCompare(wtPath);
+        return out.split('\n').some((line) => {
+            if (!line.startsWith('worktree '))
+                return false;
+            const listed = line.slice('worktree '.length).trim();
+            return resolvePathForCompare(listed) === normalized;
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Guarded `git worktree add` when auto_provision_worktree is enabled.
+ * Creates branch with -b when it does not exist locally.
+ */
+export function provisionGitWorktree(opts) {
+    const wtPath = normalizeWorktreePath(opts.worktree, opts.projectRoot);
+    const branch = opts.branch.trim();
+    if (!branch) {
+        return { ok: false, path: wtPath, created: false, message: 'branch is required' };
+    }
+    if (fs.existsSync(wtPath)) {
+        if (isGitWorktreePath(wtPath, opts.projectRoot)) {
+            return { ok: true, path: wtPath, created: false, message: 'worktree already exists' };
+        }
+        return {
+            ok: false,
+            path: wtPath,
+            created: false,
+            message: `path exists but is not a git worktree: ${wtPath}`,
+        };
+    }
+    const gitDir = path.join(opts.projectRoot, '.git');
+    if (!fs.existsSync(gitDir)) {
+        return {
+            ok: false,
+            path: wtPath,
+            created: false,
+            message: `not a git repository: ${opts.projectRoot}`,
+        };
+    }
+    const branchExists = gitBranchExists(opts.projectRoot, branch);
+    const args = branchExists
+        ? ['worktree', 'add', wtPath, branch]
+        : ['worktree', 'add', '-b', branch, wtPath];
+    try {
+        execFileSync('git', args, { cwd: opts.projectRoot, stdio: 'pipe' });
+        return { ok: true, path: wtPath, created: true, message: 'worktree provisioned' };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, path: wtPath, created: false, message };
+    }
+}

package/dist/nucleus/confer.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Confer — mandatory 3-agent quorum SSOT (researcher / architect-tools / code-review).
+ * Triggered automatically at synthesis checkpoint; records consult receipts + plan todos.
+ */
+import { type SynthesisConsultReceipt } from './synthesis-consult-receipt.js';
+export declare const CONFER_AGENTS: readonly ["researcher", "architect-tools", "code-review"];
+export interface ConferConfig {
+    enabled: boolean;
+    on_synthesis: boolean;
+}
+export interface ConferCheckpointState {
+    version: 1;
+    sessionId: string;
+    triggeredAt: string;
+    dueReason: string | null;
+    status: 'pending' | 'in_progress' | 'completed' | 'failed';
+    completedAgents: string[];
+    lastError?: string;
+}
+export interface ConferAgentResult {
+    todoId: string;
+    subagent: string;
+    outputText: string;
+    receiptRecorded: boolean;
+    todoCompleted: boolean;
+    verdict: SynthesisConsultReceipt['verdict'] | null;
+    error?: string;
+}
+export interface ConferQuorumResult {
+    status: 'completed' | 'partial' | 'skipped' | 'failed';
+    agents: ConferAgentResult[];
+    message: string;
+}
+export declare function conferCheckpointPath(projectRoot?: string): string;
+export declare function defaultConferConfig(): ConferConfig;
+export declare function loadConferConfig(projectRoot?: string): ConferConfig;
+export declare function isConferEnabled(projectRoot?: string): boolean;
+export declare function loadConferCheckpoint(projectRoot?: string): ConferCheckpointState | null;
+export declare function saveConferCheckpoint(state: ConferCheckpointState, projectRoot?: string): string;
+export declare function triggerConferCheckpoint(sessionId: string, dueReason: string | null, projectRoot?: string): ConferCheckpointState;
+export declare function isConferPending(projectRoot?: string, sessionId?: string | null): boolean;
+export declare function buildConferPrompt(subagent: string, todoTask: string, collocatedText: string, dueReason: string | null): string;
+/** Map confer subagent → MCP server + tool. */
+export declare function conferAgentMcpTarget(subagent: string): {
+    server: string;
+    tool: string;
+    args: (prompt: string, projectRoot: string) => Record<string, unknown>;
+};
+export declare function invokeConferAgent(subagent: string, prompt: string, projectRoot?: string): Promise<string>;
+export declare function applyConferConsultResult(todoId: string, subagent: string, sessionId: string, outputText: string, projectRoot?: string): ConferAgentResult;
+export declare function writeFixtureConferReceipt(todoId: string, subagent: string, sessionId: string, projectRoot?: string): ConferAgentResult;
+export declare function runConferQuorum(projectRoot: string | undefined, sessionId: string, options?: {
+    collocatedText?: string;
+    dueReason?: string | null;
+    fixture?: boolean;
+}): Promise<ConferQuorumResult>;
+export declare function formatConferQuorumReport(result: ConferQuorumResult): string;