hive-lite 0.2.0 → 0.2.1

package/docs/cli-semantics.md

@@ -193,9 +193,9 @@ Saved handoffs are written under:
 .hive/state/intents/<intent_id>/start-intent.json
 ```
 
-The validator requires `type: hive-lite.start-intent`, `version: 1`, `status: ready_for_hive`, a safe `intent_id`, required Markdown sections, and `Blocking Questions` set to `None`.
+The validator requires `type: hive-lite.start-intent`, `version: 1`, `status: ready_for_hive`, a safe `intent_id`, and the minimal Markdown sections `Original Idea`, `Agreed Direction`, and `User-Confirmed Decisions`. `Blocking Questions` is optional, but if present for a ready handoff it must be `None`.
 It rejects execution-only content such as `Direct Writable`, final file scope, implementation plans, validation plans, files-to-modify sections, and direct instructions that an agent should edit specific files.
-`show --json` includes a derived `findIntent` for `$hive-lite-start-prompt`.
+`show --json` includes a derived `findIntent` for `$hive-lite-start-prompt`; it is target-oriented and derived from `Agreed Direction`.
 The human-readable `intent save` output recommends starting the operator runner with `hive-lite operator run --intent <intent_id>` and also prints the equivalent saved handoff path form.
 
 ## `skills`

package/docs/skills/hive-lite-discovery/SKILL.md

@@ -1,16 +1,18 @@
 ---
 name: hive-lite-discovery
-description: Use this skill when a user has a vague or exploratory product idea that is not ready for Hive Lite start/find yet. It runs a pre-Hive, pre-operator clarification flow, may inspect the repository read-only, asks only blocking product questions, drafts and saves a Start Intent Handoff with `hive-lite intent save`, and stops before code execution, Project Map repair, or operator-run automation.
+description: Use this skill when a user wants to discuss and clarify a product/code requirement before coding. It behaves like a no-code requirements conversation, may inspect the repository read-only to compare the idea with the current project, asks follow-up questions when the requirement is unclear, saves a short Start Intent Handoff with `hive-lite intent save`, and stops before code execution, Project Map repair, or operator-run automation.
 ---
 
 # Hive Lite Discovery
 
 ## Purpose
 
-Turn a vague idea into a durable Start Intent Handoff that is ready for Hive Lite to search.
+Turn a requirements conversation into a durable Start Intent Handoff that is ready for Hive Lite to search.
 
 Discovery makes an idea ready for Hive Lite. Start makes that intent ready for code.
 
+The mental model is simple: the user is saying, "do not write code yet; discuss this requirement with me." If the requirement is unclear, ask natural follow-up questions. If repo context would help, inspect it read-only. When the direction is clear enough, save the agreed result for the next skill.
+
 ## Boundaries
 
 - This skill is pre-Hive and pre-operator.
@@ -18,16 +20,15 @@ Discovery makes an idea ready for Hive Lite. Start makes that intent ready for c
 - Do not run `hive-lite find`, `check`, `validate`, `accept`, `operator run`, or coding-agent execution.
 - Do not produce `Direct Writable`, final file scope, an implementation plan, a validation plan, files to modify, or instructions that an agent should edit specific files.
 - Do not turn vague ideas into coding permission. The handoff is search-ready, not execution-ready.
-- Product decisions belong in `User-Confirmed Decisions` or `Blocking Questions`, not `Unknowns For Hive Lite To Resolve`.
-- `Unknowns For Hive Lite To Resolve` must contain codebase/context unknowns that Hive Lite can answer from Project Map and Context Packet discovery.
+- Keep the handoff plain and short. Do not add sections merely to sound complete.
+- Optional non-goals, acceptance signals, unknowns, or hints are for unusual cases only; omit them by default.
 
 ## Completion Contract
 
 End with exactly one clear outcome:
 
 - `ready_for_hive`: a valid Start Intent Handoff is saved, `intent_id` and artifact paths are reported, and the next terminal `hive-lite operator run --intent ...` command is shown.
-- `needs_user_decision`: one to three blocking product questions are asked; no `ready_for_hive` handoff is saved.
-- `skip_discovery`: the requirement is already clear; provide the exact `$hive-lite-start-prompt` handoff and stop.
+- `needs_user_decision`: one to three product questions are asked because the direction is not clear enough; no `ready_for_hive` handoff is saved.
 - `blocked`: CLI, repo, or artifact validation prevents saving; report the exact blocker and next action.
 
 Do not produce a coding prompt, implementation plan, or file-edit permission as a discovery outcome.
@@ -38,20 +39,21 @@ Gather only enough facts to make the idea ready for Hive Lite search.
 
 Stop searching once these are known:
 
-- the user-approved product direction and non-goals;
+- the user-approved product direction;
 - confirmed product decisions versus open blocking questions;
-- only the minimal repo vocabulary or existing capability hints needed to phrase the handoff;
+- whether the request is best understood as a bug, new capability, behavior change, or replacement of existing behavior;
+- only the minimal repo vocabulary or existing capability hints needed to phrase the direction in project terms;
 - whether the handoff can be saved as `status: ready_for_hive`.
 
 Do not inspect the repo to choose final files, architecture, validation commands, or Direct Writable scope. Those belong to `$hive-lite-start-prompt` and the Context Packet.
 
 ## Workflow
 
-1. Understand the original vague idea and preserve it as provenance.
-2. Inspect the repo read-only only when project vocabulary or feasibility needs clarification. Prefer `rg` and `rg --files`; do not write files during exploration.
-3. Ask only blocking product questions. If product decisions remain unresolved, do not save a `ready_for_hive` handoff.
+1. Understand the user's starting idea and preserve it as provenance.
+2. Inspect the repo read-only only when project vocabulary, current behavior, or the difference between the idea and the current project needs clarification. Prefer `rg` and `rg --files`; do not write files during exploration.
+3. Ask follow-up questions only when the answer affects the product direction. If product decisions remain unresolved, do not save a `ready_for_hive` handoff.
 4. Separate confirmed decisions from ideas that were merely discussed.
-5. Draft a Start Intent Handoff using the required structure below.
+5. Draft a short Start Intent Handoff using the required structure below.
 6. Save it with one of:
 
 ```bash
