@axiom-lattice/core 7.0.3 → 8.0.0

package/dist/index.mjs

@@ -7016,7 +7016,13 @@ If the Worker has task capability, it may truthfully update the same task.
 Otherwise, the owning caller interprets the returned observation.
 
 An execution result is an observation, not automatic proof of business
-completion. \`task\` returns its exact \`executionResultId\`. After \`task\`
+completion. \`task\` returns its exact \`executionResultId\` and the task's
+\`taskStatus\` (re-read **after** the worker settled). **Check \`taskStatus\`
+before completing:** if it is already \`completed\` the task is done \u2014 do NOT
+complete it again (use \`add_activity\` for extra notes); if it is still
+\`in_progress\` you are the single completer and may \`set_status completed\`;
+if it is \`failed\` or \`interrupted\`, act on that (retry / resume / new task)
+instead. After \`task\`
 returns, inspect the observation, then pass that \`executionResultId\` to the
 meaningful \`manage_task set_status\` (status transition), \`manage_task
 update\` (content fields), or \`manage_task add_activity\` that interprets
@@ -7060,7 +7066,11 @@ handled by the configured HITL lifecycle; \`review_required\` is not a task stat
 Create the active parent and each started subtask as records: \`manage_task
 create\` always persists \`pending\`. **Process the task you were assigned in this
 run: set it \`in_progress\` with \`manage_task set_status\` when you start (a
-dispatched task is claimed automatically by the engine).** To bring
+dispatched task is claimed automatically by the engine).** \`in_progress\` means a
+run is executing that task: set it yourself ONLY for the task THIS run executes,
+and for a task you delegate leave it \`pending\` \u2014 \`task\` dispatch claims it.
+Complete a task exactly once: if it is already \`completed\`, do NOT complete it
+again (the terminal state stands; use \`add_activity\` for extra notes). To bring
 in a more suitable expert, create a subtask (\`pending\`) and dispatch THAT with
 \`task { taskId, agentId }\` (a specialist, or agentId "general-purpose" to run your
 own capabilities in an isolated run). **Never re-dispatch the task you are
@@ -8626,7 +8636,9 @@ criteria are truly met \u2014 never as a workaround.
   \`manage_task create(title: <goal>, description: <contract + Belief State>, ownerType: "agent")\`
   \`create\` always yields a \`pending\` record \u2014 it never starts execution. Record
   the returned parent task id, then **process it in this run**, setting it
-  \`in_progress\` with \`manage_task set_status\` when you start. To decompose, create each subtask
+  \`in_progress\` with \`manage_task set_status\` when you start. Set \`in_progress\`
+  only for a task THIS run executes; a task you delegate stays \`pending\` and is
+  claimed by \`task\` dispatch. To decompose, create each subtask
   with \`manage_task create\` (\`pending\`) and delegate it with \`task { taskId,
   agentId }\` to the agent that should execute it (a specialist, or
   "general-purpose" for your own capabilities). The executor does not need
@@ -8659,10 +8671,13 @@ ${TASK_BELIEF_REFERENCE_EXAMPLE}
 ## Status discipline \u2014 MANDATORY
 
 - Execution ownership: process the task you were assigned in this run; set it
-  \`in_progress\` with \`manage_task set_status\` when you start. To involve a more
+  \`in_progress\` with \`manage_task set_status\` when you start. Set it only for a
+  task THIS run executes; a task you delegate stays \`pending\`. To involve a more
   suitable expert, create a subtask and dispatch it with \`task { taskId, agentId }\`
   \u2014 never re-dispatch the task you are processing. Report the outcome with
   \`set_status completed\` (result + beliefImpact), \`failed\`, or \`interrupted\`.
+  Complete a task exactly once: if it is already \`completed\`, do not complete it
+  again \u2014 use \`add_activity\` for extra notes.
 - All status transitions go through \`manage_task set_status\` (with
   \`result\` on completed, \`failureReason\` on failed). \`update\` is for
   content fields only and rejects a status field.
@@ -19345,6 +19360,7 @@ async function runDiscoverHandler(executor, manifest, handler, config, tenantId2
 var PLUGINS_ROOT2 = "/root/.agents/plugins";
 var PLUGIN_TYPE_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 var DEFAULT_HASH_TTL_MS = 3e4;
+var BACKUP_DIR_NAME = ".backup";
 function pluginTypeFromPath(dirPath) {
   return dirPath.slice(dirPath.lastIndexOf("/") + 1);
 }
@@ -19356,6 +19372,10 @@ function topLevelPluginDirs(entries) {
     return remainder.length > 0 && !remainder.includes("/");
   }).sort((a, b) => a.path.localeCompare(b.path));
 }
+function isUnderBackup(path8, pluginDir) {
+  const backupDir = `${pluginDir}/${BACKUP_DIR_NAME}`;
+  return path8 === backupDir || path8.startsWith(`${backupDir}/`);
+}
 var TenantPluginCatalog = class {
   /**
    * @param deps - Sandbox resolver, executor, reserved types, and cache/logger seams
@@ -19391,6 +19411,177 @@ var TenantPluginCatalog = class {
     const snapshot = await this.ensureLoaded(tenantId2);
     return snapshot.manifests[type];
   }
+  /**
+   * Validate a single plugin by reading its files from the sandbox volume.
+   *
+   * Dry-run counterpart to {@link reload}: it lists the plugin directory, reads
+   * `plugin.json`, and runs the same manifest validation the catalog uses when
+   * loading, with handler existence checked against the files actually present
+   * on disk. It never touches the cache and never publishes anything, so a
+   * caller can validate an on-disk plugin without making it live.
+   *
+   * @param tenantId - Tenant that owns the plugin
+   * @param type - Plugin type (directory name); must match the kebab-case type pattern
+   * @returns The structured `diagnostics` and whether the manifest passed fatal
+   *   validation (`valid`). A non-kebab-case `type`, an unreadable directory, or
+   *   a missing/invalid `plugin.json` yields a diagnostic with `valid: false`.
+   */
+  async validatePluginFromDisk(tenantId2, type) {
+    if (typeof type !== "string" || !PLUGIN_TYPE_RE.test(type)) {
+      return {
+        diagnostics: [
+          {
+            level: "error",
+            code: "TYPE_INVALID",
+            pluginType: type,
+            message: `type "${type}" must match ${PLUGIN_TYPE_RE}`
+          }
+        ],
+        valid: false
+      };
+    }
+    const pluginDir = `${PLUGINS_ROOT2}/${type}`;
+    const sandbox = await this.deps.resolveSandbox({ tenantId: tenantId2 });
+    let listing;
+    try {
+      listing = await sandbox.file.listPath(pluginDir, { recursive: true });
+    } catch (err) {
+      return {
+        diagnostics: [
+          {
+            level: "error",
+            code: "PLUGINS_LIST_FAILED",
+            pluginType: type,
+            message: err instanceof Error ? err.message : String(err)
+          }
+        ],
+        valid: false
+      };
+    }
+    let raw;
+    let manifestJson;
+    try {
+      const { content } = await sandbox.file.readFile(`${pluginDir}/plugin.json`);
+      raw = JSON.parse(content);
+      manifestJson = JSON.stringify(raw);
+    } catch (err) {
+      return {
+        diagnostics: [
+          {
+            level: "error",
+            code: "MANIFEST_READ",
+            pluginType: type,
+            message: err instanceof Error ? err.message : String(err)
+          }
+        ],
+        valid: false
+      };
+    }
+    const files = listing.files ?? [];
+    const handlerExists = (rel) => files.some((f) => !f.is_dir && f.path === `${pluginDir}/${rel}`);
+    const knownTypes = new Set(
+      Object.keys(this.cache.get(tenantId2)?.value.manifests ?? {}).filter((t) => t !== type)
+    );
+    const result = validateSandboxPluginManifest({
+      raw,
+      dirName: type,
+      reservedTypes: this.deps.reservedTypes(),
+      knownTypes,
+      handlerExists,
+      rawSizeBytes: Buffer.byteLength(manifestJson, "utf8")
+    });
+    return { diagnostics: result.diagnostics, valid: Boolean(result.manifest) };
+  }
+  /**
+   * Snapshot a plugin's current files into its in-directory backup.
+   *
+   * Keeps a single backup (`<pluginDir>/.backup/`): the previous backup is
+   * replaced. Files already under `.backup/` are excluded, so a backup never
+   * nests. Manual action — it is not triggered by {@link writePlugin}.
+   *
+   * @param tenantId - Tenant that owns the plugin
+   * @param type - Plugin type (directory name)
+   * @returns The number of files snapshotted (`0` when the plugin has no files)
+   */
+  async backupPlugin(tenantId2, type) {
+    this.assertSafeType(type);
+    const pluginDir = `${PLUGINS_ROOT2}/${type}`;
+    const backupDir = `${pluginDir}/${BACKUP_DIR_NAME}`;
+    const sandbox = await this.deps.resolveSandbox({ tenantId: tenantId2 });
+    const entries = (await sandbox.file.listPath(pluginDir, { recursive: true })).files ?? [];
+    const files = entries.filter((entry) => !entry.is_dir && !isUnderBackup(entry.path, pluginDir));
+    if (files.length === 0) {
+      return { files: 0 };
+    }
+    if (entries.some((entry) => isUnderBackup(entry.path, pluginDir))) {
+      await sandbox.file.deletePath(backupDir);
+    }
+    let count = 0;
+    for (const entry of files) {
+      const rel = entry.path.slice(pluginDir.length + 1);
+      const { content } = await sandbox.file.readFile(entry.path);
+      await this.writeRelativeFile(sandbox, backupDir, rel, content);
+      count += 1;
+    }
+    return { files: count };
+  }
+  /**
+   * Restore a plugin's files from its in-directory backup.
+   *
+   * The plugin directory (excluding `.backup/`) is made to match the backup:
+   * files present in the backup are (re)written and files absent from it are
+   * removed. Callers should {@link reload} afterward so the restored shape is
+   * picked up.
+   *
+   * @param tenantId - Tenant that owns the plugin
+   * @param type - Plugin type (directory name)
+   * @returns The number of files restored
+   * @throws Error when the plugin has no backup
+   */
+  async restorePlugin(tenantId2, type) {
+    this.assertSafeType(type);
+    const pluginDir = `${PLUGINS_ROOT2}/${type}`;
+    const backupDir = `${pluginDir}/${BACKUP_DIR_NAME}`;
+    const sandbox = await this.deps.resolveSandbox({ tenantId: tenantId2 });
+    const backupFiles = await (async () => {
+      try {
+        return ((await sandbox.file.listPath(backupDir, { recursive: true })).files ?? []).filter((entry) => !entry.is_dir);
+      } catch {
+        return [];
+      }
+    })();
+    if (backupFiles.length === 0) {
+      throw new Error(`no backup found for plugin "${type}"`);
+    }
+    const backupRels = new Set(backupFiles.map((entry) => entry.path.slice(backupDir.length + 1)));
+    const currentFiles = ((await sandbox.file.listPath(pluginDir, { recursive: true })).files ?? []).filter((entry) => !entry.is_dir && !isUnderBackup(entry.path, pluginDir));
+    for (const entry of currentFiles) {
+      const rel = entry.path.slice(pluginDir.length + 1);
+      if (!backupRels.has(rel)) await sandbox.file.deletePath(entry.path);
+    }
+    let count = 0;
+    for (const entry of backupFiles) {
+      const rel = entry.path.slice(backupDir.length + 1);
+      const { content } = await sandbox.file.readFile(entry.path);
+      await this.writeRelativeFile(sandbox, pluginDir, rel, content);
+      count += 1;
+    }
+    return { files: count };
+  }
+  /**
+   * Write a file under a base directory, creating its parent directory first.
+   *
+   * @param sandbox - Sandbox whose file service receives the write
+   * @param baseDir - Absolute target directory (a plugin or backup directory)
+   * @param rel - Safe path relative to `baseDir`
+   * @param content - File contents
+   * @returns Nothing once the file is written
+   */
+  async writeRelativeFile(sandbox, baseDir, rel, content) {
+    const slash = rel.lastIndexOf("/");
+    if (slash !== -1) await sandbox.file.createDirectory(`${baseDir}/${rel.slice(0, slash)}`);
+    await sandbox.file.writeFile(`${baseDir}/${rel}`, content);
+  }
   /**
    * Drop the cached snapshot for a tenant.
    *
@@ -19467,6 +19658,30 @@ var TenantPluginCatalog = class {
     const { content } = await sandbox.file.readFile(`${PLUGINS_ROOT2}/${type}/${relPath}`);
     return content;
   }
+  /**
+   * List the relative file paths currently present under a plugin directory.
+   *
+   * Used to decide whether a plugin already exists before scaffolding, and to
+   * surface a plugin's files without reading their contents.
+   *
+   * @param tenantId - Tenant that owns the plugin
+   * @param type - Plugin type (directory name); must match the kebab-case type pattern
+   * @returns Relative paths (e.g. `plugin.json`, `handlers/x.js`); empty when the
+   *   directory is missing or the listing fails
+   */
+  async listPluginFiles(tenantId2, type) {
+    this.assertSafeType(type);
+    const sandbox = await this.deps.resolveSandbox({ tenantId: tenantId2 });
+    const pluginDir = `${PLUGINS_ROOT2}/${type}`;
+    let listing;
+    try {
+      listing = await sandbox.file.listPath(pluginDir, { recursive: true });
+    } catch {
+      return [];
+    }
+    const prefix = `${pluginDir}/`;
+    return listing.files.filter((entry) => !entry.is_dir).map((entry) => entry.path.startsWith(prefix) ? entry.path.slice(prefix.length) : entry.path);
+  }
   /**
    * Write a plugin manifest and handler files into the tenant volume.
    *
@@ -19491,11 +19706,7 @@ var TenantPluginCatalog = class {
     await sandbox.file.createDirectory(dir);
     await sandbox.file.writeFile(`${dir}/plugin.json`, JSON.stringify(manifest, null, 2));
     for (const [rel, content] of Object.entries(handlers)) {
-      const slash = rel.lastIndexOf("/");
-      if (slash !== -1) {
-        await sandbox.file.createDirectory(`${dir}/${rel.slice(0, slash)}`);
-      }
-      await sandbox.file.writeFile(`${dir}/${rel}`, content);
+      await this.writeRelativeFile(sandbox, dir, rel, content);
     }
   }
   /**
@@ -19600,7 +19811,7 @@ var TenantPluginCatalog = class {
       const dirFiles = entries.filter(
         (entry) => entry.path === dir.path || entry.path.startsWith(`${dir.path}/`)
       );
-      const relPaths = dirFiles.filter((entry) => !entry.is_dir && entry.path !== `${dir.path}/plugin.json`).map((entry) => entry.path.slice(dir.path.length + 1)).sort();
+      const relPaths = dirFiles.filter((entry) => !entry.is_dir && entry.path !== `${dir.path}/plugin.json` && !isUnderBackup(entry.path, dir.path)).map((entry) => entry.path.slice(dir.path.length + 1)).sort();
       const manifestPath = `${dir.path}/plugin.json`;
       let raw;
       let manifestJson;
@@ -19631,7 +19842,7 @@ var TenantPluginCatalog = class {
     const manifests = {};
     for (const candidate of candidates) {
       try {
-        const handlerExists = (rel) => candidate.files.some((f) => f.path === `${candidate.dirPath}/${rel}`);
+        const handlerExists = (rel) => candidate.files.some((f) => !f.is_dir && f.path === `${candidate.dirPath}/${rel}`);
         const result = validateSandboxPluginManifest({
           raw: candidate.raw,
           dirName: candidate.type,
@@ -38375,7 +38586,11 @@ var TaskLifecycleService = class {
       expectedStatuses: ["completed", "cancelled"],
       updates: { status: "in_progress", failureReason: null, result: null },
       summary: "Task reopened",
-      detail: { type: "reopen" }
+      detail: { type: "reopen" },
+      // Preserve an existing thread by default (the project runtime reuses the
+      // canonical Task Thread); a dispatch that allocated a fresh run thread
+      // opts in to replacing it.
+      replaceThread: input.replaceThread ?? false
     });
   }
   /**
@@ -40236,6 +40451,39 @@ function createTaskRunBridge(deps) {
           transitioned: true
         };
       }
+      if (task.status === "completed" || task.status === "cancelled") {
+        if (task.ownerType !== "agent") {
+          return {
+            success: false,
+            code: "AGENT_TASK_REQUIRED",
+            error: "Lifecycle transitions only support agent tasks."
+          };
+        }
+        const reopened = await deps.lifecycle.reopenTask({
+          tenantId: tenantId2,
+          taskId: task.id,
+          actor,
+          ...threadId !== void 0 ? { threadId } : {},
+          // The caller allocated a fresh run thread for this dispatch.
+          replaceThread: true
+        });
+        if (!reopened.success) {
+          return {
+            success: false,
+            code: reopened.code,
+            error: reopened.error,
+            ...reopened.hint !== void 0 ? { hint: reopened.hint } : {},
+            ...reopened.retryable !== void 0 ? { retryable: reopened.retryable } : {}
+          };
+        }
+        return {
+          success: true,
+          task: reopened.task,
+          warnings: reopened.warnings ?? [],
+          mutated: true,
+          transitioned: true
+        };
+      }
       return { success: true, task, warnings, mutated: false, transitioned: false };
     },
     async settleRun(input) {
@@ -40408,6 +40656,45 @@ async function tryAcquireTaskRun(input) {
   };
 }
 
+// src/services/taskLiveness.ts
+function registeredLeaseStore() {
+  try {
+    return storeLatticeManager.getStoreLattice("default", "lease").store;
+  } catch {
+    return void 0;
+  }
+}
+async function isTaskRunLeaseHeld(task) {
+  const store = registeredLeaseStore();
+  if (!store) return false;
+  try {
+    if (await store.get(taskRunLeaseKey(task.id))) return true;
+    const threadId = typeof task.context?.thread_id === "string" ? task.context.thread_id : void 0;
+    if (threadId && task.ownerId && await store.get(threadRunLeaseKey(task.tenantId, task.ownerId, threadId))) {
+      return true;
+    }
+    return false;
+  } catch {
+    return true;
+  }
+}
+function createTaskRunLiveness() {
+  return async (task) => taskRunRegistry.isLive(task.id) || isTaskRunLeaseHeld(task);
+}
+function isMultiReplicaDeclared() {
+  const id = process.env.AXIOM_REPLICA_ID;
+  return typeof id === "string" && id.trim() !== "";
+}
+function isSharedLeaseStore() {
+  const store = registeredLeaseStore();
+  const name = store?.constructor?.name;
+  return typeof name === "string" && !name.startsWith("InMemory");
+}
+function canConvergeOrphan() {
+  if (!isMultiReplicaDeclared()) return true;
+  return isSharedLeaseStore();
+}
+
 // src/services/ExecutionAuthorityRegistry.ts
 var ManagedTaskStartError = class extends Error {
   /**
@@ -40491,7 +40778,10 @@ async function prepareTaskDispatch(deps, input) {
       }
     };
   }
-  if (task.status === "completed" || task.status === "cancelled") {
+  const managedAuthority = executionAuthorityRegistry.resolve(task);
+  const terminal = task.status === "completed" || task.status === "cancelled";
+  const reopenableTerminal = terminal && task.ownerType === "agent" && !managedAuthority;
+  if (terminal && !reopenableTerminal) {
     return {
       kind: "failure",
       failure: {
@@ -40515,19 +40805,18 @@ async function prepareTaskDispatch(deps, input) {
       }
     };
   }
-  if (task.status !== "pending" && task.status !== "interrupted" && task.status !== "failed") {
+  if (task.status !== "pending" && task.status !== "interrupted" && task.status !== "failed" && !reopenableTerminal) {
     return {
       kind: "failure",
       failure: {
         success: false,
         code: "TASK_NOT_DISPATCHABLE",
-        error: "Only a `pending`, `interrupted`, or `failed` task can be dispatched.",
-        hint: `This task is '${task.status}'. A \`pending\` task starts, an \`interrupted\` task resumes, and a \`failed\` task retries. A task already \`in_progress\` is held by a live run; terminal tasks cannot be dispatched.`,
+        error: "Only a `pending`, `interrupted`, `failed`, or reopenable terminal task can be dispatched.",
+        hint: `This task is '${task.status}'. A \`pending\` task starts, an \`interrupted\` task resumes, a \`failed\` task retries, and an agent-owned \`completed\`/\`cancelled\` task reopens. A task already \`in_progress\` is held by a live run.`,
         taskId: task.id
       }
     };
   }
