things-api 0.12.0 → 0.14.0

package/dist/mcp/server.js

@@ -16,7 +16,7 @@
  */
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ALL_DESC, AREA_FILTER_DESC, AREA_LIMIT_DESC, AREA_PREVIEW_LIMIT, blockedCode, capabilitiesTable, DATE_FORMAT, DEFAULT_LIST_LIMIT, diagnose, FILTER_CONTRACT, FULL_DESC, hasTagPresence, isLooseRef, isValidTimeZone, LIMIT_DESC, looseShadowNotice, MCP_WHEN_LABELS, mutationWireData, noUuidMatch, omitEmpty, OMIT_EMPTY_NOTE, OP_ID_RE, OPERATION_KINDS, openThings, PKG_VERSION, PROJECT_LIMIT_DESC, PROJECT_PREVIEW_LIMIT, REF_FORMAT, ReferenceResolutionError, REMINDER_FORMAT, schemaWarnings, shapeReadPayload, splitWhenSugar, tagFilterFields, tagFlagConflict, validateViewArgs, verifyFailedCode, WHEN_VALUES, } from "../index.js";
+import { ALL_DESC, AREA_FILTER_DESC, AREA_LIMIT_DESC, AREA_PREVIEW_LIMIT, blockedCode, capabilitiesTable, DATE_FORMAT, DEFAULT_LIST_LIMIT, diagnose, FILTER_CONTRACT, FULL_DESC, hasTagPresence, isLooseRef, isValidTimeZone, LIMIT_DESC, looseShadowNotice, MCP_WHEN_LABELS, mutationWireData, noUuidMatch, omitEmpty, OMIT_EMPTY_NOTE, OP_ID_RE, OPERATION_KINDS, openThings, PKG_VERSION, PROJECT_LIMIT_DESC, PROJECT_PREVIEW_LIMIT, REF_FORMAT, REF_RULE_NOTE, ReferenceResolutionError, REMINDER_FORMAT, RESOLUTION_DATE_FORMAT, schemaWarnings, shapeReadPayload, withTodayBucketTotals, withAreaBucketTotals, withSectionTotals, withUpcomingBlockTotals, splitWhenSugar, tagFilterFields, tagFlagConflict, validateViewArgs, verifyFailedCode, WHEN_VALUES, } from "../index.js";
 function jsonResult(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
@@ -32,24 +32,31 @@ function readResult(data) {
 /**
  * A read result carrying truncation metadata: the data (already limited) in
  * the first content block, and a second block with the {@link Truncation}
- * numbers plus a one-line note the agent can read when rows were dropped.
+ * numbers plus a one-line note the agent can read when rows were dropped. `meta`
+ * merges extra whole-view metadata into that second block — the today view's
+ * `counts` aggregate (the analog of the CLI envelope's `meta.counts`), so `data`
+ * stays pure domain rows.
  */
-function truncatedResult(data, truncation) {
+function truncatedResult(data, truncation, meta) {
     const note = truncation.truncated
         ? `showing ${truncation.shown} of ${truncation.total} items — pass limit (or all: true) to see more`
         : undefined;
     return {
         content: [
             { type: "text", text: JSON.stringify(omitEmpty(data)) },
-            { type: "text", text: JSON.stringify({ truncation, ...(note !== undefined && { note }) }) },
+            {
+                type: "text",
+                text: JSON.stringify({ truncation, ...meta, ...(note !== undefined && { note }) }),
+            },
         ],
     };
 }
 /**
- * Grouped read result (anytime/someday): the per-block-truncated sections plus
- * a second block carrying the unified {@link Truncation} counts (its `blocks`
- * hold the per-block nesting) and, when anything was hidden, a one-line note the
- * agent can read.
+ * Grouped read result (anytime/someday): the per-block-truncated sections (each
+ * capped section carrying its inline `total`, R1) plus a second block carrying
+ * the WHOLE-VIEW {@link Truncation} rollup and, when anything was hidden, a
+ * one-line note the agent can read. The pre-v2 `blocks[]` sidecar is retired —
+ * completeness rides each section's inline `total` (doctrine v2 PR 5).
  */
 function groupedResult(data, truncation) {
     const note = truncation.truncated
@@ -173,7 +180,11 @@ function moveResult(result) {
             return jsonResult(result.plan);
         case "move-refused":
             return errorResult({
-                code: result.refusal,
+                // A hoisted placement block names its hazard — surface the canonical
+                // `blocked:<hazard>` code, matching a direct reorder hazard block.
+                code: result.hazard !== undefined
+                    ? blockedCode({ hazard: result.hazard, reason: "hazard" })
+                    : result.refusal,
                 message: result.detail,
                 ...(result.remediation !== undefined && { remediation: result.remediation }),
                 ...(result.candidates !== undefined && { details: { candidates: result.candidates } }),
@@ -228,6 +239,26 @@ function movePositionArgs(args) {
         return { after: args.after };
     return undefined;
 }
+/** The universal-reorder anchor grammar (start/end/before/after → MovePosition). */
+function reorderPositionArgs(args) {
+    const chosen = [
+        args.start === true,
+        args.end === true,
+        args.before !== undefined,
+        args.after !== undefined,
+    ].filter(Boolean).length;
+    if (chosen > 1)
+        return "conflict";
+    if (args.start === true)
+        return { at: "first" };
+    if (args.end === true)
+        return { at: "last" };
+    if (args.before !== undefined)
+        return { before: args.before };
+    if (args.after !== undefined)
+        return { after: args.after };
+    return undefined;
+}
 /** The shared position input schema for the move tools. */
 const positionShape = {
     first: z.boolean().optional().describe("place the block at the top of its bucket"),
@@ -566,19 +597,23 @@ export function createThingsMcpServer(options = {}) {
     };
     // ------------------------------------------------------------------ reads
     server.registerTool("read_view", {
-        description: "Read a Things list as the app presents it: today (split into Today and This " +
-            "Evening), inbox, anytime, upcoming, someday, logbook, or trash. For upcoming, " +
+        description: "Read a Things list as the app presents it: today (two children buckets — " +
+            "children.today and children.evening, evening expires daily; the whole-view " +
+            "count due/overdue vs. other rides the result's second block), inbox, anytime, " +
+            "upcoming, someday, logbook, or trash. For upcoming, " +
             "horizon > 1 also includes future occurrences of repeating items (up to 10 each). " +
             "anytime/someday return sections in canonical order (area + items; null area = the " +
             "top-level block); children of someday/future-scheduled projects are excluded " +
             "from anytime — the project row represents them; someday lists each group's " +
-            "project rows before its to-dos. Flat views (today/inbox/upcoming/logbook/trash) " +
+            "project rows before its to-dos. Row-capped views (today/inbox/upcoming/logbook/trash) " +
             `return at most ${DEFAULT_LIST_LIMIT} items by default (raise with limit); ` +
             "anytime/someday always return every group and cap per block instead — " +
             `area_limit (default ${AREA_PREVIEW_LIMIT}) per area block, and on anytime ` +
             `project_limit (default ${PROJECT_PREVIEW_LIMIT}) per project block. ` +
             "all: true lifts every cap; the result's second block reports the counts. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             view: z.enum(["today", "inbox", "anytime", "upcoming", "someday", "logbook", "trash"]),
             ...tagFilterShape,
@@ -690,7 +725,7 @@ export function createThingsMcpServer(options = {}) {
             const area = args.area !== undefined ? { area: args.area } : {};
             switch (args.view) {
                 case "today": {
-                    const { view, truncation, filter: fm, } = c.read.today({
+                    const { view, truncation, totals, filter: fm, } = c.read.today({
                         ...filter,
                         ...zone,
                         ...area,
@@ -698,14 +733,17 @@ export function createThingsMcpServer(options = {}) {
                         limit,
                     });
                     filterMeta = fm;
-                    return truncatedResult(shapeReadPayload("today", view, full), truncation);
+                    // The data block is the two `children` bucket records (each with its
+                    // inline `total` when capped); the whole-view `counts` aggregate
+                    // rides the metadata block (the CLI meta.counts analog).
+                    return truncatedResult(withTodayBucketTotals(shapeReadPayload("today", view, full, c.refPromoter()), totals), truncation, { counts: view.counts });
                 }
                 case "inbox": {
                     const { items, truncation } = c.read.inbox({ ...filter, ...zone, limit });
-                    return truncatedResult(shapeReadPayload("inbox", items, full), truncation);
+                    return truncatedResult(shapeReadPayload("inbox", items, full, c.refPromoter()), truncation);
                 }
                 case "anytime": {
-                    const { view, truncation, filter: fm, } = c.read.anytime({
+                    const { view, truncation, sectionTotals, filter: fm, } = c.read.anytime({
                         ...filter,
                         ...zone,
                         ...area,
@@ -713,10 +751,10 @@ export function createThingsMcpServer(options = {}) {
                         projectLimit,
                     });
                     filterMeta = fm;
-                    return groupedResult(shapeReadPayload("anytime", view, full), truncation);
+                    return groupedResult(withSectionTotals(shapeReadPayload("anytime", view, full, c.refPromoter()), sectionTotals), truncation);
                 }
                 case "upcoming": {
-                    const { items, truncation, filter: fm, } = c.read.upcoming({
+                    const { items, truncation, upcomingTotals, filter: fm, } = c.read.upcoming({
                         ...filter,
                         ...zone,
                         ...area,
@@ -724,14 +762,16 @@ export function createThingsMcpServer(options = {}) {
                         limit,
                     });
                     filterMeta = fm;
-                    return truncatedResult(shapeReadPayload("upcoming", items, full), truncation);
+                    // The data block is the day-block `sections` array, each capped block
+                    // carrying its inline `total` (R1); the flat rollup rides truncation.
+                    return truncatedResult(withUpcomingBlockTotals(shapeReadPayload("upcoming", items, full, c.refPromoter()), upcomingTotals), truncation);
                 }
                 case "someday": {
                     const active = showActiveProjectItems;
                     if (typeof active === "number" && args.all === true) {
                         return usage("pass at most one of a numeric show_active_project_items / all");
                     }
-                    const { view, truncation, filter: fm, } = c.read.someday({
+                    const { view, truncation, sectionTotals, filter: fm, } = c.read.someday({
                         ...filter,
                         ...zone,
                         ...area,
@@ -743,7 +783,7 @@ export function createThingsMcpServer(options = {}) {
                         projectLimit: typeof active === "number" ? active : null,
                     });
                     filterMeta = fm;
-                    return groupedResult(shapeReadPayload("someday", view, full), truncation);
+                    return groupedResult(withSectionTotals(shapeReadPayload("someday", view, full, c.refPromoter()), sectionTotals), truncation);
                 }
                 case "logbook": {
                     const { items, truncation, filter: fm, } = c.read.logbook({
@@ -753,11 +793,11 @@ export function createThingsMcpServer(options = {}) {
                         limit,
                     });
                     filterMeta = fm;
-                    return truncatedResult(shapeReadPayload("logbook", items, full), truncation);
+                    return truncatedResult(shapeReadPayload("logbook", items, full, c.refPromoter()), truncation);
                 }
                 case "trash": {
                     const { items, truncation } = c.read.trash({ ...zone, limit });
-                    return truncatedResult(shapeReadPayload("trash", items, full), truncation);
+                    return truncatedResult(shapeReadPayload("trash", items, full, c.refPromoter()), truncation);
                 }
             }
         }, args.tz, () => (filterMeta !== undefined ? { filter: filterMeta } : undefined), () => looseAreaWarnings(getClient(), args.area));
@@ -766,7 +806,9 @@ export function createThingsMcpServer(options = {}) {
         description: "Find items by title/notes substring. Returns open, untrashed items by default; " +
             "include more with logged/trashed/all. Scope with project/area/tag — scope " +
             "references must name existing items. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             query: z.string(),
             ...tagFilterShape,
@@ -821,13 +863,15 @@ export function createThingsMcpServer(options = {}) {
             ...(args.trashed === true && { trashed: true }),
             ...(args.all === true && { all: true }),
         });
-        return truncatedResult(shapeReadPayload("search", items, args.full === true), truncation);
+        return truncatedResult(shapeReadPayload("search", items, args.full === true, getClient().refPromoter()), truncation);
     }, args.tz, undefined, () => looseAreaWarnings(getClient(), args.area)));
     server.registerTool("changes_since", {
         description: "List items created or modified since a moment — including trashed, logged, and " +
             "repeating items (inspect each item's fields to tell them apart). Edits to tags, " +
             "areas, and checklist items do not mark the containing item as modified. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             since: z.string().describe("ISO date-time, e.g. 2026-07-06T08:00:00"),
             ...limitShape,
@@ -849,26 +893,32 @@ export function createThingsMcpServer(options = {}) {
             limit,
             ...(args.tz !== undefined && { zone: args.tz }),
         });
-        return truncatedResult(shapeReadPayload("changes", items, args.full === true), truncation);
+        return truncatedResult(shapeReadPayload("changes", items, args.full === true, getClient().refPromoter()), truncation);
     }, args.tz));
     server.registerTool("get_item", {
         description: "Full detail for one item by uuid: notes, schedule, reminder, deadline, tags " +
             "(direct and inherited), checklist with per-item state, repeat schedule, and its " +
             "project/area/heading. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: { uuid: z.string() },
         annotations: READ_ONLY,
     }, async (args) => readGuard(() => {
         const item = getClient().read.byUuid(args.uuid);
         return item === null
             ? errorResult({ code: "not-found", message: noUuidMatch("item", args.uuid) })
-            : readResult(shapeReadPayload("detail", item, false));
+            : readResult(shapeReadPayload("detail", item, false, getClient().refPromoter()));
     }));
     server.registerTool("get_project", {
         description: "One project's full contents: metadata plus its to-dos grouped under their headings. " +
-            "The tag filters keep only the child to-dos matching by their own tags (a heading left " +
-            "with none is dropped). " +
-            OMIT_EMPTY_NOTE,
+            "Open headings (and archived ones not yet swept to the logbook) stay live, carrying " +
+            "archived once archived; a swept archived heading moves into the logged region as a " +
+            "group with its children. The tag filters keep only the child to-dos matching by their " +
+            "own tags (a heading left with none is dropped). " +
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             uuid: z.string().describe("Project uuid or unique name"),
             ...tagOnlyShape,
@@ -890,7 +940,7 @@ export function createThingsMcpServer(options = {}) {
             overdue: args.overdue === true,
             ...tagFilterFields(tagPresence(args)),
             ...(args.tz !== undefined && { zone: args.tz }),
-        }), args.full === true));
+        }), args.full === true, getClient().refPromoter()));
     }, args.tz));
     server.registerTool("get_area", {
         description: "One area's contents: metadata plus its direct to-dos (active first), its " +
@@ -900,7 +950,9 @@ export function createThingsMcpServer(options = {}) {
             `The project-rows and direct-to-dos sections are capped at ${AREA_PREVIEW_LIMIT} each ` +
             "by default (project_limit / area_limit adjust them; all: true lifts both); the " +
             "second result block reports the counts. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             ref: z.string().describe("Area uuid or unique name"),
             ...tagOnlyShape,
@@ -941,7 +993,7 @@ export function createThingsMcpServer(options = {}) {
             if (areaLimit === "conflict" || projectLimit === "conflict") {
                 return usage("pass at most one of area_limit/project_limit / all");
             }
-            const { view, truncation, notice } = getClient().read.areaView(args.ref, {
+            const { view, truncation, totals, notice } = getClient().read.areaView(args.ref, {
                 overdue: args.overdue === true,
                 ...tagFilterFields(tagPresence(args)),
                 ...(args.tz !== undefined && { zone: args.tz }),
@@ -949,14 +1001,18 @@ export function createThingsMcpServer(options = {}) {
                 projectLimit,
             });
             areaNotice = notice;
-            return groupedResult(shapeReadPayload("area-view", view, args.full === true), truncation);
+            // Each capped scope's completeness rides its inline `total` (R1, PR 3);
+            // the whole-view rollup rides `truncation` (no `blocks[]` sidecar).
+            return groupedResult(withAreaBucketTotals(shapeReadPayload("area-view", view, args.full === true, getClient().refPromoter()), totals), truncation);
         }, args.tz, undefined, () => (areaNotice !== undefined ? [areaNotice] : undefined));
     });
     server.registerTool("list_collections", {
         description: "List every project, area, or tag (tags include their parent-tag nesting). Use to " +
             "refresh the inventory summarized in the server instructions. The tag filters scope " +
             "the projects list by each project's own tags (areas/tags reject them). " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             kind: z.enum(["projects", "areas", "tags"]),
             ...tagOnlyShape,
@@ -1001,7 +1057,7 @@ export function createThingsMcpServer(options = {}) {
             })
             : args.kind === "areas"
                 ? c.read.areas()
-                : c.read.tags(), args.full === true));
+                : c.read.tags(), args.full === true, c.refPromoter()));
     }, args.tz));
     // ---------------------------------------------------------------- to-dos
     const whenSchema = z.string().optional().describe(WHEN_VALUES);
@@ -1026,6 +1082,15 @@ export function createThingsMcpServer(options = {}) {
                 .boolean()
                 .optional()
                 .describe("Confirm adding into a completed/canceled project (this reopens it)"),
+            created_at: z
+                .string()
+                .optional()
+                .describe(`Born with this creation timestamp (${RESOLUTION_DATE_FORMAT})`),
+            completed_at: z
+                .string()
+                .optional()
+                .describe(`Born completed, in the Logbook, with this completion timestamp ` +
+                `(${RESOLUTION_DATE_FORMAT}); drop when/reminder`),
             ...createTagsShape,
             ...tzShape,
             ...dryRunShape,
@@ -1052,6 +1117,8 @@ export function createThingsMcpServer(options = {}) {
             ...(args.project !== undefined && { project: containerRef(args.project) }),
             ...(args.area !== undefined && { area: containerRef(args.area) }),
             ...(args.heading !== undefined && { heading: args.heading }),
+            ...(args.created_at !== undefined && { createdAt: args.created_at }),
+            ...(args.completed_at !== undefined && { completedAt: args.completed_at }),
         }, writeOptions(args)));
     }));
     server.registerTool("update", {
@@ -1061,7 +1128,10 @@ export function createThingsMcpServer(options = {}) {
             "deadline/clear_deadline; changing the schedule keeps an existing reminder unless a new " +
             "one is set, schedule and deadline changes are unavailable for repeating items, and " +
             "clear_reminder needs the item scheduled for today or this evening (a reminder on a " +
-            "future date can only be changed, not cleared). kind area: title and/or tags (the full " +
+            "future date can only be changed, not cleared). created_at/completed_at rewrite the " +
+            "resolution timestamps of an already-resolved item; created_at is status-safe, but " +
+            "completed_at on an open item is refused — resolving it is set_status's boundary, not " +
+            "update's. kind area: title and/or tags (the full " +
             "replacement set). kind tag: title, parent (nest under it) or unnest (to the top level; " +
             "exclusive), and shortcut or clear_shortcut (exclusive). Tags must exist unless " +
             "create_tags is set.",
@@ -1080,6 +1150,16 @@ export function createThingsMcpServer(options = {}) {
             clear_reminder: z.boolean().optional().describe("todo/project: remove the reminder"),
             deadline: z.string().optional().describe(`todo/project: ${DATE_FORMAT}`),
             clear_deadline: z.boolean().optional().describe("todo/project: remove the deadline"),
+            created_at: z
+                .string()
+                .optional()
+                .describe(`todo/project: rewrite the creation timestamp (${RESOLUTION_DATE_FORMAT}); status-safe`),
+            completed_at: z
+                .string()
+                .optional()
+                .describe("todo/project: rewrite the completion timestamp of an already-resolved item " +
+                `(${RESOLUTION_DATE_FORMAT}; a canceled one stays canceled); an open item is ` +
+                "refused — use set_status to resolve it"),
             tags: z
                 .array(z.string())
                 .optional()
@@ -1127,6 +1207,8 @@ export function createThingsMcpServer(options = {}) {
                     ...(args.clear_reminder === true && { reminder: null }),
                     ...(args.deadline !== undefined && { deadline: args.deadline }),
                     ...(args.clear_deadline === true && { deadline: null }),
+                    ...(args.created_at !== undefined && { createdAt: args.created_at }),
+                    ...(args.completed_at !== undefined && { completedAt: args.completed_at }),
                 }, opts));
             }
             return mutationResult(await c.write.updateProject(args.uuid, {
@@ -1139,6 +1221,8 @@ export function createThingsMcpServer(options = {}) {
                 ...(args.clear_reminder === true && { reminder: null }),
                 ...(args.deadline !== undefined && { deadline: args.deadline }),
                 ...(args.clear_deadline === true && { deadline: null }),
+                ...(args.created_at !== undefined && { createdAt: args.created_at }),
+                ...(args.completed_at !== undefined && { completedAt: args.completed_at }),
             }, opts));
         }
         if (args.kind === "area") {
@@ -1178,7 +1262,10 @@ export function createThingsMcpServer(options = {}) {
             "scope project, completing or canceling requires a children policy: 'require-resolved' " +
             "errors if open to-dos remain; 'auto-complete'/'auto-cancel' resolves them together with " +
             "the project (canceling never alters already-completed children). scope project, status " +
-            "open, restore_children also reopens the to-dos that were resolved with the project.",
+            "open, restore_children also reopens the to-dos that were resolved with the project. " +
+            "completed_at (status completed or canceled) sets the completion timestamp — also the " +
+            '"Completed on" stamp for a canceled item — backdating it; reaching a backdated canceled ' +
+            "item is a multi-leg, non-atomic sequence, disclosed in the result and in dry_run.",
         inputSchema: {
             scope: z.enum(["todo", "project"]),
             uuid: z
@@ -1193,21 +1280,33 @@ export function createThingsMcpServer(options = {}) {
                 .boolean()
                 .optional()
                 .describe("scope project, open only: also reopen the to-dos resolved with the project"),
+            completed_at: z
+                .string()
+                .optional()
+                .describe(`status completed or canceled: the completion timestamp (${RESOLUTION_DATE_FORMAT})`),
+            ...tzShape,
             ...dryRunShape,
             ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
+        const badZone = badTz(args.tz);
+        if (badZone !== null)
+            return badZone;
         const c = getClient();
         const opts = writeOptions(args);
+        if (args.completed_at !== undefined && args.status === "open") {
+            return usage("completed_at applies only to status 'completed' or 'canceled'");
+        }
+        const resolution = args.completed_at !== undefined ? { completedAt: args.completed_at } : {};
         if (args.scope === "todo") {
             if (args.children !== undefined || args.restore_children !== undefined) {
                 return usage("children/restore_children apply only to scope project");
             }
             return mutationResult(args.status === "completed"
-                ? await c.write.completeTodo(args.uuid, opts)
+                ? await c.write.completeTodo(args.uuid, resolution, opts)
                 : args.status === "canceled"
-                    ? await c.write.cancelTodo(args.uuid, opts)
+                    ? await c.write.cancelTodo(args.uuid, resolution, opts)
                     : await c.write.reopenTodo(args.uuid, opts));
         }
         // scope project
@@ -1218,13 +1317,13 @@ export function createThingsMcpServer(options = {}) {
             if (args.children !== "require-resolved" && args.children !== "auto-complete") {
                 return usage("status 'completed' requires children: 'require-resolved' or 'auto-complete'");
             }
-            return mutationResult(await c.write.completeProject(args.uuid, { children: args.children }, opts));
+            return mutationResult(await c.write.completeProject(args.uuid, { children: args.children, ...resolution }, opts));
         }
         if (args.status === "canceled") {
             if (args.children !== "require-resolved" && args.children !== "auto-cancel") {
                 return usage("status 'canceled' requires children: 'require-resolved' or 'auto-cancel'");
             }
-            return mutationResult(await c.write.cancelProject(args.uuid, { children: args.children }, opts));
+            return mutationResult(await c.write.cancelProject(args.uuid, { children: args.children, ...resolution }, opts));
         }
         if (args.children !== undefined) {
             return usage("children applies only to status 'completed' or 'canceled'");
@@ -1488,41 +1587,12 @@ export function createThingsMcpServer(options = {}) {
             ? await c.write.restoreTodo(args.uuid, writeOptions(args))
             : await c.write.restoreProject(args.uuid, writeOptions(args)));
     }));
-    server.registerTool("backdate_todo", {
-        description: "Rewrite a to-do's completion and/or creation timestamp to noon (local) on the " +
-            "given date. completion_date requires the to-do to already be completed or " +
-            "canceled; the Logbook re-sorts to the new date.",
-        inputSchema: {
-            uuid: z.string(),
-            completion_date: z.string().optional().describe(DATE_FORMAT),
-            creation_date: z.string().optional().describe(DATE_FORMAT),
-            ...dryRunShape,
-            ...opIdShape,
-        },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.backdateTodo(args.uuid, {
-        ...(args.completion_date !== undefined && { completionDate: args.completion_date }),
-        ...(args.creation_date !== undefined && { creationDate: args.creation_date }),
-    }, writeOptions(args)))));
-    server.registerTool("add_logged_todo", {
-        description: "Create a to-do directly in the Logbook: completed, with the given past " +
-            "completion date (and optionally a past creation date). For importing history " +
-            "from another system.",
-        inputSchema: {
-            title: z.string(),
-            completion_date: z.string().describe(DATE_FORMAT),
-            creation_date: z.string().optional().describe(`${DATE_FORMAT}; <= completion_date`),
-            notes: z.string().optional(),
-            ...dryRunShape,
-            ...opIdShape,
-        },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.addLoggedTodo({
-        title: args.title,
-        completionDate: args.completion_date,
-        ...(args.creation_date !== undefined && { creationDate: args.creation_date }),
-        ...(args.notes !== undefined && { notes: args.notes }),
-    }, writeOptions(args)))));
+    // NB: the bespoke backdate_todo / add_logged_todo tools were removed with the
+    // engine ops (plan PR A). MCP parity for the resolution-timestamp surface is
+    // restored (PR B) as created_at/completed_at params folded onto the existing
+    // write tools: add_todo / add_project (Logbook import), update (rewrite an
+    // already-resolved item's timestamps), and set_status (backdate on
+    // complete/cancel) — matching the CLI's --created-at/--completed-at flags.
     server.registerTool("heading", {
         description: "Manage a project's headings — action selects which; project is always required, and a " +
             "heading is selected by its exact title or its uuid (never an ordinal). add_heading: a " +
@@ -1912,6 +1982,15 @@ export function createThingsMcpServer(options = {}) {
             when: whenSchema,
             deadline: z.string().optional().describe(DATE_FORMAT),
             todos: z.array(z.string()).optional().describe("Initial child to-do titles"),
+            created_at: z
+                .string()
+                .optional()
+                .describe(`Born with this creation timestamp (${RESOLUTION_DATE_FORMAT})`),
+            completed_at: z
+                .string()
+                .optional()
+                .describe(`Born completed, in the Logbook, with this completion timestamp ` +
+                `(${RESOLUTION_DATE_FORMAT}); cannot seed open child to-dos`),
             ...tzShape,
             ...dryRunShape,
             ...opIdShape,
@@ -1928,6 +2007,8 @@ export function createThingsMcpServer(options = {}) {
             ...(args.when !== undefined && { when: args.when }),
             ...(args.deadline !== undefined && { deadline: args.deadline }),
             ...(args.todos !== undefined && { todos: args.todos }),
+            ...(args.created_at !== undefined && { createdAt: args.created_at }),
+            ...(args.completed_at !== undefined && { completedAt: args.completed_at }),
         }, writeOptions(args)));
     }));
     server.registerTool("move_project", {
@@ -2108,81 +2189,53 @@ export function createThingsMcpServer(options = {}) {
         };
     }));
     server.registerTool("reorder", {
-        description: "Rearrange to-dos IN PLACE within the list or container and the bucket they already " +
-            "share — this REARRANGES, never changes what an item belongs to (to change membership " +
-            "use move_todo / move_project). The refs order is the resulting order; unmentioned " +
-            "siblings keep theirs. Bare (no position) assembles the named items as a block at the " +
-            "EARLIEST one's current slot (partial-selection friendly); first/last/before/after " +
-            "position the block instead. Refs that span different containers or buckets are refused. " +
-            "A Today or This Evening member also holds a slot in its own container, so a set that is " +
-            "coherent on BOTH axes is ambiguous — pass `in` to name the axis (the refusal names both " +
-            "choices). The project rows the Today/Evening/day lists intermix with to-dos may be " +
-            "reordered alongside them. Ordering the Today, Inbox, or Someday lists, a project's " +
-            "to-dos, or an area must first be enabled once via `things config set allow-experimental " +
-            "true`. To reorder a project's HEADINGS (children follow) use the heading tool's " +
-            "move_heading action; to reorder sidebar AREAS use reorder_areas.",
+        description: "The ONE reorder tool — rearrange a single-KIND set IN PLACE: to-dos, projects, headings, " +
+            "OR sidebar areas. This REARRANGES, never changes what an item belongs to (to change " +
+            "membership use move_todo / move_project). All refs must be one kind; only to-dos and " +
+            "projects may intermix, and only on the shared Today/Evening/day axes. A mixed-kind set, " +
+            "a cross-container set, and a non-member anchor each get one precise refusal. The refs " +
+            "order is the resulting order; unmentioned siblings keep theirs. Bare (no position) " +
+            "assembles the named items as a block at the EARLIEST one's current slot; start/end/" +
+            "before/after position the block. A Today or This Evening member also holds a slot in its " +
+            "container, so a set coherent on BOTH axes is ambiguous — pass `in` to name the axis. " +
+            "HEADINGS: same-project heading re-ranking runs the native heading-block wire (children " +
+            "follow); an archived heading is reorderable but repositioning it brings it back to open " +
+            "(disclosed in the result). AREAS: this drives the local Things app (sidebar drag) and " +
+            "must be turned on with `things config set ui-enabled true` plus dangerously_drive_gui; " +
+            "the areas' projects and to-dos are untouched. Ordering the Today, Inbox, or Someday " +
+            "lists, or a project's to-dos, must first be enabled once via `things config set " +
+            "allow-experimental true`.",
         inputSchema: {
             refs: z
                 .array(z.string())
-                .describe("The items to rearrange, in the order they should land (may be a subset)"),
-            ...positionShape,
+                .describe("The items to rearrange (one kind: to-dos, projects, headings, or areas), in the " +
+                "order they should land (may be a subset)"),
+            start: z.boolean().optional().describe("place the block at the start of its scope"),
+            end: z.boolean().optional().describe("place the block at the end of its scope"),
+            before: z.string().optional().describe("place the block immediately before this item"),
+            after: z.string().optional().describe("place the block immediately after this item"),
             in: z
                 .string()
                 .optional()
-                .describe("Disambiguate the axis of a Today/This Evening set: today | evening | anytime | " +
-                "someday | inbox, or a project/area/heading ref (uuid or unique title)"),
+                .describe("to-dos/projects only — name the axis to reorder on: today | evening | anytime | " +
+                "someday | inbox, a project/area/heading ref (uuid or unique title), upcoming (the " +
+                "one future day the set shares), or a YYYY-MM-DD day-block. A stage-list or " +
+                "container axis sorts one KIND at a time; only today | evening | upcoming | a " +
+                "day-block intermix both kinds."),
+            ...driveGuiShape,
             ...dryRunShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
-        const position = movePositionArgs(args);
+        const position = reorderPositionArgs(args);
         if (position === "conflict")
-            return usage("pass at most one of first/last/before/after");
+            return usage("pass at most one of start/end/before/after");
         const request = {
             uuids: args.refs,
             ...(position !== undefined && { position }),
             ...(args.in !== undefined && { in: args.in }),
         };
-        return moveResult(await getClient().write.reorderTodos(request, writeOptions(args)));
-    }));
-    server.registerTool("reorder_areas", {
-        description: "Move a sidebar area to a new position in the area order (target by uuid or unique " +
-            "name). Pass exactly one destination: before/after another area, or first/last. This " +
-            "visibly drives the local Things app (the window comes forward and the sidebar may " +
-            "scroll) and must be turned on first with `things config set ui-enabled true`; the " +
-            "area's projects and to-dos are untouched.",
-        inputSchema: {
-            target: z.string().describe(`the area to move (${REF_FORMAT})`),
-            before: z
-                .string()
-                .optional()
-                .describe(`place it immediately above this area (${REF_FORMAT})`),
-            after: z
-                .string()
-                .optional()
-                .describe(`place it immediately below this area (${REF_FORMAT})`),
-            first: z.boolean().optional().describe("move it to the top of the area list"),
-            last: z.boolean().optional().describe("move it to the bottom of the area list"),
-            ...driveGuiShape,
-            ...dryRunShape,
-        },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => {
-        const chosen = [
-            args.before !== undefined,
-            args.after !== undefined,
-            args.first === true,
-            args.last === true,
-        ].filter(Boolean).length;
-        if (chosen !== 1)
-            return usage("pass exactly one of before / after / first / last");
-        return mutationResult(await getClient().write.run("area.reorder", {
-            target: args.target,
-            ...(args.before !== undefined && { before: args.before }),
-            ...(args.after !== undefined && { after: args.after }),
-            ...(args.first === true && { position: "first" }),
-            ...(args.last === true && { position: "last" }),
-        }, writeOptions(args)));
+        return moveResult(await getClient().write.reorderAny(request, writeOptions(args)));
     }));
     server.registerTool("undo", {
         description: "Undo the last N changes, newest first (changes made directly in the Things app " +