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

package/dist/index.d.ts

@@ -132,3 +132,5 @@ export type { NegotiationSpeakerParticipants, NegotiationSpeakerMessage, Negotia
 export { assessConsultationEligibility, consultationPromptFor, negotiationConsultationPolicyMode } from "./negotiations/negotiation.module.js";
 export type { ConsultationEligibility, ConsultationEligibilityInput, NegotiationConsultationPolicyMode } from "./negotiations/negotiation.module.js";
 export { NEGOTIATION_QUESTION_GENERIC_COUNTERPARTY, NEGOTIATION_QUESTION_GENERIC_NETWORK, NEGOTIATION_QUESTION_GENERIC_UPTAKE_ACTIVITY, negotiationQuestionSettlementId, } from "./negotiations/negotiation.module.js";
+export { classifyParkedNegotiation, consumeQuestionBlockAnswers, negotiationParkAnswerId, resumeParkedNegotiation, routeAnswerRef, } from "./negotiations/negotiation.module.js";
+export type { AnswerRoute, InflightAnswerSettlementInput, InflightAnswerSettlementResult, NegotiationAnswerConsumptionPorts, NegotiationAnswerInput, NegotiationAnswerResumeOutcome, ParkClassification, QuestionBlockAnswerConsumptionInput, QuestionBlockAnswerConsumptionResult, RoutedAnswer, } from "./negotiations/negotiation.module.js";

package/dist/index.js

@@ -116,3 +116,5 @@ export { HERMES_OWNER_DIRECTIVE, HermesNegotiationResponseSchema, allowedHermesA
 export { isNegotiationTurnCapReached, expectedNegotiationSpeaker, negotiationScopeKey, readNegotiationMessages, allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, isTerminalAction, isRejectLikeAction, readProtocolVersion, resolveSeat, seatViolationMessage } from "./negotiations/negotiation.module.js";
 export { assessConsultationEligibility, consultationPromptFor, negotiationConsultationPolicyMode } from "./negotiations/negotiation.module.js";
 export { NEGOTIATION_QUESTION_GENERIC_COUNTERPARTY, NEGOTIATION_QUESTION_GENERIC_NETWORK, NEGOTIATION_QUESTION_GENERIC_UPTAKE_ACTIVITY, negotiationQuestionSettlementId, } from "./negotiations/negotiation.module.js";
+// ─── Negotiation answer consumption (conversational questions) ──────────────
+export { classifyParkedNegotiation, consumeQuestionBlockAnswers, negotiationParkAnswerId, resumeParkedNegotiation, routeAnswerRef, } from "./negotiations/negotiation.module.js";

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.answer-consumption.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Answer consumption: route a client's DM reply to its parked negotiations and
+ * resume them (conversational-questions plan, "Answers").
+ *
+ * The delivery surface decides that a chat reply answers a question-message
+ * and maps the reply's content onto block refs; this module owns everything
+ * after that decision — the RESUME SEAM. Given a routed answer and the block
+ * it answers, it re-resolves each referenced negotiation to its current park
+ * and resumes it exactly once:
+ *
+ * - A mid-flight consult park (`input_required` task with a captured ask-user
+ *   binding) resumes through the same durable settlement → exact continuation
+ *   path the card answer used: settle the exact task, then enqueue the
+ *   settlement-keyed resume. The settle is a CAS on the parked task, so a
+ *   second delivery finds it already settled and only re-enqueues the
+ *   idempotent continuation — never a double resume.
+ * - A post-stall park (completed task on a stalled opportunity whose trailing
+ *   turn is the authored `ask_user` gap, `NEGOTIATION_PARK_REASONING`) resumes
+ *   as a fresh negotiation attempt: the answer is recorded on the opportunity
+ *   (where continuation prompts already read it via
+ *   `getOpportunityUserAnswers`) and a retry is enqueued. Exactly-once is the
+ *   attempt claim: concurrent retries race `createNegotiationTaskForAttempt`
+ *   and all but one lose.
+ *
+ * Idempotency is a property of the negotiation, not of any settlement record
+ * kept here: re-resolution + the `input_required` admission gate (mid-flight)
+ * and the atomic attempt claim (post-stall) make a repeated delivery a no-op.
+ * A ref that matches nothing in the block resumes NOTHING — misrouting resumes
+ * the wrong negotiation with the wrong fact, which is worse than asking again —
+ * and is reported back so the delivery surface can ask a clarifying follow-up.
+ *
+ * A resumed negotiation may park again; the ask-rounds cap (#1430) bounds that
+ * loop at park time. This module deliberately adds no second counter.
+ */
+import type { NegotiationGraphDatabase, NegotiationUserAnswer } from "../shared/interfaces/database.interface.js";
+import type { QuestionBlock, QuestionBlockQuestion } from "../shared/schemas/question-block.schema.js";
+/** One answer the delivery agent routed onto a block ref. */
+export interface RoutedAnswer {
+    /** The block ref the reply was matched to — primary or alsoUnblocks alike. */
+    ref: string;
+    /** The client's answer for that question, as free text. */
+    answerText: string;
+}
+/** A resolved route: the owning question and every negotiation its answer resumes. */
+export interface AnswerRoute {
+    question: QuestionBlockQuestion;
+    /** Primary first, then `alsoUnblocks` — one answer resumes them all. */
+    opportunityIds: string[];
+}
+/**
+ * Resolve a matched ref to its question and full resume set. The block schema
+ * guarantees every ref appears exactly once across the whole block, so this is
+ * a lookup — ambiguity is a producer-side error that cannot reach here through
+ * a parsed block. Returns null for a ref the block does not carry: the caller
+ * must ask a clarifying follow-up, never resume speculatively.
+ */
+export declare function routeAnswerRef(block: QuestionBlock, ref: string): AnswerRoute | null;
+/** The minimal ask-user binding a mid-flight resume needs, read off task metadata. */
+interface AskUserResumeBinding {
+    settlementId: string;
+    recipientUserId: string;
+    recipientIntentId: string;
+    networkId: string;
+    opportunityId: string;
+}
+/** What answering a given ref would resume, as re-resolved right now. */
+export type ParkClassification = {
+    kind: "inflight";
+    taskId: string;
+    binding: AskUserResumeBinding;
+} | {
+    kind: "post_stall";
+    taskId: string;
+}
+/** No negotiation task exists for the ref at all. */
+ | {
+    kind: "no_negotiation";
+}
+/** A negotiation exists but holds no live park — already resumed, expired, or terminal. */
+ | {
+    kind: "not_parked";
+}
+/** Parked, but awaiting the OTHER side's client — this user's answer must not resume it. */
+ | {
+    kind: "wrong_recipient";
+};
+/**
+ * Re-resolve a negotiation ref to its current park. This is the exact task
+ * re-resolution the graph itself uses (`getNegotiationTaskForOpportunity`),
+ * never a snapshot: answer routing branches on what the negotiation is NOW,
+ * so a park that was answered, expired, or superseded since the block was
+ * authored classifies as `not_parked` and the answer no-ops.
+ */
+export declare function classifyParkedNegotiation(database: Pick<NegotiationGraphDatabase, "getNegotiationTaskForOpportunity" | "getNegotiationMessages">, input: {
+    opportunityId: string;
+    userId: string;
+}): Promise<ParkClassification>;
+/** Everything a mid-flight settle needs; all fields come from the re-resolved binding. */
+export interface InflightAnswerSettlementInput {
+    taskId: string;
+    settlementId: string;
+    opportunityId: string;
+    recipientUserId: string;
+    recipientIntentId: string;
+    networkId: string;
+    answer: {
+        selectedOptions: string[];
+        freeText?: string;
+        answeredAt: string;
+    };
+}
+/**
+ * - `settled`: this call closed the exact `input_required` task and durably
+ *   stored the answer for the continuation claim to read.
+ * - `already_settled`: an earlier delivery settled it; the stored settlement
+ *   stands. Resuming is still correct — the continuation enqueue and claim are
+ *   settlement-keyed and idempotent, so re-enqueueing recovers a lost job
+ *   without a double resume.
+ * - `lost`: the admission gate refused — the task is no longer
+ *   `input_required` (answer-window expiry or another path won). No resume.
+ */
+export type InflightAnswerSettlementResult = "settled" | "already_settled" | "lost";
+export interface NegotiationAnswerConsumptionPorts {
+    /** The same reads the negotiation graph resolves parks with. */
+    database: Pick<NegotiationGraphDatabase, "getNegotiationTaskForOpportunity" | "getNegotiationMessages">;
+    /**
+     * Settle the exact mid-flight consult: CAS the `input_required` task closed
+     * under the deterministic settlement lock and durably store the answer where
+     * the continuation claim reads its private consultation. Implementations
+     * must be answer-vs-timeout safe (the expiry worker races this) and must
+     * report a repeat delivery as `already_settled`, never settle twice.
+     */
+    settleInflightAnswer(input: InflightAnswerSettlementInput): Promise<InflightAnswerSettlementResult>;
+    /**
+     * Enqueue the exact durable continuation — the same settlement-keyed resume
+     * the card answer path enqueues. Must be idempotent per settlementId.
+     */
+    enqueueInflightResume(input: {
+        opportunityId: string;
+        userId: string;
+        taskId: string;
+        settlementId: string;
+        recipientIntentId: string;
+        networkId: string;
+    }): Promise<void>;
+    /**
+     * Append the routed answer to the opportunity's `userAnswers`, where
+     * continuation prompts already read between-session context. Implementations
+     * MUST ignore an append whose `questionId` is already present — that key is
+     * deterministic per park, so a repeated delivery records nothing twice.
+     */
+    recordOpportunityAnswer(input: {
+        opportunityId: string;
+        answer: NegotiationUserAnswer;
+    }): Promise<void>;
+    /**
+     * Enqueue a fresh negotiate-existing retry of the stalled opportunity.
+     * `parkTaskId` identifies the answered park; implementations should dedupe
+     * on it. Over-enqueueing is safe regardless: every retry races the atomic
+     * attempt claim and all but one lose.
+     */
+    enqueueStalledRetry(input: {
+        opportunityId: string;
+        userId: string;
+        parkTaskId: string;
+    }): Promise<void>;
+}
+/** Deterministic identity of a post-stall park's recorded answer (dedup key, never rendered). */
+export declare function negotiationParkAnswerId(parkTaskId: string): string;
+export type NegotiationAnswerResumeOutcome = "resumed_inflight" | "resumed_retry" | "not_parked" | "no_negotiation" | "wrong_recipient";
+export interface NegotiationAnswerInput {
+    /** The negotiation to resume: one ref out of a routed answer's resume set. */
+    opportunityId: string;
+    /** The answering client — the park must be awaiting THIS user's side. */
+    userId: string;
+    answerText: string;
+    /** ISO timestamp of the reply; defaults to now. */
+    answeredAt?: string;
+}
+/**
+ * Resume one parked negotiation with a routed answer, exactly once. Both
+ * outcomes that resume enqueue asynchronously — the negotiation continues on
+ * its queue, not inline. Every other outcome resumes nothing. Throws only on
+ * port failure; every step is safe to repeat, so the caller may simply
+ * redeliver.
+ */
+export declare function resumeParkedNegotiation(ports: NegotiationAnswerConsumptionPorts, input: NegotiationAnswerInput): Promise<NegotiationAnswerResumeOutcome>;
+export interface QuestionBlockAnswerConsumptionInput {
+    /** The parsed block the reply answers (see `parseQuestionMessage`). */
+    block: QuestionBlock;
+    /** The replying client — the DM's owner. */
+    userId: string;
+    /** The reply's content routed onto block refs; empty when nothing matched. */
+    answers: RoutedAnswer[];
+    /** ISO timestamp of the reply; defaults to now. */
+    answeredAt?: string;
+}
+export interface QuestionBlockAnswerConsumptionResult {
+    resumed: Array<{
+        opportunityId: string;
+        outcome: "resumed_inflight" | "resumed_retry";
+    }>;
+    skipped: Array<{
+        opportunityId: string;
+        outcome: "not_parked" | "no_negotiation" | "wrong_recipient" | "duplicate_route" | "failed";
+    }>;
+    /** Routed answers whose ref the block does not carry — resume nothing, ask again. */
+    unmatched: RoutedAnswer[];
+    /**
+     * True when the reply left something unresolved on the routing side: no
+     * answer matched at all, or a ref matched nothing in the block. The caller
+     * owns the clarifying follow-up; this seam only ever refuses to guess.
+     */
+    needsClarification: boolean;
+}
+/**
+ * Consume a client reply against the block it answers: resolve each routed
+ * answer to its question, then resume the primary negotiation and every
+ * `alsoUnblocks` ref with that answer, exactly once each. Failures are
+ * per-negotiation — one broken target never blocks the rest of the reply.
+ */
+export declare function consumeQuestionBlockAnswers(ports: NegotiationAnswerConsumptionPorts, input: QuestionBlockAnswerConsumptionInput): Promise<QuestionBlockAnswerConsumptionResult>;
+export {};

package/dist/negotiations/negotiation.answer-consumption.js

@@ -0,0 +1,275 @@
+/**
+ * Answer consumption: route a client's DM reply to its parked negotiations and
+ * resume them (conversational-questions plan, "Answers").
+ *
+ * The delivery surface decides that a chat reply answers a question-message
+ * and maps the reply's content onto block refs; this module owns everything
+ * after that decision — the RESUME SEAM. Given a routed answer and the block
+ * it answers, it re-resolves each referenced negotiation to its current park
+ * and resumes it exactly once:
+ *
+ * - A mid-flight consult park (`input_required` task with a captured ask-user
+ *   binding) resumes through the same durable settlement → exact continuation
+ *   path the card answer used: settle the exact task, then enqueue the
+ *   settlement-keyed resume. The settle is a CAS on the parked task, so a
+ *   second delivery finds it already settled and only re-enqueues the
+ *   idempotent continuation — never a double resume.
+ * - A post-stall park (completed task on a stalled opportunity whose trailing
+ *   turn is the authored `ask_user` gap, `NEGOTIATION_PARK_REASONING`) resumes
+ *   as a fresh negotiation attempt: the answer is recorded on the opportunity
+ *   (where continuation prompts already read it via
+ *   `getOpportunityUserAnswers`) and a retry is enqueued. Exactly-once is the
+ *   attempt claim: concurrent retries race `createNegotiationTaskForAttempt`
+ *   and all but one lose.
+ *
+ * Idempotency is a property of the negotiation, not of any settlement record
+ * kept here: re-resolution + the `input_required` admission gate (mid-flight)
+ * and the atomic attempt claim (post-stall) make a repeated delivery a no-op.
+ * A ref that matches nothing in the block resumes NOTHING — misrouting resumes
+ * the wrong negotiation with the wrong fact, which is worse than asking again —
+ * and is reported back so the delivery surface can ask a clarifying follow-up.
+ *
+ * A resumed negotiation may park again; the ask-rounds cap (#1430) bounds that
+ * loop at park time. This module deliberately adds no second counter.
+ */
+import { NEGOTIATION_PARK_REASONING } from "./negotiation.stall-gap.js";
+import { negotiationQuestionSettlementId } from "./negotiation.question-safety.js";
+import { turnsFromMessages } from "./negotiation.graph.shared.js";
+import { protocolLogger } from "../shared/observability/protocol.logger.js";
+const answerLog = protocolLogger("NegotiationAnswerConsumption");
+/**
+ * Resolve a matched ref to its question and full resume set. The block schema
+ * guarantees every ref appears exactly once across the whole block, so this is
+ * a lookup — ambiguity is a producer-side error that cannot reach here through
+ * a parsed block. Returns null for a ref the block does not carry: the caller
+ * must ask a clarifying follow-up, never resume speculatively.
+ */
+export function routeAnswerRef(block, ref) {
+    for (const question of block.questions) {
+        const opportunityIds = [question.opportunityId, ...(question.alsoUnblocks ?? [])];
+        if (opportunityIds.includes(ref))
+            return { question, opportunityIds };
+    }
+    return null;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function readAskUserResumeBinding(metadata) {
+    const turnContext = metadata?.turnContext;
+    const binding = turnContext?.askUserBinding;
+    if (!binding
+        || !nonEmptyString(binding.settlementId)
+        || !nonEmptyString(binding.recipientUserId)
+        || !nonEmptyString(binding.recipientIntentId)
+        || !nonEmptyString(binding.networkId)
+        || !nonEmptyString(binding.opportunityId))
+        return null;
+    return {
+        settlementId: binding.settlementId,
+        recipientUserId: binding.recipientUserId,
+        recipientIntentId: binding.recipientIntentId,
+        networkId: binding.networkId,
+        opportunityId: binding.opportunityId,
+    };
+}
+/**
+ * The trailing canonical turn of a negotiation's own messages, when it is the
+ * authored post-stall gap. Non-turn messages are skipped, mirroring
+ * `turnsFromMessages`; any other trailing turn means the negotiation is not
+ * parked post-stall.
+ */
+function trailingParkMessage(messages) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        const turn = turnsFromMessages([message])[0];
+        if (!turn)
+            continue;
+        return turn.action === "ask_user" && turn.assessment?.reasoning === NEGOTIATION_PARK_REASONING
+            ? { senderId: message.senderId, taskId: message.taskId, turn }
+            : null;
+    }
+    return null;
+}
+/**
+ * Re-resolve a negotiation ref to its current park. This is the exact task
+ * re-resolution the graph itself uses (`getNegotiationTaskForOpportunity`),
+ * never a snapshot: answer routing branches on what the negotiation is NOW,
+ * so a park that was answered, expired, or superseded since the block was
+ * authored classifies as `not_parked` and the answer no-ops.
+ */
+export async function classifyParkedNegotiation(database, input) {
+    const task = await database.getNegotiationTaskForOpportunity(input.opportunityId);
+    if (!task)
+        return { kind: "no_negotiation" };
+    if (task.state === "input_required") {
+        const binding = readAskUserResumeBinding(task.metadata);
+        if (!binding
+            || binding.opportunityId !== input.opportunityId
+            || binding.settlementId !== negotiationQuestionSettlementId(task.id)) {
+            answerLog.warn("input_required negotiation task carries no coherent ask-user binding; answer cannot resume it", {
+                taskId: task.id,
+                opportunityId: input.opportunityId,
+            });
+            return { kind: "not_parked" };
+        }
+        if (binding.recipientUserId !== input.userId)
+            return { kind: "wrong_recipient" };
+        return { kind: "inflight", taskId: task.id, binding };
+    }
+    if (task.state === "completed") {
+        const messages = await database.getNegotiationMessages(input.opportunityId);
+        const park = trailingParkMessage(messages);
+        if (!park)
+            return { kind: "not_parked" };
+        // The gap was written by the finalizing session's task — the most recent
+        // one. A trailing park from an older task means state has moved on.
+        if (park.taskId != null && park.taskId !== task.id)
+            return { kind: "not_parked" };
+        if (park.senderId !== `agent:${input.userId}`)
+            return { kind: "wrong_recipient" };
+        return { kind: "post_stall", taskId: task.id };
+    }
+    // submitted/working/waiting_for_agent: a session is live (possibly the very
+    // resume a first delivery triggered); canceled: a settled consult awaiting
+    // its successor; failed/rejected: terminal. None hold an answerable park.
+    return { kind: "not_parked" };
+}
+/** Deterministic identity of a post-stall park's recorded answer (dedup key, never rendered). */
+export function negotiationParkAnswerId(parkTaskId) {
+    return `negotiation-park-answer-v1-${parkTaskId}`;
+}
+/**
+ * Resume one parked negotiation with a routed answer, exactly once. Both
+ * outcomes that resume enqueue asynchronously — the negotiation continues on
+ * its queue, not inline. Every other outcome resumes nothing. Throws only on
+ * port failure; every step is safe to repeat, so the caller may simply
+ * redeliver.
+ */
+export async function resumeParkedNegotiation(ports, input) {
+    const classification = await classifyParkedNegotiation(ports.database, {
+        opportunityId: input.opportunityId,
+        userId: input.userId,
+    });
+    const answeredAt = input.answeredAt ?? new Date().toISOString();
+    if (classification.kind === "inflight") {
+        const settlement = await ports.settleInflightAnswer({
+            taskId: classification.taskId,
+            settlementId: classification.binding.settlementId,
+            opportunityId: input.opportunityId,
+            recipientUserId: classification.binding.recipientUserId,
+            recipientIntentId: classification.binding.recipientIntentId,
+            networkId: classification.binding.networkId,
+            answer: { selectedOptions: [], freeText: input.answerText, answeredAt },
+        });
+        if (settlement === "lost") {
+            answerLog.info("negotiation_answer_settlement_lost", {
+                taskId: classification.taskId,
+                opportunityId: input.opportunityId,
+            });
+            return "not_parked";
+        }
+        // Settlement is durable; enqueue after it, never before — a crash between
+        // the two is recovered by redelivery (`already_settled` → enqueue again).
+        await ports.enqueueInflightResume({
+            opportunityId: input.opportunityId,
+            userId: classification.binding.recipientUserId,
+            taskId: classification.taskId,
+            settlementId: classification.binding.settlementId,
+            recipientIntentId: classification.binding.recipientIntentId,
+            networkId: classification.binding.networkId,
+        });
+        answerLog.info("negotiation_answer_resumed_inflight", {
+            taskId: classification.taskId,
+            opportunityId: input.opportunityId,
+            settlement,
+        });
+        return "resumed_inflight";
+    }
+    if (classification.kind === "post_stall") {
+        // Record before enqueueing: the retry's continuation prompt must see the
+        // answer. The deterministic id makes the append idempotent, so the
+        // crash-recovery order (record, then enqueue, redeliver on failure) holds.
+        await ports.recordOpportunityAnswer({
+            opportunityId: input.opportunityId,
+            answer: {
+                questionId: negotiationParkAnswerId(classification.taskId),
+                selectedOptions: [],
+                freeText: input.answerText,
+                answeredAt,
+            },
+        });
+        await ports.enqueueStalledRetry({
+            opportunityId: input.opportunityId,
+            userId: input.userId,
+            parkTaskId: classification.taskId,
+        });
+        answerLog.info("negotiation_answer_resumed_retry", {
+            taskId: classification.taskId,
+            opportunityId: input.opportunityId,
+        });
+        return "resumed_retry";
+    }
+    if (classification.kind === "wrong_recipient") {
+        answerLog.warn("Answer routed to a negotiation parked on the counterparty's side; not resuming", {
+            opportunityId: input.opportunityId,
+        });
+    }
+    return classification.kind;
+}
+/**
+ * Consume a client reply against the block it answers: resolve each routed
+ * answer to its question, then resume the primary negotiation and every
+ * `alsoUnblocks` ref with that answer, exactly once each. Failures are
+ * per-negotiation — one broken target never blocks the rest of the reply.
+ */
+export async function consumeQuestionBlockAnswers(ports, input) {
+    const answeredAt = input.answeredAt ?? new Date().toISOString();
+    const result = {
+        resumed: [],
+        skipped: [],
+        unmatched: [],
+        needsClarification: false,
+    };
+    const consumedQuestions = new Set();
+    for (const answer of input.answers) {
+        const route = routeAnswerRef(input.block, answer.ref);
+        if (!route) {
+            result.unmatched.push(answer);
+            continue;
+        }
+        // Two routed answers can name refs of the same question; the first wins.
+        // The later one is surfaced as a duplicate rather than silently merged —
+        // choosing between conflicting phrasings is the delivery agent's job.
+        if (consumedQuestions.has(route.question.opportunityId)) {
+            result.skipped.push({ opportunityId: route.question.opportunityId, outcome: "duplicate_route" });
+            continue;
+        }
+        consumedQuestions.add(route.question.opportunityId);
+        for (const opportunityId of route.opportunityIds) {
+            try {
+                const outcome = await resumeParkedNegotiation(ports, {
+                    opportunityId,
+                    userId: input.userId,
+                    answerText: answer.answerText,
+                    answeredAt,
+                });
+                if (outcome === "resumed_inflight" || outcome === "resumed_retry") {
+                    result.resumed.push({ opportunityId, outcome });
+                }
+                else {
+                    result.skipped.push({ opportunityId, outcome });
+                }
+            }
+            catch (err) {
+                answerLog.error("Failed to resume an answered negotiation; continuing with the rest of the reply", {
+                    opportunityId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                result.skipped.push({ opportunityId, outcome: "failed" });
+            }
+        }
+    }
+    result.needsClarification = input.answers.length === 0 || result.unmatched.length > 0;
+    return result;
+}

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,12 @@ 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 { classifyParkedNegotiation, consumeQuestionBlockAnswers, negotiationParkAnswerId, resumeParkedNegotiation, routeAnswerRef, } from "./negotiation.answer-consumption.js";
+export type { AnswerRoute, InflightAnswerSettlementInput, InflightAnswerSettlementResult, NegotiationAnswerConsumptionPorts, NegotiationAnswerInput, NegotiationAnswerResumeOutcome, ParkClassification, QuestionBlockAnswerConsumptionInput, QuestionBlockAnswerConsumptionResult, RoutedAnswer, } from "./negotiation.answer-consumption.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,10 @@ 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 { classifyParkedNegotiation, consumeQuestionBlockAnswers, negotiationParkAnswerId, resumeParkedNegotiation, routeAnswerRef, } from "./negotiation.answer-consumption.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/dist/negotiations/negotiation.stance.contracts.d.ts

@@ -9,11 +9,11 @@
  *
  * `NEGOTIATOR_STANCE` makes that stance configurable instead of hard-coded:
  *
- * | stance      | framing                              | value bar        | query rule              | deadlock  |
- * |-------------|--------------------------------------|------------------|-------------------------|-----------|
- * | `advocate`  | argue the case (today)               | none             | mandate (today)         | bargain   |
- * | `evaluator` | assess first, advocate if it survives | opportunity-cost | necessary-not-sufficient| bargain   |
- * | `skeptic`   | + "most matches are not worth making" | opportunity-cost | necessary-not-sufficient| stalemate |
+ * | stance      | framing                              | value bar        | query rule              | consult propensity      | deadlock  |
+ * |-------------|--------------------------------------|------------------|-------------------------|-------------------------|-----------|
+ * | `advocate`  | argue the case (today)               | none             | mandate (today)         | none (today)            | bargain   |
+ * | `evaluator` | assess first, advocate if it survives | opportunity-cost | necessary-not-sufficient| prefer over assumption  | bargain   |
+ * | `skeptic`   | + "most matches are not worth making" | opportunity-cost | necessary-not-sufficient| + unverified = don't proceed | stalemate |
  *
  * Design constraints (hard):
  * - **`advocate` is byte-identical.** Every fragment below is additive and

package/dist/negotiations/negotiation.stance.contracts.js

@@ -9,11 +9,11 @@
  *
  * `NEGOTIATOR_STANCE` makes that stance configurable instead of hard-coded:
  *
- * | stance      | framing                              | value bar        | query rule              | deadlock  |
- * |-------------|--------------------------------------|------------------|-------------------------|-----------|
- * | `advocate`  | argue the case (today)               | none             | mandate (today)         | bargain   |
- * | `evaluator` | assess first, advocate if it survives | opportunity-cost | necessary-not-sufficient| bargain   |
- * | `skeptic`   | + "most matches are not worth making" | opportunity-cost | necessary-not-sufficient| stalemate |
+ * | stance      | framing                              | value bar        | query rule              | consult propensity      | deadlock  |
+ * |-------------|--------------------------------------|------------------|-------------------------|-------------------------|-----------|
+ * | `advocate`  | argue the case (today)               | none             | mandate (today)         | none (today)            | bargain   |
+ * | `evaluator` | assess first, advocate if it survives | opportunity-cost | necessary-not-sufficient| prefer over assumption  | bargain   |
+ * | `skeptic`   | + "most matches are not worth making" | opportunity-cost | necessary-not-sufficient| + unverified = don't proceed | stalemate |
  *
  * Design constraints (hard):
  * - **`advocate` is byte-identical.** Every fragment below is additive and
@@ -113,12 +113,45 @@ export function stanceJobFraming(stance) {
  */
 const VALUE_BAR_RULE = `
 - OPPORTUNITY COST: {userName}'s attention is finite and their name is spent on every connection made on their behalf. The bar is "worth that spend", not "does no harm" — absence of a downside is NOT a reason to proceed. Ask what {userName} gives up by spending this attention here instead of on a better match, and say no when the answer is "too much".`;
+/**
+ * Consult propensity — assessing stances only.
+ *
+ * The assessing stances demand a judgment ("is this actually worth making for
+ * {userName}?") that sometimes turns on a fact only the client holds: their
+ * current priorities, their real constraints, what "alignment" would mean to
+ * them. The legacy failure mode is resolving that gap by assumption —
+ * guessing, conceding, or accepting on vibes. This rule names the resolution
+ * path instead: consult the client.
+ *
+ * Deliberately names no action and no mechanism: like every fragment here it
+ * renders into all seats and protocol versions, including seats with no
+ * consultation vocabulary, so the seat's own rules decide HOW a consultation
+ * happens and whether one is still available this turn. This only sets when
+ * the agent should WANT one — which is also why it stays conditional on the
+ * uncertainty being client-resolvable: no "always"/"regardless" wording that
+ * would fight the per-negotiation consultation cap
+ * (`negotiationAskRoundsCap`).
+ */
+const CONSULT_PROPENSITY_RULE = `
+- CONSULT, DON'T ASSUME: when your judgment turns on a fact about {userName}'s OWN intent that you do not hold — their current priorities, their real constraints, what "alignment" would actually mean to them — prefer consulting {userName} over resolving that uncertainty by assumption. Guessing their answer, conceding to keep things moving, or proceeding because nothing contradicts the match are all ways of deciding for them what only they can decide.`;
+/**
+ * `skeptic` sharpening of the consult rule, appended to the same bullet (the
+ * same additive pattern as `SKEPTIC_FRAMING` over `EVALUATOR_FRAMING`): under
+ * the not-worth-making prior an unverified alignment assumption is itself a
+ * reason not to proceed, and consulting the client is how it gets verified.
+ */
+const SKEPTIC_CONSULT_SHARPENING = ` For you this is a gate, not a preference: an UNVERIFIED assumption that the two sides' intents actually align is a reason NOT to proceed, and consulting {userName} is how that assumption gets verified.`;
 /**
  * Extra action-rule lines contributed by the stance, appended after the seat's
  * own rules. Empty under `advocate` → byte-identical.
  */
 export function stanceActionRules(stance) {
-    return stanceAppliesValueBar(stance) ? VALUE_BAR_RULE : "";
+    if (!stanceAppliesValueBar(stance))
+        return "";
+    const consultRule = stance === "skeptic"
+        ? CONSULT_PROPENSITY_RULE + SKEPTIC_CONSULT_SHARPENING
+        : CONSULT_PROPENSITY_RULE;
+    return VALUE_BAR_RULE + consultRule;
 }
 /**
  * The discovery-query satisfaction rule.

package/package.json

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