pi-jar 0.1.4 → 0.1.5

package/src/settings-ui.ts

@@ -2,7 +2,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, visibleWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { FOOTER_FIELDS, type FooterField } from "./footer-settings.ts";
 import { ICON_SETS } from "./icons.ts";
-import { GOAL_ROUND_CHOICES, type JarAccent, type JarVisualSettings } from "./settings.ts";
+import { GOAL_ROUND_CHOICES, MAX_SUBAGENT_CHOICES, type JarAccent, type JarVisualSettings } from "./settings.ts";
 
 const LABELS: Record<FooterField, string> = {
   model: "Model", effort: "Model effort", sessionName: "Session name", cwd: "Working directory",
@@ -35,25 +35,37 @@ export async function openJarSettings(
     let width = 64;
     const accents: JarAccent[] = ["follow", ...availableAccents.filter((name): name is JarAccent =>
       name === "default" || ["gray", "pink", "teal", "azure", "violet", "amber"].includes(name))];
-    const fields = () => page === "footer" ? FOOTER_FIELDS.length : page === "pi" ? 5 : 7;
+    let choosing: "goalRounds" | "maxSubagents" | undefined;
+    const choices = () => choosing === "maxSubagents" ? MAX_SUBAGENT_CHOICES : GOAL_ROUND_CHOICES;
+    const fields = () => choosing ? choices().length : page === "footer" ? FOOTER_FIELDS.length : page === "pi" ? 6 : 7;
+    const finishChoice = () => { selected = choosing === "maxSubagents" ? 3 : 2; choosing = undefined; };
     const piError = (error: unknown) => ctx.ui.notify("Could not change Pi setting: " + (error as Error).message, "error");
-    const pageSize = () => Math.min(fields(), Math.max(4, (process.stdout.rows ?? 24) - 9));
+    const explainPool = () => choosing === "maxSubagents" || (page === "pi" && !choosing && selected === 3);
+    const pageSize = () => Math.min(fields(), Math.max(4, (process.stdout.rows ?? 24) - (explainPool() ? 10 : 9)));
     const firstVisible = () => Math.min(Math.max(0, selected - pageSize() + 1), Math.max(0, fields() - pageSize()));
     const visibleCount = () => Math.min(pageSize(), fields());
     const apply = (index: number) => {
       const state = current();
-      if (page === "footer") {
+      if (choosing) {
+        if (choosing === "maxSubagents") update({ ...state, maxSubagents: MAX_SUBAGENT_CHOICES[index]! });
+        else update({ ...state, goalRounds: GOAL_ROUND_CHOICES[index]! });
+        finishChoice();
+      } else if (page === "footer") {
         const field = FOOTER_FIELDS[index];
         if (field) update({ ...state, footer: { ...state.footer, [field]: !state.footer[field] } });
       } else if (page === "pi") {
         if (index === 0 && pi) { try { pi.setFullscreen(!pi.get().fullscreen); ctx.ui.notify("Pi TUI mode saved; restart Pi to apply", "info"); } catch (error) { piError(error); } }
         else if (index === 1 && pi) { try { pi.setCopyOnSelect(!pi.get().copyOnSelect); } catch (error) { piError(error); } }
         else if (index === 2) {
-          const at = GOAL_ROUND_CHOICES.indexOf(state.goalRounds as never);
-          update({ ...state, goalRounds: GOAL_ROUND_CHOICES[(at + 1) % GOAL_ROUND_CHOICES.length]! });
+          choosing = "goalRounds";
+          selected = Math.max(0, GOAL_ROUND_CHOICES.indexOf(state.goalRounds as never));
         }
-        else if (index === 3) update({ ...state, advisor: !state.advisor });
-        else if (index === 4) update({ ...state, advisorGates: !state.advisorGates });
+        else if (index === 3) {
+          choosing = "maxSubagents";
+          selected = Math.max(0, MAX_SUBAGENT_CHOICES.indexOf(state.maxSubagents));
+        }
+        else if (index === 4) update({ ...state, advisor: !state.advisor });
+        else if (index === 5) update({ ...state, advisorGates: !state.advisorGates });
       } else if (index === 0) {
         const at = Math.max(0, accents.indexOf(state.accent));
         update({ ...state, accent: accents[(at + 1) % accents.length]! });
@@ -77,7 +89,12 @@ export async function openJarSettings(
     return {
       invalidate() {},
       handleInput(data: string) {
-        if (matchesKey(data, Key.escape) || data === "q") { done(); return; }
+        if (matchesKey(data, Key.escape) || data === "q") {
+          if (choosing) { finishChoice(); tui.requestRender(); } else done();
+          return;
+        }
+        if (choosing && (matchesKey(data, Key.tab) || matchesKey(data, Key.right)
+          || matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left))) return;
         if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
           page = PAGES[(PAGES.indexOf(page) + 1) % PAGES.length]!;
           selected = 0;
@@ -97,6 +114,7 @@ export async function openJarSettings(
         if (event.type !== "click" || event.button !== "left") return;
         if (event.y === 0 && event.x >= width - 4) { done(); return { handled: true }; }
         if (event.y === 1) {
+          choosing = undefined;
           if (event.x >= 2 && event.x < Math.min(width - 2, 19)) { page = "appearance"; selected = 0; }
           else if (event.x >= 19 && event.x < Math.min(width - 2, 32)) { page = "footer"; selected = 0; }
           else if (event.x >= 32 && event.x < width - 2) { page = "pi"; selected = 0; }
@@ -121,14 +139,17 @@ export async function openJarSettings(
           + "   " + theme.fg(page === "pi" ? "accent" : "muted", "[ Pi ]"));
         const prefs = pi?.get();
         const divider = theme.fg("dim", "├" + "─".repeat(Math.max(0, width - 2)) + "┤");
-        const allRows = page === "footer"
+        const allRows = choosing
+          ? choices().map((choice, index) => row(index, String(choice), state[choosing!] === choice ? "CURRENT" : "", true))
+          : page === "footer"
           ? FOOTER_FIELDS.map((field, index) => row(index, LABELS[field], state.footer[field] ? "ON" : "OFF", state.footer[field]))
           : page === "pi" ? [
             row(0, "Mouse clicks (Pi fullscreen, restart)", !prefs ? "N/A" : prefs.fullscreen ? "ON" : "OFF", !!prefs?.fullscreen),
             row(1, "Copy on select", !prefs ? "N/A" : prefs.copyOnSelect ? "ON" : "OFF", !!prefs?.copyOnSelect),
             row(2, "Goal auto rounds", String(state.goalRounds), true),
-            row(3, "Advisor (jar_advisor, /advisor)", state.advisor ? "ON" : "OFF", state.advisor),
-            row(4, "Advisor gates (loops, repeated failures)", state.advisorGates ? "ON" : "OFF", state.advisorGates)
+            row(3, "Max subagents (retained live pool)", String(state.maxSubagents), true),
+            row(4, "Advisor (jar_advisor, /advisor)", state.advisor ? "ON" : "OFF", state.advisor),
+            row(5, "Advisor gates (loops, repeated failures)", state.advisorGates ? "ON" : "OFF", state.advisorGates)
           ] : [
             row(0, "Accent", state.accent === "follow" ? "FOLLOW PI" : state.accent.toUpperCase(), true),
             row(1, "Motion", state.animations ? "ON" : "OFF", state.animations),
@@ -141,11 +162,16 @@ export async function openJarSettings(
         const start = firstVisible();
         const rows = allRows.slice(start, start + pageSize());
         return [top, tabs, divider,
-          line(theme.fg("accent", page === "footer" ? " FOOTER VISIBILITY" : page === "pi" ? " PI & WORKFLOWS" : " APPEARANCE & MOTION")),
-          line(theme.fg("dim", page === "footer" ? ` Footer fields ${start + 1}–${start + rows.length}/${fields()}`
+          line(theme.fg("accent", choosing === "maxSubagents" ? " MAX SUBAGENTS · RETAINED LIVE POOL"
+            : choosing === "goalRounds" ? " GOAL AUTO ROUNDS" : page === "footer" ? " FOOTER VISIBILITY" : page === "pi" ? " PI & WORKFLOWS" : " APPEARANCE & MOTION")),
+          line(theme.fg("dim", explainPool() ? " Live pool includes idle/paused subagents"
+            : choosing ? " Select a value; Enter/click to save, Esc to cancel"
+            : page === "footer" ? ` Footer fields ${start + 1}–${start + rows.length}/${fields()}`
             : page === "pi" ? " Fullscreen mode enables clicks and copy-on-select" : " Accent cycles through loaded themes")),
           ...rows,
-          line(theme.fg("dim", " Tab: section · ↑↓: choose · Enter/click: change · Esc")),
+          line(theme.fg("dim", choosing ? " ↑↓: choose · Enter/click: save · Esc: cancel"
+            : " Tab: section · ↑↓: choose · Enter/click: change · Esc")),
+          ...(explainPool() ? [line(theme.fg("dim", " Lowering does not terminate existing subagents"))] : []),
           theme.fg("dim", "╰" + "─".repeat(Math.max(0, width - 2)) + "╯")];
       }
     };

package/src/settings.ts

@@ -17,6 +17,8 @@ export interface JarVisualSettings {
   suggestions: boolean;
   /** Automatic implement/audit rounds per user message while a goal is active. */
   goalRounds: number;
+  /** Retained live subagent pool, including idle/paused agents; lowering does not terminate them. */
+  maxSubagents: MaxSubagents;
   /** The jar_advisor second-opinion tool and /advisor. */
   advisor: boolean;
   /** Consult the advisor automatically when the agent repeats a tool call or keeps failing. */
@@ -27,10 +29,15 @@ export interface JarVisualSettings {
 }
 
 export const GOAL_ROUND_CHOICES = [4, 8, 12, 20] as const;
+export const MAX_SUBAGENT_CHOICES = [2, 4, 6, 8, 16] as const;
+export type MaxSubagents = (typeof MAX_SUBAGENT_CHOICES)[number];
+export function isMaxSubagents(value: unknown): value is MaxSubagents {
+  return MAX_SUBAGENT_CHOICES.some((choice) => choice === value);
+}
 
 export const SETTINGS_FILE = "pi-jar-settings.json";
 export function defaultVisualSettings(footer: FooterSettings = DEFAULT_FOOTER_SETTINGS): JarVisualSettings {
-  return { version: 1, accent: "follow", animations: true, ui: true, composer: true, mascot: true, suggestions: true, goalRounds: 8, advisor: true, advisorGates: true, icons: "unicode", footer: { ...footer } };
+  return { version: 1, accent: "follow", animations: true, ui: true, composer: true, mascot: true, suggestions: true, goalRounds: 8, maxSubagents: 4, advisor: true, advisorGates: true, icons: "unicode", footer: { ...footer } };
 }
 
 /** Legacy footer choices are imported only while the new file is absent. Never modify the old file. */
@@ -60,6 +67,7 @@ export function loadVisualSettings(directory: string): JarVisualSettings {
     suggestions: typeof value.suggestions === "boolean" ? value.suggestions : fallback.suggestions,
     goalRounds: typeof value.goalRounds === "number" && Number.isInteger(value.goalRounds) && value.goalRounds >= 1 && value.goalRounds <= 50
       ? value.goalRounds : fallback.goalRounds,
+    maxSubagents: isMaxSubagents(value.maxSubagents) ? value.maxSubagents : fallback.maxSubagents,
     advisor: typeof value.advisor === "boolean" ? value.advisor : fallback.advisor,
     advisorGates: typeof value.advisorGates === "boolean" ? value.advisorGates : fallback.advisorGates,
     icons: ICON_SETS.some((set) => set === value.icons) ? value.icons as IconSet : fallback.icons,

package/src/status.ts

@@ -73,7 +73,8 @@ export function collectStatuses(statuses: ReadonlyMap<string, string>, now: numb
     const id = rawKey.slice(ROLE_PREFIX.length);
     if (!/^[a-z0-9][a-z0-9-]{0,31}$/.test(id)) continue;
     const role = cachedRole(id, rawValue);
-    if (!role || role.expiresAt == null || role.expiresAt <= now || role.expiresAt > now + ROLE_TTL_MS) {
+    const ttl = id.startsWith("delegate-") ? 24 * 60 * 60_000 : ROLE_TTL_MS;
+    if (!role || role.expiresAt == null || role.expiresAt <= now || role.expiresAt > now + ttl) {
       extras.push(`${id}: unavailable`);
       continue;
     }

package/src/task-tool.ts

@@ -4,7 +4,7 @@ import { Type } from "typebox";
 import type { Todo, TodoInput, TodoStatus } from "./tasks.ts";
 import { TODO_STATUSES, TodoStore, todoMark, todoProgress, todoTotals } from "./tasks.ts";
 
-const ACTIONS = ["write", "list", "append", "remove", "replace", "add", "start", "done", "open", "edit", "delete"] as const;
+const ACTIONS = ["write", "list", "append", "remove", "update", "add", "start", "done", "open", "edit", "delete"] as const;
 const Action = Type.Unsafe<(typeof ACTIONS)[number]>({ type: "string", enum: [...ACTIONS] });
 const Status = Type.Unsafe<(typeof TODO_STATUSES)[number]>({ type: "string", enum: [...TODO_STATUSES] });
 const Content = Type.String({ description: "Imperative task title, e.g. \"Run the tests\"." });
@@ -19,10 +19,10 @@ const Parameters = Type.Object({
     subtasks: Type.Optional(Type.Array(Type.Object({ id: Type.Optional(Type.String()), content: Content, status: Status, activeForm: ActiveForm }), {
       description: "Optional steps of this task (one level deep). The task's status then follows its subtasks."
     }))
-  }), { description: "For append: new tasks only. For replace: exactly one replacement task. With write (or no action): the complete list, replacing it." })),
+  }), { description: "For append: new tasks only. For update: exactly one updated task. With write (or no action): the complete list, replacing it." })),
   action: Type.Optional(Action),
-  id: Type.Optional(Type.String({ description: "Stable task id for replace/remove/start/done/open/edit/delete. On a parent, start runs its first open subtask; done/open apply to all its subtasks." })),
-  title: Type.Optional(Type.String({ description: "Task title for append/add/edit/replace." })),
+  id: Type.Optional(Type.String({ description: "Stable task id for update/remove/start/done/open/edit/delete. On a parent, start runs its first open subtask; done/open apply to all its subtasks." })),
+  title: Type.Optional(Type.String({ description: "Task title for append/add/edit/update." })),
   status: Type.Optional(Status),
   activeForm: ActiveForm,
   parent: Type.Optional(Type.String({ description: "For append/add: id of a top-level task to add the new task under as a subtask." })),
@@ -42,6 +42,8 @@ interface TaskToolDetails {
   changed?: string;
   /** Full stable id index, including items outside the bounded preview. */
   ids?: { id: string; title: string; parentId?: string }[];
+  /** Optional deliberately small render surface for terse mutations such as start/done. */
+  display?: Todo[];
   truncated?: boolean;
   /** Subtask counts of previewed parents when the preview cuts the list. */
   progress?: { id: string; done: number; total: number }[];
@@ -85,11 +87,13 @@ export function registerTaskTool(
   pi.registerTool({
     name: "jar_todo",
     label: "tasks",
-    description: "Maintain session tasks incrementally: append adds todos (or title), remove deletes id and its subtasks, replace updates only id using title/status/activeForm or exactly one todos item. Omitted replacement fields/subtasks are preserved. append with parent adds subtasks. Stable IDs are returned for every task. Legacy write (or todos without action) replaces the entire list. add/delete and start/done/open/edit/list remain supported.",
-    promptSnippet: "Track multi-step work with jar_todo: append new tasks, replace/remove by stable id, keep one leaf in_progress, complete tasks as they finish.",
+    description: "Maintain session tasks: write establishes a fresh complete task plan, update changes one existing task by stable id, append adds genuinely new work, and remove deletes one task tree. start/done/open/edit remain concise status operations. Stable IDs are returned for every task.",
+    promptSnippet: "Track multi-step work with jar_todo: write the task plan first, update/remove existing tasks by stable id, append only when new work arrives mid-run, and keep one leaf in_progress.",
     promptGuidelines: [
       "Use jar_todo proactively, without waiting for the user, for any task with three or more distinct steps, when the user gives several tasks, or right after receiving new instructions. Skip it for single trivial requests and pure questions.",
-      "Prefer incremental actions: append with todos adds only new tasks; replace with id updates only that task; remove with id deletes only that task tree. Use the returned stable IDs. write with todos is legacy full-list replacement and removes omitted tasks. Each todos item has content, status, and optional activeForm/subtasks.",
+      "Prefer write when establishing the task plan for a new request. If the existing checklist is fully completed, start the next request with a fresh write rather than appending onto old completed work.",
+      "Use update with a stable id to revise one existing task and remove to delete one task tree. Use append mainly when the user steers or adds genuinely new requirements while an active checklist is already in progress; do not use append as the default way to create a new plan.",
+      "write with todos is the complete current task plan and removes omitted tasks. Each item has content, status, and optional activeForm/subtasks.",
       "Break a large task into `subtasks` (same shape, one level deep). A parent's status follows its subtasks: it is completed when all of them are. Progress counts leaf tasks (subtasks and tasks without subtasks).",
       "Keep exactly one leaf task in_progress at a time. Mark a task in_progress before you start it and completed immediately after it is verified; do not batch completions.",
       "Only mark a task completed when it is fully done. If tests fail, work is partial or you are blocked, keep it in_progress and add a task for what must be resolved. Remove tasks that are no longer relevant."
@@ -109,7 +113,7 @@ export function registerTaskTool(
           if (!Array.isArray(params.todos)) throw new Error();
           inputs = params.todos.map(toInput);
         } catch { error = "todos must be an array of task objects with array subtasks."; }
-        if (!["write", "append", "replace"].includes(action)) error = "todos may only be used with write, append, or replace; no tasks were changed.";
+        if (!["write", "append", "update"].includes(action)) error = "todos may only be used with write, append, or update; no tasks were changed.";
       }
       if (!error) switch (action) {
         case "list":
@@ -125,15 +129,15 @@ export function registerTaskTool(
           if (!error) changedId = current.all().find((item) => !before.has(item.id))?.id;
           break;
         }
-        case "replace": {
-          if (!params.id) { error = "replace needs a valid existing task id."; break; }
-          if (inputs && (inputs.length !== 1 || params.title !== undefined || params.status !== undefined || params.activeForm !== undefined)) { error = "replace accepts exactly one todos item OR title/status/activeForm fields."; break; }
+        case "update": {
+          if (!params.id) { error = "update needs a valid existing task id."; break; }
+          if (inputs && (inputs.length !== 1 || params.title !== undefined || params.status !== undefined || params.activeForm !== undefined)) { error = "update accepts exactly one todos item OR title/status/activeForm fields."; break; }
           const replacement = inputs?.[0] ?? {
             ...(params.title !== undefined ? { title: params.title } : {}),
             ...(params.status !== undefined ? { status: params.status } : {}),
             ...(params.activeForm !== undefined ? { activeForm: params.activeForm } : {})
           };
-          error = current.replace(params.id, replacement);
+          error = current.update(params.id, replacement);
           if (!error) changedId = params.id;
           break;
         }
@@ -154,7 +158,7 @@ export function registerTaskTool(
           if (!item) error = `${action} needs a valid id from jar_todo list.`;
           else if (action === "start" && progress.total && progress.done === progress.total) error = `every subtask of ${item.id} is completed; open it or add a subtask first.`;
           else if (!current.setStatus(item.id, action === "start" ? "in_progress" : action === "done" ? "completed" : "pending")) error = "Could not save the task.";
-          else changedId = item.id;
+          else changedId = action === "start" ? (current.current()?.id ?? item.id) : item.id;
           break;
         }
         case "edit":
@@ -177,6 +181,8 @@ export function registerTaskTool(
       const group = root ? items.filter((item) => item.id === root || item.parentId === root) : [];
       const mutationItems = action === "write" || action === "append" ? items : group;
       const mutationPreview = mutationItems.slice(0, 8);
+      const terseMutation = action === "start" || action === "done";
+      const terseItem = terseMutation && changedId ? items.find((item) => item.id === changedId) : undefined;
       // Keep task prose bounded while still returning every addressable id in canonical order.
       const idIndex = mutationItems.length > 8
         ? "\nTask IDs (list order): " + items.map((item, index) => `${index + 1}=${item.id}`).join(", ") + "\nUse list for all task titles."
@@ -185,7 +191,11 @@ export function registerTaskTool(
         ? `Could not ${action} tasks: ${error} (${summary(items)}).`
         : action === "list"
           ? `Tasks (${summary(items)}):\n${lines(items)}`
-          : `Task list updated (${summary(items)}).${mutationPreview.length ? "\n" + mutationPreview.map((item) => line(items, item)).join("\n") : ""}${idIndex}\n${REMINDER}`;
+          : action === "start" && terseItem
+            ? `Started task:\n${line(items, terseItem)}`
+            : action === "done" && terseItem
+              ? `Completed task:\n${line(items, terseItem)}`
+              : `Task list updated (${summary(items)}).${mutationPreview.length ? "\n" + mutationPreview.map((item) => line(items, item)).join("\n") : ""}${idIndex}\n${REMINDER}`;
       // A subagent's parent mirrors the checklist from these details, so children send it whole.
       const preview = process.env.PI_JAR_CHILD ? items : items.slice(0, 8);
       const truncated = preview.length < items.length;
@@ -198,6 +208,7 @@ export function registerTaskTool(
         details: {
           action, items: preview, total: state.total, done: state.done, count: items.length,
           ids: items.map(({ id, title, parentId }) => ({ id, title, ...(parentId ? { parentId } : {}) })),
+          ...(terseItem ? { display: [{ ...terseItem }] } : {}),
           ...(state.current ? { current: state.current } : {}),
           ...(truncated ? { truncated: true } : {}),
           ...(progress.length ? { progress } : {}),
@@ -218,15 +229,19 @@ export function registerTaskTool(
       if (isPartial) return new Text(theme.fg("warning", "Updating tasks…"), 0, 0);
       const details = result.details as TaskToolDetails | undefined;
       const items = details?.items ?? [];
+      const displayItems = details?.display ?? items;
       // Older results predate `count`, when `total` counted every item.
       const count = details?.count ?? details?.total ?? items.length;
       const totals = details?.total === undefined ? todoTotals(items) : { done: details.done, total: details.total };
       if (!count) return new Text(theme.fg("dim", "No tracked tasks."), 0, 0);
       const known = new Map((details?.progress ?? []).map((value) => [value.id, value]));
-      const shown = expanded ? items : items.slice(0, 8);
-      let text = theme.fg("dim", `${totals.done}/${totals.total} done${details?.current ? " · now: " + details.current : ""}`);
-      for (const item of shown) text += "\n" + todoRow(item, (color, value) => theme.fg(color, value), (value) => theme.bold(value), known.get(item.id) ?? todoProgress(items, item.id));
-      if (details?.truncated || shown.length < count) text += "\n" + theme.fg("dim", `  … +${Math.max(0, count - shown.length)} more · /jar tasks`);
+      const shown = details?.display ? displayItems : expanded ? items : items.slice(0, 8);
+      let text = details?.display ? "" : theme.fg("dim", `${totals.done}/${totals.total} done${details?.current ? " · now: " + details.current : ""}`);
+      for (const item of shown) {
+        const row = todoRow(item, (color, value) => theme.fg(color, value), (value) => theme.bold(value), known.get(item.id) ?? todoProgress(items, item.id));
+        text += (text ? "\n" : "") + row;
+      }
+      if (!details?.display && (details?.truncated || shown.length < count)) text += "\n" + theme.fg("dim", `  … +${Math.max(0, count - shown.length)} more · /jar tasks`);
       return new Text(text, 0, 0);
     }
   });

package/src/tasks.ts

@@ -11,7 +11,7 @@ export type TodoStatus = (typeof TODO_STATUSES)[number];
 export interface Todo { id: string; title: string; done: boolean; status: TodoStatus; activeForm?: string; details?: string; parentId?: string }
 /** A parent's own `status` is ignored when it has subtasks. */
 export interface TodoInput { id?: string; title: string; status: TodoStatus; activeForm?: string; details?: string; subtasks?: readonly TodoInput[] }
-export type TodoReplacement = Partial<Omit<TodoInput, "id">>;
+export type TodoUpdate = Partial<Omit<TodoInput, "id">>;
 /** Bounds the whole list: parents plus subtasks. */
 export const MAX_TODOS = 50;
 
@@ -312,12 +312,12 @@ export class TodoStore {
     } else next.push(...inputs);
     return this.write(next);
   }
-  /** Replace only the addressed task. Omitted fields and subtasks are preserved. */
-  replace(id: string, replacement: TodoReplacement): string | undefined {
-    if (!this.items.has(id)) return "replace needs a valid existing task id.";
-    if (!replacement || typeof replacement !== "object" || Array.isArray(replacement)) return "replace needs task fields.";
-    if ("id" in replacement && replacement.id !== id) return "Replacement id must match the addressed task.";
-    if (!Object.keys(replacement).some((key) => ["title", "status", "activeForm", "subtasks"].includes(key))) return "replace needs at least one task field.";
+  /** Update only the addressed task. Omitted fields and subtasks are preserved. */
+  update(id: string, replacement: TodoUpdate): string | undefined {
+    if (!this.items.has(id)) return "update needs a valid existing task id.";
+    if (!replacement || typeof replacement !== "object" || Array.isArray(replacement)) return "update needs task fields.";
+    if ("id" in replacement && replacement.id !== id) return "Update id must match the addressed task.";
+    if (!Object.keys(replacement).some((key) => ["title", "status", "activeForm", "subtasks"].includes(key))) return "update needs at least one task field.";
     const next = this.snapshot();
     const target = next.flatMap((item) => [item, ...(item.subtasks ?? [])]).find((item) => item.id === id)!;
     if (this.items.get(id)?.parentId && replacement.subtasks?.length) return "Subtasks cannot have their own subtasks; nest only one level.";