@indexnetwork/protocol 6.12.1-rc.404.1 → 6.13.22-rc.405.1

package/dist/negotiation/application/negotiation.graph.js

@@ -0,0 +1,1393 @@
+import { StateGraph } from "@langchain/langgraph";
+import { invokeWithAbortSignal } from "../../shared/agent/model-signal.js";
+import { requestContext } from "../../shared/observability/request-context.js";
+import { NegotiationGraphState } from "../domain/negotiation.state.js";
+import { IndexNegotiator } from "./negotiation.agent.js";
+import { allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, configuredProtocolVersion, fallbackActionFor, isRejectLikeAction, isTerminalAction, readProtocolVersion, rejectActionFor } from "../domain/negotiation.protocol.js";
+import { assessConsultationEligibility, consultationPromptFor, negotiationConsultationPolicyMode } from "../domain/negotiation.consultation-policy.js";
+import { blocksNegotiationBeforeFirstTurn, NegotiationScreener } from "./negotiation.screen.js";
+import { configuredScreenMode } from "../domain/negotiation.screen.contracts.js";
+import { assessDeadlock, configuredDeadlockShiftEnabled, configuredDeadlockThreshold } from "../domain/negotiation.deadlock.js";
+import { protocolLogger } from "../../shared/observability/protocol.logger.js";
+import { NEGOTIATION_QUESTION_GENERIC_COUNTERPARTY, NEGOTIATION_QUESTION_GENERIC_NETWORK, negotiationQuestionSettlementId, validateInflightAskUserFields } from '../domain/negotiation.question-safety.js';
+import { buildIntentSnapshots } from "../domain/negotiation.intent-snapshot-provenance.js";
+import { holdsNegotiationConversationLock } from "../domain/negotiation.task-lock-policy.js";
+import { attributedDialogueIsEmpty, buildSeededAttribution, combineAttributedDialogue } from '../negotiation.attribution.js';
+const logger = protocolLogger("NegotiationGraph");
+const initLog = protocolLogger("NegotiationGraph:Init");
+const screenNodeLog = protocolLogger("NegotiationGraph:Screen");
+const turnLog = protocolLogger("NegotiationGraph:Turn");
+const finalizeLog = protocolLogger("NegotiationGraph:Finalize");
+const negotiateCandidatesLog = protocolLogger("NegotiationGraph:negotiateCandidates");
+/** Extracts the ordered NegotiationTurn list from A2A message data parts. */
+function turnsFromMessages(messages) {
+    return messages
+        .map((m) => {
+        const dataPart = m.parts.find((p) => p.kind === "data");
+        return dataPart?.data;
+    })
+        .filter(Boolean);
+}
+/**
+ * Whether `userId`'s side has already spent its one `ask_user` client
+ * consultation in this conversation (P3.2 rationing: max one per negotiation
+ * per side, checked against the full message history so continuations count
+ * prior sessions' consultations too).
+ */
+function hasPriorAskUser(messages, userId) {
+    const sender = `agent:${userId}`;
+    return messages.some((m) => {
+        if (m.senderId !== sender)
+            return false;
+        const dataPart = m.parts.find((p) => p.kind === "data");
+        return dataPart?.data?.action === "ask_user";
+    });
+}
+/**
+ * Factory for the bilateral negotiation LangGraph state machine.
+ * @remarks Accepts an AgentDispatcher for per-turn agent resolution.
+ */
+export class NegotiationGraphFactory {
+    constructor(database, dispatcher, timeoutQueue, questionerEnqueue, reflectEnqueue, memoryRetrieve) {
+        this.database = database;
+        this.dispatcher = dispatcher;
+        this.timeoutQueue = timeoutQueue;
+        this.questionerEnqueue = questionerEnqueue;
+        this.reflectEnqueue = reflectEnqueue;
+        this.memoryRetrieve = memoryRetrieve;
+    }
+    createGraph() {
+        const { database, dispatcher, timeoutQueue, questionerEnqueue, reflectEnqueue, memoryRetrieve } = this;
+        const systemAgent = new IndexNegotiator();
+        const screener = new NegotiationScreener();
+        /**
+         * P5.3 memory retrieval — never throws, never blocks a negotiation. The
+         * injected fn already resolves [] when NEGOTIATOR_MEMORY_INJECT is off;
+         * this wrapper adds the graph-side failure guard.
+         */
+        const retrieveMemory = async (userId, counterpartyUserId, queryText, scope) => {
+            if (!memoryRetrieve)
+                return [];
+            try {
+                return await memoryRetrieve({ userId, counterpartyUserId, queryText, scope });
+            }
+            catch (err) {
+                logger.warn("Negotiator memory retrieval failed; proceeding without memory", {
+                    userId,
+                    scope,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return [];
+            }
+        };
+        /** Similarity query text: seed reasoning + counterparty context. */
+        const memoryQueryText = (state, counterparty) => [
+            state.discoveryQuery ? `Search: ${state.discoveryQuery}` : "",
+            state.seedAssessment?.reasoning ?? "",
+            counterparty?.profile?.name ?? "",
+            counterparty?.profile?.bio ?? "",
+            (counterparty?.intents ?? []).slice(0, 5).map((i) => `${i.title}: ${i.description}`).join("\n"),
+        ].filter(Boolean).join("\n");
+        /**
+         * IND-569: resolve a prior negotiation task's attribution metadata for the
+         * per-opportunity prior-dialogue labels. Never throws — any failure returns
+         * null so the turns degrade to the unattributed block instead of leaking
+         * into the current opportunity's context.
+         */
+        const resolveTaskAttribution = async (taskId) => {
+            try {
+                const task = await database.getTask(taskId);
+                if (!task)
+                    return null;
+                const md = (task.metadata ?? {});
+                const opportunityId = typeof md.opportunityId === 'string' && md.opportunityId.length > 0 ? md.opportunityId : null;
+                const snapshots = Array.isArray(md.intentSnapshots) ? md.intentSnapshots : [];
+                const sourceIntentId = typeof md.sourceIntentId === 'string' ? md.sourceIntentId : null;
+                const snap = snapshots.find((s) => s && s.intentId === sourceIntentId) ?? snapshots[0];
+                const opportunityTitle = snap && typeof snap.title === 'string' && snap.title.trim().length > 0 ? snap.title : null;
+                let outcome = null;
+                try {
+                    const artifacts = await database.getArtifactsForTask(taskId);
+                    const outArtifact = artifacts.find((a) => a.name === 'negotiation-outcome');
+                    if (outArtifact) {
+                        const firstPart = Array.isArray(outArtifact.parts) ? outArtifact.parts[0] : undefined;
+                        const data = firstPart?.data;
+                        if (data && typeof data.hasOpportunity === 'boolean') {
+                            outcome = data.hasOpportunity ? 'accepted' : (data.reason === 'screened_out' ? 'not pursued' : 'declined');
+                        }
+                        else if (typeof outArtifact.metadata?.continuationOutcome === 'string') {
+                            outcome = outArtifact.metadata.continuationOutcome;
+                        }
+                    }
+                }
+                catch { /* outcome stays null; header degrades to "outcome unknown" */ }
+                const concludedAt = task.updatedAt instanceof Date
+                    ? task.updatedAt.toISOString()
+                    : (task.updatedAt ? new Date(task.updatedAt).toISOString() : null);
+                return { opportunityId, opportunityTitle, outcome, concludedAt };
+            }
+            catch {
+                return null;
+            }
+        };
+        /**
+         * IND-569: build the attributed prior dialogue passed to the screener and
+         * turn prompts. Combines the immutable seeded attribution (earlier + legacy
+         * unattributed blocks, resolved once in init) with this session's own turns
+         * (task-id-matched). Null when there is no seeded attribution.
+         */
+        const buildAttributedDialogue = (state) => {
+            if (!state.isContinuation || !state.priorAttribution)
+                return null;
+            const currentSessionTurns = turnsFromMessages(state.messages.filter((m) => m.taskId === state.taskId));
+            const dialogue = combineAttributedDialogue(state.priorAttribution, currentSessionTurns);
+            return attributedDialogueIsEmpty(dialogue) ? null : dialogue;
+        };
+        const initNode = async (state) => {
+            try {
+                // Exact continuations reuse the prior conversation and preclaimed
+                // successor; they must not create any mutable state before the fence.
+                const agentIdA = `agent:${state.sourceUser.id}`;
+                const agentIdB = `agent:${state.candidateUser.id}`;
+                const execution = state.continuationExecution;
+                const conversation = execution
+                    ? { id: execution.conversationId }
+                    : await database.getOrCreateDM(agentIdA, agentIdB, 'agent');
+                // --- Lock gate: check for an active task on this conversation ---
+                const priorMessages = await database.getMessagesForConversation(conversation.id);
+                if (Boolean(state.resumeFromTaskId) !== Boolean(state.continuationSettlementId)
+                    || Boolean(state.resumeFromTaskId) !== Boolean(execution))
+                    return { error: 'invalid continuation correlation' };
+                const exactContinuation = state.resumeFromTaskId && state.continuationSettlementId && execution
+                    ? { taskId: state.resumeFromTaskId, settlementId: state.continuationSettlementId, execution }
+                    : null;
+                const priorTask = exactContinuation
+                    ? await database.getTask(exactContinuation.taskId)
+                    : state.opportunityId
+                        ? await database.getNegotiationTaskForOpportunity(state.opportunityId)
+                        : null;
+                const claimedSuccessor = exactContinuation
+                    ? await database.getTask(exactContinuation.execution.successorTaskId)
+                    : null;
+                if (exactContinuation) {
+                    const settlement = priorTask?.metadata?.questionSettlement;
+                    const storedExecution = claimedSuccessor?.metadata?.continuationExecution;
+                    if (!priorTask
+                        || priorTask.conversationId !== conversation.id
+                        || priorTask.state !== 'canceled'
+                        || priorTask.metadata?.opportunityId !== state.opportunityId
+                        || settlement?.settlementId !== exactContinuation.settlementId
+                        || settlement?.taskId !== exactContinuation.taskId
+                        || !claimedSuccessor
+                        || claimedSuccessor.conversationId !== conversation.id
+                        || storedExecution?.token !== exactContinuation.execution.token
+                        || storedExecution?.fence !== exactContinuation.execution.fence
+                        || storedExecution?.status !== 'claimed')
+                        return { error: 'invalid exact continuation task' };
+                }
+                const isLocked = !exactContinuation && !!priorTask && holdsNegotiationConversationLock(priorTask);
+                if (isLocked) {
+                    initLog.info('Conversation locked by active task, returning busy', {
+                        conversationId: conversation.id,
+                        opportunityId: state.opportunityId,
+                    });
+                    return { error: 'busy' };
+                }
+                // --- Load prior messages and determine continuation ---
+                const priorTurns = turnsFromMessages(priorMessages);
+                const isContinuation = priorTurns.length > 0;
+                // Determine currentSpeaker from last prior message. An `ask_user` last
+                // turn does NOT pass the floor: the sender paused to consult its own
+                // client, so on resume the same side speaks again — now armed with the
+                // client's answer (or its recorded absence). Flipping here would hand
+                // the turn to the counterparty, who has nothing to respond to.
+                let currentSpeaker = 'source';
+                if (isContinuation && priorMessages.length > 0) {
+                    const lastMessage = priorMessages[priorMessages.length - 1];
+                    const lastAction = turnsFromMessages([lastMessage])[0]?.action;
+                    if (lastAction === 'ask_user') {
+                        currentSpeaker = lastMessage.senderId === agentIdA ? 'source' : 'candidate';
+                    }
+                    else {
+                        currentSpeaker = lastMessage.senderId === agentIdA ? 'candidate' : 'source';
+                    }
+                }
+                // Determine scenario-based maxTurns
+                const scope = { action: 'manage:negotiations', scopeType: 'network', scopeId: state.indexContext.networkId };
+                const [sourceHasAgent, candidateHasAgent] = await Promise.all([
+                    dispatcher.hasExternalAgent(state.sourceUser.id, scope),
+                    dispatcher.hasExternalAgent(state.candidateUser.id, scope),
+                ]);
+                const ambientMax = Number(process.env.NEGOTIATION_MAX_TURNS_AMBIENT) || 6;
+                let maxTurns = state.maxTurns;
+                if (maxTurns == null) {
+                    maxTurns = (sourceHasAgent && candidateHasAgent) ? 0 : ambientMax;
+                }
+                // --- Initiator seat resolution (v2: rigid per match, stamped at discovery) ---
+                // 1. Continuations inherit from the prior task for the same opportunity —
+                //    never re-derive, so the seat cannot flip between sessions.
+                // 2. Conversation-scoped tie-break: if another negotiation on this DM is
+                //    active and fresh (symmetric concurrent start under a different
+                //    opportunityId — the opportunity-scoped lock above cannot see it),
+                //    the first created task keeps the seat; this run inherits its stamp.
+                // 3. Otherwise: explicit stamp from the caller, falling back to the
+                //    session's sourceUser (pre-stamp heuristic behavior, unchanged).
+                const readInitiator = (metadata) => {
+                    const v = metadata?.initiatorUserId;
+                    return typeof v === 'string' && v.length > 0 ? v : null;
+                };
+                let initiatorUserId = readInitiator(priorTask?.metadata) ?? state.initiatorUserId ?? state.sourceUser.id;
+                // Conversation-scoped prior task: used only for the initiator tie-break
+                // (and only when active+fresh).
+                const convTask = !exactContinuation && !readInitiator(priorTask?.metadata)
+                    ? await database.getLatestNegotiationTaskForConversation?.(conversation.id).catch(() => null)
+                    : null;
+                if (!readInitiator(priorTask?.metadata)) {
+                    if (convTask && convTask.id !== priorTask?.id && holdsNegotiationConversationLock(convTask)) {
+                        const convInitiator = readInitiator(convTask.metadata);
+                        if (convInitiator) {
+                            initLog.info('Conversation-scoped tie-break: inheriting initiator seat from concurrent task', {
+                                conversationId: conversation.id,
+                                winningTaskId: convTask.id,
+                                initiatorUserId: convInitiator,
+                            });
+                            initiatorUserId = convInitiator;
+                        }
+                    }
+                }
+                // --- Protocol version: pinned per negotiation, re-stamped per match ---
+                // A prior task for this same negotiation (exact continuation resume or
+                // a re-run of the same opportunity) pins the version, so one
+                // negotiation never flips semantics mid-flight (absent field on a
+                // genuine prior = pre-v2 task = v1). Everything else — including
+                // continuations of older conversations between the same pair — stamps
+                // fresh from NEGOTIATION_PROTOCOL_VERSION, so a version cutover
+                // reaches existing pairs on their next new match instead of being
+                // pinned to v1 forever by conversation history.
+                const protocolVersion = priorTask
+                    ? (readProtocolVersion(priorTask.metadata) ?? 'v1')
+                    : configuredProtocolVersion();
+                const taskMetadata = {
+                    type: 'negotiation',
+                    sourceUserId: state.sourceUser.id,
+                    initiatorUserId,
+                    protocolVersion,
+                    candidateUserId: state.candidateUser.id,
+                    networkId: state.indexContext.networkId,
+                    sourceIntentId: state.sourceIntentId,
+                    candidateIntentId: state.candidateIntentId,
+                    participantBindings: [
+                        ...(state.sourceIntentId ? [{ userId: state.sourceUser.id, intentId: state.sourceIntentId, networkId: state.indexContext.networkId }] : []),
+                        ...(state.candidateIntentId ? [{ userId: state.candidateUser.id, intentId: state.candidateIntentId, networkId: state.indexContext.networkId }] : []),
+                    ],
+                    intentSnapshots: buildIntentSnapshots(state.sourceUser, state.candidateUser),
+                    ...(state.opportunityId && { opportunityId: state.opportunityId }),
+                    maxTurns,
+                    isContinuation,
+                    priorTurnCount: priorTurns.length,
+                    ...(exactContinuation ? {
+                        resumeFromTaskId: exactContinuation.taskId,
+                        continuationSettlementId: exactContinuation.settlementId,
+                    } : {}),
+                };
+                if (state.opportunityId && Boolean(state.opportunityStatus) !== Boolean(state.opportunityUpdatedAt)) {
+                    throw new Error('Negotiation attempt requires both opportunity status and updatedAt');
+                }
+                const task = exactContinuation
+                    ? claimedSuccessor
+                    : state.opportunityId && state.opportunityStatus && state.opportunityUpdatedAt
+                        ? await database.createNegotiationTaskForAttempt({
+                            conversationId: conversation.id,
+                            opportunityId: state.opportunityId,
+                            expectedStatus: state.opportunityStatus,
+                            expectedUpdatedAt: state.opportunityUpdatedAt,
+                            metadata: taskMetadata,
+                        })
+                        : await database.createTask(conversation.id, taskMetadata);
+                if (!task) {
+                    throw new Error('Negotiation attempt is stale or already claimed');
+                }
+                // Attempt-bound discovery atomically promoted the exact persisted state
+                // to `negotiating` while inserting the task. Legacy/direct invocations
+                // with only an opportunity ID retain the prior best-effort status update.
+                if (state.opportunityId && !state.opportunityUpdatedAt) {
+                    await database.updateOpportunityStatus(state.opportunityId, 'negotiating').catch((err) => {
+                        initLog.error('Failed to set opportunity status to negotiating', { opportunityId: state.opportunityId, error: err });
+                    });
+                }
+                // Load user answers collected by the questioner between sessions
+                const userAnswers = (isContinuation && state.opportunityId)
+                    ? await database.getOpportunityUserAnswers(state.opportunityId).catch((err) => {
+                        initLog.error('Failed to load user answers', { opportunityId: state.opportunityId, error: err });
+                        return [];
+                    })
+                    : [];
+                // Seed messages with prior turns (additive reducer appends new turns on top).
+                // taskId is preserved so the turn/screen nodes can separate this
+                // session's turns from seeded prior-task turns (IND-569).
+                const seedMessages = isContinuation ? priorMessages.map((m) => ({
+                    id: m.id,
+                    senderId: m.senderId,
+                    role: 'agent',
+                    parts: m.parts,
+                    createdAt: m.createdAt,
+                    taskId: m.taskId ?? null,
+                })) : [];
+                // IND-569: attribute seeded prior turns to their originating opportunity
+                // once, up front. Earlier-opportunity and legacy unattributed blocks are
+                // immutable for the session; the current block is composed per turn.
+                const priorAttribution = isContinuation
+                    ? await buildSeededAttribution(priorMessages
+                        .map((m) => ({ taskId: m.taskId ?? null, turn: turnsFromMessages([m])[0] }))
+                        .filter((e) => Boolean(e.turn)), state.opportunityId, resolveTaskAttribution)
+                    : null;
+                return {
+                    conversationId: conversation.id,
+                    taskId: task.id,
+                    currentSpeaker,
+                    turnCount: 0,
+                    maxTurns,
+                    isContinuation,
+                    initiatorUserId,
+                    protocolVersion,
+                    priorTurnCount: priorTurns.length,
+                    ...(priorAttribution && { priorAttribution }),
+                    ...(userAnswers.length > 0 && { userAnswers }),
+                    ...(exactContinuation?.execution.consultation
+                        ? { privateConsultation: exactContinuation.execution.consultation }
+                        : {}),
+                    ...(exactContinuation && (() => {
+                        const turnContext = priorTask?.metadata?.turnContext;
+                        const reason = turnContext?.consultationPolicyReason;
+                        return typeof reason === 'string' ? { consultationPolicyReason: reason } : {};
+                    })()),
+                    ...(seedMessages.length > 0 && { messages: seedMessages }),
+                };
+            }
+            catch (err) {
+                return { error: `Init failed: ${err instanceof Error ? err.message : String(err)}` };
+            }
+        };
+        /**
+         * Screen node (P2.1) — the outreach gate. Runs between init and the first
+         * turn on FRESH negotiations only (routing skips it on continuations and
+         * when NEGOTIATION_SCREEN_MODE=off). The reaching client's negotiator
+         * decides whether the match is worth its client's name; in shadow mode the
+         * decision is recorded (task metadata + trace event + log line) but never
+         * blocks — the negotiation always proceeds to the first turn. In enforce
+         * mode (P2.2) a `pass` routes straight to finalize: zero turns, zero
+         * counterparty involvement, outcome `reason: "screened_out"`, opportunity
+         * quietly `rejected` (init had already flipped it to `negotiating`).
+         * A failed screen still fails OPEN in every mode.
+         */
+        const screenNode = async (state) => {
+            const traceEmitter = requestContext.getStore()?.traceEmitter;
+            const emitWide = (event) => traceEmitter?.(event);
+            const mode = configuredScreenMode();
+            const start = Date.now();
+            // The client is the initiator seat's user — the side whose negotiator is
+            // reaching out. Fresh runs stamp initiatorUserId in init; fall back to
+            // sourceUser (what the stamp defaults to anyway).
+            const initiatorId = state.initiatorUserId ?? state.sourceUser.id;
+            const clientIsSource = initiatorId !== state.candidateUser.id;
+            const clientUser = clientIsSource ? state.sourceUser : state.candidateUser;
+            const counterpartyUser = clientIsSource ? state.candidateUser : state.sourceUser;
+            // P5.3: the client's own negotiator memory informs the outreach gate.
+            // Cached into state so the client's first turn reuses it.
+            const clientSide = clientIsSource ? "source" : "candidate";
+            const clientMemory = state.memoryBySide?.[clientSide]
+                ?? (memoryRetrieve
+                    ? await retrieveMemory(clientUser.id, counterpartyUser.id, memoryQueryText(state, counterpartyUser), "screen")
+                    : []);
+            let decision;
+            let failedOpen = false;
+            let screenError;
+            try {
+                const counterpartyContext = (await database.getUserContext(counterpartyUser.id, null).catch(() => null))?.text ?? "";
+                const priorDialogueAttributed = buildAttributedDialogue(state);
+                decision = await screener.invoke({
+                    clientUser,
+                    counterpartyUser,
+                    ...(counterpartyContext && { counterpartyContext }),
+                    ...(clientMemory.length > 0 && { memory: clientMemory }),
+                    // discoveryQuery belongs to the discovery session's source user; only
+                    // meaningful for the client when the client holds the source side.
+                    ...(clientIsSource && state.discoveryQuery && { discoveryQuery: state.discoveryQuery }),
+                    seedAssessment: state.seedAssessment,
+                    indexContext: state.indexContext,
+                    isContinuation: state.isContinuation,
+                    ...(state.messages.length > 0 && { priorDialogue: turnsFromMessages(state.messages) }),
+                    ...(priorDialogueAttributed && { priorDialogueAttributed }),
+                });
+            }
+            catch (err) {
+                // Fail open: a screen failure must never block a negotiation.
+                failedOpen = true;
+                screenError = err instanceof Error ? err.message : String(err);
+                screenNodeLog.warn("Screen failed; proceeding open (reach_out)", {
+                    taskId: state.taskId,
+                    opportunityId: state.opportunityId || undefined,
+                    error: screenError,
+                });
+                decision = {
+                    decision: "reach_out",
+                    reasoning: `screen_error: ${screenError}`,
+                    evidence: { counterpartyPremiseFit: "", intentAlignment: "" },
+                };
+            }
+            const durationMs = Date.now() - start;
+            const record = {
+                ...decision,
+                mode,
+                ...(failedOpen && { failedOpen, error: screenError }),
+                screenedAt: new Date().toISOString(),
+                durationMs,
+            };
+            await database.setTaskScreenDecision?.(state.taskId, record, state.continuationExecution).catch((err) => {
+                screenNodeLog.error("Failed to persist screen decision", { taskId: state.taskId, error: err });
+            });
+            screenNodeLog.info("negotiation_screen", {
+                taskId: state.taskId,
+                opportunityId: state.opportunityId || undefined,
+                decision: decision.decision,
+                mode,
+                failedOpen,
+                durationMs,
+            });
+            if (state.opportunityId) {
+                emitWide({
+                    type: "negotiation_screen",
+                    opportunityId: state.opportunityId,
+                    negotiationConversationId: state.conversationId,
+                    decision: decision.decision,
+                    reasoning: decision.reasoning,
+                    mode,
+                    failedOpen,
+                    durationMs,
+                });
+            }
+            // Routing happens on the conditional edge: shadow always proceeds to
+            // the first turn; enforce routes a (non-failed-open) pass to finalize.
+            return { screenDecision: record, memoryBySide: { [clientSide]: clientMemory } };
+        };
+        const turnNode = async (state) => {
+            const traceEmitter = requestContext.getStore()?.traceEmitter;
+            // Local helper to emit events whose shape is wider than the declared
+            // `TraceEmitter` union. The chat agent already casts at its relay sink;
+            // here we localize the cast at the callsite so the rest of the body stays typed.
+            const emitWide = (event) => traceEmitter?.(event);
+            const agentName = "Index negotiator";
+            const agentStart = Date.now();
+            traceEmitter?.({ type: "agent_start", name: agentName });
+            try {
+                const history = turnsFromMessages(state.messages);
+                const isSource = state.currentSpeaker === "source";
+                const ownUser = isSource ? state.sourceUser : state.candidateUser;
+                const otherUser = isSource ? state.candidateUser : state.sourceUser;
+                const ownIntentId = isSource ? state.sourceIntentId : state.candidateIntentId;
+                // Determine if this is the system agent's final allowed turn
+                const maxTurns = state.maxTurns ?? 0;
+                const isFinalTurn = maxTurns > 0 && (state.turnCount + 1) >= maxTurns;
+                // Seat attribution keys on initiatorUserId (rigid v2 stamp), never on
+                // parity or source/candidate position — under the conversation-scoped
+                // tie-break this run's source may hold the counterparty seat.
+                const version = state.protocolVersion ?? 'v1';
+                const seat = ownUser.id === (state.initiatorUserId ?? state.sourceUser.id)
+                    ? 'initiator'
+                    : 'counterparty';
+                // Legacy ask_user availability (P3.2): flag on, full pause loop wired
+                // (questioner + answer-window timer + an opportunity to resume
+                // against), v2 non-final non-opening turn, and this side's one client
+                // consultation not yet spent (rationing). Shadow is observational and
+                // must preserve this legacy path byte-for-byte except for telemetry.
+                const policyMode = negotiationConsultationPolicyMode();
+                const askUserAvailable = version === 'v2'
+                    && !isFinalTurn
+                    && configuredAskUserEnabled()
+                    && !!questionerEnqueue
+                    && !!timeoutQueue?.enqueueAskUserExpiry
+                    && !!state.opportunityId
+                    && !!ownIntentId
+                    && !!state.indexContext.networkId
+                    && !(state.turnCount === 0 && !state.isContinuation)
+                    && !hasPriorAskUser(state.messages, ownUser.id);
+                // ─── Deadlock detection → persuasion→bargaining stance (IND-428) ──────
+                // Deterministic trailing-run inspection of the persisted history — no
+                // LLM in the decision. Gated on the strict default-off flag AND v2,
+                // checked alongside the protocol-version plumbing so v1 semantics stay
+                // untouched. Fail-open: any detection error means "no deadlock" and
+                // the legacy path proceeds byte-identically. The shift changes the
+                // system agent's drafting stance only — allowedActions, the dispatch
+                // payload, and all termination rules are untouched.
+                let deadlock = null;
+                if (version === 'v2' && configuredDeadlockShiftEnabled()) {
+                    try {
+                        deadlock = assessDeadlock(history, configuredDeadlockThreshold());
+                    }
+                    catch (err) {
+                        turnLog.warn('Deadlock detection failed; proceeding without mode shift', {
+                            taskId: state.taskId,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                        deadlock = null;
+                    }
+                }
+                const bargainingMode = deadlock?.deadlocked === true;
+                // P5.3: the speaker's own negotiator memory (cached per side across
+                // turns). Injected into both the dispatch payload (the user's own
+                // agent — scope-correct) and the system-agent prompt.
+                const ownSide = isSource ? "source" : "candidate";
+                const ownMemory = state.memoryBySide?.[ownSide]
+                    ?? (memoryRetrieve
+                        ? await retrieveMemory(ownUser.id, otherUser.id, memoryQueryText(state, otherUser), "turn")
+                        : []);
+                const payload = {
+                    negotiationId: state.taskId,
+                    ownUser,
+                    otherUser,
+                    indexContext: state.indexContext,
+                    seedAssessment: state.seedAssessment,
+                    history,
+                    isFinalTurn,
+                    isDiscoverer: isSource,
+                    seat,
+                    protocolVersion: version,
+                    allowedActions: [...allowedActionsFor(version, seat, isFinalTurn, { askUser: askUserAvailable })],
+                    ...(state.discoveryQuery && isSource && { discoveryQuery: state.discoveryQuery }),
+                    ...(ownMemory.length > 0 && { negotiatorMemory: ownMemory }),
+                    ...(state.privateConsultation?.recipientUserId === ownUser.id
+                        ? { privateConsultation: state.privateConsultation }
+                        : {}),
+                };
+                const scope = { action: 'manage:negotiations', scopeType: 'network', scopeId: state.indexContext.networkId };
+                const dispatchResult = await dispatcher.dispatch(ownUser.id, scope, payload, { timeoutMs: state.timeoutMs });
+                let turn;
+                if (dispatchResult.handled) {
+                    // Personal agent responded. Under v2, coerce out-of-seat actions to
+                    // the conservative fallback — the polling/respond surfaces reject
+                    // these with a 400, but locally-dispatched turns land here directly.
+                    turn = dispatchResult.turn;
+                    if (version === 'v2' && !allowedActionsFor(version, seat, isFinalTurn, { askUser: askUserAvailable }).includes(turn.action)) {
+                        turnLog.warn('Personal agent returned out-of-seat action, coercing to conservative fallback', {
+                            action: turn.action, seat, isFinalTurn,
+                        });
+                        turn = { ...turn, action: fallbackActionFor(version, seat, isFinalTurn) };
+                    }
+                }
+                else if (dispatchResult.reason === 'waiting') {
+                    // Long timeout — graph suspends. Persist the full turn context so the
+                    // polling agent (and MCP consumers via get_negotiation) reconstruct
+                    // the same view the in-process system agent would see. The view is
+                    // stored in absolute source/candidate terms; perspective is projected
+                    // at pickup time using the claiming user's id.
+                    traceEmitter?.({ type: "agent_end", name: agentName, durationMs: Date.now() - agentStart, summary: "waiting_for_agent" });
+                    await database.setTaskTurnContext(state.taskId, {
+                        sourceUser: state.sourceUser,
+                        candidateUser: state.candidateUser,
+                        indexContext: state.indexContext,
+                        seedAssessment: state.seedAssessment,
+                        // Keep discoveryQuery speaker-scoped: include it only when the
+                        // parked turn belongs to the discoverer (source). Persisting it on
+                        // candidate-side turns would make the pickup prompt frame the
+                        // search as "your user searched for X" for the wrong user.
+                        ...(isSource && state.discoveryQuery && { discoveryQuery: state.discoveryQuery }),
+                        ...(state.privateConsultation && state.privateConsultation.recipientUserId === ownUser.id
+                            ? { privateConsultation: state.privateConsultation }
+                            : {}),
+                    }, state.continuationExecution);
+                    await database.updateTaskState(state.taskId, "waiting_for_agent", undefined, state.continuationExecution);
+                    return { status: 'waiting_for_agent' };
+                }
+                else {
+                    // No personal agent or timeout — run system agent
+                    const agentPriorDialogue = buildAttributedDialogue(state);
+                    turn = await systemAgent.invoke({
+                        ownUser,
+                        otherUser,
+                        indexContext: state.indexContext,
+                        seedAssessment: state.seedAssessment,
+                        history,
+                        isFinalTurn,
+                        isDiscoverer: isSource,
+                        seat,
+                        protocolVersion: version,
+                        ...(state.discoveryQuery && isSource && { discoveryQuery: state.discoveryQuery }),
+                        isContinuation: state.isContinuation,
+                        ...(agentPriorDialogue && { priorDialogue: agentPriorDialogue }),
+                        ...(state.userAnswers.length > 0 && { userAnswers: state.userAnswers }),
+                        ...(askUserAvailable && { canAskUser: true }),
+                        ...(bargainingMode && { bargaining: { consecutiveNonConvergent: deadlock.consecutiveNonConvergent } }),
+                        ...(ownMemory.length > 0 && { memory: ownMemory }),
+                        ...(state.privateConsultation?.recipientUserId === ownUser.id
+                            ? { privateConsultation: state.privateConsultation }
+                            : {}),
+                    });
+                }
+                traceEmitter?.({ type: "agent_end", name: agentName, durationMs: Date.now() - agentStart, summary: `${turn.action}` });
+                // First turn must open the negotiation (unless continuing a prior
+                // conversation): v1 → "propose"; v2 initiator → "outreach". A v2 turn-0
+                // speaker holding the counterparty seat (tie-break inheritance) is left
+                // unforced — it is responding, not opening.
+                if (state.turnCount === 0 && !state.isContinuation) {
+                    const openingAction = version === 'v2' ? 'outreach' : 'propose';
+                    if ((version !== 'v2' || seat === 'initiator') && turn.action !== openingAction) {
+                        turnLog.warn(`Agent returned unexpected action on turn 0, forcing to ${openingAction}`, { action: turn.action });
+                        turn.action = openingAction;
+                    }
+                }
+                // IND-564: block a `withdraw` that comes before the initiator has opened
+                // (no in-task `outreach`) — this would retract a message never made and
+                // drop a spurious message into the shared thread. Exact ask_user resumes
+                // are exempt: the successor is the SAME logical negotiation resumed after
+                // the client answered, so post-consultation withdraw is legitimate.
+                if (turn.action === 'withdraw' && !state.outreachOpened && !state.continuationExecution) {
+                    turnLog.info('negotiation_opening_withdraw_screened_out', {
+                        taskId: state.taskId,
+                        opportunityId: state.opportunityId || undefined,
+                        seat,
+                        turnCount: state.turnCount,
+                        isContinuation: state.isContinuation,
+                    });
+                    traceEmitter?.({ type: "agent_end", name: agentName, durationMs: Date.now() - agentStart, summary: "screened_out: opening withdraw" });
+                    return { lastTurn: turn, firstTurnScreenedOut: true };
+                }
+                // IND-508 deterministic admission is evaluated only after the opening
+                // guard but before any turn is persisted. It consumes action/role enums
+                // only; free-form reasoning, messages, profiles, and evaluator inputs
+                // are intentionally unavailable to the policy.
+                let consultationPolicyReason;
+                const policyEligibility = policyMode === 'off' ? { eligible: false } : assessConsultationEligibility({
+                    protocolVersion: version,
+                    seat,
+                    isOpeningTurn: state.turnCount === 0 && !state.isContinuation,
+                    isFinalTurn,
+                    screenedOut: blocksNegotiationBeforeFirstTurn(state.screenDecision, state.turnCount),
+                    action: turn.action,
+                    ownSuggestedRole: turn.assessment?.suggestedRoles?.ownUser,
+                    priorActions: history.map((prior) => prior.action),
+                    previouslyConsulted: hasPriorAskUser(state.messages, ownUser.id),
+                    hasExactResumeCoordinate: Boolean(configuredAskUserEnabled()
+                        && questionerEnqueue
+                        && timeoutQueue?.enqueueAskUserExpiry
+                        && state.taskId
+                        && state.opportunityId
+                        && ownIntentId
+                        && state.indexContext.networkId),
+                    lifecycleValid: Boolean(state.taskId && state.opportunityId && ownIntentId && state.indexContext.networkId),
+                });
+                const emitConsultationTelemetry = (stage, reason) => {
+                    turnLog.info('negotiation_consultation_policy', { stage, mode: policyMode, reason });
+                    emitWide({ type: 'negotiation_consultation_policy', stage, mode: policyMode, reason });
+                };
+                if (policyEligibility.eligible && policyEligibility.reason) {
+                    emitConsultationTelemetry('eligible', policyEligibility.reason);
+                    if (policyMode === 'on') {
+                        consultationPolicyReason = policyEligibility.reason;
+                        turn = {
+                            ...turn,
+                            action: 'ask_user',
+                            message: null,
+                            assessment: {
+                                reasoning: 'Client consultation required.',
+                                suggestedRoles: turn.assessment.suggestedRoles,
+                            },
+                            askUser: consultationPromptFor(consultationPolicyReason),
+                        };
+                        emitConsultationTelemetry('asked', consultationPolicyReason);
+                    }
+                }
+                // Safety net: off/shadow retain legacy behavior. In on, a spontaneous
+                // ask_user is admissible only when the deterministic policy just
+                // authorized it, so no unbounded pause can enter shared history.
+                if (turn.action === 'ask_user' && (!askUserAvailable || (policyMode === 'on' && !consultationPolicyReason))) {
+                    turnLog.warn('ask_user emitted while unavailable, coercing to conservative fallback', {
+                        seat, isFinalTurn, taskId: state.taskId,
+                    });
+                    turn = { ...turn, action: fallbackActionFor(version, seat, isFinalTurn) };
+                }
+                // ─── Deadlock shift record (IND-428) ───────────────────────────────
+                // Applied-stance analytics: recorded once per session, on the first
+                // turn actually drafted in the bargaining stance (the system agent —
+                // externally dispatched turns never receive the stance). Internal
+                // metadata only: persisted to tasks.metadata.deadlockShift via the
+                // optional hook; negotiation API surfaces project specific fields and
+                // never return task metadata verbatim. Every step fails open.
+                const bargainingApplied = bargainingMode && !dispatchResult.handled;
+                let deadlockShiftRecord = null;
+                if (bargainingApplied && !state.deadlockShift) {
+                    deadlockShiftRecord = {
+                        reason: 'consecutive_non_convergent',
+                        consecutiveNonConvergent: deadlock.consecutiveNonConvergent,
+                        threshold: deadlock.threshold,
+                        shiftedAtTurn: state.turnCount,
+                        seat,
+                        detectedAt: new Date().toISOString(),
+                    };
+                    await database.setTaskDeadlockShift?.(state.taskId, deadlockShiftRecord, state.continuationExecution).catch((err) => {
+                        turnLog.error('Failed to persist deadlock shift record', { taskId: state.taskId, error: err });
+                    });
+                    turnLog.info('negotiation_deadlock_shift', {
+                        taskId: state.taskId,
+                        opportunityId: state.opportunityId || undefined,
+                        seat,
+                        consecutiveNonConvergent: deadlockShiftRecord.consecutiveNonConvergent,
+                        threshold: deadlockShiftRecord.threshold,
+                        turnIndex: state.turnCount,
+                    });
+                    if (state.opportunityId) {
+                        emitWide({
+                            type: 'negotiation_deadlock_shift',
+                            opportunityId: state.opportunityId,
+                            negotiationConversationId: state.conversationId,
+                            turnIndex: state.turnCount,
+                            actor: isSource ? 'source' : 'candidate',
+                            consecutiveNonConvergent: deadlockShiftRecord.consecutiveNonConvergent,
+                            threshold: deadlockShiftRecord.threshold,
+                        });
+                    }
+                }
+                const parts = [{ kind: "data", data: turn }];
+                const message = await database.createMessage({
+                    conversationId: state.conversationId,
+                    senderId: `agent:${ownUser.id}`,
+                    role: "agent",
+                    parts,
+                    taskId: state.taskId,
+                    ...(state.continuationExecution ? { continuationExecution: state.continuationExecution } : {}),
+                });
+                // ─── ask_user pause (P3.2) ────────────────────────────────────────────
+                // The negotiator consults its OWN client: persist the turn (done above),
+                // park the full turn context, arm the answer-window timer, enqueue the
+                // question through the negotiation_inflight preset, then suspend the
+                // task as input_required. The graph exits at this turn boundary exactly
+                // like the waiting_for_agent suspend; the answer (or window expiry)
+                // resumes via the run-existing continuation path.
+                if (turn.action === 'ask_user') {
+                    const counterparty = isSource ? state.candidateUser : state.sourceUser;
+                    const safeAskUser = validateInflightAskUserFields({
+                        disclosureSubject: turn.askUser?.disclosureSubject,
+                        draftQuestion: turn.askUser?.draftQuestion,
+                        forbiddenIdentifiers: [
+                            counterparty.id,
+                            counterparty.profile.name ?? '',
+                            state.opportunityId,
+                            state.taskId,
+                            state.indexContext.networkId,
+                            isSource ? state.candidateIntentId ?? '' : state.sourceIntentId ?? '',
+                        ],
+                        forbiddenSourceText: [
+                            counterparty.profile.bio ?? '',
+                            counterparty.profile.location ?? '',
+                            ...counterparty.intents.flatMap((intent) => [intent.title, intent.description]),
+                            state.seedAssessment.reasoning,
+                            state.indexContext.prompt,
+                            state.discoveryQuery ?? '',
+                        ],
+                    });
+                    const settlementId = negotiationQuestionSettlementId(state.taskId);
+                    const askUserBinding = await database.captureNegotiationAskUserBinding({
+                        taskId: state.taskId,
+                        settlementId,
+                        recipientUserId: ownUser.id,
+                        recipientIntentId: ownIntentId,
+                        opportunityId: state.opportunityId,
+                        networkId: state.indexContext.networkId,
+                        turnContext: {
+                            sourceUser: state.sourceUser,
+                            candidateUser: state.candidateUser,
+                            indexContext: state.indexContext,
+                            seedAssessment: state.seedAssessment,
+                            ...(isSource && state.discoveryQuery && { discoveryQuery: state.discoveryQuery }),
+                            ...(consultationPolicyReason && { consultationPolicyReason }),
+                        },
+                        ...(state.continuationExecution ? { continuationExecution: state.continuationExecution } : {}),
+                    });
+                    // Arm the timer BEFORE flipping state: it is the durable recovery
+                    // trigger even when generation enqueues no job or persists no row.
+                    const windowMs = askUserAnswerWindowMs();
+                    await timeoutQueue.enqueueAskUserExpiry(state.taskId, {
+                        settlementId,
+                        opportunityId: state.opportunityId,
+                        userId: ownUser.id,
+                        recipientIntentId: ownIntentId,
+                        networkId: state.indexContext.networkId,
+                        intentFingerprint: askUserBinding.intentFingerprint,
+                        opportunityStatus: askUserBinding.opportunityStatus,
+                        opportunityUpdatedAt: askUserBinding.opportunityUpdatedAt,
+                        counterpartyUserId: askUserBinding.counterpartyUserId,
+                        counterpartyIntentId: askUserBinding.counterpartyIntentId,
+                    }, windowMs);
+                    // Persistence admission requires the exact task to be input_required.
+                    // Flip before enqueue; if the structured ask_user fields fail the
+                    // deterministic privacy gate, the timer alone closes the exact task.
+                    await database.updateTaskState(state.taskId, 'input_required', undefined, state.continuationExecution);
+                    if (safeAskUser) {
+                        const userContext = (await database.getUserContext(ownUser.id, null).catch(() => null))?.text ?? '';
+                        await questionerEnqueue({
+                            mode: 'negotiation_inflight',
+                            purpose: 'inflight_consultation',
+                            userId: ownUser.id,
+                            sourceType: 'opportunity',
+                            sourceId: state.opportunityId,
+                            negotiation: {
+                                purpose: 'inflight_consultation',
+                                recipientUserId: ownUser.id,
+                                recipientIntentId: ownIntentId,
+                                opportunityId: state.opportunityId,
+                                taskId: state.taskId,
+                                networkId: state.indexContext.networkId,
+                            },
+                            context: {
+                                negotiationId: state.taskId,
+                                counterpartyHint: NEGOTIATION_QUESTION_GENERIC_COUNTERPARTY,
+                                disclosureSubject: safeAskUser.disclosureSubject,
+                                ...(safeAskUser.draftQuestion && { draftQuestion: safeAskUser.draftQuestion }),
+                                indexContext: NEGOTIATION_QUESTION_GENERIC_NETWORK,
+                                ...(consultationPolicyReason && { consultationPolicyReason }),
+                                ...(userContext && { userContext }),
+                            },
+                        }).catch((error) => {
+                            turnLog.error('Failed to enqueue safe ask_user question; timeout recovery remains armed', {
+                                taskId: state.taskId,
+                                opportunityId: state.opportunityId,
+                                error,
+                            });
+                        });
+                    }
+                    else {
+                        turnLog.warn('Skipping unsafe or incomplete ask_user question generation', {
+                            taskId: state.taskId,
+                            opportunityId: state.opportunityId,
+                        });
+                    }
+                    turnLog.info('negotiation_ask_user_pause', {
+                        taskId: state.taskId,
+                        opportunityId: state.opportunityId,
+                        seat,
+                        askingUserId: ownUser.id,
+                        windowMs,
+                    });
+                    traceEmitter?.({ type: "agent_end", name: agentName, durationMs: Date.now() - agentStart, summary: "ask_user" });
+                    emitWide({
+                        type: 'negotiation_ask_user',
+                        opportunityId: state.opportunityId,
+                        negotiationConversationId: state.conversationId,
+                        turnIndex: state.turnCount,
+                        actor: isSource ? 'source' : 'candidate',
+                        questionGenerationSafe: Boolean(safeAskUser),
+                        windowMs,
+                    });
+                    return {
+                        messages: [{
+                                id: message.id,
+                                senderId: message.senderId,
+                                role: "agent",
+                                parts: message.parts,
+                                createdAt: message.createdAt,
+                            }],
+                        turnCount: state.turnCount + 1,
+                        lastTurn: turn,
+                        status: 'input_required',
+                        ...(deadlockShiftRecord && { deadlockShift: deadlockShiftRecord }),
+                    };
+                }
+                await database.updateTaskState(state.taskId, "working", undefined, state.continuationExecution);
+                if (state.opportunityId) {
+                    emitWide({
+                        type: "negotiation_turn",
+                        opportunityId: state.opportunityId,
+                        negotiationConversationId: state.conversationId,
+                        turnIndex: state.turnCount,
+                        actor: isSource ? "source" : "candidate",
+                        action: turn.action,
+                        ...(turn.assessment?.reasoning && { reasoning: turn.assessment.reasoning }),
+                        ...(turn.message && { message: turn.message }),
+                        ...(turn.assessment?.suggestedRoles && { suggestedRoles: turn.assessment.suggestedRoles }),
+                        durationMs: Date.now() - agentStart,
+                    });
+                }
+                return {
+                    messages: [{
+                            id: message.id,
+                            senderId: message.senderId,
+                            role: "agent",
+                            parts: message.parts,
+                            createdAt: message.createdAt,
+                        }],
+                    turnCount: state.turnCount + 1,
+                    currentSpeaker: (isSource ? "candidate" : "source"),
+                    lastTurn: turn,
+                    memoryBySide: { [ownSide]: ownMemory },
+                    // Record the in-task outreach so a later `withdraw` is legal (IND-564).
+                    ...(turn.action === 'outreach' && { outreachOpened: true }),
+                    ...(deadlockShiftRecord && { deadlockShift: deadlockShiftRecord }),
+                };
+            }
+            catch (err) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                turnLog.error("Agent invocation failed", { error: errMsg, stack: err instanceof Error ? err.stack : undefined, turnCount: state.turnCount });
+                traceEmitter?.({ type: "agent_end", name: agentName, durationMs: Date.now() - agentStart, summary: `error: ${errMsg}` });
+                const errorSeat = (state.currentSpeaker === 'source' ? state.sourceUser.id : state.candidateUser.id) === (state.initiatorUserId ?? state.sourceUser.id)
+                    ? 'initiator'
+                    : 'counterparty';
+                return {
+                    lastTurn: {
+                        action: rejectActionFor(state.protocolVersion ?? 'v1', errorSeat),
+                        assessment: { reasoning: `Agent error: ${errMsg}`, suggestedRoles: { ownUser: "peer", otherUser: "peer" } },
+                    },
+                    turnCount: state.turnCount + 1,
+                    error: `Turn failed: ${errMsg}`,
+                };
+            }
+        };
+        const evaluateNode = (state) => {
+            if (state.status === 'waiting_for_agent')
+                return "finalize";
+            if (state.status === 'input_required')
+                return "finalize";
+            if (state.error)
+                return "finalize";
+            if (!state.lastTurn)
+                return "finalize";
+            // Terminal actions: accept (v1+v2), reject (v1), withdraw/decline (v2)
+            if (isTerminalAction(state.lastTurn.action))
+                return "finalize";
+            // question routes same as counter — next turn
+            if ((state.maxTurns ?? 0) > 0 && state.turnCount >= state.maxTurns)
+                return "finalize";
+            return "turn";
+        };
+        const finalizeNode = async (state) => {
+            const traceEmitter = requestContext.getStore()?.traceEmitter;
+            const emitWide = (event) => traceEmitter?.(event);
+            const pauseReceipt = (outcome) => state.continuationExecution
+                ? {
+                    continuationReceipt: {
+                        priorTaskId: state.continuationExecution.taskId,
+                        settlementId: state.continuationExecution.settlementId,
+                        successorTaskId: state.continuationExecution.successorTaskId,
+                        fence: state.continuationExecution.fence,
+                        outcome,
+                    },
+                }
+                : undefined;
+            if (state.status === 'waiting_for_agent') {
+                if (state.opportunityId) {
+                    emitWide({
+                        type: "negotiation_outcome",
+                        opportunityId: state.opportunityId,
+                        outcome: "waiting_for_agent",
+                        turnCount: state.turnCount,
+                        isContinuation: state.isContinuation,
+                    });
+                }
+                return pauseReceipt('waiting_for_agent') ?? {};
+            }
+            // ask_user pause: no outcome, no completed state — the task stays
+            // input_required until the client answers or the window expires.
+            if (state.status === 'input_required') {
+                if (state.opportunityId) {
+                    emitWide({
+                        type: "negotiation_outcome",
+                        opportunityId: state.opportunityId,
+                        outcome: "input_required",
+                        turnCount: state.turnCount,
+                        isContinuation: state.isContinuation,
+                    });
+                }
+                return pauseReceipt('input_required') ?? {};
+            }
+            // Init can fail closed before an attempt owns a task. Such a rejection is
+            // not a completed negotiation and must not write through an empty task ID,
+            // create an artifact, or advance the opportunity lifecycle.
+            if (!state.taskId) {
+                finalizeLog.info('Skipping outcome persistence because no negotiation task was claimed', {
+                    opportunityId: state.opportunityId || undefined,
+                    error: state.error || undefined,
+                });
+                return {};
+            }
+            const history = turnsFromMessages(state.messages);
+            const lastTurn = state.lastTurn;
+            const hasOpportunity = lastTurn?.action === "accept";
+            // P2.2: the client's own outreach gate declined before any turn — the
+            // negotiation never happened from the counterparty's perspective.
+            // IND-564: an opening-move `withdraw` blocked before any message was
+            // persisted is the same quiet screen-out outcome (no in-task outreach to
+            // retract), reached from the turn node rather than the screen node.
+            const screenedOut = blocksNegotiationBeforeFirstTurn(state.screenDecision, state.turnCount) || state.firstTurnScreenedOut === true;
+            const atCap = !screenedOut && (state.maxTurns ?? 0) > 0 && state.turnCount >= state.maxTurns && !isTerminalAction(lastTurn?.action);
+            let agreedRoles = [];
+            if (hasOpportunity && history.length >= 2) {
+                const acceptTurn = history[history.length - 1];
+                const precedingTurn = history[history.length - 2];
+                const accepterIsSource = state.currentSpeaker === "candidate";
+                const [sourceRole, candidateRole] = accepterIsSource
+                    ? [acceptTurn.assessment.suggestedRoles.ownUser, precedingTurn.assessment.suggestedRoles.ownUser]
+                    : [precedingTurn.assessment.suggestedRoles.ownUser, acceptTurn.assessment.suggestedRoles.ownUser];
+                agreedRoles = [
+                    { userId: state.sourceUser.id, role: sourceRole },
+                    { userId: state.candidateUser.id, role: candidateRole },
+                ];
+            }
+            const outcome = {
+                hasOpportunity,
+                agreedRoles,
+                reasoning: screenedOut
+                    ? (state.screenDecision?.reasoning ?? lastTurn?.assessment?.reasoning ?? "")
+                    : (lastTurn?.assessment.reasoning ?? ""),
+                turnCount: state.turnCount,
+                ...(screenedOut
+                    ? { reason: "screened_out" }
+                    : atCap
+                        ? { reason: "turn_cap" }
+                        : {}),
+            };
+            try {
+                await database.updateTaskState(state.taskId, "completed", undefined, state.continuationExecution);
+                await database.createArtifact({
+                    taskId: state.taskId,
+                    name: "negotiation-outcome",
+                    parts: [{ kind: "data", data: outcome }],
+                    metadata: {
+                        hasOpportunity,
+                        turnCount: state.turnCount,
+                        ...(state.continuationExecution ? {
+                            continuationOutcome: hasOpportunity
+                                ? 'accepted'
+                                : (screenedOut || isRejectLikeAction(lastTurn?.action)) ? 'rejected' : 'stalled',
+                        } : {}),
+                    },
+                    ...(state.continuationExecution ? { continuationExecution: state.continuationExecution } : {}),
+                });
+                finalizeLog.info('Session complete', {
+                    conversationId: state.conversationId,
+                    taskId: state.taskId,
+                    isContinuation: state.isContinuation,
+                    turnsAdded: state.turnCount,
+                    priorTurnCount: state.priorTurnCount,
+                    outcome: hasOpportunity ? 'accepted' : screenedOut ? 'screened_out' : (atCap ? 'turn_cap' : (lastTurn?.action ?? 'unknown')),
+                    opportunityId: state.opportunityId || undefined,
+                });
+                if (state.opportunityId) {
+                    // screened_out → 'rejected': quiet terminal status (hidden from
+                    // default lists), never 'stalled' — with zero turns the generic
+                    // mapping would misfile the client's own gate decision.
+                    const nextStatus = lastTurn?.action === 'accept'
+                        ? 'pending'
+                        : (screenedOut || isRejectLikeAction(lastTurn?.action))
+                            ? 'rejected'
+                            : 'stalled';
+                    await database.updateOpportunityStatus(state.opportunityId, nextStatus, undefined, state.continuationExecution).catch((err) => {
+                        finalizeLog.error("Failed to update opportunity status", { opportunityId: state.opportunityId, nextStatus, error: err });
+                    });
+                }
+            }
+            catch (err) {
+                finalizeLog.error("Failed to persist outcome", { error: err });
+            }
+            if (state.opportunityId) {
+                const emittedOutcome = hasOpportunity
+                    ? "accepted"
+                    : screenedOut
+                        ? "screened_out"
+                        : atCap
+                            ? "turn_cap"
+                            : state.error && /timeout/i.test(state.error)
+                                ? "timed_out"
+                                : "rejected_stalled";
+                emitWide({
+                    type: "negotiation_outcome",
+                    opportunityId: state.opportunityId,
+                    outcome: emittedOutcome,
+                    turnCount: state.turnCount,
+                    isContinuation: state.isContinuation,
+                    turnsAdded: state.turnCount,
+                    priorTurnCount: state.priorTurnCount,
+                    ...(outcome.reasoning && { reasoning: outcome.reasoning }),
+                    ...(hasOpportunity && agreedRoles.length >= 2 && {
+                        agreedRoles: {
+                            ownUser: agreedRoles[0]?.role,
+                            otherUser: agreedRoles[1]?.role,
+                        },
+                    }),
+                });
+            }
+            if (state.consultationPolicyReason) {
+                // Stable, content-free terminal funnel telemetry. This executes only
+                // after a fenced continuation has reached its terminal outcome.
+                finalizeLog.info('negotiation_consultation_policy', {
+                    stage: 'terminal_outcome',
+                    reason: state.consultationPolicyReason,
+                    outcome: hasOpportunity ? 'accepted' : (screenedOut || isRejectLikeAction(lastTurn?.action)) ? 'rejected' : 'stalled',
+                });
+                emitWide({
+                    type: 'negotiation_consultation_policy',
+                    stage: 'terminal_outcome',
+                    reason: state.consultationPolicyReason,
+                    outcome: hasOpportunity ? 'accepted' : (screenedOut || isRejectLikeAction(lastTurn?.action)) ? 'rejected' : 'stalled',
+                });
+            }
+            // Enqueue post-negotiation reflection (P5.2 memory write path) — fire
+            // and forget: a reflection failure must never affect the outcome. Only
+            // sessions that actually exchanged turns teach anything; init/turn
+            // errors with turnCount 0 are skipped.
+            if (reflectEnqueue && state.turnCount > 0 && !state.continuationExecution) {
+                reflectEnqueue({
+                    negotiationId: state.taskId,
+                    conversationId: state.conversationId,
+                    ...(state.opportunityId && { opportunityId: state.opportunityId }),
+                    sourceUser: {
+                        id: state.sourceUser.id,
+                        ...(state.sourceUser.profile.name && { name: state.sourceUser.profile.name }),
+                        ...(state.sourceUser.profile.bio && { bio: state.sourceUser.profile.bio }),
+                    },
+                    candidateUser: {
+                        id: state.candidateUser.id,
+                        ...(state.candidateUser.profile.name && { name: state.candidateUser.profile.name }),
+                        ...(state.candidateUser.profile.bio && { bio: state.candidateUser.profile.bio }),
+                    },
+                    initiatorUserId: state.initiatorUserId ?? state.sourceUser.id,
+                    outcome: { hasOpportunity, reasoning: outcome.reasoning, turnCount: state.turnCount },
+                }).catch((err) => finalizeLog.error('Failed to enqueue negotiation reflection', {
+                    taskId: state.taskId,
+                    error: err,
+                }));
+            }
+            // Enqueue question generation for stalled/capped negotiations (not accepted or explicitly rejected).
+            // Require turnCount > 0 so early init/turn errors don't enqueue with empty context.
+            if (!hasOpportunity && !isRejectLikeAction(lastTurn?.action) && state.turnCount > 0 && state.opportunityId && state.sourceIntentId && state.indexContext.networkId && questionerEnqueue && !state.continuationExecution) {
+                const stallReason = atCap
+                    ? 'turn_cap'
+                    : (state.error && /timeout/i.test(state.error))
+                        ? 'timeout'
+                        : 'stalled';
+                const userContext = (await database.getUserContext(state.sourceUser.id, null))?.text ?? '';
+                const sourceIntent = state.sourceUser.intents.find((intent) => intent.id === state.sourceIntentId);
+                questionerEnqueue({
+                    mode: 'negotiation',
+                    purpose: 'stalled_followup',
+                    userId: state.sourceUser.id,
+                    sourceType: 'opportunity',
+                    sourceId: state.opportunityId,
+                    negotiation: {
+                        purpose: 'stalled_followup',
+                        recipientUserId: state.sourceUser.id,
+                        recipientIntentId: state.sourceIntentId,
+                        opportunityId: state.opportunityId,
+                        taskId: state.taskId,
+                        networkId: state.indexContext.networkId,
+                    },
+                    context: {
+                        negotiationId: state.taskId,
+                        counterpartyHint: NEGOTIATION_QUESTION_GENERIC_COUNTERPARTY,
+                        indexContext: NEGOTIATION_QUESTION_GENERIC_NETWORK,
+                        outcomeReason: stallReason,
+                        recipientIntent: sourceIntent
+                            ? `${sourceIntent.title}: ${sourceIntent.description}`
+                            : 'the signal attached to this match',
+                        userContext,
+                    },
+                }).catch((err) => finalizeLog.error('Failed to enqueue negotiation question generation', {
+                    opportunityId: state.opportunityId,
+                    error: err,
+                }));
+            }
+            const terminalReceipt = state.continuationExecution
+                ? {
+                    continuationReceipt: {
+                        priorTaskId: state.continuationExecution.taskId,
+                        settlementId: state.continuationExecution.settlementId,
+                        successorTaskId: state.continuationExecution.successorTaskId,
+                        fence: state.continuationExecution.fence,
+                        outcome: hasOpportunity
+                            ? 'accepted'
+                            : (screenedOut || isRejectLikeAction(lastTurn?.action)) ? 'rejected' : 'stalled',
+                    },
+                }
+                : undefined;
+            return { outcome, status: 'completed', ...terminalReceipt };
+        };
+        const workflow = new StateGraph(NegotiationGraphState)
+            .addNode("init", initNode)
+            .addNode("screen", screenNode)
+            .addNode("turn", turnNode)
+            .addNode("finalize", finalizeNode)
+            .addConditionalEdges("turn", evaluateNode, {
+            turn: "turn",
+            finalize: "finalize",
+        })
+            .addConditionalEdges("init", (state) => {
+            if (state.error)
+                return "finalize";
+            // Screen gate: fresh negotiations only (continuations already passed
+            // the gate when the dialogue opened); off disables the node entirely.
+            // IND-563: regular continuations (new opportunity, existing dm_pair)
+            // also run through the screen gate so stale matches are caught before
+            // re-engaging the counterparty. Exact ask_user resumes
+            // (continuationExecution) are mid-flight and must never be re-screened.
+            if (configuredScreenMode() !== "off" && !state.continuationExecution)
+                return "screen";
+            return "turn";
+        }, { screen: "screen", turn: "turn", finalize: "finalize" })
+            // P2.2: enforce-mode pass → finalize (screened_out); everything else → turn.
+            .addConditionalEdges("screen", (state) => blocksNegotiationBeforeFirstTurn(state.screenDecision, state.turnCount) ? "finalize" : "turn", { turn: "turn", finalize: "finalize" })
+            .addEdge("__start__", "init")
+            .addEdge("finalize", "__end__");
+        return workflow.compile();
+    }
+}
+/**
+ * Runs bilateral negotiation for each candidate in parallel.
+ * @returns Only candidates that produced an opportunity
+ */
+export async function negotiateCandidates(negotiationGraph, sourceUser, candidates, indexContext, opts) {
+    const { maxTurns, traceEmitter, indexContextOverrides, timeoutMs, onCandidateResolved, trigger, initiatorUserId, resumeFromTaskId, continuationSettlementId, continuationExecution, } = opts ?? {};
+    // Local helper to emit events whose shape is wider than the declared
+    // `TraceEmitter` union (mirrors the cast used in chat.agent at the relay sink
+    // and inside turn/finalize nodes above).
+    const emitWide = (event) => traceEmitter?.(event);
+    const results = await Promise.all(candidates.map(async (candidate) => {
+        const start = Date.now();
+        if (candidate.opportunityId) {
+            const candidateName = candidate.candidateUser?.profile?.name;
+            emitWide({
+                type: "negotiation_session_start",
+                opportunityId: candidate.opportunityId,
+                negotiationConversationId: "", // filled in on session_end
+                sourceUserId: sourceUser.id,
+                candidateUserId: candidate.userId,
+                initiatorUserId: initiatorUserId ?? sourceUser.id,
+                ...(candidateName && { candidateName }),
+                trigger: trigger ?? "ambient",
+                startedAt: start,
+            });
+        }
+        traceEmitter?.({ type: "agent_start", name: "Negotiating candidate" });
+        try {
+            const candidateIndexContext = candidate.networkId
+                ? { networkId: candidate.networkId, prompt: indexContextOverrides?.get(candidate.networkId) ?? '' }
+                : indexContext;
+            const result = await invokeWithAbortSignal(negotiationGraph, {
+                sourceUser,
+                candidateUser: candidate.candidateUser,
+                ...(candidate.sourceIntentId && { sourceIntentId: candidate.sourceIntentId }),
+                ...(candidate.candidateIntentId && { candidateIntentId: candidate.candidateIntentId }),
+                indexContext: candidateIndexContext,
+                seedAssessment: {
+                    reasoning: candidate.reasoning,
+                    valencyRole: candidate.valencyRole,
+                },
+                ...(candidate.discoveryQuery && { discoveryQuery: candidate.discoveryQuery }),
+                ...(candidate.opportunityId && { opportunityId: candidate.opportunityId }),
+                ...(candidate.opportunityStatus && { opportunityStatus: candidate.opportunityStatus }),
+                ...(candidate.opportunityUpdatedAt && { opportunityUpdatedAt: candidate.opportunityUpdatedAt }),
+                ...(initiatorUserId && { initiatorUserId }),
+                ...(resumeFromTaskId && continuationSettlementId && continuationExecution ? {
+                    resumeFromTaskId,
+                    continuationSettlementId,
+                    continuationExecution,
+                } : {}),
+                ...(maxTurns !== undefined && { maxTurns }),
+                ...(timeoutMs !== undefined && { timeoutMs }),
+            });
+            const durationMs = Date.now() - start;
+            const outcome = result.outcome;
+            const hasOpportunity = outcome?.hasOpportunity === true;
+            const isContinuation = result.isContinuation ?? false;
+            const priorTurnCount = result.priorTurnCount ?? 0;
+            const turnFlow = (result.messages ?? [])
+                .map((m) => {
+                const dataPart = m.parts?.find((p) => p.kind === "data");
+                if (!dataPart?.data)
+                    return null;
+                const turn = dataPart.data;
+                return turn.action ?? "unknown";
+            })
+                .filter(Boolean)
+                .join(" → ");
+            const statusTag = hasOpportunity ? "✓ opportunity" : "✗ rejected";
+            traceEmitter?.({ type: "agent_end", name: "Negotiating candidate", durationMs, summary: `${candidate.userId}: ${turnFlow} ${statusTag}` });
+            if (candidate.opportunityId) {
+                emitWide({
+                    type: "negotiation_session_end",
+                    opportunityId: candidate.opportunityId,
+                    negotiationConversationId: result.conversationId ?? "",
+                    durationMs: Date.now() - start,
+                    isContinuation,
+                    turnsAdded: outcome?.turnCount ?? 0,
+                    priorTurnCount,
+                });
+            }
+            const accepted = hasOpportunity && outcome
+                ? {
+                    userId: candidate.userId,
+                    agreedRoles: outcome.agreedRoles,
+                    reasoning: outcome.reasoning,
+                    turnCount: outcome.turnCount,
+                }
+                : null;
+            if (onCandidateResolved) {
+                const turnHistory = turnsFromMessages(result.messages ?? []);
+                const resolvedOutcome = result.outcome ?? {
+                    hasOpportunity: false,
+                    agreedRoles: [],
+                    reasoning: "no outcome returned by negotiation graph",
+                    turnCount: turnHistory.length,
+                };
+                try {
+                    await onCandidateResolved({
+                        candidate,
+                        accepted,
+                        turns: turnHistory,
+                        outcome: resolvedOutcome,
+                        ...(result.continuationReceipt ? { continuationReceipt: result.continuationReceipt } : {}),
+                    });
+                }
+                catch (hookErr) {
+                    // Hook failures must not sink the candidate result — the aggregate
+                    // return is still useful, and the orchestrator branch logs its own
+                    // failures inline.
+                    negotiateCandidatesLog.error("onCandidateResolved hook threw", {
+                        candidateUserId: candidate.userId,
+                        error: hookErr,
+                    });
+                }
+            }
+            return accepted;
+        }
+        catch (err) {
+            const durationMs = Date.now() - start;
+            traceEmitter?.({ type: "agent_end", name: "Negotiating candidate", durationMs, summary: `${candidate.userId}: error` });
+            if (candidate.opportunityId) {
+                emitWide({
+                    type: "negotiation_session_end",
+                    opportunityId: candidate.opportunityId,
+                    negotiationConversationId: "",
+                    durationMs: Date.now() - start,
+                });
+            }
+            negotiateCandidatesLog.error("Negotiation failed", { candidateUserId: candidate.userId, error: err });
+            if (onCandidateResolved) {
+                try {
+                    await onCandidateResolved({
+                        candidate,
+                        accepted: null,
+                        turns: [],
+                        outcome: {
+                            hasOpportunity: false,
+                            agreedRoles: [],
+                            reasoning: err instanceof Error ? err.message : String(err),
+                            turnCount: 0,
+                        },
+                    });
+                }
+                catch {
+                    // ignore hook failure on error path
+                }
+            }
+            return null;
+        }
+    }));
+    return results.filter((r) => r !== null);
+}