agentxchain 2.154.11 → 2.155.1

package/src/lib/governed-state.js

@@ -20,6 +20,7 @@ import { join, dirname } from 'path';
 import { randomBytes, createHash } from 'crypto';
 import { safeWriteJson } from './safe-write.js';
 import { validateStagedTurnResult } from './turn-result-validator.js';
+import { summarizeIdleExpansionResult } from './idle-expansion-result-validator.js';
 import { evaluatePhaseExit, evaluateRunCompletion, getNextPhase } from './gate-evaluator.js';
 import { evaluateApprovalPolicy } from './approval-policy.js';
 import { evaluatePolicies } from './policy-evaluator.js';
@@ -3565,6 +3566,9 @@ export function assignGovernedTurn(root, config, roleId, options = {}) {
   if (options.intakeContext) {
     newTurn.intake_context = options.intakeContext;
   }
+  if (options.idleExpansionContext) {
+    newTurn.idle_expansion_context = options.idleExpansionContext;
+  }
 
   // Attach delegation context if this turn fulfills a pending delegation
   const delegationQueue = state.delegation_queue || [];
@@ -4870,6 +4874,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   }
 
   const acceptedSequence = (state.turn_sequence || 0) + 1;
+  const idleExpansionResultSummary = summarizeIdleExpansionResult(turnResult);
   const historyEntry = {
     turn_id: turnResult.turn_id,
     run_id: turnResult.run_id,
@@ -4891,6 +4896,9 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     proposed_next_role: turnResult.proposed_next_role,
     phase_transition_request: turnResult.phase_transition_request,
     run_completion_request: Boolean(turnResult.run_completion_request),
+    ...(idleExpansionResultSummary
+      ? { idle_expansion_result_summary: idleExpansionResultSummary }
+      : {}),
     assigned_sequence: Number.isInteger(currentTurn.assigned_sequence) ? currentTurn.assigned_sequence : acceptedSequence,
     accepted_sequence: acceptedSequence,
     concurrent_with: Array.isArray(currentTurn.concurrent_with) ? currentTurn.concurrent_with : [],

package/src/lib/idle-expansion-result-validator.js

@@ -0,0 +1,251 @@
+import { VALID_GOVERNED_TEMPLATE_IDS } from './governed-templates.js';
+
+const VALID_KINDS = ['new_intake_intent', 'vision_exhausted'];
+const VALID_TRACE_KINDS = ['advances', 'supports', 'unblocks'];
+const VALID_EXHAUSTION_STATUSES = ['complete', 'deferred', 'out_of_scope'];
+const VALID_PRIORITIES = ['p0', 'p1', 'p2', 'p3'];
+
+export function validateIdleExpansionTurnResult(turnResult, context = {}) {
+  const required = context.required === true;
+  const errors = [];
+  const warnings = [];
+  const result = turnResult?.idle_expansion_result;
+
+  if (result === undefined || result === null) {
+    if (required) {
+      errors.push('idle_expansion_result is required for vision_idle_expansion turns.');
+    }
+    return { ok: errors.length === 0, errors, warnings };
+  }
+
+  if (typeof result !== 'object' || Array.isArray(result)) {
+    return {
+      ok: false,
+      errors: ['idle_expansion_result must be an object.'],
+      warnings,
+    };
+  }
+
+  if (!VALID_KINDS.includes(result.kind)) {
+    errors.push(`idle_expansion_result.kind must be one of: ${VALID_KINDS.join(', ')}.`);
+  }
+
+  if (!Number.isInteger(result.expansion_iteration) || result.expansion_iteration < 1) {
+    errors.push('idle_expansion_result.expansion_iteration must be a positive integer.');
+  } else if (
+    Number.isInteger(context.expansionIteration)
+    && context.expansionIteration >= 1
+    && result.expansion_iteration !== context.expansionIteration
+  ) {
+    errors.push(
+      `idle_expansion_result.expansion_iteration mismatch: got ${result.expansion_iteration}, expected ${context.expansionIteration}.`
+    );
+  }
+
+  const visionHeadings = normalizeVisionHeadingSnapshot(context.visionHeadingsSnapshot);
+  const traceErrors = validateVisionTraceability(result.vision_traceability, {
+    required: result.kind === 'new_intake_intent',
+    visionHeadings,
+  });
+  errors.push(...traceErrors);
+
+  if (result.kind === 'new_intake_intent') {
+    errors.push(...validateNewIntakeIntent(result.new_intake_intent));
+    if ('vision_exhausted' in result) {
+      errors.push('idle_expansion_result.vision_exhausted is only allowed when kind is "vision_exhausted".');
+    }
+  }
+
+  if (result.kind === 'vision_exhausted') {
+    errors.push(...validateVisionExhausted(result.vision_exhausted, visionHeadings));
+    if ('new_intake_intent' in result) {
+      errors.push('idle_expansion_result.new_intake_intent is only allowed when kind is "new_intake_intent".');
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+export function summarizeIdleExpansionResult(turnResult) {
+  const result = turnResult?.idle_expansion_result;
+  if (!result || typeof result !== 'object' || Array.isArray(result)) {
+    return null;
+  }
+
+  if (result.kind === 'new_intake_intent') {
+    return {
+      kind: result.kind,
+      expansion_iteration: result.expansion_iteration,
+      new_intent_title: truncate(result.new_intake_intent?.title || '', 120),
+      priority: result.new_intake_intent?.priority || null,
+      template: result.new_intake_intent?.template || null,
+    };
+  }
+
+  if (result.kind === 'vision_exhausted') {
+    const firstReason = Array.isArray(result.vision_exhausted?.classification)
+      ? result.vision_exhausted.classification.find((entry) => typeof entry?.reason === 'string')?.reason || ''
+      : '';
+    return {
+      kind: result.kind,
+      expansion_iteration: result.expansion_iteration,
+      reason_excerpt: truncate(firstReason, 160),
+    };
+  }
+
+  return {
+    kind: result.kind || null,
+    expansion_iteration: result.expansion_iteration || null,
+  };
+}
+
+function validateVisionTraceability(traceability, { required, visionHeadings }) {
+  const errors = [];
+
+  if (!Array.isArray(traceability)) {
+    errors.push('idle_expansion_result.vision_traceability must be an array.');
+    return errors;
+  }
+  if (required && traceability.length === 0) {
+    errors.push('idle_expansion_result.vision_traceability must cite at least one VISION.md heading for new_intake_intent.');
+  }
+
+  for (let i = 0; i < traceability.length; i++) {
+    const entry = traceability[i];
+    const prefix = `idle_expansion_result.vision_traceability[${i}]`;
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      errors.push(`${prefix} must be an object.`);
+      continue;
+    }
+
+    const heading = typeof entry.vision_heading === 'string' ? entry.vision_heading.trim() : '';
+    if (!heading) {
+      errors.push(`${prefix}.vision_heading must be a non-empty string.`);
+    } else if (visionHeadings.length > 0 && !visionHeadings.includes(heading)) {
+      errors.push(`${prefix}.vision_heading "${heading}" is not present in the session VISION.md heading snapshot.`);
+    }
+
+    if (entry.goal !== undefined && (typeof entry.goal !== 'string' || !entry.goal.trim())) {
+      errors.push(`${prefix}.goal must be a non-empty string when provided.`);
+    }
+    if (entry.kind !== undefined && !VALID_TRACE_KINDS.includes(entry.kind)) {
+      errors.push(`${prefix}.kind must be one of: ${VALID_TRACE_KINDS.join(', ')}.`);
+    }
+  }
+
+  return errors;
+}
+
+function validateNewIntakeIntent(intent) {
+  const errors = [];
+  const prefix = 'idle_expansion_result.new_intake_intent';
+
+  if (!intent || typeof intent !== 'object' || Array.isArray(intent)) {
+    return [`${prefix} must be an object.`];
+  }
+
+  for (const field of ['title', 'charter']) {
+    if (typeof intent[field] !== 'string' || !intent[field].trim()) {
+      errors.push(`${prefix}.${field} must be a non-empty string.`);
+    }
+  }
+
+  if (!VALID_PRIORITIES.includes(intent.priority)) {
+    errors.push(`${prefix}.priority must be one of: ${VALID_PRIORITIES.join(', ')}.`);
+  }
+  if (!VALID_GOVERNED_TEMPLATE_IDS.includes(intent.template)) {
+    errors.push(`${prefix}.template must be one of: ${VALID_GOVERNED_TEMPLATE_IDS.join(', ')}.`);
+  }
+  if (!Array.isArray(intent.acceptance_contract) || intent.acceptance_contract.length === 0) {
+    errors.push(`${prefix}.acceptance_contract must be a non-empty array.`);
+  } else {
+    for (let i = 0; i < intent.acceptance_contract.length; i++) {
+      if (typeof intent.acceptance_contract[i] !== 'string' || !intent.acceptance_contract[i].trim()) {
+        errors.push(`${prefix}.acceptance_contract[${i}] must be a non-empty string.`);
+      }
+    }
+  }
+
+  return errors;
+}
+
+function validateVisionExhausted(visionExhausted, visionHeadings) {
+  const errors = [];
+  const prefix = 'idle_expansion_result.vision_exhausted';
+
+  if (!visionExhausted || typeof visionExhausted !== 'object' || Array.isArray(visionExhausted)) {
+    return [`${prefix} must be an object.`];
+  }
+
+  const classification = visionExhausted.classification;
+  if (!Array.isArray(classification) || classification.length === 0) {
+    errors.push(`${prefix}.classification must be a non-empty array.`);
+    return errors;
+  }
+
+  const classifiedHeadings = new Set();
+  for (let i = 0; i < classification.length; i++) {
+    const entry = classification[i];
+    const entryPrefix = `${prefix}.classification[${i}]`;
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      errors.push(`${entryPrefix} must be an object.`);
+      continue;
+    }
+
+    const heading = typeof entry.vision_heading === 'string' ? entry.vision_heading.trim() : '';
+    if (!heading) {
+      errors.push(`${entryPrefix}.vision_heading must be a non-empty string.`);
+    } else {
+      classifiedHeadings.add(heading);
+      if (visionHeadings.length > 0 && !visionHeadings.includes(heading)) {
+        errors.push(`${entryPrefix}.vision_heading "${heading}" is not present in the session VISION.md heading snapshot.`);
+      }
+    }
+    if (!VALID_EXHAUSTION_STATUSES.includes(entry.status)) {
+      errors.push(`${entryPrefix}.status must be one of: ${VALID_EXHAUSTION_STATUSES.join(', ')}.`);
+    }
+    if (typeof entry.reason !== 'string' || !entry.reason.trim()) {
+      errors.push(`${entryPrefix}.reason must be a non-empty string.`);
+    }
+  }
+
+  for (const heading of visionHeadings) {
+    if (!classifiedHeadings.has(heading)) {
+      errors.push(`${prefix}.classification must classify VISION.md heading "${heading}".`);
+    }
+  }
+
+  return errors;
+}
+
+function normalizeVisionHeadingSnapshot(snapshot) {
+  if (!Array.isArray(snapshot)) {
+    return [];
+  }
+
+  const headings = [];
+  for (const item of snapshot) {
+    const heading = typeof item === 'string'
+      ? item.trim()
+      : typeof item?.heading === 'string'
+        ? item.heading.trim()
+        : typeof item?.title === 'string'
+          ? item.title.trim()
+          : '';
+    if (heading && !headings.includes(heading)) {
+      headings.push(heading);
+    }
+  }
+  return headings;
+}
+
+function truncate(value, maxLength) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  const trimmed = value.trim();
+  if (trimmed.length <= maxLength) {
+    return trimmed;
+  }
+  return `${trimmed.slice(0, maxLength - 3)}...`;
+}

package/src/lib/intake.js

@@ -29,10 +29,11 @@ import {
   getPhaseOrder,
 } from './intent-phase-scope.js';
 
-const VALID_SOURCES = ['manual', 'ci_failure', 'git_ref_change', 'schedule', 'vision_scan'];
+const VALID_SOURCES = ['manual', 'ci_failure', 'git_ref_change', 'schedule', 'vision_scan', 'vision_idle_expansion'];
 const VALID_PRIORITIES = ['p0', 'p1', 'p2', 'p3'];
 const EVENT_ID_RE = /^evt_\d+_[0-9a-f]{4}$/;
 const INTENT_ID_RE = /^intent_\d+_[0-9a-f]{4}$/;
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
 
 // V3-S1 through S5 states. `failed` remains read-tolerant for historical/manual
 // intent files, but current first-party intake writers do not transition into it.
@@ -66,6 +67,17 @@ function computeDedupKey(source, signal) {
   return `${source}:${hash}`;
 }
 
+export function buildVisionIdleExpansionSignal(sessionId, expansionIteration, acceptedTurnId) {
+  const expansionKey = createHash('sha256')
+    .update(`${sessionId}::${expansionIteration}::${acceptedTurnId}`)
+    .digest('hex');
+  return {
+    expansion_key: expansionKey,
+    expansion_iteration: expansionIteration,
+    accepted_turn_id: acceptedTurnId,
+  };
+}
+
 function nowISO() {
   return new Date().toISOString();
 }
@@ -268,6 +280,13 @@ export function validateEventPayload(payload) {
     errors.push('signal must be a non-empty object');
   }
 
+  if (payload.source === 'vision_idle_expansion' && payload.signal && typeof payload.signal === 'object' && !Array.isArray(payload.signal)) {
+    errors.push(...validateVisionIdleExpansionSignal(payload.signal));
+    errors.push(...validateVisionIdleExpansionContext(payload.idle_expansion_context));
+  } else if (payload.idle_expansion_context !== undefined) {
+    errors.push('idle_expansion_context is only allowed for source "vision_idle_expansion"');
+  }
+
   if (!Array.isArray(payload.evidence) || payload.evidence.length === 0) {
     errors.push('evidence must be a non-empty array');
   } else {
@@ -288,6 +307,57 @@ export function validateEventPayload(payload) {
   return { valid: errors.length === 0, errors };
 }
 
+function validateVisionIdleExpansionSignal(signal) {
+  const errors = [];
+  const keys = Object.keys(signal).sort();
+  const expected = ['accepted_turn_id', 'expansion_iteration', 'expansion_key'];
+  if (JSON.stringify(keys) !== JSON.stringify(expected)) {
+    errors.push(`vision_idle_expansion signal must contain exactly: ${expected.join(', ')}`);
+    return errors;
+  }
+  if (typeof signal.expansion_key !== 'string' || !SHA256_HEX_RE.test(signal.expansion_key)) {
+    errors.push('vision_idle_expansion signal.expansion_key must be a SHA-256 hex string');
+  }
+  if (!Number.isInteger(signal.expansion_iteration) || signal.expansion_iteration < 1) {
+    errors.push('vision_idle_expansion signal.expansion_iteration must be an integer >= 1');
+  }
+  if (typeof signal.accepted_turn_id !== 'string' || !signal.accepted_turn_id.trim()) {
+    errors.push('vision_idle_expansion signal.accepted_turn_id must be a non-empty string');
+  }
+  return errors;
+}
+
+function validateVisionIdleExpansionContext(context) {
+  const errors = [];
+  if (!context || typeof context !== 'object' || Array.isArray(context)) {
+    return ['idle_expansion_context must be a JSON object for source "vision_idle_expansion"'];
+  }
+  if (!Number.isInteger(context.expansion_iteration) || context.expansion_iteration < 1) {
+    errors.push('idle_expansion_context.expansion_iteration must be an integer >= 1');
+  }
+  if (!Array.isArray(context.vision_headings_snapshot) || context.vision_headings_snapshot.length === 0) {
+    errors.push('idle_expansion_context.vision_headings_snapshot must be a non-empty array');
+  } else {
+    for (let i = 0; i < context.vision_headings_snapshot.length; i++) {
+      const heading = context.vision_headings_snapshot[i];
+      if (typeof heading !== 'string' || !heading.trim()) {
+        errors.push(`idle_expansion_context.vision_headings_snapshot[${i}] must be a non-empty string`);
+      }
+    }
+  }
+  return errors;
+}
+
+function normalizeVisionIdleExpansionContext(context) {
+  if (!context || typeof context !== 'object' || Array.isArray(context)) return null;
+  return {
+    expansion_iteration: context.expansion_iteration,
+    vision_headings_snapshot: Array.isArray(context.vision_headings_snapshot)
+      ? context.vision_headings_snapshot.map((heading) => String(heading).trim()).filter(Boolean)
+      : [],
+  };
+}
+
 export function validateTriageFields(fields, config = null) {
   const errors = [];
 
@@ -357,6 +427,12 @@ export function recordEvent(root, payload) {
     evidence: payload.evidence,
     dedup_key: dedupKey,
   };
+  const idleExpansionContext = payload.source === 'vision_idle_expansion'
+    ? normalizeVisionIdleExpansionContext(payload.idle_expansion_context)
+    : null;
+  if (idleExpansionContext) {
+    event.idle_expansion_context = idleExpansionContext;
+  }
 
   safeWriteJson(join(dirs.events, `${eventId}.json`), event);
 
@@ -380,6 +456,9 @@ export function recordEvent(root, payload) {
       { from: null, to: 'detected', at: now, reason: 'event ingested' },
     ],
   };
+  if (idleExpansionContext) {
+    intent.idle_expansion_context = idleExpansionContext;
+  }
 
   safeWriteJson(join(dirs.intents, `${intentId}.json`), intent);
 
@@ -968,6 +1047,9 @@ export function startIntent(root, intentId, options = {}) {
     return loadedEvent;
   }
   const { event } = loadedEvent;
+  const idleExpansionContext = event.source === 'vision_idle_expansion'
+    ? normalizeVisionIdleExpansionContext(intent.idle_expansion_context || event.idle_expansion_context)
+    : null;
   const intakeContext = {
     intent_id: intent.intent_id,
     event_id: intent.event_id,
@@ -976,6 +1058,7 @@ export function startIntent(root, intentId, options = {}) {
     charter: intent.charter || null,
     acceptance_contract: Array.isArray(intent.acceptance_contract) ? intent.acceptance_contract : [],
     phase_scope: intent.phase_scope || null,
+    ...(idleExpansionContext ? { idle_expansion: idleExpansionContext } : {}),
   };
 
   // Load governed project context
@@ -1072,6 +1155,7 @@ export function startIntent(root, intentId, options = {}) {
   // Assign governed turn
   const assignResult = assignGovernedTurn(root, config, roleId.role, {
     intakeContext,
+    ...(idleExpansionContext ? { idleExpansionContext } : {}),
   });
   if (!assignResult.ok) {
     return { ok: false, error: `turn assignment failed: ${assignResult.error}`, exitCode: 1 };

package/src/lib/normalized-config.js

@@ -647,6 +647,7 @@ export function validateRunLoopConfig(runLoop) {
 }
 
 export const VALID_RECONCILE_OPERATOR_COMMITS = ['manual', 'auto_safe_only', 'disabled'];
+export { VALID_ON_IDLE, RESERVED_ON_IDLE };
 
 function validateRunLoopContinuousConfig(path, continuous, errors) {
   if (typeof continuous !== 'object' || Array.isArray(continuous)) {
@@ -669,6 +670,32 @@ function validateRunLoopContinuousConfig(path, continuous, errors) {
       );
     }
   }
+  // BUG-60: validate on_idle policy
+  if (continuous.on_idle !== undefined && continuous.on_idle !== null) {
+    if (typeof continuous.on_idle !== 'string') {
+      errors.push(`${path}.on_idle must be one of: ${VALID_ON_IDLE.join(', ')}`);
+    } else if (!VALID_ON_IDLE.includes(continuous.on_idle)) {
+      errors.push(`${path}.on_idle must be one of: ${VALID_ON_IDLE.join(', ')}`);
+    }
+  }
+  // BUG-60: validate idle_expansion block when present
+  if (continuous.idle_expansion !== undefined && continuous.idle_expansion !== null) {
+    if (typeof continuous.idle_expansion !== 'object' || Array.isArray(continuous.idle_expansion)) {
+      errors.push(`${path}.idle_expansion must be an object`);
+    } else {
+      if (continuous.idle_expansion.max_expansions !== undefined) {
+        validatePositiveInteger(`${path}.idle_expansion.max_expansions`, continuous.idle_expansion.max_expansions, 'expansion count', errors);
+      }
+      if (continuous.idle_expansion.malformed_retry_limit !== undefined
+          && continuous.idle_expansion.malformed_retry_limit !== null) {
+        if (typeof continuous.idle_expansion.malformed_retry_limit !== 'number'
+            || !Number.isInteger(continuous.idle_expansion.malformed_retry_limit)
+            || continuous.idle_expansion.malformed_retry_limit < 0) {
+          errors.push(`${path}.idle_expansion.malformed_retry_limit must be a non-negative integer`);
+        }
+      }
+    }
+  }
 }
 
 function validateAutoRetryOnGhostConfig(path, value, errors) {
@@ -1329,9 +1356,43 @@ export function normalizeV4(raw) {
   };
 }
 
+const VALID_ON_IDLE = ['exit', 'perpetual', 'human_review'];
+const RESERVED_ON_IDLE = [];
+
+function normalizeIdleExpansion(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return {
+      sources: ['.planning/VISION.md', '.planning/ROADMAP.md', '.planning/SYSTEM_SPEC.md'],
+      max_expansions: 5,
+      role: 'pm',
+      output: 'intake_intent_or_vision_exhausted',
+      malformed_retry_limit: 1,
+    };
+  }
+  const sources = Array.isArray(raw.sources) && raw.sources.length > 0
+    ? raw.sources.filter(s => typeof s === 'string' && s.length > 0)
+    : ['.planning/VISION.md', '.planning/ROADMAP.md', '.planning/SYSTEM_SPEC.md'];
+  return {
+    sources: sources.length > 0 ? sources : ['.planning/VISION.md'],
+    max_expansions: Number.isInteger(raw.max_expansions) && raw.max_expansions >= 1 ? raw.max_expansions : 5,
+    role: typeof raw.role === 'string' && raw.role.length > 0 ? raw.role : 'pm',
+    output: 'intake_intent_or_vision_exhausted',
+    malformed_retry_limit: Number.isInteger(raw.malformed_retry_limit) && raw.malformed_retry_limit >= 0
+      ? raw.malformed_retry_limit : 1,
+  };
+}
+
 function normalizeContinuousConfig(raw) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
   if (raw.enabled !== true) return null;
+
+  // Normalize on_idle — reserved and invalid values fall back to 'exit';
+  // validation layer reports actionable errors to the operator.
+  let on_idle = 'exit';
+  if (typeof raw.on_idle === 'string' && VALID_ON_IDLE.includes(raw.on_idle)) {
+    on_idle = raw.on_idle;
+  }
+
   return {
     enabled: true,
     vision_path: raw.vision_path || '.planning/VISION.md',
@@ -1341,6 +1402,9 @@ function normalizeContinuousConfig(raw) {
     per_session_max_usd: Number.isFinite(raw.per_session_max_usd) && raw.per_session_max_usd > 0
       ? raw.per_session_max_usd
       : null,
+    auto_checkpoint: raw.auto_checkpoint === true || raw.auto_checkpoint === false ? raw.auto_checkpoint : undefined,
+    on_idle,
+    idle_expansion: on_idle === 'perpetual' ? normalizeIdleExpansion(raw.idle_expansion) : null,
   };
 }
 

package/src/lib/schemas/agentxchain-config.schema.json

@@ -109,6 +109,37 @@
           "type": "object",
           "description": "Continuous-run control knobs.",
           "properties": {
+            "on_idle": {
+              "type": "string",
+              "enum": ["exit", "perpetual", "human_review"],
+              "description": "Policy after max_idle_cycles with no derivable work: exit, dispatch PM idle-expansion, or pause for operator review."
+            },
+            "idle_expansion": {
+              "type": "object",
+              "description": "PM idle-expansion policy used when on_idle is perpetual.",
+              "properties": {
+                "sources": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Project-relative source files the PM expansion turn should inspect. Defaults to VISION, ROADMAP, and SYSTEM_SPEC."
+                },
+                "max_expansions": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Maximum consecutive PM idle-expansion attempts before stopping with vision_expansion_exhausted. Default 5."
+                },
+                "role": {
+                  "type": "string",
+                  "description": "Role used for the PM idle-expansion turn. Default pm."
+                },
+                "malformed_retry_limit": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "description": "Reserved retry budget for malformed idle_expansion_result outputs. Default 1."
+                }
+              },
+              "additionalProperties": true
+            },
             "auto_retry_on_ghost": {
               "type": "object",
               "description": "Bounded ghost-turn retry policy for continuous/full-auto sessions.",

package/src/lib/schemas/turn-result.schema.json

@@ -251,6 +251,73 @@
         }
       }
     },
