Take over a session¶
Use this in Claude Code, Codex or another interactive MCP client. Coding runs
started with scripts/heyaira-run.sh follow their brief instead. Write in the
project's working language; speak to the owner in theirs.
- Identity and rules.
server_identityon the intended project; stop on a mismatch with the supplied profile, never borrow another connection's identity. Thensession_start,continuity_context(read-only), the repository instructions and the work contract. Use the profile in everywrite_context. - Task and version. For
handoff: <id-prefix> v<version>, find the one matching task withtask_list(in_progress, blocked, then todo) andtask_getit. If it is newer than the line, also read that version and report the changes since. Write against the latest version. - Read just enough. The handoff fields, the latest receipt (the fields
win over an older one) and the decisions or notes they name; check the
named repository, branch and commit with Git (
git status --short --branch), preserving unrelated work. If the first line ofhandoff_nextis aWykonuje:naming a session other than the predecessor (any form butWykonuje: nikt — handoff …), stop: it was taken over; rename and archive nothing. Lock break: replace such a line only on the owner's direction for this task, or when that session is gone: archived, deleted, or unknown to this client's session tools while the line names this same client. An idle session still holds its lock, and a session of another client loses it only by the owner's direction. Then writeWykonuje: <you>, <client>, <date>, przejęte po <that session>, treat the latest checkpoint as the handoff, and compare the branch head with its commit first. - Confirm takeover. Only when the work contract permits taking it over:
a continuation from a handoff (§5's exception), a lock break under step 3
(owner's direction or a session that is gone), or otherwise every §5
condition (ready or named by the owner, no other session, the project's
work-in-progress limit); if not, stop and report. Then one
task_updatewithexpected_versionandwrite_context: status=in_progresswhen the task istodoorin_progress; ablockedtask keepsblockeduntil its blocker is checked; a task that still has a historical workflow gets its status set explicitly, which makes the server retire that workflow;handoff_next:Wykonuje: <session reference>, <client>, <date>in place of a firstWykonuje:line, or before the unchanged text;handoff_completed: its entire current text plusTaken over by session <session reference>(fields are replaced, not appended);due_at: the value the handoff recorded, or cleared; if that time has passed, its check is due now: do it first or set a newdue_at. This write is the lock: onversion_conflict, re-read; stop as in step 3 if another session'sWykonuje:is now first, else write once more. Read back withtask_get,due_atincluded. Use the client's session ID or a stable label, never an invented ID.- Messages in flight. Take over the messages sent after the handoff and tell their senders where the work continues; say so if the client cannot read them. Never store conversation history in HeyAira.
- Check, then re-arm. Run the handoff's check command and check each
unverified item before relying on it; report what does not hold. Approvals
count only as listed: read each with
decision_getby its full ID and check it is in force, the owner's answer and its scope (a memory is not an approval); ask again for the rest. Start each restartable job with its command and cursor. Re-run an in-flight job only when it did not finish, the predecessor no longer runs it, its authorization still covers a re-run and it is safe to repeat from where it stopped; otherwise reconcile its partial effects or report it. - Report and act. The task, its state and the first step, and which
session actions were done or unavailable. Take the first authorized step;
ask only for a required decision. Checkpoint from now on as
write-session-handoffsays.
With session tools (Claude Desktop): read the predecessor's last ~20 events
for messages after the handoff (its ID is Previous session: in
handoff_next, legacy Poprzednia sesja:). Start your own background jobs,
stop its copies, then archive it, only after the takeover and only if it is
not working; then give this session its title, never one an active session
has. Report a missing ID or an active predecessor and leave it alone. Without
these tools the MCP takeover still stands.
While you work¶
- Wait with one command where HeyAira Bridge is installed:
heyaira-bridge work-center tasks --counter unattended --wait --timeout 90in the background (a session other than the coordinator adds--assignment-id <its assignment>). It lists tasks whose handed-over move nobody took for 15 minutes, or whosedue_atpassed with no write, printsnext_afterand exits 0; 3 at the timeout, 4 on a lasting error. Re-arm it after every exit: after 0 act, then re-run with--after <next_after>(the first run has no--after; never a wall-clock time); after 3 the same--after; after 4 read the error, fix or report it. In this repositoryscripts/heyaira-watch-unattended.sh [<after>]does that and returns only on tasks, an unknown exit or 5 errors in a row. No session-local watchers over Bridge files or task lists. - Hand over a move explicitly. For a task without a Bridge workflow that
waits for another session,
task_stage_setwithnext_actor_override_assignment_idandwaiting_reason; a message alone is invisible to the server. The recipient writes its move (a verdict, an answer) keeping the occupancy line, or claims the task; clear the override when the move returns. - Schedule a check in
due_at, not as text, so the server wakes the coordinator if it is missed.