@indexnetwork/protocol 21.1.0-rc.491.1 → 21.1.0-rc.492.1

package/dist/negotiations/negotiation.agent.d.ts

@@ -103,6 +103,7 @@ export interface IndexNegotiatorConfig {
      */
     turnTimeoutMs?: number;
 }
+export declare function resolveTurnTimeoutMs(override?: number): number;
 /**
  * Unified system negotiation agent that advocates for its user.
  * Adapts behavior based on turn position (first turn = propose, subsequent = respond).

package/dist/negotiations/negotiation.agent.js

@@ -113,7 +113,7 @@ const DEFAULT_TURN_TIMEOUT_MS = 15000;
 function isValidTimeoutMs(n) {
     return Number.isFinite(n) && n > 0 && n <= Number.MAX_SAFE_INTEGER;
 }
-function resolveTurnTimeoutMs(override) {
+export function resolveTurnTimeoutMs(override) {
     if (typeof override === "number" && isValidTimeoutMs(override))
         return override;
     const envValue = process.env.NEGOTIATOR_TURN_TIMEOUT_MS;

package/dist/negotiations/negotiation.graph.finalize.js

@@ -2,11 +2,12 @@
  * Negotiation graph, stage 4: persist the outcome and fan out follow-ups.
  */
 import { requestContext } from "../shared/observability/request-context.js";
-import { isRejectLikeAction, isTerminalAction } from "./negotiation.protocol.js";
+import { isRejectLikeAction, isTerminalAction, negotiationAskRoundsCap } from "./negotiation.protocol.js";
 import { blocksNegotiationBeforeFirstTurn } from "./negotiation.screen.js";
-import { NEGOTIATION_QUESTION_GENERIC_COUNTERPARTY, NEGOTIATION_QUESTION_GENERIC_NETWORK } from './negotiation.question-safety.js';
+import { NEGOTIATION_QUESTION_GENERIC_COUNTERPARTY, NEGOTIATION_QUESTION_GENERIC_NETWORK, isSafeAuthoredNegotiationQuestion } from './negotiation.question-safety.js';
+import { NEGOTIATION_PARK_REASONING } from './negotiation.stall-gap.js';
 import { isNegotiationTurnCapReached } from "./negotiation.turn-cap.js";
-import { finalizeLog, turnsFromMessages } from "./negotiation.graph.shared.js";
+import { countNegotiationAskRounds, finalizeLog, retrieveClientDm, turnsFromMessages } from "./negotiation.graph.shared.js";
 export async function finalizeNode(state, deps) {
     const traceEmitter = requestContext.getStore()?.traceEmitter;
     const emitWide = (event) => traceEmitter?.(event);
@@ -113,6 +114,131 @@ export async function finalizeNode(state, deps) {
                 ? { reason: "turn_cap" }
                 : {}),
     };
