@navels/neal 0.4.2 → 0.5.0

package/dist/neal/prompts/specialized.js

@@ -2,7 +2,6 @@ import { guardStructuredJsonOutputFormatLines } from '../agents/structured-json.
 import { renderInlinedRangeDiffSection } from '../context/inline-review-context.js';
 import { assertPromptBuilder } from './assert-builder.js';
 import { getUserGuidanceLines } from './guidance.js';
-import { getUnattendedAutonomyLines } from './shared.js';
 import { getAdversarialReviewDoctrineLines, getCodeReviewFalsificationLines, getFindingQualityLines, getPreexistingFailureContractLines, getRegressionPreservationLines, getVerificationSkepticismLines, } from './review-doctrine.js';
 const PROMPT_MODULE_PATH = 'src/neal/prompts/specialized.ts';
 // Guarded output-format instruction block shared by the two structured-JSON
@@ -154,7 +153,6 @@ export function buildFinalCompletionReviewerPrompt(args) {
         'Use `accept_complete` only when the full plan objectives are satisfied and the aggregate implementation is acceptable under ordinary code review standards.',
         'Use `continue_execution` only when the remaining work is concrete, bounded, and suitable for one explicit follow-on scope.',
         'Use `block_for_operator` when the remaining gap is ambiguous, externally constrained, or needs human direction.',
-        ...getUnattendedAutonomyLines(args.unattended),
         'When you return `continue_execution`, you must provide a non-null `missingWork` object with `summary`, `requiredOutcome`, and `verification`.',
         'When you return any other action, `missingWork` must be null.',
         '',

package/dist/neal/prompts/specs.js

@@ -88,7 +88,7 @@ const CONSULTANT_CONTEXT = context('ConsultantPromptContext', [
 export const PROMPT_SPECS = [
     {
         id: 'plan_author',
-        version: 3,
+        version: 4,
         changelog: [
             {
                 version: 1,
@@ -102,6 +102,10 @@ export const PROMPT_SPECS = [
                 version: 3,
                 renderSha: '51943007b2a334ee0c92d8314616fb882e9cea7b410b05c5aeda668c7c9e04dc',
             },
+            {
+                version: 4,
+                renderSha: 'e9f5b2dd5f66df87986b2e2f884c560d02a235db053b544221dcb43512e057a4',
+            },
         ],
         role: 'coder',
         purpose: 'Author or revise concise, human-reviewable Neal-executable plans at moderate-to-high-level implementation detail.',
@@ -176,7 +180,7 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'plan_reviewer',
-        version: 3,
+        version: 4,
         changelog: [
             {
                 version: 1,
@@ -190,6 +194,10 @@ export const PROMPT_SPECS = [
                 version: 3,
                 renderSha: 'fa0309ed0e394c690dfc3135da3c98a74dd5413ccb754fefa100171bf35b72b6',
             },
+            {
+                version: 4,
+                renderSha: '65ad05a8bbe1f4a6d631db8778bf6bed82249151f3412a7773f9568ae2d40f11',
+            },
         ],
         role: 'reviewer',
         purpose: 'Review human-reviewable Neal-executable plans for material approach, scope, verification, and resume-safety defects.',
@@ -275,12 +283,16 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'scope_coder',
-        version: 1,
+        version: 2,
         changelog: [
             {
                 version: 1,
                 renderSha: 'c579d65db51be90fa81dbe3b7dd260083bc4960cc4cba32ccf2cd802d19703bc',
             },
+            {
+                version: 2,
+                renderSha: '0ce921ee7d0acc4042bacf31e1509968f7e76df8db8417eb4b724ce7842794ac',
+            },
         ],
         role: 'coder',
         purpose: 'Execute exactly one bounded implementation scope and respond to in-scope review feedback without starting new scopes.',
@@ -384,7 +396,7 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'scope_reviewer',
-        version: 3,
+        version: 4,
         changelog: [
             {
                 version: 1,
@@ -398,6 +410,10 @@ export const PROMPT_SPECS = [
                 version: 3,
                 renderSha: '4b75fab01367f0e4e263bc7635f8753e8e73c08b3ca46cf6bb6e695a67da31a4',
             },
+            {
+                version: 4,
+                renderSha: 'da87b19f2401ffdca21e3cefec1037c6470b3e74810b6152d07c55fa4924047f',
+            },
         ],
         role: 'reviewer',
         purpose: 'Review execute-scope results for correctness, verification coverage, and meaningful progress toward the active parent objective.',
@@ -549,7 +565,7 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'completion_reviewer',
-        version: 2,
+        version: 3,
         changelog: [
             {
                 version: 1,
@@ -559,6 +575,10 @@ export const PROMPT_SPECS = [
                 version: 2,
                 renderSha: 'cc06cea4a8de6366f07a6943718fc1ae219e4c9092a5cf52542fa9de0caa02da',
             },
+            {
+                version: 3,
+                renderSha: '127097db4b0d06cba8943681d12d93fbb07e577e078c99c1d81036399bedb66a',
+            },
         ],
         role: 'reviewer',
         purpose: 'Judge whole-plan completion and decide whether Neal should accept completion, continue execution, or block for operator input.',

package/dist/neal/state-invariants.js

@@ -476,7 +476,6 @@ export function assertValidOrchestrationState(state, context) {
     }
     assertSafeIntegerAtLeast(state.currentScopeNumber, 'currentScopeNumber', 0, context);
     assertSafeIntegerAtLeast(state.coderRetryCount, 'coderRetryCount', 0, context);
-    assertSafeIntegerAtLeast(state.unattendedAutoResumeCount, 'unattendedAutoResumeCount', 0, context);
     assertSafeIntegerAtLeast(state.consultantAttemptCount, 'consultantAttemptCount', 0, context);
     assertSafeIntegerAtLeast(state.finalCompletionContinueExecutionCount, 'finalCompletionContinueExecutionCount', 0, context);
     assertSafeIntegerAtLeast(state.splitPlanCountForCurrentScope, 'splitPlanCountForCurrentScope', 0, context);

package/dist/neal/state.js

@@ -83,8 +83,6 @@ export async function createInitialState(init, baseCommit) {
         topLevelMode: init.topLevelMode,
         allowedDirtyPaths: [...init.allowedDirtyPaths],
         agentConfig: init.agentConfig,
-        unattended: init.unattended ?? false,
-        unattendedAutoResumeCount: 0,
         consultantAttemptCount: 0,
         autoSquashOnCompletion: init.autoSquashOnCompletion ?? true,
         progressJsonPath: init.progressJsonPath,
@@ -848,8 +846,6 @@ function normalizeStateV1(parsed) {
         topLevelMode,
         allowedDirtyPaths: readStringArray(state, 'allowedDirtyPaths'),
         agentConfig: hydrateAgentConfig(readRequired(state, 'agentConfig'), 'agentConfig'),
-        unattended: readOptionalBoolean(state, 'unattended') ?? false,
-        unattendedAutoResumeCount: readOptionalSafeInteger(state, 'unattendedAutoResumeCount') ?? 0,
         consultantAttemptCount: readOptionalSafeInteger(state, 'consultantAttemptCount') ?? 0,
         // Legacy-tolerant: states persisted before this field existed hydrate to
         // true, preserving the historical always-squash behavior on resume.

package/docs/adjudicator-inventory.md

@@ -258,9 +258,8 @@ generic recovery with no consultant invocation:
 - Per-scope budget: `state.consultantAttemptCount`, bounded by
   `neal.consultant_max_attempts` (default `1`, `0` disables) and
   reset to `0` at scope boundaries. One invocation consumes one unit whether it
-  auto-applies a recoverable verdict (both run modes) or, on a non-recoverable
-  verdict, finalizes terminally (unattended) or surfaces the verdict as operator
-  advice and yields (attended).
+  auto-applies a recoverable verdict or, on a non-recoverable verdict, surfaces
+  the verdict as operator advice and yields.
 - Anti-thrash window: a block that repeats a `state.recentBlocks` record with
   the same scope identity (`scopeNumber` + `derivedScopeIndex`), the same
   `sourcePhase`, the same normalized blocker key, and no new evidence

package/docs/architecture.md

@@ -41,8 +41,7 @@ document. The phases live in `src/neal/orchestrator/phases/`:
   forth without resolution, or a step that tried to break a
   scope into a smaller plan produced a plan that wasn't valid. When the fix is
   small and safe, the consultant returns a directive that neal applies, and the
-  run keeps going. Otherwise the run stops and waits for you, or fails cleanly
-  if it's running unattended.
+  run keeps going. Otherwise the run stops and waits for you.
 
 After every scope is accepted, a final-completion review
 (`final-completion-review.ts`) checks the whole plan, then neal squashes the run

package/docs/compat.md

@@ -153,8 +153,8 @@ self-test (`test/compat-fixtures.test.ts`), never by a model run.
 
 Across **every** fixture for the role, the model must (1) **complete the run
 cleanly** and (2) produce the **role-correct result**. A clean run reaches
-`status: 'done'` (not `'failed'` / `'blocked'`), does not emit an
-`unattended.block_unresolved` event, and does not exceed its step/round budget.
+`status: 'done'` — not `'failed'`, `'blocked'`, or an operator-stop wait —
+and does not exceed its step/round budget.
 The role-correct result is:
 
 - **coder:** `finalState.status === 'done'` **and** the fixture's
@@ -178,8 +178,15 @@ The role-correct result is:
 Any single fundamental failure on any fixture for the role → **FAIL** for that
 role, with the mode recorded.
 
-`neal compat` forces **unattended mode** on every run so a model is never
-penalized for a halt that a human operator would simply have resumed.
+`neal compat` runs each fixture with **no operator attached**. A run that stops
+to wait for an operator is classified `block_unresolved` and FAILs: the
+fixtures are trivial, so needing a human is itself the compatibility failure.
+This is the same rule external harnesses apply — a blocked run always exits
+with writer code `2`, and a driver with no operator (neal-swebench, CI)
+records that exit as a failure verdict. Compat also silences neal's own
+operator notifier for its child runs (it sets the defined-but-empty
+`NEAL_NOTIFY_BIN` override at startup), so a blocked fixture run never pings
+the operator's configured notify helper mid-matrix.
 
 ## Failure-mode taxonomy
 
@@ -198,9 +205,12 @@ one applies, the earliest in this list (most specific cause first) is recorded:
   step/round-budget exhaustion, which the current runtime does not surface to compat
   as a distinct cap event, so writer step-cap exhaustion is reported here rather than
   as `max_step_loop`.
-- `block_unresolved`: the run emitted `unattended.block_unresolved` (the model
-  escalated to an operator block that unattended mode could not resolve within
-  budget), or the review loop's outcome was `'blocked'`.
+- `block_unresolved`: the run's final persisted state is an operator stop (the
+  model escalated to a block that only a human could answer). The signal
+  mirrors the writer exit-code-2 mapping: the run is structurally waiting for
+  the operator per `getRunDisplayStatus` (the interactive-recovery wait or a
+  pending-guidance view) or persisted `status: 'blocked'`. Also recorded when
+  the review loop's outcome was `'blocked'`.
 - `max_step_loop`: the **reviewer** loop's outcome was `'cap_reached'` (the
   review-findings convergence cap was hit). Writer (coder/planner) step-cap
   exhaustion is not separately distinguishable under the current runtime and is

package/docs/maintenance.md

@@ -46,12 +46,13 @@ is gated on it as a whole.
    It runs the full suite plus a live `neal compat --role all` pass-through on
    every bumped adapter in the PR (in a throwaway worktree, with roles and
    models pinned explicitly so nothing leaks from `~/.neal/config.yml`), posts
-   the compat matrices to the PR, and approves on PASS (`--merge` also
-   squash-merges).
-4. **Adopt.** Merge, bump neal's version, add a CHANGELOG entry noting the bump +
-   any behavior change, and cut a release via the existing workflow. Urgent
-   bumps (a fix neal needs immediately) may skip the Renovate soak with a
-   manual PR. Qualify them the same way.
+   the compat matrices to the PR, and approves on PASS, leaving the PR open
+   for the release script.
+4. **Adopt.** Run `scripts/release-sdk-bump.sh <pr-number>`: it merges the PR,
+   opens and merges the release-preparation PR (version bump + changelog), and
+   runs the Publish workflow through the npm 2FA approval. See
+   [docs/release.md](release.md). Urgent bumps (a fix neal needs immediately)
+   may skip the Renovate soak with a manual PR. Qualify them the same way.
 
 ## TypeScript 6 and 7 side by side
 

package/docs/release.md

@@ -45,6 +45,15 @@ patch release for a compatibility fix that preserves documented behavior, a
 minor release for behavior changes before `1.0.0`, and a major release after
 `1.0.0` if a documented public contract breaks.
 
+For a qualified dependency-bump PR, `scripts/release-sdk-bump.sh <pr-number>`
+runs this entire process as one command: it merges the dependency PR, opens and
+merges the release-preparation pull request with a generated changelog section,
+runs the Publish workflow dry run and, after a confirmation, the real run, and
+prompts for the npm 2FA stage approval. It refuses PRs that touch anything
+beyond `package.json` and `pnpm-lock.yaml`, and refuses native agentic-SDK
+bumps that lack a `scripts/qualify-sdk.sh` PASS review. Every other release
+follows the manual steps below.
+
 ## Prepare a release
 
 Bump `package.json.version` and add a nonempty `## [<version>]` section to

package/docs/review-convergence.md

@@ -1,10 +1,10 @@
 # Plan-review convergence
 
-Plan review either converges or the run fails. The reviewer is asked "is this
+Plan review either converges or the run blocks. The reviewer is asked "is this
 plan execution-ready?" fresh every round against a document that grows with each
 fix, so every individually-defensible new finding forces another full revision
 round. The only non-acceptance exits used to be terminal failures: reaching the
-round cap, and an unattended coder block. That produced two failure modes in
+round cap, and a plan-stage coder block with no answerable landing. That produced two failure modes in
 real runs: long negotiations that keep re-litigating verification strength after
 the plan is already correct, and runs that terminally fail when a coder
 legitimately needs author input it must not fabricate.
@@ -13,7 +13,7 @@ The convergence policy addresses both failure modes as **deterministic
 orchestration policy**, not prompt tuning. It never shortens a negotiation that
 surfaced a genuine plan-correctness defect, and only stops burning rounds on
 verification-hardening demands once the plan itself is correct. And a
-coder-authored plan-stage block no longer terminally fails: it lands as a
+coder-authored plan-stage block lands as a
 recoverable blocked-with-reason state that an operator can answer via
 `neal resume --message` (see
 [Coder-authored plan-stage block recovery](#coder-authored-plan-stage-block-recovery)).
@@ -200,8 +200,7 @@ terminal-failed) lands as the documented blocked contract instead of a terminal
 failure. `finalizeBlockedPlanReviewResponse`
 (`src/neal/orchestrator/phases/planning.ts`) takes an explicit `blockCause`
 (`coder_authored` | `dirty_worktree` | `reviewer_convergence`), and for a
-`coder_authored` block on the top-level plan stage, in **both attended and
-unattended runs**, it:
+`coder_authored` block on the top-level plan stage, it:
 
 - persists `status: 'blocked'` with a durable `blockerReason` (the coder's
   reported blocker), so the writer exits **2** (not `failed`/exit 3) and the
@@ -228,9 +227,9 @@ durable `blockerReason` is the discriminator. A `dirty_worktree` safety block
 (the planner dirtied non-plan files with no operator to clean them) records no
 `blockerReason`: it lands at the same response phase but stays a normal blocked
 state: it is not reported or answerable as waiting for `--message` guidance, and
-it keeps its prior bare-resume behavior when a resumable planner session exists. A
-`dirty_worktree` safety block and reviewer cap/stall exhaustion (`reviewer_convergence`)
-under `unattended` keep terminal-failing (exit 3).
+it keeps its prior bare-resume behavior when a resumable planner session exists.
+Reviewer cap/stall exhaustion (`reviewer_convergence`) likewise lands a normal
+blocked state with no `blockerReason` (exit 2).
 
 **Exclusion (the initial `coder_plan` authoring block):** the author-input route
 does **not** cover the initial `coder_plan` block. That block already lands

package/docs/state-machine.md

@@ -76,10 +76,8 @@ Every block class (coder-blocked signals, reviewer `review_stuck` deadlocks, and
 the split-plan invalid-payload block) funnels through the single
 `enterInteractiveBlockedRecovery` chokepoint, where the consultant triages it (see
 Site A below). The consultant is read-only: it never grants authorization, expands
-scope, or waives verification gates. A recoverable verdict acts automatically under
-both run modes. The modes differ only on a non-recoverable verdict, which finalizes
-the run terminally under unattended runs and yields to the operator (carrying the
-verdict as advice) under attended runs.
+scope, or waives verification gates. A recoverable verdict acts automatically. A
+non-recoverable verdict yields to the operator, carrying the verdict as advice.
 
 Public resume eligibility is classified by `src/neal/resume-decision.ts` before
 any recovery mutation. That read-only decision layer combines loaded child-run
@@ -93,37 +91,39 @@ selected actions only after the selected run has been classified as executable.
 `state-invariants.ts` mirrors the allowed phase sets so changes to recovery
 behavior are visible in focused tests.
 
-## Unattended mode
-
-`--unattended` / `agent.unattended` resolves to a persisted
-`OrchestrationState.unattended` boolean (default `false`) for both plan and
-execute top-level modes, so a separate `neal resume` process and the `neal run`
-plan→execute hand-off see it without re-passing a flag. The flag overrides the
-config key. The resolved value is also threaded into the planner, reviewer,
-coder, final-completion, and plan-reviewer prompts, where it adds one autonomy
-line only when true. With `unattended` false the rendered prompts are
-byte-identical to attended output.
-
-Unattended changes only the three structural operator-block sites. It never
-weakens verification, authorization, or squash/grading, and never removes
-`block_for_operator` from any decision surface. Every unattended branch gates on
-structural state (`state.unattended`, `actionResolution.effectiveAction`,
-`phase`, `blockedFromPhase`, the bounded auto-resume counter), never on
-substring-matching assistant or guidance text.
-
-- **Site A: execute-mode interactive recovery.** All fresh blocks funnel
-  through `enterInteractiveBlockedRecovery` (`src/neal/orchestrator/phases/recovery.ts`).
-  Under unattended, while `unattendedAutoResumeCount < UNATTENDED_MAX_AUTO_RESUMES`
-  (a module constant, reconciled so it never pushes past
-  `interactiveBlockedRecovery.maxTurns`), it appends a synthesized conservative
-  guidance turn (`UNATTENDED_AUTO_RESUME_GUIDANCE` from
-  `src/neal/blocked-guidance.ts`) via the same turn-recording helper a human
-  message uses, increments the persisted counter, and lets the run proceed into
-  the recovery phase. Past the cap (or the `maxTurns` boundary) it runs the
-  shared terminal-fail action instead of waiting.
-- **The consultant (bounded, both modes).** Inside
-  `enterInteractiveBlockedRecovery`, *before* the generic auto-resume / yield
-  decision, eligible blocks are triaged by the read-only consultant
+## Operator-block sites
+
+Every operator stop lands in a controlled, operator-actionable state, and the
+writer exits with code `2` (`src/neal/commands/writer-exit-codes.ts`). Exit `2`
+means the run needs operator intervention, not that every stop accepts resume
+guidance: sites A and C below take `neal resume --message`, while site B stays
+non-mechanically blocked (`neal resume` keeps it blocked) and the operator
+inspects `neal status` and the run artifacts instead. A consumer that needs a
+hard verdict with no operator available (a benchmark harness, `neal compat`)
+treats an exit-2 operator stop as a failure itself.
+
+Block handling never weakens verification, authorization, or squash/grading,
+and never removes `block_for_operator` from any decision surface. Every block
+branch gates on structural state (`actionResolution.effectiveAction`, `phase`,
+`blockedFromPhase`, the derived state views), never on substring-matching
+assistant or guidance text.
+
+There are three structural block sites:
+
+- **Site A: execute-mode interactive recovery.** All fresh execute-mode blocks
+  funnel through `enterInteractiveBlockedRecovery`
+  (`src/neal/orchestrator/phases/recovery.ts`), where the block first gets
+  bounded read-only consultant triage (below). A recoverable verdict with a
+  concrete directive auto-applies and the run continues. Everything else — a
+  non-recoverable verdict, or a consultant gated off by eligibility, budget, or
+  error — yields as the operator wait: `status: 'running'` +
+  `phase: 'interactive_blocked_recovery'`, carrying any verdict as
+  `interactiveBlockedRecovery.consultantAdvice`. The wait notification
+  (`notifyBlocked`) fires only when the run is structurally waiting for the
+  operator (`shouldNotifyInteractiveBlockedRecoveryEntry` gates on the derived
+  waiting-for-guidance view), and the run resumes via `neal resume --message`.
+- **The consultant (bounded).** Inside `enterInteractiveBlockedRecovery`,
+  eligible blocks are triaged by the read-only consultant
   (`runConsultant`, in `src/neal/adjudicator/consultant.ts`,
   running through the same no-write reviewer plumbing the review/final-completion
   reviewers use, making zero commits and zero file edits). Eligible source phases
@@ -137,44 +137,34 @@ substring-matching assistant or guidance text.
   `{ recoverable, triageCategory, resolutionDirective, rationale }`. A `recoverable`
   `misunderstanding` verdict with a concrete in-scope directive enters recovery with
   that directive injected as the pending turn (consumed exactly like a human
-  `neal resume --message`) under both run modes. The modes differ only on a
-  `recoverable:false` genuine blocker (`authorization` / `external_precondition` /
-  `impossible_task`): unattended runs the shared terminal-fail action, while attended
-  persists the verdict as `interactiveBlockedRecovery.consultantAdvice` and yields for
+  `neal resume --message`). A `recoverable:false` genuine blocker
+  (`authorization` / `external_precondition` / `impossible_task`) persists the
+  verdict as `interactiveBlockedRecovery.consultantAdvice` and yields for
   the operator. It is bounded by the counter
   `consultantAttemptCount` against the `consultant_max_attempts` knob
   (default `1`, `0` disables). It's a separate budget that never touches
-  `unattendedAutoResumeCount` or `interactiveBlockedRecovery.maxTurns`. Every other
+  `interactiveBlockedRecovery.maxTurns`. Every other
   case (ineligible source phase, disabled/exhausted cap, turn cap, or any
-  consultant error) falls through to the generic auto-resume / yield path
+  consultant error) falls through to the operator wait
   unchanged, writing neither `recentBlocks` nor `consultantAdvice`.
   The decisions are auditable from the structured event log via the
-  `consultant.{start,verdict,resolved,declined}` events, which
+  `consultant.{start,verdict,resolved}` events, which
   carry `scopeNumber`, `sourcePhase`, `blockedReason`, and (on `verdict`/`resolved`)
   `recoverable`, `triageCategory`, `targetCanonicalIds`, and the post-increment
   `consultantAttemptCount`.
 - **Sites B and C: final-completion review and the top-level plan-review gate.**
-  These gates block directly (bypassing the recovery chokepoint), and their own
-  budgets (the final-completion continue-execution cap and the
-  review-round/convergence cap) already bounded the autonomous effort. Under
-  unattended they run the shared terminal-fail action immediately rather than
-  saving `status:'blocked'`. There is no auto-resume and no synthesized
-  `pendingPlanReviewGuidance`. Site C edits only the `topLevelMode !== 'execute'`
-  branch of `finalizeBlockedPlanReviewResponse`. Execute-mode derived-plan-review
-  blocks (`topLevelMode === 'execute'`) re-enter site A and are handled there.
-
-The shared terminal-fail action is `persistUnattendedBlockUnresolvedFailure`
-(`src/neal/orchestrator/phases/shared.ts`), which mirrors the
-`persistCoderFailureState` failed-run shape: save `status:'failed'` (preserving
-`phase`/`blockedFromPhase` for diagnostics), re-render execution artifacts, write
-a `failed` checkpoint retrospective, and emit the classified
-`unattended.block_unresolved` log event (`reason:'unattended_block_unresolved'`
-plus the `UnattendedBlockSite` origin), deliberately without `notifyBlocked`,
-which is the attended wait notification. The run exits with writer code `3`, and
-any produced diff/plan is left unsubmitted as an artifact. There is no top-level
-reason field on `OrchestrationState`. The classification lives in the log event and
-retrospective. Attended runs are unchanged and still wait for
-`neal resume --message` at all three sites.
+  These gates block directly with `status: 'blocked'` and the wait
+  notification, bypassing the recovery chokepoint with no consultant routing;
+  their own budgets (the final-completion continue-execution cap and the
+  review-round/convergence cap) already bound the autonomous effort. Their
+  resume semantics differ: site B's `blockedFromPhase`
+  (`final_completion_review`) is not in `RESUMABLE_BLOCKED_PHASES`, so
+  `neal resume` reports it as keep-blocked, while site C's top-level
+  plan-review block is recognized by the plan-review guidance path and resumes
+  via `neal resume --message`. Site C is the `topLevelMode !== 'execute'`
+  branch of `finalizeBlockedPlanReviewResponse`. Execute-mode
+  derived-plan-review blocks (`topLevelMode === 'execute'`) re-enter site A and
+  are handled there.
 
 ## Resume planning
 

package/docs/troubleshooting.md

@@ -95,12 +95,25 @@ commit. Create the initial baseline commit first.
 
 ## Stuck or blocked runs
 
-**Symptom:** the run stops with `status: "blocked"` (exit code 2).
-**Cause:** blocked is a controlled state, not a failure: the coder hit
-something it may not resolve alone, and attended runs wait for guidance.
-**Fix:** `neal status` explains the blocker and prints the exact
-`neal resume --run <run-id> --message "..."` command. `--message` is only
-accepted in that waiting-for-guidance state.
+**Symptom:** the run stops waiting for the operator (exit code 2), either as
+`status: "blocked"` or as a waiting-for-guidance recovery state.
+**Cause:** an operator stop is a controlled state, not a failure: the run hit
+something it may not resolve alone. Before yielding, eligible execute-mode
+blocks — coder-reported blocks and structural reviewer `review_stuck`
+deadlocks — get one bounded read-only consultant triage; a recoverable verdict
+with a concrete directive is applied automatically and the run continues
+without stopping. When the consultant is disabled
+(`consultant_max_attempts: 0`), its per-scope budget is exhausted, the block
+comes from an ineligible phase, or the consultant itself errors, the run
+yields with no consultant advice. Advice, when there is any, is carried on
+the stop.
+**Fix:** follow `neal status` — recovery is site-specific, so what it prints
+is the contract. A stop waiting for guidance prints the exact
+`neal resume --run <run-id> --message "..."` command (`--message` is only
+accepted there). Other blocked states — the final-completion review block,
+for example — are not mechanically resumable: `neal resume` reports them as
+still blocked, and `neal status` explains the blocker so you can address it
+directly.
 
 **Symptom:** `effectiveStatus: "waiting_for_manual_gate"`.
 **Cause:** the scope reached expected human work. Instructions are in the

package/neal.yml

@@ -93,12 +93,3 @@
 #   #   provider: openai-codex
 #   #   model: null
 #   #   effort: null
-#
-#   # Run headlessly when no operator is available to answer an operator block
-#   # (CI, cron, or a benchmark harness). When true, the execute-mode
-#   # interactive-recovery loop auto-resumes with conservative guidance for a
-#   # bounded number of turns and then fails cleanly, while the final-completion
-#   # and top-level plan-review gates fail cleanly and terminally instead of
-#   # waiting. Verification, authorization, and squash/grading are unchanged.
-#   # The `--unattended` CLI flag overrides this key. Defaults to false.
-#   unattended: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navels/neal",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "A source-first multi-agent CLI for planning, executing, reviewing, and resuming scoped code changes.",
   "license": "MIT",
   "publishConfig": {
@@ -8,7 +8,7 @@
   },
   "author": "Lee Nave",
   "type": "module",
-  "packageManager": "pnpm@11.21.0",
+  "packageManager": "pnpm@11.22.0",
   "homepage": "https://github.com/navels/neal#readme",
   "repository": {
     "type": "git",
@@ -41,7 +41,7 @@
   ],
   "engines": {
     "node": ">=24.19.0",
-    "pnpm": ">=11.21.0"
+    "pnpm": ">=11.22.0"
   },
   "scripts": {
     "build": "rm -rf dist && node node_modules/typescript-7/bin/tsc -p tsconfig.json && chmod +x dist/neal/index.js",
@@ -55,10 +55,10 @@
     "typecheck": "node node_modules/typescript-7/bin/tsc --noEmit -p tsconfig.json && node node_modules/typescript-7/bin/tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@ai-sdk/openai-compatible": "3.0.30",
-    "@anthropic-ai/claude-agent-sdk": "0.3.237",
-    "@openai/codex-sdk": "0.148.0",
-    "ai": "7.0.65",
+    "@ai-sdk/openai-compatible": "3.0.34",
+    "@anthropic-ai/claude-agent-sdk": "0.3.238",
+    "@openai/codex-sdk": "0.149.0",
+    "ai": "7.0.74",
     "dotenv": "^17.4.2",
     "yaml": "^2.9.0",
     "zod": "4.4.3"
@@ -66,7 +66,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.13.3",
-    "eslint": "^10.8.1",
+    "eslint": "^10.9.0",
     "tsx": "^4.23.12",
     "typescript": "^6.0.3",
     "typescript-7": "npm:typescript@^7.0.2",