0xray 3.4.10 → 3.5.1

package/dist/integrations/hooks/delegation-gate-runtime.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Load compiled delegation-gate SSOT from consumer or package dist.
+ * Used by Grok hooks, Hermes bridge, and verify fixtures.
+ */
+import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** 0xray package root — never use consumer workspace env (GROK_WORKSPACE_ROOT / XRAY_ROOT). */
+function resolvePackageRoot() {
+  let dir = __dirname;
+  for (let i = 0; i < 10; i++) {
+    const pkg = join(dir, 'package.json');
+    if (existsSync(pkg)) {
+      try {
+        const require = createRequire(join(dir, 'package.json'));
+        const name = require('./package.json').name;
+        if (name === '0xray') return dir;
+      } catch {
+        /* continue */
+      }
+    }
+    const nm = join(dir, 'node_modules', '0xray', 'package.json');
+    if (existsSync(nm)) {
+      return dirname(nm);
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(__dirname, '../../..');
+}
+
+function loadDelegationGate() {
+  const root = resolvePackageRoot();
+  const candidates = [
+    join(__dirname, '../../nucleus/delegation-gate.js'),
+    join(root, 'dist/nucleus/delegation-gate.js'),
+    join(process.cwd(), 'node_modules/0xray/dist/nucleus/delegation-gate.js'),
+  ];
+  const found = candidates.find((p) => existsSync(p));
+  if (!found) {
+    throw new Error(
+      'delegation-gate.js missing — run npm run build in 0xray or npm install 0xray@^3.5.1',
+    );
+  }
+  return createRequire(import.meta.url)(found);
+}
+
+const gate = loadDelegationGate();
+
+export const {
+  loadDelegationGateFeatures,
+  normalizeHostToolInput,
+  evaluatePreToolGate,
+  evaluatePendingDelegationGate,
+  evaluateSpawnPlanGate,
+  evaluatePostToolSpawn,
+  checkPendingDelegationGate,
+  checkSubagentGate,
+  satisfyDelegationsFromToolInput,
+  isSubagentTool,
+  isOrchestrateToolEvent,
+  isReadOnlyTool,
+  isWriteTool,
+  isShellTool,
+  getActivePendingDelegations,
+  validateSpawnMatchesTodo,
+  updatePlanTodoStatus,
+  updatePlanTodoStatusInPlace,
+} = gate;

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

@@ -26,6 +26,7 @@ export declare class ComplexityHandler {
      */
     handleAnalyzeComplexity(args: {
         tasks: AnalyzeComplexityInput[];
+        sessionId?: string;
     }, asideId?: string): Promise<{
         content: Array<{
             type: string;

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

@@ -5,6 +5,8 @@
  */
 import { frameworkLogger } from '../../../core/framework-logger.js';
 import { buildLeadDevPlan, isLeadDevModeActive, persistLeadDevPlan, } from '../../../nucleus/autonomy-kernel.js';
+import { bindPlanToSession } from '../../../nucleus/lead-dev-plan-persistence.js';
+import { clearPendingDelegations } from '../../../nucleus/pending-delegations.js';
 import { getExecutionPlanner } from '../execution/execution-planner.js';
 import { addObservations, extractComplexityObservations } from '../aside-context.js';
 function normalizeAnalyzeTasks(raw) {
@@ -63,9 +65,14 @@ export class ComplexityHandler {
                 : null;
             if (leadDevPlan) {
                 try {
+                    const sessionId = args.sessionId ?? `analyze-${Date.now()}`;
+                    clearPendingDelegations();
                     const planPath = persistLeadDevPlan(leadDevPlan);
+                    const bound = bindPlanToSession(sessionId);
                     await frameworkLogger.log('orchestrator.server', 'lead-dev-plan-persisted', 'info', {
                         planPath,
+                        sessionId,
+                        planGeneration: bound?.planGeneration,
                         phaseCount: leadDevPlan.phases.length,
                         todoCount: leadDevPlan.phases.reduce((n, p) => n + p.todos.length, 0),
                     });

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

@@ -8,6 +8,7 @@ import { getExecutionPlanner } from '../execution/execution-planner.js';
 import { mcpClientManager } from '../../../mcps/mcp-client.js';
 import { addObservations, extractOrchestrationObservations, spawnAside } from '../aside-context.js';
 import { getProvider } from '../config/memory-routing-bridge.js';
+import { delegationSummaryForResponse, recordDeferredDelegations, } from '../../../nucleus/pending-delegations.js';
 /**
  * Task Handler
  * Processes orchestrate-task requests
@@ -31,6 +32,7 @@ export class TaskHandler {
             recommendations: [],
         };
         const startTime = Date.now();
+        let pendingDelegations = [];
         try {
             // Validate tasks
             const validation = this.planner.validateTasks(tasks);
@@ -50,6 +52,10 @@ export class TaskHandler {
                 });
             }
             const results = await this.executePlan(executionPlan, sessionId, timeout);
+            if (results.deferredRecords.length > 0) {
+                pendingDelegations = recordDeferredDelegations(sessionId, results.deferredRecords);
+                await frameworkLogger.log('orchestrator.task-handler', 'pending-delegations-recorded', 'info', { count: pendingDelegations.length, sessionId });
+            }
             // Feed per-task outcomes back to memory provider (not aggregate session stats)
             if (memoryProvider.ingestFeedback) {
                 const outcomeByKey = new Map(results.taskOutcomes.map((o) => [`${o.agent}:${o.taskId}`, o]));
@@ -100,7 +106,7 @@ export class TaskHandler {
             orchestrationResult.recommendations.push(`Orchestration error: ${error instanceof Error ? error.message : String(error)}`);
         }
         orchestrationResult.duration = Date.now() - startTime;
-        const response = this.formatOrchestrationResponse(description, orchestrationResult, executionMode);
+        const response = this.formatOrchestrationResponse(description, orchestrationResult, executionMode, pendingDelegations);
         return { content: [{ type: 'text', text: response }] };
     }
     /**
@@ -114,6 +120,7 @@ export class TaskHandler {
         let failedTasks = 0;
         let deferredTasks = 0;
         const agentOutputs = {};
+        const deferredRecords = [];
         const taskOutcomes = [];
         const skillServers = new Set([
             'code-review', 'code-reviewer',
@@ -167,6 +174,12 @@ export class TaskHandler {
             else {
                 for (const task of tasks) {
                     deferredTasks++;
+                    deferredRecords.push({
+                        taskId: task.id,
+                        agent,
+                        description: task.description,
+                        type: task.type,
+                    });
                     taskOutcomes.push({
                         taskId: task.id,
                         agent,
@@ -199,6 +212,7 @@ export class TaskHandler {
             bottlenecks,
             recommendations,
             agentOutputs,
+            deferredRecords,
             taskOutcomes,
         };
     }
@@ -232,7 +246,10 @@ export class TaskHandler {
     /**
      * Format orchestration response
      */
-    formatOrchestrationResponse(description, result, executionMode) {
+    formatOrchestrationResponse(description, result, executionMode, pendingDelegations = []) {
+        const delegationsBlock = pendingDelegations.length > 0
+            ? `\n**Delegations (host Task required):**\n\`\`\`json\n${JSON.stringify({ delegations: delegationSummaryForResponse(pendingDelegations) }, null, 2)}\n\`\`\`\n`
+            : '';
         return `🎯 Orchestration Complete: "${description}"
 
 **Session ID:** ${result.sessionId}
@@ -257,6 +274,6 @@ ${result.recommendations.length > 0 ? result.recommendations.map((r) => `•
 
 ${result.agentOutputs && Object.keys(result.agentOutputs).length > 0
             ? `**Agent Outputs (real MCP responses):**\n${Object.entries(result.agentOutputs).map(([k, v]) => `• ${k}: ${v.substring(0, 200)}${v.length > 200 ? '...' : ''}`).join('\n')}\n`
-            : ''}`;
+            : ''}${delegationsBlock}`;
     }
 }

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

@@ -0,0 +1,86 @@
+/**
+ * Multi-host delegation gate SSOT — pending-delegations + spawn todo enforcement.
+ * Grok / Hermes / OpenCode adapters call evaluatePreToolGate; Grok-only logic was
+ * previously duplicated in grok-hook-utils.js.
+ */
+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 / unrelated work while pending delegations exist. */
+export declare function evaluatePendingDelegationGate(toolName: string, toolInput: ToolGateInput, ctx: PreToolGateContext): PreToolGateResult;
+/**
+ * Full pre-tool evaluation — same order as Grok PreToolUse:
+ * pending gate first, 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,275 @@
+/**
+ * Multi-host delegation gate SSOT — pending-delegations + spawn todo enforcement.
+ * Grok / Hermes / OpenCode adapters call evaluatePreToolGate; Grok-only logic was
+ * previously duplicated in grok-hook-utils.js.
+ */
+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, hasValidLeadDevPlanForSpawn, loadPersistedLeadDevPlan, validateSpawnMatchesTodo, updatePlanTodoStatus, } from './lead-dev-plan-persistence.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',
+    'get-orchestration-status',
+    'get_orchestration_status',
+    'orchestrate-task',
+    'orchestrate_task',
+]);
+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 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 / 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 — same order as Grok PreToolUse:
+ * pending gate first, then spawn todo gate for subagent tools.
+ */
+export function evaluatePreToolGate(toolName, toolInput, ctx) {
+    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);
+    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

@@ -0,0 +1,43 @@
+/**
+ * Todo-level lead-dev plan persistence — spawn gate survives beyond 4h mtime
+ * while outstanding todos remain. SSOT for plan todo status sync.
+ */
+import type { LeadDevPlan, LeadDevTodo } from './autonomy-kernel.js';
+export interface PersistedLeadDevPlan extends LeadDevPlan {
+    persistedAt?: string;
+    sessionId?: string;
+    planGeneration?: number;
+}
+export interface SpawnTodoValidation {
+    valid: boolean;
+    reason?: string;
+    gate?: string;
+    hint?: Record<string, unknown>;
+    expectedTodoId?: string | null;
+}
+export declare function leadDevPlanStatePath(projectRoot?: string): string;
+export declare function loadPersistedLeadDevPlan(projectRoot?: string): PersistedLeadDevPlan | null;
+export declare function savePersistedLeadDevPlan(plan: PersistedLeadDevPlan, projectRoot?: string): string;
+export declare function allPlanTodos(plan: PersistedLeadDevPlan): LeadDevTodo[];
+export declare function getOutstandingTodos(plan: PersistedLeadDevPlan): LeadDevTodo[];
+/** First outstanding todo in phase order */
+export declare function getNextRequiredTodo(plan: PersistedLeadDevPlan): LeadDevTodo | null;
+/**
+ * Plan valid for spawn when active and either:
+ * - outstanding todos remain (ignores 4h mtime), or
+ * - all todos complete and persistedAt within TTL
+ */
+export declare function hasValidLeadDevPlanForSpawn(projectRoot?: string, _sessionId?: string | null): 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 {
+    prompt?: string;
+    description?: string;
+    task?: string;
+    subagent_type?: string;
+    agent?: string;
+    delegationId?: string;
+    planTodoId?: string;
+}
+export declare function validateSpawnMatchesTodo(toolInput: SpawnToolInput, projectRoot?: string, expectedTodo?: LeadDevTodo | null): SpawnTodoValidation;
+export declare function markTodoInProgressOnSpawn(toolInput: SpawnToolInput, projectRoot?: string): string | null;