@goah/cli 0.13.2 → 0.13.4

package/dist/{chunk-KJ4HJCTK.js → chunk-5PZFP5CO.js}

@@ -2,30 +2,27 @@ import { createRequire as __goahCreateRequire } from "node:module";
 const require = __goahCreateRequire(import.meta.url);
 import {
   runnerPlugin
-} from "./chunk-D2DVAH37.js";
+} from "./chunk-R6GKCNTB.js";
 import {
   SQLITE_SCHEMA_VERSION,
   SqliteLedger
-} from "./chunk-YH6YJ2IB.js";
+} from "./chunk-CDELLMIJ.js";
 import {
   RunnerRouter,
   Supervisor,
   deriveRecoveryViews
-} from "./chunk-QBD6EJ2Z.js";
+} from "./chunk-SQJZ5OFH.js";
 import {
   ProcessRunner,
   piWorkerPath,
   resolveEnvSpec
-} from "./chunk-7E7V6OIU.js";
+} from "./chunk-EK6BTCFG.js";
 import {
   createPiModel
 } from "./chunk-6M3OOCKO.js";
 import {
   replayTranscript
 } from "./chunk-R6I3VKME.js";
-import {
-  normalizeAssistantText
-} from "./chunk-TJON22J4.js";
 
 // node_modules/.dist-original/index.js
 import { accessSync, chmodSync as chmodSync3, constants, existsSync as existsSync3, mkdirSync as mkdirSync2, openSync, closeSync, readFileSync as readFileSync3, renameSync, rmSync as rmSync3, statSync as statSync2, writeFileSync as writeFileSync2 } from "node:fs";
@@ -440,10 +437,7 @@ async function* turnFrames(turnId, ledger, isActive) {
       throw new Error("Turn disappeared");
     if (current.status !== "in_progress") {
       yield* drain();
-      const answer = ledger.turnItems(turnId).filter((item) => item.type === "assistant_message").at(-1);
-      const answerText = String(answer?.data?.text ?? "");
-      const streamed = answerText !== "" && ledger.readStream(`turn:${turnId}`).some((event) => event.type === "response.committed" ? event.data.text === answerText : event.type === "message.assistant.completed" && assistantEventText(event.data) === answerText);
-      yield { type: "result", value: { turn: { ...current, leaseToken: null }, ...answer && !streamed ? { response: { content: answerText } } : {} } };
+      yield { type: "result", value: { turn: { ...current, leaseToken: null } } };
       return;
     }
     await new Promise((resolve3) => setTimeout(resolve3, 50));
@@ -461,16 +455,6 @@ function requiredGoal(ledger, id) {
     throw new Error("goal not found");
   return goal;
 }
-function assistantEventText(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value) || !value.message || typeof value.message !== "object" || Array.isArray(value.message))
-    return "";
-  const content = value.message.content;
-  if (typeof content === "string")
-    return normalizeAssistantText(content);
-  if (!Array.isArray(content))
-    return "";
-  return content.map((item) => item && typeof item === "object" && !Array.isArray(item) && item.type === "text" && typeof item.text === "string" ? normalizeAssistantText(item.text) : "").filter(Boolean).join("\n");
-}
 function isTurnPresentationEvent(type) {
   return type.startsWith("message.") || type.startsWith("tool.") || type.startsWith("item.") || type.startsWith("turn.") || type === "response.committed" || type === "handoff.recorded" || type === "transcript.interrupted" || type === "transcript.completed";
 }

package/dist/{chunk-YH6YJ2IB.js → chunk-CDELLMIJ.js}

@@ -751,9 +751,25 @@ var SqliteLedger = class {
     return this.#transaction(() => this.#repairOpenTurnItems(id, reason, now, actor));
   }
   finishTurn(id, status, error, now, actor, mailIds = []) {
+    if (status === "completed")
+      throw new Error("successful Turn completion requires commitTurnResponse or commitHandoff");
     const current = this.#requiredTurn(id);
     return this.#transaction(() => this.#finishTurn(current, status, error, now, actor, mailIds));
   }
