@circuitwall/jarela 2.2.1 → 2.3.0

package/lib/stores/version-adoption.test.ts

@@ -13,6 +13,7 @@ const {
   getVersionAdoptionState,
   recordVersionAdoptionWorkflowProgress,
   updateVersionAdoptionState,
+  VersionAdoptionRequestError,
 } = await import("@/lib/stores/version-adoption");
 
 afterAll(() => {
@@ -132,6 +133,7 @@ describe("version adoption state", () => {
     expect(running.checklist[0].status).toBe("done");
     expect(running.checklist[1].id).toBe("build-todo-list");
     expect(running.checklist[1].status).toBe("checking");
+    expect(running.checklist[1].attempts).toBe(1);
   });
 
   it("records item-by-item adoption progress through the workflow helper", () => {
@@ -174,6 +176,100 @@ describe("version adoption state", () => {
     });
   });
 
+  it("builds adaptation items and prompt hints from bundled release changesets", () => {
+    upsertAgentConfig({
+      id: "default-agent",
+      name: "Assistant",
+      identity: "helper",
+      instructions: "Be useful.",
+      tools: [],
+      is_default: true,
+    });
+    updateVersionAdoptionState("mark_done", "2.0.5");
+
+    const pending = getVersionAdoptionState("2.2.1");
+    expect(pending.previous_version).toBe("2.0.5");
+    expect(pending.checklist[0]).toMatchObject({ id: "fetch-changes", status: "done" });
+    expect(pending.checklist[0].validation_evidence).toContain("bundled release changesets for 2.1.0, 2.2.0, 2.2.1");
+    expect(pending.stale_prompt_risks).toEqual(expect.arrayContaining([
+      "Adapt agent settings to tool changes",
+      "Adapt scheduled task and watcher prompts",
+      "Adapt agent instructions and skills",
+    ]));
+
+    const running = updateVersionAdoptionState("start", "2.2.1");
+    const prompt = running.adoption_prompt ?? "";
+    expect(prompt).toContain("read deterministically by the system from the bundled release changesets");
+    expect(prompt).toContain("Release changesets — model-facing prompt and tool description/schema changes from 2.0.5 to 2.2.1:");
+    expect(prompt).toContain("tool `workflow_progress`");
+    expect(prompt).toContain("params added: validation_evidence");
+    expect(prompt).toContain("apply an edit only after the user approves it");
+    expect(prompt).not.toContain("partial");
+
+    const adoption = recordVersionAdoptionWorkflowProgress({
+      item_id: "build-todo-list",
+      status: "done",
+      validation_evidence: "Every changed prompt and tool is covered by an adapt item.",
+    }, "2.2.1");
+    const ids = adoption.state.checklist.map((item) => item.id);
+    expect(ids).toEqual(["adapt-settings", "adapt-task-prompts", "adapt-instructions-skills"]);
+    for (const item of adoption.state.checklist) {
+      expect(item.input.trim()).not.toBe("");
+      expect(item.output.trim()).not.toBe("");
+      expect(item.validation).toMatch(/re-(read|list)/);
+    }
+    expect(adoption.state.checklist[0].affected_files).toContain("tool:workflow_progress");
+  });
+
+  it("retries a single adoption step with a focused prompt and keeps other steps", () => {
+    upsertAgentConfig({
+      id: "default-agent",
+      name: "Assistant",
+      identity: "helper",
+      instructions: "Be useful.",
+      tools: [],
+      is_default: true,
+    });
+    updateVersionAdoptionState("mark_done", "2.0.5");
+    updateVersionAdoptionState("start", "2.2.1");
+    recordVersionAdoptionWorkflowProgress({
+      item_id: "build-todo-list",
+      status: "done",
+      validation_evidence: "Every changed prompt and tool is covered.",
+    }, "2.2.1");
+    recordVersionAdoptionWorkflowProgress({
+      phase: "adoption",
+      item_id: "adapt-settings",
+      status: "done",
+      validation_evidence: "Re-read agent settings; no removed tools referenced.",
+    }, "2.2.1");
+    recordVersionAdoptionWorkflowProgress({
+      phase: "adoption",
+      item_id: "adapt-task-prompts",
+      status: "needs_attention",
+    }, "2.2.1");
+
+    const retried = updateVersionAdoptionState("retry", "2.2.1", "adapt-settings");
+    expect(retried.status).toBe("running");
+    expect(retried.phase).toBe("adoption");
+    const settings = retried.checklist.find((item) => item.id === "adapt-settings");
+    expect(settings?.status).toBe("checking");
+    expect(settings?.attempts).toBe(1);
+    expect(settings?.validation_evidence).toBeUndefined();
+    expect(retried.checklist.find((item) => item.id === "adapt-task-prompts")?.status).toBe("needs_attention");
+
+    const prompt = retried.adoption_prompt ?? "";
+    expect(prompt).toContain("Retry one Jarela version adoption step for upgrade from 2.0.5 to 2.2.1");
+    expect(prompt).toContain("Step: adapt-settings");
+    expect(prompt).toContain('item_id: "adapt-settings"');
+    expect(prompt).toContain('phase: "adoption"');
+    expect(prompt).toContain("Release changesets:");
+    expect(prompt).not.toContain("Phase 1 — impact radius analysis");
+
+    expect(() => updateVersionAdoptionState("retry", "2.2.1", "missing-step")).toThrow(VersionAdoptionRequestError);
+    expect(() => updateVersionAdoptionState("retry", "2.2.1", "fetch-changes")).toThrow(VersionAdoptionRequestError);
+  });
+
   it("blocks adoption until a default agent exists", () => {
     const state = getVersionAdoptionState("1.29.5");
     expect(state.status).toBe("blocked_no_default_agent");

package/lib/stores/version-adoption.ts

@@ -3,6 +3,12 @@ import { getMemory, putMemory } from "@/lib/stores/memory";
 import { getDefaultAgentConfig } from "@/lib/stores/agent-configs";
 import { getOrCreateAgentThread } from "@/lib/stores/threads";
 import { getCurrentVersion } from "@/lib/lifecycle/version";
+import {
+  changesetsBetween,
+  formatChangesetsForPrompt,
+  summarizeChangesets,
+  type ChangesetRange,
+} from "@/lib/lifecycle/changesets";
 import {
   completeWorkflow,
   mergeWorkflowProgress,
@@ -34,6 +40,7 @@ export interface VersionAdoptionChecklistItem {
   validation: string;
   status: VersionAdoptionChecklistStatus;
   validation_evidence?: string;
+  attempts?: number;
   reason: string;
   affected_files: string[];
   action?: VersionAdoptionAction;
@@ -62,6 +69,9 @@ type StoredVersionAdoptionState = VersionAdoptionState & {
   last_adopted_version: string | null;
 };
 
+/** A client request that cannot be applied to the current adoption state. */
+export class VersionAdoptionRequestError extends Error {}
+
 const DEFAULT_CHECKLIST: VersionAdoptionChecklistItem[] = [
   {
     id: "instructions",
@@ -102,9 +112,9 @@ const PHASE_1_CHECKLIST: VersionAdoptionChecklistItem[] = [
   {
     id: "fetch-changes",
     label: "Fetch changes",
-    input: "Previously adopted version tag and current repository HEAD.",
-    output: "The changed-file list between the baseline and current version.",
-    validation: "Use the system-computed git diff result; if no baseline is available, explicitly identify first-adoption status.",
+    input: "Previously adopted version, current version, the bundled release changesets, and git history when running from a source checkout.",
+    output: "The prompt and tool description/schema deltas from the release changesets, or the changed-file list from git, between the baseline and current version.",
+    validation: "Use the system-computed changeset or git diff result; if no baseline is available, explicitly identify first-adoption status.",
     status: "pending",
     reason: "Compare the current version with the previously adopted version or baseline.",
     affected_files: [],
@@ -112,9 +122,9 @@ const PHASE_1_CHECKLIST: VersionAdoptionChecklistItem[] = [
   {
     id: "build-todo-list",
     label: "Build todo list",
-    input: "System-computed changed-file list and classified adoption surfaces.",
+    input: "System-computed change surface and classified adoption surfaces.",
     output: "A Phase 2 checklist covering all matched changes and a fallback review for unmatched changes.",
-    validation: "Check that every changed path is represented by an adoption item or explicitly covered by the fallback.",
+    validation: "Check that every changed prompt, tool, or path is represented by an adoption item or explicitly covered by the fallback.",
     status: "pending",
     reason: "Turn detected version changes into the concrete Phase 2 adoption checklist.",
     affected_files: [],
@@ -192,6 +202,7 @@ function normalizeChecklistItem(value: unknown): VersionAdoptionChecklistItem |
       ? item.validation
       : "Verify findings against the affected files; report unavailable evidence instead of inferring.",
     ...(validationEvidence ? { validation_evidence: validationEvidence } : {}),
+    ...(typeof item.attempts === "number" && Number.isInteger(item.attempts) && item.attempts > 0 ? { attempts: item.attempts } : {}),
     ...(isVersionAdoptionAction(item.action) ? { action: item.action } : {}),
   };
 }
@@ -262,12 +273,118 @@ function item(
   };
 }
 
-function buildChecklist(previousVersion: string | null, currentVersion: string): VersionAdoptionChecklistItem[] {
-  if (!previousVersion) {
-    return DEFAULT_CHECKLIST.map((entry) => ({ ...entry }));
+type ChangeSource = "changeset" | "git" | "none";
+
+interface AdoptionPlan {
+  items: VersionAdoptionChecklistItem[];
+  source: ChangeSource;
+  range: ChangesetRange | null;
+}
+
+function changesetChecklist(previousVersion: string, range: ChangesetRange): VersionAdoptionChecklistItem[] {
+  const summary = summarizeChangesets(range.entries);
+  const toolRefs = summary.toolNames.map((name) => `tool:${name}`);
+  const promptRefs = summary.promptIds.map((id) => `prompt:${id}`);
+  const removed = summary.removedTools.length > 0 ? ` Removed tools: ${summary.removedTools.join(", ")}.` : "";
+  const items: VersionAdoptionChecklistItem[] = [];
+  const surfaceItem = (
+    entry: Omit<VersionAdoptionChecklistItem, "status" | "affected_files"> & { refs: string[] },
+  ): VersionAdoptionChecklistItem => {
+    const { refs, ...rest } = entry;
+    return { ...rest, status: "pending", affected_files: refs.slice(0, 12) };
+  };
+
+  if (summary.toolNames.length > 0) {
+    items.push(surfaceItem({
+      id: "adapt-settings",
+      label: "Adapt agent settings to tool changes",
+      reason: `${summary.toolNames.length} built-in tool(s) changed description or schema since ${previousVersion}.${removed}`,
+      input: "Release changeset tool deltas, every agent's configuration from read_agent_config (tool allowlist and delegate targets), and the live catalog from list_tools.",
+      output: "Per agent: proposed settings edits for allowlists that reference removed tools or should include changed tools the user relies on, or an explicit no-change finding.",
+      validation: "After approved edits, re-read each agent with read_agent_config and confirm every allowlisted tool name exists in list_tools; name every agent checked.",
+      action: "review_permissions",
+      refs: toolRefs,
+    }));
+  }
+  if (summary.toolNames.length > 0 || summary.promptIds.length > 0) {
+    items.push(surfaceItem({
+      id: "adapt-task-prompts",
+      label: "Adapt scheduled task and watcher prompts",
+      reason: "Long-lived task and watcher prompts can reference changed tools or parameters, or repeat built-in guidance that changed.",
+      input: "Release changeset tool and prompt deltas, plus every prompt returned by list_scheduled_tasks and list_watchers.",
+      output: "For each affected task or watcher: current prompt, proposed prompt, and the changeset delta that motivates it; unaffected ones listed as checked.",
+      validation: "After approved update_scheduled_task / update_watcher calls, re-list and confirm each stored prompt equals the approved text and names only tools present in list_tools.",
+      action: "review_schedule",
+      refs: [...toolRefs, ...promptRefs],
+    }));
+    items.push(surfaceItem({
+      id: "adapt-instructions-skills",
+      label: "Adapt agent instructions and skills",
+      reason: "Agent instructions and user skills can reference changed tools or parameters, or duplicate or contradict changed built-in prompt guidance.",
+      input: "Release changeset prompt and tool deltas, each agent's instructions from read_agent_instruction, and user skills from list_skills / read_skill.",
+      output: "For each affected instruction or skill: before and after text and the changeset delta that motivates it; unaffected ones listed as checked.",
+      validation: "After approved update_agent_instruction / write_skill calls, re-read each artifact and confirm the stored text matches and names only tools and parameters present in list_tools and the changed schemas.",
+      action: "read_skill",
+      refs: [...promptRefs, ...toolRefs],
+    }));
+  }
+  if (summary.hints.length > 0) {
+    items.push(surfaceItem({
+      id: "release-hints",
+      label: "Apply release adoption hints",
+      reason: `The release notes include ${summary.hints.length} adoption hint(s) from the maintainers.`,
+      input: `Adoption hints: ${summary.hints.join(" | ")}`,
+      output: "Each hint applied to the user's setup, or a finding that it does not apply.",
+      validation: "For each hint, cite the artifact or setting checked and re-read anything changed.",
+      action: "review_release",
+      refs: [],
+    }));
+  }
+  if (!range.complete) {
+    items.push(surfaceItem({
+      id: "version-diff",
+      label: "Review changes not covered by changesets",
+      reason: `Bundled changesets do not fully cover ${previousVersion} → current; older releases predate changesets.`,
+      input: "The available changesets and the changelog for the uncovered versions.",
+      output: "Findings for uncovered versions and any required adoption actions.",
+      validation: "State which versions were covered by changesets and which only by the changelog.",
+      action: "review_release",
+      refs: [],
+    }));
   }
+  if (items.length === 0) {
+    items.push(surfaceItem({
+      id: "version-diff",
+      label: "Review version changes",
+      reason: "Release changesets report no prompt or tool description/schema changes; user prompts, skills, and settings need no adaptation.",
+      input: "Release changesets for the version range.",
+      output: "Confirmation that no adaptation is required.",
+      validation: "Confirm each changeset in the range lists no tool or prompt changes and no adoption hints.",
+      action: "review_release",
+      refs: [],
+    }));
+    items[0].status = "skipped";
+  }
+  return items;
+}
 
+function computeAdoptionPlan(previousVersion: string | null, currentVersion: string): AdoptionPlan {
+  if (!previousVersion) {
+    return { items: DEFAULT_CHECKLIST.map((entry) => ({ ...entry })), source: "none", range: null };
+  }
+  const range = changesetsBetween(previousVersion, currentVersion);
+  if (range.entries.length > 0) {
+    return { items: changesetChecklist(previousVersion, range), source: "changeset", range };
+  }
   const files = changedFiles(previousVersion, currentVersion);
+  return { items: gitChecklist(files), source: files.length > 0 ? "git" : "none", range: null };
+}
+
+function buildChecklist(previousVersion: string | null, currentVersion: string): VersionAdoptionChecklistItem[] {
+  return computeAdoptionPlan(previousVersion, currentVersion).items;
+}
+
+function gitChecklist(files: readonly string[]): VersionAdoptionChecklistItem[] {
   const dynamic = [
     item(
       "permissions",
@@ -353,26 +470,35 @@ function phase1Checklist(): VersionAdoptionChecklistItem[] {
   return PHASE_1_CHECKLIST.map((entry) => ({ ...entry }));
 }
 
-// `fetch-changes` never needs an agent tool call: the git diff it reports
-// on already ran synchronously in createState() (via buildChecklist), so
-// the item starts pre-completed with the deterministic result baked into
-// its reason. Only `build-todo-list` is left for the agent to actually do.
+// `fetch-changes` never needs an agent tool call: the changeset read or git
+// diff it reports on already ran synchronously in createState() (via
+// computeAdoptionPlan), so the item starts pre-completed with the
+// deterministic result baked into its reason. Only `build-todo-list` is left
+// for the agent to actually do.
 function resolvedPhase1Checklist(
-  adoptionChecklist: readonly VersionAdoptionChecklistItem[],
+  plan: AdoptionPlan,
   isFirst: boolean,
 ): VersionAdoptionChecklistItem[] {
   const [fetchChanges, ...rest] = phase1Checklist();
+  const adoptionChecklist = plan.items;
   const affectedCount = adoptionChecklist.reduce((n, entry) => n + entry.affected_files.length, 0);
+  const changesetVersions = plan.range?.entries.map((entry) => entry.version).join(", ") ?? "";
+  const evidence = isFirst
+    ? "System confirmed that this is the first adoption and no prior baseline exists."
+    : plan.source === "changeset"
+      ? `System read bundled release changesets for ${changesetVersions}${plan.range?.complete ? "" : " (partial coverage)"}; ${affectedCount} changed prompt/tool surface reference(s) were counted.`
+      : `System computed the changed-file surface against the prior version; ${affectedCount} affected file(s) were counted.`;
+  const reason = isFirst
+    ? "First adoption — no previously adopted version to diff against."
+    : plan.source === "changeset"
+      ? `Read deterministically from the bundled release changesets (prompt and tool description/schema deltas): ${affectedCount} surface reference(s) across ${adoptionChecklist.length} area(s).`
+      : `Computed deterministically via git diff against the previously adopted version: ${affectedCount} affected file(s) across ${adoptionChecklist.length} area(s).`;
   return [
     {
       ...fetchChanges,
       status: "done",
-      validation_evidence: isFirst
-        ? "System confirmed that this is the first adoption and no prior baseline exists."
-        : `System computed the changed-file surface against the prior version; ${affectedCount} affected file(s) were counted.`,
-      reason: isFirst
-        ? "First adoption — no previously adopted version to diff against."
-        : `Computed deterministically via git diff against the previously adopted version: ${affectedCount} affected file(s) across ${adoptionChecklist.length} area(s).`,
+      validation_evidence: evidence,
+      reason,
     },
     ...rest,
   ];
@@ -380,7 +506,8 @@ function resolvedPhase1Checklist(
 
 function stalePromptRisks(checklist: readonly VersionAdoptionChecklistItem[]): string[] {
   return checklist
-    .filter((item) => item.id === "skills-instructions" || item.id === "scheduled-work" || item.id === "stale-prompts" || item.id === "permissions")
+    .filter((item) => item.id === "skills-instructions" || item.id === "scheduled-work" || item.id === "stale-prompts" || item.id === "permissions"
+      || item.id === "adapt-settings" || item.id === "adapt-task-prompts" || item.id === "adapt-instructions-skills")
     .map((item) => item.label);
 }
 
@@ -395,11 +522,21 @@ function buildAdoptionPrompt(state: Pick<VersionAdoptionState, "current_version"
   const phaseLabel = state.is_first_adoption
     ? `current-version baseline ${state.current_version}`
     : `upgrade from ${state.previous_version} to ${state.current_version}`;
+  const plan = computeAdoptionPlan(state.previous_version, state.current_version);
+  const changesetSection = plan.source === "changeset" && plan.range
+    ? [
+      "",
+      `Release changesets — model-facing prompt and tool description/schema changes from ${state.previous_version} to ${state.current_version}${plan.range.complete ? "" : " (partial: older versions predate changesets)"}:`,
+      formatChangesetsForPrompt(plan.range.entries),
+    ]
+    : [];
   return [
     `Run Jarela version adoption for ${phaseLabel}.`,
     "",
     "Phase 1 — impact radius analysis:",
-    "- The changed-file surface (`fetch-changes`) was already computed deterministically by the system via git diff against the previously adopted version — see each Phase 2 checklist item below with its affected_files. Do not independently fetch or guess at what changed; that item is already marked done in the UI.",
+    plan.source === "changeset"
+      ? "- The change surface (`fetch-changes`) was already read deterministically by the system from the bundled release changesets: prompt text and built-in tool description/schema deltas between the previously adopted version and this one. They are listed under \"Release changesets\" below. Do not independently fetch or guess at what changed; that item is already marked done in the UI."
+      : "- The changed-file surface (`fetch-changes`) was already computed deterministically by the system via git diff against the previously adopted version — see each Phase 2 checklist item below with its affected_files. Do not independently fetch or guess at what changed; that item is already marked done in the UI.",
     "- Every checklist item provides its input, expected output, and validation criteria. Work from the stated inputs, validate the output using those criteria, and report observed evidence before marking the item done.",
     "- Prefer executable checks for code-verifiable behavior. If a check cannot run, say why and leave the result unverified or mark the item needs_attention.",
     "- Call `workflow_progress` with `workflow_id: \"version_adoption\"`, `phase: \"impact_radius\"`, `item_id: \"build-todo-list\"`, and `status: \"checking\"`.",
@@ -410,9 +547,10 @@ function buildAdoptionPrompt(state: Pick<VersionAdoptionState, "current_version"
     "- Start Phase 2 by calling `workflow_progress` with `workflow_id: \"version_adoption\"` and `phase: \"adoption\"`; the UI will swap from the Phase 1 checklist to the generated adoption todo list.",
     "- Before each Phase 2 checklist item, call `workflow_progress` with that `item_id` and `status: \"checking\"`.",
     "- If Phase 1 finds actionable adoption work, complete safe local updates directly when your available tools allow it.",
+    "- For `adapt-*` items, compare each user artifact (agent settings, instructions, skills, scheduled task and watcher prompts) with the release changesets: removed tools, added, removed, or newly required parameters, changed tool descriptions, and built-in prompt guidance the artifact now duplicates or contradicts. Show the before and after text, apply an edit only after the user approves it, then re-read the artifact to validate.",
     "- For risky or external side effects, propose an approval flow instead of acting silently.",
     "- If Phase 1 finds no adoption work, explicitly say that Phase 2 is skipped and why.",
-    "- After each Phase 2 item, call `workflow_progress` with `status: \"done\"` and observed `validation_evidence`, or `status: \"skipped\"` / `status: \"needs_attention\"` as appropriate.",
+    "- After each Phase 2 item, call `workflow_progress` with `status: \"done\"` and observed `validation_evidence`, or `status: \"skipped\"` / `status: \"needs_attention\"` as appropriate. Add `needs_user: true` only when the user must decide or act; other unfinished or failed steps are retried automatically, up to 3 attempts per step.",
     "- Before your final response, call `workflow_progress` with `workflow_id: \"version_adoption\"`, `phase: \"complete\"`, and a concise `summary`.",
     "",
     "Constraints:",
@@ -423,15 +561,81 @@ function buildAdoptionPrompt(state: Pick<VersionAdoptionState, "current_version"
     "Phase 1 checklist:",
     ...PHASE_1_CHECKLIST.map((item) => `- ${item.id}: ${item.label} — Input: ${item.input} Output: ${item.output} Validation: ${item.validation} Reason: ${item.reason}`),
     "Phase 2 adoption checklist:",
-    ...buildChecklist(state.previous_version, state.current_version).map((item) => `- ${item.id}: ${item.label}: Input: ${item.input} Output: ${item.output} Validation: ${item.validation} Reason: ${item.reason}${item.affected_files.length > 0 ? ` Affected files: ${item.affected_files.join(", ")}.` : ""}`),
+    ...plan.items.map((item) => `- ${item.id}: ${item.label}: Input: ${item.input} Output: ${item.output} Validation: ${item.validation} Reason: ${item.reason}${item.affected_files.length > 0 ? ` Affected: ${item.affected_files.join(", ")}.` : ""}`),
     state.stale_prompt_risks.length > 0 ? `Stale-prompt risks: ${state.stale_prompt_risks.join(", ")}.` : "Stale-prompt risks: none detected in the checklist.",
+    ...changesetSection,
   ].join("\n");
 }
 
+function buildAdoptionStepRetryPrompt(
+  state: Pick<VersionAdoptionState, "current_version" | "previous_version" | "is_first_adoption">,
+  phase: "impact_radius" | "adoption",
+  entry: VersionAdoptionChecklistItem,
+): string {
+  const phaseLabel = state.is_first_adoption
+    ? `current-version baseline ${state.current_version}`
+    : `upgrade from ${state.previous_version} to ${state.current_version}`;
+  const plan = computeAdoptionPlan(state.previous_version, state.current_version);
+  const changesetSection = phase === "adoption" && plan.source === "changeset" && plan.range
+    ? ["", "Release changesets:", formatChangesetsForPrompt(plan.range.entries)]
+    : [];
+  return [
+    `Retry one Jarela version adoption step for ${phaseLabel}. The user asked to redo only this step; leave every other checklist item unchanged.`,
+    "",
+    `Step: ${entry.id} — ${entry.label}`,
+    `Input: ${entry.input}`,
+    `Output: ${entry.output}`,
+    `Validation: ${entry.validation}`,
+    `Reason: ${entry.reason}`,
+    ...(entry.affected_files.length > 0 ? [`Affected: ${entry.affected_files.join(", ")}.`] : []),
+    "",
+    `- Call \`workflow_progress\` with \`workflow_id: "version_adoption"\`, \`phase: "${phase}"\`, \`item_id: "${entry.id}"\`, and \`status: "checking"\`.`,
+    "- Redo the step from its stated input. Prefer executable checks for code-verifiable behavior, and do not reuse earlier evidence: run the validation again.",
+    `- Then call \`workflow_progress\` for \`item_id: "${entry.id}"\` with \`status: "done"\` and newly observed \`validation_evidence\`, or \`status: "needs_attention"\` with the reason.`,
+    "- For `adapt-*` steps, show the before and after text and apply an edit only after the user approves it, then re-read the artifact.",
+    "- Do not create external issues, PRs, scheduled tasks, watcher updates, or credential changes unless the user explicitly approves.",
+    "- Keep the response concise: what you rechecked, the observed result, and any approval needed.",
+    ...changesetSection,
+  ].join("\n");
+}
+
+function retryAdoptionItem(
+  state: StoredVersionAdoptionState,
+  checklist: VersionAdoptionChecklistItem[],
+  itemId: string,
+  t: string,
+): StoredVersionAdoptionState {
+  const index = checklist.findIndex((entry) => entry.id === itemId);
+  if (index === -1) throw new VersionAdoptionRequestError(`Unknown adoption checklist item: ${itemId}`);
+  if (itemId === "fetch-changes") {
+    throw new VersionAdoptionRequestError("fetch-changes is computed by the system and cannot be retried by the agent.");
+  }
+  if (!state.default_agent_id) {
+    return { ...state, status: "blocked_no_default_agent", phase: null, error: "No default agent is configured." };
+  }
+  const phase = PHASE_1_CHECKLIST.some((entry) => entry.id === itemId) ? "impact_radius" : "adoption";
+  const { validation_evidence: _previousEvidence, ...rest } = checklist[index];
+  checklist[index] = { ...rest, status: "checking", attempts: (rest.attempts ?? 0) + 1 };
+  const thread = getOrCreateAgentThread(state.default_agent_id);
+  return {
+    ...state,
+    status: "running",
+    phase,
+    started_at: state.started_at ?? t,
+    completed_at: null,
+    dismissed_at: null,
+    checklist,
+    adoption_thread_id: thread.thread_id,
+    adoption_prompt: buildAdoptionStepRetryPrompt(state, phase, checklist[index]),
+    error: null,
+  };
+}
+
 function createState(currentVersion: string, previousVersion: string | null): StoredVersionAdoptionState {
   const defaultAgent = getDefaultAgentConfig();
   const isFirst = previousVersion === null;
-  const adoptionChecklist = buildChecklist(previousVersion, currentVersion);
+  const plan = computeAdoptionPlan(previousVersion, currentVersion);
+  const adoptionChecklist = plan.items;
   const summaryInput = {
     current_version: currentVersion,
     previous_version: previousVersion,
@@ -450,7 +654,7 @@ function createState(currentVersion: string, previousVersion: string | null): St
     started_at: null,
     completed_at: null,
     dismissed_at: null,
-    checklist: resolvedPhase1Checklist(adoptionChecklist, isFirst),
+    checklist: resolvedPhase1Checklist(plan, isFirst),
     stale_prompt_risks: stalePromptRisks(adoptionChecklist),
     summary: buildSummary(summaryInput, adoptionChecklist),
     error: defaultAgent ? null : "No default agent is configured.",
@@ -475,6 +679,7 @@ export function getVersionAdoptionState(currentVersion = getCurrentVersion()): V
 export function updateVersionAdoptionState(
   action: "start" | "mark_done" | "dismiss" | "retry",
   currentVersion = getCurrentVersion(),
+  itemId?: string,
 ): VersionAdoptionState {
   const existing = parseStored();
   const state = existing && existing.current_version === currentVersion
@@ -483,6 +688,10 @@ export function updateVersionAdoptionState(
   const t = now();
   const nextChecklist = state.checklist.map((entry) => ({ ...entry }));
 
+  if (action === "retry" && itemId) {
+    return persist(retryAdoptionItem(state, nextChecklist, itemId, t));
+  }
+
   if (action === "start" || action === "retry") {
     if (!state.default_agent_id) {
       return persist({
@@ -497,7 +706,11 @@ export function updateVersionAdoptionState(
     // still-open item (normally build-todo-list) as checking instead of
     // hardcoding index 0, which would otherwise clobber that done status.
     const firstOpen = nextChecklist.findIndex((entry) => entry.status !== "done" && entry.status !== "skipped");
-    if (firstOpen !== -1) nextChecklist[firstOpen].status = "checking";
+    if (firstOpen !== -1) {
+      const entry = nextChecklist[firstOpen];
+      if (entry.status !== "checking") entry.attempts = (entry.attempts ?? 0) + 1;
+      entry.status = "checking";
+    }
     const running = {
       ...state,
       status: "running",

package/lib/stores/workflow-progress.ts

@@ -5,6 +5,8 @@ export interface WorkflowItem<Action extends string = string> {
   label: string;
   status: WorkflowItemStatus;
   validation_evidence?: string;
+  /** Times the step has entered `checking`; auto- and manual retries add one each. */
+  attempts?: number;
   reason: string;
   affected_files: string[];
   action?: Action;
@@ -59,6 +61,7 @@ export function updateWorkflowItem<State extends WorkflowState>(
     return {
       ...item,
       status,
+      ...(status === "checking" && item.status !== "checking" ? { attempts: (item.attempts ?? 0) + 1 } : {}),
       ...(validationEvidence ? { validation_evidence: validationEvidence } : {}),
     };
   });

package/lib/tools/communications/ms-todo.ts

@@ -21,19 +21,12 @@ import { registerLangChainPackage } from "../packages/langchain-package";
 import {
   getMicrosoftAccessToken,
   resolveMicrosoftAuth,
-  type MicrosoftAuth,
 } from "@/lib/integrations/microsoft-oauth";
 
 const msTodoReadTools = optionalTools<StructuredToolInterface>("@circuitwall/ms-todo-langchain", "msTodoReadTools");
 const msTodoWriteTools = optionalTools<StructuredToolInterface>("@circuitwall/ms-todo-langchain", "msTodoWriteTools");
 const setAuthResolver = optionalFunction<(resolver: () => unknown) => void>("@circuitwall/ms-todo-langchain", "setAuthResolver", () => undefined);
 
-// Exposed for the integrations test endpoint, matching the gmail/outlook
-// `_resolveXxxAuth` probe convention.
-export function _resolveMsTodoAuth(): MicrosoftAuth | { error: string } {
-  return resolveMicrosoftAuth();
-}
-
 // Bridge: the package calls this on every tool invocation. We resolve
 // the user's Microsoft credentials from Jarela's encrypted store (or env
 // vars) and exchange them for a short-lived access token via the shared

package/lib/tools/general/memory.ts

@@ -46,7 +46,7 @@ export const memoryUpsertTool = tool(
   {
     name: "memory_upsert",
     description:
-      "Store a durable, structured memory record for proactive semantic recall. Use namespace='facts' for information that should surface in future conversations. Store explicit user preferences, verified facts, decisions, constraints, and reusable project context; do not store transient chat details or secrets. Use an expiry for temporary facts, and status='archived' to soft-retire a record instead of deleting it.",
+      "Store a durable, structured memory record for proactive semantic recall. Use namespace='facts' for information that should surface in future conversations. Store explicit user preferences, verified facts, decisions, constraints, and reusable project context; do not store transient chat details or secrets. Use an expiry for temporary facts, and status='archived' to soft-retire a record instead of deleting it. Save proactively in the same turn the information appears so other agents can use it immediately; do not defer to background compaction.",
     schema: z.object({
       namespace: z.string().describe("Memory namespace. Use 'facts' for proactively recalled durable knowledge."),
       key: z.string().describe("Stable, descriptive key such as 'user-research-preference' or 'project-auth-decision'."),

package/lib/tools/general/workflow-progress.ts

@@ -30,6 +30,7 @@ const workflowProgressSchema = z.object({
   summary: z.string().max(300).optional().describe("Optional short workflow summary shown in the chat checklist."),
   detail: z.string().max(300).optional().describe("Optional live progress text to stream immediately to the UI."),
   needs_attention_reason: z.string().max(300).optional().describe("Optional reason shown when the item or workflow needs user attention."),
+  needs_user: z.boolean().optional().describe("For version_adoption only: set true when item_id cannot progress without the user's input or approval."),
 });
 
 function versionAdoptionPhase(phase: string | undefined): "impact_radius" | "adoption" | "complete" | undefined {
@@ -132,6 +133,7 @@ export const workflowProgressTool = tool(
     name: "workflow_progress",
     description:
       "Report structured progress for a substantial multi-step task. Use only when the task has several dependent phases, likely spans turns, or needs explicit verification; skip simple tasks and work already covered by native tool progress. For agent-created workflows, send the full current items snapshot on every call and reuse the same workflow_id. Keep secrets and private data out of workflow fields. Mark items done only with observed validation evidence; use needs_attention for blockers; phase=complete requires every item done or skipped. " +
+      "A rejected update, or a step left checking or needs_attention at the end of the turn, is retried automatically (at most 3 attempts per step); set needs_user=true on a step that only the user can unblock. " +
       "Every item needs input, expected output, and concrete validation criteria. Completed items also need observed validation_evidence. The system-owned version_adoption workflow has its own durable checklist.",
     schema: workflowProgressSchema,
   },

package/lib/tools/runtime/catalog.ts

@@ -5,10 +5,7 @@ import {
   registeredTools,
   registeredNames,
   registeredCategory,
-  registeredCapability,
-  registeredGroup,
   registeredIntegration,
-  groupForCategory,
   type Capability,
   type ToolCategory,
   type ToolGroup,
@@ -30,7 +27,7 @@ import { isBasicToolCategory, normalizeToolCategory } from "./categories";
 import { isAlwaysOnTool } from "./always-on";
 import { getIntegrationReadiness } from "@/lib/health/probe-cache";
 import { getInjectedSubprocessEnv } from "@/lib/env/allowlist";
-import { getAllTools, getAllToolsAsync } from "./runtime";
+import { getAllTools } from "./runtime";
 
 export type ToolSource = "builtin" | "external" | "mcp";
 export type ToolStatus = "enabled" | "disabled" | "unavailable";
@@ -94,10 +91,6 @@ export function getToolSource(name: string): ToolSource {
   return "mcp";
 }
 
-export function getToolCapability(name: string): Capability {
-  return registeredCapability(name) ?? "execute";
-}
-
 export function getToolCategory(name: string): ToolCategory {
   const builtin = registeredCategory(name);
   if (builtin) return builtin;
@@ -108,16 +101,6 @@ export function getToolCategory(name: string): ToolCategory {
   return normalizeToolCategory(mcpCat) as ToolCategory;
 }
 
-export function getToolGroup(name: string): ToolGroup {
-  const cat = getToolCategory(name);
-  if (cat === "MCP") return null;
-  const builtinGroup = registeredGroup(name);
-  if (builtinGroup !== undefined) return builtinGroup;
-  const mcpGroup = getMcpToolMeta(name)?.group;
-  if (mcpGroup !== undefined) return mcpGroup as ToolGroup;
-  return groupForCategory(cat);
-}
-
 export function getToolCredentialsRequired(name: string): string[] {
   if (registeredCategory(name)) return [];
   const ext = loadExternal().credentialsRequired.get(name);
@@ -160,13 +143,6 @@ export function getDefaultAgentToolNames(): string[] {
     .map((t) => t.name);
 }
 
-export async function getDefaultAgentToolNamesAsync(): Promise<string[]> {
-  const tools = await getAllToolsAsync();
-  return tools
-    .filter((t) => isDefaultBasicTool(t.name, getToolCategory(t.name)))
-    .map((t) => t.name);
-}
-
 function isDefaultBasicTool(name: string, category: string): boolean {
   return isBasicToolCategory(category) && !DEFAULT_EXCLUDED_BASIC_TOOLS.has(name);
 }

package/lib/triggers/registry.ts

@@ -14,10 +14,6 @@ export function registerTriggerHandler(handler: TriggerHandler): void {
   state.handlers.set(handler.kind, handler);
 }
 
-export function getTriggerHandler(kind: string): TriggerHandler | undefined {
-  return state.handlers.get(kind);
-}
-
 export function listTriggerHandlers(): TriggerHandler[] {
   return Array.from(state.handlers.values());
 }