@awak-app/simy-cli 0.3.3 → 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.
@@ -203,6 +234,61 @@ limit. SIMY Web can edit that suggestion and call
 `provider_token_budget`. The CLI persists the higher limit and resumes the same
 run. SIMY token consumption remains a separate platform billing record.
 
+## SQM local checks
+
+SQM deliberately has two identity-bound stages:
+
+1. `simy sqm min-check` quickly inspects committed changes, the working tree,
+   untracked files, and deletions. It runs only deterministic low-cost rules,
+   reports preliminary findings, and writes the applicable state, transition,
+   stress, and scenario plan. A passing min-check is not a complete validation.
+2. `simy sqm check` verifies that repository, base, HEAD, working-tree digest,
+   and signed bundle still match the min-check. It then evaluates applicable
+   state transitions, invariants, stress/strength expectations, and scenarios,
+   writes `proof.json`, and signs that proof with the local device identity.
+
+Normal runs do not require a separate sync command: the CLI
+uses a verified local cache and revalidates it with TTL and ETag semantics.
+The Agentic Loop runs min-check after each code modification and the full check
+before PR readiness. Findings and the redacted signed-proof summary are recorded
+in its audit; source text is never uploaded.
+
+Configure the bundle service with `SIMY_SQM_BUNDLE_URL`. Authentication uses
+the current SIMY session in the coding loop, or `SIMY_SQM_TOKEN`/
+`SIMY_ACCESS_TOKEN` for the diagnostic command. On the first authenticated
+HTTPS request, the CLI receives the bundle verification key from the SIMY
+gateway, verifies the signed bundle, and pins that key to the endpoint,
+account, organization, and repository cache identity for offline use. Explicit
+trust anchors can instead be configured as a JSON key-ID map in
+`SIMY_SQM_PUBLIC_KEYS_JSON`, or as one `SIMY_SQM_KEY_ID` plus
+`SIMY_SQM_PUBLIC_KEY`. Public keys may be PEM, base64 SPKI, or a base64 raw
+32-byte Ed25519 key. Optional settings are:
+
+- `SIMY_SQM_CACHE_DIR`: verified bundle cache location.
+- `SIMY_SQM_CACHE_TTL_MS`: revalidation TTL, defaulting to five minutes.
+- `SIMY_SQM_ACCOUNT_ID` and `SIMY_SQM_ORGANIZATION_ID`: tenant identity for
+  diagnostic checks. Coding-loop checks receive tenant identity from the
+  authenticated session. Cache entries are isolated by endpoint, account,
+  organization, and repository, and the organization is verified against the
+  signed bundle. `SIMY_SQM_ORGANIZATION_ID` is required for standalone
+  diagnostic checks; without a tenant identity SQM fails closed in shadow mode.
+
+Use either phase with `--offline` to prohibit network access and `--refresh` to force
+ETag revalidation, `--base <branch>` to select a base branch, and `--json` for
+machine-readable results. Full check additionally accepts `--min-result`,
+`--proof`, `--signed-evidence`, and `--no-upload`. The min result and full proof
+share one pinned signed bundle and one exact repository identity, so a code
+change cannot silently reuse an old preflight. If Cloud is unavailable, the CLI clearly warns and
+uses the last unexpired signature-verified bundle only after a network failure
+or Cloud 5xx response. Authentication, authorization, compatibility,
+signature, schema, tenant, and expiry failures never execute stale knowledge.
+With no verified cache it skips SQM
+in shadow mode. Bundles contain only the fixed declarative checker vocabulary;
+the CLI never executes shell, JavaScript, Python, WASM, or another remotely
+supplied implementation. A module's matcher array has explicit **AND semantics**:
+every matcher must match before any check in that module runs; it is not an OR
+list.
+
 ## Interactive console
 
 Running `simy` in a terminal opens the Agentic Loop chat. It discovers the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "Local SIMY executor for non-coding Local Tasks and Agentic Loop runs.",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
     "start": "node ./src/index.js",
     "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: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",
@@ -35,7 +36,8 @@
     "test:e2e:console:real-provider": "node ./scripts/real-provider-console-e2e.js",
     "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",
+    "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: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

@@ -557,6 +557,16 @@ export async function startAgent({
           device_id: typeof body.device_id === "string" ? body.device_id : null,
           api_origin: apiOrigin,
           api_base_url: apiBaseUrl,
+          account_id: typeof body.account_id === "string"
+            ? body.account_id
+            : typeof body.auth_user_id === "string"
+            ? body.auth_user_id
+            : null,
+          organization_id: typeof body.organization_id === "string"
+            ? body.organization_id
+            : typeof body.org_id === "string"
+            ? body.org_id
+            : null,
           expires_at: typeof body.expires_at === "string" ? body.expires_at : expiresAtFromNow(),
         };
         await writeSession(apiOrigin, session, sessionRoot);
@@ -679,6 +689,13 @@ export async function startAgent({
           json(res, 400, { error: "instruction is required" });
           return;
         }
+        const authorizationInstruction = String(
+          body.authorization_instruction || instruction,
+        ).trim();
+        if (!authorizationInstruction) {
+          json(res, 400, { error: "authorization_instruction is required" });
+          return;
+        }
         if (body.backend !== "codex" && body.backend !== "claude") {
           json(res, 400, { error: "backend must be codex or claude" });
           return;
@@ -686,7 +703,7 @@ export async function startAgent({
         const idempotencyKey = String(
           req.headers["idempotency-key"] || body.client_request_id || "",
         ).trim();
-        const guardrail = classifyExecutionRequirement(instruction);
+        const guardrail = classifyExecutionRequirement(authorizationInstruction);
         if (
           guardrail.decision !== "direct_executor" ||
           body.guardrail?.policy_version !== EXECUTION_GUARDRAIL_POLICY_VERSION ||

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.3.3";
+export const CLI_VERSION = "0.5.0";
 export const CLI_API_CONTRACT_VERSION = 10;
 
 export function withCliContract(

package/src/execution-guardrail.js

@@ -1,4 +1,4 @@
-export const EXECUTION_GUARDRAIL_POLICY_VERSION = "2026-07-26.1";
+export const EXECUTION_GUARDRAIL_POLICY_VERSION = "2026-07-29.1";
 
 const OBSERVE_PATTERN =
   /\b(monitor|watch|observe|track|status|progress|keep an eye on)\b|監視|見守|進捗|状況を?(?:見|確認)|监控|監控|观察|觀察|进度|進度|状态|狀態/i;
@@ -98,7 +98,7 @@ export function classifyExecutionRequirement(sourceMessage) {
       reason_code: "observe_existing_provider_session",
     });
   }
-  if (changeRequested && knowledgeWork && !codingTarget) {
+  if (changeRequested && (knowledgeWork || hasObject) && !codingTarget) {
     return guardrail("direct_executor", {
       change_requested: true,
       repository_required: false,