+  commitTurnResponse(id, responseItemId, now, actor, mailIds = []) {
+    return this.#transaction(() => {
+      const current = this.#requiredTurn(id);
+      if (current.goalId !== null)
+        throw new Error("Goal-bound Turn response requires commitHandoff");
+      const responseItem = this.turnItems(id).find((item) => item.id === responseItemId);
+      const text = responseItem && responseItem.type === "assistant_message" && responseItem.status === "completed" ? normalizeAssistantText(String(responseItem.data.text ?? "")) : "";
+      if (!responseItem || !text)
+        throw new Error("Turn response does not match a readable Assistant Item");
+      const streamId = `turn:${id}`;
+      this.#insertEvent({ streamId, ts: now, actor, type: "response.committed", data: { messageItemId: responseItem.id, text } });
+      return this.#finishTurn(current, "completed", null, now, actor, mailIds);
+    });
+  }
   releaseTurnProcess(id, actor) {
     if (actor !== "supervisor")
       throw new Error("only supervisor may release Runner process ownership");
@@ -1451,25 +1467,36 @@ var SqliteLedger = class {
     } else {
       if (event.type !== `turn.${turn.status}` || turn.attempt !== current.attempt || turn.runnerPid !== current.runnerPid)
         throw new Error(`turn event ${event.seq} has an invalid terminal transition`);
-      if (turn.status === "completed" && turn.goalId !== null)
-        this.#assertReplayGoalCompletion(turn, event);
+      if (turn.status === "completed") {
+        if (turn.goalId !== null)
+          this.#assertReplayGoalCompletion(turn, event);
+        else
+          this.#assertReplayResponseCompletion(turn, event);
+      }
     }
   }
+  #assertReplayResponseCompletion(turn, event) {
+    const responseRow = this.db.prepare("SELECT data FROM events WHERE stream_id=? AND type='response.committed' AND seq<? ORDER BY seq DESC LIMIT 1").get(`turn:${turn.id}`, event.seq);
+    if (!responseRow)
+      throw new Error(`turn event ${event.seq} completes without a committed response`);
+    const response = JSON.parse(responseRow.data);
+    const responseItem = this.turnItems(turn.id).find((item) => item.id === response.messageItemId && item.type === "assistant_message" && item.status === "completed");
+    if (!responseItem || normalizeAssistantText(String(responseItem.data.text ?? "")) !== response.text)
+      throw new Error(`turn event ${event.seq} has a mismatched committed response`);
+    return responseItem;
+  }
   #assertReplayGoalCompletion(turn, event) {
     if (turn.goalId === null || turn.goalRevision === null)
       throw new Error(`turn event ${event.seq} has no Goal commitment`);
     const items = this.turnItems(turn.id);
-    const responses = items.filter((item) => item.type === "assistant_message" && item.status === "completed" && typeof item.data.text === "string" && Boolean(item.data.text.trim()));
+    this.#assertReplayResponseCompletion(turn, event);
     const handoffItem = items.findLast((item) => item.type === "handoff" && item.status === "completed");
-    const responseRow = this.db.prepare("SELECT data FROM events WHERE stream_id=? AND type='response.committed' AND seq<? ORDER BY seq DESC LIMIT 1").get(`turn:${turn.id}`, event.seq);
     const handoffRow = this.db.prepare("SELECT data FROM events WHERE stream_id=? AND type='handoff.recorded' AND seq<? ORDER BY seq DESC LIMIT 1").get(`turn:${turn.id}`, event.seq);
-    if (!responseRow || !handoffRow || !handoffItem)
-      throw new Error(`turn event ${event.seq} completes a Goal without response and Handoff`);
-    const response = JSON.parse(responseRow.data);
+    if (!handoffRow || !handoffItem)
+      throw new Error(`turn event ${event.seq} completes a Goal without Handoff`);
     const handoff = JSON.parse(handoffRow.data);
-    const responseItem = responses.find((item) => item.id === response.messageItemId);
-    if (!responseItem || responseItem.data.text !== response.text || !isDeepStrictEqual(handoffItem.data, handoff))
-      throw new Error(`turn event ${event.seq} has mismatched response or Handoff facts`);
+    if (!isDeepStrictEqual(handoffItem.data, handoff))
+      throw new Error(`turn event ${event.seq} has mismatched Handoff facts`);
     assertHandoff(handoff);
     const record = this.workRecord(turn.goalId);
     if (handoff.goalId !== turn.goalId || handoff.goalRevision !== turn.goalRevision || record?.recordRevision !== handoff.recordRevision)

package/dist/{chunk-7E7V6OIU.js → chunk-EK6BTCFG.js}

@@ -124,18 +124,23 @@ var PiRunnerAdapter = class {
   }
   async #run(request) {
     const runnerSession = await this.driver.createRunnerSession(request);
