Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: keep Gmail delivery unknown after a lost send acknowledgement (#10715)

Adam Eivy515b62fe4cd9
diff --git a/docs/features/messages-browser-send.md b/docs/features/messages-browser-send.md
index 197e6725b3..16c5bbd95c 100644
--- a/docs/features/messages-browser-send.md
+++ b/docs/features/messages-browser-send.md
@@ -1,6 +1,6 @@
# Outlook and Teams draft delivery
-Approved drafts for Outlook and Teams accounts are delivered by driving the web UI in the PortOS browser tab you are already signed into. Gmail still sends through its API. This page is the contract for the browser path; the code is `server/lib/messageBrowserCompose.js` (pure planning, scripts and judging) and `sendPlaywright` in `server/services/messagePlaywrightSync.js` (the I/O).
+Approved drafts for Outlook and Teams accounts are delivered by driving the web UI in the PortOS browser tab you are already signed into. Gmail still sends through its API, under the same certainty rule: a 2xx is sent, a Gmail 4xx refusal or a failed token refresh is a definite failure, and a timeout, dropped connection or 5xx is `delivery_unknown` — the API client never retries the send (`sendGmail` in `server/services/messageGmailSync.js`). This page is the contract for the browser path; the code is `server/lib/messageBrowserCompose.js` (pure planning, scripts and judging) and `sendPlaywright` in `server/services/messagePlaywrightSync.js` (the I/O).
## Live validation status
diff --git a/server/lib/messageLogError.js b/server/lib/messageLogError.js
index 7edf269386..07b8a87121 100644
--- a/server/lib/messageLogError.js
+++ b/server/lib/messageLogError.js
@@ -2,7 +2,8 @@
// Never include free text, stacks or arbitrary provider codes in operational logs.
const SAFE_CODES = new Set([
'ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT',
- 'ABORT_ERR', 'SEND_FAILED', 'GMAIL_SEND_FAILED', 'GMAIL_NOT_CONFIGURED'
+ 'ABORT_ERR', 'SEND_FAILED', 'GMAIL_SEND_FAILED', 'GMAIL_NOT_CONFIGURED',
+ 'GMAIL_AUTH_FAILED'
]);
export function messageLogError(error) {
diff --git a/server/services/messageGmailSync.js b/server/services/messageGmailSync.js
index 0e8f397881..3904b589ff 100644
--- a/server/services/messageGmailSync.js
+++ b/server/services/messageGmailSync.js
@@ -382,11 +382,28 @@ export async function syncGmail(account, cache, io, options = {}) {
return { messages: inboxMessages, inboxComplete, sentMessages, sentTruncated: sentCoveragePartial, sendAsAliases, status: 'success', syncMethod: 'api' };
}
+// `users.messages.send` carries no idempotency key, so once the request may have
+// reached Gmail only a 2xx proves delivery and only a 4xx proves refusal. A lost
+// acknowledgement (timeout, reset socket, 5xx after acceptance) cannot say
+// whether the message left — report it as unknown so the draft is parked for
+// reconciliation, never as a `failed` draft that can be re-approved and resent.
+const GMAIL_DELIVERY_UNKNOWN = {
+ success: false,
+ deliveryUnknown: true,
+ status: 502,
+ code: 'DELIVERY_UNKNOWN',
+ error: 'Gmail did not confirm delivery and it may already have been sent. Check Sent Mail, then record the outcome. PortOS will not resend it.'
+};
+
+// A 4xx is Gmail refusing the request, so nothing was sent. 408 is excluded: it
+// is a timeout, which is exactly the ambiguity this classification exists for.
+const isDefinitiveRefusal = (status) => Number.isInteger(status) && status >= 400 && status < 500 && status !== 408;
+
/**
* Send email via Gmail API.
* @param {object} account - Account config
* @param {object} draft - Draft with to, cc, subject, body
- * @returns {{ success: boolean, error?: string }}
+ * @returns {{ success: boolean, deliveryUnknown?: boolean, error?: string }}
*/
export async function sendGmail(account, draft) {
const auth = await getAuthenticatedClient();
@@ -394,6 +411,14 @@ export async function sendGmail(account, draft) {
return { success: false, error: 'Google OAuth not configured', status: 502, code: 'GMAIL_NOT_CONFIGURED' };
}
+ // Refresh the access token before dispatch, so a token failure is a definite
+ // "not sent" rather than an error from inside the send call.
+ const tokenError = await auth.getAccessToken().then(() => null, err => err);
+ if (tokenError) {
+ console.error(`📧 Gmail send failed before dispatch: draft ${draft.id}: ${messageLogError(tokenError)}`);
+ return { success: false, error: 'Google sign-in could not be refreshed — nothing was sent', status: 502, code: 'GMAIL_AUTH_FAILED' };
+ }
+
const gmailClient = gmail({ version: 'v1', auth });
// Build RFC 2822 message
@@ -417,16 +442,20 @@ export async function sendGmail(account, draft) {
const raw = Buffer.from(lines.join('\r\n')).toString('base64url');
- const result = await gmailClient.users.messages.send({
+ // `retry: false`: the client must never resubmit a send on its own — a retry
+ // after a lost acknowledgement is a duplicate message.
+ const sendError = await gmailClient.users.messages.send({
userId: 'me',
requestBody: { raw }
- }).catch(err => {
- console.error(`📧 Gmail send failed: ${messageLogError(err)}`);
- return null;
- });
+ }, { retry: false }).then(() => null, err => err);
- if (!result) {
- return { success: false, error: 'Gmail API send failed', status: 502, code: 'GMAIL_SEND_FAILED' };
+ if (sendError) {
+ if (isDefinitiveRefusal(sendError.response?.status)) {
+ console.error(`📧 Gmail send failed: draft ${draft.id}: ${messageLogError(sendError)}`);
+ return { success: false, error: 'Gmail refused the message — nothing was sent', status: 502, code: 'GMAIL_SEND_FAILED' };
+ }
+ console.warn(`⚠️ Gmail delivery unconfirmed: draft ${draft.id}: ${messageLogError(sendError)}`);
+ return GMAIL_DELIVERY_UNKNOWN;
}
console.log(`📧 Gmail sent: draft ${draft.id}`);
diff --git a/server/services/messageGmailSync.send.test.js b/server/services/messageGmailSync.send.test.js
new file mode 100644
index 0000000000..351488ac25
--- /dev/null
+++ b/server/services/messageGmailSync.send.test.js
@@ -0,0 +1,144 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { join } from 'path';
+import { auth as googleAuth } from '@googleapis/gmail';
+
+// Gmail send workflow through the REAL sender, draft store, Gmail adapter and
+// Google API client. Only the network is stubbed (the auth client's fetch), so
+// the count of captured submissions is what Gmail would actually have received,
+// including any resubmission the client library might attempt on its own (#10715).
+const doubles = vi.hoisted(() => ({ files: new Map(), auth: null, getAccount: vi.fn() }));
+vi.mock('../lib/fileUtils.js', () => ({
+ PATHS: { messages: '/mock/messages' },
+ ensureDir: async () => {},
+ tryReadFile: async path => doubles.files.get(path) ?? null,
+ atomicWrite: async (path, data) => { doubles.files.set(path, JSON.stringify(data)); },
+ safeJSONParse: JSON.parse
+}));
+vi.mock('./messageAccounts.js', () => ({ getAccount: doubles.getAccount, listAccounts: async () => [] }));
+vi.mock('./googleAuth.js', () => ({ getAuthenticatedClient: async () => doubles.auth }));
+
+import { sendDraft } from './messageSender.js';
+import { getDraft, approveDraft, updateDraft, deleteDraft, reconcileDraftSend } from './messageDrafts.js';
+
+const SEND_URL = 'gmail.googleapis.com/gmail/v1/users/me/messages/send';
+const json = (status, body) => new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
+const timeout = () => Object.assign(new Error('Example acknowledgement lost'), { code: 'ETIMEDOUT' });
+
+let network;
+let submissions;
+function authClient({ expired = false } = {}) {
+ const client = new googleAuth.OAuth2({
+ clientId: 'example-client', clientSecret: 'example-secret',
+ transporterOptions: { fetchImplementation: async (url, init) => network(String(url), init) }
+ });
+ client.setCredentials({ access_token: 'example-token', refresh_token: 'example-refresh', expiry_date: expired ? 1 : Date.now() + 3_600_000 });
+ return client;
+}
+// The provider captures the submission first, then answers with `respond` — a
+// throw models an acknowledgement lost after Gmail may already have accepted it.
+function gmailAnswers(respond) {
+ network = async (url, init) => {
+ if (url.includes(SEND_URL)) submissions.push(init);
+ return respond(url);
+ };
+}
+function seed(id) {
+ doubles.files.set(join('/mock/messages', 'drafts.json'), JSON.stringify([{
+ id, accountId: 'account-1', status: 'approved', sendVia: 'api', to: ['[email protected]'], subject: 'Example subject', body: 'Example message'
+ }]));
+}
+
+beforeEach(() => {
+ doubles.files.clear();
+ doubles.auth = authClient();
+ doubles.getAccount.mockResolvedValue({ id: 'account-1', type: 'gmail' });
+ submissions = [];
+ vi.spyOn(console, 'log').mockImplementation(() => {});
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+});
+
+describe('Gmail draft send delivery certainty', () => {
+ it.each([
+ ['a timed-out acknowledgement', () => { throw timeout(); }],
+ ['a reset socket', () => { throw Object.assign(new Error('Example reset'), { code: 'ECONNRESET' }); }],
+ ['a server error after submission', () => json(503, { error: { code: 503, message: 'Example backend error' } })],
+ ['a request timeout status', () => json(408, { error: { code: 408, message: 'Example timeout' } })]
+ ])('parks %s as unknown, submits once, and blocks every resend until reconciled', async (_label, respond) => {
+ seed('draft-1');
+ gmailAnswers(respond);
+ expect(await sendDraft('draft-1')).toMatchObject({ success: false, status: 502, code: 'DELIVERY_UNKNOWN' });
+ const unknown = await getDraft('draft-1');
+ expect(unknown.status).toBe('delivery_unknown');
+ expect(unknown.sendAttempts).toEqual([expect.objectContaining({ id: unknown.sendAttemptId, outcome: 'delivery_unknown' })]);
+ expect(submissions).toHaveLength(1);
+
+ // Every path that could submit it again stays closed, even once Gmail is healthy.
+ gmailAnswers(() => json(200, { id: 'example-message' }));
+ expect(await sendDraft('draft-1')).toMatchObject({ status: 409 });
+ await expect(approveDraft('draft-1')).rejects.toMatchObject({ status: 409 });
+ await expect(updateDraft('draft-1', { status: 'approved' })).rejects.toMatchObject({ status: 409 });
+ await expect(deleteDraft('draft-1')).rejects.toMatchObject({ status: 409 });
+ expect(await sendDraft('draft-1')).toMatchObject({ status: 409 });
+ expect(submissions).toHaveLength(1);
+ });
+
+ it('closes an unknown send confirmed in Sent Mail without submitting again', async () => {
+ seed('draft-1');
+ gmailAnswers(() => { throw timeout(); });
+ await sendDraft('draft-1');
+ const { sendAttemptId } = await getDraft('draft-1');
+ expect((await reconcileDraftSend('draft-1', { attemptId: sendAttemptId, outcome: 'sent' })).status).toBe('sent');
+ await expect(approveDraft('draft-1')).rejects.toMatchObject({ status: 409 });
+ expect(await sendDraft('draft-1')).toMatchObject({ status: 409 });
+ expect(submissions).toHaveLength(1);
+ });
+
+ it('reopens an unknown send confirmed absent from Sent Mail for one explicit resend', async () => {
+ seed('draft-1');
+ gmailAnswers(() => { throw timeout(); });
+ await sendDraft('draft-1');
+ const { sendAttemptId } = await getDraft('draft-1');
+ expect((await reconcileDraftSend('draft-1', { attemptId: sendAttemptId, outcome: 'not_sent' })).status).toBe('draft');
+ await approveDraft('draft-1');
+ gmailAnswers(() => json(200, { id: 'example-message' }));
+ expect(await sendDraft('draft-1')).toEqual({ success: true });
+ expect((await getDraft('draft-1')).status).toBe('sent');
+ expect(submissions).toHaveLength(2);
+ });
+
+ it('keeps a proven Gmail refusal a definite, re-approvable failure', async () => {
+ seed('draft-1');
+ gmailAnswers(() => json(400, { error: { code: 400, message: 'Example invalid recipient' } }));
+ expect(await sendDraft('draft-1')).toMatchObject({ success: false, code: 'GMAIL_SEND_FAILED' });
+ expect((await getDraft('draft-1')).status).toBe('failed');
+ expect(submissions).toHaveLength(1);
+ await approveDraft('draft-1');
+ gmailAnswers(() => json(200, { id: 'example-message' }));
+ expect(await sendDraft('draft-1')).toEqual({ success: true });
+ expect(submissions).toHaveLength(2);
+ });
+
+ it.each([
+ ['OAuth is not configured', () => { doubles.auth = null; }, 'GMAIL_NOT_CONFIGURED'],
+ ['the access token cannot be refreshed', () => {
+ doubles.auth = authClient({ expired: true });
+ network = async () => json(400, { error: 'invalid_grant' });
+ }, 'GMAIL_AUTH_FAILED']
+ ])('fails definitely without contacting Gmail when %s', async (_label, arrange, code) => {
+ seed('draft-1');
+ gmailAnswers(() => json(200, { id: 'example-message' }));
+ arrange();
+ expect(await sendDraft('draft-1')).toMatchObject({ success: false, code });
+ expect((await getDraft('draft-1')).status).toBe('failed');
+ expect(submissions).toHaveLength(0);
+ });
+
+ it('marks a confirmed send as sent', async () => {
+ seed('draft-1');
+ gmailAnswers(() => json(200, { id: 'example-message', threadId: 'example-thread' }));
+ expect(await sendDraft('draft-1')).toEqual({ success: true });
+ expect((await getDraft('draft-1')).status).toBe('sent');
+ expect(submissions).toHaveLength(1);
+ });
+});
diff --git a/server/services/messageLogging.test.js b/server/services/messageLogging.test.js
index da29e853eb..a2be0645c6 100644
--- a/server/services/messageLogging.test.js
+++ b/server/services/messageLogging.test.js
@@ -26,7 +26,7 @@ vi.mock('../lib/fileUtils.js', async (original) => ({
atomicWrite: async (path, value) => { doubles.files.set(path, JSON.stringify(value)); }
}));
vi.mock('./readinessNotify.js', () => ({ noteReadinessChanged: () => {} }));
-vi.mock('./googleAuth.js', () => ({ getAuthenticatedClient: async () => ({}) }));
+vi.mock('./googleAuth.js', () => ({ getAuthenticatedClient: async () => ({ getAccessToken: async () => ({ token: 'synthetic-token' }) }) }));
vi.mock('@googleapis/gmail', () => ({
gmail: () => ({ users: {
messages: { send: doubles.send, list: doubles.list, get: doubles.get, trash: doubles.trash, modify: doubles.modify },
diff --git a/server/services/messageSender.js b/server/services/messageSender.js
index c8b8df8777..685f01ca6c 100644
--- a/server/services/messageSender.js
+++ b/server/services/messageSender.js
@@ -60,9 +60,17 @@ export async function sendDraft(draftId, io) {
};
const complete = async () => {
+ // An adapter reports a definite "not sent" by returning it. A throw after
+ // dispatch began proves nothing about whether the message left, so it is
+ // parked as unknown rather than downgraded to a re-approvable failure.
const result = await dispatch().catch(async (error) => {
- console.error(`📧 Draft send threw for ${draft.id}: ${messageLogError(error)}`);
- return { success: false, status: 502, code: 'SEND_FAILED', error: error.message };
+ console.warn(`⚠️ Draft send threw for ${draft.id}: ${messageLogError(error)}`);
+ return {
+ success: false,
+ deliveryUnknown: true,
+ status: 502,
+ error: 'The send failed after it started, so PortOS cannot tell whether the message left. Check the Sent folder, then record the outcome. PortOS will not resend it.'
+ };
});
if (result?.success) {
diff --git a/server/services/messageSender.test.js b/server/services/messageSender.test.js
index e1bc363739..9147ff6712 100644
--- a/server/services/messageSender.test.js
+++ b/server/services/messageSender.test.js
@@ -114,12 +114,11 @@ describe('draft send workflow', () => {
expect(doubles.sendGmail).toHaveBeenCalledTimes(2);
});
- it.each(['returned', 'thrown'])('persists a %s dispatch failure and permits explicit reapproval', async kind => {
+ it('persists a returned dispatch failure and permits explicit reapproval', async () => {
seed({ id: 'draft-1', sendVia: 'playwright', to: ['[email protected]'], subject: 'Example subject' });
doubles.getAccount.mockResolvedValue({ id: 'account-1', type: 'outlook' });
doubles.listAccounts.mockResolvedValue([{ id: 'account-1', type: 'outlook' }]);
- if (kind === 'thrown') doubles.sendPlaywright.mockRejectedValueOnce(new Error('Example transport failure'));
- else doubles.sendPlaywright.mockResolvedValueOnce({ success: false, status: 502, code: 'SEND_FAILED', error: 'Example transport failure' });
+ doubles.sendPlaywright.mockResolvedValueOnce({ success: false, status: 502, code: 'SEND_FAILED', error: 'Example transport failure' });
expect(await sendDraft('draft-1')).toMatchObject({ success: false, code: 'SEND_FAILED' });
expect((await getDraft('draft-1')).status).toBe('failed');
expect(await sendDraft('draft-1')).toMatchObject({ status: 409 });
@@ -128,6 +127,16 @@ describe('draft send workflow', () => {
expect((await getDraft('draft-1')).status).toBe('sent');
});
+ it('parks a thrown dispatch as delivery unknown rather than a re-approvable failure', async () => {
+ seed({ id: 'draft-1' });
+ doubles.sendGmail.mockRejectedValueOnce(new Error('Example transport failure'));
+ expect(await sendDraft('draft-1')).toMatchObject({ success: false, status: 502, code: 'DELIVERY_UNKNOWN' });
+ expect((await getDraft('draft-1')).status).toBe('delivery_unknown');
+ await expect(approveDraft('draft-1')).rejects.toMatchObject({ status: 409 });
+ expect(await sendDraft('draft-1')).toMatchObject({ status: 409 });
+ expect(doubles.sendGmail).toHaveBeenCalledTimes(1);
+ });
+
it('rechecks eligibility after account lookup and dispatches only the claimed snapshot', async () => {
seed({ id: 'draft-1' });
doubles.getAccount.mockImplementationOnce(async () => {