---
name: manage-nelos-tasks
description: Plan multi-stream feature or fix work into dependency-safe waves with subagents or durable Codex tasks and machine-generated next actions.
---

# Manage Nelos Tasks

Planning quality must not depend on the queen's model. One bounded Sol planner
decomposes; the queen judges. Use bundled MCP tools; never use the CLI as fallback. Native kinds:

Before mutations call `nelos_runtime_health`; require `mutationAllowed`, else use `recovery`.
Never live-upgrade Nelos. Quit, install externally, relaunch and open fresh task; task alone leaves workers live.

- A `subagent` is a joined child. Its primary identity is `agentPath`; its
  internal thread ID is verification evidence only. Never call it a spinoff.
- A `spinoff` is a durable Codex task controlled by `threadId`.

## Choose the Planning Path

Only if the user explicitly supplied a complete plan with `schemaVersion`,
`objective`, and bounded `slices`, call `nelos_plan_slices` directly. A queen-authored plan is not user-supplied.

Otherwise call `nelos_plan_lifecycle` with schema version 1, queen task ID,
caller-stable idempotency key, objective, optional bounded context/parallelism,
`receipt: null`, and `launchAuthorization: null`. Spinoffs are cleanup-capable;
use `cleanupIntended: false` only when explicitly requested. Do not first author slices or
classify them in the queen. Execute only its returned action, then
call again with the unchanged request, returned `bootstrapId`, and exact native
receipt. Never substitute an agent path for a task ID.

Reject invalid identity, parent, route, or result-turn evidence. Render maps from top-level `structuredContent`; reserve `structuredContent.protocol.result` for nonvisual handling. Ordinary maps omit archived members.
Only when the user asks for historical web members, call `nelos_execution_map_history` with the exact web and queen IDs; never make full history routine.

## Follow the One Desktop Path

After the fast path or bootstrap, execute only the returned
`nextAction`; do not reconstruct a procedure from memory.

- `native-set-title`: for the queen or durable spinoff, use exact `threadId` and
  `title`; verify, then repeat the returning tool. Joined subagents cannot use it.
- `launch-planner`: follow the bounded path; map exact `forkTurns` to the
  native launcher's `fork_turns` field.
- `verify-route`: call its `tool` with unchanged `arguments`.
- `authorization-required`: run its `authorizationEffect` with registry data and
  confirmed user intent. Replay its exact receipt; never author one.
- `execution-unavailable`: stop; never substitute a launcher or execute locally.
- `launch-wave`: its `executionGate` is authoritative. Dispatch only listed
  members with exact fields. Never omit, substitute, or inherit a decided `nativeTask`.
  `create-thread` makes spinoffs; `spawn-subagent` uses
  `agentTaskName`. Joined subagents support only Sol or Terra; Luna is
  valid only for durable spinoffs. Never bind an agent name as a thread ID.
  For each `orchestration`, call its exact tool/arguments, execute
  `native-create`, and submit the unchanged work unit plus exact task-ID receipt.
  For a subagent, resolve its agent path to the verification-only thread ID.
  Follow title effects; never invent prompts or capabilities.
  Do not launch a later wave until required current results are accepted.
- Before waiting or reading any launched wave, call
  `nelos_launch_verify_batch` once with the launch action's exact
  `verification` identity and every wave receipt. Subagents use agent paths;
  spinoffs use thread IDs, omit unobserved parent claims, and include turn IDs.
  Proceed only when `allVerified` is true; success durably adopts joined
  members and replays legacy adoption.
  Subagent title is `not-applicable`; spinoffs verify `native-thread-title`.
  On mismatch, run `native-set-title` and repeat.
  Bad identity, topology, read, or route evidence blocks the whole batch.
- `native-wait-subagent` and `native-read-subagent-result`: use collaboration
  controls with exact `agentPath`; never use its thread ID for task controls. Never
  submit a mailbox result directly: replay the exact planner launch receipt
  until Nelos returns `native-read-subagent-result`, then use its exact
  `actionId`. Never construct or guess a result action ID. Say only that the
  planner finished and Nelos is verifying its
  terminal turn; expose protocol details only if `attention` persists.
- `native-wait-wave`: route every target independently by `controlSurface`;
  `collaboration` targets are subagents and `codex-task` targets are spinoffs.
  After terminal turns call `nelos_execution_map_refresh` with resolved fields; never trust mailbox status.
- `native-wait` and `native-read`: use Codex task controls for durable task
  targets. For task checks call `nelos_thread_wait`, then
  `nelos_thread_inventory`. Never serially poll a web.
- `attach-native-task-options`: pass `nativeTask` unchanged to the next launch.
- `decide`: only the queen may judge current evidence; call `nelos_queen_decide`
  with schema version 1 and the exact consumed `native-result-read` receipt,
  web/queen IDs, decision, and summary; execute its returned
  `nelos_orchestrate_advance` action. Never reconstruct result provenance.
  Author slices only when explicitly returned unresolved.
- `cleanup-spinoffs`: call its exact `tool` and unchanged `arguments`. The
  snapshotted default `auto` archives eligible spinoffs; `ask` prompts
  once with exact names/IDs, and `keep` preserves. `rememberPolicy:
  true` with `userIntentConfirmed: true` only for an explicit always choice;
  submit receipts until settled. `not-ready` retains unaccepted members but archives
  accepted siblings. On `authorization-required`, run its exact effect and replay
  the same `nelos_spinoff_cleanup` call with its `launchAuthorization`; never route
  that receipt through planning. Durable cleanup makes a restarted
  `nelos_orchestrate_advance` resume the next-wave authorization boundary.
- `orchestration-repair-member`: submit its exact identity as an `orchestration-member-repaired` receipt through `nelos_orchestrate_advance`,
  adding only `resolution: "detach"`; never detach locally.
- `attention`: stop and resolve the named evidence gap; do not infer an action.
  For `missing-persisted-dependency-work-units`, replay exact launch
  verification for named legacy joined members, then retry the transition.
- `complete`: stop; the command has no additional protocol step.

Spinoffs run exact `nelos_spinoff_complete`: start with `receipt: null`, send its
effect through `codex_app.send_message_to_thread`, then pass the exact
`{"threadId":"..."}` result; never add fields or repeat `attention`. After acceptance
follow `cleanup-spinoffs`; never depend on remembering a separate cleanup call.
Never clean up failed, blocked, detached, unaccepted, stale, or archive-incapable work.

Use `nelos_plan_replan` only for a typed terminal failure/block, user
requirements change, or insufficient-confidence event. Supply the base
plan-run identity, plan, affected/completed slices, evidence, and generation 1.
Timeouts, unavailable reads, and successful execution are not replanning
triggers. Completed slices remain unchanged and are never scheduled again; a
second autonomous replan stops.

Unavailable reads and timed-out waits are unknown evidence, not failure. Registry-only
topology has a lifecycle cache; never write lifecycle or archival state from a native
action. Lifecycle reads reconcile their cache on every read; the observation lease is informational.
Never perform a second local lifecycle mutation to mirror a native archive.