chainlesschain 0.166.2 → 0.166.4

package/src/lib/agent-team/team-runner.js

@@ -16,10 +16,52 @@
 
 import { emitHooksV2Event } from "../hooks-v2-producers.js";
 
+const HANDOFF_REGISTRY_METHODS = Object.freeze([
+  "offerHandoff",
+  "findHandoff",
+  "acceptHandoff",
+  "rejectHandoff",
+  "commitHandoff",
+  "revokeHandoff",
+  "expireHandoffs",
+  "pendingCommittedHandoffs",
+  "refreshCommittedHandoffLease",
+  "markHandoffStarted",
+]);
+
+function supportsCustodyHandoffs(registry) {
+  return HANDOFF_REGISTRY_METHODS.every(
+    (method) => typeof registry?.[method] === "function",
+  );
+}
+
 function leaseFencingToken(lease) {
   return lease?.fencingToken ?? lease?.leaseId ?? null;
 }
 
+const FOLLOWUP_WAKE_PROMPT = [
+  "A teammate explicitly requested a follow-up turn for this existing team session.",
+  "Process the pending teammate mailbox messages shown below or available through team_receive.",
+  "Use team_ack only after durable processing, and keep all message content within the original task authority, budget, and workspace contract.",
+].join(" ");
+
+function taskStatus(task) {
+  return String(task?.status || "").toLowerCase();
+}
+
+function followupMetadata(task) {
+  const value = task?.metadata?.teamFollowup;
+  return value && typeof value === "object" ? value : null;
+}
+
+function custodyRecipient(task) {
+  const history = task?.metadata?.custodyHandoffs;
+  if (!Array.isArray(history)) return null;
+  return [...history]
+    .reverse()
+    .find((handoff) => handoff?.status === "committed")?.toHolder;
+}
+
 export class TeamRunner {
   /**
    * @param {TaskLeaseRegistry} registry
@@ -33,6 +75,11 @@ export class TeamRunner {
    */
   constructor(registry, opts = {}) {
     this.registry = registry;
+    // TeamRunner is also driven through older/durable registry adapters such
+    // as TeamDistributedQueue. Custody handoff is an optional registry
+    // capability: do not make ordinary scheduling depend on methods an adapter
+    // has not implemented; child calls on that adapter fail closed.
+    this.handoffEnabled = supportsCustodyHandoffs(registry);
     this.runTask = opts.runTask;
     this.teammates = opts.teammates > 0 ? Math.floor(opts.teammates) : 2;
     this.ttlMs = opts.ttlMs;
@@ -84,6 +131,31 @@ export class TeamRunner {
     // it. Ordinary renewals keep the same identity and do not call this hook.
     this.onLeaseChanged =
       typeof opts.onLeaseChanged === "function" ? opts.onLeaseChanged : null;
+    // An explicit follow-up to an idle teammate is materialized as a bounded,
+    // high-priority system task. It receives its own task lease/fence but
+    // resumes the recipient's prior agent session. The mutation hook persists
+    // the new task immediately so a coordinator crash cannot lose the wake.
+    this.onFollowupMutation =
+      typeof opts.onFollowupMutation === "function"
+        ? opts.onFollowupMutation
+        : null;
+    this.onHandoffMutation =
+      typeof opts.onHandoffMutation === "function"
+        ? opts.onHandoffMutation
+        : null;
+    this.graphRevisionDigest = opts.graphRevisionDigest || null;
+    this.graphAuthorityDigest = opts.graphAuthorityDigest || null;
+    this.maxFollowupWakes =
+      Number.isSafeInteger(opts.maxFollowupWakes) && opts.maxFollowupWakes > 0
+        ? opts.maxFollowupWakes
+        : 3;
+    this.maxFollowupTasks =
+      Number.isSafeInteger(opts.maxFollowupTasks) && opts.maxFollowupTasks > 0
+        ? opts.maxFollowupTasks
+        : Math.min(this.maxTasks, 1000);
+    this._followupTasks = this.registry
+      .list()
+      .filter((task) => followupMetadata(task)).length;
     this._executions = 0;
     this._reservedExecutions = 0;
     this._inFlight = 0;
@@ -93,6 +165,7 @@ export class TeamRunner {
     // same process must not steal and double-run that still-active task.
     this._activeKeys = new Set();
     this._members = new Map(); // holder → lifecycle record
+    this._residentHolders = new Set();
     this._budgetStopped = false;
     this._registryBudgetReason = null;
     this._fatalError = null;
@@ -103,6 +176,8 @@ export class TeamRunner {
     this._workerCount = 1;
     this._claimControllers = new Set();
     this._claimsByKey = new Map();
+    this._handoffTransfers = new Map();
+    this._handoffExpiryTimers = new Map();
     this._wallTimer = null;
   }
 
@@ -127,16 +202,32 @@ export class TeamRunner {
     }
     if (state === "completed-task") {
       m.completed += 1;
+      if (extra.key) m.lastTaskKey = extra.key;
+      if (extra.sessionTaskKey) m.sessionTaskKey = extra.sessionTaskKey;
+      m.currentTaskKey = null;
       return m;
     }
     if (state === "failed-task") {
       m.failed += 1;
       m.lastError = extra.error || null;
+      if (extra.key) m.lastTaskKey = extra.key;
+      if (extra.sessionTaskKey) m.sessionTaskKey = extra.sessionTaskKey;
+      m.currentTaskKey = null;
       return m;
     }
     if (m.state === state) return m; // no transition
     const previousState = m.state;
+    // Durable message adapters bind online/offline admission to the same member
+    // lifecycle used by the scheduler. A running target releases held sequence;
+    // idle/shutdown targets retain it without reporting false delivery.
+    this.mailbox?.setRecipientState?.(holder, state);
     m.state = state;
+    if (state === "running") {
+      m.currentTaskKey = extra.key || null;
+      if (extra.sessionTaskKey) m.sessionTaskKey = extra.sessionTaskKey;
+    } else if (state === "idle" || state === "shutdown") {
+      m.currentTaskKey = null;
+    }
     this._emit("teammate:state", { holder, state, ...extra });
     // Initial registration starts in `idle`; the hook is reserved for a real
     // transition back to idle after a teammate has participated in the run.
@@ -170,6 +261,806 @@ export class TeamRunner {
     }
   }
 
+  _sessionTaskKey(key, task = this.registry.getTask(key)) {
+    return followupMetadata(task)?.sessionTaskKey || key;
+  }
+
+  _followupTasksFor(recipient, messageId) {
+    return this.registry
+      .list()
+      .filter((task) => {
+        const metadata = followupMetadata(task);
+        return (
+          metadata?.recipient === recipient && metadata.messageId === messageId
+        );
+      })
+      .sort(
+        (left, right) =>
+          (followupMetadata(left)?.wakeAttempt || 0) -
+          (followupMetadata(right)?.wakeAttempt || 0),
+      );
+  }
+
+  _terminalMessageReceipt(recipient, messageId) {
+    const receipt = this.mailbox
+      ?.snapshot?.()
+      ?.receipts?.map((entry) => entry?.[1])
+      ?.find(
+        (candidate) =>
+          candidate?.recipient === recipient &&
+          candidate?.messageId === messageId,
+      );
+    return ["processed", "dead_letter"].includes(receipt?.status)
+      ? receipt
+      : null;
+  }
+
+  _persistFollowupMutation(event) {
+    if (!this.onFollowupMutation) return;
+    try {
+      this.onFollowupMutation(event);
+    } catch (error) {
+      const failure =
+        error instanceof Error
+          ? error
+          : new Error(String(error || "follow-up persistence failed"));
+      failure.code ||= "TEAM_FOLLOWUP_PERSIST_FAILED";
+      this.abortRun(failure, { requireAdjudication: true });
+      throw failure;
+    }
+  }
+
+  _deadLetterExhaustedFollowup(recipient, message) {
+    const receipts = this.mailbox.acknowledge(recipient, {
+      messageIds: [message.id],
+      consumerKey: `team-followup-wake:${message.id}`,
+      status: "dead_letter",
+      reason: "followup_wake_attempts_exhausted",
+      recipientAttempt: {
+        holder: recipient,
+        taskKey: null,
+        attempt: this.maxFollowupWakes,
+        leaseId: null,
+        fencingToken: null,
+      },
+    });
+    this._emit("followup:dead-lettered", {
+      holder: recipient,
+      messageId: message.id,
+      reason: "followup_wake_attempts_exhausted",
+    });
+    this._persistFollowupMutation({
+      type: "followup:dead-lettered",
+      holder: recipient,
+      messageId: message.id,
+    });
+    return {
+      recipient,
+      wake: "dead_lettered",
+      messageId: message.id,
+      receipt: receipts[0],
+    };
+  }
+
+  _requestRecipientFollowupWake(recipient, message) {
+    const terminal = this._terminalMessageReceipt(recipient, message.id);
+    if (terminal) {
+      return {
+        recipient,
+        wake:
+          terminal.status === "processed"
+            ? "already_processed"
+            : "dead_lettered",
+        messageId: message.id,
+      };
+    }
+    const member = this._members.get(recipient);
+    if (member?.state === "running") {
+      return { recipient, wake: "target_active", messageId: message.id };
+    }
+    if (!this._residentHolders.has(recipient)) {
+      return {
+        recipient,
+        wake: "queued_until_target_turn",
+        messageId: message.id,
+      };
+    }
+    const sessionTaskKey = member?.sessionTaskKey || null;
+    const sourceTask = sessionTaskKey
+      ? this.registry.getTask(sessionTaskKey)
+      : null;
+    if (!sourceTask || taskStatus(sourceTask) !== "completed") {
+      return {
+        recipient,
+        wake: "queued_until_target_turn",
+        messageId: message.id,
+      };
+    }
+    const existing = this._followupTasksFor(recipient, message.id);
+    const unsettled = existing.find((task) =>
+      ["pending", "in_progress"].includes(taskStatus(task)),
+    );
+    if (unsettled) {
+      return {
+        recipient,
+        wake: "turn_scheduled",
+        messageId: message.id,
+        taskKey: unsettled.key,
+        idempotent: true,
+      };
+    }
+    if (existing.length >= this.maxFollowupWakes) {
+      return this._deadLetterExhaustedFollowup(recipient, message);
+    }
+    if (this._followupTasks >= this.maxFollowupTasks) {
+      const error = new Error("Team follow-up wake task capacity exceeded");
+      error.code = "TEAM_FOLLOWUP_WAKE_CAPACITY";
+      throw error;
+    }
+    const completedWake = [...existing]
+      .reverse()
+      .find((task) => taskStatus(task) === "completed");
+    const dependencyKey = completedWake?.key || sessionTaskKey;
+    const wakeAttempt = existing.length + 1;
+    const key = `team_followup:${message.id}:${recipient}:${wakeAttempt}`.slice(
+      0,
+      256,
+    );
+    const sourceMetadata = sourceTask.metadata || {};
+    const added = this.registry.addTask({
+      key,
+      title: `Follow up message ${message.id} for ${recipient}`,
+      dependsOn: [dependencyKey],
+      priority: "high",
+      createdBy: message.from || "coordinator",
+      metadata: {
+        prompt: FOLLOWUP_WAKE_PROMPT,
+        ...(Array.isArray(sourceMetadata.scopePaths)
+          ? { scopePaths: [...sourceMetadata.scopePaths] }
+          : {}),
+        ...(sourceMetadata.agent ? { agent: sourceMetadata.agent } : {}),
+        ...(sourceMetadata.policy ? { policy: sourceMetadata.policy } : {}),
+        retrySafe: sourceMetadata.retrySafe === true,
+        teamFollowup: {
+          messageId: message.id,
+          recipient,
+          sender: message.from || null,
+          sessionTaskKey,
+          dependencyTaskKey: dependencyKey,
+          wakeAttempt,
+        },
+      },
+    });
+    if (!added.ok) {
+      const duplicate = this.registry.getTask(key);
+      if (duplicate && followupMetadata(duplicate)?.messageId === message.id) {
+        return {
+          recipient,
+          wake: "turn_scheduled",
+          messageId: message.id,
+          taskKey: key,
+          idempotent: true,
+        };
+      }
+      const error = new Error(
+        `Could not schedule follow-up wake for ${recipient}: ${added.reason}`,
+      );
+      error.code = "TEAM_FOLLOWUP_WAKE_REJECTED";
+      throw error;
+    }
+    this._followupTasks += 1;
+    this._emit("followup:wake-scheduled", {
+      holder: recipient,
+      messageId: message.id,
+      key,
+      sessionTaskKey,
+      wakeAttempt,
+    });
+    this._persistFollowupMutation({
+      type: "followup:wake-scheduled",
+      holder: recipient,
+      messageId: message.id,
+      key,
+      sessionTaskKey,
+      wakeAttempt,
+    });
+    this._signalProgress();
+    return {
+      recipient,
+      wake: "turn_scheduled",
+      messageId: message.id,
+      taskKey: key,
+      wakeAttempt,
+    };
+  }
+
+  /**
+   * Materialize an explicit follow-up as a real lease-bound turn when the
+   * target has an idle resumable session. Active targets keep using their live
+   * bridge; recipients without a prior session retain the durable message for
+   * their first ordinary turn.
+   */
+  requestFollowupWake({ to, message, senderAttempt = null } = {}) {
+    if (
+      !this.realtimeMessaging ||
+      !this.mailbox ||
+      message?.mode !== "followup"
+    ) {
+      return { wake: "queued_until_target_turn", recipients: [] };
+    }
+    const sender = senderAttempt?.holder || message?.from || null;
+    if (to === "coordinator") {
+      return { wake: "queued_for_coordinator", recipients: [] };
+    }
+    const recipients =
+      to === "*"
+        ? (this.mailbox.status?.().recipients || []).filter(
+            (recipient) => recipient !== sender,
+          )
+        : [to];
+    const results = recipients.map((recipient) =>
+      this._requestRecipientFollowupWake(recipient, message),
+    );
+    const wakes = results.map((result) => result.wake);
+    const wake = wakes.includes("turn_scheduled")
+      ? "turn_scheduled"
+      : wakes.includes("target_active")
+        ? "target_active"
+        : wakes.includes("queued_until_target_turn")
+          ? "queued_until_target_turn"
+          : wakes.includes("dead_lettered")
+            ? "dead_lettered"
+            : wakes[0] || "queued_until_target_turn";
+    return { wake, recipients: results };
+  }
+
+  _reconcileFollowupWakes(recipient = null) {
+    if (!this.realtimeMessaging || !this.mailbox) return 0;
+    const recipients = recipient ? [recipient] : [...this._residentHolders];
+    let scheduled = 0;
+    for (const holder of recipients) {
+      for (const message of this.mailbox.peek(holder)) {
+        if (message.mode !== "followup") continue;
+        const outcome = this._requestRecipientFollowupWake(holder, message);
+        if (outcome.wake === "turn_scheduled" && !outcome.idempotent) {
+          scheduled += 1;
+        }
+      }
+    }
+    return scheduled;
+  }
+
+  _persistHandoffMutation(event) {
+    if (!this.onHandoffMutation) return;
+    try {
+      const result = this.onHandoffMutation(event);
+      if (result && typeof result.then === "function") {
+        Promise.resolve(result).catch(() => {});
+        throw new Error("onHandoffMutation must be synchronous");
+      }
+    } catch (error) {
+      const failure =
+        error instanceof Error
+          ? error
+          : new Error(String(error || "handoff persistence failed"));
+      failure.code ||= "TEAM_HANDOFF_PERSIST_FAILED";
+      this.abortRun(failure, { requireAdjudication: true });
+      throw failure;
+    }
+  }
+
+  _handoffMessage(to, handoff, kind, senderAttempt, reason = null) {
+    if (!this.mailbox) return null;
+    const message = this.mailbox.send({
+      from: senderAttempt?.holder || "coordinator",
+      to,
+      subject: `Task custody handoff ${kind}`,
+      body: {
+        kind: `team_handoff_${kind}`,
+        handoffId: handoff.id,
+        taskKey: handoff.taskKey,
+        from: handoff.fromHolder,
+        to: handoff.toHolder,
+        status: handoff.status,
+        ...(reason ? { reason } : {}),
+      },
+      mode: kind === "offered" ? "followup" : "send",
+      idempotencyKey: `team-handoff:${handoff.id}:${kind}`,
+      causationId: handoff.id,
+      correlationId: handoff.id,
+      senderAttempt,
+    });
+    this._persistHandoffMutation({
+      type: "handoff:message",
+      handoffId: handoff.id,
+      kind,
+      messageId: message.id,
+      to,
+    });
+    if (kind === "offered") {
+      this.requestFollowupWake({
+        to,
+        message,
+        senderAttempt,
+      });
+    }
+    return message;
+  }
+
+  _settleHandoffOfferMessage(
+    recipient,
+    handoffId,
+    authority,
+    { status = "processed", reason = null } = {},
+  ) {
+    if (!this.mailbox) return null;
+    const ids = this.mailbox
+      .log()
+      .filter(
+        (message) =>
+          (message.to === recipient || message.to === "*") &&
+          message.body?.kind === "team_handoff_offered" &&
+          message.body?.handoffId === handoffId,
+      )
+      .map((message) => message.id);
+    if (ids.length === 0) return null;
+    try {
+      return this.mailbox.acknowledge(recipient, {
+        messageIds: ids,
+        consumerKey: `team-handoff-${status}:${handoffId}`,
+        status,
+        ...(reason ? { reason } : {}),
+        recipientAttempt: authority,
+      });
+    } catch (error) {
+      // A prior explicit ACK may have used another consumer key. Its terminal
+      // receipt already proves the offer notification cannot spawn an idle
+      // wake, so only propagate non-terminal/structural mailbox failures.
+      const terminal = ids.every((messageId) =>
+        (this.mailbox.snapshot().receipts || []).some(
+          ([, receipt]) =>
+            receipt.recipient === recipient &&
+            receipt.messageId === messageId &&
+            ["processed", "dead_letter"].includes(receipt.status),
+        ),
+      );
+      if (terminal) return null;
+      throw error;
+    }
+  }
+
+  _clearHandoffExpiry(handoffId) {
+    const timer = this._handoffExpiryTimers.get(handoffId);
+    if (timer) clearTimeout(timer);
+    this._handoffExpiryTimers.delete(handoffId);
+  }
+
+  _scheduleHandoffExpiry(handoff) {
+    if (
+      !handoff ||
+      !["offered", "accepted"].includes(handoff.status) ||
+      this._handoffExpiryTimers.has(handoff.id)
+    ) {
+      return;
+    }
+    const milliseconds = Math.max(0, Number(handoff.expiresAtMs) - this._now());
+    const timer = setTimeout(
+      () => {
+        this._handoffExpiryTimers.delete(handoff.id);
+        try {
+          this._expireHandoffs();
+        } catch (error) {
+          this.abortRun(error, { requireAdjudication: true });
+        }
+      },
+      Math.min(milliseconds, 2_147_483_647),
+    );
+    timer.unref?.();
+    this._handoffExpiryTimers.set(handoff.id, timer);
+  }
+
+  _expireHandoffs() {
+    if (!this.handoffEnabled) return [];
+    const result = this._assertHandoffResult(
+      this.registry.expireHandoffs(),
+      "expire",
+    );
+    for (const handoff of result.expired) {
+      this._clearHandoffExpiry(handoff.id);
+      const coordinatorAttempt = {
+        holder: "coordinator",
+        taskKey: handoff.taskKey,
+        leaseId: null,
+        fencingToken: null,
+      };
+      this._settleHandoffOfferMessage(
+        handoff.toHolder,
+        handoff.id,
+        coordinatorAttempt,
+        { status: "dead_letter", reason: "handoff_expired" },
+      );
+      this._persistHandoffMutation({
+        type: "handoff:expired",
+        key: handoff.taskKey,
+        handoffId: handoff.id,
+      });
+      this._handoffMessage(
+        handoff.fromHolder,
+        handoff,
+        "expired",
+        coordinatorAttempt,
+        "handoff_expired",
+      );
+    }
+    for (const task of this.registry.list()) {
+      for (const handoff of task.metadata?.custodyHandoffs || []) {
+        this._scheduleHandoffExpiry(handoff);
+      }
+    }
+    return result.expired;
+  }
+
+  _handoffFailure(code, message, details = {}) {
+    const error = new Error(message);
+    error.code = code;
+    Object.assign(error, details);
+    return error;
+  }
+
+  _assertHandoffResult(result, operation) {
+    if (result?.ok) return result;
+    throw this._handoffFailure(
+      `TEAM_HANDOFF_${String(operation).toUpperCase()}_REJECTED`,
+      `Team handoff ${operation} rejected: ${result?.reason || "unknown"}`,
+      { reason: result?.reason || "unknown" },
+    );
+  }
+
+  _queueHandoffTransfer(transfer) {
+    const queue = this._handoffTransfers.get(transfer.holder) || [];
+    if (
+      queue.some(
+        (candidate) =>
+          candidate.key === transfer.key &&
+          candidate.handoffId === transfer.handoffId,
+      )
+    ) {
+      return false;
+    }
+    queue.push(transfer);
+    this._handoffTransfers.set(transfer.holder, queue);
+    this._reservedExecutions += 1;
+    this._emit("handoff:transfer-queued", {
+      key: transfer.key,
+      handoffId: transfer.handoffId,
+      holder: transfer.holder,
+      recovered: transfer.recovered === true,
+    });
+    this._signalProgress();
+    return true;
+  }
+
+  _reserveHandoffTransfer(key, handoff, lease, { recovered = false } = {}) {
+    const holder = handoff.toHolder;
+    if (!this._residentHolders.has(holder)) {
+      throw this._handoffFailure(
+        "TEAM_HANDOFF_TARGET_NOT_RESIDENT",
+        `Handoff target is not resident in this run: ${holder}`,
+      );
+    }
+    if (this._executions + this._reservedExecutions >= this.maxTasks) {
+      throw this._handoffFailure(
+        "TEAM_HANDOFF_TASK_BUDGET_EXHAUSTED",
+        "Task execution budget cannot admit the handoff target attempt",
+      );
+    }
+    const task = this.registry.getTask(key);
+    const budgetReservation = this._reserveTaskBudget(key, task, lease);
+    if (!budgetReservation.ok) {
+      throw this._handoffFailure(
+        "TEAM_HANDOFF_RESOURCE_BUDGET_REJECTED",
+        `Resource budget cannot admit handoff: ${budgetReservation.reason}`,
+        { reason: budgetReservation.reason },
+      );
+    }
+    let sessionWork;
+    try {
+      sessionWork = this._reserveSessionWork(key, lease);
+    } catch (error) {
+      if (budgetReservation.id) {
+        this.budget?.releaseReservation?.(budgetReservation.id);
+      }
+      throw error;
+    }
+    if (!sessionWork.ok) {
+      if (budgetReservation.id) {
+        this.budget?.releaseReservation?.(budgetReservation.id);
+      }
+      throw this._handoffFailure(
+        "TEAM_HANDOFF_SESSION_BUDGET_REJECTED",
+        `Session budget cannot admit handoff: ${sessionWork.reason}`,
+        { reason: sessionWork.reason },
+      );
+    }
+    return {
+      key,
+      handoffId: handoff.id,
+      holder,
+      lease,
+      budgetReservation,
+      sessionWork,
+      recovered,
+    };
+  }
+
+  /** Lease-bound state machine entry point used by the team_handoff tool. */
+  requestHandoff({ action, handoffId, authority, ...args } = {}) {
+    if (!this.handoffEnabled) {
+      throw this._handoffFailure(
+        "TEAM_HANDOFF_UNAVAILABLE",
+        "Task custody handoff is unavailable for this registry adapter",
+      );
+    }
+    const holder = authority?.holder;
+    if (!holder || !authority?.taskKey || !authority?.leaseId) {
+      throw this._handoffFailure(
+        "TEAM_HANDOFF_STALE_ATTEMPT",
+        "Handoff requires an active lease-bound task attempt",
+      );
+    }
+    const active = this._claimsByKey.get(authority.taskKey);
+    if (
+      active?.holder !== holder ||
+      active?.leaseId !== authority.leaseId ||
+      active?.fencingToken !== authority.fencingToken
+    ) {
+      throw this._handoffFailure(
+        "TEAM_HANDOFF_STALE_ATTEMPT",
+        "Handoff authority is no longer active",
+      );
+    }
+    if (action === "offer") {
+      if (!this.graphRevisionDigest || !this.graphAuthorityDigest) {
+        throw this._handoffFailure(
+          "TEAM_HANDOFF_BINDING_UNAVAILABLE",
+          "Graph revision and authority bindings are unavailable",
+        );
+      }
+      if (
+        !args.to ||
+        args.to === "*" ||
+        args.to === "coordinator" ||
+        !this._residentHolders.has(args.to)
+      ) {
+        throw this._handoffFailure(
+          "TEAM_HANDOFF_INVALID_RECIPIENT",
+          "Handoff requires one resident teammate recipient",
+        );
+      }
+      const offered = this._assertHandoffResult(
+        this.registry.offerHandoff(authority.taskKey, {
+          handoffId,
+          holder,
+          leaseId: authority.leaseId,
+          toHolder: args.to,
+          revisionDigest: this.graphRevisionDigest,
+          authorityDigest: this.graphAuthorityDigest,
+          artifactIds: args.artifactIds || [],
+          preconditions: args.preconditions || null,
+          summary: args.summary || null,
+          ttlMs: args.ttlMs,
+          idempotencyKey: handoffId,
+        }),
+        "offer",
+      );
+      this._persistHandoffMutation({
+        type: "handoff:offered",
+        key: authority.taskKey,
+        handoffId,
+      });
+      this._handoffMessage(args.to, offered.handoff, "offered", authority);
+      this._scheduleHandoffExpiry(offered.handoff);
+      return offered;
+    }
+
+    const found = this.registry.findHandoff(handoffId);
+    if (!found) {
+      throw this._handoffFailure(
+        "TEAM_HANDOFF_NOT_FOUND",
+        `Handoff not found: ${handoffId}`,
+      );
+    }
+    const handoff = found.handoff;
+    if (![handoff.fromHolder, handoff.toHolder].includes(holder)) {
+      throw this._handoffFailure(
+        "TEAM_HANDOFF_FORBIDDEN",
+        "Only the source or designated recipient can inspect this handoff",
+      );
+    }
+    if (action === "status") {
+      this._persistHandoffMutation({
+        type: "handoff:status",
+        key: found.key,
+        handoffId,
+      });
+      return { ok: true, key: found.key, handoff };
+    }
+    if (action === "accept") {
+      const accepted = this._assertHandoffResult(
+        this.registry.acceptHandoff(handoffId, {
+          holder,
+          recipientAttempt: authority,
+        }),
+        "accept",
+      );
+      this._settleHandoffOfferMessage(holder, handoffId, authority);
+      this._persistHandoffMutation({
+        type: "handoff:accepted",
+        key: found.key,
+        handoffId,
+      });
+      this._handoffMessage(
+        handoff.fromHolder,
+        accepted.handoff,
+        "accepted",
+        authority,
+      );
+      return accepted;
+    }
+    if (action === "reject") {
+      const rejected = this._assertHandoffResult(
+        this.registry.rejectHandoff(handoffId, {
+          holder,
+          reason: args.reason,
+        }),
+        "reject",
+      );
+      this._clearHandoffExpiry(handoffId);
+      this._settleHandoffOfferMessage(holder, handoffId, authority);
+      this._persistHandoffMutation({
+        type: "handoff:rejected",
+        key: found.key,
+        handoffId,
+      });
+      this._handoffMessage(
+        handoff.fromHolder,
+        rejected.handoff,
+        "rejected",
+        authority,
+        args.reason,
+      );
+      return rejected;
+    }
+    if (action === "revoke") {
+      const revoked = this._assertHandoffResult(
+        this.registry.revokeHandoff(handoffId, {
+          holder,
+          leaseId: authority.leaseId,
+          reason: args.reason,
+        }),
+        "revoke",
+      );
+      this._clearHandoffExpiry(handoffId);
+      this._persistHandoffMutation({
+        type: "handoff:revoked",
+        key: found.key,
+        handoffId,
+      });
+      this._handoffMessage(
+        handoff.toHolder,
+        revoked.handoff,
+        "revoked",
+        authority,
+        args.reason,
+      );
+      return revoked;
+    }
+    if (action !== "commit") {
+      throw this._handoffFailure(
+        "TEAM_HANDOFF_INVALID_ACTION",
+        `Unknown handoff action: ${String(action || "")}`,
+      );
+    }
+    if (
+      found.key !== authority.taskKey ||
+      handoff.fromHolder !== holder ||
+      handoff.fromLeaseId !== authority.leaseId
+    ) {
+      throw this._handoffFailure(
+        "TEAM_HANDOFF_SOURCE_MISMATCH",
+        "Only the exact source task attempt can commit this handoff",
+      );
+    }
+    const syntheticLease = {
+      leaseId: `handoff-target:${handoff.id}`,
+      holder: handoff.toHolder,
+    };
+    const reserved = this._reserveHandoffTransfer(
+      found.key,
+      handoff,
+      syntheticLease,
+    );
+    let committed;
+    try {
+      committed = this._assertHandoffResult(
+        this.registry.commitHandoff(handoffId, {
+          holder,
+          leaseId: authority.leaseId,
+          ttlMs: this.ttlMs,
+        }),
+        "commit",
+      );
+    } catch (error) {
+      if (reserved.budgetReservation?.id) {
+        this.budget?.releaseReservation?.(reserved.budgetReservation.id);
+      }
+      reserved.sessionWork?.release?.();
+      throw error;
+    }
+    reserved.lease = committed.lease;
+    this._clearHandoffExpiry(handoffId);
+    if (!this._queueHandoffTransfer(reserved)) {
+      if (reserved.budgetReservation?.id) {
+        this.budget?.releaseReservation?.(reserved.budgetReservation.id);
+      }
+      reserved.sessionWork?.release?.();
+    }
+    this._persistHandoffMutation({
+      type: "handoff:committed",
+      key: found.key,
+      handoffId,
+      holder: handoff.toHolder,
+      leaseId: committed.lease.leaseId,
+    });
+    const transferred = this._handoffFailure(
+      "TEAM_HANDOFF_COMMITTED",
+      `Task custody transferred to ${handoff.toHolder}`,
+    );
+    transferred.retryable = false;
+    active.handoffCommitted = { handoffId, error: transferred };
+    try {
+      active.abortController.abort(transferred);
+    } catch {
+      /* the replacement lease already fences every source settlement */
+    }
+    this._signalProgress();
+    return committed;
+  }
+
+  _reconcileCommittedHandoffs() {
+    if (!this.handoffEnabled) return [];
+    for (const pending of this.registry.pendingCommittedHandoffs()) {
+      if (!this._residentHolders.has(pending.handoff.toHolder)) {
+        throw this._handoffFailure(
+          "TEAM_HANDOFF_TARGET_NOT_RESIDENT",
+          `Committed handoff target is not resident: ${pending.handoff.toHolder}`,
+        );
+      }
+      const refreshed = this._assertHandoffResult(
+        this.registry.refreshCommittedHandoffLease(pending.key, {
+          handoffId: pending.handoff.id,
+          holder: pending.handoff.toHolder,
+          ttlMs: this.ttlMs,
+        }),
+        "recover",
+      );
+      const transfer = this._reserveHandoffTransfer(
+        pending.key,
+        refreshed.handoff,
+        refreshed.lease,
+        { recovered: true },
+      );
+      this._queueHandoffTransfer(transfer);
+      this._persistHandoffMutation({
+        type: "handoff:recovered",
+        key: pending.key,
+        handoffId: pending.handoff.id,
+        holder: pending.handoff.toHolder,
+        leaseId: refreshed.lease.leaseId,
+      });
+    }
+  }
+
   /** Snapshot of local in-flight claims for an IDE/operator control surface. */
   activeClaims() {
     return Array.from(this._claimsByKey.values()).map((claim) => ({
@@ -347,20 +1238,48 @@ export class TeamRunner {
     }
     this.sessionBudget?.start?.();
     const workers = [];
+    const requiredHandoffWorker = (
+      this.handoffEnabled ? this.registry.pendingCommittedHandoffs() : []
+    ).reduce((maximum, pending) => {
+      const match = /^teammate-(\d+)$/u.exec(pending.handoff.toHolder);
+      return match ? Math.max(maximum, Number(match[1])) : maximum;
+    }, 0);
+    if (requiredHandoffWorker > this.teammates) {
+      const error = new Error(
+        `Committed handoff target requires ${requiredHandoffWorker} teammates, but this run allows ${this.teammates}`,
+      );
+      error.code = "TEAM_HANDOFF_TARGET_NOT_RESIDENT";
+      throw error;
+    }
     const workerCount = Math.min(
       this.teammates,
-      Math.max(1, this.registry.list().length),
+      Math.max(1, this.registry.list().length, requiredHandoffWorker),
     );
     this._workerCount = workerCount;
     const holders = Array.from(
       { length: workerCount },
       (_, index) => `teammate-${index + 1}`,
     );
+    this._residentHolders = new Set(holders);
     this.mailbox?.registerRecipients?.(holders);
     for (const holder of holders) {
       this._setState(holder, "idle");
-      workers.push(this._worker(holder));
     }
+    try {
+      this._expireHandoffs();
+      this._reconcileCommittedHandoffs();
+    } catch (error) {
+      if (this._wallTimer) {
+        clearTimeout(this._wallTimer);
+        this._wallTimer = null;
+      }
+      throw error;
+    }
+    // A prior coordinator may have committed a follow-up message immediately
+    // before crashing, before it could materialize the wake task. Reconcile
+    // those durable messages before workers decide the graph has no more work.
+    this._reconcileFollowupWakes();
+    for (const holder of holders) workers.push(this._worker(holder));
     try {
       await Promise.all(workers);
     } finally {
@@ -368,6 +1287,10 @@ export class TeamRunner {
         clearTimeout(this._wallTimer);
         this._wallTimer = null;
       }
+      for (const timer of this._handoffExpiryTimers.values()) {
+        clearTimeout(timer);
+      }
+      this._handoffExpiryTimers.clear();
     }
     if (this._fatalError) throw this._fatalError;
     const stats = this.registry.stats();
@@ -395,6 +1318,137 @@ export class TeamRunner {
     return summary;
   }
 
+  _takeHandoffTransfer(holder) {
+    const queue = this._handoffTransfers.get(holder) || [];
+    for (let index = 0; index < queue.length; index++) {
+      const transfer = queue[index];
+      if (this._activeKeys.has(transfer.key)) continue;
+      if (this.scopeLock) {
+        const task = this.registry.getTask(transfer.key);
+        const check = this.scopeLock.canAcquire(
+          transfer.key,
+          this.scopeForTask(task, transfer.key),
+        );
+        if (!check.ok) {
+          if (check.code === "TEAM_SCOPE_LOCK_SCOPE_CONFLICT") continue;
+          const error = new Error(
+            check.message ||
+              `invalid task scope ownership for "${transfer.key}"`,
+          );
+          error.code = check.code || "TEAM_SCOPE_LOCK_INVALID_SCOPES";
+          this._setFatal(error, {
+            phase: "handoff-scope-validation",
+            key: transfer.key,
+            holder,
+          });
+          return null;
+        }
+      }
+      queue.splice(index, 1);
+      if (queue.length === 0) this._handoffTransfers.delete(holder);
+      return transfer;
+    }
+    return null;
+  }
+
+  _discardHandoffTransfer(transfer, claim = null) {
+    if (transfer?.budgetReservation?.id) {
+      this.budget?.releaseReservation?.(transfer.budgetReservation.id);
+    }
+    if (claim) this._endClaim(claim);
+    else transfer?.sessionWork?.release?.();
+    this._reservedExecutions = Math.max(0, this._reservedExecutions - 1);
+    this._signalProgress();
+  }
+
+  async _executeHandoffTransfer(holder, transfer) {
+    const current = this.registry.getTask(transfer.key);
+    if (
+      !current?.lease ||
+      current.lease.holder !== holder ||
+      current.lease.leaseId !== transfer.lease?.leaseId
+    ) {
+      this._discardHandoffTransfer(transfer);
+      const error = this._handoffFailure(
+        "TEAM_HANDOFF_TARGET_LEASE_CHANGED",
+        `Committed handoff target lease changed before dispatch: ${transfer.key}`,
+      );
+      this._setFatal(error, {
+        phase: "handoff-dispatch",
+        key: transfer.key,
+        holder,
+      });
+      return;
+    }
+    let claim;
+    try {
+      claim = this._beginClaim(
+        holder,
+        transfer.key,
+        transfer.lease,
+        transfer.budgetReservation,
+        transfer.sessionWork,
+      );
+      claim.handoffId = transfer.handoffId;
+    } catch (error) {
+      this._discardHandoffTransfer(transfer);
+      this._setFatal(error, {
+        phase: "handoff-session-budget-bind",
+        key: transfer.key,
+        holder,
+      });
+      return;
+    }
+    if (!this._acquireScope(holder, transfer.key)) {
+      this._discardHandoffTransfer(transfer, claim);
+      return;
+    }
+    const started = this.registry.markHandoffStarted(transfer.key, {
+      handoffId: transfer.handoffId,
+      holder,
+      leaseId: transfer.lease.leaseId,
+    });
+    if (!started.ok) {
+      const error = this._handoffFailure(
+        "TEAM_HANDOFF_TARGET_START_REJECTED",
+        `Could not durably start handoff target: ${started.reason}`,
+      );
+      this._setFatal(error, {
+        phase: "handoff-start",
+        key: transfer.key,
+        holder,
+      });
+      this._releaseScope(holder, transfer.key);
+      this._discardHandoffTransfer(transfer, claim);
+      return;
+    }
+    try {
+      this._persistHandoffMutation({
+        type: "handoff:target-started",
+        key: transfer.key,
+        handoffId: transfer.handoffId,
+        holder,
+        leaseId: transfer.lease.leaseId,
+        recovered: transfer.recovered === true,
+      });
+    } catch {
+      this._releaseScope(holder, transfer.key);
+      this._discardHandoffTransfer(transfer, claim);
+      return;
+    }
+    if (!(await this._prepareTask(holder, transfer.key, claim))) {
+      this._releaseScope(holder, transfer.key);
+      this._discardHandoffTransfer(transfer, claim);
+      return;
+    }
+    if (this._fatalError || claim.lost) {
+      this._releaseScope(holder, transfer.key);
+      this._discardHandoffTransfer(transfer, claim);
+      return;
+    }
+    await this._execute(holder, transfer.key, claim);
+  }
+
   async _worker(holder) {
     // Each teammate keeps taking claimable work until none is left FOR IT. A
     // task blocked only by a peer's in-flight lease will free up (complete) or
@@ -405,6 +1459,11 @@ export class TeamRunner {
         this._setState(holder, "shutdown", { reason: "fatal-error" });
         return;
       }
+      const transfer = this._takeHandoffTransfer(holder);
+      if (transfer) {
+        await this._executeHandoffTransfer(holder, transfer);
+        continue;
+      }
       const sessionStopReason = this._sessionBudgetStopReason();
       if (sessionStopReason) {
         const reason = sessionStopReason;
@@ -447,11 +1506,16 @@ export class TeamRunner {
       }
       const key = this._nextFor(holder);
       if (!key) {
+        this._setState(holder, "idle");
+        // A follow-up may have arrived while this target's previous turn was
+        // still active. If it was not explicitly ACKed by turn settlement,
+        // convert it into a fresh lease-bound turn now instead of shutting the
+        // worker down with a stranded wake intent.
+        if (this._reconcileFollowupWakes(holder) > 0) continue;
         // Nothing to claim right now. If peers are still working, wait and
         // retry (their completions may unblock a dependent). Otherwise we're done.
         const heldScopes = this.scopeLock?.status?.().count || 0;
         if (this._inFlight > 0 || this._reservedExecutions > 0) {
-          this._setState(holder, "idle");
           await this._waitForProgress();
           continue;
         }
@@ -1045,7 +2109,7 @@ export class TeamRunner {
   }
 
   /** Pick a claimable task key for this holder (highest priority first). */
-  _nextFor() {
+  _nextFor(holder) {
     // A whole-workspace owner blocks every other scope, so avoid walking a
     // large ready queue only to rediscover the same conflict for each task.
     if (
@@ -1059,8 +2123,15 @@ export class TeamRunner {
       const excluded = new Set(this._activeKeys);
       for (let scanned = 0; scanned < this.maxScopeScan; scanned++) {
         const key = this.registry.nextClaimable({ excludeKeys: excluded });
-        if (!key || !this.scopeLock) return key;
+        if (!key) return null;
         const task = this.registry.getTask(key);
+        const targetHolder =
+          followupMetadata(task)?.recipient || custodyRecipient(task) || null;
+        if (targetHolder && targetHolder !== holder) {
+          excluded.add(key);
+          continue;
+        }
+        if (!this.scopeLock) return key;
         const check = this.scopeLock.canAcquire(
           key,
           this.scopeForTask(task, key),
@@ -1087,6 +2158,9 @@ export class TeamRunner {
     for (const key of claimable) {
       if (this._activeKeys.has(key)) continue;
       const t = this.registry.getTask(key);
+      const targetHolder =
+        followupMetadata(t)?.recipient || custodyRecipient(t) || null;
+      if (targetHolder && targetHolder !== holder) continue;
       const score = rank[t?.priority] ?? 1;
       if (score < bestScore) {
         bestScore = score;
@@ -1138,20 +2212,46 @@ export class TeamRunner {
 
   async _execute(holder, key, claim) {
     const task = this.registry.getTask(key);
+    const sessionTaskKey = this._sessionTaskKey(key, task);
     this._reservedExecutions--;
     this._executions++;
     this._inFlight++;
     this._maxInFlight = Math.max(this._maxInFlight, this._inFlight);
-    this._setState(holder, "running", { key });
+    this._setState(holder, "running", { key, sessionTaskKey });
     this._emit("task:claimed", { key, holder, attempts: task.attempts });
     const renew = () => this._renewClaim(claim);
     // A teammate-scoped messaging handle: post to a peer / broadcast, and read
     // its own inbox (direct messages + unseen broadcasts).
-    const inbox = this.mailbox
+    const mailboxInbox = this.mailbox
       ? this.realtimeMessaging
-        ? this.mailbox.peek(holder)
+        ? this.mailbox.receive(holder, { limit: 100, markRead: true })
         : this.mailbox.drain(holder)
       : [];
+    const custodyHandoff = claim.handoffId
+      ? (task.metadata?.custodyHandoffs || []).find(
+          (handoff) => handoff.id === claim.handoffId,
+        )
+      : null;
+    const inbox = custodyHandoff
+      ? [
+          ...mailboxInbox,
+          {
+            id: null,
+            from: custodyHandoff.fromHolder,
+            to: custodyHandoff.toHolder,
+            subject: "Committed task custody handoff",
+            body: {
+              handoffId: custodyHandoff.id,
+              taskKey: key,
+              summary: custodyHandoff.summary,
+              preconditions: custodyHandoff.preconditions,
+              artifactIds: custodyHandoff.artifactIds || [],
+              revisionDigest: custodyHandoff.revisionDigest,
+              authorityDigest: custodyHandoff.authorityDigest,
+            },
+          },
+        ]
+      : mailboxInbox;
     const messageAuthority = () => {
       const current = this._claimsByKey.get(key);
       if (
@@ -1179,6 +2279,18 @@ export class TeamRunner {
       const member = this._members.get(recipient);
       return member ? { ...member } : null;
     };
+    const requestFollowupWake = (request = {}) =>
+      this.requestFollowupWake({
+        ...request,
+        senderAttempt: request.senderAttempt || messageAuthority(),
+      });
+    const requestHandoff = this.handoffEnabled
+      ? (request = {}) =>
+          this.requestHandoff({
+            ...request,
+            authority: request.authority || messageAuthority(),
+          })
+      : null;
     const sendMessage = (to, body, subject = null, options = {}) => {
       if (!this.mailbox) return null;
       let message;
@@ -1251,6 +2363,8 @@ export class TeamRunner {
         sendMessage,
         messageAuthority,
         recipientState,
+        requestFollowupWake,
+        requestHandoff,
         mailbox: this.mailbox,
         budget: this.budget,
         budgetReservation: claim.budgetReservation,
@@ -1266,6 +2380,9 @@ export class TeamRunner {
       if (claim.coordinatorAbort) {
         throw claim.coordinatorAbort;
       }
+      if (claim.handoffCommitted) {
+        throw claim.handoffCommitted.error;
+      }
       this._recordSessionUsage(claim, result);
       if (
         claim.sessionBudgetUsageUnknown ||
@@ -1322,7 +2439,10 @@ export class TeamRunner {
       });
       if (done.ok) {
         if (span) span.end();
-        this._setState(holder, "completed-task");
+        this._setState(holder, "completed-task", {
+          key,
+          sessionTaskKey,
+        });
         this._emit("task:completed", {
           key,
           holder,
@@ -1390,6 +2510,8 @@ export class TeamRunner {
       if (outcome?.ok) {
         this._setState(holder, "failed-task", {
           error: failure?.message || String(failure),
+          key,
+          sessionTaskKey,
         });
         this._emit("task:failed", {
           key,