@@ -59,7 +61,8 @@ hive-lite intent save --from <draft-start-intent.md> --json
 hive-lite intent save --stdin --json
 ```
 
-7. If the CLI reports errors, revise the draft and save again. Treat execution-only content errors as real scope violations, not formatting nits.
+7. If the CLI reports errors, revise the draft only when the error is about this draft's content. Treat execution-only content errors as real scope violations, not formatting nits.
+   - If the CLI reports `MISSING_SECTION` for optional legacy sections such as `Non-Goals`, `Acceptance Signals`, `Unknowns For Hive Lite To Resolve`, `Pre-Hive Observations / Hints`, or `Blocking Questions`, the installed CLI is stale relative to this skill. Do not add those sections just to satisfy the old CLI. Stop and tell the user to update or reinstall Hive Lite CLI, then rerun discovery.
 8. Return the `intent_id`, `start-intent.md` path, and the next terminal command for `hive-lite operator run --intent`.
 
 ## Required Handoff
@@ -90,37 +93,32 @@ created_at: 2026-05-15T00:00:00+08:00
 
 - <Decision actually confirmed by the user.>
 
-## Non-Goals
-
-- <Scope boundary.>
-- Do not commit to exact files, Direct Writable scope, or implementation architecture before Hive Lite context discovery.
-
-## Acceptance Signals
-
-- <User-level signal that the direction would feel complete. This is not a validation plan.>
-
-## Unknowns For Hive Lite To Resolve
-
-- <Codebase/context question, such as where an existing provider abstraction lives.>
+```
 
-## Pre-Hive Observations / Hints
+The sections above are enough for most handoffs. Add optional sections only when they remove real ambiguity:
 
-These are non-authoritative hints from discovery. Hive Lite must verify them through the Project Map and Context Packet.
+- `## Blocking Questions`: use only when the handoff is not ready; for `ready_for_hive`, omit it or set it to `None`.
+- `## Non-Goals`: use only for a user-confirmed scope boundary that would otherwise be easy to misunderstand.
+- `## Pre-Hive Observations / Hints`: use only for non-authoritative repo observations that materially help wording.
+- Avoid `## Acceptance Signals` and `## Unknowns For Hive Lite To Resolve` by default. They easily become noisy pseudo-specs.
 