+    let messageSequence = 0;
     try {
       while (true) {
         const step = await runnerSession.step();
         for (const trace of step.trace ?? [])
           request.emit(trace);
-        if (step.response)
-          return { outcome: "completed", response: step.response };
+        if (step.response) {
+          const finalMessageId = `adapter:${request.execution.id}:attempt:${request.execution.attempt}:message:${++messageSequence}`;
+          request.emit({ type: "message.assistant.completed", data: { message: { id: finalMessageId, role: "assistant", content: [{ type: "text", text: step.response.content }] }, commitState: "committed" } });
+          return { outcome: "completed", finalMessageId };
+        }
         if (step.handoff) {
-          const validation = await request.rpc?.("goal.handoff.validate", { handoff: step.handoff.handoff, candidateMessage: step.handoff.response.content });
+          const messageItemId = `adapter:${request.execution.id}:attempt:${request.execution.attempt}:message:${++messageSequence}`;
+          const validation = await request.rpc?.("goal.handoff.validate", { handoff: step.handoff.handoff, candidateMessageId: messageItemId, candidateMessage: step.handoff.response.content });
           if (!validation)
             return { outcome: "abnormal", reason: "Handoff validation is unavailable" };
-          request.emit({ type: "message.assistant.completed", data: { message: { id: `adapter:${request.execution.id}:handoff:${validation.attemptId}`, role: "assistant", content: [{ type: "text", text: step.handoff.response.content }], stopReason: "toolUse" }, commitState: "provisional" } });
+          request.emit({ type: "message.assistant.completed", data: { message: { id: messageItemId, role: "assistant", content: [{ type: "text", text: step.handoff.response.content }], stopReason: "toolUse" }, commitState: "provisional" } });
           if (!validation.accepted) {
             if (validation.fatal)
               return { outcome: "abnormal", reason: validation.issues.map((issue) => issue.message).join("; ") };
@@ -143,9 +148,11 @@ var PiRunnerAdapter = class {
             request.emit({ type: "runner.handoff_rejected", data: { attemptId: validation.attemptId, issues: validation.issues } });
             continue;
           }
+          if (validation.messageItemId !== messageItemId)
+            return { outcome: "abnormal", reason: "Handoff validation returned a different assistant message identity" };
           const output = { validationAttemptId: validation.attemptId, validationToken: validation.token, handoff: step.handoff.handoff };
           assertTurnOutput(output);
-          return { outcome: "completed", response: step.handoff.response, handoff: output };
+          return { outcome: "completed", finalMessageId: messageItemId, handoff: output };
         }
         if (step.stopped)
           return { outcome: "abnormal", reason: request.turn.goalCommitment ? "runner stopped without a readable response and valid handoff" : "runner stopped without a response" };

package/dist/{chunk-D2DVAH37.js → chunk-R6GKCNTB.js}

@@ -3,7 +3,7 @@ const require = __goahCreateRequire(import.meta.url);
 import {
   createPiProcessRunner,
   piRunnerConfigurator
-} from "./chunk-7E7V6OIU.js";
+} from "./chunk-EK6BTCFG.js";
 
 // node_modules/.dist-original/runner-registry.js
 var plugins = /* @__PURE__ */ new Map([

package/dist/{chunk-QBD6EJ2Z.js → chunk-SQJZ5OFH.js}

@@ -92,14 +92,20 @@ function field(value, key) {
 
 // node_modules/goah-supervisor/dist/roles.js
 var prompts = {
-  child: "Own the assigned Child Goal. Follow its observation method, verify completion with its verification method, inspect shared Work Records, cite Ledger evidence, update this Goal's Work Record every Turn, and hand off an explicit outcome. Handoff is declarative: use mail.send to notify or escalate, setting its typed goalId route to the parent Goal when it should wake the parent's next committed Turn; use schedule.set to request future motion and send a completion_proposed Mail when the parent should review completion. You are not a task-only worker and cannot redefine or complete your own Goal.",
-  ceo: `You are the user's sole operating interface and the durable CEO identity for this Goal tree. You organize work; you do not impersonate child execution.
+  child: `Own the assigned Child Goal. A Wake starts a work session; it is not a request for one short status update. Follow the observation method, verify completion with the verification method, inspect shared Work Records, cite Ledger evidence, and continue working while any safe, useful action can be executed now with current tools and authority. Use the Work Record as a durable checkpoint whenever the semantic state changes; updating it does not end the Turn. Planning, partial progress, or scheduling a future Wake are not by themselves reasons to stop. Before Handoff, ask whether another useful action can be completed without new authority, unavailable data, another Agent's result, or the passage of time; if yes, do it now.
+
+Handoff is declarative and ends this Turn. Use outcome progress only after meaningful work when the current actionable frontier is exhausted; waiting only for an explicit external condition; blocked only for a real obstacle; and completion_proposed only when the verification material is ready for parent review. Use mail.send to notify or escalate, setting its typed goalId route to the parent Goal when it should wake the parent's next committed Turn; use schedule.set for genuinely time-dependent future observation and send a completion_proposed Mail when the parent should review completion. You are not a task-only worker and cannot redefine or complete your own Goal.`,
+  ceo: `You are the user's sole operating interface and the durable CEO identity for this Goal tree. You organize work and execute directly wherever work is not delegated. You are the executor of last resort when no suitable Child Agent profile exists.
 
 On the first wake for a root with no observation method, operationalize the goal before claiming measurable progress: inspect the current directory with read/edit/write/bash; read project documentation, configuration, code, scripts, local CLIs, and existing ledger evidence; clarify the objective, constraints, baseline, and meaning of success; identify the data source or qualitative inspection protocol; define freshness, cadence, time zone, sustain window, and missing-data behavior when relevant; list the exact access required; then propose a textual observation method to the human. Ask only for facts or permissions that cannot be discovered locally. Continue safe reversible exploration while waiting. Never invent a baseline, data source, permission, success criterion, or observation result.
 
-On every wake: (1) orient from the root and descendants, each current observation method and revision, Team motion, incoming mail, handoffs, blockers, unknown Tool Calls, and recovery facts; (2) diagnose every active child's motion, ownership, and adherence to its authoritative observation method; (3) decide whether to keep, delegate, revise the objective/method pair, reassign, pause, resume, complete, or escalate; (4) apply organization changes only through the high-level atomic tools; (5) repair every idle_unplanned child and every child missing an observation method before handoff; (6) close with active child motion plus a CEO review, an explicit wait/blocker, a human request, or a completion recommendation carrying evidence produced under the current method.
+During every Goal Turn: (1) orient from the root and descendants, each current observation method and revision, Team motion, incoming mail, handoffs, blockers, unknown Tool Calls, and recovery facts; (2) diagnose every active child's motion, ownership, and adherence to its authoritative observation method; (3) decide whether to keep, delegate, revise the objective/method pair, reassign, pause, resume, complete, or escalate; (4) apply organization changes only through the high-level atomic tools; (5) repair every idle_unplanned child and every child missing an observation method; (6) execute the current work frontier instead of stopping at planning; (7) before ending, leave active child motion plus a CEO review, an explicit wait/blocker, a human request, or a completion recommendation carrying evidence produced under the current method.
+
+Use goal.delegate rather than separate goal/mail/schedule calls. Execute ambiguous or exploratory work yourself until a stream has a bounded objective, independent observation and verification methods, and a reviewable result; only then create a distinct Goal-owning Agent. If no suitable Child Agent profile exists, continue executing the work yourself rather than stopping after decomposition. Use team.list as the roster source of truth.
+
+A Wake starts a work session; it does not imply that the Turn should be short. Continue while any safe, useful action can be executed now with current tools and authority. Use the bound Goal's Work Record as a durable checkpoint whenever semantic state changes; updating it does not end the Turn. Planning, partial progress, decomposition, or scheduling a future Wake are not by themselves reasons to stop. Before Handoff, ask whether another useful action can be completed without new authority, unavailable data, another Agent's result, or the passage of time; if yes, do it now. Use outcome progress only when meaningful work is complete and the current actionable frontier is exhausted. Use waiting for an explicit external condition, blocked for a real obstacle, and completion_proposed only when verification material is ready for review.
 
-Use goal.delegate rather than separate goal/mail/schedule calls. Execute ambiguous or exploratory work yourself until a stream has a bounded objective, independent observation and verification methods, and a reviewable result; only then create a distinct Goal-owning Agent. Use team.list as the roster source of truth. Read the shared Work Record index, update the bound Goal's Work Record every Turn, and treat it as the durable semantic timeline. Handoff is declarative: use mail.send for explicit organization communication, schedule.set for future motion, and human.request when Human authority is required. Never claim authority to confirm Root methods, complete, or materially change a Root Goal: request the Human instead.`,
+Handoff is declarative and ends the Turn: use mail.send for explicit organization communication, schedule.set only for genuinely time-dependent future motion, and human.request when Human authority is required. Never claim authority to confirm Root methods, complete, or materially change a Root Goal: request the Human instead.`,
   verifier: "Verify one Turn's handoff claims against its trace and runner facts. Do not trust self-report. Persist concise findings with exact evidence sequences.",
   audit: "Independently reconstruct outcomes from durable facts and external observations. Persist independent audit judgment with memory_append; it never substitutes for fresh evidence."
 };
@@ -550,27 +556,18 @@ var Supervisor = class {
           this.#scheduleTurnRecovery(sourceWake, sourceWakeTriggers, current.id, agent);
           return;
         }
-        const response = normalizeAssistantText(result.response.content);
-        if (!response)
-          throw new Error("completed Turn requires a readable assistant response");
+        const responseItem = this.#finalAssistantItem(current.id, result.finalMessageId);
         if (turnContext.goalCommitment) {
           if (!result.handoff)
             throw new Error("committed Turn requires Handoff");
-          this.#commitTurnGoalWork(current.id, agent, turnContext, response, result.handoff, sourceWake?.id ?? null, deliveredMailIds, recordRevisionAtStart);
+          this.#commitTurnGoalWork(current.id, agent, turnContext, responseItem, result.handoff, sourceWake?.id ?? null, deliveredMailIds, recordRevisionAtStart);
           return;
         }
         if (result.handoff)
           throw new Error("uncommitted Turn cannot finish with Handoff");
-        const latestMessage = this.ledger.turnItems(current.id).findLast((item) => item.type === "assistant_message" && item.status === "completed");
-        if (latestMessage) {
-          const traced = normalizeAssistantText(String(latestMessage.data.text ?? ""));
-          if (traced !== response)
-            throw new Error("completed Turn response does not match its latest assistant trace");
-          if (this.#assistantCommitState(current.id, traced) !== "committed")
-            throw new Error("uncommitted Turn requires a committed assistant trace");
-        } else
-          this.#appendTurnItem(current.id, "assistant_message", { text: response }, agent);
-        this.ledger.finishTurn(current.id, "completed", null, this.#now(), "supervisor", deliveredMailIds);
+        if (this.#assistantCommitState(current.id, responseItem.id) !== "committed")
+          throw new Error("uncommitted Turn requires a committed assistant trace");
+        this.ledger.commitTurnResponse(current.id, responseItem.id, this.#now(), "supervisor", deliveredMailIds);
         return;
       } catch (error) {
         if (renewal)
@@ -727,19 +724,32 @@ ${history}` } : {} };
     const facts = this.ledger.readStream(`turn:${turnId}`).filter((event) => event.type === "turn.retry_started").map((event) => `${event.type}: ${JSON.stringify(event.data)}`);
     return [...items, ...facts].join("\n");
   }
-  #assistantCommitState(turnId, text) {
-    const canonical = normalizeAssistantText(text);
-    const event = this.ledger.readStream(`turn:${turnId}`).findLast((candidate) => {
+  #assistantMessageEvent(turnId, messageItemId) {
+    return this.ledger.readStream(`turn:${turnId}`).findLast((candidate) => {
       if (candidate.type !== "message.assistant.completed" || !candidate.data || typeof candidate.data !== "object" || Array.isArray(candidate.data))
         return false;
       const message = candidate.data.message;
-      return messageTextContent(message?.content) === canonical;
+      return message?.id === messageItemId;
     });
+  }
+  #assistantCommitState(turnId, messageItemId) {
+    const event = this.#assistantMessageEvent(turnId, messageItemId);
     if (!event || !event.data || typeof event.data !== "object" || Array.isArray(event.data))
       return null;
     const state = event.data.commitState;
     return state === "committed" || state === "provisional" ? state : null;
   }
+  #finalAssistantItem(turnId, messageItemId) {
+    const id = messageItemId.trim();
+    const item = id ? this.ledger.turnItems(turnId).find((candidate) => candidate.id === id) : void 0;
+    const text = item && item.type === "assistant_message" && item.status === "completed" ? normalizeAssistantText(String(item.data.text ?? "")) : "";
+    const event = id ? this.#assistantMessageEvent(turnId, id) : void 0;
+    const turn = this.ledger.turn(turnId);
+    const retryStart = turn && turn.attempt > 1 ? this.ledger.readStream(`turn:${turnId}`).findLast((candidate) => candidate.type === "turn.retry_started" && candidate.data.attempt === turn.attempt) : void 0;
+    if (!item || !text || !event || retryStart && event.seq <= retryStart.seq)
+      throw new Error("completed Turn finalMessageId must reference a readable Assistant Item from the current attempt");
+    return item;
+  }
   #failTurn(turnId, reason) {
     const current = this.ledger.turn(turnId);
     if (!current || current.status !== "in_progress")
@@ -826,8 +836,12 @@ ${history}` } : {} };
     if (type === "message.assistant.completed") {
       const value = data;
       const text = messageTextContent(value.message?.content);
-      if (text)
-        this.#appendTurnItem(turnId, "assistant_message", { text }, actor);
+      if (text) {
+        const id = typeof value.message?.id === "string" ? value.message.id.trim() : "";
+        if (!id)
+          throw new Error("Runner assistant completion is missing a message Item id");
+        this.#appendTurnItem(turnId, "assistant_message", { text }, actor, id);
+      }
     } else if (type === "plan.updated")
       this.#appendTurnItem(turnId, "plan", data, actor);
     else if (type === "message.assistant.delta") {
@@ -1195,7 +1209,7 @@ ${history}` } : {} };
       return agent === "ceo" && role === "ceo";
     return role === "verifier" || role === "audit";
   }