-  const managedAuthority = executionAuthorityRegistry.resolve(task);
   if (managedAuthority) {
     if (managedAuthority.onManagedStart) {
       try {
@@ -40697,7 +40986,8 @@ function persistedExecutionObservation(item, attempted) {
 }
 function buildWorkerMessage(task, parent, dependencies) {
   const sections2 = [
-    "Execute the following persistent task. Return your result as an observation; do not assume the task is complete.",
+    `You have been assigned persistent task \`${task.id}\` to execute in THIS run. Do NOT dispatch this task \u2014 \`task\` is only for delegating a NEW child subtask; this task is already yours.`,
+    "When the acceptance criteria are truly met, record the outcome yourself with `manage_task set_status completed` (result + beliefImpact), or `failed`/`interrupted`. If you do not have `manage_task`, return your result as an observation for the caller to record.",
     `Persisted Task ID: \`${task.id}\``,
     `# Task: ${task.title}`,
     task.description?.trim() || "No task description was provided."
@@ -40729,9 +41019,17 @@ function createTaskExecutionService(deps) {
     taskStore: deps.taskStore,
     workItemStore: deps.workItemStore
   });
+  const isTaskHeldByLiveRun = deps.isTaskHeldByLiveRun ?? createTaskRunLiveness();
   const run = async (plan) => {
     const { tenantId: tenantId2, agentId, actor, parent, completedDependencies } = plan;
     let task = plan.task;
+    const readTaskStatus = async () => {
+      try {
+        return (await deps.taskStore.getById(tenantId2, task.id))?.status;
+      } catch {
+        return void 0;
+      }
+    };
     const storedThreadId = (task.status === "interrupted" || task.status === "failed") && typeof task.context?.thread_id === "string" && task.context.thread_id.trim() !== "" ? task.context.thread_id : void 0;
     const storedRunId = typeof task.context?.run_id === "string" && task.context.run_id.trim() !== "" ? task.context.run_id : void 0;
     let reuseCurrentRun = false;
@@ -40790,7 +41088,7 @@ function createTaskExecutionService(deps) {
       task = transfer.task;
     }
     const warnings = [];
-    if (task.status === "pending" || task.status === "interrupted" || task.status === "failed") {
+    if (task.status === "pending" || task.status === "interrupted" || task.status === "failed" || task.status === "completed" || task.status === "cancelled") {
       const begun = await bridge.beginRun({
         tenantId: tenantId2,
         task,
@@ -40917,6 +41215,7 @@ function createTaskExecutionService(deps) {
               ...warnings.length > 0 ? { warnings } : {}
             };
           }
+          const settledStatus = await readTaskStatus();
           return {
             success: false,
             code: failureCode,
@@ -40925,6 +41224,7 @@ function createTaskExecutionService(deps) {
             agentId,
             threadId,
             executionResultId: eventKey,
+            ...settledStatus !== void 0 ? { taskStatus: settledStatus } : {},
             ...warnings.length > 0 ? { warnings } : {}
           };
         } catch (persistenceError) {
@@ -40973,6 +41273,7 @@ function createTaskExecutionService(deps) {
             ...warnings.length > 0 ? { warnings } : {}
           };
         }
+        const taskStatus = await readTaskStatus();
         return {
           success: true,
           taskId: task.id,
@@ -40980,6 +41281,7 @@ function createTaskExecutionService(deps) {
           threadId,
           observation: validated.observation,
           executionResultId: eventKey,
+          ...taskStatus !== void 0 ? { taskStatus } : {},
           ...warnings.length > 0 ? { warnings } : {}
         };
       } catch (error) {
@@ -41000,6 +41302,23 @@ function createTaskExecutionService(deps) {
   };
   return {
     start: async (input) => {
+      let current;
+      try {
+        current = await deps.taskStore.getById(input.tenantId, input.taskId);
+      } catch {
+        current = null;
+      }
+      if (current && current.status === "in_progress" && current.ownerType === "agent" && canConvergeOrphan() && !executionAuthorityRegistry.resolve(current) && !await isTaskHeldByLiveRun(current)) {
+        try {
+          await lifecycle.failTask({
+            tenantId: input.tenantId,
+            taskId: current.id,
+            actor: input.actor,
+            failureReason: "Run is no longer executing this task (no_executor)"
+          });
+        } catch {
+        }
+      }
       const prepared = await prepareTaskDispatch(deps, input);
       if (prepared.kind === "managed") return prepared.result;
       if (prepared.kind === "failure") return prepared.failure;
@@ -43144,9 +43463,85 @@ Use \`imagine_html\`. Wrap the entire thing in a single raised card. All content
   </div>
 </div>
 \`\`\``;
+var ANNOTATABLE_MOCKUP = `## Annotatable drafts (reviewable mockups)
+
+When the output is a **UI design** \u2014 a draft the user critiques element-by-element \u2014 make it **annotatable** so feedback comes back to the conversation and you can revise. **Right-click** (\`contextmenu\`) any marked element to leave a note; a plain left-click stays free for the mock's own interactions. (A structural or functional overview is different: make it **click-to-explore interactive** to confirm, not annotatable.)
+
+- Show a small **always-visible hint** (in the user's language) so the draft is discoverable, e.g. \`\u53F3\u952E\u4EFB\u610F\u5143\u7D20\u6279\u6CE8\` / \`Right-click an element to comment\`.
+- Mark each element worth commenting on with \`class="anno"\`; highlight hover with an **\`outline\`** (never \`border\` \u2014 outline does not reflow the layout). Give it a **negative \`outline-offset\`** (e.g. \`-2px\`) so the frame sits *inside* the element: a positive offset can fall outside the container and get clipped, hiding the cue.
+- Wrap the whole draft in a \`position: relative\` container and put the comment box in an overlay inside it with \`position: absolute; inset: 0\` \u2014 **never** \`position: fixed\` (it collapses the iframe to min-height).
+- Handle \`contextmenu\` with event delegation; \`preventDefault()\` + \`stopPropagation()\` (this replaces the native browser menu, which is fine on a draft).
+- The dialog shows the element name and its **current value**, a note field, and **Cancel / Send** buttons (Send is primary). Cancel, clicking the scrim, and \`Escape\` all close without sending. Mark the element being commented (add \`.marked\`, a solid outline) so it is obvious which one is active.
+- Send the note back with \`sendPrompt()\` as a clear instruction \u2014 the element, its current value, and the requested change \u2014 so the agent knows exactly what to change. The agent then restates the feedback and re-shows a revised draft.
+
+\`\`\`html
+<style>
+.anno{position:relative}
+.anno:hover{outline:1px dashed var(--color-border-info);outline-offset:-2px;border-radius:var(--border-radius-md)}
+.anno.marked{outline:1.5px solid var(--color-text-info);outline-offset:-2px}
+.overlay{position:absolute;inset:0;background:rgba(0,0,0,.35);display:flex;align-items:center;justify-content:center;border-radius:var(--border-radius-lg);z-index:10}
+.modal{background:var(--color-background-primary);border:0.5px solid var(--color-border-secondary);border-radius:var(--border-radius-lg);padding:16px;width:88%;max-width:420px}
+.modal .mt{font-size:14px;font-weight:500;margin-bottom:2px}
+.modal .ms{font-size:11px;color:var(--color-text-tertiary);margin-bottom:10px}
+.modal textarea{width:100%;box-sizing:border-box;height:auto;min-height:72px;padding:8px 10px;resize:vertical}
+.modal .mrow{display:flex;gap:8px;justify-content:flex-end;margin-top:10px}
+.primary{background:var(--color-text-info);color:var(--color-background-primary);border-color:var(--color-text-info)}
+.primary:hover{background:var(--color-text-info);opacity:.9}
+</style>
+<div class="panel" style="position:relative">
+  <div style="font-size:12px;color:var(--color-text-tertiary);margin-bottom:8px">Right-click an element to comment</div>
+  <div class="anno" data-el="Title" data-val="Q4 revenue">Q4 revenue</div>
+  <div class="anno" data-el="Primary action" data-val="Export">Export</div>
+</div>
+<script>
+var panel = document.querySelector('.panel');
+var current = null;
+function closeBox(){
+  if (current) current.classList.remove('marked');
+  var ov = panel.querySelector('.overlay');
+  if (ov) ov.remove();
+  current = null;
+}
+function openBox(el){
+  closeBox();
+  current = el;
+  el.classList.add('marked');
+  var ov = document.createElement('div');
+  ov.className = 'overlay';
+  ov.innerHTML = '<div class="modal">' +
+    '<div class="mt">Note: ' + el.dataset.el + '</div>' +
+    (el.dataset.val ? '<div class="ms">Current: ' + el.dataset.val + '</div>' : '') +
+    '<textarea id="cmt" placeholder="What should change? e.g. bolder bar / expand by default / add a year filter"></textarea>' +
+    '<div class="mrow"><button id="cancel">Cancel</button><button class="primary" id="send">Send note \u2197</button></div>' +
+    '</div>';
+  panel.appendChild(ov);
+  ov.querySelector('#cmt').focus();
+  ov.querySelector('#send').onclick = function(){
+    var text = ov.querySelector('#cmt').value.trim();
+    if (text && typeof sendPrompt === 'function') {
+      sendPrompt('[design note] ' + el.dataset.el + (el.dataset.val ? ' (current: ' + el.dataset.val + ')' : '') + ' \u2014 change: ' + text);
+    }
+    closeBox();
+  };
+  ov.querySelector('#cancel').onclick = closeBox;
+  ov.addEventListener('click', function(e){ if (e.target === ov) closeBox(); });
+}
+document.addEventListener('keydown', function(e){ if (e.key === 'Escape') closeBox(); });
+panel.addEventListener('contextmenu', function(e){
+  var el = e.target.closest('.anno');
+  if (!el) return;
+  e.preventDefault(); e.stopPropagation();
+  openBox(el);
+});
+</script>
+\`\`\`
+
+- The host already pre-styles bare \`<button>\` and \`<textarea>\` (token borders, radius, hover/focus) \u2014 use them as-is and add only what is missing: a \`.primary\` variant for the send button and a \`width\`/\`min-height\` override on the \`textarea\`. Do NOT re-declare the base button/field styles. Add a \`\u2197\` to the send button (it triggers \`sendPrompt\`).
+
+Keep it lightweight: annotate only meaningful elements, reuse one overlay, no libraries, and put \`<script>\` last so the draft streams in top-down.`;
 var MODULE_SECTIONS = {
   art: [SVG_SETUP, ART_AND_ILLUSTRATION],
-  mockup: [UI_COMPONENTS, COLOR_PALETTE],
+  mockup: [UI_COMPONENTS, COLOR_PALETTE, ANNOTATABLE_MOCKUP],
   interactive: [UI_COMPONENTS, COLOR_PALETTE],
   chart: [UI_COMPONENTS, COLOR_PALETTE, CHARTS_CHART_JS],
   diagram: [COLOR_PALETTE, SVG_SETUP, DIAGRAM_TYPES]
@@ -43653,7 +44048,7 @@ function renderTaskBinding(taskId) {
 
 ## Bound Task
 
-You are executing task \`${taskId}\`. Read its contract with \`manage_task get\`, update it as you work, and complete it when done.
+You are executing task \`${taskId}\` in THIS run \u2014 it is already assigned to you. Read its contract with \`manage_task get\`, update it as you work, and complete it when done. Do NOT dispatch this task with \`task\`; \`task\` is only for delegating a NEW child subtask.
 `;
 }
 function createBoundTaskLifecycle() {
@@ -44172,7 +44567,7 @@ var manageTaskSchema = z70.object({
   title: z70.string().optional().describe("Task title (required for create)"),
   description: z70.string().optional().describe("Task description in Markdown"),
   priority: z70.enum(["low", "medium", "high"]).optional().describe("Priority level"),
-  status: z70.enum(["pending", "in_progress", "review", "failed", "interrupted", "completed", "cancelled"]).optional().describe("Task status. For status-only changes, prefer set_status action. Set 'in_progress' when you start processing a task you hold; 'completed'/'failed' require the task to be 'in_progress'. Agent summary-only interrupted updates default to missing_input"),
+  status: z70.enum(["pending", "in_progress", "review", "failed", "interrupted", "completed", "cancelled"]).optional().describe("Task status. For status-only changes, prefer set_status action. Set 'in_progress' only for a task THIS run executes (a delegated task is claimed by `task` dispatch); 'completed'/'failed' require the task to be 'in_progress'. Agent summary-only interrupted updates default to missing_input"),
   dueDate: z70.string().optional().describe("Due date (ISO 8601 format)"),
   metadata: z70.record(z70.unknown()).optional().describe("Structured metadata (e.g. projectId, module)"),
   metadataFilter: z70.record(
@@ -45763,8 +46158,8 @@ ${TASK_CONVERGENCE_GUIDANCE}
 - update: Update a task's content fields (title/description/priority/dueDate/metadata/parentId/sourceId/context/ownerId/result/failureReason/requireReview/dependencies/files)
   Status changes can also be done here, but use set_status for a simpler dedicated status update.
 - set_status: Change a task's status (id and status required). Use this when you only need to change the status.
-  Start processing a task you hold: set_status with status='in_progress' (the engine binds it to this run's thread).
-  To mark complete: set_status with status='completed', result='...' (the task must be in_progress)
+  Start a task THIS run executes: set_status with status='in_progress' (the engine binds it to this run's thread). Do NOT set in_progress on a task you will delegate \u2014 leave it pending; \`task\` dispatch claims it.
+  To mark complete: set_status with status='completed', result='...' (the task must be in_progress). Complete a task exactly once: if it is already completed, do not complete it again \u2014 use add_activity for extra notes.
   To mark failed: set_status with status='failed', failureReason='...'
   To pause for input: set_status with status='interrupted', summary='what is needed'
   Valid status values: pending, in_progress, review, failed, interrupted, completed, cancelled.
@@ -45781,16 +46176,16 @@ Report existing keys directly; set 'isNew: true' to add a key the owner does not
 track yet. Belief is evidence metadata: it never blocks a completion, and an
 unmatched or malformed entry is recorded without changing the owner's table.
 Create always persists a pending record \u2014 a supplied status is coerced and no
-execution is dispatched. When you start processing a task you hold, set it
-\`in_progress\` with \`manage_task set_status\`; a dispatched task is claimed
-automatically by the engine. Use \`task { taskId, agentId }\` to delegate a subtask
+execution is dispatched. Set \`in_progress\` yourself ONLY for a task THIS run
+executes; a task you delegate stays \`pending\` and is claimed automatically by
+\`task\` dispatch. Use \`task { taskId, agentId }\` to delegate a subtask
 to an expert \u2014 never re-dispatch the task you are processing.`,
           schema: manageTaskSchema
         }
       ),
       tool64(handleStartTask, {
         name: "task",
-        description: `Start a persisted TaskItem with any existing Agent in a fresh isolated thread. Use this to delegate work \u2014 dispatch a subtask you created to the agent that should execute it; never re-dispatch the task you are currently processing (give the expert a child task instead). Pass agentId "general-purpose" for the general-purpose worker \u2014 ${DEFAULT_GENERAL_PURPOSE_DESCRIPTION} It has access to all the caller's tools, model, and middleware, so use it for general-purpose subtasks, to isolate context and token usage, and whenever no specialized agent fits. The target does NOT need task-management tools: it runs and returns an observation plus an executionResultId, and the caller passes that executionResultId to the manage_task update or add_activity that interprets and records it. A project task instead returns a managed result (success:true, managed:true) because the project-lifecycle queue owns execution.`,
+        description: `Start a persisted TaskItem with any existing Agent in a fresh isolated thread. Use this to delegate work \u2014 dispatch a subtask you created to the agent that should execute it; never re-dispatch the task you are currently processing (give the expert a child task instead). Pass agentId "general-purpose" for the general-purpose worker \u2014 ${DEFAULT_GENERAL_PURPOSE_DESCRIPTION} It has access to all the caller's tools, model, and middleware, so use it for general-purpose subtasks, to isolate context and token usage, and whenever no specialized agent fits. The target does NOT need task-management tools: it runs and returns an observation, an executionResultId, and the task's taskStatus (re-read after the worker settled). Check taskStatus before completing: if it is already 'completed' the worker finished it \u2014 do NOT complete again (use manage_task add_activity); if it is still 'in_progress' you are the single completer and pass the executionResultId to manage_task set_status completed; if it is 'failed' or 'interrupted', act on that. The caller reconciles via manage_task, which interprets the result and records the outcome. A project task instead returns a managed result (success:true, managed:true) because the project-lifecycle queue owns execution.`,
         schema: startTaskSchema
       })
     ]
@@ -47493,7 +47888,7 @@ A plugin is the SET of classes it needs, e.g. \`connection + tools + skills\` or
 | Tool shows an interactive panel | \`sandbox-plugins-ui\` |
 | Tool orchestrates platform tools/agents | \`sandbox-plugins-consume-open\` |
 | Tool callable by external MCP clients | \`sandbox-plugins-expose\` |
-| Run as a long-lived resident service | \`sandbox-plugins-deploy\` |
+| Run as a long-lived resident service (only on the human's explicit request) | \`sandbox-plugins-deploy\` |
 | Validate / test / debug | \`sandbox-plugins-testing\` |
 
 ## Agents (not a supported authoring path)
@@ -47535,8 +47930,8 @@ chart, table, viewer\u2026). It can also call the plugin's OWN tools back from t
 - It is NOT the tool's JSON \`schema\` (that is the input contract for the model).
 - It is NOT the tool \`description\`.
 - It is NOT required: a text/JSON-returning tool needs no UI.
-- Saying "add a UI" means: add a \`ui\` field to the tool in \`plugin.json\` + create
-  \`ui/<tool>.html\`. Details in \`sandbox-plugins-ui\`.
+- Saying "add a UI" means: add a \`ui\` field to the tool in \`plugin.json\` and write
+  \`ui/<tool>.html\` (with \`write_file\`). Details in \`sandbox-plugins-ui\`.
 
 ## Decide first \u2014 clarify these with the user before writing files
 Ask for anything not already stated; do not guess silently:
@@ -47551,7 +47946,7 @@ Ask for anything not already stated; do not guess silently:
      multi-select? connection test needed? \u2192 read \`sandbox-plugins-connection\`.
    - **UI**: should the tool show an interactive panel instead of only text? what
      does it show, how do users interact, external origins? \u2192 read
-     \`sandbox-plugins-ui\` and add \`ui\` + \`ui/<tool>.html\` (step 4 below). If the
+      \`sandbox-plugins-ui\` and add \`ui\` + \`ui/<tool>.html\` (step 6 below). If the
      user says no UI, skip it \u2014 text-only is fine.
    - **Skills**: procedure or knowledge? who consumes it? trigger phrase? tied to a
      specific tool?
@@ -47584,13 +47979,34 @@ Ask for anything not already stated; do not guess silently:
 \`\`\`
 
 ## Flow
-1. Read \`sandbox-plugins-manifest\` and write \`plugin.json\`.
-2. Read \`sandbox-plugins-handlers\` and write each handler.
-3. If the plugin needs credentials: read \`sandbox-plugins-connection\`.
-4. **Only if a tool needs a UI** (UI class in step 3 above): read \`sandbox-plugins-ui\`, add \`ui\` to that tool in \`plugin.json\`, and create \`ui/<tool>.html\` (pass the HTML in the \`manage_plugin\` \`handlers\` map, or write it directly under \`ui/\` and \`reload\`).
-5. If a tool must be callable by external MCP clients: read \`sandbox-plugins-expose\`
+1. **Design first, and iterate \u2014 then get explicit approval before you build (non-trivial plugins).**
+   Before writing any file, produce the design and review it with the human. It has two parts,
+   with different treatments:
+   - **Functional design** (always): an **interactive** component map of what you intend to
+     build \u2014 the tools, their inputs/outputs, whether a connection is needed, whether a UI
+     is needed, and how the agent calls them. Make it click-to-explore (e.g. click a tool to
+     reveal its handler / IO / connection); it is a map to **confirm**, not to annotate.
+   - **UI design** (only when the UI class applies): an **annotatable** mock of the tool's UI \u2014
+     the human right-clicks elements to leave notes (see \`sandbox-plugins-ui\` \u2192
+     "Reviewable drafts").
+   Show both drafts with the \`widget\` middleware, then run the review loop:
+   - Ask the human to review (say how to comment). On each round of comments, **restate the
+     feedback** (element + requested change), then **regenerate the draft with the feedback and
+     present it again** \u2014 comments are "revise and re-show", never "start building".
+   - **Do NOT scaffold or write any file during the loop.** Implement only after the human
+     **explicitly approves**, and ask for that go-ahead yourself before you start.
+   Skip the drafts only for a trivial single-tool plugin whose shape is already agreed \u2014 but
+   still confirm the goal.
+2. Scaffold with \`manage_plugin { action: "create", type, name }\` \u2014 creates
+   \`/root/.agents/plugins/<type>/\` with a stub \`plugin.json\`. It carries no content.
+3. Read \`sandbox-plugins-manifest\` and write \`plugin.json\` with \`write_file\`.
+4. Read \`sandbox-plugins-handlers\` and write each handler with \`write_file\`.
+5. If the plugin needs credentials: read \`sandbox-plugins-connection\`.
+6. **Only if a tool needs a UI** (the UI class from \`sandbox-plugins-patterns\`): read \`sandbox-plugins-ui\`, add \`ui\` to that tool in \`plugin.json\`, and write \`ui/<tool>.html\` with \`write_file\`.
+7. If a tool must be callable by external MCP clients: read \`sandbox-plugins-expose\`
    and add \`expose: true\` (plus \`readOnly\`/\`destructive\` accuracy hints).
-6. Read \`sandbox-plugins-testing\` and iterate using \`manage_plugin\`.
+8. Read \`sandbox-plugins-testing\` and iterate: edit files with \`edit_file\`, then
+   \`validate\` \u2192 \`reload\` \u2192 \`test\`.
 
 Templates: \`templates/plugin.json\`, \`templates/handler.js\`, \`templates/test.js\`, \`templates/discover.js\`, \`templates/ui.html\`.
 `,
@@ -47652,6 +48068,20 @@ description: Add an interactive HTML UI to a tenant plugin tool (rendered as a s
 A tool can declare an HTML file that Axiom renders as a sandboxed MCP App when
 the tool runs. The app can call the plugin's OWN tools back.
 
+## Reviewable drafts (before you build the real UI)
+When you show a **UI mock with \`show_widget\`** for the user to react to (the design
+step, before writing \`ui/<tool>.html\`), make it **annotatable**: the user right-clicks
+any element to leave a comment that comes back to you as a message. Turn it on by
+default for review drafts and include a small visible hint (e.g. "\u53F3\u952E\u4EFB\u610F\u5143\u7D20\u6279\u6CE8");
+the \`widget\` mockup guidelines have the pattern. Omit it only when the draft is meant
+to be purely experienced (a live demo with no review) \u2014 then leave out the hint and
+the handlers. This is only for the **mock**: the real \`ui/<tool>.html\` is the plugin's
+product and is never annotatable.
+A round of annotations is **NOT approval**: restate the comments you received, regenerate
+the mock from them, and show it again, iterating until the human is satisfied. Build
+\`ui/<tool>.html\` only after the human **explicitly approves** \u2014 and ask for that go-ahead
+yourself.
+
 ## Declare it
 \`\`\`
 /root/.agents/plugins/<type>/
@@ -47684,11 +48114,10 @@ the tool runs. The app can call the plugin's OWN tools back.
 - Omit \`csp\` for the restrictive default (\`default-src 'none'\`). WebAssembly is allowed by default.
 
 ## How to write the HTML file
-The HTML must end up at \`/root/.agents/plugins/<type>/ui/<tool>.html\`. Two ways:
-- \`manage_plugin\` create/update: pass it in the \`handlers\` map \u2014 that map carries ALL
-  plugin files, not just JS handlers. Example: \`handlers\` = \`{ "handlers/render_report.js": "<js...>", "ui/report.html": "<!doctype html>..." }\`.
-  The validator's existence check runs against these keys, so an HTML file NOT in this map is treated as missing (\`TOOL_UI\`).
-- Or write the file directly in the sandbox under \`ui/\` and call \`manage_plugin reload\`.
+Write the HTML to \`/root/.agents/plugins/<type>/ui/<tool>.html\` with \`write_file\`,
+then call \`manage_plugin { action: "reload", type }\` so the host serves the new HTML.
+The file must be declared by a tool's \`ui.resource\` in \`plugin.json\`, otherwise it is
+treated as missing (\`TOOL_UI\`).
 
 ## How it behaves at runtime
 - The tool result carries a hidden \`mcp_app\` marker; Axiom renders \`ui/<tool>.html\` inline. \`displayMode\` is recorded but NOT yet honored \u2014 fullscreen happens only when the app itself calls \`ui/request-display-mode\`.
@@ -47784,7 +48213,7 @@ grants apply to the UI too). See \`sandbox-plugins-expose\`.
 ## Gotchas
 - \`ui.resource\` must be a safe relative path ending in \`.html\` that EXISTS; otherwise the UI is dropped (diagnostic \`TOOL_UI\`) but the tool still loads.
 - \`displayMode\`, \`permissions\`, and \`prefersBorder\` are accepted but NOT yet applied.
-- After editing the HTML, call \`manage_plugin reload\` (or bump \`version\`); the host caches the HTML (TTL ~5 min) and, if a fetch fails, may keep serving a stale copy until it succeeds.
+- After editing the HTML, call \`manage_plugin { action: "reload", type }\`; the host caches the resource, so a reload is what makes it re-read the new file.
 
 Start from \`templates/ui.html\`.
 `,
@@ -48048,21 +48477,23 @@ description: Validate, test, and reload a tenant sandbox plugin using the manage
 
 Use the \`manage_plugin\` tool. The loop:
 
-1. \`action: "validate"\` with \`{ type, manifest, handlers }\` \u2014 dry-run, no writes, returns diagnostics.
-2. \`action: "create"\` or \`"update"\` \u2014 writes files, bumps version, reloads.
+1. Write/edit the plugin files with the filesystem tools (\`write_file\`/\`edit_file\`) under
+   \`/root/.agents/plugins/<type>/\`; \`create\` only scaffolds the directory + stub.
+2. \`action: "validate"\` with \`{ type }\` \u2014 reads the plugin back **from the sandbox** and returns diagnostics (no writes). The files must already be on disk; a \`type\` with no files reports a read error.
 3. If the plugin has \`connection.fields\` and a tool reads credentials: a **human**
    must configure a connection of this plugin type. You cannot create credentials.
    Call \`list_connections { type }\` first \u2014 if none exist, use \`ask_user_to_clarify\`
    to state explicitly that only the human can configure the connector, ask them to
    add it (Console \u2192 Connections) and to give you the connection key. Do not claim
    the tool works until a real \`connectionKey\` test passes.
-4. \`action: "test"\` to exercise a handler without an LLM:
+4. \`action: "reload"\` \u2014 refresh the compiled catalog after writing/editing files (the catalog caches; an edited file is invisible to \`test\` until you reload).
+5. \`action: "test"\` to exercise a handler without an LLM:
    - Tool: \`{ type, target: { kind: "tool", name, input, connectionKey? } }\`
    - Connection: \`{ type, target: { kind: "connection-test" } }\` or \`{ kind: "connection-discover" }\`
    Returns \`{ ok, result, exitCode, durationMs, stdout, stderr }\`.
    For credentialed tools, pass the real \`connectionKey\`. Without one, the handler
    receives an empty connection \u2014 that only checks plumbing, NOT functional success.
-5. \`action: "reload"\` if you edited files directly.
+6. \`action: "backup"\` / \`"restore"\` \u2014 manual snapshot and rollback. \`backup\` copies the plugin into \`.backup/\` **inside its own directory** (keeps only the latest), and \`restore\` makes the plugin match that snapshot (adds back missing files, removes files added since). Use it before a risky rewrite.
 
 ## Secrets
 - \`list_connections\` returns identifiers only (\`key\`/\`name\`/\`description\`), never config or secrets.
@@ -48077,10 +48508,10 @@ Use the \`manage_plugin\` tool. The loop:
 | HANDLER_MISSING | handler path wrong or file not written |
 | TOOL_SCHEMA | unsupported JSON Schema keyword |
 | non-zero exit | handler threw; read stdout/stderr from \`test\` |
-| old behaviour after edit | version/hash unchanged \u2014 bump \`version\` or call \`reload\` |
+| old behaviour after edit | the catalog caches by content hash/TTL \u2014 call \`reload\` |
 | empty connection in handler | no \`connectionKey\` passed, or no connection configured for this type |
 
-Fall back to \`execute_code\`/\`shell\` to run \`node handlers/x.js\` manually with
+Fall back to \`shell_exec\` to run \`node handlers/x.js\` manually with
 \`PLUGIN_INPUT\` and a synthetic \`PLUGIN_CONNECTION_FILE\` to reproduce logic bugs.
 A synthetic fixture only verifies plumbing \u2014 a real upstream call requires a real
 \`connectionKey\` configured by a human.
@@ -48091,7 +48522,7 @@ A synthetic fixture only verifies plumbing \u2014 a real upstream call requires
     version: "1.0.0",
     content: `---
 name: sandbox-plugins-deploy
-description: Deploy a validated tenant plugin as a resident service (alwaysOn vs onDemand), check its status, and undeploy it. Trigger: after a plugin's tests pass and it should run as a long-lived service, or when inspecting/removing a deployment.
+description: Deploy a validated tenant plugin as a resident service (alwaysOn vs onDemand), check its status, and undeploy it. Trigger: the human explicitly asks to run a plugin as a long-lived resident service (or to inspect/remove one) \u2014 deployment is human-gated, never automatic.
 ---
 
 # Deploying a Plugin as a Resident Service
@@ -48101,10 +48532,13 @@ Optionally, you can **deploy** the plugin as a **resident service**: one
 long-lived sandbox per plugin that serves every call. This is faster for
 frequent or heavy calls, but costs a running sandbox.
 
-## Precondition: tests must pass first
-Deploy ONLY after the plugin is validated AND its tests pass:
-1. \`manage_plugin validate\` \u2014 no diagnostics.
-2. \`manage_plugin create\`/\`update\` \u2014 written and reloaded.
+## Precondition: human request, then tests must pass first
+Deployment is **opt-in and human-gated**: NEVER deploy on your own after tests
+pass. Wait until the human explicitly asks for it or approves it. A passing test
+is necessary but NOT sufficient to deploy.
+Then confirm the plugin is validated AND its tests pass:
+1. Files written with the filesystem tools and \`reload\` run.
+2. \`manage_plugin validate\` \u2014 no diagnostics.
 3. \`manage_plugin test\` \u2014 every tool/connection test returns \`ok: true\`
    (a real \`connectionKey\` test for credentialed tools).
 Never deploy a plugin you have not tested: a resident service wraps the same
@@ -48172,6 +48606,30 @@ load "sandbox-plugins-expose" and follow it (\`expose: true\` + key grants).
 If a tool must call the platform's own tools/agents from its handler, load
 "sandbox-plugins-consume-open".
 
+Design first, and iterate on it before you build \u2014 the design is a conversation, not
+a one-shot. Use the \`widget\` middleware to present it (a decision surface, not a showcase):
+- **Functional design** (always): an **interactive** component map of the shape you
+  intend to build \u2014 which tools, their inputs/outputs, whether a connection or a UI
+  is needed, how the agent calls them. Make it click-to-explore (and prefer it over
+  an SVG flowchart); it is a map to **confirm**, NOT an annotatable draft.
+- **UI design** (UI class only): an **annotatable** mock of the tool's UI \u2014 the human
+  right-clicks elements to leave notes.
+Then run a review loop:
+- Ask the human to review (tell them how to comment). When they send comments, **restate the
+  feedback** (which element, what change) so they can confirm you understood, then **build a
+  NEW draft that incorporates the feedback and present it again**; keep iterating until
+  they are satisfied. Comments mean "revise and re-show", NOT "start building".
+- Do NOT scaffold or write any file during the loop. Implement only once the human
+  **explicitly approves** the design \u2014 and still ASK for that go-ahead yourself; never
+  start building on your own initiative.
+Also surface genuinely different options (scope, layout, which tools) visually and let
+the human choose, instead of describing them in prose.
+
+How to render a good widget is the widget middleware's own concern \u2014 follow it
+there; keep this prompt to plugin-design intent. These widgets are design aids
+only; the plugin's actual UI is still the MCP App HTML you author and test with
+\`manage_plugin\`.
+
 Plan with persistent Tasks: MANDATORY until you load "task-tracking" with the
 \`skill\` tool, call neither \`manage_task\` nor any other task operation. Use
 persistent Tasks as the development planning surface and create one Task per
@@ -48179,7 +48637,16 @@ independently verifiable outcome (for example "manifest written", "handlers
 implemented", "UI added", "validated/tested via manage_plugin"). As you work,
 update each Task's status to reflect reality. Never use \`write_todos\`.
 
-Author with the \`manage_plugin\` tool: validate, then create/update, then test.
+After the human confirms the design, author the plugin files directly with the filesystem tools, then verify with \`manage_plugin\`.
+1. Scaffold once: \`manage_plugin { action: "create", type: "<type>", name }\` \u2014 it creates
+   \`/root/.agents/plugins/<type>/\` with a stub \`plugin.json\`. It never carries content.
+2. Write and edit every file yourself with \`write_file\` / \`edit_file\` (read back with
+   \`read_file\`) under \`/root/.agents/plugins/<type>/\`: \`plugin.json\`, \`handlers/*.js\`, and
+   (UI class) \`ui/*.html\`. Change one file at a time; edit in place instead of rewriting.
+3. Verify in order: \`manage_plugin { action: "validate", type }\` (reads the files back from
+   the sandbox) \u2192 \`manage_plugin { action: "reload", type }\` (the catalog caches, so a
+   freshly written file is invisible to \`test\` until you reload) \u2192 \`manage_plugin
+   { action: "test", type, target }\`.
 If a tool needs credentials, a human must configure the connection \u2014 use
 \`list_connections\` to check, and \`ask_user_to_clarify\` to ask the human to add
 the connector and give you its key. Only after a real \`connectionKey\` test
@@ -48188,14 +48655,15 @@ unverified (missing credentials), not as passing. Use \`shell_exec\` (the tool
 provided by the \`code_eval\` middleware) to run \`node handlers/x.js\` for manual
 checks when reproducing a failure.
 
-After the plugin passes \`validate\` and its tests, deploy it as a resident
-service: load "sandbox-plugins-deploy" and follow it. Choose \`onDemand\`
+Deployment is human-gated: do NOT deploy on your own after the tests pass.
+Only deploy when the human explicitly asks for it or approves it, then load
+"sandbox-plugins-deploy" and follow it. Choose \`onDemand\`
 (default) or \`alwaysOn\` for hot paths, call \`manage_plugin deploy\` with the
 chosen \`mode\`, then confirm with \`manage_plugin status\` (\`running\`). Only claim
 the plugin is deployed and serving once \`status\` reports \`running\`; if the
 environment reports no deployment service, say so and treat deployment as
-unavailable \u2014 do NOT claim success. \`undeploy\` removes the service without
-touching the plugin files.`;
+unavailable \u2014 do NOT claim success. Report the plugin as ready and let the human
+decide; \`undeploy\` removes the service without touching the plugin files.`;
 
 // src/middlewares/sandboxPluginsUi.ts
 var SANDBOX_PLUGINS_UI_RESOURCE = "ui://sandbox-plugins/app";
@@ -48371,6 +48839,7 @@ var SANDBOX_PLUGINS_APP_HTML = `<!doctype html>
 `;
 
 // src/middlewares/sandboxPluginsMiddleware.ts
+var PLUGINS_ROOT3 = "/root/.agents/plugins";
 var SANDBOX_PLUGINS_UI_REF = {
   kind: "plugin",
   pluginType: "sandbox-plugins",
@@ -48427,18 +48896,19 @@ var managePluginSchema = z73.object({
     "get",
     "validate",
     "create",
-    "update",
     "delete",
     "reload",
     "test",
+    "backup",
+    "restore",
     "deploy",
     "undeploy",
     "status",
     "deployments"
   ]),
   type: z73.string().optional(),
-  manifest: z73.record(z73.unknown()).optional(),
-  handlers: z73.record(z73.string()).optional(),
+  name: z73.string().optional(),
+  description: z73.string().optional(),
   mode: z73.enum(["onDemand", "alwaysOn"]).optional(),
   target: z73.object({
     kind: z73.enum(["tool", "connection-test", "connection-discover"]),
@@ -48452,12 +48922,12 @@ var sandboxPluginsPlugin = {
     type: "sandbox-plugins",
     category: "execution",
     name: "Sandbox Plugins",
-    description: "Author and manage tenant plugins stored in the sandbox: list/validate/create/update/delete/reload/test, and deploy/undeploy/status/deployments to run a plugin as a resident service. Tools are agent-callable JS handlers and may declare an optional interactive HTML UI (rendered as a sandboxed MCP App). Pairs with the Skill plugin for authoring guidance.",
+    description: "Author and manage tenant plugins stored in the sandbox: list/validate/create/delete/reload/test/backup/restore, and deploy/undeploy/status/deployments to run a plugin as a resident service. Tools are agent-callable JS handlers and may declare an optional interactive HTML UI (rendered as a sandboxed MCP App). Pairs with the Skill plugin for authoring guidance.",
     recommends: ["skill"],
     tools: [
       {
         name: "manage_plugin",
-        description: "Author and manage tenant sandbox plugins (tools, optional per-tool HTML UI, connections, Open/MCP exposure, and resident deployment). Actions: list/get/validate/create/update/delete/reload/test, deploy/undeploy/status, and `deployments` to list every resident deployment for the tenant.",
+        description: "Author and manage tenant sandbox plugins (tools, optional per-tool HTML UI, connections, Open/MCP exposure, and resident deployment). Actions: list/get/validate/create/delete/reload/test/backup/restore, deploy/undeploy/status, and `deployments` to list every resident deployment for the tenant.",
         ui: { resource: SANDBOX_PLUGINS_UI_RESOURCE, displayMode: "inline" }
       }
     ],
@@ -48484,7 +48954,7 @@ var sandboxPluginsPlugin = {
           id: "sandbox-plugins",
           type: "sandbox-plugins",
           name: "Sandbox Plugins",
-          description: "Author and manage tenant plugins (list/validate/create/update/delete/reload/test/deploy/undeploy/status)",
+          description: "Author and manage tenant plugins (list/validate/create/delete/reload/test/backup/restore/deploy/undeploy/status)",
           enabled: true,
           config: {}
         },
@@ -48504,6 +48974,14 @@ var sandboxPluginsPlugin = {
           enabled: true,
           config: {}
         },
+        {
+          id: "widget",
+          type: "widget",
+          name: "Widget",
+          description: "Align on the plugin design before building it: show the shape you intend to build (tools, IO, connections, UI) and a UI mock for the human to correct scope before files exist.",
+          enabled: true,
+          config: {}
+        },
         {
           id: "ask_user_to_clarify",
           type: "ask_user_to_clarify",
@@ -48544,6 +49022,7 @@ var sandboxPluginsPlugin = {
               return JSON.stringify({
                 plugins: loaded.plugins.map((p) => ({
                   type: p.meta.type,
+                  path: `${PLUGINS_ROOT3}/${p.meta.type}`,
                   name: p.meta.name,
                   tools: p.meta.tools?.map((t) => t.name) ?? [],
                   source: p.meta.source
@@ -48554,32 +49033,87 @@ var sandboxPluginsPlugin = {
             }
             case "get": {
               if (!input.type) return "type is required";
-              return await catalog2.readPluginFile(tenantId2, input.type, "plugin.json");
+              const content = await catalog2.readPluginFile(tenantId2, input.type, "plugin.json");
+              let manifest = content;
+              try {
+                manifest = JSON.parse(content);
+              } catch {
+              }
+              return JSON.stringify({
+                type: input.type,
+                path: `${PLUGINS_ROOT3}/${input.type}`,
+                manifest
+              });
             }
             case "reload": {
               const loaded = await catalog2.reload(tenantId2);
               void publishPluginCatalogChanged(tenantId2);
               return JSON.stringify({ reloaded: true, plugins: loaded.plugins.length, diagnostics: loaded.diagnostics });
             }
-            case "create":
-            case "update": {
-              if (!input.type || !input.manifest) return "type and manifest are required";
-              const handlers = input.handlers ?? {};
+            case "backup": {
+              if (!input.type) return "type is required";
+              try {
+                const result = await catalog2.backupPlugin(tenantId2, input.type);
+                if (result.files === 0) {
+                  return JSON.stringify({ backedUp: false, error: "nothing to back up (plugin has no files)" });
+                }
+                return JSON.stringify({ backedUp: true, files: result.files });
+              } catch (err) {
+                return JSON.stringify({ backedUp: false, error: errorText(err) });
+              }
+            }
+            case "restore": {
+              if (!input.type) return "type is required";
+              let restored;
+              let failure3;
+              try {
+                restored = await catalog2.restorePlugin(tenantId2, input.type);
+              } catch (err) {
+                failure3 = errorText(err);
+              }
+              try {
+                await catalog2.reload(tenantId2);
+                void publishPluginCatalogChanged(tenantId2);
+              } catch {
+              }
+              if (failure3) return JSON.stringify({ restored: false, error: failure3 });
+              return JSON.stringify({ restored: true, files: restored?.files ?? 0 });
+            }
+            case "create": {
+              if (!input.type) return "type is required";
               const known = new Set(
                 (catalog2.getCached(tenantId2)?.plugins ?? []).map((p) => p.meta.type).filter((t) => t !== input.type)
               );
+              const stub = {
+                schemaVersion: 1,
+                type: input.type,
+                name: input.name ?? input.type,
+                description: input.description ?? "",
+                version: "0.1.0",
+                tools: []
+              };
               const check = validateSandboxPluginManifest({
-                raw: input.manifest,
+                raw: stub,
                 dirName: input.type,
                 reservedTypes: new Set(PluginRegistry.list()),
                 knownTypes: known,
-                handlerExists: (rel) => rel in handlers
+                handlerExists: () => true
               });
-              if (!check.manifest) return JSON.stringify({ written: false, diagnostics: check.diagnostics });
-              await catalog2.writePlugin(tenantId2, input.type, input.manifest, handlers);
+              if (!check.manifest) {
+                return JSON.stringify({ created: false, diagnostics: check.diagnostics });
+              }
+              const files = await catalog2.listPluginFiles(tenantId2, input.type);
+              if (files.includes("plugin.json")) {
+                return JSON.stringify({ created: false, error: "plugin already exists" });
+              }
+              await catalog2.writePlugin(tenantId2, input.type, check.manifest, {});
               const loaded = await catalog2.reload(tenantId2);
               void publishPluginCatalogChanged(tenantId2);
-              return JSON.stringify({ written: true, diagnostics: loaded.diagnostics, hash: loaded.hash });
+              return JSON.stringify({
+                created: true,
+                path: `${PLUGINS_ROOT3}/${input.type}`,
+                diagnostics: loaded.diagnostics
+              });
             }
             case "delete": {
               if (!input.type) return "type is required";
@@ -48590,18 +49124,8 @@ var sandboxPluginsPlugin = {
             }
             case "validate": {
               if (!input.type) return "type is required";
-              const handlers = input.handlers ?? {};
-              const known = new Set(
-                (catalog2.getCached(tenantId2)?.plugins ?? []).map((p) => p.meta.type).filter((t) => t !== input.type)
-              );
-              const result = validateSandboxPluginManifest({
-                raw: input.manifest ?? {},
-                dirName: input.type,
-                reservedTypes: new Set(PluginRegistry.list()),
-                knownTypes: known,
-                handlerExists: (rel) => rel in handlers
-              });
-              return JSON.stringify({ diagnostics: result.diagnostics, valid: Boolean(result.manifest) });
+              const result = await catalog2.validatePluginFromDisk(tenantId2, input.type);
+              return JSON.stringify({ diagnostics: result.diagnostics, valid: result.valid });
             }
             case "test": {
               if (!input.type || !input.target) return "type and target are required";
@@ -48675,7 +49199,16 @@ var sandboxPluginsPlugin = {
                     assistantId: typeof runCfg.assistant_id === "string" ? runCfg.assistant_id : void 0
                   }
                 });
-                return handlerResultText(redactSecretValues(result, secrets));
+                const text = handlerResultText(redactSecretValues(result, secrets));
+                const ui = toolDef.ui;
+                if (!ui?.resource) return text;
+                const uiRef = {
+                  kind: "plugin",
+                  pluginType: input.type,
+                  resource: ui.resource,
+                  displayMode: ui.displayMode ?? "inline"
+                };
+                return appendUiFence(text, uiRef);
               } catch (err) {
                 return JSON.stringify(redactSecretValues({ ok: false, error: errorText(err) }, secrets));
               }
@@ -48747,7 +49280,7 @@ var sandboxPluginsPlugin = {
         },
         {
           name: "manage_plugin",
-          description: "Author and manage tenant sandbox plugins (list/get/validate/create/update/delete/reload/test) and deploy/undeploy/status a plugin as a resident service.",
+          description: "Author and manage tenant sandbox plugins (list/get/validate/create/delete/reload/test/backup/restore) and deploy/undeploy/status a plugin as a resident service.",
           schema: managePluginSchema
         }
       )
@@ -49923,6 +50456,7 @@ export {
   buildTableName,
   buildTaskMutationFallback,
   buildTaskNormalizationFallback,
+  canConvergeOrphan,
   checkEmptyContent,
   clearEncryptionKeyCache,
   clearEvalRunService,
@@ -49972,6 +50506,7 @@ export {
   createTaskLifecycleService,
   createTaskMiddleware,
   createTaskRunBridge,
+  createTaskRunLiveness,
   createTeamMiddleware,
   createTeammateTools,
   createTrustedAgentMessageDispatcher,
@@ -50069,6 +50604,7 @@ export {
   isMcpConnectionError,
   isPluginSkillAuthorizedInSandbox,
   isPluginSkillManagedInSandbox,
+  isTaskRunLeaseHeld,
   isUsingDefaultKey,
   isValidCronExpression,
   isValidSandboxName,