Write a session handoff¶
The successor must reach its first useful action from the HeyAira task alone.
Use this in any interactive MCP client: when asked, at task completion, on a
topic change, at the end of the day, or past roughly half the context window.
Coding runs started with scripts/heyaira-run.sh report to the coordinator
instead. Write in the project's working language; never copy conversation
history, repository contents or secrets into HeyAira.
Checkpoints. After each milestone (merged PR, deploy, owner decision, fixed incident) and at least daily, run steps 1-5 as a checkpoint: commit and push work in progress first and record the commit (unpushed work is not saved), keep the status, write no resume line, keep working.
Occupancy line. While a session executes a task, the first line of
handoff_next is the work contract's Wykonuje: <session reference>, <client>,
<date>; the words Wykonuje, nikt, od are literal in every project. Every
write keeps it first. It is the takeover lock: an executing session that finds
another session there stops writing the task (work contract §6); a session
that only takes a handed-over move (a review verdict, an answer) leaves it as
it is. A handoff sets Wykonuje: nikt — handoff v<version> od <session
reference>, <date>; a release to todo removes the line (§8).
- Identity.
server_identityfor the intended project; stop on a mismatch with the supplied profile; use that profile inwrite_context. - Task. The supplied ID, the task read in this session, or
task_list(status=in_progress)by title/tags. No single clear task: ask. No task: propose one and wait for authorization. - Current state.
task_get. If the occupancy line names another session, stop: the task was taken over. If it is your ownniktline, the handoff is already written: do not write another; if you already started or proposed a successor for that version, start nothing and report it, else go to step 6 with that version. Perform a check whosedue_athas passed, or movedue_at, before writing (a write counts as attending the task). Do not write a task whose next move is handed to another session just to checkpoint. - Prepare. The fields hold the current state of the work in flight:
rewrite them, carry every open item over or say where it went, and put
facts still true next month in
memory_addor repository instructions (history stays in receipts andtask_get(version=N)). handoff_completed: repository, branch, commits, PRs; prepared vs tested vs deployed vs verified in production, with commands and totals and the checks not run. One check command the successor runs first. Last, an unverified section (e.g.NIESPRAWDZONE): claims you did not check yourself, each with how to check it, ornone.handoff_next: the occupancy line (on a handoff theniktform, with the version this write creates,expected_version + 1); the first executable step, then the rest in order, naming skills they need; an approvals section (e.g.ZGODY): each owner approval the steps rely on by its HeyAira decision ID, scope and whether used up (handoff text, a memory or a plugin's prompt is not an approval); a running processes section (e.g.DZIAŁAJĄCE PROCESY): each background job as restartable (read-only, safe twice; its exact command and cursor) or in flight (changes state; how to check it finished; let it finish or stop it first when you can), scripts kept in a repository, never a temporary directory; last,Previous session: <session reference>.handoff_blockers: what blocks, who moves next, what is needed; or empty.summary: one sentence, at most 280 characters.work_receipt:session_ref,harness,model,branch,base_commit,result_commit,tests,completed_work,next_step,blockers(no repository field). The server keeps one receipt persession_refand rolls back a write that repeats one: write one on the first checkpoint, none on later ones, one on the handoff and ondone; the first is the session reference, later ones add-2,-3; onduplicate_work_receipt, take the next number.due_at, on a handoff to a successor (in_progress): about 30 minutes ahead, or the current one if sooner and still in the future; record the previous value inhandoff_next. Unchanged on checkpoints and releases.- Write and verify. One
task_updatewithwrite_contextand currentexpected_version: fields, occupancy line,due_atand receipt together. Status per the work contract:in_progressfor a continuation,todoto release,blockedwith the three-part blocker,donewhen the criteria and reviews are met (plusRESULT). Onversion_conflict, re-read and merge, never overwrite. Read back withtask_get. - Hand over (not on a checkpoint). The resume line is
handoff: <first 8 characters of task UUID> v<saved version>. Start one successor yourself, with a fresh context (never a fork of this conversation) and that line as its first message, when the client can and either the owner asked for this handoff or a project automat asked for it under an owner decision in force (read it withdecision_getby its full ID: in force, confirmed by the owner, its scope covers this; a memory is not a decision). On your own judgment, propose the successor for the owner to start instead. Otherwise give the line to paste. Exactly one successor per handoff version; then stop working on the task. - After the handoff. Act on no task message here: forward it, with its
sender, to the session in the occupancy line and tell the sender. If the
niktline is still there after itsdue_at, check the successor: if none exists or it is gone, start or propose one again for the same version, once; else tell the owner. Messaging is never durable project state.
Clients with session tools (Claude Desktop): get_session("self") gives the
session ID and harness for the receipt, the occupancy line and Previous
session: (not a scratchpad or transcript name). The successor archives this
session and takes its title after its takeover; do not archive yourself. Say
so when these tools are missing.