@awak-app/simy-cli 0.4.0 → 0.5.0

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.0",
   "description": "Local SIMY executor for non-coding Local Tasks and Agentic Loop runs.",
   "type": "module",
   "bin": {

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.0";
 export const CLI_API_CONTRACT_VERSION = 10;
 
 export function withCliContract(

package/src/index.js

@@ -2,6 +2,7 @@
 
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
 
 import { startAgent } from "./agent.js";
 import {
@@ -9,6 +10,8 @@ import {
   createCliAutoUpdater,
   readCliPackageInfo,
   restartDaemonProcess,
+  runCliUpdateGate,
+  shouldRetryIncompatibleCli,
   writeUpdateHandoffFromEnvironment,
 } from "./auto-update.js";
 import { openAuthorizationUrl } from "./browser.js";
@@ -20,26 +23,75 @@ import { DEFAULT_WEB_ORIGIN, resolveWebOrigin } from "./web-origin.js";
 
 const argv = process.argv.slice(2);
 const args = new Set(argv);
+const dispatchArgv = argv.filter((value) => value !== "--no-auto-update");
+const entryPath = fileURLToPath(import.meta.url);
+const packageInfo = await readCliPackageInfo();
+const updatesDisabled = args.has("--no-auto-update") || process.env.SIMY_AUTO_UPDATE === "0";
 
-if (argv[0] === "sqm") {
-  const packageInfo = await readCliPackageInfo();
-  try {
-    const { runSqmCommand } = await import("./sqm/command.js");
-    process.exitCode = await runSqmCommand(argv.slice(1), { cliVersion: packageInfo.version });
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 2;
+if (dispatchArgv[0] === "update") {
+  const checkOnly = args.has("--check");
+  const result = await runCliUpdateGate({
+    argv,
+    packageInfo,
+    mode: checkOnly ? "check" : "update",
+    disabled: updatesDisabled,
+    allowMajor: args.has("--yes"),
+    confirmMajor: confirmMajorUpdate,
+  });
+  process.exitCode = ["check_failed", "install_failed"].includes(result.outcome) ? 1 : 0;
+} else {
+  const startupUpdate = await runCliUpdateGate({
+    argv,
+    packageInfo,
+    entryPath,
+    disabled: updatesDisabled,
+  });
+  if (startupUpdate.reexecuted) {
+    process.exitCode = startupUpdate.exitCode;
+  } else {
+    await runCommand();
   }
-  process.exit();
 }
 
-if (args.has("--help") || args.has("-h")) {
-  console.log(`Usage:
+async function runCommand() {
+  if (dispatchArgv[0] === "sqm") {
+    try {
+      const { runSqmCommand } = await import("./sqm/command.js");
+      process.exitCode = await runSqmCommand(dispatchArgv.slice(1), { cliVersion: packageInfo.version });
+    } catch (error) {
+      if (shouldRetryIncompatibleCli(error)) {
+        const retried = await runCliUpdateGate({
+          argv,
+          packageInfo,
+          entryPath,
+          mode: "incompatible",
+          disabled: updatesDisabled,
+          allowMajor: args.has("--yes"),
+          confirmMajor: confirmMajorUpdate,
+          incompatibleRetry: true,
+        });
+        if (retried.reexecuted) {
+          process.exitCode = retried.exitCode;
+          return;
+        }
+        const required = error.minimumVersion ? ` (requires ${error.minimumVersion}+)` : "";
+        console.error(`SQM requires a newer SIMY CLI${required}, but automatic recovery did not install one.`);
+      }
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 2;
+    }
+    return;
+  }
+
+  if (args.has("--help") || args.has("-h")) {
+    console.log(`Usage:
   simy            Start the local SIMY agent
   simy --daemon   Start it in the background
   simy --no-tui   Start the foreground HTTP agent without the interactive console
   simy sqm min-check  Run the fast deterministic SQM diff preflight
   simy sqm check      Run full scenarios, write proof.json, and sign the run
+  simy update --check Check the installed and latest stable CLI versions
+  simy update         Install an eligible stable CLI update
 
 Options:
   --daemon, --deamon  Run detached in the background
@@ -47,73 +99,92 @@ Options:
   --no-open           Do not open the browser when authorization is required
   --port <port>       Bind a specific localhost port
   --host <url>        Connect to a SIMY Web origin (default: ${DEFAULT_WEB_ORIGIN})
-  --no-auto-update    Disable the hourly CLI update check
+  --no-auto-update    Disable update checks and automatic installation
 
 ${autoUpdateHelpText()}
 `);
-  process.exit(0);
-}
+    return;
+  }
 
-const daemon = args.has("--daemon") || args.has("--deamon");
-const interactive = !daemon && !args.has("--no-tui") && process.stdin.isTTY && process.stdout.isTTY;
-const port = readPort(argv);
-const packageInfo = await readCliPackageInfo();
-let webOrigin;
-try {
-  webOrigin = resolveWebOrigin(readOption(argv, "--host"));
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(2);
+  await runLocalAgent();
 }
 
-if (daemon && process.env.SIMY_DAEMON_CHILD !== "1") {
-  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
-    detached: true,
-    stdio: "ignore",
-    env: { ...process.env, SIMY_DAEMON_CHILD: "1" },
-  });
-  child.unref();
-  console.log("SIMY local agent started in the background.");
-  process.exit(0);
-}
+async function runLocalAgent() {
+  const daemon = args.has("--daemon") || args.has("--deamon");
+  const interactive = !daemon && !args.has("--no-tui") && process.stdin.isTTY && process.stdout.isTTY;
+  const port = readPort(argv);
+  let webOrigin;
+  try {
+    webOrigin = resolveWebOrigin(readOption(argv, "--host"));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 2;
+    return;
+  }
 
-const updateManager = await createCliAutoUpdater({
-  daemon,
-  interactive,
-  requestedPort: port,
-  disabled: args.has("--no-auto-update") || process.env.SIMY_AUTO_UPDATE === "0",
-  dependencies: { packageInfo },
-});
-const agent = await startAgent({
-  requestedPort: port,
-  daemon,
-  webOrigin,
-  quiet: interactive,
-  updateManager,
-});
-const shutdownAgent = createAgentShutdown(agent);
-installAgentShutdownSignalHandlers({ shutdown: shutdownAgent });
-await writeUpdateHandoffFromEnvironment({ version: packageInfo.version, port: agent.port });
-updateManager.start({
-  registry: agent.registry,
-  restartDaemon: async (targetVersion) => {
-    await restartDaemonProcess({
-      entryPath: fileURLToPath(import.meta.url),
-      argv: process.argv.slice(2),
-      targetVersion,
+  if (daemon && process.env.SIMY_DAEMON_CHILD !== "1") {
+    const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, SIMY_DAEMON_CHILD: "1" },
     });
-    await shutdownAgent();
-  },
-});
-if (agent.loginUrl && !args.has("--no-open")) {
-  await openAuthorizationUrl(agent.loginUrl);
+    child.unref();
+    console.log("SIMY local agent started in the background.");
+    return;
+  }
+
+  const updateManager = await createCliAutoUpdater({
+    daemon,
+    interactive,
+    requestedPort: port,
+    disabled: args.has("--no-auto-update") || process.env.SIMY_AUTO_UPDATE === "0",
+    dependencies: { packageInfo },
+  });
+  const agent = await startAgent({
+    requestedPort: port,
+    daemon,
+    webOrigin,
+    quiet: interactive,
+    updateManager,
+  });
+  const shutdownAgent = createAgentShutdown(agent);
+  installAgentShutdownSignalHandlers({ shutdown: shutdownAgent });
+  await writeUpdateHandoffFromEnvironment({ version: packageInfo.version, port: agent.port });
+  updateManager.start({
+    registry: agent.registry,
+    restartDaemon: async (targetVersion) => {
+      await restartDaemonProcess({
+        entryPath: fileURLToPath(import.meta.url),
+        argv: process.argv.slice(2),
+        targetVersion,
+      });
+      await shutdownAgent();
+    },
+  });
+  if (agent.loginUrl && !args.has("--no-open")) {
+    await openAuthorizationUrl(agent.loginUrl);
+  }
+  if (interactive) {
+    const { runAgenticLoopConsole } = await import("./console/index.js");
+    try {
+      await runAgenticLoopConsole(agent);
+    } finally {
+      await shutdownAgent();
+    }
+  }
 }
-if (interactive) {
-  const { runAgenticLoopConsole } = await import("./console/index.js");
+
+async function confirmMajorUpdate({ currentVersion, latestVersion }) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.log(`Major update ${currentVersion} → ${latestVersion} requires confirmation. Re-run with \`simy update --yes\`.`);
+    return false;
+  }
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    await runAgenticLoopConsole(agent);
+    const answer = await prompt.question(`Install major SIMY CLI update ${currentVersion} → ${latestVersion}? [y/N] `);
+    return /^(y|yes)$/i.test(answer.trim());
   } finally {
-    await shutdownAgent();
+    prompt.close();
   }
 }
 

package/src/orchestrator/completion-contract.js

@@ -79,8 +79,14 @@ export function completionEvidenceChecks(charter, attempt) {
   if (contract.version !== COMPLETION_CONTRACT_VERSION) return [];
 
   const uncertainty = normalizeUncertaintyVerification(attempt?.uncertainty_verification);
-  const criterionEvidence = normalizeCriterionEvidence(attempt?.criterion_evidence);
   const rows = acceptanceCriterionRows(charter);
+  const criterionEvidence = normalizeCriterionEvidence(attempt?.criterion_evidence);
+  const expectedCriterionIds = new Set(rows.map((row) => row.id));
+  const unexpectedCriterionIds = uniqueStrings(
+    criterionEvidence
+      .map((item) => item.criterion_id)
+      .filter((criterionId) => !expectedCriterionIds.has(criterionId)),
+  );
   const checks = [
     check(
       "top_uncertainty_recorded",
@@ -110,6 +116,14 @@ export function completionEvidenceChecks(charter, attempt) {
         ? "The executor marked the highest uncertainty resolved with observed evidence."
         : uncertainty.fallback || "The highest uncertainty remains unresolved.",
     ),
+    check(
+      "criterion_evidence_scope",
+      "Criterion evidence matches the charter acceptance criteria",
+      unexpectedCriterionIds.length === 0,
+      unexpectedCriterionIds.length === 0
+        ? "Every criterion evidence row references a chartered acceptance criterion."
+        : `Unexpected criterion evidence: ${unexpectedCriterionIds.join(", ")}.`,
+    ),
   ];
 
   for (const row of rows) {

package/src/sqm/bundle-store.js

@@ -9,6 +9,18 @@ import { validateKnowledgeBundle } from "./validation.js";
 const DEFAULT_TTL_MS = 5 * 60 * 1000;
 export const SQM_BUNDLE_FETCH_TIMEOUT_MS = 15_000;
 
+export class SqmIncompatibleCliError extends Error {
+  constructor(message, { currentVersion, minimumVersion, modules = [] } = {}) {
+    super(message);
+    this.name = "SqmIncompatibleCliError";
+    this.code = "incompatible_cli";
+    this.currentVersion = currentVersion || null;
+    this.minimumVersion = minimumVersion || null;
+    this.modules = modules;
+    this.fallbackAllowed = false;
+  }
+}
+
 export async function loadKnowledgeBundle({
   repository,
   cliVersion,
@@ -68,6 +80,7 @@ export async function loadKnowledgeBundle({
       });
       return result(bundle, [], "cloud");
     } catch (error) {
+      if (error?.code === "incompatible_cli") throw error;
       if (error?.fallbackAllowed !== false && cached && Date.parse(cached.bundle.expires_at) > now) return result(cached.bundle, [`SQM Cloud unavailable; using last verified bundle: ${message(error)}`], "stale_cache");
       return result(null, [`SQM knowledge could not be used; shadow checks were skipped: ${message(error)}`], "unavailable");
     }
@@ -169,6 +182,18 @@ async function fetchBundle({ endpoint, repository, cliVersion, token, organizati
   }
   if (!response.ok) {
     const body = await response.text().catch(() => "");
+    const parsed = parseErrorBody(body);
+    if (response.status === 409 && parsed?.error?.code === "incompatible_cli") {
+      const modules = Array.isArray(parsed.error.modules) ? parsed.error.modules : [];
+      const minimumVersion = modules
+        .map((module) => String(module?.min_cli_version || ""))
+        .filter(Boolean)
+        .sort(compareSemverDescending)[0] || null;
+      throw new SqmIncompatibleCliError(
+        parsed.error.message || "The selected knowledge bundle requires a newer SIMY CLI.",
+        { currentVersion: parsed.error.cli_version || cliVersion, minimumVersion, modules },
+      );
+    }
     const error = new Error(`SQM Cloud returned HTTP ${response.status}${body ? `: ${body.slice(0, 300)}` : ""}.`);
     error.fallbackAllowed = response.status >= 500 && response.status <= 599;
     throw error;
@@ -186,6 +211,23 @@ async function fetchBundle({ endpoint, repository, cliVersion, token, organizati
   }
 }
 
+function parseErrorBody(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+
+function compareSemverDescending(left, right) {
+  const a = left.split(".").map(Number);
+  const b = right.split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    if ((a[index] || 0) !== (b[index] || 0)) return (b[index] || 0) - (a[index] || 0);
+  }
+  return 0;
+}
+
 async function readVerifiedCache(location, options, identity) {
   try {
     const [bundleRaw, metadataRaw] = await Promise.all([readFile(location.bundle, "utf8"), readFile(location.metadata, "utf8")]);