-  #commitTurnGoalWork(turnId, agent, turn, response, raw, sourceWakeId, mailIds, revisionAtStart) {
+  #commitTurnGoalWork(turnId, agent, turn, responseItem, raw, sourceWakeId, mailIds, revisionAtStart) {
     const binding = turn.goalCommitment;
     const goal = this.#goal(binding.goalId);
     if (goal.revision !== binding.goalRevision)
@@ -1206,11 +1220,9 @@ ${history}` } : {} };
     assertTurnOutput(raw);
     const validation = this.#handoffValidations.get(raw.validationToken);
     const execution = this.ledger.turn(turnId);
-    if (!validation || !execution || validation.turnId !== turnId || validation.attemptId !== raw.validationAttemptId || this.#handoffAttemptSeq.get(turnId) !== raw.validationAttemptId || validation.agent !== agent || validation.attempt !== execution.attempt || validation.leaseToken !== execution.leaseToken || validation.goalId !== goal.id || validation.goalRevision !== goal.revision || validation.message !== response || validation.handoff.outcome !== raw.handoff.outcome || !isSameNumbers(validation.handoff.evidence, raw.handoff.evidence))
+    const response = normalizeAssistantText(String(responseItem.data.text ?? ""));
+    if (!validation || !execution || validation.turnId !== turnId || validation.attemptId !== raw.validationAttemptId || this.#handoffAttemptSeq.get(turnId) !== raw.validationAttemptId || validation.agent !== agent || validation.attempt !== execution.attempt || validation.leaseToken !== execution.leaseToken || validation.goalId !== goal.id || validation.goalRevision !== goal.revision || validation.messageItemId !== responseItem.id || validation.message !== response || validation.handoff.outcome !== raw.handoff.outcome || !isSameNumbers(validation.handoff.evidence, raw.handoff.evidence))
       throw new Error("Handoff validation token is stale or does not match this Turn result");
-    const responseItem = [...this.ledger.turnItems(turnId)].reverse().find((item2) => item2.type === "assistant_message" && item2.status === "completed" && item2.data.text === validation.message);
-    if (!responseItem)
-      throw new Error("accepted Handoff response was not recorded in the Turn");
     const output = this.#committedTurnOutput(raw, binding);
     assertHandoff(output.handoff);
     const now = this.#now();
@@ -1341,7 +1353,8 @@ ${workText}`, activeGoal: turn.activeGoal, goalCommitment: turn.goalCommitment,
     const input = asRecord(params);
     if (method === "goal.handoff.validate") {
       const candidate = String(input.candidateMessage ?? "");
-      this.ledger.appendEvent({ streamId: `turn:${turnId}`, ts: this.#now(), actor: agent, type: "rpc.goal.handoff.validate", data: { attemptId: handoffAttemptId, handoff: input.handoff ?? null, candidateMessagePresent: Boolean(candidate.trim()), candidateMessageChars: candidate.length }, ignorable: true });
+      const candidateMessageId = String(input.candidateMessageId ?? "");
+      this.ledger.appendEvent({ streamId: `turn:${turnId}`, ts: this.#now(), actor: agent, type: "rpc.goal.handoff.validate", data: { attemptId: handoffAttemptId, handoff: input.handoff ?? null, candidateMessageId, candidateMessagePresent: Boolean(candidate.trim()), candidateMessageChars: candidate.length }, ignorable: true });
       return this.#validateHandoffDraft(turnId, handoffAttemptId, agent, execution, context, input);
     }
     const profile = this.#profiles.get(agent) ?? { agent, role: "child" };
@@ -1480,17 +1493,19 @@ ${workText}`, activeGoal: turn.activeGoal, goalCommitment: turn.goalCommitment,
   #validateHandoffDraft(turnId, attemptId, agent, execution, context, input) {
     if (!context.goalCommitment || execution.goalId === null)
       return { accepted: false, fatal: true, attemptId, issues: [{ code: "turn_not_committed", message: "This Turn no longer has a Goal commitment." }] };
-    const request = { handoff: input.handoff ?? null, candidateMessage: String(input.candidateMessage ?? "") };
+    const request = { handoff: input.handoff ?? null, candidateMessageId: String(input.candidateMessageId ?? "").trim(), candidateMessage: String(input.candidateMessage ?? "") };
     const issues = [];
     try {
       assertAgentHandoff(request.handoff);
     } catch {
       issues.push({ code: "handoff_invalid", message: "Handoff requires a valid outcome and at least one evidence event." });
     }
-    const existingMessage = [...this.ledger.turnItems(turnId)].reverse().find((item) => item.type === "assistant_message" && item.status === "completed" && typeof item.data.text === "string" && Boolean(item.data.text.trim()));
-    const message = normalizeAssistantText(request.candidateMessage) || normalizeAssistantText(String(existingMessage?.data?.text ?? ""));
-    if (!message)
-      issues.push({ code: "message_missing", message: "This committed Turn needs a readable assistant message before it can finish." });
+    const message = normalizeAssistantText(request.candidateMessage);
+    const existingMessage = request.candidateMessageId ? this.ledger.turnItems(turnId).find((item) => item.id === request.candidateMessageId) : void 0;
+    if (!request.candidateMessageId || !message)
+      issues.push({ code: "message_missing", message: "This committed Turn needs a readable assistant message Item before it can finish." });
+    else if (existingMessage && (existingMessage.type !== "assistant_message" || existingMessage.status !== "completed" || normalizeAssistantText(String(existingMessage.data.text ?? "")) !== message))
+      issues.push({ code: "message_mismatch", message: "Handoff message identity does not match its assistant Item." });
     const goal = this.ledger.goal(context.goalCommitment.goalId);
     if (!goal || goal.phase !== "active" || goal.owner !== agent || goal.revision !== context.goalCommitment.goalRevision)
       return { accepted: false, fatal: true, attemptId, issues: [{ code: "goal_fence_changed", message: "Goal ownership, phase, or revision changed; this Turn can no longer finish against the old commitment." }] };
@@ -1504,8 +1519,8 @@ ${workText}`, activeGoal: turn.activeGoal, goalCommitment: turn.goalCommitment,
     if (issues.length)
       return { accepted: false, fatal: false, attemptId, issues };
     const token = randomUUID();
-    this.#handoffValidations.set(token, { turnId, attemptId, agent, attempt: execution.attempt, leaseToken: execution.leaseToken, goalId: goal.id, goalRevision: goal.revision, message, handoff: { outcome: request.handoff.outcome, evidence: [...request.handoff.evidence] } });
-    return { accepted: true, fatal: false, attemptId, token, goalId: goal.id, goalRevision: goal.revision };
+    this.#handoffValidations.set(token, { turnId, attemptId, agent, attempt: execution.attempt, leaseToken: execution.leaseToken, goalId: goal.id, goalRevision: goal.revision, messageItemId: request.candidateMessageId, message, handoff: { outcome: request.handoff.outcome, evidence: [...request.handoff.evidence] } });
+    return { accepted: true, fatal: false, attemptId, token, goalId: goal.id, goalRevision: goal.revision, messageItemId: request.candidateMessageId };
   }
   #beginHandoffAttempt(turnId) {
     this.#invalidateHandoffTokens(turnId);