fix(backend): stop discarding step_complete's handoff before the next step reads it (#3446)

Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com>
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
This commit is contained in:
Henry
2026-09-09 02:57:45 +08:00
committed by GitHub
parent 7e2df645c2
commit ad32c6b2cd
50 changed files with 3921 additions and 143 deletions
+18 -4
View File
@@ -2316,12 +2316,14 @@ func (h *Handlers) handleStepComplete(ctx context.Context, msg *ws.Message) (*ws
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "workflow step changed before signal was recorded", nil)
}
boundedHandoff, handoffTruncated := boundStepCompletionSignalField(strings.TrimSpace(req.Handoff))
boundedBlockers, blockersTruncated := boundStepCompletionSignalField(strings.TrimSpace(req.Blockers))
signal := models.PendingStepCompletionSignal{
StepID: launchStepID,
Source: models.StepCompletionSourceAgent,
Summary: strings.TrimSpace(req.Summary),
Handoff: strings.TrimSpace(req.Handoff),
Blockers: strings.TrimSpace(req.Blockers),
Handoff: boundedHandoff,
Blockers: boundedBlockers,
SignaledAt: time.Now().UTC(),
}
stored, err := h.claimStepCompletionSignal(ctx, req.TaskID, req.SessionID, launchStepID, signal)
@@ -2353,11 +2355,23 @@ func (h *Handlers) handleStepComplete(ctx context.Context, msg *ws.Message) (*ws
return errMsg, err
}
return ws.NewResponse(msg.ID, msg.Action, map[string]interface{}{
response := map[string]interface{}{
"accepted": true,
"step_id": task.WorkflowStepID,
"signaled_at": signal.SignaledAt,
})
}
var truncatedFields []string
if handoffTruncated {
truncatedFields = append(truncatedFields, "handoff")
}
if blockersTruncated {
truncatedFields = append(truncatedFields, "blockers")
}
if len(truncatedFields) > 0 {
response["truncated"] = truncatedFields
response["truncation_limit_bytes"] = stepCompletionSignalFieldLimitBytes
}
return ws.NewResponse(msg.ID, msg.Action, response)
}
func (h *Handlers) stepCompletionLaunchStep(ctx context.Context, sessionID, fallback string) (string, error) {
@@ -0,0 +1,29 @@
package handlers
import (
"github.com/kandev/kandev/internal/common/truncate"
)
// stepCompletionSignalFieldLimitBytes is the fixed, compiled-in ceiling for
// the step_complete_kandev handoff and blockers arguments. It is inclusive of
// stepCompletionSignalTruncationMarker and applies to each field
// independently, so it is never configurable at runtime or per deployment.
const stepCompletionSignalFieldLimitBytes = 8192
// stepCompletionSignalTruncationMarker is appended to a truncated handoff or
// blockers value so a later reader cannot mistake a cut value for a complete
// one. Its byte length (33) is subtracted from the ceiling before cutting.
const stepCompletionSignalTruncationMarker = "[truncated: over 8192-byte limit]"
// boundStepCompletionSignalField bounds an already-trimmed handoff or
// blockers value to stepCompletionSignalFieldLimitBytes, measured as UTF-8
// byte length. A value at or under the ceiling is stored byte-for-byte; a
// larger value is cut on a UTF-8 character boundary and the fixed marker is
// appended, so the stored result is never larger than the ceiling.
func boundStepCompletionSignalField(trimmed string) (bounded string, wasTruncated bool) {
if len(trimmed) <= stepCompletionSignalFieldLimitBytes {
return trimmed, false
}
prefixLimit := stepCompletionSignalFieldLimitBytes - len(stepCompletionSignalTruncationMarker)
return truncate.UTF8(trimmed, prefixLimit) + stepCompletionSignalTruncationMarker, true
}
@@ -0,0 +1,60 @@
package handlers
import (
"strings"
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
// TestBoundStepCompletionSignalField_Boundary covers AC-003.2's exact
// boundary pair: 8,192 bytes stores whole, 8,193 truncates.
func TestBoundStepCompletionSignalField_Boundary(t *testing.T) {
atLimit := strings.Repeat("a", stepCompletionSignalFieldLimitBytes)
bounded, truncated := boundStepCompletionSignalField(atLimit)
assert.False(t, truncated)
assert.Equal(t, atLimit, bounded)
assert.Len(t, bounded, stepCompletionSignalFieldLimitBytes)
overLimit := strings.Repeat("a", stepCompletionSignalFieldLimitBytes+1)
bounded, truncated = boundStepCompletionSignalField(overLimit)
assert.True(t, truncated)
assert.LessOrEqual(t, len(bounded), stepCompletionSignalFieldLimitBytes)
assert.True(t, strings.HasSuffix(bounded, stepCompletionSignalTruncationMarker))
}
// TestBoundStepCompletionSignalField_MultiByteBoundary ensures a cut landing
// mid-rune is avoided: the retained prefix must be valid UTF-8 and the total
// length (marker included) must stay within the ceiling (AC-003.3).
func TestBoundStepCompletionSignalField_MultiByteBoundary(t *testing.T) {
// Each rune is 3 bytes (e.g. "世"), chosen so a naive byte-count cut would
// very likely split a character.
rune3 := "世"
require.Len(t, rune3, 3)
overLimit := strings.Repeat(rune3, (stepCompletionSignalFieldLimitBytes/3)+50)
bounded, truncated := boundStepCompletionSignalField(overLimit)
require.True(t, truncated)
assert.LessOrEqual(t, len(bounded), stepCompletionSignalFieldLimitBytes)
assert.True(t, strings.HasSuffix(bounded, stepCompletionSignalTruncationMarker))
prefix := strings.TrimSuffix(bounded, stepCompletionSignalTruncationMarker)
assert.True(t, utf8ValidString(prefix), "retained prefix must not split a multi-byte character")
}
func utf8ValidString(s string) bool {
for _, r := range s {
if r == '�' {
return false
}
}
return true
}
// TestBoundStepCompletionSignalField_WellUnderLimit is the trivial pass-
// through case: a short value is stored unchanged with no marker.
func TestBoundStepCompletionSignalField_WellUnderLimit(t *testing.T) {
bounded, truncated := boundStepCompletionSignalField("short handoff")
assert.False(t, truncated)
assert.Equal(t, "short handoff", bounded)
}
@@ -378,6 +378,53 @@ func TestHandleStepComplete_DedupRunningNoRepublish(t *testing.T) {
assert.Equal(t, before, after, "already_signaled dedup must not increment workflow_step_completion_signal_received_total")
}
// TestHandleStepComplete_DuplicateCallDoesNotOverwriteHandoffOrBlockers covers
// AC-001.13: a rejected duplicate call must not mutate the already-persisted
// bag, even when the second call's handoff/blockers differ from the first's.
// Only the first accepted call's content may ever reach the single-slot carry
// token or the audit metadata — a duplicate silently replacing it would let a
// second, unvetted call clobber content already committed to the transition.
func TestHandleStepComplete_DuplicateCallDoesNotOverwriteHandoffOrBlockers(t *testing.T) {
ctx := context.Background()
svc, repo := newTestTaskService(t)
seedStepCompleteTarget(t, repo, "task-dup-overwrite", "session-dup-overwrite", "step-1", models.TaskSessionStateRunning)
require.NoError(t, repo.SetSessionMetadataKey(ctx, "session-dup-overwrite", models.SessionMetaKeyPendingStepCompletion, models.PendingStepCompletionSignal{
StepID: "step-1",
Source: models.StepCompletionSourceAgent,
Summary: "first call",
Handoff: "first handoff",
Blockers: "first blockers",
SignaledAt: time.Now().UTC(),
}))
seedAgentProfileSnapshot(t, repo, "session-dup-overwrite", "claude-dup-overwrite")
bus := &mcpRecordingEventBus{}
h := newStepCompleteHandler(t, svc, repo, bus)
msg := makeWSMessage(t, ws.ActionMCPStepComplete, map[string]interface{}{
"task_id": "task-dup-overwrite",
"session_id": "session-dup-overwrite",
"summary": "second call (same step)",
"handoff": "second handoff should not land",
"blockers": "second blockers should not land",
})
resp, err := h.handleStepComplete(ctx, msg)
require.NoError(t, err)
require.NotNil(t, resp)
var payload map[string]interface{}
require.NoError(t, json.Unmarshal(resp.Payload, &payload))
assert.Equal(t, false, payload["accepted"])
assert.Equal(t, "already_signaled", payload["reason"])
session, err := repo.GetTaskSession(ctx, "session-dup-overwrite")
require.NoError(t, err)
bag, ok := models.LoadPendingStepSignal(session.Metadata)
require.True(t, ok, "expected the original bag entry to still be present")
assert.Equal(t, "first call", bag.Summary, "duplicate call must not overwrite the persisted summary")
assert.Equal(t, "first handoff", bag.Handoff, "duplicate call must not overwrite the persisted handoff")
assert.Equal(t, "first blockers", bag.Blockers, "duplicate call must not overwrite the persisted blockers")
}
// TestHandleStepComplete_DedupWaitingRepublishes covers the retry-after-
// publish-failure path. When the session is WAITING_FOR_INPUT, the bag is
// already persisted but the orchestrator subscriber may have never fired
@@ -0,0 +1,170 @@
package handlers
import (
"context"
"encoding/json"
"strings"
"testing"
"time"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"github.com/kandev/kandev/internal/task/models"
ws "github.com/kandev/kandev/pkg/websocket"
)
// TestHandleStepComplete_TruncatesOversizedHandoff covers AC-003.1/003.2/003.4:
// an oversized handoff never strands the step (the call is still accepted and
// stored bounded), and the result reports which argument was truncated.
func TestHandleStepComplete_TruncatesOversizedHandoff(t *testing.T) {
svc, repo := newTestTaskService(t)
seedStepCompleteTarget(t, repo, "task-trunc", "session-trunc", "step-1", models.TaskSessionStateRunning)
bus := &mcpRecordingEventBus{}
h := newStepCompleteHandler(t, svc, repo, bus)
oversized := strings.Repeat("h", stepCompletionSignalFieldLimitBytes+500)
msg := makeWSMessage(t, ws.ActionMCPStepComplete, map[string]interface{}{
"task_id": "task-trunc",
"session_id": "session-trunc",
"summary": "done",
"handoff": oversized,
})
resp, err := h.handleStepComplete(context.Background(), msg)
require.NoError(t, err)
var payload map[string]interface{}
require.NoError(t, json.Unmarshal(resp.Payload, &payload))
assert.Equal(t, true, payload["accepted"], "an oversized value must never strand the step")
truncatedRaw, ok := payload["truncated"].([]interface{})
require.True(t, ok, "expected truncated array in response")
assert.Equal(t, []interface{}{"handoff"}, truncatedRaw)
assert.Equal(t, float64(stepCompletionSignalFieldLimitBytes), payload["truncation_limit_bytes"])
session, err := repo.GetTaskSession(context.Background(), "session-trunc")
require.NoError(t, err)
bag, ok := models.LoadPendingStepSignal(session.Metadata)
require.True(t, ok)
assert.LessOrEqual(t, len(bag.Handoff), stepCompletionSignalFieldLimitBytes)
assert.True(t, strings.HasSuffix(bag.Handoff, stepCompletionSignalTruncationMarker))
}
// TestHandleStepComplete_WhitespacePaddedHandoffTrimsBeforeMeasuring covers
// AC-003.2's trim-first ordering: a handoff that is oversized BEFORE
// trimming but at or under the ceiling AFTER trimming must be stored whole,
// with no truncation reported.
func TestHandleStepComplete_WhitespacePaddedHandoffTrimsBeforeMeasuring(t *testing.T) {
svc, repo := newTestTaskService(t)
seedStepCompleteTarget(t, repo, "task-trim-first", "session-trim-first", "step-1", models.TaskSessionStateRunning)
bus := &mcpRecordingEventBus{}
h := newStepCompleteHandler(t, svc, repo, bus)
atLimit := strings.Repeat("h", stepCompletionSignalFieldLimitBytes)
padded := strings.Repeat(" ", 500) + atLimit + strings.Repeat("\n", 500)
msg := makeWSMessage(t, ws.ActionMCPStepComplete, map[string]interface{}{
"task_id": "task-trim-first",
"session_id": "session-trim-first",
"summary": "done",
"handoff": padded,
})
resp, err := h.handleStepComplete(context.Background(), msg)
require.NoError(t, err)
var payload map[string]interface{}
require.NoError(t, json.Unmarshal(resp.Payload, &payload))
assert.Equal(t, true, payload["accepted"])
_, hasTruncated := payload["truncated"]
assert.False(t, hasTruncated, "trimmed value is exactly at the ceiling and must not report truncation")
session, err := repo.GetTaskSession(context.Background(), "session-trim-first")
require.NoError(t, err)
bag, ok := models.LoadPendingStepSignal(session.Metadata)
require.True(t, ok)
assert.Equal(t, atLimit, bag.Handoff, "stored value must equal the trimmed input exactly, whole and unmarked")
}
// TestHandleStepComplete_TruncatesBothFieldsInOrder covers AC-003.5: when
// both handoff and blockers truncate, the array lists "handoff" before
// "blockers".
func TestHandleStepComplete_TruncatesBothFieldsInOrder(t *testing.T) {
svc, repo := newTestTaskService(t)
seedStepCompleteTarget(t, repo, "task-trunc2", "session-trunc2", "step-1", models.TaskSessionStateRunning)
bus := &mcpRecordingEventBus{}
h := newStepCompleteHandler(t, svc, repo, bus)
oversized := strings.Repeat("x", stepCompletionSignalFieldLimitBytes+1)
msg := makeWSMessage(t, ws.ActionMCPStepComplete, map[string]interface{}{
"task_id": "task-trunc2",
"session_id": "session-trunc2",
"summary": "done",
"handoff": oversized,
"blockers": oversized,
})
resp, err := h.handleStepComplete(context.Background(), msg)
require.NoError(t, err)
var payload map[string]interface{}
require.NoError(t, json.Unmarshal(resp.Payload, &payload))
assert.Equal(t, []interface{}{"handoff", "blockers"}, payload["truncated"])
}
// TestHandleStepComplete_NoTruncationOmitsFields covers AC-003.5's converse:
// when nothing was truncated, both fields are entirely absent from the
// response rather than present with empty/zero values.
func TestHandleStepComplete_NoTruncationOmitsFields(t *testing.T) {
svc, repo := newTestTaskService(t)
seedStepCompleteTarget(t, repo, "task-notrunc", "session-notrunc", "step-1", models.TaskSessionStateRunning)
bus := &mcpRecordingEventBus{}
h := newStepCompleteHandler(t, svc, repo, bus)
msg := makeWSMessage(t, ws.ActionMCPStepComplete, map[string]interface{}{
"task_id": "task-notrunc",
"session_id": "session-notrunc",
"summary": "done",
"handoff": "short",
})
resp, err := h.handleStepComplete(context.Background(), msg)
require.NoError(t, err)
var payload map[string]interface{}
require.NoError(t, json.Unmarshal(resp.Payload, &payload))
_, hasTruncated := payload["truncated"]
_, hasLimit := payload["truncation_limit_bytes"]
assert.False(t, hasTruncated)
assert.False(t, hasLimit)
}
// TestHandleStepComplete_DuplicateReportsNoTruncation covers AC-003.5a: a
// call rejected as a duplicate keeps its existing rejection shape and never
// reports truncation, even though its (discarded) values would have
// truncated.
func TestHandleStepComplete_DuplicateReportsNoTruncation(t *testing.T) {
ctx := context.Background()
svc, repo := newTestTaskService(t)
seedStepCompleteTarget(t, repo, "task-dup-trunc", "session-dup-trunc", "step-1", models.TaskSessionStateRunning)
require.NoError(t, repo.SetSessionMetadataKey(ctx, "session-dup-trunc", models.SessionMetaKeyPendingStepCompletion, models.PendingStepCompletionSignal{
StepID: "step-1",
Source: models.StepCompletionSourceAgent,
Summary: "first call",
SignaledAt: time.Now().UTC(),
}))
bus := &mcpRecordingEventBus{}
h := newStepCompleteHandler(t, svc, repo, bus)
oversized := strings.Repeat("y", stepCompletionSignalFieldLimitBytes+1)
msg := makeWSMessage(t, ws.ActionMCPStepComplete, map[string]interface{}{
"task_id": "task-dup-trunc",
"session_id": "session-dup-trunc",
"summary": "second call",
"handoff": oversized,
})
resp, err := h.handleStepComplete(ctx, msg)
require.NoError(t, err)
var payload map[string]interface{}
require.NoError(t, json.Unmarshal(resp.Payload, &payload))
assert.Equal(t, false, payload["accepted"])
assert.Equal(t, "already_signaled", payload["reason"])
_, hasTruncated := payload["truncated"]
assert.False(t, hasTruncated, "a rejected duplicate must report no truncation")
}
+3 -3
View File
@@ -1706,10 +1706,10 @@ func (s *Server) updateRepositoryBaseBranchHandler() server.ToolHandlerFunc {
func (s *Server) registerStepCompleteTool() {
s.mcpServer.AddTool(
mcp.NewTool("step_complete_kandev",
mcp.WithDescription(`Signal that every requirement for the current workflow step is complete. Call this as the step's final action; do not call before asking the user, during partial work, or with an unresolved blocker. The signal is idempotent within a step, and any configured transition runs asynchronously at turn end. A new user message cancels a pending signal. The summary is shown to the user and may be forwarded to the next step.`),
mcp.WithDescription(`Signal that every requirement for the current workflow step is complete. Call this as the step's final action; do not call before asking the user or during partial work. If you cannot make further progress without input, describe the issue in blockers. The signal is idempotent within a step, and any configured transition runs asynchronously at turn end. A new user message cancels a pending signal. The summary is shown to the user and is recorded on the step-transition history.`),
mcp.WithString("summary", mcp.Required(), mcp.Description("One-paragraph plain-text summary of what was done in this step. Shown to the user.")),
mcp.WithString("handoff", mcp.Description("Optional context the next step's agent will need to pick up where you left off (decisions, open files, follow-ups).")),
mcp.WithString("blockers", mcp.Description("Optional list of known unresolved issues. Use sparingly — only when the step is complete in the sense that you cannot make further progress without input, not for normal partial work.")),
mcp.WithString("handoff", mcp.Description("Optional context for the immediately-following step's agent, delivered once in that step's first prompt and not carried beyond it. Up to 8,192 bytes; longer values are truncated.")),
mcp.WithString("blockers", mcp.Description("Optional list of known unresolved issues. Recorded on this step's transition history, not delivered to the next step's agent — do not use it to pass context forward. Use sparingly, only when you cannot make further progress without input. Up to 8,192 bytes; longer values are truncated.")),
),
s.wrapHandler("step_complete_kandev", s.stepCompleteHandler()),
)
@@ -0,0 +1,61 @@
package mcp
import (
"strings"
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
// TestStepCompleteToolDescription_DeliveryExtent covers REQ-004: the
// registered descriptions must state the actual delivered behavior (handoff
// is delivered once, to the immediately-next step, and not carried further;
// blockers is recorded on the transition record and never delivered to the
// next step's agent), state the byte ceiling, and must not claim a
// forwarding behavior the mechanism does not provide.
func TestStepCompleteToolDescription_DeliveryExtent(t *testing.T) {
s := newTaskModeServer(t, &testBackend{}, "task-current")
tool, ok := s.mcpServer.ListTools()["step_complete_kandev"]
require.True(t, ok)
var handoffDesc, blockersDesc string
raw, ok := tool.Tool.InputSchema.Properties["handoff"].(map[string]interface{})
require.True(t, ok, "expected handoff property schema")
handoffDesc, _ = raw["description"].(string)
raw, ok = tool.Tool.InputSchema.Properties["blockers"].(map[string]interface{})
require.True(t, ok, "expected blockers property schema")
blockersDesc, _ = raw["description"].(string)
// AC-004.1: handoff's description states one-time, immediately-next-step
// delivery and that it is not carried beyond that step.
assert.Contains(t, handoffDesc, "once")
assert.Contains(t, handoffDesc, "not carried beyond")
// AC-004.2: blockers' description states it is recorded on the transition
// record and NOT delivered to the next step's agent.
assert.Contains(t, blockersDesc, "not delivered to the next step")
// AC-004.3: both descriptions state the byte ceiling.
assert.Contains(t, handoffDesc, "8,192")
assert.Contains(t, blockersDesc, "8,192")
// AC-004.4: the top-level description must not claim handoff/blockers are
// forwarded to the next step (the mechanism does not deliver blockers at
// all, and handoff only survives one hop).
assert.NotContains(t, strings.ToLower(tool.Tool.Description), "forwarded to the next step")
// AC-004.5: both arguments remain registered, optional, and string-typed.
_, handoffRequired := requiredSet(tool.Tool.InputSchema.Required)["handoff"]
_, blockersRequired := requiredSet(tool.Tool.InputSchema.Required)["blockers"]
assert.False(t, handoffRequired)
assert.False(t, blockersRequired)
}
func requiredSet(required []string) map[string]struct{} {
set := make(map[string]struct{}, len(required))
for _, name := range required {
set[name] = struct{}{}
}
return set
}
@@ -210,6 +210,8 @@ func TestFallbackFreshLaunch_CoordinatorCancellationWinsBeforeResetWrite(t *test
"session-fallback-stop-race",
"replacement prompt",
false,
"",
false,
nil,
nil,
nil,
@@ -263,6 +265,8 @@ func TestFallbackFreshLaunch_DoesNotResetCancellationObservedBeforeGuard(t *test
"session-fallback-already-stopped",
"replacement prompt",
false,
"",
false,
nil,
nil,
nil,
@@ -789,11 +789,12 @@ func (s *Service) recordQueuedUserMessage(ctx context.Context, queuedMsg *messag
}
references := entityrefs.NormalizePersisted(queuedMsg.Metadata[messagequeue.MetadataEntityReferences])
promptContent := AppendEntityReferenceContext(queuedMsg.Content, references)
promptContent = appendStepHandoffToPrompt(promptContent, stepHandoffFromQueuedMetadata(queuedMsg.Metadata))
meta := NewUserMessageMeta().
WithPlanMode(queuedMsg.PlanMode).
WithAttachments(attachments).
WithEntityReferences(references)
metaMap := mergeMetadata(meta.ToMap(), metadataWithoutEntityReferences(queuedMsg.Metadata))
metaMap := mergeMetadata(meta.ToMap(), metadataWithoutQueueOnlyKeys(queuedMsg.Metadata))
if err := s.messageCreator.CreateUserMessage(ctx, queuedMsg.TaskID, promptContent, queuedMsg.SessionID, turnID, metaMap); err != nil {
s.logger.Error("failed to create user message for queued message", zap.String("session_id", queuedMsg.SessionID), zap.Error(err))
return err
@@ -865,6 +866,7 @@ func (s *Service) executeQueuedMessageWithReservation(
}
references := entityrefs.NormalizePersisted(queuedMsg.Metadata[messagequeue.MetadataEntityReferences])
promptContent := AppendEntityReferenceContext(queuedMsg.Content, references)
promptContent = appendStepHandoffToPrompt(promptContent, stepHandoffFromQueuedMetadata(queuedMsg.Metadata))
// Create user messages for ordinary queue entries now. Lifecycle entries
// persist their visible message only after the final active-task claim.
@@ -1153,13 +1155,19 @@ func markQueuedUserMessageRecorded(queuedMsg *messagequeue.QueuedMessage) {
queuedMsg.Metadata[metaKeyUserMessageRecorded] = true
}
func metadataWithoutEntityReferences(metadata map[string]interface{}) map[string]interface{} {
// metadataWithoutQueueOnlyKeys strips queue-transport-only keys before a
// queued message's metadata is persisted onto a chat message row:
// entity references are re-added via WithEntityReferences, and a carried
// completion handoff (messagequeue.MetadataStepHandoff) is already folded
// into the recorded content by the caller, so neither belongs in the row's
// own stored metadata.
func metadataWithoutQueueOnlyKeys(metadata map[string]interface{}) map[string]interface{} {
if len(metadata) == 0 {
return nil
}
copy := make(map[string]interface{}, len(metadata))
for key, value := range metadata {
if key != messagequeue.MetadataEntityReferences {
if key != messagequeue.MetadataEntityReferences && key != messagequeue.MetadataStepHandoff {
copy[key] = value
}
}
@@ -586,7 +586,7 @@ func TestAutoStartCreatedLaunch_QueuesPromptWhenAgentAlreadyRunning(t *testing.T
t.Fatalf("set session profile: %v", err)
}
err = svc.autoStartStepPrompt(ctx, taskID, session, step, "Do the work", false, true)
err = svc.autoStartStepPrompt(ctx, taskID, session, step, "Do the work", false, true, nil)
if err == nil {
t.Fatal("expected autoStartStepPrompt to return the launch error")
}
@@ -664,7 +664,7 @@ func TestAutoStartCreatedLaunch_DoesNotRestoreHandoffAfterQueueingMergedPrompt(t
t.Fatalf("seed handoff message: %v", err)
}
err = svc.autoStartStepPrompt(ctx, taskID, session, step, autoStart, false, true)
err = svc.autoStartStepPrompt(ctx, taskID, session, step, autoStart, false, true, nil)
if err == nil {
t.Fatal("expected autoStartStepPrompt to return the launch error")
}
@@ -158,7 +158,7 @@ func TestWorkflowAutoStartCreatedNonEmptyPromptPreservesQueuedHandoff(t *testing
if err := fixture.svc.autoStartStepPrompt(
context.Background(), fixture.taskID, fixture.session, fixture.step,
fixture.step.Prompt, false, true,
fixture.step.Prompt, false, true, nil,
); err != nil {
t.Fatalf("autoStartStepPrompt returned error: %v", err)
}
@@ -228,7 +228,7 @@ func TestWorkflowAutoStartPlanModeOnlyPromptForCreatedSession(t *testing.T) {
}
if err := fixture.svc.autoStartStepPrompt(
context.Background(), fixture.taskID, fixture.session, fixture.step, "", true, true,
context.Background(), fixture.taskID, fixture.session, fixture.step, "", true, true, nil,
); err != nil {
t.Fatalf("autoStartStepPrompt returned error: %v", err)
}
@@ -298,7 +298,7 @@ func TestWorkflowAutoStartAttachmentOnlyHandoffIsRecorded(t *testing.T) {
if err := fixture.svc.autoStartStepPrompt(
context.Background(), fixture.taskID, fixture.session, fixture.step,
"", false, true,
"", false, true, nil,
); err != nil {
t.Fatalf("autoStartStepPrompt returned error: %v", err)
}
@@ -2,6 +2,7 @@ package orchestrator
import (
"context"
"strings"
"go.uber.org/zap"
@@ -82,17 +83,26 @@ func (s *Service) recordAutoStepTransition(ctx context.Context, sessionID, fromS
"signal_source": signal.Source,
"signal_summary": signal.Summary,
}
if handoff := strings.TrimSpace(signal.Handoff); handoff != "" {
metadata["signal_handoff"] = handoff
}
if blockers := strings.TrimSpace(signal.Blockers); blockers != "" {
metadata["signal_blockers"] = blockers
}
}
trigger := wfmodels.StepTransitionTriggerAutoComplete
if len(triggers) > 0 && triggers[0] != "" {
trigger = triggers[0]
}
if asyncRecorder, ok := s.stepHistoryRecorder.(asyncStepHistoryRecorder); ok {
asyncRecorder.EnqueueStepTransition(sessionID, fromStepID, toStepID, trigger, nil, metadata)
return
if asyncRecorder.EnqueueStepTransition(sessionID, fromStepID, toStepID, trigger, nil, metadata) {
return
}
// A full or closed worker must not discard a consumed signal's audit
// payload. Fall through to the bounded synchronous write below.
}
// Test doubles can remain synchronous. Production workflow service uses the
// queue branch above.
// Test doubles remain synchronous, and production falls back here when its
// bounded worker cannot accept the row.
writeCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), constants.StepHistoryWriteTimeout)
defer cancel()
if err := s.stepHistoryRecorder.CreateStepTransition(
@@ -119,12 +129,14 @@ func (s *Service) recordManualStepTransition(ctx context.Context, sessionID, fro
}
// Test doubles can remain synchronous. Production workflow service uses the
// queue branch below.
if asyncRecorder, ok := s.stepHistoryRecorder.(asyncStepHistoryRecorder); ok {
if asyncRecorder.EnqueueStepTransition(sessionID, fromStepID, toStepID, wfmodels.StepTransitionTriggerManual, nil, nil) {
return
}
// Fall through when the bounded worker is full or closed.
}
writeCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), constants.StepHistoryWriteTimeout)
defer cancel()
if asyncRecorder, ok := s.stepHistoryRecorder.(asyncStepHistoryRecorder); ok {
asyncRecorder.EnqueueStepTransition(sessionID, fromStepID, toStepID, wfmodels.StepTransitionTriggerManual, nil, nil)
return
}
if err := s.stepHistoryRecorder.CreateStepTransition(
writeCtx, sessionID, fromStepID, toStepID, wfmodels.StepTransitionTriggerManual, nil, nil,
); err != nil {
@@ -81,6 +81,15 @@ type taskMetadataKeySetterIfNoActiveSession interface {
SetTaskMetadataKeyIfNoActiveSession(context.Context, string, string, interface{}) (bool, error)
}
// taskMetadataCarryTaker is the compare-and-swap claim behind the
// completion-handoff carry token. A repository that lacks it degrades to
// today's behavior (no handoff delivered) rather than erroring.
type taskMetadataCarryTaker interface {
TakeTaskMetadataKeyIfDestinationStep(
ctx context.Context, taskID, key, expectedStepID, expectedStamp string,
) (json.RawMessage, bool, error)
}
type lifecycleTaskMetadataLister interface {
ListTasksWithMetadataKey(context.Context, string) ([]*models.Task, error)
}
@@ -402,6 +411,21 @@ func (s *Service) executeStepTransition(ctx context.Context, taskID, sessionID s
// transition.
task.WorkflowStepID = toStepID
task.UpdatedAt = time.Now().UTC()
// Capture the completion signal before admission and carry its handoff on
// the same task snapshot. A queued destination can be promoted immediately
// after this write, so a post-commit metadata write would leave a race where
// the first prompt starts without its handoff.
var consumedSignal *models.PendingStepCompletionSignal
signalSession, signalErr := s.repo.GetTaskSession(ctx, sessionID)
if signalErr != nil {
s.logger.Warn("failed to load session for step handoff carry",
zap.String("session_id", sessionID), zap.Error(signalErr))
} else if triggerOnEnter && signalSession != nil {
if signal, has := models.LoadPendingStepSignal(signalSession.Metadata); has && signal.StepID == fromStep.ID {
consumedSignal = &signal
}
setStepHandoffCarryMetadata(task, toStepID, consumedSignal)
}
// executeStepTransition's two callers are always a genuine session turn:
// on_turn_complete (triggerOnEnter=true) or on_turn_start (false).
legacyTrigger := engine.TriggerOnTurnStart
@@ -420,13 +444,14 @@ func (s *Service) executeStepTransition(ctx context.Context, taskID, sessionID s
}
queued := task.QueuedForStepID != ""
// Process on_exit only after the transition is durably admitted. Freshly
// load the session since the caller may not have it (legacy path).
// Process on_exit only after the transition is durably admitted. Reload the
// session so side effects use the same fresh snapshot as the old path; the
// earlier signal snapshot was needed only to make carry part of admission.
exitSession, exitErr := s.repo.GetTaskSession(ctx, sessionID)
if exitErr != nil {
s.logger.Warn("failed to load session for on_exit",
zap.String("session_id", sessionID), zap.Error(exitErr))
} else {
} else if exitSession != nil {
s.processOnExit(ctx, taskID, exitSession, fromStep)
}
@@ -447,26 +472,28 @@ func (s *Service) executeStepTransition(ctx context.Context, taskID, sessionID s
if s.workflowStore != nil {
s.workflowStore.pullNextTaskOnVacate(ctx, fromStep.ID, taskID)
}
if queued {
s.setSessionWaitingForInput(ctx, taskID, sessionID)
return
}
// ADR 0015 — record the audit row before the pending signal (if any)
// is cleared below. Only the triggerOnEnter=true (legacy
// on_turn_complete) branch could have consumed a signal; the
// on_turn_start branch records with no signal metadata.
var consumedSignal *models.PendingStepCompletionSignal
if triggerOnEnter && exitSession != nil {
if signal, has := models.LoadPendingStepSignal(exitSession.Metadata); has && signal.StepID == fromStep.ID {
consumedSignal = &signal
}
}
// A queued transition still commits: the task's step already changed
// above, only entry into it is deferred until a queue promotion admits
// the task. So the audit row and any handoff carry token are captured
// here, before the queued check below returns — a later promotion
// dispatches through StartSessionForWorkflowStep, which claims the token
// itself and has no other way to learn one was ever written. Only the
// triggerOnEnter=true (legacy on_turn_complete) branch could have
// consumed a signal; the on_turn_start branch records with no signal
// metadata and never touches the token.
trigger := wfmodels.StepTransitionTriggerTurnStart
if triggerOnEnter {
trigger = wfmodels.StepTransitionTriggerAutoComplete
}
s.recordAutoStepTransition(ctx, sessionID, fromStep.ID, toStepID, consumedSignal, trigger)
if queued {
if triggerOnEnter {
s.clearPendingStepSignalByID(ctx, sessionID)
}
s.setSessionWaitingForInput(ctx, taskID, sessionID)
return
}
if triggerOnEnter {
// ADR 0015 — clear any pending completion-signal bag for the
@@ -3000,7 +3027,10 @@ func (s *Service) processOnEnter(ctx context.Context, taskID string, session *mo
}
s.setSessionWaitingForInput(ctx, taskID, sessionID, session)
s.publishSessionWaitingEvent(ctx, taskID, sessionID, step.ID, session)
s.drainQueuedMessageForPromptableSession(ctx, sessionID)
// This step entry never reaches buildWorkflowEntryPrompt or
// launchAfterOnEnterDispatch (no on_enter actions, no profile switch),
// so a single-use claim helper covers it.
s.drainQueuedMessageForPromptableSessionWithHandoff(ctx, taskID, sessionID, step.ID, newStepHandoffOnce())
return
}
@@ -3041,6 +3071,10 @@ func (s *Service) launchAfterOnEnterDispatch(
) {
sessionID := session.ID
isPassthrough := s.agentManager.IsPassthroughSession(ctx, sessionID)
// One claim for this whole step entry: every branch and replacement
// launch below shares it, so a successful claim's text is reused rather
// than silently lost to a second, always-empty DB attempt.
handoffOnce := newStepHandoffOnce()
var effectivePrompt string
if hasAutoStart || (sessionSwitched && step.Prompt != "") {
var err error
@@ -3062,10 +3096,16 @@ func (s *Service) launchAfterOnEnterDispatch(
// The empty workflow prompt is suppressed for an already-prompted
// session, but a queued handoff may still be the next user input.
// Drain it through the normal executor path so passthrough attachments
// are materialized and the handoff is not stranded in the queue.
s.drainQueuedMessageForPromptableSession(ctx, sessionID)
// are materialized and the handoff is not stranded in the queue. This
// branch still DISPATCHES, so it carries the completion handoff too.
s.drainQueuedMessageForPromptableSessionWithHandoff(ctx, taskID, sessionID, step.ID, handoffOnce)
return
}
// Claimed after the actionability decision above (effectivePrompt was
// non-blank), over content that excludes the handoff text.
effectivePrompt = appendStepHandoffToPrompt(
effectivePrompt, s.resolveStepHandoffText(ctx, handoffOnce, taskID, step.ID, true),
)
if err := s.autoStartPassthroughPrompt(ctx, taskID, session, step.Name, effectivePrompt); err != nil {
s.logger.Error("failed to auto-start passthrough agent for step",
zap.String("task_id", taskID),
@@ -3081,38 +3121,11 @@ func (s *Service) launchAfterOnEnterDispatch(
// When called from applyEngineTransition (on_turn_complete), processOnEnter
// runs in a goroutine and the session is already WAITING_FOR_INPUT, so
// autoStartStepPrompt sends the prompt directly via PromptTask.
if err := s.autoStartStepPrompt(ctx, taskID, session, step, effectivePrompt, hasPlanMode, true); err != nil {
if err := s.autoStartStepPrompt(ctx, taskID, session, step, effectivePrompt, hasPlanMode, true, handoffOnce); err != nil {
if errors.Is(err, errWorkflowAutoStartSessionTerminalized) {
if workflowAutoStartWasCancelled(err) {
s.logger.Info("workflow auto-start cancelled before dispatch; not creating replacement",
zap.String("task_id", taskID), zap.String("session_id", sessionID))
return
}
s.logger.Info("creating fresh workflow session after reused session terminalized",
zap.String("task_id", taskID), zap.String("session_id", sessionID))
replacement, replacementErr := s.createNewSessionForStep(
ctx, taskID, session, session.AgentProfileID,
s.replaceTerminalizedAutoStartSession(
ctx, taskID, taskDescription, session, step, isPassthrough, hasPlanMode, handoffOnce, err,
)
if replacementErr != nil {
s.logger.Error("failed to create replacement after reused session terminalized",
zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.Error(replacementErr))
return
}
replacementPrompt, promptErr := s.buildWorkflowEntryPrompt(
ctx, taskDescription, step, taskID, replacement.ID, isPassthrough,
)
if promptErr != nil {
s.handleWorkflowEntryPromptError(ctx, taskID, replacement, step, promptErr)
return
}
if replacementErr = s.autoStartStepPrompt(
ctx, taskID, replacement, step, replacementPrompt, hasPlanMode, true,
); replacementErr != nil {
s.logger.Error("failed to auto-start replacement after reused session terminalized",
zap.String("task_id", taskID), zap.String("session_id", replacement.ID), zap.Error(replacementErr))
s.setSessionWaitingForInput(ctx, taskID, replacement.ID, replacement)
s.publishSessionWaitingEvent(ctx, taskID, replacement.ID, step.ID, replacement)
}
return
}
s.logger.Error("failed to auto-start agent for step",
@@ -3179,7 +3192,7 @@ func (s *Service) launchAfterOnEnterDispatch(
return
}
if replacementErr = s.autoStartStepPrompt(
asyncCtx, taskID, replacement, step, replacementPrompt, planMode, true,
asyncCtx, taskID, replacement, step, replacementPrompt, planMode, true, handoffOnce,
); replacementErr != nil {
s.logger.Error("failed to auto-start replacement after terminalized profile switch",
zap.String("task_id", taskID), zap.String("session_id", replacement.ID), zap.Error(replacementErr))
@@ -3191,7 +3204,7 @@ func (s *Service) launchAfterOnEnterDispatch(
lock.Unlock()
release()
err := s.autoStartStepPrompt(asyncCtx, taskID, fresh, step, effectivePrompt, planMode, true)
err := s.autoStartStepPrompt(asyncCtx, taskID, fresh, step, effectivePrompt, planMode, true, handoffOnce)
if err != nil {
if errors.Is(err, errWorkflowAutoStartSessionTerminalized) {
if workflowAutoStartWasCancelled(err) {
@@ -3217,7 +3230,7 @@ func (s *Service) launchAfterOnEnterDispatch(
return
}
if replacementErr = s.autoStartStepPrompt(
asyncCtx, taskID, replacement, step, replacementPrompt, planMode, true,
asyncCtx, taskID, replacement, step, replacementPrompt, planMode, true, handoffOnce,
); replacementErr != nil {
s.logger.Error("failed to auto-start replacement after terminalized dispatch",
zap.String("task_id", taskID), zap.String("session_id", replacement.ID), zap.Error(replacementErr))
@@ -3232,7 +3245,7 @@ func (s *Service) launchAfterOnEnterDispatch(
zap.Error(err))
s.setSessionWaitingForInput(asyncCtx, taskID, sessionID, fresh)
s.publishSessionWaitingEvent(asyncCtx, taskID, sessionID, stepID, fresh)
s.drainQueuedMessageForPromptableSession(asyncCtx, sessionID)
s.drainQueuedMessageForPromptableSessionWithHandoff(asyncCtx, taskID, sessionID, stepID, handoffOnce)
}
}()
return
@@ -3246,12 +3259,55 @@ func (s *Service) launchAfterOnEnterDispatch(
// so user-queued messages would otherwise stick forever on transitions to
// steps without auto_start_agent (e.g. Review). Drain here to match the
// pre-#677 behavior where handleAgentReady always drained after returning
// from inline processOnEnter.
s.drainQueuedMessageForPromptableSession(ctx, sessionID)
// from inline processOnEnter. This is the ordinary no-on_enter-actions
// step shape, so it carries the completion handoff too.
s.drainQueuedMessageForPromptableSessionWithHandoff(ctx, taskID, sessionID, step.ID, handoffOnce)
}
}
// replaceTerminalizedAutoStartSession handles the ACP auto-start path's
// errWorkflowAutoStartSessionTerminalized outcome: an explicit cancellation
// stays terminal, otherwise a fresh replacement session is created and
// launched with the same shared handoffOnce so the completion handoff (if any
// was already claimed) is not silently dropped.
func (s *Service) replaceTerminalizedAutoStartSession(
ctx context.Context, taskID, taskDescription string, session *models.TaskSession, step *wfmodels.WorkflowStep,
isPassthrough, hasPlanMode bool, handoffOnce *stepHandoffOnce, err error,
) {
sessionID := session.ID
if workflowAutoStartWasCancelled(err) {
s.logger.Info("workflow auto-start cancelled before dispatch; not creating replacement",
zap.String("task_id", taskID), zap.String("session_id", sessionID))
return
}
s.logger.Info("creating fresh workflow session after reused session terminalized",
zap.String("task_id", taskID), zap.String("session_id", sessionID))
replacement, replacementErr := s.createNewSessionForStep(
ctx, taskID, session, session.AgentProfileID,
)
if replacementErr != nil {
s.logger.Error("failed to create replacement after reused session terminalized",
zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.Error(replacementErr))
return
}
replacementPrompt, promptErr := s.buildWorkflowEntryPrompt(
ctx, taskDescription, step, taskID, replacement.ID, isPassthrough,
)
if promptErr != nil {
s.handleWorkflowEntryPromptError(ctx, taskID, replacement, step, promptErr)
return
}
if replacementErr = s.autoStartStepPrompt(
ctx, taskID, replacement, step, replacementPrompt, hasPlanMode, true, handoffOnce,
); replacementErr != nil {
s.logger.Error("failed to auto-start replacement after reused session terminalized",
zap.String("task_id", taskID), zap.String("session_id", replacement.ID), zap.Error(replacementErr))
s.setSessionWaitingForInput(ctx, taskID, replacement.ID, replacement)
s.publishSessionWaitingEvent(ctx, taskID, replacement.ID, step.ID, replacement)
}
}
func (s *Service) handleWorkflowEntryPromptError(
ctx context.Context,
taskID string,
@@ -4000,13 +4056,14 @@ func (s *Service) handleCreatedAutoStartLaunchFailure(
origin workflowMessageOrigin,
references []v1.EntityReference,
takenMsg *messagequeue.QueuedMessage,
handoffText string,
) {
promptQueued := false
if shouldQueueIfBusy && (isAgentAlreadyRunningError(launchErr) ||
isSessionBusyError(launchErr) || isTransientPromptError(launchErr)) {
if queueErr := s.queueAutoStartPrompt(
ctx, taskID, sessionID, prompt, planMode,
attachments, origin, userMessageRecorded, references,
attachments, origin, userMessageRecorded, references, handoffText,
); queueErr != nil {
s.logger.Warn("failed to queue auto-start prompt after launch failure",
zap.String("task_id", taskID),
@@ -4022,11 +4079,18 @@ func (s *Service) handleCreatedAutoStartLaunchFailure(
}
}
// handoffOnce claims the completion-handoff carry token addressed to step,
// through the caller's shared per-step-entry stepHandoffOnce, so a
// replacement launch after this attempt reuses the same handoff text. Pass
// nil when the caller is not part of a step-entry dispatch (e.g. tests
// exercising this function directly) — resolveStepHandoffText treats a nil
// once as "never claim".
func (s *Service) autoStartStepPrompt(
ctx context.Context,
taskID string, session *models.TaskSession, step *wfmodels.WorkflowStep, prompt string,
planMode bool,
shouldQueueIfBusy bool,
handoffOnce *stepHandoffOnce,
) error {
sessionID := session.ID
origin := workflowOriginFromStep(step)
@@ -4037,17 +4101,30 @@ func (s *Service) autoStartStepPrompt(
// content first, hand-off after — and forward attachments verbatim.
// Track the original message so terminal failure paths can restore it
// instead of dropping the user's prompt or attachments on the floor.
takenMsg, mergedPrompt, attachments, references := s.takeAndMergeHandoffMessage(ctx, sessionID, prompt)
takenMsg, mergedPrompt, attachments, references, queuedHandoff := s.takeAndMergeHandoffMessage(ctx, sessionID, prompt)
prompt = mergedPrompt
agentPrompt := AppendEntityReferenceContext(prompt, references)
effectiveAgentPrompt := s.effectivePromptForSession(sessionID, agentPrompt, planMode, session)
if strings.TrimSpace(effectiveAgentPrompt) == "" && len(attachments) == 0 {
if strings.TrimSpace(effectiveAgentPrompt) == "" && len(attachments) == 0 && queuedHandoff == "" {
// The session is already running after ensureSessionRunning; no prompt
// means we leave it waiting for the first user message rather than
// auto-starting. Attachment-only handoffs are admitted below.
return nil
}
// The completion-handoff carry token is claimed only after the
// actionability decision above, and over content that excludes the
// handoff text, then appended last, after the queued hand-off already
// merged into agentPrompt/effectiveAgentPrompt above.
handoffText := s.resolveStepHandoffText(ctx, handoffOnce, taskID, step.ID, true)
if queuedHandoff != "" {
agentPrompt = appendStepHandoffToPrompt(agentPrompt, queuedHandoff)
effectiveAgentPrompt = appendStepHandoffToPrompt(effectiveAgentPrompt, queuedHandoff)
}
agentPrompt = appendStepHandoffToPrompt(agentPrompt, handoffText)
effectiveAgentPrompt = appendStepHandoffToPrompt(effectiveAgentPrompt, handoffText)
handoffForQueue := joinStepHandoffText(queuedHandoff, handoffText)
// requeueTaken puts the original queued message back so a manual retry can
// pick it up. Skip when shouldQueueIfBusy successfully re-queued the
// concatenated prompt (the content is already preserved there).
@@ -4062,7 +4139,7 @@ func (s *Service) autoStartStepPrompt(
// userMessageRecorded=false: recordAutoStartMessage has not run yet —
// the drain side (executeQueuedMessage) is responsible for inserting
// the chat-history row.
queued, err := s.queueAutoStartPromptIfRunning(ctx, taskID, session, prompt, planMode, attachments, origin, false, references)
queued, err := s.queueAutoStartPromptIfRunning(ctx, taskID, session, prompt, planMode, attachments, origin, false, references, handoffForQueue)
if err != nil {
requeueTaken()
return err
@@ -4195,7 +4272,7 @@ func (s *Service) autoStartStepPrompt(
s.handleCreatedAutoStartLaunchFailure(
ctx, taskID, sessionID, stepName, prompt, err,
planMode, shouldQueueIfBusy, userMsgRecorded,
attachments, origin, references, takenMsg,
attachments, origin, references, takenMsg, handoffForQueue,
)
}
return err
@@ -4205,6 +4282,15 @@ func (s *Service) autoStartStepPrompt(
for attempt := 1; attempt <= maxRetryAttempts; attempt++ {
_, err := s.promptTask(ctx, taskID, sessionID, dispatchPrompt, "", planMode, attachments, false, promptTaskOptions{
requireNonterminalSession: true,
// dispatchPrompt is already fully composed for this step entry
// (handoff included, see the ErrExecutionNotFound branch below):
// if promptTask's own internal ErrExecutionNotFound recovery fires
// first (ordinary lazy-resume race), it must use the same
// composed-prompt seam rather than recomposing from the
// destination step's own template and discarding the handoff.
promptAlreadyComposed: true,
fallbackLaunchPrompt: recordedPrompt,
fallbackRetryPrompt: dispatchPrompt,
})
if err == nil {
return nil
@@ -4218,15 +4304,17 @@ func (s *Service) autoStartStepPrompt(
// the lifecycle manager no longer has (e.g. the post-resume agent
// process failed to start and runAgentProcessAsync removed it). The
// session's stored AgentExecutionID is now stale. Recover by clearing
// it and routing through StartCreatedSession for a fresh launch — the
// prompt is baked into LaunchPreparedSession so we don't lose it.
// it and relaunching fresh through the composed-prompt seam — recordedPrompt
// and dispatchPrompt are already fully composed for this step entry
// (handoff included), so the fallback must not let StartCreatedSession
// recompose them from the destination step's own template.
if errors.Is(err, executor.ErrExecutionNotFound) {
s.logger.Warn("auto-start: PromptTask hit missing execution; falling back to fresh launch",
zap.String("task_id", taskID),
zap.String("session_id", sessionID),
zap.String("step_name", stepName))
return s.fallbackFreshLaunchOnMissingExecution(
ctx, taskID, sessionID, recordedPrompt, planMode, takenMsg, attachments, references,
ctx, taskID, sessionID, recordedPrompt, true, dispatchPrompt, planMode, takenMsg, attachments, references,
)
}
@@ -4237,7 +4325,7 @@ func (s *Service) autoStartStepPrompt(
// chat row was successfully inserted above; a failed write passes false,
// letting the drain re-attempt insertion.
if isAgentAlreadyRunningError(err) && shouldQueueIfBusy {
if queueErr := s.queueAutoStartPrompt(ctx, taskID, sessionID, prompt, planMode, attachments, origin, userMsgRecorded, references); queueErr != nil {
if queueErr := s.queueAutoStartPrompt(ctx, taskID, sessionID, prompt, planMode, attachments, origin, userMsgRecorded, references, handoffForQueue); queueErr != nil {
requeueTaken()
return queueErr
}
@@ -4252,7 +4340,7 @@ func (s *Service) autoStartStepPrompt(
if shouldQueueIfBusy {
// Pass userMsgRecorded so the drain skips CreateUserMessage only when
// the chat row was successfully inserted above by recordAutoStartMessage.
if queueErr := s.queueAutoStartPrompt(ctx, taskID, sessionID, prompt, planMode, attachments, origin, userMsgRecorded, references); queueErr != nil {
if queueErr := s.queueAutoStartPrompt(ctx, taskID, sessionID, prompt, planMode, attachments, origin, userMsgRecorded, references, handoffForQueue); queueErr != nil {
requeueTaken()
return queueErr
}
@@ -4279,12 +4367,21 @@ func (s *Service) autoStartStepPrompt(
// fallbackFreshLaunchOnMissingExecution recovers from a PromptTask that returned
// ErrExecutionNotFound — the session's stored AgentExecutionID points at an
// execution the lifecycle manager doesn't have, so the resume path is dead.
// Clear the stale ID, flip state to CREATED, and route through StartCreatedSession
// (which uses LaunchPreparedSession with the prompt baked in — bypassing resume).
// On further failure, the queued message is restored so a manual retry recovers it.
// Clear the stale ID, flip state to CREATED, and relaunch with prompt.
// promptAlreadyComposed routes the relaunch through the composed-prompt seam
// (startCreatedSessionWithComposedPrompt, with retryPrompt as its raw dispatch
// value) instead of the public StartCreatedSession, so a caller that already
// composed prompt itself (e.g. appending a claimed step handoff) is not
// recomposed from the destination step's own template — which discards
// everything it was passed when that template lacks {{task_prompt}}. Callers
// that have not composed the prompt pass promptAlreadyComposed=false and an
// empty retryPrompt. On further failure, the queued message is restored so a
// manual retry recovers it.
func (s *Service) fallbackFreshLaunchOnMissingExecution(
ctx context.Context,
taskID, sessionID, prompt string,
promptAlreadyComposed bool,
retryPrompt string,
planMode bool,
takenMsg *messagequeue.QueuedMessage,
attachments []v1.MessageAttachment,
@@ -4316,14 +4413,23 @@ func (s *Service) fallbackFreshLaunchOnMissingExecution(
return err
}
if _, err := s.StartCreatedSession(
ctx, taskID, sessionID, fresh.AgentProfileID,
prompt, true, planMode, true, attachments, references,
); err != nil {
var launchErr error
if promptAlreadyComposed {
_, launchErr = s.startCreatedSessionWithComposedPrompt(
ctx, taskID, sessionID, fresh.AgentProfileID,
prompt, retryPrompt, true, planMode, true, attachments, references,
)
} else {
_, launchErr = s.StartCreatedSession(
ctx, taskID, sessionID, fresh.AgentProfileID,
prompt, true, planMode, true, attachments, references,
)
}
if launchErr != nil {
s.logger.Error("auto-start fallback: fresh launch failed",
zap.String("session_id", sessionID), zap.Error(err))
zap.String("session_id", sessionID), zap.Error(launchErr))
requeue()
return err
return launchErr
}
return nil
}
@@ -4378,13 +4484,17 @@ func (s *Service) resetSessionForFreshFallback(
// the original queued message (so terminal failure paths can re-queue it via
// requeueMessage), merged prompt, converted attachments, and structurally
// normalized references.
func (s *Service) takeAndMergeHandoffMessage(ctx context.Context, sessionID, basePrompt string) (*messagequeue.QueuedMessage, string, []v1.MessageAttachment, []v1.EntityReference) {
func (s *Service) takeAndMergeHandoffMessage(ctx context.Context, sessionID, basePrompt string) (*messagequeue.QueuedMessage, string, []v1.MessageAttachment, []v1.EntityReference, string) {
if s.messageQueue == nil {
return nil, basePrompt, nil, nil
return nil, basePrompt, nil, nil, ""
}
msg, ok := s.messageQueue.TakeQueuedIfAutoRun(ctx, sessionID)
if !ok || msg == nil || (msg.Content == "" && len(msg.Attachments) == 0) {
return nil, basePrompt, nil, nil
queuedHandoff := ""
if msg != nil {
queuedHandoff = stepHandoffFromQueuedMetadata(msg.Metadata)
}
if !ok || msg == nil || (msg.Content == "" && len(msg.Attachments) == 0 && queuedHandoff == "") {
return nil, basePrompt, nil, nil, ""
}
prompt := basePrompt
if msg.Content != "" {
@@ -4407,7 +4517,7 @@ func (s *Service) takeAndMergeHandoffMessage(ctx context.Context, sessionID, bas
}
s.publishQueueStatusEvent(ctx, sessionID)
references := entityrefs.NormalizePersisted(msg.Metadata[messagequeue.MetadataEntityReferences])
return msg, prompt, attachments, references
return msg, prompt, attachments, references, queuedHandoff
}
// recordAutoStartMessage creates a user message for a workflow auto-start prompt
@@ -4469,11 +4579,12 @@ func (s *Service) queueAutoStartPromptIfRunning(
origin workflowMessageOrigin,
userMessageRecorded bool,
references []v1.EntityReference,
handoffText string,
) (bool, error) {
if session.State != models.TaskSessionStateRunning && session.State != models.TaskSessionStateStarting {
return false, nil
}
if err := s.queueAutoStartPrompt(ctx, taskID, session.ID, prompt, planMode, attachments, origin, userMessageRecorded, references); err != nil {
if err := s.queueAutoStartPrompt(ctx, taskID, session.ID, prompt, planMode, attachments, origin, userMessageRecorded, references, handoffText); err != nil {
return false, err
}
return true, nil
@@ -4508,7 +4619,10 @@ func toQueuedAttachments(attachments []v1.MessageAttachment) []messagequeue.Mess
// Callers that queue BEFORE recordAutoStartMessage runs (e.g.
// queueAutoStartPromptIfRunning's early-busy path) must pass false. Prompt
// content stays raw here; references remain metadata until drain-time context
// is built, preventing duplicate system blocks across retries.
// is built, preventing duplicate system blocks across retries. handoffText, if
// non-empty, is a completion handoff already claimed for this step entry; it
// rides the same way, so a dispatch deferred through this queue still appends
// it last, after entity-reference expansion, at actual dispatch time.
func (s *Service) queueAutoStartPrompt(
ctx context.Context,
taskID, sessionID, prompt string,
@@ -4517,6 +4631,7 @@ func (s *Service) queueAutoStartPrompt(
origin workflowMessageOrigin,
userMessageRecorded bool,
references []v1.EntityReference,
handoffText string,
) error {
if s.messageQueue == nil {
return fmt.Errorf("message queue is not configured")
@@ -4525,6 +4640,9 @@ func (s *Service) queueAutoStartPrompt(
if userMessageRecorded {
meta[metaKeyUserMessageRecorded] = true
}
if handoffText != "" {
meta[messagequeue.MetadataStepHandoff] = handoffText
}
_, err := s.messageQueue.QueueMessageWithMetadata(
ctx,
sessionID,
@@ -720,7 +720,7 @@ func TestHandleTaskMovedWithSession(t *testing.T) {
_ = repo.UpdateTaskSession(ctx, session)
svc := createTestService(repo, newMockStepGetter(), newMockTaskRepo())
queued, err := svc.queueAutoStartPromptIfRunning(ctx, "t1", session, "prompt", false, nil, workflowMessageOrigin{}, false, nil)
queued, err := svc.queueAutoStartPromptIfRunning(ctx, "t1", session, "prompt", false, nil, workflowMessageOrigin{}, false, nil, "")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
@@ -223,7 +223,7 @@ func TestAutoStartStepPrompt_OfficeWithoutRuntimeEnvFailsClosed(t *testing.T) {
)
prompt := spoofedReference + "\n\n" +
sysprompt.InjectOfficeContext("wrong-task", "wrong-session", "Do the work")
err = svc.autoStartStepPrompt(ctx, "task-office", session, step, prompt, false, false)
err = svc.autoStartStepPrompt(ctx, "task-office", session, step, prompt, false, false, nil)
if err == nil || !strings.Contains(err.Error(), "office tasks must be started through Office") {
t.Fatalf("autoStartStepPrompt error = %v, want Office scheduler guard", err)
}
@@ -278,7 +278,7 @@ func TestAutoStartStepPrompt_ResetContextInjectsCompletionContractForReusedSessi
messages := &mockMessageCreator{}
svc := createTestServiceWithScheduler(repo, stepGetter, newMockTaskRepo(), agentMgr)
svc.messageCreator = messages
err = svc.autoStartStepPrompt(ctx, "task-reused", session, step, "Review the change", false, false)
err = svc.autoStartStepPrompt(ctx, "task-reused", session, step, "Review the change", false, false, nil)
if err != nil {
t.Fatalf("autoStartStepPrompt returned error: %v", err)
}
@@ -321,7 +321,7 @@ func TestAutoStartStepPrompt_ResetContextPreservesOfficeModeForReusedSession(t *
messages := &mockMessageCreator{}
svc := createTestServiceWithScheduler(repo, stepGetter, newMockTaskRepo(), agentMgr)
svc.messageCreator = messages
if err := svc.autoStartStepPrompt(ctx, task.ID, session, step, "Run the Office task", false, false); err != nil {
if err := svc.autoStartStepPrompt(ctx, task.ID, session, step, "Run the Office task", false, false, nil); err != nil {
t.Fatalf("autoStartStepPrompt returned error: %v", err)
}
if len(messages.userMessages) != 1 {
@@ -240,7 +240,7 @@ func TestWorkflowAutoStartRejectsSessionTerminalizedBeforeResume(t *testing.T) {
}
errCh := make(chan error, 1)
go func() {
errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false)
errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false, nil)
}()
<-barrierRepo.claimReached
@@ -290,7 +290,7 @@ func TestWorkflowAutoStartRollsBackPromptClaimWhenPostClaimReloadFails(t *testin
repo: failingRepo,
}
err = svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false)
err = svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false, nil)
if !errors.Is(err, reloadErr) {
t.Fatalf("auto-start error = %v, want post-claim reload error", err)
}
@@ -348,7 +348,7 @@ func TestWorkflowAutoStartRollsBackPromptClaimWhenTerminalizedAfterClaim(t *test
errCh := make(chan error, 1)
go func() {
errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false)
errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false, nil)
}()
<-barrierRepo.claimReached
@@ -528,7 +528,7 @@ func TestWorkflowAutoStartReleasesTerminalGuardAfterPromptAdmission(t *testing.T
svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{})
errCh := make(chan error, 1)
go func() {
errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false)
errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false, nil)
}()
<-agentMgr.dispatched
@@ -618,7 +618,7 @@ func TestWorkflowAutoStartCreatedTerminalizedGuard(t *testing.T) {
errCh := make(chan error, 1)
go func() {
errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, step, "review the task", false, false)
errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, step, "review the task", false, false, nil)
}()
<-barrierRepo.lockAcquired
@@ -199,7 +199,7 @@ func TestResetAgentContext_ActiveTurnAllowsSuccessorPrompt(t *testing.T) {
}},
}
if err := svc.autoStartStepPrompt(
context.Background(), "task1", resetSession, step, "successor prompt", false, false,
context.Background(), "task1", resetSession, step, "successor prompt", false, false, nil,
); err != nil {
t.Fatalf("auto-start successor prompt: %v", err)
}
@@ -0,0 +1,72 @@
package orchestrator
import (
"context"
"strings"
"testing"
"github.com/kandev/kandev/internal/orchestrator/executor"
"github.com/kandev/kandev/internal/task/models"
wfmodels "github.com/kandev/kandev/internal/workflow/models"
v1 "github.com/kandev/kandev/pkg/api/v1"
"github.com/stretchr/testify/require"
)
// TestFallbackFreshLaunch_ComposedPromptSurvivesStepRecomposition covers the
// ErrExecutionNotFound recovery path from autoStartStepPrompt: when the
// caller has already composed the dispatch prompt (appending a claimed step
// handoff), the fresh launch must not let StartCreatedSession's own workflow
// step recomposition discard it. A destination step Prompt template with no
// {{task_prompt}} placeholder replaces any base prompt during recomposition
// (see TestApplyWorkflowAndPlanMode_KeepsWorkflowPromptVisibleWhenStepEnablesPlanMode
// in workflow_prompt_test.go), so promptAlreadyComposed must route around
// that seam entirely instead of losing the handoff.
func TestFallbackFreshLaunch_ComposedPromptSurvivesStepRecomposition(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-fallback-handoff"
sessionID = "session-fallback-handoff"
stepID = "step-next"
handoff = "watch out for the flaky test"
)
repo := setupTestRepo(t)
seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput)
dbTask, err := repo.GetTask(ctx, taskID)
require.NoError(t, err)
dbTask.WorkflowStepID = stepID
require.NoError(t, repo.UpdateTask(ctx, dbTask))
session, err := repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
session.AgentProfileID = "profile-fallback"
require.NoError(t, repo.UpdateTaskSession(ctx, session))
stepGetter := newMockStepGetter()
stepGetter.steps[stepID] = &wfmodels.WorkflowStep{
ID: stepID, WorkflowID: "wf1", Name: "Next",
Prompt: "Recomposed step instructions.",
}
taskRepo := newMockTaskRepo()
taskRepo.tasks[taskID] = &v1.Task{ID: taskID, Title: "Test Task", State: v1.TaskStateInProgress}
var launchedDescription string
agentMgr := &mockAgentManager{
repoForExecutionLookup: repo,
launchAgentFunc: func(_ context.Context, req *executor.LaunchAgentRequest) (*executor.LaunchAgentResponse, error) {
launchedDescription = req.TaskDescription
return &executor.LaunchAgentResponse{AgentExecutionID: "exec-fresh"}, nil
},
}
svc := createTestServiceWithScheduler(repo, stepGetter, taskRepo, agentMgr)
svc.messageCreator = &mockMessageCreator{}
composedPrompt := "Run the next workflow step.\n\n" + stepHandoffPromptHeading + "\n\n" + handoff
err = svc.fallbackFreshLaunchOnMissingExecution(
ctx, taskID, sessionID, composedPrompt, true, composedPrompt, false, nil, nil, nil,
)
require.NoError(t, err)
require.Contains(t, launchedDescription, handoff,
"the already-composed prompt (with the claimed handoff) must survive the fresh launch")
require.NotEqual(t, "Recomposed step instructions.", strings.TrimSpace(launchedDescription),
"promptAlreadyComposed must skip StartCreatedSession's own step-template recomposition")
}
@@ -140,6 +140,7 @@ func BuildSendNowEnvelope(entries []QueuedMessage) (*QueuedMessage, error) {
seenReferences := make(map[string]struct{})
references := make([]apiv1.EntityReference, 0)
sources := make([]map[string]interface{}, 0, len(entries))
var handoffText string
for _, entry := range entries {
if entry.Content != "" {
@@ -155,6 +156,12 @@ func BuildSendNowEnvelope(entries []QueuedMessage) (*QueuedMessage, error) {
references = append(references, reference)
}
if handoffText == "" {
if text, ok := entry.Metadata[MetadataStepHandoff].(string); ok && text != "" {
handoffText = text
}
}
sources = append(sources, map[string]interface{}{
"id": entry.ID,
"task_id": entry.TaskID,
@@ -172,6 +179,11 @@ func BuildSendNowEnvelope(entries []QueuedMessage) (*QueuedMessage, error) {
} else {
metadata[MetadataEntityReferences] = references
}
if handoffText == "" {
delete(metadata, MetadataStepHandoff)
} else {
metadata[MetadataStepHandoff] = handoffText
}
metadata[MetadataSendNowSources] = sources
return &QueuedMessage{
@@ -64,6 +64,52 @@ func TestBuildSendNowEnvelopeAggregatesInFIFOOrder(t *testing.T) {
}
}
func TestBuildSendNowEnvelopeCarriesHandoffFromNonHeadEntry(t *testing.T) {
queuedAt := time.Date(2026, time.January, 1, 12, 0, 0, 0, time.UTC)
entries := []QueuedMessage{
{
ID: "first", SessionID: "session-1", TaskID: "task-1", Position: 10,
Content: "user message", QueuedAt: queuedAt, QueuedBy: QueuedByUser,
Metadata: map[string]interface{}{"origin": "user-input"},
},
{
ID: "second", SessionID: "session-1", TaskID: "task-1", Position: 20,
Content: "workflow auto-start", QueuedAt: queuedAt.Add(time.Minute), QueuedBy: QueuedByWorkflow,
Metadata: map[string]interface{}{MetadataStepHandoff: "claimed handoff text"},
},
}
envelope, err := BuildSendNowEnvelope(entries)
if err != nil {
t.Fatalf("BuildSendNowEnvelope() error = %v", err)
}
if got, ok := envelope.Metadata[MetadataStepHandoff].(string); !ok || got != "claimed handoff text" {
t.Fatalf("envelope handoff = %#v, want the second entry's claimed handoff text", envelope.Metadata[MetadataStepHandoff])
}
}
func TestBuildSendNowEnvelopeOmitsHandoffWhenNoEntryCarriesOne(t *testing.T) {
queuedAt := time.Date(2026, time.January, 1, 12, 0, 0, 0, time.UTC)
entries := []QueuedMessage{
{
ID: "first", SessionID: "session-1", TaskID: "task-1", Position: 10,
Content: "user message", QueuedAt: queuedAt, QueuedBy: QueuedByUser,
},
{
ID: "second", SessionID: "session-1", TaskID: "task-1", Position: 20,
Content: "another message", QueuedAt: queuedAt.Add(time.Minute), QueuedBy: QueuedByUser,
},
}
envelope, err := BuildSendNowEnvelope(entries)
if err != nil {
t.Fatalf("BuildSendNowEnvelope() error = %v", err)
}
if _, ok := envelope.Metadata[MetadataStepHandoff]; ok {
t.Fatalf("envelope handoff = %#v, want absent", envelope.Metadata[MetadataStepHandoff])
}
}
func TestBuildSendNowEnvelopeAllowsAttachmentOnlyEntries(t *testing.T) {
entries := []QueuedMessage{
{ID: "first", SessionID: "session-1", Position: 1, Attachments: []MessageAttachment{{Data: "aA==", SizeBytes: 1}}},
@@ -46,6 +46,13 @@ const MetadataCoalesceKey = "coalesce_key"
// queued message.
const MetadataEntityReferences = "entity_references"
// MetadataStepHandoff carries a completion-handoff carry token's claimed text
// for a queued workflow auto-start prompt, so a dispatch path that defers
// delivery through the queue (rather than sending it directly) still appends
// the handoff at actual dispatch time, after entity-reference context, rather
// than losing it at claim time or appending it out of order.
const MetadataStepHandoff = "step_handoff"
// MetadataContextFiles carries path/name references and optional directory
// identity for queued user messages.
const MetadataContextFiles = "context_files"
@@ -0,0 +1,96 @@
package orchestrator
import (
"context"
"strings"
"testing"
"github.com/kandev/kandev/internal/orchestrator/executor"
"github.com/kandev/kandev/internal/sysprompt"
"github.com/kandev/kandev/internal/task/models"
wfmodels "github.com/kandev/kandev/internal/workflow/models"
v1 "github.com/kandev/kandev/pkg/api/v1"
"github.com/stretchr/testify/require"
)
// TestHandlePromptDispatchFailure_ComposedPromptSurvivesInternalFallback
// covers promptTask's OWN internal ErrExecutionNotFound recovery
// (handlePromptDispatchFailure), a second, independent trigger for
// fallbackFreshLaunchOnMissingExecution beyond autoStartStepPrompt's own
// explicit branch (covered by
// TestFallbackFreshLaunch_ComposedPromptSurvivesStepRecomposition). This
// internal recovery fires on the ordinary "lazy resume after a backend
// restart" race (promptTask's resumedForPrompt) and used to always call
// fallbackFreshLaunchOnMissingExecution with promptAlreadyComposed=false,
// silently discarding an already-claimed step handoff whenever the caller
// had already composed the dispatch prompt (e.g. autoStartStepPrompt,
// appending a claimed handoff before calling promptTask) — the same failure
// mode Build round 4 fixed at the sibling call site only.
//
// Exercises handlePromptDispatchFailure directly rather than through
// promptTask/PromptTask: promptTask's requireNonterminalSession branch
// already holds the per-session cancelInFlightGuard for the rest of the
// call, and fallbackFreshLaunchOnMissingExecution re-acquires that same
// guard — a pre-existing, unrelated locking shape (present at merge-base,
// unrelated to this capability) that this test must not exercise.
func TestHandlePromptDispatchFailure_ComposedPromptSurvivesInternalFallback(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-dispatch-failure-handoff"
sessionID = "session-dispatch-failure-handoff"
stepID = "step-next-dispatch-failure"
handoff = "watch out for the flaky test"
)
repo := setupTestRepo(t)
seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput)
dbTask, err := repo.GetTask(ctx, taskID)
require.NoError(t, err)
dbTask.WorkflowStepID = stepID
require.NoError(t, repo.UpdateTask(ctx, dbTask))
session, err := repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
session.AgentProfileID = "profile-dispatch-failure"
require.NoError(t, repo.UpdateTaskSession(ctx, session))
stepGetter := newMockStepGetter()
stepGetter.steps[stepID] = &wfmodels.WorkflowStep{
ID: stepID, WorkflowID: "wf1", Name: "Next",
Prompt: "Recomposed step instructions.",
}
taskRepo := newMockTaskRepo()
taskRepo.tasks[taskID] = &v1.Task{ID: taskID, Title: "Test Task", State: v1.TaskStateInProgress}
var launchedDescription string
agentMgr := &mockAgentManager{
repoForExecutionLookup: repo,
launchAgentFunc: func(_ context.Context, req *executor.LaunchAgentRequest) (*executor.LaunchAgentResponse, error) {
launchedDescription = req.TaskDescription
return &executor.LaunchAgentResponse{AgentExecutionID: "exec-fresh"}, nil
},
}
svc := createTestServiceWithScheduler(repo, stepGetter, taskRepo, agentMgr)
svc.messageCreator = &mockMessageCreator{}
composedPrompt := "Run the next workflow step.\n\n" + stepHandoffPromptHeading + "\n\n" + handoff
// Mirrors the guard handlePromptDispatchFailure checks before recovering
// internally: resumedForPrompt=true, nothing accepted or reserved yet,
// and the specific ErrExecutionNotFound this recovery targets.
result, err := svc.handlePromptDispatchFailure(
ctx, taskID, sessionID, composedPrompt,
true, true,
nil,
promptClaimRollback{},
false, false,
executor.ErrExecutionNotFound,
true, sysprompt.InjectPlanMode(composedPrompt), composedPrompt,
)
require.NoError(t, err)
require.NotNil(t, result)
require.Contains(t, launchedDescription, handoff,
"the already-composed prompt (with the claimed handoff) must survive promptTask's own internal fallback")
require.Contains(t, launchedDescription, sysprompt.PlanMode(),
"the fallback must retain the plan-mode transform")
require.NotEqual(t, "Recomposed step instructions.", strings.TrimSpace(launchedDescription),
"promptAlreadyComposed must skip StartCreatedSession's own step-template recomposition")
}
@@ -76,6 +76,7 @@ func TestAutoStartStepPrompt_LeavesHandoffQueuedWhenAutoRunPaused(t *testing.T)
autoStart,
false,
false,
nil,
)
require.NoError(t, err)
@@ -462,6 +462,7 @@ func (s *Service) promptSendNowClaim(ctx context.Context, claim *messagequeue.Se
}
references := entityrefs.NormalizePersisted(claim.Dispatch.Metadata[messagequeue.MetadataEntityReferences])
promptContent := AppendEntityReferenceContext(claim.Dispatch.Content, references)
promptContent = appendStepHandoffToPrompt(promptContent, stepHandoffFromQueuedMetadata(claim.Dispatch.Metadata))
if err := s.recordQueuedUserMessage(ctx, &claim.Dispatch, attachments); err != nil {
s.logger.Warn("failed to record send-now user message before prompt",
zap.String("session_id", sessionID), zap.Error(err))
@@ -222,7 +222,10 @@ type StepHistoryRecorder interface {
}
type asyncStepHistoryRecorder interface {
EnqueueStepTransition(sessionID, fromStepID, toStepID string, trigger wfmodels.StepTransitionTrigger, actorID *string, metadata map[string]interface{})
// EnqueueStepTransition returns false when the bounded worker cannot accept
// the row. Signal-bearing callers can then use their bounded synchronous
// fallback instead of silently losing the audit payload.
EnqueueStepTransition(sessionID, fromStepID, toStepID string, trigger wfmodels.StepTransitionTrigger, actorID *string, metadata map[string]interface{}) bool
}
// AgentFamilyResolver maps a hand-written agent family reference onto the
@@ -0,0 +1,252 @@
package orchestrator
import (
"context"
"encoding/json"
"strings"
"sync"
"github.com/google/uuid"
"go.uber.org/zap"
"github.com/kandev/kandev/internal/orchestrator/messagequeue"
"github.com/kandev/kandev/internal/task/models"
)
// drainQueuedMessageForPromptableSessionWithHandoff is a sibling of
// drainQueuedMessageForPromptableSessionOutcome for the step-entry dispatch
// branches whose only activity is draining a queued message. It duplicates
// that function's guard/reserve tail instead of adding a splice parameter to
// the shared drain chain, which has 12 production call sites that are not
// step entries at all and must keep their existing behavior unchanged. The
// handoff is claimed only once a message is confirmed about to be
// dispatched, and is carried on a LOCAL COPY of that message's metadata —
// never onto the stored queue entry — so a skipped or paused reservation
// cannot lose or double-append it on a later drain. It rides as metadata
// rather than being spliced onto Content directly because the actual
// dispatch still runs entity-reference expansion over Content; appending the
// handoff here would let that expansion land after it, violating the
// "handoff last" rule whenever the queued message itself carries references.
func (s *Service) drainQueuedMessageForPromptableSessionWithHandoff(
ctx context.Context, taskID, sessionID, stepID string, once *stepHandoffOnce,
) bool {
lock, release := s.acquireCancelInFlightGuard(sessionID)
defer release()
lock.Lock()
defer lock.Unlock()
if s.isCancelInFlight(sessionID) {
return false
}
session, err := s.repo.GetTaskSession(ctx, sessionID)
if err != nil {
s.logger.Warn("failed to reload session before handoff-aware drain",
zap.String("session_id", sessionID), zap.Error(err))
return false
}
if err := s.checkSessionPromptable(session.TaskID, sessionID, session.State); err != nil {
return false
}
if s.messageQueue == nil || s.isQueuedDispatchInFlight(sessionID) || s.isSteerInFlight(sessionID) {
return false
}
queuedMsg, ok, autoRun := s.messageQueue.ReserveQueuedWithAutoRun(ctx, sessionID)
if !autoRun || !ok || queuedMsg == nil {
return false
}
if queuedMsg.Content != "" || len(queuedMsg.Attachments) > 0 {
if handoffText := s.resolveStepHandoffText(ctx, once, taskID, stepID, true); handoffText != "" {
queuedMsg = withStepHandoffMetadata(queuedMsg, handoffText)
}
}
return s.dispatchTakenQueuedMessage(ctx, sessionID, queuedMsg, ok)
}
// withStepHandoffMetadata returns a shallow copy of msg carrying handoffText
// under messagequeue.MetadataStepHandoff, leaving the original message (and
// its metadata map) untouched so a later drain of the same stored entry never
// observes a handoff it was not itself claimed for.
func withStepHandoffMetadata(msg *messagequeue.QueuedMessage, handoffText string) *messagequeue.QueuedMessage {
spliced := *msg
metadata := make(map[string]interface{}, len(msg.Metadata)+1)
for k, v := range msg.Metadata {
metadata[k] = v
}
metadata[messagequeue.MetadataStepHandoff] = handoffText
spliced.Metadata = metadata
return &spliced
}
// stepHandoffFromQueuedMetadata extracts a claimed handoff carried through a
// queued message's metadata (see withStepHandoffMetadata / queueAutoStartPrompt),
// so a deferred dispatch path can append it last, after entity-reference
// expansion, instead of losing it or racing that expansion.
func stepHandoffFromQueuedMetadata(metadata map[string]interface{}) string {
handoff, _ := metadata[messagequeue.MetadataStepHandoff].(string)
return handoff
}
// stepHandoffPromptHeading is the fixed heading the claimed handoff text is
// appended under, last in the composed prompt. Not localized: the same class
// as workflowInstructionsHeading, sent to the model rather than rendered to a
// user.
const stepHandoffPromptHeading = "## Context from the previous workflow step"
// setStepHandoffCarryMetadata applies the same single-slot carry semantics to
// a task snapshot before a workflow transition is persisted. Keeping the token
// on that snapshot makes admission and carry publication one database write,
// so a queued task cannot be promoted in the gap between the transition and a
// later metadata update.
func setStepHandoffCarryMetadata(task *models.Task, nextStepID string, signal *models.PendingStepCompletionSignal) {
if task == nil || nextStepID == "" {
return
}
if task.Metadata == nil {
task.Metadata = make(map[string]interface{})
}
handoff := ""
if signal != nil {
handoff = strings.TrimSpace(signal.Handoff)
}
if handoff == "" {
delete(task.Metadata, models.MetaKeyStepHandoffCarry)
return
}
task.Metadata[models.MetaKeyStepHandoffCarry] = models.StepHandoffCarryToken{
Handoff: handoff,
StepID: nextStepID,
Stamp: uuid.NewString(),
}
}
// claimStepHandoffCarryText performs the advisory-read-then-claim for the
// step being entered, returning the claimed handoff text and whether a token
// was actually claimed. A repository lacking the capability, a missing or
// mismatched token, or a claim error all report claimed=false with no text,
// so a failed attempt never spends the step entry's one-claim budget.
func (s *Service) claimStepHandoffCarryText(ctx context.Context, taskID, stepID string) (string, bool) {
if taskID == "" || stepID == "" || s.repo == nil {
return "", false
}
taker, ok := s.repo.(taskMetadataCarryTaker)
if !ok {
return "", false
}
token, ok := s.advisoryStepHandoffCarryToken(ctx, taskID, stepID)
if !ok {
return "", false
}
claimedRaw, claimed, err := taker.TakeTaskMetadataKeyIfDestinationStep(
ctx, taskID, models.MetaKeyStepHandoffCarry, stepID, token.Stamp,
)
if err != nil {
s.logger.Debug("failed to claim step handoff carry token",
zap.String("task_id", taskID), zap.String("step_id", stepID), zap.Error(err))
return "", false
}
if !claimed {
return "", false
}
var claimedToken models.StepHandoffCarryToken
if err := json.Unmarshal(claimedRaw, &claimedToken); err != nil {
return "", false
}
return strings.TrimSpace(claimedToken.Handoff), true
}
// advisoryStepHandoffCarryToken performs the non-claiming read used to decide
// whether a claim attempt targeting stepID is worth making. This read is not
// synchronized with a concurrent claim, so the caller still must perform the
// compare-and-swap via TakeTaskMetadataKeyIfDestinationStep rather than acting
// on this result directly.
func (s *Service) advisoryStepHandoffCarryToken(ctx context.Context, taskID, stepID string) (models.StepHandoffCarryToken, bool) {
task, err := s.repo.GetTask(ctx, taskID)
if err != nil || task == nil || task.Metadata == nil {
return models.StepHandoffCarryToken{}, false
}
rawValue, present := task.Metadata[models.MetaKeyStepHandoffCarry]
if !present {
return models.StepHandoffCarryToken{}, false
}
tokenBytes, err := json.Marshal(rawValue)
if err != nil {
return models.StepHandoffCarryToken{}, false
}
var token models.StepHandoffCarryToken
if err := json.Unmarshal(tokenBytes, &token); err != nil {
return models.StepHandoffCarryToken{}, false
}
if token.StepID != stepID || strings.TrimSpace(token.Stamp) == "" {
return models.StepHandoffCarryToken{}, false
}
return token, true
}
// appendStepHandoffToPrompt appends the claimed handoff text under the fixed
// heading, last in the composed prompt. Called after reference expansion has
// already run over the rest of the prompt, so the handoff text is never
// itself expanded.
func appendStepHandoffToPrompt(prompt, handoffText string) string {
if handoffText == "" {
return prompt
}
section := stepHandoffPromptHeading + "\n\n" + handoffText
if strings.TrimSpace(prompt) == "" {
return section
}
return prompt + "\n\n" + section
}
// joinStepHandoffText combines raw handoff payloads for a queue entry. The
// queue adds one heading when it dispatches, so the payload stays free of
// formatting and remains safe to append after reference expansion.
func joinStepHandoffText(previous, current string) string {
previous = strings.TrimSpace(previous)
current = strings.TrimSpace(current)
switch {
case previous == "":
return current
case current == "":
return previous
default:
return previous + "\n\n" + current
}
}
// stepHandoffOnce memoizes one step entry's handoff claim so a replacement
// launch (after a failed or terminalized first attempt within the same step
// entry) reuses the same text instead of re-claiming: the underlying DB claim
// only ever succeeds once, so a second raw attempt would silently find
// nothing. Only a SUCCESSFUL claim is memoized — a failure (no repository
// capability, no matching token, or a claim error) is not, so a later
// replacement launch in the same entry retries it.
type stepHandoffOnce struct {
mu sync.Mutex
claimed bool
text string
}
func newStepHandoffOnce() *stepHandoffOnce {
return &stepHandoffOnce{}
}
// resolveStepHandoffText returns the handoff text to append for this step
// entry, claiming it at most once. wouldSend reports whether the caller's own
// dispatch branch has already decided it will send the agent something over
// content that excludes the handoff text; when false, nothing is claimed, so
// a dispatch that never happens can never consume a handoff.
func (s *Service) resolveStepHandoffText(ctx context.Context, once *stepHandoffOnce, taskID, stepID string, wouldSend bool) string {
if once == nil || !wouldSend {
return ""
}
once.mu.Lock()
defer once.mu.Unlock()
if once.claimed {
return once.text
}
text, claimed := s.claimStepHandoffCarryText(ctx, taskID, stepID)
if claimed {
once.claimed = true
once.text = text
}
return text
}
@@ -0,0 +1,751 @@
package orchestrator
import (
"context"
"encoding/json"
"errors"
"fmt"
"strings"
"sync/atomic"
"testing"
"time"
"github.com/kandev/kandev/internal/orchestrator/executor"
"github.com/kandev/kandev/internal/orchestrator/messagequeue"
"github.com/kandev/kandev/internal/orchestrator/queue"
"github.com/kandev/kandev/internal/orchestrator/scheduler"
"github.com/kandev/kandev/internal/sysprompt"
"github.com/kandev/kandev/internal/task/models"
wfmodels "github.com/kandev/kandev/internal/workflow/models"
v1 "github.com/kandev/kandev/pkg/api/v1"
"github.com/stretchr/testify/require"
)
func seedHandoffCarryToken(t *testing.T, repo interface {
SetTaskMetadataKey(ctx context.Context, taskID, key string, value interface{}) error
}, taskID, stepID, handoff, stamp string) {
t.Helper()
err := repo.SetTaskMetadataKey(context.Background(), taskID, models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{
Handoff: handoff, StepID: stepID, Stamp: stamp,
})
if err != nil {
t.Fatalf("seed carry token: %v", err)
}
}
// TestAutoStartStepPrompt_DeliversHandoffLastAfterQueuedHandoff covers
// AC-001.6 and AC-001.6a on the ACP dispatch branch: an AutoRun-enabled
// queued hand-off message merges first, then the completion handoff carry
// token is claimed and appended last, under the fixed heading.
func TestAutoStartStepPrompt_DeliversHandoffLastAfterQueuedHandoff(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-handoff-order"
sessionID = "session-handoff-order"
stepID = "step-next"
queued = "please also check the migration"
autoStart = "Run the next workflow step"
carried = "watch out for the flaky test"
)
repo := setupTestRepo(t)
seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput)
seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-order")
agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo}
svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr)
svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{})
seedExecutorRunning(t, repo, sessionID, taskID, "exec-handoff-order")
_, err := svc.messageQueue.QueueMessage(ctx, sessionID, taskID, queued, "", "user", false, nil)
require.NoError(t, err)
session, err := repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
err = svc.autoStartStepPrompt(
ctx, taskID, session, &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Next"},
autoStart, false, false, newStepHandoffOnce(),
)
require.NoError(t, err)
require.Len(t, agentMgr.capturedPrompts, 1)
prompt := agentMgr.capturedPrompts[0]
autoStartIdx := strings.Index(prompt, autoStart)
queuedIdx := strings.Index(prompt, queued)
headingIdx := strings.Index(prompt, stepHandoffPromptHeading)
carriedIdx := strings.Index(prompt, carried)
require.NotEqual(t, -1, autoStartIdx, "prompt = %q", prompt)
require.NotEqual(t, -1, queuedIdx, "prompt = %q", prompt)
require.NotEqual(t, -1, headingIdx, "prompt = %q", prompt)
require.NotEqual(t, -1, carriedIdx, "prompt = %q", prompt)
require.True(t, autoStartIdx < queuedIdx, "auto-start content must precede the queued hand-off")
require.True(t, queuedIdx < headingIdx, "the completion handoff must land after the queued hand-off")
require.True(t, headingIdx < carriedIdx)
if _, present := carryToken(t, repo, taskID); present {
t.Fatal("the claimed carry token must be removed")
}
}
// TestAutoStartStepPrompt_NoTokenNoHeading covers the plain case: with no
// carry token, the prompt is unchanged and no heading is injected.
func TestAutoStartStepPrompt_NoTokenNoHeading(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-no-handoff"
sessionID = "session-no-handoff"
autoStart = "Run the next workflow step"
)
repo := setupTestRepo(t)
seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput)
agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo}
svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr)
svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{})
seedExecutorRunning(t, repo, sessionID, taskID, "exec-no-handoff")
session, err := repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
err = svc.autoStartStepPrompt(
ctx, taskID, session, &wfmodels.WorkflowStep{ID: "step-next", WorkflowID: "wf1", Name: "Next"},
autoStart, false, false, newStepHandoffOnce(),
)
require.NoError(t, err)
require.Len(t, agentMgr.capturedPrompts, 1)
require.False(t, strings.Contains(agentMgr.capturedPrompts[0], stepHandoffPromptHeading))
}
// TestAutoStartStepPrompt_ReplacementLaunchReusesClaimedHandoff covers
// AC-001.8: a replacement launch within the same step entry, sharing the same
// stepHandoffOnce, receives the same handoff text even though the DB-level
// claim can only succeed once.
func TestAutoStartStepPrompt_ReplacementLaunchReusesClaimedHandoff(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-replacement-handoff"
sessionID = "session-replacement-handoff"
stepID = "step-next"
autoStart = "Run the next workflow step"
carried = "carried across the replacement"
)
repo := setupTestRepo(t)
seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput)
seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-replacement")
agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo}
svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr)
svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{})
seedExecutorRunning(t, repo, sessionID, taskID, "exec-replacement-handoff")
session, err := repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Next"}
once := newStepHandoffOnce()
// First attempt: claims and delivers the token, removing it from the DB.
err = svc.autoStartStepPrompt(ctx, taskID, session, step, autoStart, false, false, once)
require.NoError(t, err)
require.Len(t, agentMgr.capturedPrompts, 1)
require.Contains(t, agentMgr.capturedPrompts[0], carried)
if _, present := carryToken(t, repo, taskID); present {
t.Fatal("the token must be removed after the first claim")
}
// A replacement launch in the SAME step entry reuses the shared once — the
// DB has nothing left to claim, but the memoized text must still appear.
// Reset the session back to promptable, standing in for a real replacement
// launch (created after the first session terminalized).
require.NoError(t, repo.UpdateTaskSessionState(ctx, sessionID, models.TaskSessionStateWaitingForInput, ""))
seedExecutorRunning(t, repo, sessionID, taskID, "exec-replacement-handoff-2")
session, err = repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
err = svc.autoStartStepPrompt(ctx, taskID, session, step, autoStart, false, false, once)
require.NoError(t, err)
require.Len(t, agentMgr.capturedPrompts, 2)
require.Contains(t, agentMgr.capturedPrompts[1], carried, "the replacement launch must reuse the already-claimed handoff text")
}
// TestLaunchAfterOnEnterDispatch_PassthroughEmptyPromptDeliversViaDrain covers
// AC-001.6c: the passthrough branch that finds its composed prompt empty
// still dispatches a drained queued message, and that dispatch carries the
// completion handoff.
func TestLaunchAfterOnEnterDispatch_PassthroughEmptyPromptDeliversViaDrain(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-passthrough-drain"
sessionID = "session-passthrough-drain"
stepID = "step1"
queued = "drain me please"
carried = "passthrough carried text"
)
repo := setupTestRepo(t)
seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput)
seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-passthrough")
agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo, isPassthrough: true}
svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr)
svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{})
seedExecutorRunning(t, repo, sessionID, taskID, "exec-passthrough-drain")
_, err := svc.messageQueue.QueueMessage(ctx, sessionID, taskID, queued, "", "user", false, nil)
require.NoError(t, err)
session, err := repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
// Pre-consume the one-time initial-prompt fallback claim so buildWorkflowEntryPrompt
// treats taskDescription as ineligible and composes an empty prompt below — the
// actual case this test targets. Without this, the first claim on a fresh session
// wins and taskDescription becomes the composed prompt, silently exercising the
// unrelated autoStartPassthroughPrompt branch instead of the drain-only one.
_, err = repo.ClaimInitialPromptFallback(ctx, sessionID)
require.NoError(t, err)
done := make(chan struct{}, 1)
agentMgr.passthroughStdinFunc = func(context.Context, string, string) error {
done <- struct{}{}
return nil
}
step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Step 1", Prompt: ""}
svc.launchAfterOnEnterDispatch(ctx, taskID, session, step, "task description", false, true, false)
select {
case <-done:
case <-time.After(5 * time.Second):
t.Fatal("timed out waiting for the drained queue message to dispatch")
}
// The claim happens synchronously inside the guarded reserve, before the
// dispatch's async execution.
if _, present := carryToken(t, repo, taskID); present {
t.Fatal("the drain-only passthrough branch must claim the token when it dispatches")
}
require.Len(t, agentMgr.passthroughStdinCalls, 1)
written := agentMgr.passthroughStdinCalls[0].Data
require.Contains(t, written, queued)
require.Contains(t, written, carried, "the passthrough drain must deliver the claimed handoff text")
}
// TestProcessOnEnter_NoOnEnterActionsDrainDeliversHandoff covers F22's first
// gap: processOnEnter's own early return (no on_enter actions, no profile
// switch) never reaches launchAfterOnEnterDispatch, yet still drains a queued
// message and must still carry the handoff.
func TestProcessOnEnter_NoOnEnterActionsDrainDeliversHandoff(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-no-onenter-drain"
sessionID = "session-no-onenter-drain"
stepID = "step1"
queued = "drain me too"
carried = "no on_enter carried text"
)
repo := setupTestRepo(t)
seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput)
seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-no-onenter")
agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo}
svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr)
svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{})
seedExecutorRunning(t, repo, sessionID, taskID, "exec-no-onenter-drain")
_, err := svc.messageQueue.QueueMessage(ctx, sessionID, taskID, queued, "", "user", false, nil)
require.NoError(t, err)
session, err := repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
done := make(chan struct{})
svc.onQueuedMessageExecutionComplete = func() { close(done) }
step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Step 1"}
svc.processOnEnter(ctx, taskID, session, step, "task description", 0, nil)
select {
case <-done:
case <-time.After(5 * time.Second):
t.Fatal("timed out waiting for the drained queue message to dispatch")
}
if _, present := carryToken(t, repo, taskID); present {
t.Fatal("processOnEnter's own drain-only early return must claim the token when it dispatches")
}
require.Len(t, agentMgr.capturedPrompts, 1)
prompt := agentMgr.capturedPrompts[0]
require.Contains(t, prompt, queued)
require.Contains(t, prompt, carried, "processOnEnter's drain-only early return must deliver the claimed handoff text")
}
// TestLaunchAfterOnEnterDispatch_EmptyEntrySendsNothingClaimsNothing covers
// AC-001.6a: when a step entry decides — over content excluding the handoff
// text — that it will send the agent nothing, the handoff must never be
// claimed. Modeled on TestWorkflowAutoStartEmptyPrompt's "prompted session
// suppresses task description" case, which reaches autoStartStepPrompt's own
// early return with no queued hand-off to fall back to.
func TestLaunchAfterOnEnterDispatch_EmptyEntrySendsNothingClaimsNothing(t *testing.T) {
fixture := newInitialPromptDedupFixture(t, true, false)
seedHandoffCarryToken(t, fixture.repo, fixture.taskID, fixture.step.ID, "must not be claimed", "stamp-unsent")
fixture.svc.launchAfterOnEnterDispatch(
context.Background(), fixture.taskID, fixture.session, fixture.step,
fixture.taskDescription, false, true, false,
)
if len(fixture.agent.capturedPrompts) != 0 {
t.Fatalf("captured prompts = %#v, want none", fixture.agent.capturedPrompts)
}
token, present := carryToken(t, fixture.repo, fixture.taskID)
if !present || token.Handoff != "must not be claimed" {
t.Fatalf("a dispatch that sends nothing must not claim the token, got present=%v token=%+v", present, token)
}
}
// TestAutoStartPassthroughPrompt_ClaimedTokenNotRestoredOnDispatchFailure
// covers AC-001.9: a claimed token is never restored, even when the entry
// that claimed it then fails to dispatch — and a later entry into that same
// step gets no handoff either, since REQ-005 accepts the handoff as lost
// rather than risk a double-delivery on retry.
func TestAutoStartPassthroughPrompt_ClaimedTokenNotRestoredOnDispatchFailure(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-unrestored-handoff"
sessionID = "session-unrestored-handoff"
stepID = "step-next"
carried = "lost on dispatch failure"
)
repo := setupTestRepo(t)
seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput)
seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-unrestored")
agentMgr := &mockAgentManager{
isAgentRunning: true, repoForExecutionLookup: repo, isPassthrough: true,
passthroughStdinErr: errors.New("simulated stdin write failure"),
}
svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr)
svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{})
seedExecutorRunning(t, repo, sessionID, taskID, "exec-unrestored-handoff")
session, err := repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Next", Prompt: "go"}
svc.launchAfterOnEnterDispatch(ctx, taskID, session, step, "task description", false, true, false)
if _, present := carryToken(t, repo, taskID); present {
t.Fatal("the token must be claimed (removed) even though dispatch failed")
}
text, claimed := svc.claimStepHandoffCarryText(ctx, taskID, stepID)
if claimed || text != "" {
t.Fatalf("a later entry into the same step must get nothing back, got claimed=%v text=%q", claimed, text)
}
}
// TestStartSessionForWorkflowStep_DeliversHandoff covers AC-001.11: the queue
// promotion / manual auto-start dispatch path also claims and appends the
// completion handoff.
func TestStartSessionForWorkflowStep_DeliversHandoff(t *testing.T) {
fixture := newInitialPromptDedupFixture(t, true, false)
fixture.step.Prompt = "Continue with validation."
seedHandoffCarryToken(t, fixture.repo, fixture.taskID, fixture.step.ID, "queue promotion carried text", "stamp-queue-promo")
if err := fixture.svc.StartSessionForWorkflowStep(
context.Background(), fixture.taskID, fixture.sessionID, fixture.step.ID,
); err != nil {
t.Fatalf("StartSessionForWorkflowStep returned error: %v", err)
}
got := fixture.agent.capturedPrompts
if len(got) != 1 || !strings.Contains(got[0], fixture.step.Prompt) || !strings.Contains(got[0], "queue promotion carried text") {
t.Fatalf("captured prompts = %#v, want step prompt plus carried handoff", got)
}
if _, present := carryToken(t, fixture.repo, fixture.taskID); present {
t.Fatal("the claimed token must be removed")
}
}
// TestStartSessionForWorkflowStep_ComposedHandoffSurvivesLazyResumeFallback
// covers the same ErrExecutionNotFound-after-lazy-resume race
// autoStartStepPrompt and promptTask's own internal recovery were already
// fixed for, at the one remaining composed-prompt caller: StartSessionForWorkflowStep
// appends a claimed handoff to effectivePrompt before dispatch, but used to
// call the public PromptTask (promptAlreadyComposed defaults to false), so a
// missing-execution race hitting promptTask's internal recovery would
// recompose the prompt from the destination step's own template and silently
// drop the handoff.
func TestStartSessionForWorkflowStep_ComposedHandoffSurvivesLazyResumeFallback(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-workflow-step-lazy-resume"
sessionID = "session-workflow-step-lazy-resume"
stepID = "step-workflow-step-lazy-resume"
handoff = "watch out for the flaky test"
)
repo := setupTestRepo(t)
seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput)
session, err := repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
session.AgentExecutionID = "exec-before-restart"
session.AgentProfileID = "profile-lazy-resume"
require.NoError(t, repo.UpdateTaskSession(ctx, session))
seedExecutorRunning(t, repo, sessionID, taskID, "exec-before-restart")
seedHandoffCarryToken(t, repo, taskID, stepID, handoff, "stamp-lazy-resume")
stepGetter := newMockStepGetter()
stepGetter.steps[stepID] = &wfmodels.WorkflowStep{
ID: stepID, WorkflowID: "wf1", Name: "Next",
Prompt: "Recomposed step instructions.",
Events: wfmodels.StepEvents{OnEnter: []wfmodels.OnEnterAction{{Type: wfmodels.OnEnterEnablePlanMode}}},
}
taskRepo := newMockTaskRepo()
taskRepo.tasks[taskID] = &v1.Task{ID: taskID, Title: "Test Task", State: v1.TaskStateInProgress}
// IsAgentRunningForSession reports "running" for every call except the
// second: StartSessionForWorkflowStep's own ensureSessionRunning (call 1)
// sees the session as already running and skips resuming it, then
// promptTask's internal hadExecutionBeforeEnsure check (call 2) hits a
// momentary "not running" blip — the exact lazy-resume race
// promptTask's own internal ErrExecutionNotFound recovery exists for —
// before promptTask's own ensureSessionRunning call (call 3) sees it
// running again and does not attempt a second resume. No cold-resume
// launch is needed to reach this state; the only launch in this test is
// the fresh-launch fallback after PromptAgent reports ErrExecutionNotFound.
var runningChecks atomic.Int32
var launchCalls atomic.Int32
launchPrompts := make(chan string, 1)
agentMgr := &mockAgentManager{
repoForExecutionLookup: repo,
promptErr: executor.ErrExecutionNotFound,
isAgentRunningFn: func(_ context.Context, _ string) bool {
return runningChecks.Add(1) != 2
},
isAgentReadyFn: func(_ context.Context, _ string) bool { return true },
launchAgentFunc: func(_ context.Context, req *executor.LaunchAgentRequest) (*executor.LaunchAgentResponse, error) {
call := launchCalls.Add(1)
launchPrompts <- req.TaskDescription
return &executor.LaunchAgentResponse{AgentExecutionID: fmt.Sprintf("exec-fresh-%d", call)}, nil
},
}
svc := createTestServiceWithAgent(repo, stepGetter, taskRepo, agentMgr)
exec := executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{})
svc.executor = exec
svc.scheduler = scheduler.NewScheduler(queue.NewTaskQueue(100), exec, taskRepo, testLogger(), scheduler.DefaultSchedulerConfig())
svc.messageCreator = &mockMessageCreator{}
err = svc.StartSessionForWorkflowStep(ctx, taskID, sessionID, stepID)
require.NoError(t, err)
require.Equal(t, int32(1), launchCalls.Load(), "expected exactly the fresh-launch fallback, no cold-resume launch")
freshPrompt := <-launchPrompts
require.Contains(t, freshPrompt, handoff,
"the already-composed prompt (with the claimed handoff) must survive the fresh-launch fallback")
require.Contains(t, freshPrompt, sysprompt.PlanMode(),
"the fresh-launch fallback must retain the destination step's plan-mode instructions")
require.NotEqual(t, "Recomposed step instructions.", strings.TrimSpace(freshPrompt),
"promptAlreadyComposed must skip StartCreatedSession's own step-template recomposition")
}
// TestAutoStartStepPrompt_QueueFallbackWhenRunningCarriesHandoffMetadata covers
// AC-001.6/AC-001.8's queue-fallback half: when autoStartStepPrompt's
// shouldQueueIfBusy branch queues instead of dispatching directly (the
// session is already RUNNING), the handoff already claimed for this step
// entry must ride along as queue metadata — not the raw pre-handoff prompt —
// so a later drain (through the ordinary, non-handoff-aware drain path every
// other queued message uses) still appends it, last, after entity-reference
// expansion.
func TestAutoStartStepPrompt_QueueFallbackWhenRunningCarriesHandoffMetadata(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-queue-fallback-running"
sessionID = "session-queue-fallback-running"
stepID = "step-next"
autoStart = "Run the next workflow step"
carried = "carried through queue fallback"
)
repo := setupTestRepo(t)
seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateRunning)
seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-queue-fallback")
agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo}
svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr)
svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{})
seedExecutorRunning(t, repo, sessionID, taskID, "exec-queue-fallback-running")
session, err := repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Next"}
err = svc.autoStartStepPrompt(ctx, taskID, session, step, autoStart, false, true, newStepHandoffOnce())
require.NoError(t, err)
require.Empty(t, agentMgr.capturedPrompts, "a queued-because-running fallback must not dispatch directly")
if _, present := carryToken(t, repo, taskID); present {
t.Fatal("the queue-fallback path must still claim the token up front, before deciding to queue")
}
entries, _, err := svc.messageQueue.SnapshotSession(ctx, sessionID)
require.NoError(t, err)
require.Len(t, entries, 1)
require.Equal(t, carried, stepHandoffFromQueuedMetadata(entries[0].Metadata),
"the queued message metadata must carry the already-claimed handoff, not silently drop it")
// Drain through the ordinary, non-handoff-aware path every other queued
// message goes through in production. If the fix instead spliced the
// handoff onto raw Content at queue time, this would double as an
// ordering bug; carrying it as metadata means the generic drain path
// (which knows nothing about step handoffs) still appends it correctly.
require.NoError(t, repo.UpdateTaskSessionState(ctx, sessionID, models.TaskSessionStateWaitingForInput, ""))
done := make(chan struct{})
svc.onQueuedMessageExecutionComplete = func() { close(done) }
require.True(t, svc.drainQueuedMessageForPromptableSessionLocked(ctx, sessionID))
select {
case <-done:
case <-time.After(5 * time.Second):
t.Fatal("timed out waiting for the drained queue message to dispatch")
}
require.Len(t, agentMgr.capturedPrompts, 1)
prompt := agentMgr.capturedPrompts[0]
autoStartIdx := strings.Index(prompt, autoStart)
headingIdx := strings.Index(prompt, stepHandoffPromptHeading)
carriedIdx := strings.Index(prompt, carried)
require.NotEqual(t, -1, autoStartIdx, "prompt = %q", prompt)
require.NotEqual(t, -1, headingIdx, "prompt = %q", prompt)
require.NotEqual(t, -1, carriedIdx, "prompt = %q", prompt)
require.True(t, autoStartIdx < headingIdx && headingIdx < carriedIdx,
"the handoff must land last in the drained prompt")
}
// TestAutoStartStepPrompt_QueueFallbackPreservesEntityReferenceOrderingBeforeHandoff
// covers the MAJOR ordering finding directly: a queue-fallback re-queues a
// message carrying entity references (taken from an existing queued hand-off)
// alongside the claimed step handoff. AppendEntityReferenceContext only runs
// at actual dispatch/drain time, so the drained prompt must still show the
// reference block before the handoff heading — proving the fix appends the
// handoff after reference expansion rather than baking it into raw Content at
// queue time, which would let expansion land after it.
func TestAutoStartStepPrompt_QueueFallbackPreservesEntityReferenceOrderingBeforeHandoff(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-queue-fallback-refs"
sessionID = "session-queue-fallback-refs"
stepID = "step-next"
autoStart = "Run the next workflow step"
queued = "please also check the migration"
carried = "watch out for the flaky test"
)
repo := setupTestRepo(t)
seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateRunning)
seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-queue-fallback-refs")
agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo}
svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr)
svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{})
seedExecutorRunning(t, repo, sessionID, taskID, "exec-queue-fallback-refs")
reference := queuedReferenceFixture()
_, err := svc.messageQueue.QueueMessageWithMetadata(
ctx, sessionID, taskID, queued, "", messagequeue.QueuedByUser, false, nil,
map[string]interface{}{messagequeue.MetadataEntityReferences: []v1.EntityReference{reference}},
)
require.NoError(t, err)
session, err := repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Next"}
err = svc.autoStartStepPrompt(ctx, taskID, session, step, autoStart, false, true, newStepHandoffOnce())
require.NoError(t, err)
require.Empty(t, agentMgr.capturedPrompts)
require.NoError(t, repo.UpdateTaskSessionState(ctx, sessionID, models.TaskSessionStateWaitingForInput, ""))
done := make(chan struct{})
svc.onQueuedMessageExecutionComplete = func() { close(done) }
require.True(t, svc.drainQueuedMessageForPromptableSessionLocked(ctx, sessionID))
select {
case <-done:
case <-time.After(5 * time.Second):
t.Fatal("timed out waiting for the drained queue message to dispatch")
}
require.Len(t, agentMgr.capturedPrompts, 1)
prompt := agentMgr.capturedPrompts[0]
queuedIdx := strings.Index(prompt, queued)
referenceIdx := strings.Index(prompt, "Validated work-item reference snapshots")
headingIdx := strings.Index(prompt, stepHandoffPromptHeading)
carriedIdx := strings.Index(prompt, carried)
require.NotEqual(t, -1, queuedIdx, "prompt = %q", prompt)
require.NotEqual(t, -1, referenceIdx, "prompt = %q", prompt)
require.NotEqual(t, -1, headingIdx, "prompt = %q", prompt)
require.NotEqual(t, -1, carriedIdx, "prompt = %q", prompt)
require.True(t, queuedIdx < referenceIdx && referenceIdx < headingIdx && headingIdx < carriedIdx,
"entity-reference expansion must land before the handoff, which must land last; prompt = %q", prompt)
}
func TestAutoStartStepPrompt_MergesQueuedStepHandoff(t *testing.T) {
ctx := context.Background()
fixture := newInitialPromptDedupFixture(t, true, false)
const queuedHandoff = "handoff already claimed by the queued entry"
_, err := fixture.svc.messageQueue.QueueMessageWithMetadata(
ctx,
fixture.sessionID,
fixture.taskID,
"queued workflow message",
"",
messagequeue.QueuedByWorkflow,
false,
nil,
map[string]interface{}{messagequeue.MetadataStepHandoff: queuedHandoff},
)
require.NoError(t, err)
err = fixture.svc.autoStartStepPrompt(
ctx, fixture.taskID, fixture.session, fixture.step,
"start the next step", false, true, newStepHandoffOnce(),
)
require.NoError(t, err)
require.Len(t, fixture.agent.capturedPrompts, 1)
require.Contains(t, fixture.agent.capturedPrompts[0], queuedHandoff,
"a queued entry's previously claimed handoff must survive auto-start merging")
}
// failOnceHandoffClaimRepo wraps a real repo's TakeTaskMetadataKeyIfDestinationStep
// so its first invocation fails, standing in for a transient claim error. Per
// AC-005.2, a failed claim must not spend the step entry's one-claim budget, so
// a later attempt within the same entry (e.g. a replacement launch) must retry
// and succeed against the still-present token.
type failOnceHandoffClaimRepo struct {
sessionExecutorStore
failed bool
}
func (r *failOnceHandoffClaimRepo) TakeTaskMetadataKeyIfDestinationStep(
ctx context.Context, taskID, key, expectedStepID, expectedStamp string,
) (json.RawMessage, bool, error) {
if !r.failed {
r.failed = true
return nil, false, errors.New("simulated transient claim failure")
}
taker, ok := r.sessionExecutorStore.(taskMetadataCarryTaker)
if !ok {
return nil, false, errors.New("handoff claim capability is unavailable")
}
return taker.TakeTaskMetadataKeyIfDestinationStep(ctx, taskID, key, expectedStepID, expectedStamp)
}
// TestClaimStepHandoffCarryText_FailedClaimDoesNotSpendBudget covers AC-005.2:
// a failed claim attempt must not memoize an empty result, so a later attempt
// in the same step entry (sharing the same stepHandoffOnce) retries and can
// still succeed.
func TestClaimStepHandoffCarryText_FailedClaimDoesNotSpendBudget(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-failed-claim-retry"
stepID = "step2"
carried = "carried after retry"
)
repo := setupTestRepo(t)
seedSession(t, repo, taskID, "session-failed-claim-retry", "step1")
seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-retry")
svc := createTestService(repo, twoStepGetter(), newMockTaskRepo())
wrapped := &failOnceHandoffClaimRepo{sessionExecutorStore: svc.repo}
svc.repo = wrapped
once := newStepHandoffOnce()
text := svc.resolveStepHandoffText(ctx, once, taskID, stepID, true)
require.Empty(t, text, "the first, failing attempt must not deliver a handoff")
require.True(t, wrapped.failed, "expected the wrapped claim to have been invoked")
text = svc.resolveStepHandoffText(ctx, once, taskID, stepID, true)
require.Equal(t, carried, text, "a retried attempt must claim the still-present token")
}
// TestLaunchAfterOnEnterDispatch_FallbackDrainDeliversHandoff covers F22's
// fourth gap: the final fallback drain for a step with no auto_start_agent and
// no profile switch (e.g. a Review-shaped step) still carries the handoff.
func TestLaunchAfterOnEnterDispatch_FallbackDrainDeliversHandoff(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-fallback-drain"
sessionID = "session-fallback-drain"
stepID = "step-review"
queued = "drain via fallback"
carried = "fallback carried text"
)
repo := setupTestRepo(t)
seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput)
seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-fallback")
agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo}
svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr)
svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{})
seedExecutorRunning(t, repo, sessionID, taskID, "exec-fallback-drain")
_, err := svc.messageQueue.QueueMessage(ctx, sessionID, taskID, queued, "", "user", false, nil)
require.NoError(t, err)
session, err := repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
// hasAutoStart=false, sessionSwitched=false: neither the ACP branch nor the
// implicit profile-switch branch applies, landing on the final fallback
// drain — the shape a step without auto_start_agent (e.g. Review) takes.
done := make(chan struct{})
svc.onQueuedMessageExecutionComplete = func() { close(done) }
step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Review"}
svc.launchAfterOnEnterDispatch(ctx, taskID, session, step, "task description", false, false, false)
select {
case <-done:
case <-time.After(5 * time.Second):
t.Fatal("timed out waiting for the drained queue message to dispatch")
}
if _, present := carryToken(t, repo, taskID); present {
t.Fatal("the final fallback drain must claim the token when it dispatches")
}
require.Len(t, agentMgr.capturedPrompts, 1)
prompt := agentMgr.capturedPrompts[0]
require.Contains(t, prompt, queued)
require.Contains(t, prompt, carried, "the final fallback drain must deliver the claimed handoff text")
}
// TestLaunchAfterOnEnterDispatch_AsyncProfileSwitchFailureDrainDeliversHandoff
// covers F22's third gap: when the implicit profile-switch async launch fails
// to dispatch, the failure drain reuses the already-claimed handoff text (the
// shared stepHandoffOnce, not a fresh claim) and delivers it via the drained
// queued message.
func TestLaunchAfterOnEnterDispatch_AsyncProfileSwitchFailureDrainDeliversHandoff(t *testing.T) {
ctx := context.Background()
const (
taskID = "task-profile-switch-drain"
sessionID = "session-profile-switch-drain"
stepID = "step-next"
queued = "queued after failed switch"
carried = "profile switch carried text"
)
repo := setupTestRepo(t)
seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput)
seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-profile-switch")
agentMgr := &mockAgentManager{
isAgentRunning: true, repoForExecutionLookup: repo,
promptErr: errors.New("simulated fatal profile switch prompt error"),
}
svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr)
svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{})
seedExecutorRunning(t, repo, sessionID, taskID, "exec-profile-switch-drain")
_, err := svc.messageQueue.QueueMessage(ctx, sessionID, taskID, queued, "", "user", false, nil)
require.NoError(t, err)
session, err := repo.GetTaskSession(ctx, sessionID)
require.NoError(t, err)
done := make(chan struct{})
svc.onQueuedMessageExecutionComplete = func() { close(done) }
// sessionSwitched=true with a non-empty step.Prompt and hasAutoStart=false
// selects the implicit profile-switch async goroutine (the design's
// AC-005-adjacent "profile switch failure" branch): the launch fails, then
// the failure drain must deliver the queued message with the handoff the
// launch attempt already claimed.
step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Next", Prompt: "please continue"}
svc.launchAfterOnEnterDispatch(ctx, taskID, session, step, "task description", false, false, true)
select {
case <-done:
case <-time.After(5 * time.Second):
t.Fatal("timed out waiting for the queued message to execute after the failed profile-switch dispatch")
}
require.GreaterOrEqual(t, len(agentMgr.capturedPrompts), 2,
"expected the failed profile-switch attempt plus the drained queued dispatch")
last := agentMgr.capturedPrompts[len(agentMgr.capturedPrompts)-1]
require.Contains(t, last, queued)
require.Contains(t, last, carried, "the drain must reuse the already-claimed handoff text")
if _, present := carryToken(t, repo, taskID); present {
t.Fatal("the token must have been claimed by the failed attempt")
}
}
@@ -0,0 +1,385 @@
package orchestrator
import (
"context"
"encoding/json"
"testing"
"github.com/kandev/kandev/internal/task/models"
"github.com/kandev/kandev/internal/workflow/engine"
wfmodels "github.com/kandev/kandev/internal/workflow/models"
)
func carryToken(t *testing.T, repo interface {
GetTask(ctx context.Context, id string) (*models.Task, error)
}, taskID string) (models.StepHandoffCarryToken, bool) {
t.Helper()
task, err := repo.GetTask(context.Background(), taskID)
if err != nil {
t.Fatalf("GetTask: %v", err)
}
raw, present := task.Metadata[models.MetaKeyStepHandoffCarry]
if !present {
return models.StepHandoffCarryToken{}, false
}
bytes, err := json.Marshal(raw)
if err != nil {
t.Fatalf("marshal carry token: %v", err)
}
var token models.StepHandoffCarryToken
if err := json.Unmarshal(bytes, &token); err != nil {
t.Fatalf("unmarshal carry token: %v", err)
}
return token, true
}
// TestExecuteStepTransition_WritesHandoffCarryToken covers AC-001.2 on the
// legacy funnel: a consumed signal carrying a non-blank handoff is written as
// a carry token addressed to the destination step.
func TestExecuteStepTransition_WritesHandoffCarryToken(t *testing.T) {
ctx := context.Background()
repo := setupTestRepo(t)
seedSession(t, repo, "t1", "s1", "step1")
sg := twoStepGetter()
svc := createTestService(repo, sg, newMockTaskRepo())
svc.stepHistoryRecorder = &fakeStepHistoryRecorder{}
signal := models.PendingStepCompletionSignal{
StepID: "step1",
Source: models.StepCompletionSourceAgent,
Summary: "did the work",
Handoff: "watch out for X",
}
if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil {
t.Fatalf("seed pending signal: %v", err)
}
svc.executeStepTransition(ctx, "t1", "s1", sg.steps["step1"], "step2", true)
token, present := carryToken(t, repo, "t1")
if !present {
t.Fatal("expected a carry token to be written")
}
if token.Handoff != "watch out for X" || token.StepID != "step2" || token.Stamp == "" {
t.Fatalf("token = %+v, want handoff for step2 with a stamp", token)
}
}
// TestExecuteStepTransition_BlankHandoffRemovesToken covers AC-001.2's other
// half: a consumed signal with no handoff text removes any existing token
// rather than writing a blank one.
func TestExecuteStepTransition_BlankHandoffRemovesToken(t *testing.T) {
ctx := context.Background()
repo := setupTestRepo(t)
seedSession(t, repo, "t1", "s1", "step1")
if err := repo.SetTaskMetadataKey(ctx, "t1", models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{
Handoff: "stale", StepID: "step2", Stamp: "stale-stamp",
}); err != nil {
t.Fatalf("seed stale token: %v", err)
}
sg := twoStepGetter()
svc := createTestService(repo, sg, newMockTaskRepo())
svc.stepHistoryRecorder = &fakeStepHistoryRecorder{}
signal := models.PendingStepCompletionSignal{StepID: "step1", Source: models.StepCompletionSourceAgent, Summary: "done"}
if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil {
t.Fatalf("seed pending signal: %v", err)
}
svc.executeStepTransition(ctx, "t1", "s1", sg.steps["step1"], "step2", true)
if _, present := carryToken(t, repo, "t1"); present {
t.Fatal("expected the stale token to be removed when the consumed signal has no handoff")
}
}
// TestExecuteStepTransition_OnTurnStartDoesNotTouchToken covers AC-001.2a: a
// non-consuming (on_turn_start) transition must not write or remove the
// token, since only the consuming transition may act on it.
func TestExecuteStepTransition_OnTurnStartDoesNotTouchToken(t *testing.T) {
ctx := context.Background()
repo := setupTestRepo(t)
seedSession(t, repo, "t1", "s1", "step1")
if err := repo.SetTaskMetadataKey(ctx, "t1", models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{
Handoff: "keep me", StepID: "step3", Stamp: "kept-stamp",
}); err != nil {
t.Fatalf("seed existing token: %v", err)
}
sg := twoStepGetter()
svc := createTestService(repo, sg, newMockTaskRepo())
svc.stepHistoryRecorder = &fakeStepHistoryRecorder{}
signal := models.PendingStepCompletionSignal{StepID: "step1", Source: models.StepCompletionSourceAgent, Summary: "premature"}
if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil {
t.Fatalf("seed pending signal: %v", err)
}
svc.executeStepTransition(ctx, "t1", "s1", sg.steps["step1"], "step2", false)
token, present := carryToken(t, repo, "t1")
if !present || token.StepID != "step3" || token.Handoff != "keep me" {
t.Fatalf("on_turn_start transition must leave the existing token untouched, got present=%v token=%+v", present, token)
}
}
// TestExecuteStepTransition_QueuedTransitionStillWritesHandoffCarryToken
// covers AC-001.11's legacy-funnel half: a transition that lands the task in
// a WIP-full queued state still commits — the task's step already changed,
// only dispatch is deferred until a queue promotion admits it. The carry
// token (and the audit metadata) must be captured at commit time, because
// StartSessionForWorkflowStep claims the token at promotion and has no other
// way to learn one was ever written.
func TestExecuteStepTransition_QueuedTransitionStillWritesHandoffCarryToken(t *testing.T) {
ctx := context.Background()
repo := setupTestRepo(t)
seedSession(t, repo, "t1", "s1", "step1")
if err := repo.CreateTask(ctx, &models.Task{
ID: "occupant",
WorkspaceID: "ws1",
WorkflowID: "wf1",
WorkflowStepID: "step2",
Title: "Occupant",
State: "TODO",
Priority: "medium",
}); err != nil {
t.Fatalf("create occupant: %v", err)
}
steps := newMockStepGetter()
fromStep := &wfmodels.WorkflowStep{ID: "step1", WorkflowID: "wf1", Name: "Source"}
steps.steps["step2"] = &wfmodels.WorkflowStep{
ID: "step2", WorkflowID: "wf1", Name: "Limited", WIPLimit: 1,
}
svc := createTestService(repo, steps, newMockTaskRepo())
recorder := &fakeStepHistoryRecorder{}
svc.stepHistoryRecorder = recorder
signal := models.PendingStepCompletionSignal{
StepID: "step1",
Source: models.StepCompletionSourceAgent,
Summary: "did the work",
Handoff: "watch out for X",
}
if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil {
t.Fatalf("seed pending signal: %v", err)
}
svc.executeStepTransition(ctx, "t1", "s1", fromStep, "step2", true)
task, err := repo.GetTask(ctx, "t1")
if err != nil {
t.Fatalf("load task: %v", err)
}
if task.WorkflowStepID != "step2" || task.WIPAdmitted || task.QueuedForStepID != "step2" {
t.Fatalf("queued task placement: step=%q admitted=%t queue=%q", task.WorkflowStepID, task.WIPAdmitted, task.QueuedForStepID)
}
token, present := carryToken(t, repo, "t1")
if !present {
t.Fatal("a queued transition must still write the carry token so a later queue promotion can claim it")
}
if token.Handoff != "watch out for X" || token.StepID != "step2" {
t.Fatalf("token = %+v, want handoff for step2", token)
}
calls := recorder.Calls()
if len(calls) != 1 {
t.Fatalf("expected 1 recorded transition even though dispatch is deferred, got %d", len(calls))
}
if calls[0].metadata["signal_handoff"] != "watch out for X" {
t.Errorf("metadata[signal_handoff] = %v, want 'watch out for X'", calls[0].metadata["signal_handoff"])
}
session, err := repo.GetTaskSession(ctx, "s1")
if err != nil {
t.Fatalf("load session: %v", err)
}
if _, has := models.LoadPendingStepSignal(session.Metadata); has {
t.Fatal("the consumed signal bag must be cleared even when the transition's dispatch is deferred by the queue")
}
}
// TestApplyEngineTransition_WritesHandoffCarryToken covers AC-001.2 on the
// engine funnel, proving both consuming-transition sites carry the token.
func TestApplyEngineTransition_WritesHandoffCarryToken(t *testing.T) {
ctx := context.Background()
repo := setupTestRepo(t)
seedSession(t, repo, "t1", "s1", "step1")
sg := twoStepGetter()
svc := createTestService(repo, sg, newMockTaskRepo())
svc.SetWorkflowStepGetter(sg)
svc.stepHistoryRecorder = &fakeStepHistoryRecorder{}
onEnterDone := make(chan struct{})
svc.onProcessOnEnterComplete = func() { close(onEnterDone) }
signal := models.PendingStepCompletionSignal{
StepID: "step1",
Source: models.StepCompletionSourceAgent,
Summary: "engine path done",
Handoff: "engine handoff text",
}
if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil {
t.Fatalf("seed pending signal: %v", err)
}
session, err := repo.GetTaskSession(ctx, "s1")
if err != nil {
t.Fatalf("GetTaskSession: %v", err)
}
result := engine.HandleResult{Transitioned: true, FromStepID: "step1", ToStepID: "step2"}
transitioned := svc.applyEngineTransition(ctx, "t1", session, result, engine.TriggerOnTurnComplete, "desc", true)
if !transitioned {
t.Fatalf("expected transition to apply")
}
<-onEnterDone
token, present := carryToken(t, repo, "t1")
if !present {
t.Fatal("expected a carry token to be written by the engine funnel")
}
if token.StepID != "step2" {
// The dispatch side may have already claimed it as part of on_enter
// processing once wired; either the token is still addressed to
// step2 or it has already been claimed (removed). Both are
// acceptable outcomes here — what must NOT happen is a token
// addressed to any other step.
t.Fatalf("token = %+v, want step2", token)
}
}
// TestApplyEngineTransition_QueuedTransitionWritesHandoffCarryTokenAtAdmission
// covers the engine funnel's queue boundary: the carry token must be part of
// the same admission write as the queued destination, so promotion cannot
// start before the token exists.
func TestApplyEngineTransition_QueuedTransitionWritesHandoffCarryTokenAtAdmission(t *testing.T) {
ctx := context.Background()
repo := setupTestRepo(t)
seedSession(t, repo, "t1", "s1", "step1")
if err := repo.CreateTask(ctx, &models.Task{
ID: "occupant-engine",
WorkspaceID: "ws1",
WorkflowID: "wf1",
WorkflowStepID: "step2",
Title: "Occupant",
State: "TODO",
Priority: "medium",
}); err != nil {
t.Fatalf("create occupant: %v", err)
}
steps := newMockStepGetter()
steps.steps["step1"] = &wfmodels.WorkflowStep{ID: "step1", WorkflowID: "wf1", Name: "Source", Position: 0}
steps.steps["step2"] = &wfmodels.WorkflowStep{ID: "step2", WorkflowID: "wf1", Name: "Limited", Position: 1, WIPLimit: 1}
svc := createTestService(repo, steps, newMockTaskRepo())
svc.SetWorkflowStepGetter(steps)
svc.stepHistoryRecorder = &fakeStepHistoryRecorder{}
signal := models.PendingStepCompletionSignal{
StepID: "step1",
Source: models.StepCompletionSourceAgent,
Summary: "engine queued work",
Handoff: "carry before promotion",
}
if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil {
t.Fatalf("seed pending signal: %v", err)
}
session, err := repo.GetTaskSession(ctx, "s1")
if err != nil {
t.Fatalf("GetTaskSession: %v", err)
}
result := engine.HandleResult{Transitioned: true, FromStepID: "step1", ToStepID: "step2"}
if !svc.applyEngineTransition(ctx, "t1", session, result, engine.TriggerOnTurnComplete, "desc", true) {
t.Fatal("expected queued transition to apply")
}
task, err := repo.GetTask(ctx, "t1")
if err != nil {
t.Fatalf("load queued task: %v", err)
}
if task.WIPAdmitted || task.QueuedForStepID != "step2" {
t.Fatalf("expected task queued for step2, got admitted=%t queue=%q", task.WIPAdmitted, task.QueuedForStepID)
}
token, present := carryToken(t, repo, "t1")
if !present || token.Handoff != signal.Handoff || token.StepID != "step2" {
t.Fatalf("queued engine token = present=%v token=%+v, want step2 handoff", present, token)
}
}
// TestApplyEngineTransition_OnTurnStartDoesNotTouchToken covers AC-001.2a on
// the engine funnel: a non-consuming trigger must not touch the token.
func TestApplyEngineTransition_OnTurnStartDoesNotTouchToken(t *testing.T) {
ctx := context.Background()
repo := setupTestRepo(t)
seedSession(t, repo, "t1", "s1", "step1")
if err := repo.SetTaskMetadataKey(ctx, "t1", models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{
Handoff: "keep me", StepID: "step3", Stamp: "kept-stamp",
}); err != nil {
t.Fatalf("seed existing token: %v", err)
}
sg := twoStepGetter()
svc := createTestService(repo, sg, newMockTaskRepo())
svc.SetWorkflowStepGetter(sg)
svc.stepHistoryRecorder = &fakeStepHistoryRecorder{}
signal := models.PendingStepCompletionSignal{StepID: "step1", Source: models.StepCompletionSourceAgent, Summary: "premature"}
if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil {
t.Fatalf("seed pending signal: %v", err)
}
session, err := repo.GetTaskSession(ctx, "s1")
if err != nil {
t.Fatalf("GetTaskSession: %v", err)
}
result := engine.HandleResult{Transitioned: true, FromStepID: "step1", ToStepID: "step2"}
transitioned := svc.applyEngineTransition(ctx, "t1", session, result, engine.TriggerOnTurnStart, "desc", false)
if !transitioned {
t.Fatalf("expected transition to apply")
}
token, present := carryToken(t, repo, "t1")
if !present || token.StepID != "step3" || token.Handoff != "keep me" {
t.Fatalf("on_turn_start transition must leave the existing token untouched, got present=%v token=%+v", present, token)
}
}
// TestApplyEngineTransition_GuardedDecisionDoesNotTouchToken is the F15
// guarded-decision carve-out: a quorum/approval decision carries
// TriggerOnTurnComplete too, with no turn having ended, so a trigger-only
// gate would wipe an unclaimed token the instant a reviewer approves. Only
// the compound `sessionLifecycle && trigger == TriggerOnTurnComplete` gate
// must apply.
func TestApplyEngineTransition_GuardedDecisionDoesNotTouchToken(t *testing.T) {
ctx := context.Background()
repo := setupTestRepo(t)
seedSession(t, repo, "t1", "s1", "step1")
if err := repo.SetTaskMetadataKey(ctx, "t1", models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{
Handoff: "unclaimed", StepID: "step3", Stamp: "unclaimed-stamp",
}); err != nil {
t.Fatalf("seed existing token: %v", err)
}
sg := twoStepGetter()
svc := createTestService(repo, sg, newMockTaskRepo())
svc.SetWorkflowStepGetter(sg)
svc.stepHistoryRecorder = &fakeStepHistoryRecorder{}
session, err := repo.GetTaskSession(ctx, "s1")
if err != nil {
t.Fatalf("GetTaskSession: %v", err)
}
result := engine.HandleResult{Transitioned: true, FromStepID: "step1", ToStepID: "step2"}
applied := svc.applyEngineTransitionWithCommitMode(
ctx, "t1", session, result, engine.TriggerOnTurnComplete, "desc",
transitionLifecycleGuardedDecision,
func(commitCtx context.Context) (bool, error) { return true, nil },
)
if !applied {
t.Fatalf("expected guarded decision transition to apply")
}
token, present := carryToken(t, repo, "t1")
if !present || token.StepID != "step3" || token.Handoff != "unclaimed" {
t.Fatalf("guarded decision must leave the unclaimed token untouched, got present=%v token=%+v", present, token)
}
}
@@ -0,0 +1,169 @@
package orchestrator
import (
"context"
"testing"
"github.com/kandev/kandev/internal/task/models"
"github.com/kandev/kandev/internal/workflow/engine"
wfmodels "github.com/kandev/kandev/internal/workflow/models"
)
type rejectingAsyncStepHistoryRecorder struct {
fakeStepHistoryRecorder
}
func (*rejectingAsyncStepHistoryRecorder) EnqueueStepTransition(
string, string, string, wfmodels.StepTransitionTrigger, *string, map[string]interface{},
) bool {
return false
}
// TestRecordAutoStepTransition_FallsBackWhenHistoryQueueIsFull covers the
// signal-audit durability boundary: a bounded asynchronous writer may reject
// an enqueue, but the consumed signal's blockers and handoff must still be
// written through the bounded synchronous path.
func TestRecordAutoStepTransition_FallsBackWhenHistoryQueueIsFull(t *testing.T) {
svc := &Service{logger: testLogger()}
recorder := &rejectingAsyncStepHistoryRecorder{}
svc.stepHistoryRecorder = recorder
svc.recordAutoStepTransition(context.Background(), "session-1", "step-a", "step-b", &models.PendingStepCompletionSignal{
Source: models.StepCompletionSourceAgent,
Summary: "completed",
Handoff: "carry this",
Blockers: "needs review",
}, wfmodels.StepTransitionTriggerAutoComplete)
calls := recorder.Calls()
if len(calls) != 1 {
t.Fatalf("expected synchronous fallback to record one transition, got %d", len(calls))
}
if calls[0].metadata["signal_handoff"] != "carry this" || calls[0].metadata["signal_blockers"] != "needs review" {
t.Fatalf("fallback metadata = %#v, want signal handoff and blockers", calls[0].metadata)
}
}
// TestExecuteStepTransition_RecordsHandoffAndBlockersMetadata covers
// AC-002.1: the legacy funnel's audit metadata gains signal_blockers and
// signal_handoff alongside signal_source/signal_summary.
func TestExecuteStepTransition_RecordsHandoffAndBlockersMetadata(t *testing.T) {
ctx := context.Background()
repo := setupTestRepo(t)
seedSession(t, repo, "t1", "s1", "step1")
sg := twoStepGetter()
svc := createTestService(repo, sg, newMockTaskRepo())
recorder := &fakeStepHistoryRecorder{}
svc.stepHistoryRecorder = recorder
signal := models.PendingStepCompletionSignal{
StepID: "step1",
Source: models.StepCompletionSourceAgent,
Summary: "did the work",
Handoff: "watch out for X",
Blockers: "needs a design decision",
}
if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil {
t.Fatalf("seed pending signal: %v", err)
}
svc.executeStepTransition(ctx, "t1", "s1", sg.steps["step1"], "step2", true)
calls := recorder.Calls()
if len(calls) != 1 {
t.Fatalf("expected 1 recorded transition, got %d", len(calls))
}
got := calls[0]
if got.metadata["signal_handoff"] != "watch out for X" {
t.Errorf("metadata[signal_handoff] = %v, want 'watch out for X'", got.metadata["signal_handoff"])
}
if got.metadata["signal_blockers"] != "needs a design decision" {
t.Errorf("metadata[signal_blockers] = %v, want 'needs a design decision'", got.metadata["signal_blockers"])
}
}
// TestExecuteStepTransition_OmitsBlankHandoffAndBlockers covers AC-002.2: an
// empty or whitespace-only handoff/blockers is omitted from the audit
// metadata entirely rather than written as an empty entry.
func TestExecuteStepTransition_OmitsBlankHandoffAndBlockers(t *testing.T) {
ctx := context.Background()
repo := setupTestRepo(t)
seedSession(t, repo, "t1", "s1", "step1")
sg := twoStepGetter()
svc := createTestService(repo, sg, newMockTaskRepo())
recorder := &fakeStepHistoryRecorder{}
svc.stepHistoryRecorder = recorder
signal := models.PendingStepCompletionSignal{
StepID: "step1",
Source: models.StepCompletionSourceAgent,
Summary: "did the work",
}
if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil {
t.Fatalf("seed pending signal: %v", err)
}
svc.executeStepTransition(ctx, "t1", "s1", sg.steps["step1"], "step2", true)
calls := recorder.Calls()
if len(calls) != 1 {
t.Fatalf("expected 1 recorded transition, got %d", len(calls))
}
got := calls[0]
if _, ok := got.metadata["signal_handoff"]; ok {
t.Errorf("metadata must omit signal_handoff when blank, got %v", got.metadata["signal_handoff"])
}
if _, ok := got.metadata["signal_blockers"]; ok {
t.Errorf("metadata must omit signal_blockers when blank, got %v", got.metadata["signal_blockers"])
}
}
// TestApplyEngineTransition_RecordsHandoffAndBlockersMetadata covers the
// engine funnel's half of AC-002.1, proving both consuming-transition sites
// were updated (the design's named drift risk).
func TestApplyEngineTransition_RecordsHandoffAndBlockersMetadata(t *testing.T) {
ctx := context.Background()
repo := setupTestRepo(t)
seedSession(t, repo, "t1", "s1", "step1")
sg := twoStepGetter()
svc := createTestService(repo, sg, newMockTaskRepo())
svc.SetWorkflowStepGetter(sg)
recorder := &fakeStepHistoryRecorder{}
svc.stepHistoryRecorder = recorder
onEnterDone := make(chan struct{})
svc.onProcessOnEnterComplete = func() { close(onEnterDone) }
signal := models.PendingStepCompletionSignal{
StepID: "step1",
Source: models.StepCompletionSourceAgent,
Summary: "engine path done",
Handoff: "engine handoff text",
Blockers: "engine blocker text",
}
if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil {
t.Fatalf("seed pending signal: %v", err)
}
session, err := repo.GetTaskSession(ctx, "s1")
if err != nil {
t.Fatalf("GetTaskSession: %v", err)
}
result := engine.HandleResult{Transitioned: true, FromStepID: "step1", ToStepID: "step2"}
transitioned := svc.applyEngineTransition(ctx, "t1", session, result, engine.TriggerOnTurnComplete, "desc", true)
if !transitioned {
t.Fatalf("expected transition to apply")
}
<-onEnterDone
calls := recorder.Calls()
if len(calls) != 1 {
t.Fatalf("expected 1 recorded transition, got %d", len(calls))
}
got := calls[0]
if got.metadata["signal_handoff"] != "engine handoff text" {
t.Errorf("metadata[signal_handoff] = %v, want 'engine handoff text'", got.metadata["signal_handoff"])
}
if got.metadata["signal_blockers"] != "engine blocker text" {
t.Errorf("metadata[signal_blockers] = %v, want 'engine blocker text'", got.metadata["signal_blockers"])
}
}
@@ -2509,7 +2509,23 @@ func (s *Service) StartSessionForWorkflowStep(ctx context.Context, taskID, sessi
return nil
}
_, err = s.PromptTask(ctx, taskID, sessionID, effectivePrompt, "", stepPlanMode, nil, false)
// Claimed after the actionability decision above, over content that
// excludes the handoff text, then appended last. Queue promotion and
// manual auto-start dispatch once with no replacement launch, so no
// shared stepHandoffOnce is needed here.
handoffText, _ := s.claimStepHandoffCarryText(ctx, taskID, workflowStepID)
effectivePrompt = appendStepHandoffToPrompt(effectivePrompt, handoffText)
composedLaunchPrompt := appendStepHandoffToPrompt(promptForEmptinessCheck, handoffText)
// effectivePrompt is already fully composed for this step entry (handoff
// included): if promptTask's own internal ErrExecutionNotFound recovery
// fires, it must reuse this composed prompt rather than recomposing from
// the destination step's own template and discarding the handoff.
_, err = s.promptTask(ctx, taskID, sessionID, effectivePrompt, "", stepPlanMode, nil, false, promptTaskOptions{
promptAlreadyComposed: true,
fallbackLaunchPrompt: composedLaunchPrompt,
fallbackRetryPrompt: effectivePrompt,
})
if err != nil {
return fmt.Errorf("failed to prompt session: %w", err)
}
@@ -4221,6 +4237,21 @@ type promptTaskOptions struct {
// waits for the turn to finish. Automation callers use it to bind durable
// attempt identity to the exact turn.
onAccepted func(turnID string)
// promptAlreadyComposed and fallbackRetryPrompt mirror the composed-prompt
// seam autoStartStepPrompt's own ErrExecutionNotFound branch uses (see
// fallbackFreshLaunchOnMissingExecution). When promptAlreadyComposed is
// true, handlePromptDispatchFailure's own internal ErrExecutionNotFound
// recovery relaunches via startCreatedSessionWithComposedPrompt
// (fallbackRetryPrompt as its dispatch value) instead of the public
// StartCreatedSession, so a caller that already composed the prompt itself
// (e.g. appending a claimed step handoff) is not silently recomposed from
// the destination step's own template.
promptAlreadyComposed bool
// fallbackLaunchPrompt is the fully composed prompt for fresh-launch
// recovery. The normal dispatch still receives the raw prompt so it can
// apply session transforms exactly once.
fallbackLaunchPrompt string
fallbackRetryPrompt string
}
type promptDispatchOutcome struct {
@@ -4477,6 +4508,11 @@ func (s *Service) promptTask(ctx context.Context, taskID, sessionID string, prom
)
dispatchAccepted, publicationErr := dispatchOutcome.snapshot()
if err != nil {
// Missing-execution recovery reacquires the cancel guard while it resets
// the session. Release dispatch admission before entering that path.
if releaseDispatchGuard != nil {
releaseDispatchGuard()
}
return s.finishPromptDispatchFailure(
ctx, taskID, sessionID, prompt, planMode, resumedForPrompt, attachments,
rollback, options, err, foregroundDispatch, dispatchAccepted, publicationErr,
@@ -4511,6 +4547,7 @@ func (s *Service) finishPromptDispatchFailure(
failureResult, failureErr := s.handlePromptDispatchFailure(
failureCtx, taskID, sessionID, prompt, planMode, resumedForPrompt,
attachments, rollback, options.lifecyclePrompt, dispatchAccepted, promptErr,
options.promptAlreadyComposed, options.fallbackLaunchPrompt, options.fallbackRetryPrompt,
)
return failureResult, wrapAcceptedPromptDispatchFailure(
dispatchAccepted,
@@ -4980,6 +5017,11 @@ func (s *Service) restoreLifecycleTaskState(
// it falls back to a fresh launch instead of surfacing the error to the
// caller. Otherwise — or if that fallback launch itself fails — it
// delegates to handlePromptError for the caller-facing result.
// promptAlreadyComposed/fallbackRetryPrompt are the caller's promptTaskOptions
// values, forwarded to fallbackFreshLaunchOnMissingExecution so a caller that
// already composed the dispatch prompt (e.g. autoStartStepPrompt, which
// appends a claimed step handoff) is not silently recomposed from the
// destination step's own template by this internal recovery.
func (s *Service) handlePromptDispatchFailure(
ctx context.Context,
taskID, sessionID, prompt string,
@@ -4989,14 +5031,21 @@ func (s *Service) handlePromptDispatchFailure(
lifecyclePrompt bool,
dispatchAccepted bool,
promptErr error,
promptAlreadyComposed bool,
fallbackLaunchPrompt string,
fallbackRetryPrompt string,
) (*PromptResult, error) {
if resumedForPrompt && !dispatchAccepted && !rollback.reservedTurnAccepted && rollback.reservedTurn == nil &&
errors.Is(promptErr, executor.ErrExecutionNotFound) {
s.logger.Warn("prompt after lazy resume hit missing execution; falling back to fresh launch",
zap.String("task_id", taskID),
zap.String("session_id", sessionID))
fallbackPrompt := prompt
if fallbackLaunchPrompt != "" {
fallbackPrompt = fallbackLaunchPrompt
}
if freshErr := s.fallbackFreshLaunchOnMissingExecution(
ctx, taskID, sessionID, prompt, planMode, nil, attachments, nil,
ctx, taskID, sessionID, fallbackPrompt, promptAlreadyComposed, fallbackRetryPrompt, planMode, nil, attachments, nil,
); freshErr == nil {
return &PromptResult{}, nil
} else {
@@ -105,7 +105,7 @@ func TestAutoStartStepPrompt_ResetContextReinjectsSnapshottedPullRequestTarget(t
svc.messageCreator = messages
require.NoError(t, svc.autoStartStepPrompt(
ctx, "task1", session, step, "Review the release", false, false,
ctx, "task1", session, step, "Review the release", false, false, nil,
))
require.Len(t, messages.userMessages, 1)
require.Contains(t, messages.userMessages[0].content, `gh pr create --base "main"`)
@@ -328,6 +328,23 @@ func (s *workflowStore) applyTransition(ctx context.Context, taskID, sessionID,
delete(task.Metadata, models.MetaKeyQueuedMoveExitCompleted)
delete(task.Metadata, models.MetaKeyQueuePromotionPending)
}
// The on_turn_complete transition consumes the source session's signal.
// Put its carry token on this task snapshot before admission so a queued
// destination cannot be promoted between the transition commit and a later
// metadata write.
if trigger == engine.TriggerOnTurnComplete {
var consumedSignal *models.PendingStepCompletionSignal
session, sessionErr := s.repo.GetTaskSession(ctx, sessionID)
if sessionErr != nil {
s.logger.Debug("failed to load session for step handoff carry",
zap.String("session_id", sessionID), zap.Error(sessionErr))
} else if session != nil {
if signal, has := models.LoadPendingStepSignal(session.Metadata); has && signal.StepID == fromStepID {
consumedSignal = &signal
}
setStepHandoffCarryMetadata(task, toStepID, consumedSignal)
}
}
task.UpdatedAt = time.Now().UTC()
// engine_transition applies only when no outer caller already declared a
// trigger — applyPendingMove sets mcp_deferred_move before reaching this
@@ -215,8 +215,24 @@ const (
// whose Routine workflow start step has no other transition to carry it
// into an auto_start_agent evaluation.
MetaKeyAutoStartOnCreate = "auto_start_on_create"
// MetaKeyStepHandoffCarry is a single-slot, task-scoped token carrying one
// consuming transition's completion handoff exactly one hop, to the next
// step's first dispatched prompt. Its value is a StepHandoffCarryToken.
// Recording it replaces any existing token (single-slot by construction);
// claiming it removes it. See REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.
MetaKeyStepHandoffCarry = "step_handoff_carry"
)
// StepHandoffCarryToken is the JSON shape stored under
// tasks.metadata[MetaKeyStepHandoffCarry]. Stamp is a fresh unique value
// (uuid.NewString()) minted on every write, compared by the claim's
// compare-and-swap alongside StepID; it must never be content-derived.
type StepHandoffCarryToken struct {
Handoff string `json:"handoff"`
StepID string `json:"step_id"`
Stamp string `json:"stamp"`
}
// IsAgentTitlePending reports whether task metadata contains the durable
// pending title marker. JSON rehydration produces bool values, while a
// few in-process callers may provide typed metadata, so only an explicit true
@@ -3,13 +3,14 @@ package models
import "maps"
// PublicTaskMetadata returns a detached task metadata projection for API
// responses. Deferred launch attribution is server-owned and must never expose
// the creator's raw user ID or the internal recency marker.
// responses. Deferred-launch attribution and step-handoff carry are
// server-owned and must not expose their internal state to clients.
func PublicTaskMetadata(metadata map[string]interface{}) map[string]interface{} {
if metadata == nil {
return nil
}
public := maps.Clone(metadata)
delete(public, MetaKeyStepHandoffCarry)
deferred, ok := public[MetaKeyDeferredLaunch].(map[string]interface{})
if !ok {
return public
@@ -0,0 +1,25 @@
package models
import "testing"
func TestPublicTaskMetadataRedactsStepHandoffCarry(t *testing.T) {
metadata := map[string]interface{}{
"ordinary": "visible",
MetaKeyStepHandoffCarry: StepHandoffCarryToken{
Handoff: "private handoff",
StepID: "step-next",
Stamp: "private-stamp",
},
}
public := PublicTaskMetadata(metadata)
if _, ok := public[MetaKeyStepHandoffCarry]; ok {
t.Fatalf("public metadata must not expose %q", MetaKeyStepHandoffCarry)
}
if got := public["ordinary"]; got != "visible" {
t.Fatalf("ordinary metadata = %v, want visible", got)
}
if _, ok := metadata[MetaKeyStepHandoffCarry]; !ok {
t.Fatal("redaction must not mutate stored metadata")
}
}
@@ -0,0 +1,125 @@
package sqlite
import (
"context"
"encoding/json"
"testing"
"time"
"github.com/kandev/kandev/internal/task/models"
"github.com/kandev/kandev/internal/testutil"
)
// TestPostgresTakeTaskMetadataKeyIfDestinationStepUsesJSONB proves
// TakeTaskMetadataKeyIfDestinationStep's dialect.IsPostgres branch
// (jsonb_extract_path_text / #-) behaves the same as the SQLite json_extract
// path already covered in step_handoff_carry_claim_test.go: a matching
// step_id and stamp claims and returns the token, a token naming another
// step is left in place, and a stale stamp on the same step leaves a
// same-step replacement token in place.
func TestPostgresTakeTaskMetadataKeyIfDestinationStepUsesJSONB(t *testing.T) {
db := testutil.OpenIsolatedPostgres(t, testutil.PostgresDSNFromEnv(t))
repo, err := NewWithDB(db, db, nil)
if err != nil {
t.Fatalf("init postgres schema: %v", err)
}
ctx := context.Background()
now := time.Now().UTC()
seed := func(taskID string, metadata string) {
if _, err := db.Exec(db.Rebind(`
INSERT INTO tasks (id, title, metadata, created_at, updated_at)
VALUES (?, ?, ?, ?, ?)
`), taskID, "Postgres CAS task", metadata, now, now); err != nil {
t.Fatalf("seed task %s: %v", taskID, err)
}
}
t.Run("match claims and returns", func(t *testing.T) {
const taskID = "task-pg-handoff-carry-match"
seed(taskID, `{"step_handoff_carry":{"handoff":"watch the migration","step_id":"step-b","stamp":"stamp-1"}}`)
raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep(
ctx, taskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-1",
)
if err != nil {
t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err)
}
if !ok {
t.Fatal("expected the matching token to be claimed")
}
var token models.StepHandoffCarryToken
if err := json.Unmarshal(raw, &token); err != nil {
t.Fatalf("unmarshal claimed token: %v", err)
}
if token.Handoff != "watch the migration" || token.StepID != "step-b" || token.Stamp != "stamp-1" {
t.Fatalf("claimed token = %#v, want the seeded token", token)
}
task, err := repo.GetTask(ctx, taskID)
if err != nil {
t.Fatalf("reload task: %v", err)
}
if _, present := task.Metadata[models.MetaKeyStepHandoffCarry]; present {
t.Fatal("claimed token must be removed from task metadata")
}
})
t.Run("wrong step leaves token in place", func(t *testing.T) {
const taskID = "task-pg-handoff-carry-wrong-step"
seed(taskID, `{"step_handoff_carry":{"handoff":"for step C","step_id":"step-c","stamp":"stamp-2"}}`)
raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep(
ctx, taskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-2",
)
if err != nil {
t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err)
}
if ok || raw != nil {
t.Fatalf("expected no claim for a token naming another step, got ok=%v raw=%s", ok, raw)
}
task, err := repo.GetTask(ctx, taskID)
if err != nil {
t.Fatalf("reload task: %v", err)
}
stored, _ := task.Metadata[models.MetaKeyStepHandoffCarry].(map[string]interface{})
if stored["step_id"] != "step-c" {
t.Fatalf("stored token = %#v, want step-c untouched", stored)
}
})
t.Run("stale stamp leaves replacement in place", func(t *testing.T) {
const taskID = "task-pg-handoff-carry-stale-stamp"
seed(taskID, `{"step_handoff_carry":{"handoff":"stale text","step_id":"step-b","stamp":"stamp-old"}}`)
// Simulate a replacement landing between the caller's advisory read
// and its claim attempt: same step, new stamp, new text.
if err := repo.SetTaskMetadataKey(ctx, taskID, models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{
Handoff: "fresh text",
StepID: "step-b",
Stamp: "stamp-new",
}); err != nil {
t.Fatalf("simulate replacement: %v", err)
}
raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep(
ctx, taskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-old",
)
if err != nil {
t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err)
}
if ok || raw != nil {
t.Fatalf("expected no claim against a stale stamp, got ok=%v raw=%s", ok, raw)
}
task, err := repo.GetTask(ctx, taskID)
if err != nil {
t.Fatalf("reload task: %v", err)
}
stored, _ := task.Metadata[models.MetaKeyStepHandoffCarry].(map[string]interface{})
if stored["stamp"] != "stamp-new" {
t.Fatalf("stored token = %#v, want the replacement (stamp-new) untouched", stored)
}
})
}
@@ -0,0 +1,156 @@
package sqlite
import (
"context"
"encoding/json"
"testing"
"github.com/kandev/kandev/internal/task/models"
)
// TestTakeTaskMetadataKeyIfDestinationStep_MatchClaimsAndReturns covers the
// happy path: a token naming the step being entered, with the stamp read
// alongside it, is removed and its content returned.
func TestTakeTaskMetadataKeyIfDestinationStep_MatchClaimsAndReturns(t *testing.T) {
repo := newRepoForMetadataCASTests(t)
seedMetadataCASTask(t, repo, map[string]interface{}{
models.MetaKeyStepHandoffCarry: models.StepHandoffCarryToken{
Handoff: "watch the migration",
StepID: "step-b",
Stamp: "stamp-1",
},
})
ctx := context.Background()
raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep(
ctx, casTaskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-1",
)
if err != nil {
t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err)
}
if !ok {
t.Fatal("expected the matching token to be claimed")
}
var token models.StepHandoffCarryToken
if err := json.Unmarshal(raw, &token); err != nil {
t.Fatalf("unmarshal claimed token: %v", err)
}
if token.Handoff != "watch the migration" || token.StepID != "step-b" || token.Stamp != "stamp-1" {
t.Fatalf("claimed token = %#v, want the seeded token", token)
}
if _, found := metadataValue(t, repo, models.MetaKeyStepHandoffCarry); found {
t.Fatal("claimed token must be removed from task metadata")
}
}
// TestTakeTaskMetadataKeyIfDestinationStep_WrongStepLeavesTokenInPlace
// covers AC-001.5 against the race it actually guards: a caller can only ever
// hold a stamp read alongside a stepID before the claim attempt runs, so the
// regression case is a token that was REPLACED, naming a different
// destination, between that read and the claim — not merely "no token for
// this step ever existed". Seed a token for step-b, overwrite it with a fresh
// one for step-c (simulating a transition that landed in between), then claim
// with the original step-b/stamp-1 pair: the mismatch must leave the step-c
// replacement untouched so a later entry into step-c can still receive it.
func TestTakeTaskMetadataKeyIfDestinationStep_WrongStepLeavesTokenInPlace(t *testing.T) {
repo := newRepoForMetadataCASTests(t)
seedMetadataCASTask(t, repo, map[string]interface{}{
models.MetaKeyStepHandoffCarry: models.StepHandoffCarryToken{
Handoff: "for step B",
StepID: "step-b",
Stamp: "stamp-1",
},
})
ctx := context.Background()
if err := repo.SetTaskMetadataKey(ctx, casTaskID, models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{
Handoff: "for step C",
StepID: "step-c",
Stamp: "stamp-2",
}); err != nil {
t.Fatalf("simulate replacement to a different destination step: %v", err)
}
raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep(
ctx, casTaskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-1",
)
if err != nil {
t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err)
}
if ok || raw != nil {
t.Fatalf("expected no claim for a token naming another step, got ok=%v raw=%s", ok, raw)
}
stored, found := metadataValue(t, repo, models.MetaKeyStepHandoffCarry)
if !found {
t.Fatal("the step-c replacement must remain in place")
}
storedMap, _ := stored.(map[string]interface{})
if storedMap["step_id"] != "step-c" || storedMap["stamp"] != "stamp-2" {
t.Fatalf("stored token = %#v, want the step-c replacement untouched", stored)
}
}
// TestTakeTaskMetadataKeyIfDestinationStep_StaleStampLeavesReplacementInPlace
// covers the same-step race the stamp compare exists for: a caller holding a
// stale stamp for the CORRECT step must not remove a token that was replaced
// in between, and must not deliver the stale (already-superseded) text.
func TestTakeTaskMetadataKeyIfDestinationStep_StaleStampLeavesReplacementInPlace(t *testing.T) {
repo := newRepoForMetadataCASTests(t)
seedMetadataCASTask(t, repo, map[string]interface{}{
models.MetaKeyStepHandoffCarry: models.StepHandoffCarryToken{
Handoff: "stale text",
StepID: "step-b",
Stamp: "stamp-old",
},
})
ctx := context.Background()
// Simulate a replacement landing between the caller's advisory read and
// its claim attempt: same step, new stamp, new text.
if err := repo.SetTaskMetadataKey(ctx, casTaskID, models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{
Handoff: "fresh text",
StepID: "step-b",
Stamp: "stamp-new",
}); err != nil {
t.Fatalf("simulate replacement: %v", err)
}
raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep(
ctx, casTaskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-old",
)
if err != nil {
t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err)
}
if ok || raw != nil {
t.Fatalf("expected no claim against a stale stamp, got ok=%v raw=%s", ok, raw)
}
stored, found := metadataValue(t, repo, models.MetaKeyStepHandoffCarry)
if !found {
t.Fatal("the replacement token must survive a stale-stamp claim attempt")
}
storedMap, _ := stored.(map[string]interface{})
if storedMap["stamp"] != "stamp-new" {
t.Fatalf("stored token = %#v, want the replacement (stamp-new) untouched", stored)
}
}
// TestTakeTaskMetadataKeyIfDestinationStep_NoTokenIsANoOp covers the empty
// case: nothing is stored, nothing is claimed, no error.
func TestTakeTaskMetadataKeyIfDestinationStep_NoTokenIsANoOp(t *testing.T) {
repo := newRepoForMetadataCASTests(t)
seedMetadataCASTask(t, repo, map[string]interface{}{})
ctx := context.Background()
raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep(
ctx, casTaskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-1",
)
if err != nil {
t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err)
}
if ok || raw != nil {
t.Fatalf("expected no claim when no token exists, got ok=%v raw=%s", ok, raw)
}
}
@@ -1045,6 +1045,70 @@ func (r *Repository) RemoveTaskMetadataKeyIfStamp(
return rows > 0, err
}
// TakeTaskMetadataKeyIfDestinationStep removes one metadata object only when
// its nested step_id and stamp both equal the caller's expectations, and
// returns the object's raw JSON on a successful claim. The advisory read
// happens before the conditional removal; since stamp is a fresh unique value
// minted on every write (never content-derived), a removal that matches both
// step_id and stamp can only have removed the exact object just read.
func (r *Repository) TakeTaskMetadataKeyIfDestinationStep(
ctx context.Context,
taskID, key, expectedStepID, expectedStamp string,
) (json.RawMessage, bool, error) {
if strings.TrimSpace(expectedStepID) == "" || strings.TrimSpace(expectedStamp) == "" {
return nil, false, nil
}
task, err := r.GetTask(ctx, taskID)
if err != nil {
return nil, false, err
}
value, present := task.Metadata[key]
if !present {
return nil, false, nil
}
raw, err := json.Marshal(value)
if err != nil {
return nil, false, err
}
var query string
var args []interface{}
if dialect.IsPostgres(r.db.DriverName()) {
query = `
UPDATE tasks
SET metadata = (CASE WHEN metadata IS NULL OR metadata = 'null' OR metadata = '' THEN '{}'::jsonb ELSE metadata::jsonb END #- ARRAY[?]::text[])::text, updated_at = ?
WHERE id = ?
AND jsonb_extract_path_text(CASE WHEN metadata IS NULL OR metadata = 'null' OR metadata = '' THEN '{}'::jsonb ELSE metadata::jsonb END, ?, 'step_id') = ?
AND jsonb_extract_path_text(CASE WHEN metadata IS NULL OR metadata = 'null' OR metadata = '' THEN '{}'::jsonb ELSE metadata::jsonb END, ?, 'stamp') = ?
`
args = []interface{}{key, time.Now().UTC(), taskID, key, expectedStepID, key, expectedStamp}
} else {
path := jsonPath(key)
stepIDPath := path + ".step_id"
stampPath := path + ".stamp"
query = `
UPDATE tasks
SET metadata = json_remove(CASE WHEN metadata IS NULL OR metadata = 'null' OR metadata = '' THEN '{}' ELSE metadata END, ?), updated_at = ?
WHERE id = ?
AND json_extract(CASE WHEN metadata IS NULL OR metadata = 'null' OR metadata = '' THEN '{}' ELSE metadata END, ?) = ?
AND json_extract(CASE WHEN metadata IS NULL OR metadata = 'null' OR metadata = '' THEN '{}' ELSE metadata END, ?) = ?
`
args = []interface{}{path, time.Now().UTC(), taskID, stepIDPath, expectedStepID, stampPath, expectedStamp}
}
result, err := r.db.ExecContext(ctx, r.db.Rebind(query), args...)
if err != nil {
return nil, false, err
}
rows, err := result.RowsAffected()
if err != nil {
return nil, false, err
}
if rows == 0 {
return nil, false, nil
}
return raw, true, nil
}
func (r *Repository) removeTaskMetadataKeyWithExecutor(
ctx context.Context,
exec taskSessionExecutor,
@@ -287,7 +287,7 @@ type StepHistoryRecorder interface {
}
type asyncStepHistoryRecorder interface {
EnqueueStepTransition(sessionID, fromStepID, toStepID string, trigger wfmodels.StepTransitionTrigger, actorID *string, metadata map[string]interface{})
EnqueueStepTransition(sessionID, fromStepID, toStepID string, trigger wfmodels.StepTransitionTrigger, actorID *string, metadata map[string]interface{}) bool
}
// ContributionDestinationPreparer is an internal creation-time hook for a
@@ -0,0 +1,49 @@
package service
import (
"testing"
"github.com/kandev/kandev/internal/task/models"
)
func TestProtectedTaskMetadataUpdatePreservesStepHandoffCarry(t *testing.T) {
existing := map[string]interface{}{
"ordinary": "old",
models.MetaKeyStepHandoffCarry: models.StepHandoffCarryToken{
Handoff: "trusted handoff",
StepID: "step-next",
Stamp: "trusted-stamp",
},
}
requested := map[string]interface{}{
"ordinary": "new",
models.MetaKeyStepHandoffCarry: models.StepHandoffCarryToken{
Handoff: "forged handoff",
StepID: "step-next",
Stamp: "forged-stamp",
},
}
updated := protectedTaskMetadataUpdate(existing, requested)
if got := updated["ordinary"]; got != "new" {
t.Fatalf("ordinary metadata = %v, want new", got)
}
if got := updated[models.MetaKeyStepHandoffCarry]; got != existing[models.MetaKeyStepHandoffCarry] {
t.Fatalf("carry token = %#v, want existing token", got)
}
}
func TestProtectedTaskMetadataUpdateRejectsNewStepHandoffCarry(t *testing.T) {
requested := map[string]interface{}{
models.MetaKeyStepHandoffCarry: models.StepHandoffCarryToken{
Handoff: "forged handoff",
StepID: "step-next",
Stamp: "forged-stamp",
},
}
updated := protectedTaskMetadataUpdate(nil, requested)
if _, ok := updated[models.MetaKeyStepHandoffCarry]; ok {
t.Fatalf("new carry token must not be accepted from client metadata")
}
}
@@ -18,9 +18,9 @@ func cloneTaskMetadata(metadata map[string]interface{}) map[string]interface{} {
}
// protectedTaskMetadataUpdate applies a generic metadata replacement while
// keeping the deferred launch intent owned by the server. The HTTP PATCH
// surface may replace ordinary metadata, but it cannot create, replace, or
// remove the launch record that carries deferred-start ownership.
// keeping server-managed deferred-launch and step-handoff records owned by the
// server. The HTTP PATCH surface may replace ordinary metadata, but it cannot
// create, replace, or remove either record.
func protectedTaskMetadataUpdate(existing, requested map[string]interface{}) map[string]interface{} {
updated := cloneTaskMetadata(requested)
if updated == nil {
@@ -31,5 +31,10 @@ func protectedTaskMetadataUpdate(existing, requested map[string]interface{}) map
} else {
delete(updated, models.MetaKeyDeferredLaunch)
}
if carry, ok := existing[models.MetaKeyStepHandoffCarry]; ok {
updated[models.MetaKeyStepHandoffCarry] = carry
} else {
delete(updated, models.MetaKeyStepHandoffCarry)
}
return updated
}
@@ -357,7 +357,8 @@ func (s *Service) updateTaskStateIfSessionState(
return true, nil
}
// UpdateTaskMetadata updates only the metadata of a task (merges with existing)
// UpdateTaskMetadata updates ordinary task metadata while preserving
// server-managed deferred-launch and step-handoff records.
func (s *Service) UpdateTaskMetadata(ctx context.Context, id string, metadata map[string]interface{}) (*models.Task, error) {
if err := s.authorizeTaskScope(ctx, id, authz.ScopeTaskWrite); err != nil {
return nil, err
@@ -374,7 +375,7 @@ func (s *Service) UpdateTaskMetadata(ctx context.Context, id string, metadata ma
for k, v := range metadata {
// Deferred launch ownership is server-managed. Preserve it even if a
// future metadata endpoint forwards the whole request map here.
if k == models.MetaKeyDeferredLaunch {
if k == models.MetaKeyDeferredLaunch || k == models.MetaKeyStepHandoffCarry {
continue
}
task.Metadata[k] = v
@@ -1024,10 +1025,13 @@ func (s *Service) recordQueuedPromotion(ctx context.Context, taskID, fromStepID,
return
}
if asyncRecorder, ok := s.stepHistoryRecorder.(asyncStepHistoryRecorder); ok {
asyncRecorder.EnqueueStepTransition(session.ID, fromStepID, toStepID, wfmodels.StepTransitionTriggerQueuePromotion, nil, nil)
return
if asyncRecorder.EnqueueStepTransition(session.ID, fromStepID, toStepID, wfmodels.StepTransitionTriggerQueuePromotion, nil, nil) {
return
}
}
if err := s.stepHistoryRecorder.CreateStepTransition(ctx, session.ID, fromStepID, toStepID, wfmodels.StepTransitionTriggerQueuePromotion, nil, nil); err != nil {
writeCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), constants.StepHistoryWriteTimeout)
defer cancel()
if err := s.stepHistoryRecorder.CreateStepTransition(writeCtx, session.ID, fromStepID, toStepID, wfmodels.StepTransitionTriggerQueuePromotion, nil, nil); err != nil {
s.logger.Warn("failed to record queued task promotion", zap.String("task_id", taskID), zap.Error(err))
}
}
@@ -1372,8 +1376,9 @@ func (s *Service) recordManualStepTransition(ctx context.Context, sessionID, fro
}
}
if asyncRecorder, ok := s.stepHistoryRecorder.(asyncStepHistoryRecorder); ok {
asyncRecorder.EnqueueStepTransition(sessionID, fromStepID, toStepID, trigger, actorID, nil)
return
if asyncRecorder.EnqueueStepTransition(sessionID, fromStepID, toStepID, trigger, actorID, nil) {
return
}
}
// The step change is already durably persisted by the time this runs.
// Use a detached, bounded context so a cancelled request context (client
@@ -108,6 +108,54 @@ func TestCreateHistory_NullableFromStepAndActor(t *testing.T) {
}
}
// TestListHistoryBySession_PreMigrationRowOmitsHandoffAndBlockersKeys covers
// AC-002.7: a row written before this capability shipped (metadata carrying
// only signal_source/signal_summary, the pre-existing shape) round-trips
// through the JSON metadata column unchanged — signal_handoff and
// signal_blockers must stay absent keys, not materialize as empty-string or
// null entries, so a consumer's "absent-by-default" read is correct without
// needing a migration to backfill them.
func TestListHistoryBySession_PreMigrationRowOmitsHandoffAndBlockersKeys(t *testing.T) {
repo, sqlxDB := setupTestRepoWithDB(t)
ctx := context.Background()
if _, err := sqlxDB.Exec(`INSERT INTO task_sessions (id) VALUES ('sess-pre-migration')`); err != nil {
t.Fatalf("failed to insert test session: %v", err)
}
history := &models.SessionStepHistory{
SessionID: "sess-pre-migration",
ToStepID: "step-old",
Trigger: models.StepTransitionTriggerManual,
Metadata: map[string]interface{}{
"signal_source": "agent",
"signal_summary": "old-shaped row from before handoff/blockers existed",
},
}
if err := repo.CreateHistory(ctx, history); err != nil {
t.Fatalf("CreateHistory failed: %v", err)
}
result, err := repo.ListHistoryBySession(ctx, "sess-pre-migration")
if err != nil {
t.Fatalf("ListHistoryBySession failed: %v", err)
}
if len(result) != 1 {
t.Fatalf("expected 1 history row, got %d", len(result))
}
got := result[0]
if got.Metadata["signal_summary"] != "old-shaped row from before handoff/blockers existed" {
t.Errorf("Metadata[signal_summary] = %v, want the seeded pre-migration summary", got.Metadata["signal_summary"])
}
if _, ok := got.Metadata["signal_handoff"]; ok {
t.Errorf("Metadata[signal_handoff] = %v, want the key absent for a pre-migration row", got.Metadata["signal_handoff"])
}
if _, ok := got.Metadata["signal_blockers"]; ok {
t.Errorf("Metadata[signal_blockers] = %v, want the key absent for a pre-migration row", got.Metadata["signal_blockers"])
}
}
func TestListHistoryBySession_OrderedByCreatedAt(t *testing.T) {
repo, sqlxDB := setupTestRepoWithDB(t)
ctx := context.Background()
@@ -142,23 +142,26 @@ func (s *Service) drainHistoryQueue() {
}
// EnqueueStepTransition records transition history outside the caller's
// event-reader path. The queue is bounded. A full queue, or an enqueue after
// Close has begun, is logged as a dropped best-effort telemetry row while the
// workflow mutation itself succeeds.
func (s *Service) EnqueueStepTransition(sessionID, fromStepID, toStepID string, trigger models.StepTransitionTrigger, actorID *string, metadata map[string]interface{}) {
// event-reader path. The queue is bounded. It returns false when a full queue,
// an empty session ID, or shutdown prevents enqueueing, so callers carrying
// signal data can use a bounded synchronous fallback instead of silently
// losing that payload.
func (s *Service) EnqueueStepTransition(sessionID, fromStepID, toStepID string, trigger models.StepTransitionTrigger, actorID *string, metadata map[string]interface{}) bool {
if sessionID == "" {
return
return false
}
s.historyMu.RLock()
defer s.historyMu.RUnlock()
if s.historyClosed {
s.logger.Warn("dropped step transition enqueued after shutdown", zap.String("session_id", sessionID))
return
return false
}
select {
case s.historyQueue <- historyWrite{sessionID: sessionID, fromStepID: fromStepID, toStepID: toStepID, trigger: trigger, actorID: actorID, metadata: metadata}:
return true
default:
s.logger.Warn("step transition history queue is full", zap.String("session_id", sessionID))
return false
}
}
@@ -601,8 +604,9 @@ func (s *Service) ReorderSteps(ctx context.Context, workflowID string, stepIDs [
// CreateStepTransition creates a new step transition history entry. metadata
// is optional (nil for a plain move) and carries the ADR 0015 consumed-signal
// shape ({"signal_source", "signal_summary"}) when a completion signal drove
// the transition.
// shape ({"signal_source", "signal_summary"}, plus "signal_handoff" and
// "signal_blockers" when the signal carried a non-blank value for either)
// when a completion signal drove the transition.
func (s *Service) CreateStepTransition(ctx context.Context, sessionID string, fromStepID, toStepID string, trigger models.StepTransitionTrigger, actorID *string, metadata map[string]interface{}) error {
history := &models.SessionStepHistory{
SessionID: sessionID,
@@ -9,6 +9,7 @@ test("dragging into a feeder wakes an open pull target without reload", async ({
apiClient,
seedData,
}) => {
await testPage.setViewportSize({ width: 1440, height: 900 });
const workflow = await apiClient.createWorkflow(seedData.workspaceId, "Feeder Move Workflow");
const sourceStep = await apiClient.createWorkflowStep(workflow.id, "C", 0, {
is_start_step: true,
@@ -1,6 +1,6 @@
# 0015: Explicit completion signal for auto-advance
**Status:** proposed (amended 2026-08-14)
**Status:** proposed (amended 2026-08-14, 2026-09-05)
**Date:** 2026-06-04
**Area:** backend, frontend
@@ -8,6 +8,15 @@
> [ADR-2026-08-14-current-turn-clarification-ownership](2026-08-14-current-turn-clarification-ownership.md):
> a detached clarification remains a hard-pause barrier only while its turn remains current.
> That ownership rule stands independently of this proposal's future status.
>
> Amended 2026-09-05: `handoff` now carries one hop beyond the bag into the next step's
> dispatched prompt, and `blockers` (with `handoff`) now rides the existing step-transition
> audit metadata alongside `signal_source`/`signal_summary`, retrievable through
> `GET /sessions/:id/workflow/history`. The "persisted in the bag only, not on the wire" claim
> below (Mechanism, step 1) describes the signal-publish event only and no longer describes the
> full lifecycle of either field. See
> `docs/specs/tasks/requirements/workflow-completion-signal-payload-delivery.md` and its
> system design for the carry/claim mechanism and the audit-metadata addition.
## Context
@@ -61,7 +70,7 @@ Today, a workflow step's `on_turn_complete` actions (most commonly `move_to_next
- **Idempotent.** Repeated calls within the same step are no-ops: if `existing != nil && existing.StepID == currentStepID`, the MCP tool returns `{accepted: false, reason: "already_signaled"}` without overwriting.
- **Audit (implemented for the trigger-enum call sites).** Consumed-signal context is persisted on the transition row (`SessionStepHistory.Metadata["signal_source"]` ∈ {`"agent"`, `"manual_fallback"`} plus `Metadata["signal_summary"]`), written by `orchestrator.Service.recordAutoStepTransition` immediately before the bag is cleared, for both the workflow-engine (`applyEngineTransition`) and legacy (`executeStepTransition`) transition paths. The three `StepTransitionTrigger` funnels are wired: manual moves (`StepTransitionTriggerManual`, from `task/service.MoveTaskWithOptions`, including the deferred `move_task_kandev` path via `orchestrator.applyPendingMove`), approval-gated moves (`StepTransitionTriggerApproval`, from `applyApprovalStepTransition`), and orchestrator-driven moves (`StepTransitionTriggerAutoComplete`, covering on_turn_complete, on_turn_start, and on_children_completed via `applyEngineTransition`/`executeStepTransition`) — but only an on_turn_complete transition that actually consumed a matching pending signal carries the metadata above; other automated transitions record with no metadata. Cancelled signals (overwritten by user reply) are still not retained — the bag is cleared, not archived.
Transition ownership is now explicit at the mutation boundaries. Generic `task/service.UpdateTask` changes use `task_update`; queue-promotion paths use `queue_promotion`; engine and legacy orchestrator paths preserve their event trigger; and human or agent move paths carry explicit actor provenance. The workflow service owns the history writer. Runtime callers enqueue rows on its bounded worker, which drains during service shutdown. This is best-effort telemetry: a full queue or database failure is logged and does not roll back an already-committed task mutation. A durable audit ledger would require an outbox transaction in a future change.
Transition ownership is now explicit at the mutation boundaries. Generic `task/service.UpdateTask` changes use `task_update`; queue-promotion paths use `queue_promotion`; engine and legacy orchestrator paths preserve their event trigger; and human or agent move paths carry explicit actor provenance. The workflow service owns the history writer. Runtime callers enqueue rows on its bounded worker, which drains during service shutdown; a full or closed worker falls back to a bounded synchronous write. Database failure or a shutdown deadline remains best-effort telemetry and does not roll back an already-committed task mutation. A durable audit ledger would require an outbox transaction in a future change.
- **Chat visibility (deferred).** Surfacing a `step_complete_signaled` system message in the existing message stream is planned but not yet emitted. Today the only user-visible cue is the next-step transition itself; the bag remains the only truth source.
3. **System-prompt injection.** When `auto_advance_requires_signal` is true on the current workflow step, `internal/sysprompt/` prepends a short instruction block to the agent's system prompt at launch / resume time, in the same path that already injects MCP tool descriptions. The text is fixed, terse, and points at the tool by name:
+1 -1
View File
@@ -20,7 +20,7 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
| 0012 | [Service-only UI self-update](0012-service-only-self-update.md) | accepted | backend, frontend, cli | 2026-05-29 |
| 0013 | [Multi-branch task support — N (repo, branch) pairs per task](0013-multi-branch-tasks.md) | accepted | backend, frontend | 2026-06-01 |
| 0014 | [Per-CLI MCP server injection for passthrough mode](0014-passthrough-mcp-injection-strategies.md) | accepted | backend | 2026-05-29 |
| 0015 | [Explicit completion signal for auto-advance](0015-explicit-completion-signal-for-auto-advance.md) | proposed (amended 2026-08-14) | backend, frontend | 2026-06-04 |
| 0015 | [Explicit completion signal for auto-advance](0015-explicit-completion-signal-for-auto-advance.md) | proposed (amended 2026-08-14, 2026-09-05) | backend, frontend | 2026-06-04 |
| 0016 | [Read-only absolute file paths](0016-observed-external-file-reads.md) | accepted | backend | 2026-06-14 |
| 0017 | [Resource metrics sampling](0017-resource-metrics-sampling.md) | accepted | backend, frontend, protocol | 2026-06-14 |
| 0018 | [Runtime settings overrides](0018-runtime-settings-overrides.md) | accepted (amended 2026-08-11) | backend, frontend, cli | 2026-06-14 |
+2
View File
@@ -102,6 +102,7 @@ signals, and task-scoped scheduling contracts.
- [User Question Turn Boundary](requirements/user-question-turn-boundary.md)
- [WIP Limits and Visible Overflow Queues](requirements/wip-limit-pull-system.md)
- [Tasks Without Repositories](requirements/without-repositories.md)
- [Workflow completion-signal payload delivery](requirements/workflow-completion-signal-payload-delivery.md)
- [Cancelled Turn Completion](requirements/workflow-cancelled-turn-completion.md)
- [Workflow Cycle Guardrails](requirements/workflow-cycle-guardrails.md)
- [Workflow Duplication](requirements/workflow-duplication.md)
@@ -161,6 +162,7 @@ signals, and task-scoped scheduling contracts.
- [Task Create Launch Preview](system-design/task-create-launch-preview.md)
- [Task priority visibility](system-design/task-priority-visibility.md)
- [WIP Limits and Visible Overflow Queues](system-design/wip-limit-pull-system.md)
- [Workflow completion-signal payload delivery](system-design/workflow-completion-signal-payload-delivery.md)
- [Workflow quorum decision recording](system-design/workflow-quorum-decision-recording.md)
- [Workflow Step Agent Start Ownership](system-design/workflow-step-agent-start-ownership.md)
- [Workflow Step Fixed-Profile Routing](system-design/workflow-step-fixed-profile-routing.md)
@@ -0,0 +1,318 @@
---
status: draft
system: tasks
created: 2026-09-04
owners:
- kandev
---
# Workflow completion-signal payload delivery Requirements
## Overview
`step_complete_kandev` accepts `summary`, `handoff` and `blockers`; only `summary`
survives the transition it triggers, the orchestrator having lifted it onto the
audit row before deleting the signal bag. `tasks` owns the contract: the durable
artifacts are the session signal bag and the step-transition audit row.
Measured evidence, ADR citations, provenance, per-requirement framing, and the
code shapes behind every criterion are in the paired system design,
`docs/specs/tasks/system-design/workflow-completion-signal-payload-delivery.md`.
## Terminology
- **Completion signal:** the `PendingStepCompletionSignal` written to
`TaskSession.Metadata` by `step_complete_kandev` or the manual fallback.
- **Completion handoff:** the `handoff` argument of a completion signal, and the
value this capability delivers. Not the queued hand-off message.
- **Queued hand-off message:** a pre-existing, unrelated message-queue entry a
`move_task_kandev` call can attach, already merged into a step entry prompt
after the step's own content. Different provenance and lifetime; unchanged here.
- **Consuming transition:** an orchestrator-driven step transition that both runs
on the turn-completion trigger AND carries the session lifecycle of a turn
actually ending. The trigger value alone is not the test: guarded quorum-decision
re-evaluation reuses the same turn-completion trigger without a turn having
completed, and is excluded by the session-lifecycle half. Transitions on other
triggers, including turn start and children completed, manual moves, approvals,
and guarded quorum decisions, are not consuming transitions.
- **Consumed signal:** the completion signal a consuming transition finds for the
step it is leaving, when it commits. A consuming transition may find none.
- **Transition audit record:** the `session_step_history` row a transition writes,
whose `metadata` already carries `signal_source` and `signal_summary`.
- **Handoff carry token:** a single-slot, task-scoped record holding one consumed
signal's completion handoff and the step it addresses. It is the `tasks.metadata`
key `step_handoff_carry`, an object with `handoff` (the bounded text), `step_id`
(the next step's identifier) and `stamp` (a fresh unique value per token write,
which the claim compares).
- **Step entry:** one attempt to put a task to work on a step it has entered,
from a dispatch path's start to a dispatched prompt or a decision not to
dispatch. It may compose more than one prompt when a launch is replaced after
a failure.
- **Step entry prompt:** the prompt composed for a step entry.
- **Next step:** a consuming transition's destination step.
## Prior art
The wiki leg ran and returned nothing useful; the vendor leg did not run, its
tool being unreachable. Neither informed this document; receipts and the
precedents followed are in the paired system design.
## Requirements
### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-001: A completed step's completion handoff reaches the next step's agent exactly once
#### Acceptance criteria
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.1:** When a consuming transition
commits and its consumed signal carries a non-empty completion handoff, the
system shall record a handoff carry token holding that handoff text and the
next step's identifier.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.2:** When a consuming transition
commits and its consumed signal carries an empty or whitespace-only completion
handoff, or the transition found no signal, the system shall remove any
existing handoff carry token for that task, so a handoff never survives a
later consuming transition that wrote none.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.2a:** A transition that is not a
consuming transition shall neither record nor remove a handoff carry token, so
an unclaimed token survives any turn-start transition, children-completed
transition, manual move, approval move, or guarded quorum decision occurring
before the step is entered.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.3:** The system shall keep at most one
handoff carry token per task. Recording a token shall replace any existing
token rather than append to it, so no accumulation across steps is possible.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.4:** When a branch will send the agent
something per -001.6c, the system shall claim the task's handoff carry
token in a single atomic operation that removes and returns it ONLY IF the
stored token names the step being entered, and otherwise removes nothing and
returns nothing. The destination-step comparison shall be evaluated inside that
one operation, against the stored value; any earlier read is advisory only, so a
token replaced between that read and the claim is neither delivered nor
destroyed. When two step entries race for one token, exactly one shall receive
it and the other none.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.5:** The system shall deliver a handoff
carry token only to an entry into the step it names. When the task's token names
the step being entered, the system shall claim it per -001.4 and include its
handoff text in the step entry prompt. When it names any other step, the system
shall leave it in place unclaimed and compose the prompt with no handoff text,
so a later entry into the step it does name can still receive it. The text
delivered shall be the text the -001.4 claim returned, never a copy read before it.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.6:** The system shall append the
completion handoff text LAST in the dispatched prompt: after the step entry
prompt's own composed content and after any queued hand-off message merged into
it. The text shall be introduced by the fixed heading line
`## Context from the previous workflow step`, alone on its line, with one blank
line before it and one after. The system shall not reorder, suppress, or
otherwise change how a queued hand-off message is merged, and shall not change
the prompt of an entry claiming no token.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.6a:** Every decision a dispatch branch
makes about WHETHER to send the agent anything shall be evaluated on content
that excludes the completion handoff text, using the rule that branch already
applies today, so a completion handoff can never on its own cause a dispatch
that would not otherwise happen. That decision shall precede the claim; claiming
first and deciding afterwards violates this criterion even when the discarded
prompt would have sent nothing.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.6b:** The system shall not apply
saved-prompt reference expansion to the completion handoff text, and shall apply
it to the entry prompt's own composed content exactly as today, so a completing
agent cannot pull unrelated saved-prompt content into the next agent's prompt.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.6c:** When a branch decides to send the
agent something, the system shall claim the token per -001.4 and append the
handoff per -001.6. This includes a branch that finds its composed step prompt
empty and dispatches only a drained queued message: that dispatch is a step
entry and shall carry the handoff. When a branch sends the agent nothing at all,
the system shall claim nothing and shall leave the token in place for a later
entry into the step it names. Branches of one dispatch path may apply different
rules; each shall follow its own rather than a unified one.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.7:** Every branch of every step-entry
dispatch path that sends the agent anything shall evaluate the handoff carry
token, so no branch can dispatch without the token having been considered, and
shall do so through one shared claim-and-place implementation rather than logic
duplicated per branch. Coverage is judged per branch, not per path: a path whose
ACP branch claims and whose passthrough branch does not is a violation.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.8:** When one step entry composes more
than one prompt because a launch was replaced after a failure, the system shall
claim the token at most once per step entry — only a claim that returned text
counts as that one claim — and shall include that text in every prompt composed
from that claim onward, rather than re-claiming it per prompt. A prompt composed
before any claim returned text carries none and does not violate this criterion.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.9:** After a step entry has claimed a
token, a later entry into the same step shall receive no handoff text. The
system shall not restore or re-record a claimed token, including when the entry
that claimed it subsequently fails to dispatch.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.10:** When the next step's agent
profile differs from the completing step's, so the destination step runs on a
different session, the completion handoff shall still reach the prompt composed
for that session.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.11:** When a consuming transition
commits but the destination step's entry is deferred until a queue promotion
admits the task, the handoff shall reach the prompt composed at that promotion.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.12:** When a manual move takes a task
away from a step whose token was never claimed and later returns it to that
same step, the system shall deliver that token on the return and shall add no
time-based expiry to suppress it. Any consuming transition in between removes
or replaces the token per -001.2 and -001.3.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.13:** The completion handoff and
blockers a transition carries shall be those of the first completion signal
accepted for that step. When a second `step_complete_kandev` call is rejected
as a duplicate, its handoff and blockers shall not be recorded, delivered,
merged, or allowed to overwrite the accepted signal's.
### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-002: A signal's blockers are retrievable after the transition
#### Acceptance criteria
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.1:** When a consuming transition writes
its transition audit record, the system shall include the consumed signal's
blockers under the key `signal_blockers` and its completion handoff under the
key `signal_handoff`, alongside the `signal_source` and `signal_summary` it
already writes.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.2:** The system shall omit an empty or
whitespace-only blockers value, and an empty or whitespace-only completion
handoff value, from the audit record rather than writing an empty entry.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.3:** The system shall capture the
blockers and completion handoff into the audit record before the pending signal
bag is cleared and before the carry token is recorded, so no ordering can lose
them. Where a queued worker writes the row asynchronously, capture at enqueue
satisfies this: the row may land later but shall carry the values the consuming
transition read.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.4:** The system shall expose these
values through the existing session step-history read path, adding no endpoint
and changing its response shape only by the added metadata keys.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.5:** The system shall record blockers
and completion handoff only for a transition that consumed a signal; one that
consumed none shall continue to write no signal metadata.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.6:** The system shall store these
values in the existing audit record metadata, adding no table and no column.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.7:** An audit record written before
this capability shall remain readable and shall not be rewritten or migrated.
A consumer shall treat `signal_blockers` and `signal_handoff` as
absent-by-default.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.8:** The values recorded shall be those
of the first signal accepted for the step, per -001.13. A duplicate signal
shall neither append a second audit record nor amend the existing one.
### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-003: Neither argument can grow without bound
#### Acceptance criteria
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.1:** The system shall bound the stored
completion handoff text and the stored blockers text to 8,192 bytes each,
measured as UTF-8 byte length and inclusive of any truncation marker appended,
and shall apply the bound where the completion signal is first recorded, so the
signal bag, the audit record, and the carry token hold the same bounded value.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.2:** Bounding shall be measured and
applied AFTER the handler's existing leading/trailing whitespace trim, on the
trimmed value. When that trimmed value is at most 8,192 bytes the system shall
store it byte-for-byte and append no marker. At 8,193 bytes or more it shall
store a truncated value whose total length, marker included, is at most 8,192
bytes.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.3:** When the system truncates a value
it shall cut on a UTF-8 character boundary, never storing a partial character,
and shall append the fixed marker `[truncated: over 8192-byte limit]` so a
later reader cannot mistake a cut value for a complete one. The retained content
shall be the longest whole-character prefix leaving room for that marker.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.4:** When the system bounds a value, it
shall still accept the completion signal and shall drive the step transition
exactly as it would for an unbounded value. An oversized completion handoff or
blockers value shall never strand a step.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.5:** When the system truncates one or
more values on a call it accepts, that call's `step_complete_kandev` result
shall carry `truncated`, a JSON array of the lowercase argument names that were
truncated, and `truncation_limit_bytes`, a JSON number holding the ceiling. The
array shall list `"handoff"` before `"blockers"` when both were truncated,
contain exactly one entry when one was, and never repeat a name. When nothing
was truncated the system shall omit both fields, so a result omitting them means
every submitted value was stored whole.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.5a:** When a call is rejected as a
duplicate for the step, its result shall keep its existing rejection shape and
report no truncation, none of that call's values having been stored. Bounding
shall never convert a rejected duplicate into an accepted signal.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.6:** The ceiling shall be a fixed value
compiled into the backend, identical across deployments, and readable or
writable from no configuration, environment, or runtime feature toggle.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.7:** The system shall bound each value
independently per signal; the ceiling shall not accumulate across signals,
steps, or a task's transition history.
### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-004: The tool describes what it actually does
#### Acceptance criteria
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-004.1:** The registered description of the
`handoff` argument shall state that it is delivered once to the
immediately-following step's agent and is not carried beyond that step.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-004.2:** The registered description of the
`blockers` argument shall state that it is recorded on the step-transition
record and not delivered to the next step's agent, so it is not used to pass
context forward.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-004.3:** The registered descriptions of
both arguments shall state the byte ceiling from
REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-004.4:** The tool's top-level description
shall claim no forwarding behavior the delivered mechanism does not provide.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-004.5:** The system shall keep both
arguments registered and optional, with their existing names and types.
### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-005: Delivery never costs a transition
#### Acceptance criteria
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-005.1:** When recording or removing a carry
token fails, the system shall log it and complete the transition unchanged,
without retrying, rolling back, or deferring it.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-005.2:** When claiming a carry token fails,
the system shall compose the step entry prompt exactly as today, with no
handoff text, and shall not fail the step entry. A failed claim removed and
returned nothing, so it shall not count as the step entry's one claim under
-001.8: a replacement launch in the same step entry, and any later entry into
the same step, shall attempt the claim again. The system shall not retry within
one composed prompt.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-005.3:** When the configured repository
provides no atomic task-metadata write or claim operation, the system shall
behave as today: no token recorded, none claimed, no handoff text, and no error
surfaced to the transition or the step entry.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-005.4:** When two consuming transitions for
the same task resolve concurrently, the last token write shall win — the
single-row overwrite's own commit order decides which is last, and no version or
sequence column is added — and neither outcome shall deliver a handoff to a step
the winning token does not name, because -001.4 compares the destination step
inside the same atomic operation that removes it.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-005.5:** When a duplicate delivery re-runs
a consuming transition that already recorded its token, re-recording the same
handoff and destination step shall be indistinguishable from recording them
once in what is DELIVERED: at most one entry into that step receives that
handoff. The stamp is minted fresh per write, so the stored tokens differ at
that field; that is expected, and the stamp shall never be made stable or
content-derived to satisfy this criterion.
- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-005.6:** A task with no handoff carry token
shall compose step entry prompts byte-identically to today.
## Out of scope
- **Attention routing for blockers.** Making them retrievable is this capability.
Surfacing them on a board, in chat, or in a notification is excluded: no
endpoint, no event, no frontend change, no copy, and therefore no localization.
- **Rendering or collapsing the handoff block in chat.** It is agent-facing
English composed into the prompt, not localized, the same class as the
workflow-instructions heading. No frontend affordance.
- **Changing the queued hand-off message.** Its provenance, merge position, and
requeue-on-failure behavior are untouched. AC-001.6 states only where the
completion handoff sits.
- **Unifying the actionability rules.** Dispatch branches apply different rules
today; the design records which. AC-001.6a defers to a branch's own rule rather
than reconciling them.
- **Ordering of the audit read path.** `ListHistoryBySession` orders by
`created_at` with no tiebreak column, and this capability changes neither; two
rows sharing a `created_at` stay in the order the driver returns them.
- **Putting handoff or blockers on the bus-event wire.** ADR 0015 kept both off
the `workflow.step_completion_signaled` payload. Delivery happens at transition
time from the persisted bag, not through the event.
- **Multi-hop retention.** Nothing accumulates handoffs across steps. Multi-hop
receipts remain the task plan's job; its three tools are unchanged.
- **Restructuring the completion payload into typed evidence fields.** The three
arguments keep their names, types, and optionality; a structured evidence bundle
is a separate item.
- **The manual completion fallback button.** Its source value is covered by every
rule above, but the button remains unimplemented and out of scope here, per
`REQ-TASKS-WORKFLOW-EXPLICIT-COMPLETION-SIGNAL-001`.
- **Amending ADR 0015.** Updating its text is a documentation change, not a
contract change owned here.
@@ -0,0 +1,566 @@
---
status: draft
system: tasks
requirements:
- REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-001
- REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-002
- REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-003
- REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-004
- REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-005
created: 2026-09-05
owners:
- kandev
---
# Workflow completion-signal payload delivery System Design
## Purpose and boundaries
The paired requirement is the contract. This document records the measured
current-tree shapes those criteria were written against, the mechanism chosen for
each, and the prior art followed rather than re-derived. Where the two disagree,
the requirement wins and this document is wrong.
Line numbers are omitted: they drifted between sessions of this card. Every element
below is named by symbol, so a builder greps for it.
## Provenance
**Why this exists.** ADR 0015 records the mechanism accurately at its line 42
("`handoff` and `blockers` are persisted in the bag only, not on the wire") but
justifies it at line 114 on the opposite outcome ("the summary is cheap, the
next-step agent benefits from a handoff blurb"). The mechanism never delivered
the rationale. This capability closes that gap; it does not reverse the ADR.
Amending the ADR's text is a documentation change, out of scope for the contract.
**Measured cost of the defect.** Both shipped boards tell every agent to fill
`handoff` on every step while also declaring the task plan IS the handoff, a
workaround that exists because the argument does not work. One card made 26 step
transitions on 2026-09-03/04; every handoff it wrote was discarded.
**Prior-art leg receipts.** The wiki leg RAN and returned nothing useful: the
configured Obsidian vault and QMD collection were unreachable in this
environment (all three transports unavailable — the wiki CLI not installed,
the query tool not on `PATH`, and the vault path denied by local filesystem
permissions). The vendor leg DID NOT RUN: `saas-kb` / `search_fsm_docs` are not
registered in this session, so `ai_sdlc` was not queried. Neither informed the
requirement.
## Measured input
Re-sampled against the working tree on 2026-09-05, and re-verified during spec
review. Every claim here was read from the code, not inferred.
### The lifecycle today
1. `step_complete_kandev` is registered in `internal/mcp/server`'s
`registerStepCompleteTool`, with `summary` required and `handoff` and
`blockers` optional.
2. `internal/mcp/handlers`'s `handleStepComplete` trims all three and builds a
`models.PendingStepCompletionSignal`, then calls `claimStepCompletionSignal`.
3. That claim is `SetSessionMetadataKeyIfAbsentOrDifferentStep[IfTaskAtStep]`,
so a second call at the same step returns `stored=false` and the first signal
stands. This is the mechanism behind AC-001.13 and AC-003.5a: the duplicate
path runs `handleDuplicateStepComplete`, which re-publishes the event and
returns `{accepted:false, reason:"already_signaled"}`. The second call's
`handoff` and `blockers` are already discarded today, and stay discarded.
4. Two consuming-transition sites exist in `internal/orchestrator`, both in
`event_handlers_workflow.go`: `executeStepTransition` (legacy
on_turn_complete) and **`applyEngineTransitionWithCommitMode`** (engine path).
Grep for that full name: `applyEngineTransition`,
`applyEngineTransitionWithCommit` and `applyEngineTransitionWithMode` are thin
wrappers that contain none of the consuming logic. Each site builds
`consumedSignal` by `models.LoadPendingStepSignal`, calls
`recordAutoStepTransition`, then clears the bag. Both must be changed, or the
two funnels drift.
5. `recordAutoStepTransition` in `event_handlers_step_completion.go` builds
`map[string]interface{}{"signal_source", "signal_summary"}`. This is the
single place the payload is narrowed, and the single place REQ-002 widens. It
leaves `metadata` nil when the signal is nil, which is what makes AC-002.5
hold with no added branch.
6. `clearPendingStepSignal` / `clearPendingStepSignalByID` delete the bag entry.
This is where `handoff` and `blockers` die today.
### Trigger gating: the asymmetry AC-001.2a exists for
`recordAutoStepTransition` is called **unconditionally on every trigger** at both
sites, with `consumedSignal` nil for anything that is not turn completion.
The bag clear, by contrast, **is** trigger-gated: `if triggerOnEnter` in
`executeStepTransition`, and `if sessionLifecycle && trigger ==
engine.TriggerOnTurnComplete` in `applyEngineTransitionWithCommitMode`.
Placing the carry-token write beside `recordAutoStepTransition` without adopting
that gate would let a turn-start or children-completed transition satisfy
AC-001.2's "found no signal" clause and erase a token written moments earlier by
the consuming transition that delivered the task into the step. The token write
and removal therefore take the **bag clear's gate**, not the audit row's.
**The trigger value alone is not the gate, and this is the trap.**
`applyFirstSatisfiedGuardedTransition` in `internal/workflow/engine/quorum.go`
drives a guarded quorum/approval decision through
`ApplyTransitionIfAtStep(..., TriggerOnTurnComplete)` — the SAME trigger constant a
real turn completion uses. (`TriggerOnApprovalResolved` exists in `engine/types.go`
but is not what this path passes.) So a reviewer clicking approve arrives carrying
`TriggerOnTurnComplete` with no turn having ended, on the DECIDER's session rather
than the assignee's. What excludes it is the other half of the condition:
`sessionLifecycle := mode != transitionLifecycleGuardedDecision` in
`applyEngineTransitionWithCommitMode`, which is why the gate is the compound
`sessionLifecycle && trigger == engine.TriggerOnTurnComplete` and not the trigger
test alone. A builder implementing AC-001.2 from a trigger check alone fires the
token write/remove on every quorum-gated approval, and AC-001.2's "found no
signal, so remove" branch then wipes a pending, unclaimed token the instant a
reviewer approves. Copy the compound condition; do not paraphrase it.
### The step-entry surface
- **`buildWorkflowEntryPrompt`** (`internal/orchestrator/task_operations.go`) is
the single prompt-**composition** seam, at five call sites: four in
`event_handlers_workflow.go` (the `launchAfterOnEnterDispatch` branches,
including three replacement launches after a failed or terminalized launch) and
one in `task_operations.go` inside `StartSessionForWorkflowStep` (queue
promotion and manual auto-start).
- **Composition is not dispatch.** There are **two step-entry dispatch paths**:
`launchAfterOnEnterDispatch` and `StartSessionForWorkflowStep`. The five seam
call sites sit inside those two. But the path is NOT the unit of coverage:
`launchAfterOnEnterDispatch` forks into an ACP branch (`autoStartStepPrompt`) and
a passthrough branch, and those two decide differently on identical input. AC-001.7
therefore judges coverage per branch, which is why "I changed both paths" is not
evidence that every dispatch was covered.
- **Actionability is decided after the seam returns, by three different rules.**
`promptForEmptinessCheck` covers one call site, not all three.
- `StartSessionForWorkflowStep`: `promptForEmptinessCheck :=
s.effectivePromptForSession(...)`, then `strings.TrimSpace(...) == ""` returns
without dispatching.
- `autoStartStepPrompt`: its own `effectiveAgentPrompt` check, which returns
early only when the prompt is blank **and** `len(attachments) == 0`, so an
attachment-only entry is actionable there and nowhere else.
- the passthrough branch of `launchAfterOnEnterDispatch`: a bare
`strings.TrimSpace(effectivePrompt) == ""`, which then calls
`drainQueuedMessageForPromptableSession` and returns. **That branch still
DISPATCHES** — it sends the drained queued message to the agent. It is not a
"nothing happened" path, which is why AC-001.6c names it explicitly and treats
it as a step entry that carries the handoff.
Note these are rules of BRANCHES, not paths: `autoStartStepPrompt` and the
passthrough branch both sit inside `launchAfterOnEnterDispatch` and disagree on
the same input (empty composed prompt plus a non-empty queued message). AC-001.6a
defers to the branch's own rule; unification is a named exclusion.
- **A queued hand-off message already merges into this prompt.**
`autoStartStepPrompt` calls `takeAndMergeHandoffMessage`, which drains an
Auto-run-enabled queued message (typically a `move_task_kandev` hand-off
prompt) and merges it with documented ordering "auto-start content first,
hand-off after", forwarding attachments and restoring the message on terminal
failure via `requeueTaken`. This is a different concept from the completion
handoff, with different provenance and lifetime, and the requirement names both
so a builder cannot conflate them. **This is also why AC-001.6 places the
completion handoff LAST, after the queued hand-off.**
`takeAndMergeHandoffMessage` runs BEFORE `autoStartStepPrompt`'s actionability
test and concatenates in one shot (`basePrompt + "\n\n" + msg.Content`) with no
splice point. Placing the completion handoff between the composed content and the
queued hand-off would force the claim before the actionability decision, violating
AC-001.6a, or restructure how the queued hand-off merges, which AC-001.6 forbids.
Appending last satisfies both and is reachable on every branch: after the
actionability test, before dispatch.
- **Saved-prompt reference expansion runs over the joined composition.**
`buildWorkflowPromptWithTrustedContext` ends in
`expandPromptReferencesWithContext(ctx, joined, isPassthrough)`. Appending the
completion handoff before that call would expand `@name` references inside
agent-authored text; AC-001.6b forbids it for that reason.
### Shapes the mechanism relies on
- **`session_step_history.metadata`** is a nullable `TEXT` column
(`internal/workflow/repository/sqlite.go`) holding free-form JSON. Adding keys
needs no migration, satisfying AC-002.6.
- **The read path already ships.** `GET /sessions/:id/workflow/history`
(`internal/workflow/handlers`) plus a WS action reach
`Controller.ListHistoryBySession`, whose `models.SessionStepHistory` carries
`Metadata map[string]interface{}` with `json:"metadata,omitempty"`. Added map
keys appear automatically, satisfying AC-002.4 with no endpoint and no shape
change, and `omitempty` gives AC-002.7's absent-by-default for free.
`ListHistoryBySession` is `ORDER BY created_at` with no tiebreak column; the
requirement names that as an exclusion rather than changing it.
- **Recording is asynchronous in production.** `recordAutoStepTransition` prefers
`asyncStepHistoryRecorder.EnqueueStepTransition`; when the bounded worker is
full or closed, it falls back to a bounded synchronous `CreateStepTransition`
write. The metadata map is built from the signal's fields before enqueue, so
values are captured at enqueue time even though the normal row lands later.
Database failure or a shutdown deadline can still drop telemetry; neither
rolls back an already-committed task mutation. Hence AC-002.3 says *capture*
before the clear, not *write* before it.
- **`tasks.metadata`** is an existing JSON bag with concurrent-key-safe patch
helpers on the SQLite repository: `SetTaskMetadataKey` (a plain overwrite, no
CAS, which is what makes AC-005.4's last-write-wins the primitive's actual
semantics) and `RemoveTaskMetadataKey`.
- **`RemoveTaskMetadataKey` cannot serve as the claim on its own.** Its signature
is `(ctx, taskID, key string) (bool, error)`: the boolean reports *presence*,
and the removed **value is not returned**. AC-001.4 requires one atomic
operation that both returns the content and removes it, so this capability adds
one. See "The claim primitive" below.
- **`internal/common/truncate`** already exposes `UTF8(s string, maxBytes int)`,
which cuts on a rune boundary. It appends no marker, so REQ-003's marker
handling wraps it rather than replacing it.
## Mechanism
### The claim primitive (new)
A new repository method beside `RemoveTaskMetadataKey` in
`internal/task/repository/sqlite/task.go`, returning the removed value as well as
whether it was present, so read-and-remove is one claim:
TakeTaskMetadataKeyIfDestinationStep(
ctx, taskID, key, expectedStepID, expectedStamp string,
) (json.RawMessage, bool, error)
**Why a plain take plus a pre-check is not equivalent.** `SetTaskMetadataKey` is an
unconditional overwrite, so a concurrent consuming transition can replace the token
between a check and an unconditional take, after which the take returns a token
addressed to a different step. Delivering that breaks AC-001.5; discarding it destroys
a token AC-001.5 requires be left in place, and AC-001.9 forbids putting it back.
**`RemoveTaskMetadataKeyIfStamp` supplies the conditional-compare half only, NOT the
return value.** It reports presence through `RowsAffected` and does not return what it
removed, and no single statement can: neither SQLite's nor this repository's Postgres
`RETURNING` can read a pre-`UPDATE` value. Every `UPDATE ... RETURNING` over a JSON
`metadata` column in this tree — for example the compaction-count increment in
`internal/task/repository/sqlite/session.go` — returns the POST-update value, which
after a removal is null. "Return the removed value" is therefore NOT a one-line
extension of that precedent, and a builder must not plan for it as one.
**The mechanism: compare-and-swap on the token's stamp.** The write side mints a fresh
`stamp` into every token (see "Handoff carriage"). The claim is an advisory read
followed by ONE conditional `UPDATE` whose `WHERE` compares BOTH nested fields
(paths built from `key`, as the precedent builds its own; shown here concrete):
UPDATE tasks SET metadata = json_remove(metadata, '$.step_handoff_carry')
WHERE id = ?
AND json_extract(metadata, '$.step_handoff_carry.step_id') = ?
AND json_extract(metadata, '$.step_handoff_carry.stamp') = ?
`RowsAffected == 1` means the row removed WAS the row read, because the stamp it is
keyed on is unique per token write. The method returns the handoff text from the
advisory read, and that text is provably the removed one — which is exactly what
AC-001.5's "never a copy read before it" protects against, and what AC-001.4 means by
an earlier read being advisory only. `RowsAffected == 0` means the token was replaced
or names another step: remove nothing, return nothing, compose with no handoff text,
and leave whatever is there for a later entry into the step it names.
The destination-step comparison sits in the `WHERE` clause rather than in Go, so
AC-001.4's "evaluated inside that one operation" holds literally. The stamp is what
makes the claim safe with NO isolation-level or transaction assumption: no `BeginTxx`,
no `SELECT ... FOR UPDATE`, no `BEGIN IMMEDIATE`, and no dependence on SQLite's
deferred-transaction upgrade behavior. Mirror `RemoveTaskMetadataKeyIfStamp`'s
dual-dialect body — it already carries the Postgres `jsonb_extract_path_text` / `#-`
form beside the SQLite `json_extract` / `json_remove` form — rather than adding a
SQLite-only method to a file whose every neighbour handles both.
The new method ships behind a narrow optional interface in
`internal/orchestrator/event_handlers_workflow.go`; it is deliberately not part
of the broad `sessionExecutorStore` contract in `internal/orchestrator/service.go`.
AC-005.3's degrade-to-today branch mirrors the existing
`asyncStepHistoryRecorder` and `stepCompletionSignalClaimer` optional-interface
assertions: a repository that lacks the method takes today's behavior rather than
erroring.
### Handoff carriage (REQ-001)
A **handoff carry token** on `tasks.metadata` under the key `step_handoff_carry`,
declared as a `MetaKey...` constant beside `MetaKeyQueuePromotionPending` and its ~25
neighbours in `internal/task/models/models.go`. Naming it there is not cosmetic:
`Task.Metadata` is `map[string]interface{}` with `json:"metadata,omitempty"`, so the
key ships to the frontend in every task payload, and an unregistered name can silently
collide with another feature's one-shot token. Its value is a JSON object with exactly
three fields:
- `handoff` — the bounded completion handoff text (REQ-003 bounds it, so a token
holds at most 8,192 bytes and the task payload grows by that much until claimed);
- `step_id` — the next step's identifier, which the claim compares;
- `stamp` — a fresh unique value minted on EVERY token write (`uuid.NewString()`;
`workflow_profile_session_lifecycle.go` already sets a `Stamp` that way). It must NOT
be content-derived: `models.StableLaunchErrorStamp` is a SHA-256 of its inputs, so two
successive tokens carrying the same handoff would share a stamp and the claim's
compare-and-swap would stop telling them apart. See "The claim primitive".
Single-slot by construction, since `SetTaskMetadataKey` overwrites, which is how
AC-001.3 forbids accumulation without a length check.
**Written** at both consuming-transition sites, under the same trigger gate the
bag clear uses (see "Trigger gating" above), next to `recordAutoStepTransition`
and before the bag clear, so AC-002.3's ordering falls out of placement rather
than a lock. A consumed signal with a blank handoff, or a consuming transition
that found no signal, removes the key instead of writing it (AC-001.2). A
non-consuming transition touches neither (AC-001.2a).
**Claimed** once per step entry, through one shared helper rather than logic
duplicated per branch (AC-001.7). The order is fixed by AC-001.6a, AC-001.6c and
AC-001.4:
1. compose the step entry prompt through `buildWorkflowEntryPrompt`, with no
handoff text, and let the branch merge any queued hand-off message exactly as
it does today;
2. apply that branch's existing rule for whether it will send the agent anything,
over content that excludes the handoff text (AC-001.6a);
3. if it will send nothing at all, stop: claim nothing, leave the token in place
(AC-001.6c). If it will send something — INCLUDING the passthrough branch that
found its composed prompt empty and is dispatching only a drained queued
message — continue;
4. read the token (advisory); if one is there, call
`TakeTaskMetadataKeyIfDestinationStep` with the step being entered AND the stamp
just read. If the read finds nothing, claim nothing. A token naming another step
is left untouched: AC-001.12 requires it still be deliverable when a manual move
later returns the task to that step. See "The claim primitive" for why this
settles both races (AC-001.4, AC-001.5, AC-005.4);
5. append the returned text LAST in the prompt, under the fixed heading
`## Context from the previous workflow step` (AC-001.6), without running
reference expansion over it (AC-001.6b). Appending after the composition seam
is what gives AC-001.6b for free: `expandPromptReferencesWithContext` runs
inside `buildWorkflowPromptWithTrustedContext`, which is upstream of here;
6. dispatch.
Steps 2 and 3 are per BRANCH, not per path: `launchAfterOnEnterDispatch` contains
two branches whose rules disagree (see "Actionability"). The shared helper takes the
branch's own send-or-not answer as an argument rather than re-deriving it.
A token addressed to a step that is never re-entered is not leaked: it is
single-slot, and the next consuming transition replaces it (AC-001.3) or removes
it (AC-001.2).
Composing first and claiming second is what makes AC-001.6a satisfiable: the
send-or-not rules live downstream of the composition seam, so a claim inside the
seam would necessarily precede the decision. Hence AC-001.7 is a coverage guarantee
over branches plus one shared implementation, not "claim inside
`buildWorkflowEntryPrompt`".
The claimed text is held by the dispatch path for the remainder of that step entry,
which lets a replacement launch reuse it (AC-001.8) even though the replacement
re-enters the composition seam with a fresh session. The seam's own
`ClaimInitialPromptFallback` treats a replacement as a fresh prompt boundary; the
carry token deliberately does not, so that precedent is noted to stop a builder
copying it.
Task-keyed, not session-keyed, because a transition may switch the task onto a
different session for the destination step's profile; a session-keyed token would
be written on the source session and read by nobody. That is what makes AC-001.10
and AC-001.11 hold rather than being separate code paths.
### Blockers retrievability (REQ-002)
Two more keys on the map `recordAutoStepTransition` already builds, named
`signal_blockers` and `signal_handoff` to match the `signal_source` /
`signal_summary` literals there, omitted when blank (AC-002.2). No table, no
column, no endpoint. The handoff is recorded here too, so the audit row states what
was carried as well as what was blocked.
These two names are a wire contract, not an internal detail: they surface
verbatim in the `metadata` map of `GET /sessions/:id/workflow/history`. Update the
doc comment on `CreateStepTransition` in `internal/workflow/service/service.go`,
which currently documents the shape as `{"signal_source", "signal_summary"}`, so
the documented shape and the written shape stay in step.
### Bounding (REQ-003)
Applied in `handleStepComplete`, where the signal is first constructed and
already `strings.TrimSpace`-normalised, upstream of the bag, the audit row and
the carry token, so all three hold the same bounded value from one enforcement
point. A fixed compiled-in constant, following
`REQ-TASKS-PLAN-CONTENT-SIZE-LIMIT-001`'s pattern.
Order matters and AC-003.2 pins it: TRIM FIRST, then measure. So "stored
byte-for-byte" in AC-003.2 means byte-for-byte against the TRIMMED value, not the
raw argument.
The ceiling is inclusive of the marker (AC-003.1), so the algorithm is: if the
trimmed value is at most 8,192 bytes, store it as-is; otherwise `truncate.UTF8` the
content to `8192 - len(marker)` bytes, which already cuts on a rune boundary, then
append the marker, giving a stored value of at most 8,192 bytes. The marker
`[truncated: over 8192-byte limit]` is 33 bytes, so the retained prefix is at most
8,159 bytes.
Bounding never rejects (AC-003.4): unlike the plan-size limit, refusing here
would strand a task on a step whose work is finished. The truncation report rides
the accepted result only: `truncated` is a JSON array of lowercase argument names
in the fixed order `["handoff", "blockers"]`, never a bare string and never a map,
alongside `truncation_limit_bytes` as a JSON number (AC-003.5). Both are omitted
entirely when nothing was truncated, so their absence is the signal that every
value was stored whole. `handleStepComplete` already returns a
`map[string]interface{}` that the MCP layer's `stepCompleteHandler` marshals
straight through, so the two fields reach the agent with no extra plumbing. The
duplicate path's rejection shape is untouched (AC-003.5a) because none of that
call's values were stored — note that bounding happens at signal construction,
which is upstream of the duplicate check, so a rejected duplicate must report no
truncation even though it computed one.
### Tool description (REQ-004)
Text-only change at the registration site. Non-localized: the string is sent to
the model, the same class as `workflowInstructionsHeading`, which the codebase
already documents as deliberately not i18n'd. No locale catalogs are touched, so
the i18n gate does not apply. Same for the fixed handoff heading in the prompt.
### Failure posture (REQ-005)
Every added write is best-effort, matching the contract the audit row already
has: `recordAutoStepTransition` logs and swallows, and this capability's writes
sit beside it under the same rule.
**A failed claim is not a spent claim, and that asymmetry with AC-005.1 is deliberate.**
AC-005.1 forbids retrying a failed token WRITE, because the transition it belongs to has
already committed and a retry would race the next one. The claim is the opposite case: a
claim that errors removed nothing and returned nothing, so the token is still there,
still addressed to this step, and a later attempt is free. AC-005.2 therefore does not
spend AC-001.8's one-claim-per-step-entry budget on a failure — a replacement launch in
the same step entry attempts the claim again, and so does a later entry into the same
step. What AC-005.2 does forbid is a retry loop INSIDE one composed prompt: one attempt
per composed prompt, and a failure composes with no handoff text. The claim's
compare-and-swap is what makes re-attempting safe rather than double-delivering.
**AC-005.5's re-run is not a delivery hazard.** `reconcileStepCompletionSignalLocked`
returns early on `task.WorkflowStepID != stepID`, so a replayed signal cannot re-run a
transition that already committed: the task is at the destination step by then and the
replay names the source. A re-record therefore lands only before any entry into that
step could have claimed, so AC-005.5 needs no double-delivery guard.
## Requirement framing
Each requirement's intent and user story, held here so the paired requirements
document stays inside its ceiling. These frame the contract; they are not
themselves acceptance criteria.
### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-001
*A completed step's completion handoff reaches the next step's agent exactly once*
**Intent:** Deliver what `handoff` already promises, on every path a step entry can
take, and stop there. Per-step context that is never dropped becomes a document
every later step pays to read.
**User story:** As an agent starting a workflow step, I want the previous step's
closing context in my first prompt, so I do not reconstruct it from a record that
grows on every hop.
### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-002
*A signal's blockers are retrievable after the transition*
**Intent:** Stop destroying the field. Its cheapest durable home is the audit
record already carrying the signal's summary and source, on an endpoint that
already ships.
**User story:** As someone reconstructing why a task moved, I want the blockers
the completing agent reported, so a stated unresolved issue survives the step
advancing.
### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-003
*Neither argument can grow without bound*
**Intent:** One hop of context is the deliverable. An oversized signal must still
advance the step: refusing it would strand a task on a step whose work is done.
**User story:** As an operator, I want a fixed ceiling on what one signal carries
forward, so delivering a handoff cannot reproduce the growth that made the running
record expensive to read.
### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-004
*The tool describes what it actually does*
**Intent:** The description must state delivery's exact extent: an agent believing
`handoff` persists across steps will use it as a running record.
**User story:** As an agent choosing what to put in each argument, I want the tool
to state where each lands and how long it lives, so I do not put multi-step
bookkeeping into a one-hop field.
### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-005
*Delivery never costs a transition*
**Intent:** Every added write is best-effort work on an already-committed
transition, matching the audit row's contract. A failed carry is a lost blurb; one
that rolls back or blocks a transition is a stuck card.
**User story:** As a user whose card is mid-transition, I want a carriage failure
to cost me the handoff and nothing else, so a step never stops advancing because a
context blurb could not be stored.
## Prior art followed
- **ADR 0015** widened `session_step_history.metadata` rather than adding a
table, explicitly rejecting a dedicated signal table as overkill. REQ-002 adds
keys to that same map for the same data, applying the decision rather than
reopening it.
- **`MetaKeyQueuePromotionPending` / `MetaKeyAutoStartOnCreate`** establish the
one-shot task-metadata token claimed by whichever delivery wins the atomic
remove. The carry token is that shape plus the step and stamp fields.
**Copy the claim, NOT the restore.** `restoreTaskLifecycleToken` puts a
queue-promotion token BACK at six failure/recovery sites and is generic over
`key`, so aiming it at `step_handoff_carry` is a one-line change made by
symmetry. AC-001.9 forbids it: a claimed token is never restored, even when the
entry that claimed it then fails to dispatch. That handoff is lost; REQ-005
accepts that.
- **`REQ-TASKS-PLAN-CONTENT-SIZE-LIMIT-001`** supplies the bounding pattern: one
fixed ceiling, compiled in, not configurable, enforced at a shared seam.
**What differs.** Those precedents claim a value that already had a reader, and
their claim needs only "was it there". This capability adds the reader, which is the
whole defect, and needs the VALUE back — which is why it adds a new primitive rather
than reusing `RemoveTaskMetadataKey`, and why that primitive is a compare-and-swap
rather than the plain conditional remove `RemoveTaskMetadataKeyIfStamp` performs.
## Testing notes
The two consuming-transition sites are the drift risk: a change applied to only
one leaves the other silently discarding handoffs. Cover both
`executeStepTransition` and `applyEngineTransitionWithCommitMode`, and cover a
non-consuming trigger at each to prove AC-001.2a's gate.
**Cover the guarded-decision carve-out explicitly.** A test that only varies the
trigger cannot catch F15's failure mode, because the guarded path carries
`TriggerOnTurnComplete` too. Drive a guarded quorum decision
(`transitionLifecycleGuardedDecision`) against a task holding an unclaimed carry
token and assert the token is STILL THERE afterwards. Without this test, an
implementation gated on the trigger alone passes every other test in this list.
The dispatch BRANCHES are the second drift risk, and there are more of them than
there are paths. Cover `launchAfterOnEnterDispatch` twice — the ACP branch via
`autoStartStepPrompt` (including a replacement launch, for AC-001.8) and the
passthrough branch that dispatches only a drained queued message (AC-001.6c) — plus
`StartSessionForWorkflowStep` (for AC-001.11's queue promotion). Assert the handoff
lands LAST, after any queued hand-off content, on the branch where both are present.
**The claim race needs a test that fails against a pre-check implementation.**
Between reading a token for step A and claiming it, overwrite the key with a token
for step B, then run the claim. Assert the entry into A receives no handoff AND the
step-B token is still present. An unconditional take plus a pre-check passes a naive
single-threaded test and fails this one, which is the whole point.
Add the same-step variant, which the step comparison alone cannot catch: replace the
token with a DIFFERENT token also naming step A, then claim. Assert the entry receives
nothing and the replacement is still present. An implementation that compares only
`step_id` removes the replacement and delivers the stale text, passing the step-B test
above; only the stamp compare-and-swap fails it.
Cover a failed claim followed by a replacement launch in the same step entry: assert the
second attempt runs and delivers, per the failure-posture rule that a failed claim does
not spend the entry's one claim.
Also assert an entry that sends the agent nothing claims nothing (AC-001.6a), so a
handoff can never be consumed by a dispatch that did not happen.
Assert a claimed token is NOT restored when the claiming entry then fails to dispatch
(AC-001.9): claim, fail the launch terminally, then assert `tasks.metadata` has no
`step_handoff_carry` and a later entry into that step gets no handoff. Without it the
`restoreTaskLifecycleToken` symmetry ships silently.
The async recorder means an assertion on a durable row can race. Assert on the
metadata map handed to the recorder (the test double takes the synchronous
branch), which is also the value AC-002.3 pins, and assert the exact key names
`signal_blockers` / `signal_handoff` rather than just presence.
AC-003.2's boundary pair (8,192 stored whole, 8,193 truncated) is measured AFTER
the trim, so include a case padded with whitespace that is oversized before
trimming and in-bounds after: it must store whole and report no truncation.
AC-003.3's marker-inside-the-ceiling rule needs a multi-byte-character case so a
cut landing mid-rune is caught. Assert `truncated` is an array in the order
`["handoff", "blockers"]` when both truncate, and that both fields are absent when
neither does.