@awak-app/simy-cli 0.4.0 → 0.5.1

package/README.md

@@ -9,8 +9,8 @@ npm install -g @awak-app/simy-cli
 simy --daemon
 ```
 
-This is the recommended installation because the daemon can safely install
-patch releases and restart itself when no Agentic Loop task is active. To run
+This is the recommended installation because the CLI can safely install patch
+and minor releases, and the daemon restarts only when no Agentic Loop task is active. To run
 the interactive chat after installation, use `simy`.
 
 For a one-time evaluation or source development, these modes remain supported:
@@ -135,23 +135,54 @@ available for older Web clients.
 
 ## CLI updates
 
-The CLI checks the npm registry at startup and once per hour while it is
-running. A daemon installed with `npm install -g` automatically installs stable
-patch releases only after a strict idle check confirms that there is no active,
-paused, blocked, or human-waiting task, executor child process, or pending
-ledger write. It stops accepting new work during installation, starts the new
-daemon, verifies its version and local health handoff, and only then closes the
-old process.
+Every command checks the stable npm release before dispatch, including `simy`,
+`simy --daemon`, `simy sqm min-check`, and `simy sqm check`. Globally installed
+patch releases update silently; minor releases update automatically with one
+short notice. The updated executable is verified and then re-executes the exact
+original argv once. A process-wide nonce/version guard prevents update loops.
+Major releases are never installed at startup: `simy update` asks for explicit
+confirmation (`simy update --yes` is available for non-interactive automation).
 
-Foreground, `npx`, source-checkout, fixed-port, minor, and major updates are not
-restarted silently. The CLI instead displays the exact command a normal user
-can run:
+Use these commands to inspect or apply an update explicitly:
+
+```bash
+simy update --check
+simy update
+```
+
+A running daemon also checks hourly. Before installing, its strict idle gate
+confirms there is no active, paused, blocked, or human-waiting task, executor
+child process, or pending ledger write. It stops accepting new work during
+installation, verifies the installed package, starts the new daemon, verifies
+its version and local health handoff, and only then closes the old process.
+Fixed-port daemons retain the manual restart path.
+
+Only a global npm installation may be changed automatically. `npx`, a source
+checkout, and a normal dependency installation are read-only and display an
+exact recovery command instead:
 
 ```bash
 npm install -g @awak-app/simy-cli@<version> && simy --daemon
 ```
 
-Use `--no-auto-update` or `SIMY_AUTO_UPDATE=0` to disable background checks.
+If installation or startup verification fails, the updater restores the
+current exact version when possible and prints both the pinned recovery command
+and the target command. Use `--no-auto-update` or `SIMY_AUTO_UPDATE=0` to disable
+all update checks and writes for any command.
+
+CLI `0.3.3` predates this startup updater and cannot use it to upgrade itself.
+The last required manual bridge is:
+
+```bash
+npm install -g @awak-app/simy-cli@0.4.0
+```
+
+From `0.4.0` onward, subsequent compatible minor releases update automatically.
+When SQM Cloud returns structured `incompatible_cli`, the CLI runs the same
+verified updater and re-executes the original SQM command at most once. An SQM
+min-check or full check pins its CLI version and signed knowledge bundle for the
+entire execution; no update is applied mid-check.
+
 The current update state is also exposed by `GET /v1/health` as `cli_update`.
 Auto-update E2E screenshots are generated locally under
 `.artifacts/cli-auto-update/`; this ignored directory must not be committed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Local SIMY executor for non-coding Local Tasks and Agentic Loop runs.",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "test": "node --test",
     "test:e2e:console": "node ./scripts/console-e2e.js",
     "test:e2e:sqm-complete-loop": "node ./scripts/sqm-complete-loop-e2e.js",
+    "test:e2e:sqm-local-review": "node ./scripts/sqm-local-review-e2e.js",
     "test:e2e:console:narrow": "CLI_E2E_COLUMNS=78 CLI_E2E_ROWS=40 node ./scripts/console-e2e.js",
     "test:e2e:console:no-color": "CLI_E2E_NO_COLOR=1 node ./scripts/console-e2e.js",
     "test:e2e:console:recovery": "node ./scripts/console-recovery-e2e.js",
@@ -37,7 +38,7 @@
     "test:e2e:console:fullstack": "node ./scripts/fullstack-cli-smoke.js",
     "check": "npm run check:auto-update && node --check ./src/desktop-executor.js && node --check ./src/local-task.js && node --check ./scripts/desktop-executor-e2e.js && node --check ./scripts/pre-guardrail-e2e.js && node --check ./scripts/fixtures/fake-desktop-provider.js && npm run check:syntax && npm run check:real-provider-syntax && npm test && npm run check:package",
     "check:auto-update": "node --check ./src/auto-update.js && node --check ./scripts/auto-update-e2e.js && npm run check:sqm",
-    "check:sqm": "node --check ./src/sqm/canonical.js && node --check ./src/sqm/validation.js && node --check ./src/sqm/repository.js && node --check ./src/sqm/checkers.js && node --check ./src/sqm/bundle-store.js && node --check ./src/sqm/proof.js && node --check ./src/sqm/evidence-client.js && node --check ./src/sqm/session.js && node --check ./src/sqm/index.js && node --check ./src/sqm/command.js && node --check ./scripts/sqm-complete-loop-e2e.js",
+    "check:sqm": "node --check ./src/sqm/canonical.js && node --check ./src/sqm/validation.js && node --check ./src/sqm/repository.js && node --check ./src/sqm/checkers.js && node --check ./src/sqm/bundle-store.js && node --check ./src/sqm/proof.js && node --check ./src/sqm/evidence-client.js && node --check ./src/sqm/session.js && node --check ./src/sqm/index.js && node --check ./src/sqm/command.js && node --check ./src/sqm/agent-skill.js && node --check ./src/sqm/review-worker.js && node --check ./scripts/sqm-complete-loop-e2e.js && node --check ./scripts/sqm-local-review-e2e.js",
     "check:real-provider-syntax": "node --check ./scripts/real-codex-probe.js && node --check ./scripts/real-claude-probe.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js",
     "check:syntax": "node --check ./src/index.js && node --check ./src/agent.js && node --check ./src/browser.js && node --check ./src/web-api.js && node --check ./src/durable-local-task-worker.js && node --check ./src/durable-local-task-steps-contract.js && node --check ./src/bounded-local-task-subtasks-contract.js && node --check ./src/bounded-local-task-subtask-pool.js && node --check ./src/local-task-artifact-contract.js && node --check ./src/execution-capability-contract.js && node --check ./src/shutdown.js && node --check ./src/run-registry.js && node --check ./src/direct-executor.js && node --check ./src/execution-guardrail.js && node --check ./src/backend-executable.js && node --check ./src/provider-stream.js && node --check ./src/console/index.js && node --check ./src/console/app.js && node --check ./src/console/commands.js && node --check ./src/local-attachments.js && node --check ./src/repository-inventory.js && node --check ./src/session-store.js && node --check ./src/web-origin.js && node --check ./src/workspace-context.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/recovery.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/completion-contract.js && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/problem-solving.js && node --check ./src/orchestrator/budget.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/retry.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./scripts/fixtures/completion-contract-fixture.js && node --check ./scripts/fixtures/fake-coding-backend.js && node --check ./scripts/e2e-terminal-evidence.js && node --check ./scripts/audit-gate-e2e.js && node --check ./scripts/completion-contract-e2e.js && node --check ./scripts/retry-circuit-e2e.js && node --check ./scripts/follow-up-charter-e2e.js && node --check ./scripts/task-routing-e2e.js && node --check ./scripts/executor-version-preflight-e2e.js && node --check ./scripts/blocked-recovery-e2e.js && node --check ./scripts/process-localization-e2e.js && node --check ./scripts/hypothesis-retries-e2e.js && node --check ./scripts/budget-enforcement-e2e.js && node --check ./scripts/local-task-default-workspace-e2e.js && node --check ./scripts/local-task-idempotency-e2e.js && node --check ./scripts/console-e2e-fixture.js && node --check ./scripts/console-e2e.js && node --check ./scripts/console-recovery-e2e-fixture.js && node --check ./scripts/console-recovery-e2e.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/fullstack-cli-smoke.js && node --check ./scripts/check-package-contents.js",
     "check:package": "node ./scripts/check-package-contents.js"

package/src/agent.js

@@ -115,6 +115,11 @@ import {
   normalizeLocalTaskScenarioPack,
   validateLocalTaskScenarioInputs,
 } from "./local-task-scenario-packs.js";
+import { inspectSqmAgentSkill, installSqmAgentSkill } from "./sqm/agent-skill.js";
+import {
+  createSqmLocalReviewApi,
+  createSqmLocalReviewWorker,
+} from "./sqm/review-worker.js";
 
 const DEVICE_HEARTBEAT_INTERVAL_MS = 20_000;
 
@@ -143,6 +148,10 @@ export async function startAgent({
     });
   await localTaskAttachmentStore.cleanupExpired?.();
   const authNonce = randomBytes(16).toString("base64url");
+  const sqmAgentIntegration = dependencies.sqmAgentIntegration || {
+    inspect: () => inspectSqmAgentSkill({ home: dependencies.home }),
+    install: (options) => installSqmAgentSkill({ home: dependencies.home, ...options }),
+  };
   let session = await readSession(apiOrigin, sessionRoot);
   if (session && sessionRequiresWebAuthorization(session, apiOrigin)) session = null;
   await cleanupExpiredRuns();
@@ -168,23 +177,39 @@ export async function startAgent({
   );
   const installMode = updateManager?.snapshot?.()?.install_mode ?? null;
   const inspectedCapabilities = await readCapabilities(dependencies);
+  const durableControlPlane =
+    inspectedCapabilities?.features?.local_task_control_plane === true;
+  const hasSqmLocalReview = Object.hasOwn(
+    inspectedCapabilities?.features || {},
+    "sqm_local_review",
+  );
   const contractSourceCapabilities =
-    inspectedCapabilities?.features?.local_task_control_plane === true
+    durableControlPlane || hasSqmLocalReview
       ? {
           ...inspectedCapabilities,
           features: {
-            ...inspectedCapabilities.features,
-            local_task_control_plane: daemon,
-            pipeline_local_task_artifacts:
-              daemon &&
-              inspectedCapabilities.features.pipeline_local_task_artifacts === true,
-            durable_local_task_attachments: daemon,
-            durable_local_task_steps:
-              daemon &&
-              inspectedCapabilities.features.durable_local_task_steps === true,
-            bounded_local_task_subtasks:
-              daemon &&
-              inspectedCapabilities.features.bounded_local_task_subtasks === true,
+            ...inspectedCapabilities?.features,
+            ...(durableControlPlane
+              ? {
+                  local_task_control_plane: daemon,
+                  pipeline_local_task_artifacts:
+                    daemon &&
+                    inspectedCapabilities.features.pipeline_local_task_artifacts === true,
+                  durable_local_task_attachments: daemon,
+                  durable_local_task_steps:
+                    daemon &&
+                    inspectedCapabilities.features.durable_local_task_steps === true,
+                  bounded_local_task_subtasks:
+                    daemon &&
+                    inspectedCapabilities.features.bounded_local_task_subtasks === true,
+                }
+              : {}),
+            ...(hasSqmLocalReview
+              ? {
+                  sqm_local_review:
+                    daemon && inspectedCapabilities?.features?.sqm_local_review === true,
+                }
+              : {}),
           },
         }
       : inspectedCapabilities;
@@ -211,6 +236,7 @@ export async function startAgent({
   let heartbeatTimer = null;
   let heartbeatInFlight = null;
   let durableLocalTaskWorker = null;
+  let sqmLocalReviewWorker = null;
 
   const restoreRemoteRuns = async () => {
     if (!isSessionValid(session, Date.now(), apiOrigin) || !session?.device_id) return;
@@ -254,7 +280,10 @@ export async function startAgent({
         }),
       )
       .then(async () => {
-        if (durableLocalTaskWorker) await durableLocalTaskWorker.poll();
+        const sqmResult = sqmLocalReviewWorker
+          ? await sqmLocalReviewWorker.poll()
+          : null;
+        if (!sqmResult && durableLocalTaskWorker) await durableLocalTaskWorker.poll();
         return true;
       })
       .finally(() => {
@@ -362,6 +391,27 @@ export async function startAgent({
     });
   }
 
+  if (daemon && availableCapabilities?.features?.sqm_local_review === true) {
+    const sqmApi =
+      dependencies.sqmLocalReviewApi ||
+      createSqmLocalReviewApi({
+        getConnection: () => ({
+          apiOrigin,
+          apiBaseUrl: session?.api_base_url,
+          token: session?.token,
+        }),
+        fetchImpl: dependencies.fetch || globalThis.fetch,
+      });
+    const createWorker =
+      dependencies.createSqmLocalReviewWorker || createSqmLocalReviewWorker;
+    sqmLocalReviewWorker = createWorker({
+      api: sqmApi,
+      beginWork: () => acquireUpdateWork(updateManager),
+      runReview: dependencies.runSqmLocalReview,
+      onError: (error) => reportSqmLocalReviewError(error, quiet),
+    });
+  }
+
   const selectRepository = async (run, repository) => {
     if (run) ensureAcceptingNewWork(updateManager);
     const selected = repository?.local_path
@@ -435,6 +485,34 @@ export async function startAgent({
         json(res, 200, refreshAvailableCapabilities());
         return;
       }
+      if (url.pathname === "/v1/integrations/sqm-agent") {
+        if (!isSessionValid(session, Date.now(), apiOrigin) || !session?.device_id) {
+          json(res, 401, { error: "Reconnect SIMY CLI before managing the SQM agent skill." });
+          return;
+        }
+        if (req.method === "GET") {
+          json(res, 200, await sqmAgentIntegration.inspect());
+          return;
+        }
+        if (req.method === "POST") {
+          const body = await readJson(req);
+          if (body.confirmed !== true) {
+            json(res, 400, {
+              error: "Explicit confirmation is required before installing the SIMY plugin, agent skills, and PR hooks.",
+            });
+            return;
+          }
+          try {
+            const installed = await sqmAgentIntegration.install({
+              platforms: Array.isArray(body.platforms) ? body.platforms : undefined,
+            });
+            json(res, 200, installed);
+          } catch (error) {
+            json(res, 400, { error: error instanceof Error ? error.message : String(error) });
+          }
+          return;
+        }
+      }
       if (
         req.method === "POST" &&
         url.pathname === "/v1/local-tasks/attachments/stage"
@@ -1482,8 +1560,9 @@ export async function startAgent({
     if (shutdownPromise) return shutdownPromise;
     shutdownPromise = (async () => {
       if (heartbeatTimer) clearInterval(heartbeatTimer);
-      await durableLocalTaskWorker?.close?.();
       updateManager?.stop?.();
+      await sqmLocalReviewWorker?.close?.();
+      await durableLocalTaskWorker?.close?.();
       registry.close();
       localTaskRegistry.close();
     })();
@@ -1499,6 +1578,7 @@ export async function startAgent({
     directRegistry,
     localTaskRegistry,
     durableLocalTaskWorker,
+    sqmLocalReviewWorker,
     shutdown,
     webOrigin: apiOrigin,
     get loginUrl() {
@@ -1716,6 +1796,13 @@ function reportDurableLocalTaskError(error, quiet) {
   );
 }
 
+function reportSqmLocalReviewError(error, quiet) {
+  if (quiet) return;
+  console.error(
+    `SIMY SQM Local Review worker: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}
+
 function reportStartupConnectionError(error, quiet) {
   if (quiet) return;
   console.error(
@@ -1808,6 +1895,8 @@ async function capabilities() {
       durable_local_task_scenario_packs: true,
       durable_local_task_steps: true,
       bounded_local_task_subtasks: true,
+      sqm_agent_skill_management: true,
+      sqm_local_review: codex.compatible,
     },
     session_ttl_hours: 48,
   };

package/src/auto-update.js

@@ -19,6 +19,8 @@ const execFileAsync = promisify(execFile);
 
 export const CLI_PACKAGE_NAME = "@awak-app/simy-cli";
 export const AUTO_UPDATE_CHECK_INTERVAL_MS = 60 * 60 * 1_000;
+export const UPDATE_REEXEC_ENV = "SIMY_UPDATE_REEXEC_VERSION";
+export const INCOMPATIBLE_RETRY_ENV = "SIMY_UPDATE_INCOMPATIBLE_RETRY";
 const AUTO_UPDATE_INITIAL_DELAY_MS = 15_000;
 const AUTO_UPDATE_IDLE_RETRY_MS = 30_000;
 const UPDATE_LOCK_STALE_MS = 30 * 60 * 1_000;
@@ -166,10 +168,8 @@ export class CliAutoUpdater extends EventEmitter {
         return this.snapshot();
       }
 
-      const automatic = this.#snapshot.automatic && isPatchUpgrade(
-        this.#options.currentVersion,
-        targetVersion,
-      );
+      const change = classifyVersionChange(this.#options.currentVersion, targetVersion);
+      const automatic = this.#snapshot.automatic && ["patch", "minor"].includes(change);
       const action = updateAction(targetVersion);
       if (!automatic) {
         this.#clearIdleTimer();
@@ -256,7 +256,12 @@ export class CliAutoUpdater extends EventEmitter {
         return this.snapshot();
       }
 
-      await this.#options.installVersion(targetVersion);
+      await installAndVerifyVersion({
+        currentVersion: this.#options.currentVersion,
+        targetVersion,
+        installVersion: this.#options.installVersion,
+        readInstalledVersion: this.#options.readInstalledVersion,
+      });
       if (typeof this.#restartDaemon !== "function") {
         throw new Error("The daemon restart handoff is unavailable.");
       }
@@ -343,8 +348,11 @@ export async function createCliAutoUpdater({
     installVersion:
       dependencies.installVersion ||
       ((version) => installGlobalNpmVersion(version, { execFileCommand: dependencies.execFileCommand })),
+    readInstalledVersion:
+      dependencies.readInstalledVersion ||
+      (() => readGlobalNpmVersion({ execFileCommand: dependencies.execFileCommand })),
     acquireUpdateLock:
-      dependencies.acquireUpdateLock || (() => acquireUpdateLock(stateRoot, dependencies)),
+      dependencies.acquireUpdateLock || (() => acquireGlobalUpdateLock(stateRoot, dependencies)),
     logger: dependencies.logger || console.log,
     quiet: Boolean(interactive),
     now: dependencies.now || Date.now,
@@ -416,6 +424,214 @@ export async function installGlobalNpmVersion(
   );
 }
 
+export async function readGlobalNpmVersion({ execFileCommand = execFileAsync } = {}) {
+  const { stdout } = await execFileCommand("npm", ["root", "--global"], {
+    timeout: 10_000,
+    encoding: "utf8",
+  });
+  const packagePath = path.join(String(stdout || "").trim(), ...CLI_PACKAGE_NAME.split("/"), "package.json");
+  return (await readCliPackageInfo(path.dirname(packagePath))).version;
+}
+
+export async function installAndVerifyVersion({
+  currentVersion,
+  targetVersion,
+  installVersion = installGlobalNpmVersion,
+  readInstalledVersion = readGlobalNpmVersion,
+}) {
+  try {
+    await installVersion(targetVersion);
+    const installedVersion = await readInstalledVersion();
+    if (installedVersion !== targetVersion) {
+      throw new Error(`npm reported success, but installed SIMY ${installedVersion}; expected ${targetVersion}.`);
+    }
+    return installedVersion;
+  } catch (error) {
+    let recoveryError = null;
+    try {
+      await installVersion(currentVersion);
+      const restoredVersion = await readInstalledVersion();
+      if (restoredVersion !== currentVersion) {
+        throw new Error(`restored version is ${restoredVersion || "unknown"}`);
+      }
+    } catch (restoreError) {
+      recoveryError = restoreError;
+    }
+    const suffix = recoveryError
+      ? ` Automatic rollback could not be verified (${errorMessage(recoveryError)}).`
+      : ` SIMY ${currentVersion} was restored.`;
+    throw new Error(`${errorMessage(error)}${suffix}`);
+  }
+}
+
+export async function runCliUpdateGate({
+  argv = [],
+  packageInfo,
+  mode = "startup",
+  disabled = false,
+  allowMajor = false,
+  confirmMajor,
+  incompatibleRetry = false,
+  packageRoot = PACKAGE_ROOT,
+  entryPath,
+  env = process.env,
+  logger = console.log,
+  errorLogger = console.error,
+  dependencies = {},
+} = {}) {
+  const info = packageInfo || (await readCliPackageInfo(packageRoot));
+  const installMode = dependencies.installMode || (await detectInstallMode({
+    packageRoot,
+    execFileCommand: dependencies.execFileCommand,
+  }));
+  const result = {
+    currentVersion: info.version,
+    latestVersion: null,
+    installMode,
+    outcome: disabled ? "disabled" : "not_checked",
+    exitCode: null,
+    reexecuted: false,
+  };
+  const report = (outcome, latest = null) => {
+    result.outcome = outcome;
+    result.latestVersion = latest;
+    if (mode !== "startup") {
+      logger(`Current version: ${info.version}`);
+      logger(`Latest version: ${latest || "unknown"}`);
+      logger(`Install mode: ${installMode}`);
+      logger(`Result: ${outcome}`);
+    }
+    return result;
+  };
+
+  if (disabled) return report("disabled");
+  if (mode === "startup" && (
+    env.SIMY_DAEMON_CHILD === "1" || env[UPDATE_REEXEC_ENV] === info.version
+  )) {
+    return report("reexec_guard");
+  }
+
+  let release;
+  try {
+    const releaseInfo = await (dependencies.checkLatestVersion || checkLatestVersion)();
+    release = String(releaseInfo?.version || "").trim();
+    if (!parseStableVersion(release)) throw new Error("The npm registry returned an invalid stable CLI version.");
+  } catch (error) {
+    if (mode !== "startup") errorLogger(`Update check failed: ${errorMessage(error)}`);
+    result.error = errorMessage(error);
+    return report("check_failed");
+  }
+
+  if (compareStableVersions(release, info.version) <= 0) return report("up_to_date", release);
+  const change = classifyVersionChange(info.version, release);
+  const action = updateAction(release);
+  result.recoveryCommand = action.command;
+
+  if (installMode !== "global_npm") {
+    logger(`SIMY CLI ${release} is available. This ${installMode} installation is read-only; run: ${action.command}`);
+    return report("manual_install_required", release);
+  }
+  if (change === "major" && !allowMajor) {
+    if (mode === "update" && typeof confirmMajor === "function") {
+      const confirmed = await confirmMajor({ currentVersion: info.version, latestVersion: release });
+      if (!confirmed) {
+        logger(`SIMY CLI ${release} was not installed.`);
+        return report("major_update_declined", release);
+      }
+    } else {
+      logger(`SIMY CLI ${release} is a major update and was not installed. Run \`simy update\` to review and confirm it.`);
+      return report("major_confirmation_required", release);
+    }
+  }
+  if (mode === "check") return report("update_available", release);
+
+  if (change === "minor") logger(`Updating SIMY CLI ${info.version} → ${release}...`);
+  if (change === "major") logger(`Installing confirmed major SIMY CLI update ${info.version} → ${release}...`);
+  const stateRoot = dependencies.stateRoot || defaultStateRoot();
+  const acquire = dependencies.acquireUpdateLock || (() => acquireGlobalUpdateLock(stateRoot, dependencies));
+  let releaseLock = await acquire();
+  if (!releaseLock) {
+    const installed = await waitForInstalledVersion(release, {
+      readInstalledVersion: dependencies.readInstalledVersion || (() => readGlobalNpmVersion({ execFileCommand: dependencies.execFileCommand })),
+      timeoutMs: dependencies.lockWaitTimeoutMs,
+      pollMs: dependencies.lockPollMs,
+    });
+    if (!installed) {
+      logger(`Another SIMY process holds the update lock. Retry shortly or run: ${action.command}`);
+      return report("waiting_for_other_updater", release);
+    }
+  } else {
+    try {
+      await installAndVerifyVersion({
+        currentVersion: info.version,
+        targetVersion: release,
+        installVersion: dependencies.installVersion || ((version) => installGlobalNpmVersion(version, { execFileCommand: dependencies.execFileCommand })),
+        readInstalledVersion: dependencies.readInstalledVersion || (() => readGlobalNpmVersion({ execFileCommand: dependencies.execFileCommand })),
+      });
+    } catch (error) {
+      errorLogger(`SIMY update failed: ${errorMessage(error)}`);
+      errorLogger(`Recovery: npm install -g ${CLI_PACKAGE_NAME}@${info.version}`);
+      result.error = errorMessage(error);
+      return report("install_failed", release);
+    } finally {
+      await releaseLock();
+    }
+  }
+
+  if (mode === "update" && !entryPath) return report("updated", release);
+  if (!entryPath) throw new Error("The CLI entry path is required to restart after an update.");
+  const reexecute = dependencies.reexecute || reexecuteCliCommand;
+  const childEnv = {
+    ...env,
+    [UPDATE_REEXEC_ENV]: release,
+  };
+  if (incompatibleRetry) childEnv[INCOMPATIBLE_RETRY_ENV] = "1";
+  let exitCode;
+  try {
+    exitCode = await reexecute({ entryPath, argv, env: childEnv, spawnProcess: dependencies.spawnProcess });
+  } catch (error) {
+    let rollbackDetail = `Recovery: npm install -g ${CLI_PACKAGE_NAME}@${info.version}`;
+    try {
+      const installVersion = dependencies.installVersion || ((version) => installGlobalNpmVersion(version, { execFileCommand: dependencies.execFileCommand }));
+      const readInstalledVersion = dependencies.readInstalledVersion || (() => readGlobalNpmVersion({ execFileCommand: dependencies.execFileCommand }));
+      await installVersion(info.version);
+      const restored = await readInstalledVersion();
+      if (restored !== info.version) throw new Error(`installed version is ${restored || "unknown"}`);
+      rollbackDetail = `SIMY ${info.version} was restored. ${rollbackDetail}`;
+    } catch (rollbackError) {
+      rollbackDetail = `Automatic rollback failed (${errorMessage(rollbackError)}). ${rollbackDetail}`;
+    }
+    errorLogger(`Updated SIMY could not start: ${errorMessage(error)}`);
+    errorLogger(rollbackDetail);
+    result.error = errorMessage(error);
+    return report("restart_failed", release);
+  }
+  result.exitCode = exitCode;
+  result.reexecuted = true;
+  result.outcome = "updated_and_reexecuted";
+  result.latestVersion = release;
+  return result;
+}
+
+export async function reexecuteCliCommand({
+  entryPath,
+  argv,
+  env = process.env,
+  spawnProcess = spawn,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess(process.execPath, [entryPath, ...argv], {
+      env,
+      stdio: "inherit",
+    });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (signal) reject(new Error(`Updated SIMY exited from signal ${signal}.`));
+      else resolve(code ?? 1);
+    });
+  });
+}
+
 export function isRegistryIdle(registry) {
   const runs = registry?.list?.() || [];
   return runs.every((run) => {
@@ -450,6 +666,20 @@ export function isPatchUpgrade(currentVersion, targetVersion) {
   );
 }
 
+export function classifyVersionChange(currentVersion, targetVersion) {
+  const current = parseStableVersion(currentVersion);
+  const target = parseStableVersion(targetVersion);
+  if (!current || !target) throw new Error("A stable semantic version is required.");
+  if (compareStableVersions(currentVersion, targetVersion) >= 0) return "none";
+  if (current[0] !== target[0]) return "major";
+  if (current[1] !== target[1]) return "minor";
+  return "patch";
+}
+
+export function shouldRetryIncompatibleCli(error, env = process.env) {
+  return error?.code === "incompatible_cli" && env[INCOMPATIBLE_RETRY_ENV] !== "1";
+}
+
 export async function restartDaemonProcess({
   entryPath,
   argv,
@@ -518,7 +748,7 @@ export async function writeUpdateHandoffFromEnvironment({
 
 export function autoUpdateHelpText() {
   return [
-    "Recommended installation (enables daemon auto-update):",
+    "Recommended installation (enables verified CLI auto-update):",
     `  npm install -g ${CLI_PACKAGE_NAME}`,
     "  simy --daemon",
   ].join("\n");
@@ -543,7 +773,7 @@ function manualUpdateMessage({
   return `SIMY CLI ${targetVersion} is available. This version change requires manual confirmation.`;
 }
 
-function updateAction(version) {
+export function updateAction(version) {
   return {
     id: "install_global_cli",
     label: "Install and restart SIMY",
@@ -556,7 +786,7 @@ function parseStableVersion(value) {
   return match ? match.slice(1).map(Number) : null;
 }
 
-async function acquireUpdateLock(stateRoot, dependencies = {}) {
+export async function acquireGlobalUpdateLock(stateRoot = defaultStateRoot(), dependencies = {}) {
   const now = dependencies.now || Date.now;
   const lockDirectory = path.join(stateRoot, "updates");
   const lockPath = path.join(lockDirectory, "global-npm-update.lock");
@@ -585,6 +815,23 @@ async function acquireUpdateLock(stateRoot, dependencies = {}) {
   return null;
 }
 
+async function waitForInstalledVersion(targetVersion, {
+  readInstalledVersion,
+  timeoutMs = 30_000,
+  pollMs = 100,
+}) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      if ((await readInstalledVersion()) === targetVersion) return true;
+    } catch {
+      // npm may replace the package directory while the lock owner is installing.
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+  return false;
+}
+
 async function isStaleLock(lockPath, now) {
   try {
     const details = await stat(lockPath);

package/src/cli-contract.js

@@ -13,7 +13,7 @@ import {
 } from "./durable-local-task-steps-contract.js";
 import { buildExecutionCapabilityContract } from "./execution-capability-contract.js";
 
-export const CLI_VERSION = "0.4.0";
+export const CLI_VERSION = "0.5.1";
 export const CLI_API_CONTRACT_VERSION = 10;
 
 export function withCliContract(