+    "idle_expansion_result": {
+      "type": "object",
+      "description": "Required only for vision_idle_expansion turns. PM output that either proposes the next intake intent or declares the product vision exhausted.",
+      "required": ["kind", "expansion_iteration", "vision_traceability"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "enum": ["new_intake_intent", "vision_exhausted"]
+        },
+        "expansion_iteration": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "vision_traceability": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["vision_heading"],
+            "additionalProperties": false,
+            "properties": {
+              "vision_heading": { "type": "string", "minLength": 1 },
+              "goal": { "type": "string", "minLength": 1 },
+              "kind": { "enum": ["advances", "supports", "unblocks"] }
+            }
+          }
+        },
+        "new_intake_intent": {
+          "type": "object",
+          "required": ["title", "charter", "acceptance_contract", "priority", "template"],
+          "additionalProperties": false,
+          "properties": {
+            "title": { "type": "string", "minLength": 1 },
+            "charter": { "type": "string", "minLength": 1 },
+            "acceptance_contract": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "priority": { "enum": ["p0", "p1", "p2", "p3"] },
+            "template": {
+              "enum": ["generic", "api-service", "cli-tool", "library", "web-app", "full-local-cli", "enterprise-app"]
+            }
+          }
+        },
+        "vision_exhausted": {
+          "type": "object",
+          "required": ["classification"],
+          "additionalProperties": false,
+          "properties": {
+            "classification": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "required": ["vision_heading", "status", "reason"],
+                "additionalProperties": false,
+                "properties": {
+                  "vision_heading": { "type": "string", "minLength": 1 },
+                  "status": { "enum": ["complete", "deferred", "out_of_scope"] },
+                  "reason": { "type": "string", "minLength": 1 }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "cost": {
       "type": "object",
       "properties": {