+    // Unconcluded end: no opportunity, no explicit reject, and turns actually
+    // happened — turn cap, timeout, or a plain stall. Feeds both the post-stall
+    // park below and the legacy questioner enqueue further down.
+    const endedUnconcluded = !hasOpportunity && !screenedOut && !isRejectLikeAction(lastTurn?.action) && state.turnCount > 0;
+    const stallReason = atCap
+        ? 'turn_cap'
+        : (state.error && /timeout/i.test(state.error))
+            ? 'timeout'
+            : 'stalled';
+    // ─── Post-stall park (conversational-questions plan) ──────────────────
+    // Instead of ending silently, an unconcluded negotiation parks carrying
+    // the ONE question that would let a retry conclude — authored by the
+    // negotiator from this negotiation's transcript and the signal's client
+    // DM, exactly the grounding the mid-flight consult uses. The gap is
+    // persisted as an `ask_user` message in the negotiation's own record: the
+    // parked negotiation is the only durable record of the information need,
+    // the same substrate the per-side ration reads, and an `ask_user` last
+    // message keeps the floor with the asking side on retry.
+    //
+    // Bounded per negotiation: past the ask-rounds cap the negotiation stalls
+    // TERMINALLY — no authoring call, no park — so two agents cannot
+    // ping-pong their humans indefinitely. Runs on continuations too (a
+    // resumed negotiation may park again); the cap is what bounds the loop.
+    //
+    // Every failure — authoring, safety gate, persistence — degrades to
+    // today's terminal stall. A park is additive state, never a new way for
+    // finalize to fail.
+    if (endedUnconcluded
+        && deps.stallGapAuthor
+        && state.opportunityId
+        && state.sourceIntentId
+        && state.indexContext.networkId) {
+        const askRounds = countNegotiationAskRounds(state.messages);
+        const askRoundsCap = negotiationAskRoundsCap();
+        if (askRounds >= askRoundsCap) {
+            finalizeLog.info('negotiation_ask_cap_terminal', {
+                taskId: state.taskId,
+                opportunityId: state.opportunityId,
+                askRounds,
+                askRoundsCap,
+                stallReason,
+            });
+            emitWide({
+                type: 'negotiation_ask_cap_terminal',
+                opportunityId: state.opportunityId,
+                askRounds,
+                askRoundsCap,
+            });
+        }
+        else {
+            try {
+                const clientDm = await retrieveClientDm(deps, state.sourceUser.id, state.sourceIntentId);
+                const parkIntent = state.sourceUser.intents.find((intent) => intent.id === state.sourceIntentId);
+                const gap = await deps.stallGapAuthor.author({
+                    userName: state.sourceUser.profile.name ?? 'your user',
+                    signal: parkIntent
+                        ? { title: parkIntent.title, description: parkIntent.description }
+                        : { title: 'Signal', description: 'the signal attached to this match' },
+                    seedReasoning: state.seedAssessment.reasoning,
+                    history,
+                    stallReason,
+                    ...(clientDm.length > 0 && { clientDm }),
+                });
+                // Same identifier-aware gate as the mid-flight authored question, with
+                // the same inputs in hand: the counterparty's name and the evaluator's
+                // reasoning. An unsafe question never parks — there is no enum-only
+                // downgrade here because a park without its gap records nothing.
+                const counterpartyName = state.candidateUser.profile?.name?.trim();
+                const seedReasoning = state.seedAssessment?.reasoning?.trim();
+                const safeGap = gap && isSafeAuthoredNegotiationQuestion(gap.question, {
+                    ...(counterpartyName ? { forbiddenIdentifiers: [counterpartyName] } : {}),
+                    ...(seedReasoning ? { forbiddenSourceText: [seedReasoning] } : {}),
+                });
+                if (safeGap) {
+                    const parkTurn = {
+                        action: 'ask_user',
+                        assessment: {
+                            reasoning: NEGOTIATION_PARK_REASONING,
+                            suggestedRoles: lastTurn?.assessment.suggestedRoles ?? { ownUser: 'peer', otherUser: 'peer' },
+                        },
+                        message: null,
+                        askUser: { reason: gap.reason, question: gap.question },
+                    };
+                    await deps.database.createMessage({
+                        conversationId: state.conversationId,
+                        senderId: `agent:${state.sourceUser.id}`,
+                        role: 'agent',
+                        parts: [{ kind: 'data', data: parkTurn }],
+                        taskId: state.taskId,
+                        ...(state.continuationExecution ? { continuationExecution: state.continuationExecution } : {}),
+                    });
+                    finalizeLog.info('negotiation_parked', {
+                        taskId: state.taskId,
+                        opportunityId: state.opportunityId,
+                        recipientUserId: state.sourceUser.id,
+                        recipientIntentId: state.sourceIntentId,
+                        askRounds: askRounds + 1,
+                        askRoundsCap,
+                        stallReason,
+                    });
+                    emitWide({
+                        type: 'negotiation_parked',
+                        opportunityId: state.opportunityId,
+                        negotiationConversationId: state.conversationId,
+                        askRounds: askRounds + 1,
+                        askRoundsCap,
+                        stallReason,
+                    });
+                }
+                else if (gap) {
+                    finalizeLog.warn('Dropping unsafe post-stall gap question; negotiation stalls without a park', {
+                        taskId: state.taskId,
+                        opportunityId: state.opportunityId,
+                    });
+                }
+            }
+            catch (err) {
+                finalizeLog.error('Failed to park stalled negotiation with its gap', {
+                    taskId: state.taskId,
+                    opportunityId: state.opportunityId,
+                    error: err,
+                });
+            }
+        }
+    }
     try {
         await deps.database.updateTaskState(state.taskId, "completed", undefined, state.continuationExecution);
         await deps.database.createArtifact({
@@ -226,12 +352,9 @@ export async function finalizeNode(state, deps) {
     }
     // 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 && deps.questionerEnqueue && !state.continuationExecution) {
-        const stallReason = atCap
-            ? 'turn_cap'
-            : (state.error && /timeout/i.test(state.error))
-                ? 'timeout'
-                : 'stalled';
+    // Kept alongside the post-stall park above until the conversational-questions
+    // delivery lane retires the blind questioner path.
+    if (endedUnconcluded && state.opportunityId && state.sourceIntentId && state.indexContext.networkId && deps.questionerEnqueue && !state.continuationExecution) {
         const userContext = (await deps.database.getUserContext(state.sourceUser.id, null))?.text ?? '';
         const sourceIntent = state.sourceUser.intents.find((intent) => intent.id === state.sourceIntentId);
         deps.questionerEnqueue({

package/dist/negotiations/negotiation.graph.js

@@ -8,6 +8,7 @@
 import { StateGraph } from "@langchain/langgraph";
 import { NegotiationGraphState } from "./negotiation.state.js";
 import { IndexNegotiator } from "./negotiation.agent.js";
+import { NegotiationStallGapAuthor } from "./negotiation.stall-gap.js";
 import { blocksNegotiationBeforeFirstTurn, NegotiationScreener } from "./negotiation.screen.js";
 import { configuredScreenMode } from "./negotiation.screen.contracts.js";
 import { isTerminalAction } from "./negotiation.protocol.js";
@@ -32,6 +33,7 @@ export class NegotiationGraphFactory {
             memoryRetrieve,
             clientDmRetrieve,
             systemAgent: new IndexNegotiator(),
+            stallGapAuthor: new NegotiationStallGapAuthor(),
             screener: new NegotiationScreener(),
         };
     }

package/dist/negotiations/negotiation.graph.shared.d.ts

@@ -16,6 +16,7 @@ import type { QuestionerEnqueueFn } from "../questions/question.module.js";
 import type { ReflectEnqueueFn } from "./negotiation.reflect.js";
 import type { NegotiatorMemoryEntry, NegotiatorMemoryRetrieveFn, NegotiatorMemoryScope } from "./negotiation.memory.js";
 import type { NegotiatorClientDmMessage, NegotiatorClientDmRetrieveFn } from "./negotiation.client-dm.js";
+import type { NegotiationStallGapAuthor } from "./negotiation.stall-gap.js";
 import { type AttributedPriorDialogue, type TaskAttribution } from './negotiation.attribution.js';
 /** The graph's channel state, as every node sees it. */
 export type NegotiationState = typeof NegotiationGraphState.State;
@@ -35,6 +36,8 @@ export interface NegotiationGraphDeps {
     clientDmRetrieve?: NegotiatorClientDmRetrieveFn;
     /** In-process negotiator used when no personal agent answers. */
     systemAgent: IndexNegotiator;
+    /** Authors the post-stall gap question at finalize (park-on-stall). */
+    stallGapAuthor?: NegotiationStallGapAuthor;
     /** Outreach gate for fresh negotiations. */
     screener: NegotiationScreener;
 }
@@ -60,6 +63,20 @@ export declare function hasPriorAskUser(messages: Array<{
     senderId: string;
     parts: unknown[];
 }>, userId: string): boolean;
+/**
+ * How many ask rounds this negotiation has already spent, BOTH sides combined.
+ * A round is one persisted `ask_user` park — a mid-flight client consultation
+ * or a post-stall park — each of which suspends the negotiation on a human
+ * answer. Same substrate as {@link hasPriorAskUser} (the negotiation's own
+ * message record, spanning all of its sessions), read negotiation-wide rather
+ * than per side: the cap this feeds bounds the park → answer → resume loop for
+ * the negotiation as a whole, so two agents cannot ping-pong their humans
+ * indefinitely.
+ */
+export declare function countNegotiationAskRounds(messages: Array<{
+    senderId: string;
+    parts: unknown[];
+}>): number;
 /**
  * P5.3 memory retrieval — never throws, never blocks a negotiation. The
  * injected fn already resolves [] when NEGOTIATOR_MEMORY_INJECT is off;

package/dist/negotiations/negotiation.graph.shared.js

@@ -23,6 +23,15 @@ export function turnsFromMessages(messages) {
     })
         .filter(Boolean);
 }
+/** Sender ids of every persisted `ask_user` park in this negotiation's messages. */
+function askUserSenderIds(messages) {
+    return messages
+        .filter((m) => {
+        const dataPart = m.parts.find((p) => p.kind === "data");
+        return dataPart?.data?.action === "ask_user";
+    })
+        .map((m) => m.senderId);
+}
 /**
  * Whether `userId`'s side has already spent its one `ask_user` client
  * consultation in THIS negotiation (P3.2 rationing: max one per negotiation per
@@ -32,13 +41,20 @@ export function turnsFromMessages(messages) {
  * counterparty does not.
  */
 export 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";
-    });
+    return askUserSenderIds(messages).includes(`agent:${userId}`);
+}
+/**
+ * How many ask rounds this negotiation has already spent, BOTH sides combined.
+ * A round is one persisted `ask_user` park — a mid-flight client consultation
+ * or a post-stall park — each of which suspends the negotiation on a human
+ * answer. Same substrate as {@link hasPriorAskUser} (the negotiation's own
+ * message record, spanning all of its sessions), read negotiation-wide rather
+ * than per side: the cap this feeds bounds the park → answer → resume loop for
+ * the negotiation as a whole, so two agents cannot ping-pong their humans
+ * indefinitely.
+ */
+export function countNegotiationAskRounds(messages) {
+    return askUserSenderIds(messages).length;
 }
 /**
  * P5.3 memory retrieval — never throws, never blocks a negotiation. The

package/dist/negotiations/negotiation.graph.turn.js

@@ -2,13 +2,13 @@
  * Negotiation graph, stage 3: one negotiator turn.
  */
 import { requestContext } from "../shared/observability/request-context.js";
-import { allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, fallbackActionFor, rejectActionFor } from "./negotiation.protocol.js";
+import { allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, fallbackActionFor, negotiationAskRoundsCap, rejectActionFor } from "./negotiation.protocol.js";
 import { assessConsultationEligibility, consultationPromptFor, negotiationConsultationPolicyMode } from "./negotiation.consultation-policy.js";
 import { blocksNegotiationBeforeFirstTurn } from "./negotiation.screen.js";
 import { assessDeadlock, configuredDeadlockShiftEnabled, configuredDeadlockThreshold } from "./negotiation.deadlock.js";
 import { NEGOTIATION_QUESTION_GENERIC_COUNTERPARTY, NEGOTIATION_QUESTION_GENERIC_NETWORK, isSafeAuthoredNegotiationQuestion, negotiationQuestionSettlementId } from './negotiation.question-safety.js';
 import { isNegotiationTurnCapReached } from "./negotiation.turn-cap.js";
-import { buildAttributedDialogue, hasPriorAskUser, memoryQueryText, retrieveClientDm, retrieveMemory, turnLog, turnsFromMessages } from "./negotiation.graph.shared.js";
+import { buildAttributedDialogue, countNegotiationAskRounds, hasPriorAskUser, memoryQueryText, retrieveClientDm, retrieveMemory, turnLog, turnsFromMessages } from "./negotiation.graph.shared.js";
 export async function turnNode(state, deps) {
     const traceEmitter = requestContext.getStore()?.traceEmitter;
     // Local helper to emit events whose shape is wider than the declared
@@ -38,6 +38,12 @@ export async function turnNode(state, deps) {
         // 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.
+        //
+        // The negotiation-wide ask-rounds cap reads the same message substrate
+        // as the per-side ration. It cannot bind on mid-flight consults alone
+        // (one per side < default cap); it exists so post-stall parks — which
+        // also persist `ask_user` messages — count against the same budget,
+        // and a negotiation near its cap cannot spend a further round here.
         const policyMode = negotiationConsultationPolicyMode();
         const askUserAvailable = version === 'v2'
             && !isFinalTurn
@@ -48,7 +54,8 @@ export async function turnNode(state, deps) {
             && !!ownIntentId
             && !!state.indexContext.networkId
             && !(state.turnCount === 0 && !state.isContinuation)
-            && !hasPriorAskUser(state.messages, ownUser.id);
+            && !hasPriorAskUser(state.messages, ownUser.id)
+            && countNegotiationAskRounds(state.messages) < negotiationAskRoundsCap();
         // ─── 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,

package/dist/negotiations/negotiation.module.d.ts

@@ -13,7 +13,10 @@ export { NegotiationScreener } from "./negotiation.screen.js";
 export type { ChatReflectionInput, DistilledMemory, NegotiationReflectionInput, NegotiationReflectJobData, ReflectEnqueueFn, ReflectionTranscriptEntry, } from "./negotiation.reflect.js";
 export type { NegotiationCandidate, OnNegotiationResolved } from "./negotiation.graph.js";
 export type { NegotiationDigest } from "./insight.generator.js";
-export { ASK_USER_LOCK_SLACK_MS, allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, isRejectLikeAction, isTerminalAction, readProtocolVersion, resolveSeat, seatViolationMessage, } from "./negotiation.protocol.js";
+export { ASK_USER_LOCK_SLACK_MS, DEFAULT_NEGOTIATION_ASK_ROUNDS_CAP, allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, isRejectLikeAction, isTerminalAction, negotiationAskRoundsCap, readProtocolVersion, resolveSeat, seatViolationMessage, } from "./negotiation.protocol.js";
+export { countNegotiationAskRounds } from "./negotiation.graph.shared.js";
+export { NEGOTIATION_PARK_REASONING, NegotiationStallGapAuthor } from "./negotiation.stall-gap.js";
+export type { NegotiationStallGap, NegotiationStallReason, StallGapAuthorInput } from "./negotiation.stall-gap.js";
 export { HERMES_OWNER_DIRECTIVE, HERMES_SHARED_MESSAGE_TEMPLATES, HermesNegotiationActionSchema, HermesNegotiationResponseSchema, HermesOwnerDirectiveSchema, HermesRoleAlignmentSchema, allowedHermesActionsFor, buildHermesNegotiationTurn, } from "./negotiation.hermes-contract.js";
 export { DEFAULT_NEGOTIATION_MAX_TURNS, isNegotiationTurnCapReached } from "./negotiation.turn-cap.js";
 export { expectedNegotiationSpeaker } from "./negotiation.expected-speaker.js";

package/dist/negotiations/negotiation.module.js

@@ -10,7 +10,9 @@ export { negotiateCandidates, NegotiationGraphFactory } from "./negotiation.grap
 export { NegotiationInsightsGenerator } from "./insight.generator.js";
 export { NegotiationReflector } from "./negotiation.reflect.js";
 export { NegotiationScreener } from "./negotiation.screen.js";
-export { ASK_USER_LOCK_SLACK_MS, allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, isRejectLikeAction, isTerminalAction, readProtocolVersion, resolveSeat, seatViolationMessage, } from "./negotiation.protocol.js";
+export { ASK_USER_LOCK_SLACK_MS, DEFAULT_NEGOTIATION_ASK_ROUNDS_CAP, allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, isRejectLikeAction, isTerminalAction, negotiationAskRoundsCap, readProtocolVersion, resolveSeat, seatViolationMessage, } from "./negotiation.protocol.js";
+export { countNegotiationAskRounds } from "./negotiation.graph.shared.js";
+export { NEGOTIATION_PARK_REASONING, NegotiationStallGapAuthor } from "./negotiation.stall-gap.js";
 export { HERMES_OWNER_DIRECTIVE, HERMES_SHARED_MESSAGE_TEMPLATES, HermesNegotiationActionSchema, HermesNegotiationResponseSchema, HermesOwnerDirectiveSchema, HermesRoleAlignmentSchema, allowedHermesActionsFor, buildHermesNegotiationTurn, } from "./negotiation.hermes-contract.js";
 export { DEFAULT_NEGOTIATION_MAX_TURNS, isNegotiationTurnCapReached } from "./negotiation.turn-cap.js";
 export { expectedNegotiationSpeaker } from "./negotiation.expected-speaker.js";

package/dist/negotiations/negotiation.protocol.d.ts

@@ -972,6 +972,20 @@ export declare function configuredProtocolVersion(): NegotiationProtocolVersion;
  * the same single switch.
  */
 export declare function configuredAskUserEnabled(): boolean;
+/**
+ * Default per-negotiation ask cap: total client-consultation rounds (mid-flight
+ * `ask_user` pauses and post-stall parks, both sides combined) before the
+ * negotiation stalls terminally instead of parking again. Three admits one
+ * post-stall park even after each side has spent its one mid-flight consult.
+ */
+export declare const DEFAULT_NEGOTIATION_ASK_ROUNDS_CAP = 3;
+/**
+ * Per-negotiation ask cap, overridable via `NEGOTIATION_ASK_ROUNDS_CAP`.
+ * Invalid or non-positive values fall back to the default — zero is not an
+ * off switch here; the cap exists so two agents cannot ping-pong their humans
+ * indefinitely. It tunes the bound, it does not gate the behaviour.
+ */
+export declare function negotiationAskRoundsCap(): number;
 /** Default answer window for a paused `ask_user` negotiation: 24 hours. */
 export declare const DEFAULT_ASK_USER_WINDOW_MS: number;
 /**

package/dist/negotiations/negotiation.protocol.js

@@ -155,6 +155,28 @@ export function configuredProtocolVersion() {
 export function configuredAskUserEnabled() {
     return process.env.NEGOTIATION_ASK_USER_ENABLED === "true";
 }
+/**
+ * Default per-negotiation ask cap: total client-consultation rounds (mid-flight
+ * `ask_user` pauses and post-stall parks, both sides combined) before the
+ * negotiation stalls terminally instead of parking again. Three admits one
+ * post-stall park even after each side has spent its one mid-flight consult.
+ */
+export const DEFAULT_NEGOTIATION_ASK_ROUNDS_CAP = 3;
+/**
+ * Per-negotiation ask cap, overridable via `NEGOTIATION_ASK_ROUNDS_CAP`.
+ * Invalid or non-positive values fall back to the default — zero is not an
+ * off switch here; the cap exists so two agents cannot ping-pong their humans
+ * indefinitely. It tunes the bound, it does not gate the behaviour.
+ */
+export function negotiationAskRoundsCap() {
+    const raw = process.env.NEGOTIATION_ASK_ROUNDS_CAP;
+    if (raw) {
+        const parsed = Number(raw);
+        if (Number.isInteger(parsed) && parsed > 0)
+            return parsed;
+    }
+    return DEFAULT_NEGOTIATION_ASK_ROUNDS_CAP;
+}
 /** Default answer window for a paused `ask_user` negotiation: 24 hours. */
 export const DEFAULT_ASK_USER_WINDOW_MS = 24 * 60 * 60 * 1000;
 /**

package/dist/negotiations/negotiation.stall-gap.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Post-stall gap authoring (conversational-questions plan).
+ *
+ * When a negotiation ends unconcluded — no opportunity, no explicit reject:
+ * turn cap, timeout, or stall — the finalize node asks the negotiator for the
+ * ONE question whose answer would let a retry conclude, and parks the
+ * negotiation carrying that gap as an `ask_user` message in its own record.
+ * This module owns that single extra model call.
+ *
+ * Grounding is exactly what mid-flight authoring (P3.2 / IND-401 A2H) uses:
+ * this negotiation's transcript, plus the client's own negotiator DM for the
+ * signal when the caller retrieved one. Same non-naming and non-echo rules;
+ * the caller re-checks the output with `isSafeAuthoredNegotiationQuestion`
+ * (identifiers in hand) before persisting anything.
+ *
+ * Fail-open contract: any model failure, timeout, or invalid output resolves
+ * to null — the negotiation then stalls exactly as it did before this feature,
+ * never half-parks.
+ */
+import { createStructuredModel } from "../shared/agent/model.config.js";
+import { type StructuredQuestion } from "../shared/schemas/structured-question.schema.js";
+import { type NegotiationConsultationReason } from "../shared/schemas/negotiation-state.schema.js";
+import { type NegotiatorClientDmMessage } from "./negotiation.client-dm.js";
+import type { NegotiationTurn } from "./negotiation.state.js";
+/**
+ * Fixed transcript reasoning for a post-stall park turn. Deliberately not
+ * model-authored: assessment reasoning enters the shared A2A record, and the
+ * park's "why" already lives in the guarded question itself — a second,
+ * unguarded free-text channel would reopen the leak surface the question gate
+ * closes.
+ */
+export declare const NEGOTIATION_PARK_REASONING = "Negotiation parked pending the client's answer.";
+/** Why the negotiation failed to conclude, as finalize classified it. */
+export type NegotiationStallReason = "turn_cap" | "timeout" | "stalled";
+/** The authored gap: what a retry needs from the client, and why the pause is warranted. */
+export interface NegotiationStallGap {
+    reason: NegotiationConsultationReason;
+    question: StructuredQuestion;
+}
+export interface StallGapAuthorInput {
+    /** Display name of the client the question is addressed to. */
+    userName: string;
+    /** The client's signal this negotiation was about. */
+    signal: {
+        title: string;
+        description: string;
+    };
+    /** Why the match was suggested (evaluator output; context, never copy). */
+    seedReasoning: string;
+    /** This negotiation's full transcript, oldest first. */
+    history: NegotiationTurn[];
+    stallReason: NegotiationStallReason;
+    /** Recent excerpt of the client's negotiator DM for this signal, most recent last. */
+    clientDm?: NegotiatorClientDmMessage[];
+}
+export interface NegotiationStallGapAuthorConfig {
+    /** Hard ceiling on the model round-trip, in ms. Same resolution as the negotiator turn timeout. */
+    timeoutMs?: number;
+}
+/**
+ * Authors the post-stall gap. One instance lives in the graph's dependency bag
+ * beside `systemAgent`; the finalize node calls it at most once per stalled
+ * session.
+ */
+export declare class NegotiationStallGapAuthor {
+    private readonly timeoutMs;
+    constructor(config?: NegotiationStallGapAuthorConfig);
+    /**
+     * @returns The authored gap, or null when there is none to ask — the model
+     *          said so, produced invalid output after a retry, or failed. The
+     *          caller treats every null identically: terminal stall, no park.
+     */
+    author(input: StallGapAuthorInput): Promise<NegotiationStallGap | null>;
+    /**
+     * Raw structured-model round trip. Split out as a seam so tests can drive
+     * the validate→retry→null loop without a live provider — same pattern as
+     * `IndexNegotiator.callModel`.
+     */
+    protected callModel(model: ReturnType<typeof createStructuredModel>, chatMessages: Array<{
+        role: string;
+        content: string;
+    }>): Promise<unknown>;
+}

package/dist/negotiations/negotiation.stall-gap.js

@@ -0,0 +1,152 @@
+/**
+ * Post-stall gap authoring (conversational-questions plan).
+ *
+ * When a negotiation ends unconcluded — no opportunity, no explicit reject:
+ * turn cap, timeout, or stall — the finalize node asks the negotiator for the
+ * ONE question whose answer would let a retry conclude, and parks the
+ * negotiation carrying that gap as an `ask_user` message in its own record.
+ * This module owns that single extra model call.
+ *
+ * Grounding is exactly what mid-flight authoring (P3.2 / IND-401 A2H) uses:
+ * this negotiation's transcript, plus the client's own negotiator DM for the
+ * signal when the caller retrieved one. Same non-naming and non-echo rules;
+ * the caller re-checks the output with `isSafeAuthoredNegotiationQuestion`
+ * (identifiers in hand) before persisting anything.
+ *
+ * Fail-open contract: any model failure, timeout, or invalid output resolves
+ * to null — the negotiation then stalls exactly as it did before this feature,
+ * never half-parks.
+ */
+import { z } from "zod";
+import { createStructuredModel } from "../shared/agent/model.config.js";
+import { invokeWithAbortSignal } from "../shared/agent/model-signal.js";
+import { StructuredQuestionSchema } from "../shared/schemas/structured-question.schema.js";
+import { NegotiationConsultationReasonSchema } from "../shared/schemas/negotiation-state.schema.js";
+import { renderNegotiatorClientDmSection } from "./negotiation.client-dm.js";
+import { resolveTurnTimeoutMs } from "./negotiation.agent.js";
+import { protocolLogger } from "../shared/observability/protocol.logger.js";
+const stallGapLog = protocolLogger("NegotiationStallGapAuthor");
+/**
+ * Fixed transcript reasoning for a post-stall park turn. Deliberately not
+ * model-authored: assessment reasoning enters the shared A2A record, and the
+ * park's "why" already lives in the guarded question itself — a second,
+ * unguarded free-text channel would reopen the leak surface the question gate
+ * closes.
+ */
+export const NEGOTIATION_PARK_REASONING = "Negotiation parked pending the client's answer.";
+const STALL_REASON_LABELS = {
+    turn_cap: "the turn limit was reached without agreement",
+    timeout: "the negotiation timed out",
+    stalled: "the exchange stalled without reaching a conclusion",
+};
+/**
+ * Structured output for the gap call. `hasGap: false` is a first-class answer:
+ * when no single client answer would change a retry's outcome, the negotiation
+ * must stall terminally rather than park on a filler question. Nullable
+ * declarations mirror `AskUserPayloadSchema.question` — strict structured-output
+ * conversion rejects optional-without-nullable, and a returned null reads as
+ * absent.
+ */
+const StallGapOutputSchema = z.object({
+    hasGap: z.boolean(),
+    reason: NegotiationConsultationReasonSchema.nullable().optional().transform((value) => value ?? undefined),
+    question: StructuredQuestionSchema.nullable().optional().transform((value) => value ?? undefined),
+});
+const SYSTEM_PROMPT = `You are the Index Negotiator, an AI agent acting on behalf of {userName}. A negotiation you conducted for them about a potential connection has just ended without conclusion: {stallReasonLabel}.
+
+Your job now is a single decision: is there ONE piece of information only {userName} holds whose answer would let a retry of this negotiation reach a conclusion? Read the exchange below and judge where it actually stuck.
+
+- If no single answer from {userName} would change a retry's outcome — the match is simply weak, the counterparty is the blocker, or the stall had nothing to do with missing input from {userName} — set hasGap to false and omit the question. Do not invent a question to have something to ask; asking costs {userName} attention and pauses nothing useful.
+- If yes, set hasGap to true and author the question:
+  - reason: exactly one closed server category recording WHY the pause is warranted: "unresolved_owner_constraint" | "consequential_disclosure_permission" | "repeated_non_convergence" | "insufficient_commitment_authority". It is not the wording {userName} sees.
+  - title: at most 12 characters — a noun for the decision domain, e.g. "Stage", "Timing", "Budget", "Scope".
+  - prompt: at most 2 sentences and 400 characters, ending in a question mark. Ask about the specific thing that was actually stuck in this negotiation, in {userName}'s own terms, grounded in the exchange below. Never a generic template.
+  - options: 2–4 of {userName}'s real decision options. Each label at most 120 characters; each description at most 280 characters, stating the CONSEQUENCE of choosing that option — what the retry would do with it — not what it means. Never add an "Other" option; clients provide a free-text fallback automatically.
+  - multiSelect: true ONLY when the options are not mutually exclusive; false for a single either/or decision.
+  - Do not name, quote, or describe the counterparty. {userName} can read the transcript, but the question itself must stand on its own without their identity or profile in it.
+  - Do NOT reference internal system details like scores, pre-screens, or evaluator outputs.{dmGroundingRule}`;
+/**
+ * Appended only when the call actually carries a client-DM excerpt, mirroring
+ * `ASK_USER_DM_GROUNDING_RULE`: a call with no DM must not carry a rule that
+ * dangles with nothing in the prompt to check against.
+ */
+const DM_GROUNDING_RULE = `
+  - Ground the question in your conversation with {userName} about this signal (shown below) as well as in the exchange. Do NOT ask what they have already answered there: if their own words settle the point, there is no gap on it. Use their terms for the thing at stake — the words, numbers, and framing they used, not your paraphrase of them.`;
+function formatTurnLine(turn, index) {
+    const msgPart = turn.message ? ` — message: ${turn.message}` : "";
+    return `Turn ${index + 1}: ${turn.action} — reasoning: ${turn.assessment.reasoning}${msgPart}`;
+}
+/**
+ * Authors the post-stall gap. One instance lives in the graph's dependency bag
+ * beside `systemAgent`; the finalize node calls it at most once per stalled
+ * session.
+ */
+export class NegotiationStallGapAuthor {
+    constructor(config) {
+        this.timeoutMs = resolveTurnTimeoutMs(config?.timeoutMs);
+    }
+    /**
+     * @returns The authored gap, or null when there is none to ask — the model
+     *          said so, produced invalid output after a retry, or failed. The
+     *          caller treats every null identically: terminal stall, no park.
+     */
+    async author(input) {
+        const clientDm = input.clientDm ?? [];
+        const model = createStructuredModel("negotiator", StallGapOutputSchema, { name: "negotiation_stall_gap" });
+        const systemPrompt = SYSTEM_PROMPT
+            .replace("{stallReasonLabel}", STALL_REASON_LABELS[input.stallReason])
+            .replace("{dmGroundingRule}", clientDm.length > 0 ? DM_GROUNDING_RULE : "")
+            .replace(/{userName}/g, input.userName);
+        const transcript = input.history.length > 0
+            ? `\n\nNegotiation transcript:\n${input.history.map(formatTurnLine).join("\n")}`
+            : "";
+        const userMessage = `{userName}'s signal under negotiation:
+- ${input.signal.title}: ${input.signal.description}
+
+Why this match was suggested: ${input.seedReasoning}${transcript}${renderNegotiatorClientDmSection(clientDm, input.userName)}
+
+Decide whether one question to {userName} would let a retry conclude, and author it if so.`.replace(/{userName}/g, input.userName);
+        const chatMessages = [
+            { role: "system", content: systemPrompt },
+            { role: "user", content: userMessage },
+        ];
+        try {
+            // Same validate → retry-once → give-up loop as the negotiator turn,
+            // except giving up resolves to null (terminal stall) instead of a
+            // fallback action — there is no conservative fallback question.
+            for (let attempt = 0; attempt < 2; attempt++) {
+                const result = await this.callModel(model, chatMessages);
+                const parsed = StallGapOutputSchema.safeParse(result);
+                if (!parsed.success) {
+                    stallGapLog.warn("Stall-gap output failed schema validation", {
+                        attempt: attempt + 1,
+                        issues: parsed.error.issues.map((issue) => issue.message).slice(0, 3),
+                    });
+                    continue;
+                }
+                if (!parsed.data.hasGap)
+                    return null;
+                if (!parsed.data.question || !parsed.data.reason) {
+                    stallGapLog.warn("Stall-gap output claimed a gap without question or reason", { attempt: attempt + 1 });
+                    continue;
+                }
+                return { reason: parsed.data.reason, question: parsed.data.question };
+            }
+            return null;
+        }
+        catch (err) {
+            stallGapLog.warn("Stall-gap authoring failed; negotiation stalls without a park", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+    }
+    /**
+     * Raw structured-model round trip. Split out as a seam so tests can drive
+     * the validate→retry→null loop without a live provider — same pattern as
+     * `IndexNegotiator.callModel`.
+     */
+    async callModel(model, chatMessages) {
+        return invokeWithAbortSignal(model, chatMessages, AbortSignal.timeout(this.timeoutMs));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indexnetwork/protocol",
-  "version": "21.1.0-rc.491.1",
+  "version": "21.1.0-rc.492.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",