ofw-mcp 2.20.2 → 2.20.4

package/dist/client.js

@@ -100,6 +100,9 @@ export class OFWClient {
     // deployment. Left undefined by the stdio path, which falls back to the
     // global resolver, keeping that behaviour byte-for-byte identical.
     authResolver;
+    // Which path minted the token currently held. Unset while the token is one
+    // the TokenManager restored from the session cache — nothing was minted.
+    mintedBy;
     constructor(opts) {
         this.authResolver = opts?.resolveAuth;
     }
@@ -111,7 +114,8 @@ export class OFWClient {
             // the expired placeholder that used to sit here would have meant the
             // cache was written but never read.
             const mint = async () => {
-                const { token, expiresAt } = await (this.authResolver ?? resolveAuth)();
+                const { token, expiresAt, source } = await (this.authResolver ?? resolveAuth)();
+                this.mintedBy = source;
                 return {
                     accessToken: token,
                     refreshToken: OFW_REFRESH_SENTINEL,
@@ -136,6 +140,22 @@ export class OFWClient {
         }
         return this.tokenManager;
     }
+    /**
+     * The credential's source and expiry, answered from the TokenManager — the
+     * same token, cache and single-flight mint every tool uses.
+     *
+     * `ofw_healthcheck` used to call `resolveAuth()` directly, which is a full
+     * login (or a fresh browser-bridge spin-up) on every healthcheck, ignoring
+     * the six-hour token already held. Going through the manager means a held or
+     * cached token costs nothing, and a mint, when one is needed, is the one the
+     * next real tool call would have made anyway. A mint failure propagates
+     * unchanged so the healthcheck can classify it.
+     */
+    async credentialStatus() {
+        const tokens = this.getTokenManager();
+        await tokens.getAccessToken();
+        return { source: this.mintedBy ?? 'cache', expiresAt: new Date(tokens.getExpiresAt()) };
+    }
     async request(method, path, body) {
         return this.fetchAuthed(method, path, body, 'application/json', async (response) => {
             const text = await response.text();

package/dist/config.js

@@ -14,10 +14,9 @@ function readCacheIdentity() {
     return readEnvVar('OFW_CACHE_IDENTITY') ?? readEnvVar('OFW_USERNAME') ?? '_default';
 }
 export function getCacheDir() {
-    const override = process.env.OFW_CACHE_DIR;
-    if (override && override.trim().length > 0)
-        return override.trim();
-    return join(homedir(), '.cache', 'ofw-mcp');
+    // readEnvVar, not process.env: it also treats an unexpanded mcpb
+    // `${user_config.*}` placeholder as unset.
+    return readEnvVar('OFW_CACHE_DIR') ?? join(homedir(), '.cache', 'ofw-mcp');
 }
 export function getCacheDbPath() {
     const identity = readCacheIdentity();

package/dist/extract/inflate.js

@@ -14,6 +14,28 @@
 // whatever the file felt like claiming.
 /** 32 MiB. Sized to fit comfortably inside a constrained memory budget. */
 export const MAX_DECOMPRESSED_BYTES = 32 * 1024 * 1024;
+/**
+ * 64 MiB: the most one DOCUMENT may decompress in total, across all its
+ * members or streams. The per-member cap alone does not bound memory: a
+ * workbook of 100 sheets that each inflate to just under 32 MiB, or a PDF
+ * whose every page references the same near-cap stream, would keep gigabytes
+ * of output alive from a few kilobytes of attachment.
+ */
+export const MAX_TOTAL_DECOMPRESSED_BYTES = 64 * 1024 * 1024;
+/** A running total of decompressed bytes for one document, shared by every read. */
+export class DecompressionBudget {
+    limit;
+    used = 0;
+    constructor(limit = MAX_TOTAL_DECOMPRESSED_BYTES) {
+        this.limit = limit;
+    }
+    /** Charge `bytes`; throws once the document's total passes the limit. */
+    charge(bytes, label) {
+        this.used += bytes;
+        if (this.used > this.limit)
+            throw new DecompressionLimitError(label, this.limit, 'total');
+    }
+}
 /**
  * Thrown when decompression is aborted for exceeding its cap. Distinct from a
  * decode failure so callers can tell "this file is hostile or absurd" from
@@ -21,19 +43,22 @@ export const MAX_DECOMPRESSED_BYTES = 32 * 1024 * 1024;
  * routinely survivable.
  */
 export class DecompressionLimitError extends Error {
-    constructor(label, limit) {
-        super(`${label} expands past the ${limit}-byte decompression cap`);
+    constructor(label, limit, scope = 'member') {
+        super(scope === 'total'
+            ? `${label} pushes the document past its ${limit}-byte total decompression cap`
+            : `${label} expands past the ${limit}-byte decompression cap`);
         this.name = 'DecompressionLimitError';
     }
 }
 /**
- * Inflate `data`, aborting if the OUTPUT exceeds `limit` bytes.
+ * Inflate `data`, aborting if the OUTPUT exceeds `limit` bytes, or pushes the
+ * document's shared `budget` (when given) past its total.
  *
  * `deflate-raw` is the ZIP member format; `deflate` is the zlib-wrapped form a
  * PDF `/FlateDecode` stream uses. Both go through the WHATWG
  * `DecompressionStream` so this runs unchanged wherever the standard exists.
  */
-export async function inflateBounded(data, format, limit, label) {
+export async function inflateBounded(data, format, limit, label, budget) {
     const stream = new Blob([data]).stream()
         .pipeThrough(new DecompressionStream(format));
     const reader = stream.getReader();
@@ -49,6 +74,13 @@ export async function inflateBounded(data, format, limit, label) {
             await reader.cancel();
             throw new DecompressionLimitError(label, limit);
         }
+        try {
+            budget?.charge(value.length, label);
+        }
+        catch (err) {
+            await reader.cancel();
+            throw err;
+        }
         chunks.push(value);
     }
     return Buffer.concat(chunks);

package/dist/extract/pdf.js

@@ -9,7 +9,7 @@
 // What it must never do is fail silently. A scanned PDF has no text layer at
 // all, and the honest answer for one is `textLayer: false` plus a note saying
 // it needs OCR — not an empty string that reads like an empty document.
-import { inflateBounded, DecompressionLimitError, MAX_DECOMPRESSED_BYTES, } from './inflate.js';
+import { inflateBounded, DecompressionBudget, DecompressionLimitError, MAX_DECOMPRESSED_BYTES, } from './inflate.js';
 const OBJ_HEADER = /(\d+)\s+\d+\s+obj\b/g;
 function parseObjects(text) {
     const objects = new Map();
@@ -79,19 +79,21 @@ function streamBytes(bytes, obj) {
     return bytes.subarray(from, end === -1 ? undefined : end);
 }
 /** Decode a stream's bytes, honouring FlateDecode. Null for filters we can't read. */
-async function decodeStream(bytes, obj) {
+async function decodeStream(bytes, obj, budget) {
     const raw = streamBytes(bytes, obj);
     if (!raw)
         return null;
     const filter = /\/Filter\s*(\/\w+|\[[^\]]*\])/.exec(obj.body)?.[1] ?? '';
-    if (filter === '')
+    if (filter === '') {
+        budget.charge(raw.length, 'PDF stream');
         return raw;
+    }
     if (!filter.includes('FlateDecode'))
         return null; // LZW/DCT/JPX: not text anyway
     try {
         // PDF stream dictionaries say nothing about inflated length, so the cap is
         // the only thing standing between a crafted stream and the memory budget.
-        return await inflateBounded(raw, 'deflate', MAX_DECOMPRESSED_BYTES, 'PDF stream');
+        return await inflateBounded(raw, 'deflate', MAX_DECOMPRESSED_BYTES, 'PDF stream', budget);
     }
     catch (err) {
         // A truncated or mis-bounded stream must not take the whole document down;
@@ -245,6 +247,7 @@ export async function extractPdf(bytes, opts = {}) {
     const pageObjects = orderedPages(objects);
     if (pageObjects.length === 0)
         throw new Error('no pages found in the PDF');
+    const budget = new DecompressionBudget(opts.maxTotalDecompressedBytes);
     const pages = [];
     const omitted = [];
     for (let i = 0; i < pageObjects.length; i++) {
@@ -259,7 +262,7 @@ export async function extractPdf(bytes, opts = {}) {
             const streamObj = objects.get(ref);
             if (!streamObj)
                 continue;
-            const decoded = await decodeStream(bytes, streamObj);
+            const decoded = await decodeStream(bytes, streamObj, budget);
             if (decoded)
                 raw += `${decoded.toString('latin1')}\n`;
         }

package/dist/extract/zip.js

@@ -9,7 +9,7 @@
 // same code runs on the stdio server and a hosted deployment. Using
 // `node:zlib` here would tie this to Node; adding a userland inflate
 // dependency would bloat it. Neither is necessary.
-import { inflateBounded, MAX_DECOMPRESSED_BYTES } from './inflate.js';
+import { DecompressionBudget, inflateBounded, MAX_DECOMPRESSED_BYTES } from './inflate.js';
 const EOCD_SIG = 0x06054b50;
 const CENTRAL_SIG = 0x02014b50;
 const LOCAL_SIG = 0x04034b50;
@@ -64,7 +64,10 @@ export async function readZip(bytes, opts = {}) {
         });
         p += 46 + nameLen + extraLen + commentLen;
     }
+    // Memoized members are bounded by the archive budget: every member read
+    // (STORED ones too, since central entries may alias one payload) is charged.
     const cache = new Map();
+    const budget = new DecompressionBudget(opts.maxTotalUncompressedBytes);
     async function read(name) {
         const cached = cache.get(name);
         if (cached)
@@ -87,10 +90,12 @@ export async function readZip(bytes, opts = {}) {
         const start = lo + 30 + bytes.readUInt16LE(lo + 26) + bytes.readUInt16LE(lo + 28);
         const raw = bytes.subarray(start, start + entry.compressedSize);
         let out;
-        if (entry.method === 0)
+        if (entry.method === 0) {
+            budget.charge(raw.length, `ZIP member ${name}`);
             out = Buffer.from(raw);
+        }
         else if (entry.method === 8)
-            out = await inflateBounded(raw, 'deflate-raw', limit, `ZIP member ${name}`);
+            out = await inflateBounded(raw, 'deflate-raw', limit, `ZIP member ${name}`, budget);
         else
             throw new Error(`unsupported ZIP compression method ${entry.method} for ${name}`);
         cache.set(name, out);

package/dist/index.js

@@ -21,6 +21,7 @@ import { OFWCache } from './cache/node.js';
 import { getCacheDbPath } from './config.js';
 import { selectToolRegistrars } from './tool-surface.js';
 import { NodeAttachmentIO } from './tools/attachments.js';
+import { VERSION } from './version.js';
 // The stdio server backs the message cache with a local `node:sqlite` file,
 // opened lazily on first use (so the server still boots and answers the host's
 // install-time tools/list probe when no cache path is configured). Both the
@@ -47,7 +48,7 @@ const tools = selectToolRegistrars({
 });
 await runMcp({
     name: 'ofw',
-    version: '2.20.2', // x-release-please-version
+    version: VERSION,
     deps: client,
     tools,
     banner: '[ofw-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion.',

package/dist/tools/_confirm.js

@@ -30,6 +30,10 @@ export function confirmWrite(ctx, opts) {
         details: opts.preview,
         unsupportedNote: 'Complete this action on ourfamilywizard.com instead.',
         tool: opts.tool,
+        // One OFW account per process (OFW_USERNAME / the captured session), so
+        // there is no principal to distinguish; mcp-utils 3 makes saying so explicit.
+        account: undefined,
+        args: opts.args,
         confirmToken: opts.confirmToken,
         subject: () => ({
             target: opts.target,

package/dist/tools/_shared.js

@@ -26,6 +26,20 @@ export function jsonResponse(data) {
 }
 // Raw-string tool result. Wrapper over @chrischall/mcp-utils' `rawTextResult`.
 export const textResponse = rawTextResult;
+// The JSON half of a mixed text response, through the same seam as
+// jsonResponse: timestamps normalized, no formatting whitespace.
+export function jsonText(data) {
+    return JSON.stringify(normalizeTimestampsInValue(data));
+}
+// A write tool's result: its transparency NOTEs/WARNINGs (null entries are
+// skipped) ahead of the structured payload, or `fallback` when OFW returned
+// nothing to show. The payload goes through jsonText, so a write tool cannot
+// hand back the naive-local `sentAt`/`modifiedAt` the read tools never do.
+export function notedJsonResponse(notes, data, fallback) {
+    const text = data ? jsonText(data) : fallback;
+    const prefix = notes.filter((n) => n !== null).join('\n\n');
+    return textResponse(prefix ? `${prefix}\n\n${text}` : text);
+}
 // A STRUCTURED failure: the machine-readable payload of `jsonResponse` plus
 // `isError`, so a refusal can carry recovery data (e.g. the server draft body
 // we declined to overwrite) without being mistaken for a successful write.

package/dist/tools/calendar.js

@@ -152,7 +152,7 @@ export function registerCalendarTools(server, client) {
     const allowWrites = getCalendarWritesAllowed();
     server.registerTool('ofw_list_events', {
         description: 'List OurFamilyWizard calendar events in a date range',
-        annotations: { readOnlyHint: true },
+        annotations: { readOnlyHint: true, openWorldHint: true },
         inputSchema: z.object({
             startDate: z.string().describe('Start date YYYY-MM-DD'),
             endDate: z.string().describe('End date YYYY-MM-DD'),
@@ -166,9 +166,10 @@ export function registerCalendarTools(server, client) {
     if (allowWrites)
         server.registerTool('ofw_create_event', {
             description: 'Create a calendar event in OurFamilyWizard. Unless privateEvent is true, the event is immediately visible to the co-parent — there is no draft stage — so a shared event is confirmed first (a private one is not). If the request fails without a definitive answer the result is EVENT_UNCONFIRMED: the event may already exist, so do NOT retry until ofw_list_events shows it did not land. ' + CONFIRM_NOTE,
-            // Additive, so not destructive — but it lands on a shared calendar
-            // outside this machine, which openWorldHint says to the host.
-            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+            // Destructive by the inverse test: a shared event is on the co-parent's
+            // calendar the moment it lands, and ofw_delete_event removes it but cannot
+            // un-show it. (A private one would be additive; the hint is per tool.)
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
             inputSchema: z.object({
                 title: z.string(),
                 ...eventWriteFields,
@@ -179,6 +180,7 @@ export function registerCalendarTools(server, client) {
             const payload = buildEventPayload(fields);
             if (!fields.privateEvent) {
                 const gate = await confirmWrite(ctx, {
+                    args,
                     tool: 'ofw_create_event',
                     action: 'ofw.event.create',
                     message: 'Review and confirm this OurFamilyWizard calendar event. It is shared with the co-parent and appears on their calendar immediately.',
@@ -216,7 +218,7 @@ export function registerCalendarTools(server, client) {
     if (allowWrites)
         server.registerTool('ofw_update_event', {
             description: 'Update an existing OurFamilyWizard calendar event. Fetches the event, applies the given changes, and writes the merged result back (OFW has no partial update). A change to an event the co-parent can see (shared before or after the change) is confirmed first; the confirmation is bound to the event exactly as read, so if it changes on OFW in between (say the co-parent edited it) the update is refused instead of overwriting their edit. If the write fails without a definitive answer, or lands but cannot be re-read to confirm it, the result is EVENT_UNCONFIRMED: the change may already be on OFW, so do NOT retry until ofw_list_events shows whether it landed. ' + CONFIRM_NOTE,
-            annotations: { destructiveHint: true },
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
             inputSchema: z.object({
                 eventId: z.string().describe('Event id — the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event'),
                 title: z.string().optional(),
@@ -249,6 +251,7 @@ export function registerCalendarTools(server, client) {
             if (current.publicFlag || !merged.privateEvent) {
                 const names = namesIn(current);
                 const gate = await confirmWrite(ctx, {
+                    args,
                     tool: 'ofw_update_event',
                     action: 'ofw.event.update',
                     message: `Review and confirm this change to the OurFamilyWizard event "${current.title}". The co-parent sees the updated event on their calendar.`,
@@ -312,6 +315,7 @@ export function registerCalendarTools(server, client) {
             if (current.publicFlag) {
                 const base = detailToWriteArgs(current);
                 const gate = await confirmWrite(ctx, {
+                    args,
                     tool: 'ofw_delete_event',
                     action: 'ofw.event.delete',
                     message: `Review and confirm deleting the OurFamilyWizard event "${current.title}". It disappears from the co-parent's calendar.`,

package/dist/tools/expenses.js

@@ -208,7 +208,7 @@ export function registerExpenseTools(server, client, attachmentIO) {
     if (!uploadOnly)
         server.registerTool('ofw_get_expense_totals', {
             description: 'Get OurFamilyWizard expense summary totals (owed/paid)',
-            annotations: { readOnlyHint: true },
+            annotations: { readOnlyHint: true, openWorldHint: true },
         }, async () => {
             const data = await client.request('GET', '/pub/v2/expense/expenses/totals');
             return jsonResponse(data);
@@ -216,7 +216,7 @@ export function registerExpenseTools(server, client, attachmentIO) {
     if (!uploadOnly)
         server.registerTool('ofw_list_expense_categories', {
             description: 'List OurFamilyWizard expense categories, including preset and custom categories with their responsibility split metadata. Read-only.',
-            annotations: { readOnlyHint: true },
+            annotations: { readOnlyHint: true, openWorldHint: true },
         }, async () => {
             const data = await client.request('GET', '/pub/v2/expense/categories');
             return jsonResponse(data);
@@ -224,7 +224,7 @@ export function registerExpenseTools(server, client, attachmentIO) {
     if (!uploadOnly)
         server.registerTool('ofw_list_expenses', {
             description: 'List OurFamilyWizard expenses. OFW pages this endpoint with 1-based page/size parameters; its older start/max parameters are ignored and repeatedly return page 1. The response leads with hasMore and nextPage (null when exhausted) before the records. Continue by passing nextPage.',
-            annotations: { readOnlyHint: true },
+            annotations: { readOnlyHint: true, openWorldHint: true },
             inputSchema: z.object({
                 page: z.number().int().min(1).describe('1-based page number (default 1). To continue, pass the nextPage returned by the previous response.').optional(),
                 size: z.number().int().min(1).max(100).describe('Requested page size (default 20). OFW may cap or normalize this value.').optional(),
@@ -272,8 +272,10 @@ export function registerExpenseTools(server, client, attachmentIO) {
         });
     if (allowReceiptUploads)
         server.registerTool('ofw_upload_expense_pdf', {
+            // Destructive by the inverse test: always uploaded SHARED, so the
+            // co-parent sees it in My Files at once, and no tool here deletes it.
             description: 'Upload a PDF to OurFamilyWizard My Files for later attachment to an expense. Accepts either a local path or a signed ChatGPT/oaiusercontent HTTPS URL plus fileName. Exactly one of path or url must be supplied. This tool accepts PDF files only and uploads them using the same SHARED file metadata as the OFW expense form so the returned fileId can be attached to an expense. A SHARED file is visible to the co-parent in My Files immediately, whatever the visibility of the expense it is later attached to (that is set separately by ofw_create_expense privateExpense). ' + CONFIRM_NOTE,
-            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
             inputSchema: z.object({
                 path: z.string().describe('Path to a local PDF file inside the upload directory (OFW_UPLOAD_DIR). Tilde (~) is expanded by the configured attachment I/O implementation. Mutually exclusive with url.').optional(),
                 url: z.string().describe('Signed HTTPS oaiusercontent.com URL for a PDF supplied by the ChatGPT host. Mutually exclusive with path.').optional(),
@@ -309,6 +311,7 @@ export function registerExpenseTools(server, client, attachmentIO) {
             const label = args.label ?? fileName;
             const description = args.description ?? fileName;
             const gate = await confirmWrite(ctx, {
+                args,
                 tool: 'ofw_upload_expense_pdf',
                 action: 'ofw.file.share',
                 message: `Review and confirm uploading the receipt "${fileName}" to OurFamilyWizard. It is uploaded SHARED, so the co-parent can see it in My Files immediately — even if the expense it is attached to is private.`,
@@ -455,6 +458,7 @@ export function registerExpenseTools(server, client, attachmentIO) {
                 });
             }
             const gate = await confirmWrite(ctx, {
+                args,
                 tool: 'ofw_update_expense',
                 action: 'ofw.expense.update',
                 message: next.isPrivate
@@ -558,6 +562,7 @@ export function registerExpenseTools(server, client, attachmentIO) {
                 payload.fileIds = [args.receiptFileId];
             const isPrivate = args.privateExpense === true;
             const gate = await confirmWrite(ctx, {
+                args,
                 tool: 'ofw_create_expense',
                 action: 'ofw.expense.create',
                 message: isPrivate

package/dist/tools/healthcheck.js

@@ -1,5 +1,5 @@
 import { registerCredentialHealthcheckTool } from '@chrischall/mcp-utils/healthcheck';
-import { resolveAuth, isNoAuthConfigured, isBridgeDown } from '../auth.js';
+import { isNoAuthConfigured, isBridgeDown } from '../auth.js';
 /**
  * `ofw_healthcheck` — the one call that answers "is this connector working?".
  *
@@ -13,10 +13,17 @@ import { resolveAuth, isNoAuthConfigured, isBridgeDown } from '../auth.js';
  * fetchproxy, and "which of those actually supplied it" is the first thing
  * anyone needs when the connector misbehaves. That is why `source` is
  * reported.
+ *
+ * The credential comes from the CLIENT (`credentialStatus`), not from a direct
+ * `resolveAuth()` call. That used to be a full login — or a fresh browser-bridge
+ * spin-up — on every healthcheck, ignoring the six-hour token the client
+ * already held; with a bad password each check re-POSTed it against OFW's
+ * failed-attempt counter (chrischall/fleet-audit#881). Through the client's
+ * TokenManager a held or cached token costs nothing, a needed mint is the one
+ * the next tool call would make anyway, and the probe then exercises that very
+ * token — so a passing healthcheck means the tools' own token works.
  */
-export function registerHealthcheckTools(server, client, 
-/** Seam: the auth resolver, injectable so tests need no network. */
-resolve = resolveAuth) {
+export function registerHealthcheckTools(server, client) {
     registerCredentialHealthcheckTool({
         server,
         prefix: 'ofw',
@@ -27,12 +34,13 @@ resolve = resolveAuth) {
         probePath: '/pub/v2/profiles',
         resolveCredential: async () => {
             try {
-                const auth = await resolve();
+                const { source, expiresAt } = await client.credentialStatus();
                 return {
-                    source: auth.source,
+                    source,
                     // Never the token. Expiry is the fact that explains a connector
-                    // that worked an hour ago and does not now.
-                    detail: auth.expiresAt ? { expires_at: auth.expiresAt.toISOString() } : undefined,
+                    // that worked an hour ago and does not now — and this is the one
+                    // the client itself will re-authenticate at.
+                    detail: { expires_at: expiresAt.toISOString() },
                 };
             }
             catch (e) {
@@ -73,7 +81,7 @@ resolve = resolveAuth) {
             no_credential: 'No OFW credential is configured. Either set OFW_USERNAME + OFW_PASSWORD, or install ' +
                 'ContextMint Bridge and sign in to ourfamilywizard.com in a tab (unsetting ' +
                 'OFW_DISABLE_FETCHPROXY if you set it).',
-            credential_rejected: 'OurFamilyWizard rejected the credential. If it came from `env`, the password changed or ' +
+            credential_rejected: 'OurFamilyWizard rejected the credential. If it came from `env` or `cache`, the password changed or ' +
                 'the account is locked; if from `fetchproxy`, the browser session expired — sign in again ' +
                 'in the tab. Retrying will not fix either.',
         },

package/dist/tools/journal.js

@@ -7,7 +7,7 @@ export function registerJournalTools(server, client) {
     const allowWrites = getWriteMode() === 'all';
     server.registerTool('ofw_list_journal_entries', {
         description: 'List OurFamilyWizard journal entries. Offset-paged via start/max (1-based). The response leads with its paging state — `hasMore` and `nextStart` (null when the list is exhausted) — BEFORE the records, so a truncated or partially-read response still says whether more remain. Never state an entry count or an absence from one page.',
-        annotations: { readOnlyHint: true },
+        annotations: { readOnlyHint: true, openWorldHint: true },
         inputSchema: z.object({
             start: z.number().int().min(1).describe('Start offset, 1-based (default 1). To continue a listing, pass the `nextStart` from the previous response.').optional(),
             max: z.number().int().min(1).describe('Max results (default 10)').optional(),
@@ -38,8 +38,10 @@ export function registerJournalTools(server, client) {
     });
     if (allowWrites)
         server.registerTool('ofw_create_journal_entry', {
+            // Destructive by the inverse test: the entry lands on the court-visible
+            // record and no tool here edits or deletes a journal entry.
             description: 'Create a new journal entry in OurFamilyWizard',
-            annotations: { destructiveHint: false },
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
             inputSchema: z.object({
                 title: z.string().describe('Entry title'),
                 body: z.string().describe('Entry text content'),