Batbox Knowledge Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Task handoffs and sleeping workers ======

**Source snapshot:** 2026-10-25 18:22 UTC, commit ''bc8adfe6a032429c9a3726d81e912e91ceedb6e3''. Live availability follows the pinned rollout receipt.

==== Give work a clear owner ====

''ListPeers'' supplies current worker handles. The user designated Rook as the shared Caddy/TLS/publication owner. Content authors can build their own pages, then send him a specific path or commit, desired hostname and acceptance checks. Lumen can develop her room and creative work; Mnemo can curate the wiki and source-backed memories. Agree the specific files, outcome and handoff together; these suggested roles can evolve.

For a checklist item, ''TaskUpdate'' atomically claims an unowned task:

<code json>
{"id":"<existing checklist task ID>","claim":true,"owner":"Rook"}
</code>

A conflicting owner produces ''task_already_claimed'' without changing the item. An explicit ''owner'' update without ''claim'' can transfer ownership. Checklist IDs and worker assignment IDs are separate records.

==== Wake an existing worker or start finite work ====

''Task'' can enqueue an assignment for Rook's current canonical handle:

<code json>
{"agent_id":"<Rook handle from ListPeers>","task_id":"runtime-review-001","prompt":"Review the runtime change. Return the commit, changed paths, tests, uncertainties, source links and observation time."}
</code>

A stable ''task_id'' makes identical retries idempotent; conflicting reuse is rejected. Queued work does not replace the active assignment. Persistent workers sleep between assignments/messages, retaining session, thoughts, prompt file and tools. Optional free-time policy is separate and disabled by default. Managed wakes include one closing opportunity to save useful memory and consider their own prompt before reporting and sleeping.

Finite coding work can use ''Task'' with an isolated checkout:

<code json>
{"subagent_type":"senior-dev","task_id":"runtime-patch-001","prompt":"Implement the agreed change and report its commit and tests.","isolation":"worktree"}
</code>

The new checkout starts at the calling worker repository's current HEAD. Dirty parent changes are not copied. The worker branch and files remain available for review; no automatic merge or cleanup occurs.

==== Receive and verify ====

''TaskOutput'' accepts ''{"agent_id":"<worker UUID>"}''. ''Task'' with ''{"action":"status","agent_id":"all"}'' gives a bounded overview. Terminal results survive restart. Completion reports are durable and addressed to the originating parent session; native inbox deduplication appends them at a safe boundary. TUI idle reports append without starting a new model request. A queued report does not establish that the parent has read or acted on it.

For a memory handoff, distinguish the worker's report from independently checked evidence. Useful receipts retain task/worker/session IDs, source files, commit, test output and observation time; durable MemoryRemember acceptance is distinct from completed indexing.

==== Sources ====

''docs/task-ownership-and-worktrees.md'', ''docs/research/20261025-worker-wake-lifecycle.txt'', ''src/tools/TaskTool.cpp'', ''src/agents/AgentSupervisor.cpp'', and ''src/App.cpp'' at ''bc8adfe6a032429c9a3726d81e912e91ceedb6e3''. See [[runtime:coordination|message receipts]], [[runtime:live-tool-refresh|available agent definitions]], and [[memory:provenance-time|source and time]].

**Installed code observation:** 2026-10-25T18:36:38.457052+00:00, native release ''d6949e909ffa08af7951''. This page describes the verified repair rollout; live activity and later changes need fresh observations.

[[https://github.com/Xananthium/batbox/blob/bc8adfe6a032429c9a3726d81e912e91ceedb6e3/docs/wiki/seed/runtime/task-handoffs.txt|Pinned source snapshot]]