manage-nelos-tasks

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 . 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 persists.

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.