-- <Optional read-only observation phrased as may/appears/observed/verify.>
+## Target-Only Routing Text
 
-## Blocking Questions
+`Agreed Direction` is used to derive the Hive Lite `findIntent`. Keep it target-only.
 
-None.
-```
+- Put only the capability or behavior that should be searched next.
+- Do not name reference, existing, non-regression, or "do not replace" capabilities in `Agreed Direction`.
+- If the user mentions an existing capability only as context, keep that in `Original Idea`.
+- If an additive/non-replacement boundary is important, phrase it generically in `User-Confirmed Decisions`, such as `This is additive, not a replacement of existing LLM proxy capability`, without naming unrelated providers.
+- Before saving, mentally check whether `Agreed Direction` could match multiple providers, products, modules, or target identities. If yes, rewrite it around the intended target only.
 
 ## Validation Rules
 
-- A `ready_for_hive` handoff must have `Blocking Questions` set to `None`.
-- Use `Acceptance Signals` for user-facing completion signals, not exact validation commands.
+- A `ready_for_hive` handoff must have no unresolved product questions. If `Blocking Questions` exists, it must be `None`.
+- Do not invent non-goals, acceptance criteria, codebase unknowns, or hints just to fill a template.
 - Put possible file paths only in `Pre-Hive Observations / Hints`, and phrase them as non-authoritative hints.
 - If the user asks for implementation planning, explain that `$hive-lite-start-prompt` and the Context Packet define execution boundaries after discovery.
-- If the user already has a clear coding requirement, skip discovery and hand off to `$hive-lite-start-prompt` with the requirement text.
+- If the requirement is already clear, save a short handoff without extra questions. Do not skip to `$hive-lite-start-prompt` unless the user explicitly asks to bypass discovery.
 
 ## Final Output
 

package/docs/skills/hive-lite-start-prompt/SKILL.md

@@ -42,7 +42,7 @@ If the invocation includes `Step result path`, `Artifacts directory`, and `Step-
 - Write copyable artifacts under the provided `Artifacts directory`, then write `step-result.json` to the exact `Step result path`.
 - For `prompt_ready`, write the coding prompt artifact and set `recommended_action` to `copy_coding_prompt`.
 - For `split_required`, write a ready-phase handoff prompt artifact and set `recommended_action` to `start_ready_phase`.
-- For map-maintainer handoffs, use `map_update_required` with `recommended_action: map_update_required`.
+- For map-maintainer handoffs or map repairs that must be committed/stashed before continuing, write `Artifacts directory/map-update-required.md`, use `map_update_required` with `recommended_action: map_update_required`, and set `artifacts.map_update_required_path`.
 - For setup, preflight, validation, or irrecoverable start blockers, use `blocked` with `recommended_action: revise_required`, or `failed` for unexpected tool/runtime failures.
 - After writing the structured result, stop. Do not wait for human input inside the operator-agent session.
 
