Skip to content

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.

  1. Identity and rules. server_identity on the intended project; stop on a mismatch with the supplied profile, never borrow another connection's identity. Then session_start, continuity_context (read-only), the repository instructions and the work contract. Use the profile in every write_context.
  2. Task and version. For handoff: <id-prefix> v<version>, find the one matching task with task_list (in_progress, blocked, then todo) and task_get it. If it is newer than the line, also read that version and report the changes since. Write against the latest version.
  3. 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 of handoff_next is a Wykonuje: naming a session other than the predecessor (any form but Wykonuje: 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 write Wykonuje: <you>, <client>, <date>, przejęte po <that session>, treat the latest checkpoint as the handoff, and compare the branch head with its commit first.
  4. 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_update with expected_version and write_context:
  5. status=in_progress when the task is todo or in_progress; a blocked task keeps blocked until its blocker is checked; a task that still has a historical workflow gets its status set explicitly, which makes the server retire that workflow;
  6. handoff_next: Wykonuje: <session reference>, <client>, <date> in place of a first Wykonuje: line, or before the unchanged text;
  7. handoff_completed: its entire current text plus Taken over by session <session reference> (fields are replaced, not appended);
  8. 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 new due_at. This write is the lock: on version_conflict, re-read; stop as in step 3 if another session's Wykonuje: is now first, else write once more. Read back with task_get, due_at included. Use the client's session ID or a stable label, never an invented ID.
  9. 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.
  10. 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_get by 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.
  11. 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-handoff says.

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 90 in 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 whose due_at passed with no write, prints next_after and 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 repository scripts/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_set with next_actor_override_assignment_id and waiting_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.

Sources