@xfey/tutti 0.1.127 → 0.1.128

package/dist/approvals/decision-command.d.ts

@@ -25,8 +25,8 @@ export declare function executeApprovalDecisionCommand(input: {
         state: "pending";
         request: {
             expires_at?: string;
-            task_id?: string;
             activity_ref?: string;
+            task_id?: string;
             reason?: string;
             file_change?: {
                 paths?: string[];
@@ -69,8 +69,8 @@ export declare function executeApprovalDecisionCommand(input: {
         state: "resolved";
         request: {
             expires_at?: string;
-            task_id?: string;
             activity_ref?: string;
+            task_id?: string;
             reason?: string;
             file_change?: {
                 paths?: string[];

package/dist/chat-assistant/diagnostics.d.ts

@@ -1,5 +1,6 @@
 import type { ProviderInvocationProgress } from "../providers/invocation-progress.js";
 import type { languageDiagnosticFields } from "../communication-language/index.js";
+import type { ChatFailureCode } from "./failures.js";
 export type ChatAssistantLogger = {
     info: (fields: Record<string, unknown>, message: string) => void;
     warn: (fields: Record<string, unknown>, message: string) => void;
@@ -7,8 +8,10 @@ export type ChatAssistantLogger = {
 type ChatAssistantProgress = ProviderInvocationProgress | ({
     stage: "language_context";
 } & ReturnType<typeof languageDiagnosticFields>) | {
-    stage: "queued" | "inspection_wait" | "model_requested" | "reply_persisted" | "failed" | "skipped";
-    reason_code?: "queue_full" | "stopping" | "context_unavailable" | "answer_failed" | "reply_failed";
+    stage: "queued" | "inspection_wait" | "model_requested" | "reply_persisted" | "notification_failed" | "failed" | "skipped";
+    reason_code?: "queue_full" | "stopping" | "context_unavailable" | "answer_failed" | "reply_failed" | "request_changed";
+    error_code?: ChatFailureCode;
+    diagnostic_id?: string;
     reference_source_count?: number;
 };
 export declare function createChatAssistantDiagnostics(options: {
@@ -16,6 +19,8 @@ export declare function createChatAssistantDiagnostics(options: {
     projectId: string;
     triggerMessageId: string;
     scope: string;
+    requestRef?: string;
+    attemptRef?: string;
 }): (event: ChatAssistantProgress) => void;
 export {};
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/chat-assistant/diagnostics.js

@@ -1,18 +1,21 @@
 import { createEventRef } from "@tutti/shared/ids";
 export function createChatAssistantDiagnostics(options) {
-    const requestRef = createEventRef();
+    const requestRef = options.requestRef ?? createEventRef();
     const started = performance.now();
     return (event) => {
         try {
             const fields = {
                 project_id: options.projectId,
                 chat_request_ref: requestRef,
+                ...(options.attemptRef === undefined ? {} : { attempt_ref: options.attemptRef }),
                 trigger_message_ref: options.triggerMessageId,
                 scope: options.scope,
                 elapsed_ms: Math.round(performance.now() - started),
                 ...event,
             };
-            if (event.stage === "failed" || event.stage === "provider_failed") {
+            if (event.stage === "failed" ||
+                event.stage === "provider_failed" ||
+                event.stage === "notification_failed") {
                 options.logger?.warn(fields, "Chat assistant progress");
             }
             else {

package/dist/chat-assistant/failures.d.ts

@@ -0,0 +1,27 @@
+import type { OperationFailure } from "@tutti/shared/schemas/api";
+declare const failures: {
+    readonly reference_authorization_required: readonly ["access", "none", "Authorize document access using the group card, then send your question again. Authorization does not restart this answer."];
+    readonly chat_queue_full: readonly ["capacity", "resend_request", "Tutti is busy answering other questions. Try again shortly."];
+    readonly chat_context_unavailable: readonly ["interrupted", "none", "This question's conversation is no longer available."];
+    readonly host_restarted: readonly ["interrupted", "resend_request", "The Host restarted before this answer was saved. Send your question again."];
+    readonly provider_not_configured: readonly ["configuration", "check_provider", "Ask the project owner to configure model access, then send your question again."];
+    readonly provider_auth_invalid: readonly ["access", "check_provider", "Model access could not be verified. Ask the project owner to check it."];
+    readonly provider_quota_or_billing_required: readonly ["access", "check_provider", "Model credit is unavailable. Ask the project owner to check the account."];
+    readonly provider_rate_limited: readonly ["capacity", "resend_request", "The model service is busy. Wait a moment, then send your question again."];
+    readonly provider_network_error: readonly ["dependency", "resend_request", "The model service could not be reached. Try again when the connection is available."];
+    readonly provider_model_unavailable: readonly ["configuration", "check_provider", "The selected model is unavailable. Ask the project owner to check model access."];
+    readonly provider_timeout: readonly ["dependency", "resend_request", "The model did not finish answering in time. You can send your question again."];
+    readonly provider_output_invalid: readonly ["dependency", "resend_request", "The model did not return a usable answer. You can send your question again."];
+    readonly provider_lifecycle_failed: readonly ["internal", "restart_host", "The model process could not close safely. Restart the Host before trying again."];
+    readonly chat_reply_persistence_failed: readonly ["internal", "contact_support", "The answer could not be saved. Check the Host diagnostics before trying again."];
+    readonly internal_error: readonly ["internal", "contact_support", "Tutti could not complete this read-only answer. Share the diagnostic ID if this persists."];
+};
+export type ChatFailureCode = keyof typeof failures;
+type ChatFailure = OperationFailure & {
+    code: ChatFailureCode;
+};
+export declare function chatFailure(code: ChatFailureCode, diagnosticId?: string): ChatFailure;
+export declare function chatFailureMessage(failure: OperationFailure): string;
+export declare function classifyChatFailure(error: unknown, diagnosticId: string): ChatFailure;
+export {};
+//# sourceMappingURL=failures.d.ts.map

package/dist/chat-assistant/failures.js

@@ -0,0 +1,102 @@
+import { createEventRef } from "@tutti/shared/ids";
+import { providerFailureCode } from "../providers/failure-classification.js";
+const failures = {
+    reference_authorization_required: [
+        "access",
+        "none",
+        "Authorize document access using the group card, then send your question again. Authorization does not restart this answer.",
+    ],
+    chat_queue_full: [
+        "capacity",
+        "resend_request",
+        "Tutti is busy answering other questions. Try again shortly.",
+    ],
+    chat_context_unavailable: [
+        "interrupted",
+        "none",
+        "This question's conversation is no longer available.",
+    ],
+    host_restarted: [
+        "interrupted",
+        "resend_request",
+        "The Host restarted before this answer was saved. Send your question again.",
+    ],
+    provider_not_configured: [
+        "configuration",
+        "check_provider",
+        "Ask the project owner to configure model access, then send your question again.",
+    ],
+    provider_auth_invalid: [
+        "access",
+        "check_provider",
+        "Model access could not be verified. Ask the project owner to check it.",
+    ],
+    provider_quota_or_billing_required: [
+        "access",
+        "check_provider",
+        "Model credit is unavailable. Ask the project owner to check the account.",
+    ],
+    provider_rate_limited: [
+        "capacity",
+        "resend_request",
+        "The model service is busy. Wait a moment, then send your question again.",
+    ],
+    provider_network_error: [
+        "dependency",
+        "resend_request",
+        "The model service could not be reached. Try again when the connection is available.",
+    ],
+    provider_model_unavailable: [
+        "configuration",
+        "check_provider",
+        "The selected model is unavailable. Ask the project owner to check model access.",
+    ],
+    provider_timeout: [
+        "dependency",
+        "resend_request",
+        "The model did not finish answering in time. You can send your question again.",
+    ],
+    provider_output_invalid: [
+        "dependency",
+        "resend_request",
+        "The model did not return a usable answer. You can send your question again.",
+    ],
+    provider_lifecycle_failed: [
+        "internal",
+        "restart_host",
+        "The model process could not close safely. Restart the Host before trying again.",
+    ],
+    chat_reply_persistence_failed: [
+        "internal",
+        "contact_support",
+        "The answer could not be saved. Check the Host diagnostics before trying again.",
+    ],
+    internal_error: [
+        "internal",
+        "contact_support",
+        "Tutti could not complete this read-only answer. Share the diagnostic ID if this persists.",
+    ],
+};
+export function chatFailure(code, diagnosticId = createEventRef()) {
+    const [category, recovery] = failures[code];
+    return { code, category, recovery, diagnostic_id: diagnosticId };
+}
+export function chatFailureMessage(failure) {
+    const entry = Object.hasOwn(failures, failure.code)
+        ? failures[failure.code]
+        : failures.internal_error;
+    return `${entry[2]} Diagnostic ID: ${failure.diagnostic_id}`;
+}
+// Allowlisted error facts only; neither error.message nor diagnostic callbacks
+// establish business truth. Unknown failures remain non-automatically-retryable.
+export function classifyChatFailure(error, diagnosticId) {
+    const value = typeof error === "object" && error !== null
+        ? error
+        : {};
+    const code = typeof value.code === "string" ? value.code : value.reason;
+    const mapped = typeof code === "string" && Object.hasOwn(failures, code)
+        ? code
+        : (providerFailureCode(error) ?? "internal_error");
+    return chatFailure(mapped, diagnosticId);
+}
+//# sourceMappingURL=failures.js.map

package/dist/chat-assistant/index.d.ts

@@ -1,4 +1,4 @@
-import type { ProjectId } from "@tutti/shared/ids";
+import { type ProjectId } from "@tutti/shared/ids";
 import type { MessageProjection } from "@tutti/shared/schemas/api";
 import { type ChatAssistantLogger } from "./diagnostics.js";
 import type { ProviderInvocationProgressObserver } from "../providers/invocation-progress.js";
@@ -33,6 +33,7 @@ export type ReadOnlyChatAssistantEnqueueResult = {
     triggered: boolean;
 };
 export type ReadOnlyChatAssistantHandle = {
+    register: (tx: SqliteDatabase, message: MessageProjection) => void;
     enqueue: (input: ReadOnlyChatAssistantTriggerInput) => ReadOnlyChatAssistantEnqueueResult;
     waitForIdle: () => Promise<void>;
     stopAccepting: () => void;
@@ -62,16 +63,26 @@ export declare function isChatAssistantOutput(value: unknown): value is ChatAssi
 export declare function containsTuttiMention(value: string): boolean;
 export declare class ReadOnlyChatAssistant implements ReadOnlyChatAssistantHandle {
     private readonly options;
-    private readonly pending;
     private readonly idleWaiters;
     private active;
     private accepting;
     private readonly maxQueuedMentions;
+    private recoveryTimer;
+    private started;
+    private activeAttemptRef;
+    private storageFailureReported;
     constructor(options: ReadOnlyChatAssistantOptions);
+    /** Call once after Host recovery/transport wiring. No old messages are backfilled. */
+    start(): void;
+    register(tx: SqliteDatabase, message: MessageProjection): void;
+    private now;
+    private report;
     enqueue(input: ReadOnlyChatAssistantTriggerInput): ReadOnlyChatAssistantEnqueueResult;
     waitForIdle(): Promise<void>;
     stopAccepting(): void;
     private pump;
+    private reportStorageFailure;
+    private pumpNext;
     private resolveIdleIfNeeded;
     private buildMainChatContext;
     private buildClarificationRoundContext;
@@ -80,6 +91,7 @@ export declare class ReadOnlyChatAssistant implements ReadOnlyChatAssistantHandl
     private appendMainChatAssistantMessage;
     private appendClarificationRoundAssistantMessage;
     private appendAssistantMessageForTrigger;
+    private recordReply;
     private respond;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/chat-assistant/index.js

@@ -1,3 +1,5 @@
+import { linkChatRequestInvocation } from "./requests.js";
+import { createEventRef, ID_PREFIXES, isPrefixedId, } from "@tutti/shared/ids";
 import { createChatAssistantDiagnostics } from "./diagnostics.js";
 import { createClarificationRoundAgentMessage, createMainChatAgentMessage, readClarificationRoundMessagesWindow, readClarificationRoundProjection, readMainChatMessageWindow, readMainChatMessagesBeforeCursor, readMessageProjectionById, } from "../collaboration-state/index.js";
 import { renderLanguageAwarePrompt } from "../communication-language/prompt.js";
@@ -7,6 +9,8 @@ import { withHostStoreTransaction, } from "../store/index.js";
 import { messageTextForModel, messageTextForTuttiMention, } from "../collaboration-state/message-context.js";
 import { externalReferenceMessageContext } from "../reference-access/message-context.js";
 import { readExternalReferenceReadSources } from "../reference-access/read-evidence.js";
+import { chatFailure, chatFailureMessage, classifyChatFailure } from "./failures.js";
+import { countQueuedChatRequests, insertChatRequest, listRunningChatRequests, nextQueuedChatRequest, readChatRequest, updateChatRequest, } from "./requests.js";
 const CHAT_ASSISTANT_CONTEXT_MESSAGE_LIMIT = 3;
 const CHAT_ASSISTANT_ROUND_MESSAGE_LIMIT = 50;
 const CHAT_ASSISTANT_ROUND_MESSAGE_MAX_CHARS = 2_000;
@@ -45,9 +49,6 @@ function normalizeAnswer(answer) {
     }
     return `${trimmed.slice(0, CHAT_ASSISTANT_MAX_ANSWER_CHARS - 3)}...`;
 }
-function assistantFailureMessage() {
-    return "Tutti could not complete this read-only answer. Try again later, or add more context in chat.";
-}
 function messageToContext(message) {
     const authorDisplayName = message.author.display_name?.trim();
     return {
@@ -105,46 +106,112 @@ function roundMessagesToContext(messages) {
 }
 export class ReadOnlyChatAssistant {
     options;
-    pending = [];
     idleWaiters = new Set();
     active = null;
     accepting = true;
     maxQueuedMentions;
+    recoveryTimer;
+    started = false;
+    activeAttemptRef;
+    storageFailureReported = false;
     constructor(options) {
         this.options = options;
-        this.maxQueuedMentions = options.maxQueuedMentions ?? 8;
+        this.maxQueuedMentions = Math.max(1, options.maxQueuedMentions ?? 8);
     }
-    enqueue(input) {
-        if (input.message.author.kind !== "human" &&
-            !(input.message.author.kind === "system" && input.message.refs?.development_operator === true)) {
-            return { triggered: false };
-        }
-        if (!containsTuttiMention(messageTextForTuttiMention(input.message))) {
-            return { triggered: false };
-        }
-        if (!this.accepting) {
-            return { triggered: false };
+    /** Call once after Host recovery/transport wiring. No old messages are backfilled. */
+    start() {
+        if (this.started || !this.accepting)
+            return;
+        this.started = true;
+        for (const row of listRunningChatRequests(this.options.store.db)) {
+            if (row.attempt_ref === this.activeAttemptRef)
+                continue;
+            if (row.phase === "workspace_wait") {
+                updateChatRequest(this.options.store.db, row, { status: "queued", phase: "queue" }, this.now());
+                continue;
+            }
+            const failure = chatFailure("host_restarted");
+            const recovered = updateChatRequest(this.options.store.db, row, {
+                status: "failed",
+                phase: "settled",
+                failure,
+            }, this.now());
+            const message = readMessageProjectionById(this.options.store.db, row.trigger_message_id);
+            if (recovered && message) {
+                this.report(message, recovered)({ stage: "failed", error_code: "host_restarted", diagnostic_id: failure.diagnostic_id });
+                try {
+                    this.appendAssistantMessageForTrigger(message, chatFailureMessage(failure), recovered, failure);
+                }
+                catch {
+                    this.report(message, recovered)({ stage: "failed", reason_code: "reply_failed" });
+                }
+            }
         }
-        const report = createChatAssistantDiagnostics({
+        // A lost post-commit wake must not strand a durable queued request.
+        this.recoveryTimer = setInterval(() => this.pump(), 1_000);
+        this.recoveryTimer.unref?.();
+        this.pump();
+    }
+    register(tx, message) {
+        if (!this.accepting ||
+            (message.author.kind !== "human" &&
+                !(message.author.kind === "system" && message.refs?.development_operator === true)) ||
+            !containsTuttiMention(messageTextForTuttiMention(message)) ||
+            readChatRequest(tx, message.id) !== null)
+            return;
+        insertChatRequest(tx, message.id, this.now(), countQueuedChatRequests(tx) >= this.maxQueuedMentions
+            ? chatFailure("chat_queue_full")
+            : undefined);
+    }
+    now() {
+        return (this.options.now?.() ?? new Date()).toISOString();
+    }
+    report(message, request) {
+        return createChatAssistantDiagnostics({
             ...(this.options.logger === undefined ? {} : { logger: this.options.logger }),
             projectId: this.options.project.project_id,
-            triggerMessageId: input.message.id,
-            scope: input.message.scope.kind,
+            triggerMessageId: message.id,
+            scope: message.scope.kind,
+            requestRef: message.id,
+            ...(request.attempt_ref === null ? {} : { attemptRef: request.attempt_ref }),
         });
-        if (this.pending.length >= this.maxQueuedMentions) {
-            report({ stage: "failed", reason_code: "queue_full" });
-            this.appendAssistantMessageForTrigger(input.message, assistantFailureMessage(), {
-                scratchpad_source: "exclude",
+    }
+    enqueue(input) {
+        if (!this.accepting)
+            return { triggered: false };
+        withHostStoreTransaction(this.options.store.db, (tx) => this.register(tx, input.message));
+        const request = readChatRequest(this.options.store.db, input.message.id);
+        if (request === null)
+            return { triggered: false };
+        if (request.status === "failed" &&
+            request.response_message_id === null &&
+            request.failure_json !== null) {
+            const report = this.report(input.message, request);
+            const failure = JSON.parse(request.failure_json);
+            report({
+                stage: "failed",
+                reason_code: failure.code === "chat_queue_full" ? "queue_full" : "reply_failed",
+                diagnostic_id: failure.diagnostic_id,
             });
+            try {
+                this.appendAssistantMessageForTrigger(input.message, chatFailureMessage(failure), request, failure);
+            }
+            catch {
+                // The original message and failed request are already accepted.
+                report({
+                    stage: "notification_failed",
+                    reason_code: "reply_failed",
+                    diagnostic_id: failure.diagnostic_id,
+                });
+            }
             return { triggered: true };
         }
-        report({ stage: "queued" });
-        this.pending.push({ message: input.message, report });
         this.pump();
         return { triggered: true };
     }
     async waitForIdle() {
-        if (this.active === null && this.pending.length === 0) {
+        if (this.active === null &&
+            (!this.accepting || nextQueuedChatRequest(this.options.store.db) === null)) {
             return;
         }
         await new Promise((resolve) => this.idleWaiters.add(resolve));
@@ -154,36 +221,102 @@ export class ReadOnlyChatAssistant {
             return;
         }
         this.accepting = false;
-        for (const { message, report } of this.pending.splice(0)) {
-            report({ stage: "skipped", reason_code: "stopping" });
-            this.appendAssistantMessageForTrigger(message, assistantFailureMessage(), {
-                scratchpad_source: "exclude",
-            });
-        }
+        if (this.recoveryTimer !== undefined)
+            clearInterval(this.recoveryTimer);
         this.resolveIdleIfNeeded();
     }
     pump() {
-        if (this.active !== null) {
+        try {
+            this.pumpNext();
+            this.storageFailureReported = false;
+        }
+        catch {
+            this.reportStorageFailure();
+        }
+    }
+    reportStorageFailure() {
+        if (this.storageFailureReported)
+            return;
+        this.storageFailureReported = true;
+        try {
+            this.options.logger?.warn({
+                project_id: this.options.project.project_id,
+                stage: "queue_storage_failed",
+                diagnostic_id: createEventRef(),
+            }, "Chat request queue storage unavailable");
+        }
+        catch {
+            /* Diagnostics cannot replace durable recovery. */
+        }
+    }
+    pumpNext() {
+        if (this.active !== null)
+            return;
+        if (!this.accepting) {
+            this.resolveIdleIfNeeded();
             return;
         }
-        const pending = this.pending.shift();
-        if (pending === undefined) {
+        const pending = nextQueuedChatRequest(this.options.store.db);
+        if (pending === null) {
             this.resolveIdleIfNeeded();
             return;
         }
-        const task = this.respond(pending.message, pending.report).catch(() => {
-            pending.report({ stage: "failed", reason_code: "reply_failed" });
+        const request = updateChatRequest(this.options.store.db, pending, {
+            status: "running",
+            phase: "workspace_wait",
+            attemptRef: createEventRef(),
+        }, this.now());
+        if (request === null)
+            return;
+        this.activeAttemptRef = request.attempt_ref;
+        const message = readMessageProjectionById(this.options.store.db, request.trigger_message_id);
+        if (message === null)
+            throw new Error("chat_request_source_missing");
+        const report = this.report(message, request);
+        report({ stage: "queued" });
+        const task = this.respond(message, request, report).catch(() => {
+            // Do not overwrite a committed success when only notification delivery failed.
+            try {
+                const current = readChatRequest(this.options.store.db, message.id);
+                if (current?.status === "running" && current.attempt_ref === request.attempt_ref) {
+                    const failure = chatFailure("chat_reply_persistence_failed", request.attempt_ref);
+                    updateChatRequest(this.options.store.db, current, {
+                        status: "failed",
+                        phase: "settled",
+                        failure,
+                    }, this.now());
+                    report({
+                        stage: "failed",
+                        reason_code: "reply_failed",
+                        error_code: "chat_reply_persistence_failed",
+                        diagnostic_id: failure.diagnostic_id,
+                    });
+                }
+                else if (current !== null &&
+                    current.response_message_id !== null &&
+                    current.attempt_ref === request.attempt_ref) {
+                    report({ stage: "notification_failed", reason_code: "reply_failed" });
+                }
+                else {
+                    report({ stage: "skipped", reason_code: "request_changed" });
+                }
+            }
+            catch {
+                this.reportStorageFailure();
+            }
         });
         this.active = task;
         void task.finally(() => {
             if (this.active === task) {
                 this.active = null;
+                this.activeAttemptRef = undefined;
                 this.pump();
             }
         });
     }
     resolveIdleIfNeeded() {
-        if (this.active !== null || this.pending.length !== 0) {
+        if (this.active !== null ||
+            (this.accepting && nextQueuedChatRequest(this.options.store.db) !== null)) {
             return;
         }
         for (const resolve of this.idleWaiters) {
@@ -263,7 +396,7 @@ export class ReadOnlyChatAssistant {
             },
         }, language);
     }
-    appendMainChatAssistantMessage(triggerMessage, body, refs) {
+    appendMainChatAssistantMessage(triggerMessage, body, request, failure, refs) {
         let afterCommit;
         const message = withHostStoreTransaction(this.options.store.db, (tx) => {
             const responseMessage = createMainChatAgentMessage(tx, {
@@ -279,6 +412,7 @@ export class ReadOnlyChatAssistant {
             if (typeof callback === "function") {
                 afterCommit = callback;
             }
+            this.recordReply(tx, request, responseMessage.id, failure);
             return responseMessage;
         });
         afterCommit?.();
@@ -310,6 +444,7 @@ export class ReadOnlyChatAssistant {
             });
             if (typeof callback === "function")
                 afterCommit = callback;
+            this.recordReply(tx, input.request, responseMessage.id, input.failure);
             return responseMessage;
         });
         afterCommit?.();
@@ -332,36 +467,75 @@ export class ReadOnlyChatAssistant {
             invalidates,
         });
     }
-    appendAssistantMessageForTrigger(triggerMessage, body, refs) {
+    appendAssistantMessageForTrigger(triggerMessage, body, request, failure, refs) {
+        if (failure !== undefined)
+            refs = { ...refs, scratchpad_source: "exclude" };
         if (triggerMessage.scope.kind === "clarification_round") {
             this.appendClarificationRoundAssistantMessage({
                 triggerMessage,
                 roundId: triggerMessage.scope.clarification_round_ref,
                 body,
+                request,
+                ...(failure === undefined ? {} : { failure }),
                 ...(refs === undefined ? {} : { refs }),
             });
             return;
         }
-        this.appendMainChatAssistantMessage(triggerMessage, body, refs);
+        this.appendMainChatAssistantMessage(triggerMessage, body, request, failure, refs);
+    }
+    recordReply(tx, request, messageId, failure) {
+        if (!updateChatRequest(tx, request, {
+            status: failure ? "failed" : "succeeded",
+            phase: "settled",
+            responseMessageId: messageId,
+            ...(failure === undefined ? {} : { failure }),
+        }, this.now()))
+            throw new Error("chat_request_changed");
     }
-    async respond(triggerMessage, report) {
+    async respond(triggerMessage, request, report) {
         let answer;
         let invocationRef;
         let readSources = [];
         try {
             report({ stage: "inspection_wait" });
             await this.options.waitForInspectionAvailability?.();
+            if (!this.accepting) {
+                updateChatRequest(this.options.store.db, request, { status: "queued", phase: "queue" }, this.now());
+                return;
+            }
             const prompt = this.renderPrompt(triggerMessage, report);
             if (prompt === null) {
                 report({ stage: "skipped", reason_code: "context_unavailable" });
+                updateChatRequest(this.options.store.db, request, {
+                    status: "failed",
+                    phase: "settled",
+                    failure: chatFailure("chat_context_unavailable", request.attempt_ref),
+                }, this.now());
                 return;
             }
+            const executing = updateChatRequest(this.options.store.db, request, {
+                status: "running",
+                phase: "answer",
+            }, this.now());
+            if (executing === null)
+                return;
+            request = executing;
             report({ stage: "model_requested" });
             const output = await this.options.model.answer({
                 prompt,
                 onProgress: (event) => {
-                    if (event.stage === "context_ready")
-                        invocationRef = event.invocation_ref;
+                    if (event.stage === "context_ready") {
+                        if (typeof event.invocation_ref === "string" &&
+                            isPrefixedId(event.invocation_ref, ID_PREFIXES.event)) {
+                            invocationRef = event.invocation_ref;
+                            try {
+                                linkChatRequestInvocation(this.options.store.db, request, invocationRef);
+                            }
+                            catch {
+                                report({ stage: "notification_failed" });
+                            }
+                        }
+                    }
                     report(event);
                 },
             });
@@ -370,16 +544,20 @@ export class ReadOnlyChatAssistant {
                 readSources = readExternalReferenceReadSources(this.options.store.db, invocationRef);
             }
         }
-        catch {
-            report({ stage: "failed", reason_code: "answer_failed" });
-            this.appendAssistantMessageForTrigger(triggerMessage, assistantFailureMessage(), {
-                scratchpad_source: "exclude",
+        catch (error) {
+            const failure = classifyChatFailure(error, request.attempt_ref);
+            report({
+                stage: "failed",
+                reason_code: "answer_failed",
+                error_code: failure.code,
+                diagnostic_id: failure.diagnostic_id,
             });
+            this.appendAssistantMessageForTrigger(triggerMessage, chatFailureMessage(failure), request, failure);
             report({ stage: "reply_persisted" });
             return;
         }
         // Persistence/outbound-hook failure must not retry by creating a second reply.
-        this.appendAssistantMessageForTrigger(triggerMessage, answer, readSources.length === 0 ? undefined : { external_reference_reads: readSources });
+        this.appendAssistantMessageForTrigger(triggerMessage, answer, request, undefined, readSources.length === 0 ? undefined : { external_reference_reads: readSources });
         report({ stage: "reply_persisted", reference_source_count: readSources.length });
     }
 }