@@ -179,12 +179,13 @@ hive-lite intent validate <intent_id_or_path> --json
 hive-lite intent show <intent_id_or_path> --json
 ```
 
-Use the JSON output for decisions. Refuse and send the user back to `$hive-lite-discovery` if validation is not valid, `status` is not `ready_for_hive`, or `fields.blockingQuestions` is not `None`.
+Use the JSON output for decisions. Refuse and send the user back to `$hive-lite-discovery` if validation is not valid, `status` is not `ready_for_hive`, or `fields.blockingQuestions` exists and is not `None`.
 
 For a valid handoff:
 
-- Set `originalRequirement` from the Start Intent Handoff title plus `fields.agreedDirection`; keep `fields.originalIdea` as provenance only.
-- Set `findIntent` from `show.findIntent` when present. If unavailable, derive it from `Agreed Direction`, `User-Confirmed Decisions`, `Non-Goals`, `Acceptance Signals`, and `Unknowns For Hive Lite To Resolve`.
+- Set `originalRequirement` from the Start Intent Handoff title, `fields.agreedDirection`, and `fields.userConfirmedDecisions`; keep `fields.originalIdea` as provenance only.
+- Set `findIntent` from `show.findIntent` when present. If unavailable, derive it only from `Agreed Direction`.
+- Treat `User-Confirmed Decisions` as coding-prompt requirement context, not routing text for `hive-lite find`.
 - Treat `Pre-Hive Observations / Hints` as non-authoritative hints only. Hive Lite must verify them through Project Map and Context Packet discovery.
 - Do not add Direct Writable files, final file scope, implementation plan, validation plan, or files to modify from the handoff. Those are execution boundaries produced later by `hive-lite find`.
 - Do not ask new discovery questions inside this skill. If product questions are still unresolved, stop with an explicit `$hive-lite-discovery` handoff.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hive-lite",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Local Project Map + Change Control for coding agents.",
   "keywords": [
     "codex",

package/src/cli.js

@@ -80,8 +80,8 @@ Usage:
   hive-lite intent save --stdin --json
   hive-lite intent validate <intent_id_or_path> --json
   hive-lite intent show <intent_id_or_path> --json
-  hive-lite operator run "<clear requirement>" [--operator-agent-command "..."] [--operator-agent-mode stdin|prompt_file]
-  hive-lite operator run --intent <intent_id_or_path> [--operator-agent-command "..."] [--operator-agent-mode stdin|prompt_file]
+  hive-lite operator run "<clear requirement>" [--operator-agent-command "..."] [--operator-agent-mode stdin|prompt_file] [--operator-agent-timeout-ms 600000]
+  hive-lite operator run --intent <intent_id_or_path> [--operator-agent-command "..."] [--operator-agent-mode stdin|prompt_file] [--operator-agent-timeout-ms 600000]
   hive-lite find "<intent>" [--area <id>] [--max-files 8] [--explain] [--json]
   hive-lite check [changeId] [--context ctx_id] [--json]
   hive-lite validate [changeId] [--cmd "..."] [--profile <id>]
@@ -997,6 +997,7 @@ async function main(argv) {
       intent: parsed.flags.intent || null,
       operatorAgentCommand: parsed.flags.operatorAgentCommand || parsed.flags.agentCommand,
       operatorAgentMode: parsed.flags.operatorAgentMode || parsed.flags.agentMode,
+      operatorAgentTimeoutMs: parsed.flags.operatorAgentTimeoutMs || parsed.flags.agentTimeoutMs,
     }, {
       stdin: process.stdin,
       stdout: process.stdout,

package/src/lib/intent.js

@@ -6,41 +6,47 @@ const { parseYaml } = require('./yaml');
 const SCHEMA_VERSION = 'hive.start_intent.v1';
 const INTENT_ID_PATTERN = /^int_[a-z0-9][a-z0-9_-]*$/;
 
-const REQUIRED_SECTIONS = [
+const INTENT_SECTIONS = [
   {
     key: 'originalIdea',
     title: 'Original Idea',
     aliases: ['original idea'],
+    required: true,
     allowNone: false,
   },
   {
     key: 'agreedDirection',
     title: 'Agreed Direction',
     aliases: ['agreed direction'],
+    required: true,
     allowNone: false,
   },
   {
     key: 'userConfirmedDecisions',
     title: 'User-Confirmed Decisions',
     aliases: ['user confirmed decisions', 'user-confirmed decisions'],
+    required: true,
     allowNone: true,
   },
   {
     key: 'nonGoals',
     title: 'Non-Goals',
     aliases: ['non goals', 'non-goals'],
+    required: false,
     allowNone: false,
   },
   {
     key: 'acceptanceSignals',
     title: 'Acceptance Signals',
     aliases: ['acceptance signals'],
+    required: false,
     allowNone: false,
   },
   {
     key: 'unknownsForHiveLiteToResolve',
     title: 'Unknowns For Hive Lite To Resolve',
     aliases: ['unknowns for hive lite to resolve'],
+    required: false,
     allowNone: false,
   },
   {
@@ -54,18 +60,20 @@ const REQUIRED_SECTIONS = [
       'pre hive hints',
       'pre-hive hints',
     ],
+    required: false,
     allowNone: true,
   },
   {
     key: 'blockingQuestions',
     title: 'Blocking Questions',
     aliases: ['blocking questions'],
+    required: false,
     allowNone: true,
   },
 ];
 
 const SECTION_BY_NORMALIZED = new Map();
-for (const section of REQUIRED_SECTIONS) {
+for (const section of INTENT_SECTIONS) {
   for (const alias of section.aliases) SECTION_BY_NORMALIZED.set(normalizeHeading(alias), section);
 }
 
@@ -286,7 +294,7 @@ function validateSections(parsed, frontmatter, errors, warnings) {
     }
   }
 
-  for (const required of REQUIRED_SECTIONS) {
+  for (const required of INTENT_SECTIONS.filter((section) => section.required)) {
     const section = parsed.sections[required.key];
     if (!section) {
       addError(errors, 'MISSING_SECTION', `Missing required section: ${required.title}.`, { section: required.title });
@@ -307,11 +315,6 @@ function validateSections(parsed, frontmatter, errors, warnings) {
   const unknowns = parsed.sections.unknownsForHiveLiteToResolve;
   if (unknowns) {
     const items = contentItems(unknowns);
-    if (items.length === 0) {
-      addError(errors, 'EMPTY_CODEBASE_UNKNOWNS', 'Unknowns For Hive Lite To Resolve must list codebase/context unknowns.', {
-        section: 'Unknowns For Hive Lite To Resolve',
-      });
-    }
     for (const item of items) {
       if (PRODUCT_DECISION_PATTERN.test(item)) {
         addError(errors, 'PRODUCT_DECISION_IN_UNKNOWNS', 'Product decisions belong in User-Confirmed Decisions or Blocking Questions, not Unknowns For Hive Lite To Resolve.', {
@@ -367,10 +370,6 @@ function validateExecutionContent(markdown, parsed, errors, warnings) {
 function deriveFindIntent(fields) {
   const parts = [
     ['Agreed Direction', fields.agreedDirection],
-    ['User-Confirmed Decisions', fields.userConfirmedDecisions],
-    ['Non-Goals', fields.nonGoals],
-    ['Acceptance Signals', fields.acceptanceSignals],
-    ['Codebase Unknowns For Hive Lite To Resolve', fields.unknownsForHiveLiteToResolve],
   ].filter(([, value]) => value && !isNone(value));
 
   return parts.map(([label, value]) => `${label}:\n${value}`).join('\n\n');
@@ -380,7 +379,7 @@ function parseStartIntentMarkdown(markdown) {
   const front = parseFrontmatter(markdown);
   const parsed = parseMarkdownSections(front.body);
   const fields = {};
-  for (const section of REQUIRED_SECTIONS) {
+  for (const section of INTENT_SECTIONS) {
     fields[section.key] = parsed.sections[section.key] ? parsed.sections[section.key].content : '';
   }
 

package/src/lib/operator.js

@@ -49,8 +49,11 @@ const ARTIFACT_FILENAMES = {
   review_packet_path: 'review-packet.md',
   handoff_prompt_path: 'handoff-prompt.md',
   start_intent_path: 'start-intent.md',
+  map_update_required_path: 'map-update-required.md',
 };
 
+const DEFAULT_AGENT_TIMEOUT_MS = 10 * 60 * 1000;
+
 function rel(root, file) {
   return path.relative(root, file).replace(/\\/g, '/');
 }
@@ -99,6 +102,19 @@ function splitCommand(commandText) {
   return parts;
 }
 
+function parsePositiveInteger(value, label) {
+  if (value === undefined || value === null || value === '') return null;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${label} must be a non-negative integer number of milliseconds.`);
+  }
+  return parsed;
+}
+
+function firstConfigured(values) {
+  return values.find((value) => value !== undefined && value !== null && value !== '');
+}
+
 function resolveAgentConfig(options = {}, env = process.env) {
   const commandText = options.operatorAgentCommand
     || options.agentCommand
@@ -120,11 +136,25 @@ function resolveAgentConfig(options = {}, env = process.env) {
   if (!['stdin', 'prompt_file'].includes(mode)) {
     throw new Error(`Unsupported operator agent mode: ${mode}. Use stdin or prompt_file.`);
   }
+  const commandName = path.basename(argv[0]);
+  if (mode === 'stdin' && commandName === 'codex' && !argv.slice(1).some((arg) => arg === 'exec' || arg === 'e')) {
+    throw new Error('Codex interactive CLI requires a terminal when stdin is piped. Use HIVE_LITE_OPERATOR_AGENT_COMMAND="codex -a never -s workspace-write exec" with HIVE_LITE_OPERATOR_AGENT_MODE="stdin", or pass --operator-agent-command "codex -a never -s workspace-write exec".');
+  }
+  const timeoutMs = parsePositiveInteger(
+    firstConfigured([
+      options.operatorAgentTimeoutMs,
+      options.agentTimeoutMs,
+      env.HIVE_LITE_OPERATOR_AGENT_TIMEOUT_MS,
+      env.HIVE_OPERATOR_AGENT_TIMEOUT_MS,
+    ]),
+    'operator agent timeout',
+  ) ?? DEFAULT_AGENT_TIMEOUT_MS;
   return {
     commandText,
     command: argv[0],
     args: argv.slice(1),
     mode,
+    timeoutMs,
   };
 }
 
@@ -305,6 +335,26 @@ function baseInvocation(run, paths, skill, body) {
     '- accepted',
     '- done',
     '',
+    'Required result shapes:',
+    '- For `map_update_required`, write a human-readable artifact first, then write `step-result.json` like:',
+    '```json',
+    JSON.stringify({
+      schema_version: STEP_RESULT_SCHEMA_VERSION,
+      skill,
+      status: 'map_update_required',
+      recommended_action: 'map_update_required',
+      artifacts: {
+        map_update_required_path: rel(run.root, path.join(paths.artifactsDir, 'map-update-required.md')),
+      },
+      map_update: {
+        changed_files: ['.hive/map/areas.yaml'],
+        reason: 'Project Map changed and must be committed or stashed before continuing.',
+      },
+    }, null, 2),
+    '```',
+    '- For `blocked`, write `recommended_action: revise_required` and include `blockers` with concrete next steps.',
+    '- For `failed`, use only unexpected tool/runtime failures that prevent a normal structured result.',
+    '',
     'Artifact paths in step-result.json must be under .hive/state/operator/.',
     '',
   ].join('\n');
@@ -506,6 +556,20 @@ function runSubprocess(command, args, options) {
     const stdout = fs.createWriteStream(options.stdoutPath);
     const stderr = fs.createWriteStream(options.stderrPath);
     let spawnError = null;
+    let timedOut = false;
+    let killTimer = null;
+    const timeoutMs = Number.isInteger(options.timeoutMs) ? options.timeoutMs : DEFAULT_AGENT_TIMEOUT_MS;
+    const timeoutTimer = timeoutMs > 0
+      ? setTimeout(() => {
+        timedOut = true;
+        child.kill('SIGTERM');
+        killTimer = setTimeout(() => {
+          child.kill('SIGKILL');
+        }, Math.min(2000, timeoutMs));
+        if (killTimer.unref) killTimer.unref();
+      }, timeoutMs)
+      : null;
+    if (timeoutTimer && timeoutTimer.unref) timeoutTimer.unref();
     child.on('error', (error) => {
       spawnError = error;
     });
@@ -517,9 +581,11 @@ function runSubprocess(command, args, options) {
       child.stdin.end();
     }
     child.on('close', (code, signal) => {
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (killTimer) clearTimeout(killTimer);
       stdout.end();
       stderr.end();
-      resolve({ code, signal, error: spawnError });
+      resolve({ code, signal, error: spawnError, timedOut, timeoutMs });
     });
   });
 }
@@ -545,6 +611,7 @@ async function runAgentStep(run, baseStep, skill, input, agentConfig, io) {
   }
 
   io.stdout.write('[OK] agent session started\n');
+  io.stdout.write(`[..] waiting for structured result (logs: ${rel(run.root, paths.stdoutPath)}, ${rel(run.root, paths.stderrPath)})\n`);
   const before = statusSnapshot(run.root);
   const proc = await runSubprocess(agentConfig.command, args, {
     cwd: run.root,
@@ -554,8 +621,8 @@ async function runAgentStep(run, baseStep, skill, input, agentConfig, io) {
     resultPath: paths.resultPath,
     artifactsDir: paths.artifactsDir,
     runId: run.id,
+    timeoutMs: agentConfig.timeoutMs,
   });
-  io.stdout.write('[..] waiting for result\n');
 
   const after = statusSnapshot(run.root);
   validateSkillAuthority(run.root, skill, before, after);
@@ -563,6 +630,9 @@ async function runAgentStep(run, baseStep, skill, input, agentConfig, io) {
   if (proc.error) {
     throw new Error(`Operator agent failed to start: ${proc.error.message}`);
   }
+  if (proc.timedOut) {
+    throw new Error(`Operator agent timed out after ${proc.timeoutMs}ms before completing the step. Transcript logs: ${rel(run.root, paths.stdoutPath)}, ${rel(run.root, paths.stderrPath)}. Expected result: ${rel(run.root, paths.resultPath)}`);
+  }
   if (proc.code !== 0) {
     throw new Error(`Operator agent exited with code ${proc.code}. Transcript logs: ${rel(run.root, paths.stdoutPath)}, ${rel(run.root, paths.stderrPath)}`);
   }
@@ -597,7 +667,7 @@ function validateArtifactHashes(root, result, pathFields) {
 
 function validateAndLoadStepResult(run, paths, expectedSkill) {
   if (!exists(paths.resultPath)) {
-    throw new Error(`Operator step failed: missing step-result.json at ${rel(run.root, paths.resultPath)}`);
+    throw new Error(`Operator step failed: missing step-result.json at ${rel(run.root, paths.resultPath)}. Transcript logs: ${rel(run.root, paths.stdoutPath)}, ${rel(run.root, paths.stderrPath)}`);
   }
   let result;
   try {
@@ -668,6 +738,10 @@ function validateRequiredArtifacts(result) {
       throw new Error('Operator step failed: split_required requires split.ready_phase.handoff_prompt_path');
     }
   }
+  if (result.status === 'map_update_required') {
+    const mapUpdatePath = result.artifacts && result.artifacts.map_update_required_path;
+    if (!mapUpdatePath) throw new Error('Operator step failed: map_update_required requires artifacts.map_update_required_path');
+  }
 }
 
 function syncCurrentArtifacts(root, result, resultPath) {
@@ -947,8 +1021,11 @@ async function renderBlocked(run, result, agentConfig, input, io) {
   return runAgentStep(run, 'finish', SKILLS.finish, {}, agentConfig, io);
 }
 
-async function renderMapUpdateRequired(result, input, io) {
+async function renderMapUpdateRequired(run, result, input, io) {
   io.stdout.write('\nMap Update Required\n\n');
+  const details = displayArtifact(run.root, result, 'map_update_required_path');
+  io.stdout.write('Details\n');
+  io.stdout.write(`  ${details}\n\n`);
   const changed = result.map_update && Array.isArray(result.map_update.changed_files)
     ? result.map_update.changed_files
     : [];
@@ -960,10 +1037,22 @@ async function renderMapUpdateRequired(result, input, io) {
   io.stdout.write('Reason\n');
   io.stdout.write('  Project Map was updated while preparing this requirement.\n');
   io.stdout.write('  Commit or stash the map update before generating the coding prompt.\n\n');
-  io.stdout.write('Actions\n');
-  io.stdout.write('  [q] Quit\n');
-  await input.ask('> ', 'q');
-  return null;
+  for (;;) {
+    io.stdout.write('Actions\n');
+    io.stdout.write('  [o] Open details\n');
+    io.stdout.write('  [q] Quit\n');
+    const choice = (await input.ask('> ', 'q')).trim().toLowerCase();
+    if (choice === 'o') {
+      const file = artifactPath(run.root, result, 'map_update_required_path');
+      const text = readText(file);
+      io.stdout.write('\n');
+      io.stdout.write(text);
+      if (!text.endsWith('\n')) io.stdout.write('\n');
+      io.stdout.write('\n');
+      continue;
+    }
+    return null;
+  }
 }
 
 async function handleStepResult(run, result, agentConfig, input, io) {
@@ -984,7 +1073,7 @@ async function handleStepResult(run, result, agentConfig, input, io) {
     } else if (current.status === 'blocked' || current.recommended_action === 'revise_required') {
       current = await renderBlocked(run, current, agentConfig, input, io);
     } else if (current.status === 'map_update_required') {
-      current = await renderMapUpdateRequired(current, input, io);
+      current = await renderMapUpdateRequired(run, current, input, io);
     } else if (current.status === 'accepted' || current.status === 'done') {
       io.stdout.write('\nOperator step complete.\n');
       current = null;