@awak-app/simy-cli 0.1.4 → 0.2.0

package/README.md

@@ -2,11 +2,22 @@
 
 Local execution agent for SIMY Agentic Loop runs.
 
+For normal use, install SIMY globally and keep its background agent running:
+
 ```bash
-npx @awak-app/simy-cli
 npm install -g @awak-app/simy-cli
-simy
 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
+the interactive chat after installation, use `simy`.
+
+For a one-time evaluation or source development, these modes remain supported:
+
+```bash
+npx @awak-app/simy-cli
+npm start
 simy --no-tui
 simy --host https://simy.example.com
 ```
@@ -25,6 +36,29 @@ runs. It builds the requirement charter, runs Codex or Claude Code, audits
 structured completion evidence, and re-instructs the executor within the
 configured attempt budget.
 
+## 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.
+
+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:
+
+```bash
+npm install -g @awak-app/simy-cli@<version> && simy --daemon
+```
+
+Use `--no-auto-update` or `SIMY_AUTO_UPDATE=0` to disable background checks.
+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.
+
 ## Executor compatibility
 
 SIMY checks the selected executor with `--version` before an Agentic Loop can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Local SIMY Agentic Loop executor for Codex and Claude Code.",
   "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:auto-update": "node ./scripts/auto-update-e2e.js",
     "test:e2e:audit-gate": "node ./scripts/audit-gate-e2e.js",
     "test:e2e:retry-circuit": "node ./scripts/retry-circuit-e2e.js",
     "test:e2e:follow-up-charter": "node ./scripts/follow-up-charter-e2e.js",
@@ -26,7 +27,8 @@
     "test:e2e:desktop-executor": "node ./scripts/desktop-executor-e2e.js",
     "test:e2e:console:real-provider": "node ./scripts/real-provider-console-e2e.js",
     "test:e2e:console:fullstack": "node ./scripts/fullstack-cli-smoke.js",
-    "check": "node --check ./src/desktop-executor.js && node --check ./scripts/desktop-executor-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": "npm run check:auto-update && node --check ./src/desktop-executor.js && node --check ./scripts/desktop-executor-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: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/run-registry.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/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/fake-coding-backend.js && node --check ./scripts/e2e-terminal-evidence.js && node --check ./scripts/audit-gate-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/console-e2e-fixture.js && node --check ./scripts/console-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

@@ -64,6 +64,11 @@ import {
   scanGitRepositories,
   writeRepositoryInventory,
 } from "./repository-inventory.js";
+import {
+  CLI_API_CONTRACT_VERSION,
+  CLI_VERSION,
+  withCliContract,
+} from "./cli-contract.js";
 
 const DEVICE_HEARTBEAT_INTERVAL_MS = 20_000;
 
@@ -72,6 +77,7 @@ export async function startAgent({
   daemon = false,
   webOrigin = null,
   sessionRoot,
+  updateManager = null,
   dependencies = {},
   quiet = false,
 } = {}) {
@@ -98,7 +104,11 @@ export async function startAgent({
         ]
       : [],
   );
-  const availableCapabilities = await readCapabilities(dependencies);
+  const installMode = updateManager?.snapshot?.()?.install_mode ?? null;
+  const availableCapabilities = withCliContract(
+    await readCapabilities(dependencies),
+    installMode,
+  );
   const heartbeatDevice = dependencies.heartbeatDevice || heartbeatLocalDevice;
   const runOptions = dependencies.runOptions || {};
   const repositoryScanRoot = resolve(
@@ -219,6 +229,7 @@ export async function startAgent({
   };
 
   const selectRepository = async (run, repository) => {
+    if (run) ensureAcceptingNewWork(updateManager);
     const selected = repository?.local_path
       ? repositoryInventory.find(
           (item) =>
@@ -231,10 +242,14 @@ export async function startAgent({
       throw new Error(`This run requires ${run.request.repository}; select that local repository.`);
     }
     if (!run) return selected;
-    return continueLocalCodingRunAfterRepositoryApproval(
-      run,
-      { repository: selected.repository, localPath: selected.local_path },
-      runOptions,
+    return withUpdateWork(
+      updateManager,
+      () =>
+        continueLocalCodingRunAfterRepositoryApproval(
+          run,
+          { repository: selected.repository, localPath: selected.local_path },
+          runOptions,
+        ),
     );
   };
 
@@ -252,18 +267,34 @@ export async function startAgent({
 
       const url = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
       const agenticLoopPath = canonicalAgenticLoopPath(url.pathname);
+      if (
+        req.method === "POST" &&
+        agenticLoopPath.startsWith("/v1/agentic-loop") &&
+        agenticLoopPath !== "/v1/agentic-loop/preflight"
+      ) {
+        const releaseUpdateWork = acquireUpdateWork(updateManager);
+        if (!releaseUpdateWork) {
+          json(res, 503, updateInProgressResponse(updateManager));
+          return;
+        }
+        res.once("finish", releaseUpdateWork);
+        res.once("close", releaseUpdateWork);
+      }
       if (req.method === "GET" && url.pathname === "/v1/health") {
         json(res, 200, {
           ok: true,
+          cli_version: CLI_VERSION,
+          api_contract_version: CLI_API_CONTRACT_VERSION,
           daemon,
           web_origin: apiOrigin,
           session_valid: isSessionValid(session, Date.now(), apiOrigin),
           session_expires_at: session?.expires_at ?? null,
+          cli_update: updateManager?.snapshot?.() ?? null,
         });
         return;
       }
       if (req.method === "GET" && url.pathname === "/v1/capabilities") {
-        json(res, 200, await readCapabilities(dependencies));
+        json(res, 200, availableCapabilities);
         return;
       }
       if (req.method === "POST" && agenticLoopPath === "/v1/agentic-loop/preflight") {
@@ -336,11 +367,20 @@ export async function startAgent({
         startHeartbeatTimer();
         loginUrl = null;
         registry.emit("change", registry.list());
-        json(res, 200, { ok: true, expires_at: session.expires_at });
+        json(res, 200, {
+          ok: true,
+          expires_at: session.expires_at,
+          cli_version: CLI_VERSION,
+          api_contract_version: CLI_API_CONTRACT_VERSION,
+        });
         void synchronizeAuthorizedSession();
         return;
       }
       if (req.method === "POST" && agenticLoopPath === "/v1/agentic-loop/start") {
+        if (!acceptsNewWork(updateManager)) {
+          json(res, 503, updateInProgressResponse(updateManager));
+          return;
+        }
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
           json(res, 401, { error: "simy session expired; run simy again" });
           return;
@@ -493,6 +533,10 @@ export async function startAgent({
         } else if (body.action === "pause") {
           pauseLocalCodingRun(run);
         } else if (body.action === "resume") {
+          if (!acceptsNewWork(updateManager)) {
+            json(res, 503, updateInProgressResponse(updateManager));
+            return;
+          }
           resumeLocalCodingRun(run);
         } else {
           json(res, 400, { error: "action must be pause, resume, or stop" });
@@ -567,6 +611,10 @@ export async function startAgent({
         }
 
         if (req.method === "POST") {
+          if (!acceptsNewWork(updateManager)) {
+            json(res, 503, updateInProgressResponse(updateManager));
+            return;
+          }
           const body = await readJson(req);
           const requestId = localRepositoryHilRequestId(run);
           if (body.request_id !== requestId) {
@@ -623,6 +671,10 @@ export async function startAgent({
 
       const recheckMatch = agenticLoopPath.match(/^\/v1\/agentic-loop\/([^/]+)\/recheck$/);
       if (req.method === "POST" && recheckMatch) {
+        if (!acceptsNewWork(updateManager)) {
+          json(res, 503, updateInProgressResponse(updateManager));
+          return;
+        }
         const run = registry.get(decodeURIComponent(recheckMatch[1]));
         if (!run) {
           json(res, 404, { error: "run not found" });
@@ -662,6 +714,9 @@ export async function startAgent({
     loginUrl = new URL("/local-cli/connect", apiOrigin);
     loginUrl.searchParams.set("port", String(port));
     loginUrl.searchParams.set("nonce", authNonce);
+    loginUrl.searchParams.set("cli_version", CLI_VERSION);
+    loginUrl.searchParams.set("api_contract_version", String(CLI_API_CONTRACT_VERSION));
+    if (installMode) loginUrl.searchParams.set("install_mode", installMode);
     if (!quiet) {
       console.log(`Sign in to SIMY: ${loginUrl.toString()}`);
       console.log(`Session file: ${sessionPath(apiOrigin, sessionRoot)}`);
@@ -681,6 +736,7 @@ export async function startAgent({
 
   server.on("close", () => {
     if (heartbeatTimer) clearInterval(heartbeatTimer);
+    updateManager?.stop?.();
     registry.close();
   });
   return {
@@ -694,11 +750,12 @@ export async function startAgent({
     workspace,
     repositoryScanRoot,
     capabilities: availableCapabilities,
+    updates: updateManager,
     controls: {
       repositoryInventory: () => [...repositoryInventory],
       scanRepositories,
       selectRepository,
-      create: async (input) => {
+      create: (input) => withUpdateWork(updateManager, async () => {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
           throw new Error("Sign in to SIMY before starting a coding task.");
         }
@@ -746,15 +803,69 @@ export async function startAgent({
         registry.create(run);
         void startLocalCodingRun(run, runOptions);
         return run;
-      },
-      continue: (run, guidance) => continueLocalCodingRun(run, guidance, runOptions),
-      applyDecision: (run, decision) => applyLocalHumanDecision(run, decision, runOptions),
+      }),
+      continue: (run, guidance) =>
+        withUpdateWork(updateManager, () => continueLocalCodingRun(run, guidance, runOptions)),
+      applyDecision: (run, decision) =>
+        withUpdateWork(updateManager, () => applyLocalHumanDecision(run, decision, runOptions)),
       queueGuidance: queueLocalCodingGuidance,
       pause: pauseLocalCodingRun,
-      resume: resumeLocalCodingRun,
+      resume: (run) => withUpdateWorkSync(updateManager, () => resumeLocalCodingRun(run)),
       stop: stopLocalCodingRun,
       recheck: (run) =>
-        recheckLocalCodingRun(run, { collectEvidence: runOptions.collectEvidence }),
+        withUpdateWork(updateManager, () =>
+          recheckLocalCodingRun(run, { collectEvidence: runOptions.collectEvidence }),
+        ),
+    },
+  };
+}
+
+function acceptsNewWork(updateManager) {
+  return updateManager?.acceptsNewWork?.() !== false;
+}
+
+function acquireUpdateWork(updateManager) {
+  if (!acceptsNewWork(updateManager)) return null;
+  return updateManager?.beginWork?.() ?? (() => {});
+}
+
+function ensureAcceptingNewWork(updateManager) {
+  if (acceptsNewWork(updateManager)) return;
+  throw new Error(
+    updateManager?.snapshot?.().message ||
+      "SIMY is installing an update. Wait for the daemon to restart, then try again.",
+  );
+}
+
+async function withUpdateWork(updateManager, action) {
+  const release = acquireUpdateWork(updateManager);
+  if (!release) ensureAcceptingNewWork(updateManager);
+  try {
+    return await action();
+  } finally {
+    release?.();
+  }
+}
+
+function withUpdateWorkSync(updateManager, action) {
+  const release = acquireUpdateWork(updateManager);
+  if (!release) ensureAcceptingNewWork(updateManager);
+  try {
+    return action();
+  } finally {
+    release?.();
+  }
+}
+
+function updateInProgressResponse(updateManager) {
+  return {
+    error:
+      updateManager?.snapshot?.().message ||
+      "SIMY is installing an update. Wait for the daemon to restart, then try again.",
+    code: "cli_update_in_progress",
+    recovery: {
+      title: "Wait for SIMY to restart",
+      description: "The CLI will reconnect automatically after the update finishes.",
     },
   };
 }
@@ -818,6 +929,8 @@ export async function heartbeatLocalDevice({
       ),
       body: JSON.stringify({
         port,
+        cli_version: CLI_VERSION,
+        api_contract_version: CLI_API_CONTRACT_VERSION,
         capabilities,
         repo_inventory: repoInventory,
       }),

package/src/auto-update.js

@@ -0,0 +1,631 @@
+import { execFile, spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { EventEmitter } from "node:events";
+import {
+  mkdir,
+  open,
+  readFile,
+  realpath,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export const CLI_PACKAGE_NAME = "@awak-app/simy-cli";
+export const AUTO_UPDATE_CHECK_INTERVAL_MS = 60 * 60 * 1_000;
+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;
+const RESTART_HANDOFF_TIMEOUT_MS = 30_000;
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const NON_IDLE_STATES = new Set([
+  "queued",
+  "risk_classifying",
+  "chartering",
+  "dispatching",
+  "coding",
+  "collecting_evidence",
+  "auditing",
+  "independent_auditing",
+  "checking_pr",
+  "re_instructing",
+  "waiting_human",
+  "blocked",
+]);
+const NON_IDLE_CONTROL_STATES = new Set([
+  "queued",
+  "running",
+  "paused",
+  "waiting_human",
+  "stopping",
+]);
+
+export class CliAutoUpdater extends EventEmitter {
+  #snapshot;
+  #options;
+  #registry = null;
+  #restartDaemon = null;
+  #checkTimer = null;
+  #initialTimer = null;
+  #idleTimer = null;
+  #checking = null;
+  #applying = null;
+  #stopped = false;
+  #registryListener = null;
+  #activeWork = 0;
+
+  constructor(options) {
+    super();
+    this.#options = options;
+    this.#snapshot = {
+      state: options.disabled ? "disabled" : "idle",
+      current_version: options.currentVersion,
+      target_version: null,
+      install_mode: options.installMode,
+      automatic: Boolean(
+        !options.disabled &&
+          options.daemon &&
+          options.installMode === "global_npm" &&
+          options.requestedPort === 0
+      ),
+      checked_at: null,
+      message: options.disabled
+        ? "Automatic update checks are disabled."
+        : "SIMY will check for CLI updates in the background.",
+      action: null,
+      error: null,
+    };
+  }
+
+  snapshot() {
+    return structuredClone(this.#snapshot);
+  }
+
+  acceptsNewWork() {
+    return !["updating", "restarting"].includes(this.#snapshot.state);
+  }
+
+  beginWork() {
+    if (!this.acceptsNewWork()) return null;
+    this.#activeWork += 1;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.#activeWork = Math.max(0, this.#activeWork - 1);
+      if (this.#activeWork === 0 && this.#snapshot.state === "waiting_for_idle") {
+        void this.maybeApply();
+      }
+    };
+  }
+
+  start({ registry, restartDaemon } = {}) {
+    if (this.#snapshot.state === "disabled" || this.#checkTimer || this.#stopped) return this;
+    this.#registry = registry;
+    this.#restartDaemon = restartDaemon;
+    this.#registryListener = () => {
+      if (this.#snapshot.state === "waiting_for_idle") void this.maybeApply();
+    };
+    this.#registry?.on("change", this.#registryListener);
+    this.#initialTimer = setTimeout(() => void this.checkNow(), this.#options.initialDelayMs);
+    this.#initialTimer.unref?.();
+    this.#checkTimer = setInterval(() => void this.checkNow(), this.#options.checkIntervalMs);
+    this.#checkTimer.unref?.();
+    return this;
+  }
+
+  stop() {
+    this.#stopped = true;
+    if (this.#initialTimer) clearTimeout(this.#initialTimer);
+    if (this.#checkTimer) clearInterval(this.#checkTimer);
+    if (this.#idleTimer) clearInterval(this.#idleTimer);
+    if (this.#registryListener) this.#registry?.off("change", this.#registryListener);
+    this.#initialTimer = null;
+    this.#checkTimer = null;
+    this.#idleTimer = null;
+  }
+
+  async checkNow() {
+    if (this.#stopped || this.#snapshot.state === "disabled") return this.snapshot();
+    if (this.#checking) return this.#checking;
+    if (["updating", "restarting"].includes(this.#snapshot.state)) return this.snapshot();
+
+    this.#checking = this.#performCheck().finally(() => {
+      this.#checking = null;
+    });
+    return this.#checking;
+  }
+
+  async #performCheck() {
+    this.#setState("checking", {
+      message: "Checking for a newer SIMY CLI version...",
+      error: null,
+    });
+    try {
+      const release = await this.#options.checkLatestVersion();
+      const targetVersion = String(release?.version || "").trim();
+      if (!parseStableVersion(targetVersion)) {
+        throw new Error("The npm registry returned an invalid stable CLI version.");
+      }
+      const checkedAt = new Date(this.#options.now()).toISOString();
+      if (compareStableVersions(targetVersion, this.#options.currentVersion) <= 0) {
+        this.#clearIdleTimer();
+        this.#setState("up_to_date", {
+          target_version: null,
+          checked_at: checkedAt,
+          message: `SIMY CLI ${this.#options.currentVersion} is up to date.`,
+          action: null,
+          error: null,
+        });
+        return this.snapshot();
+      }
+
+      const automatic = this.#snapshot.automatic && isPatchUpgrade(
+        this.#options.currentVersion,
+        targetVersion,
+      );
+      const action = updateAction(targetVersion);
+      if (!automatic) {
+        this.#clearIdleTimer();
+        this.#setState("update_available", {
+          target_version: targetVersion,
+          checked_at: checkedAt,
+          message: manualUpdateMessage({
+            currentVersion: this.#options.currentVersion,
+            targetVersion,
+            installMode: this.#options.installMode,
+            daemon: this.#options.daemon,
+            requestedPort: this.#options.requestedPort,
+          }),
+          action,
+          error: null,
+        });
+        this.#announce();
+        return this.snapshot();
+      }
+
+      this.#setState("waiting_for_idle", {
+        target_version: targetVersion,
+        checked_at: checkedAt,
+        message: `SIMY CLI ${targetVersion} is ready and will install when no task is active.`,
+        action,
+        error: null,
+      });
+      this.#startIdleTimer();
+      this.#announce();
+      return this.maybeApply();
+    } catch (error) {
+      this.#clearIdleTimer();
+      this.#setState("check_failed", {
+        checked_at: new Date(this.#options.now()).toISOString(),
+        message: "SIMY could not check for updates. It will try again later.",
+        error: errorMessage(error),
+      });
+      this.#announce();
+      return this.snapshot();
+    }
+  }
+
+  async maybeApply() {
+    if (this.#stopped || this.#snapshot.state !== "waiting_for_idle") {
+      return this.snapshot();
+    }
+    if (this.#applying) return this.#applying;
+    if (!this.#isIdle()) return this.snapshot();
+
+    this.#applying = this.#performUpdate().finally(() => {
+      this.#applying = null;
+    });
+    return this.#applying;
+  }
+
+  async #performUpdate() {
+    const targetVersion = this.#snapshot.target_version;
+    this.#setState("updating", {
+      message: `Updating SIMY CLI ${this.#options.currentVersion} to ${targetVersion}...`,
+      error: null,
+    });
+    this.#announce();
+
+    if (!this.#isIdle()) {
+      this.#setState("waiting_for_idle", {
+        message: `SIMY CLI ${targetVersion} is ready and will install when no task is active.`,
+      });
+      return this.snapshot();
+    }
+
+    let releaseLock = null;
+    try {
+      releaseLock = await this.#options.acquireUpdateLock();
+      if (!releaseLock) {
+        this.#setState("waiting_for_idle", {
+          message: "Another SIMY process is updating the CLI. This process will check again shortly.",
+        });
+        return this.snapshot();
+      }
+      if (!this.#isIdle()) {
+        this.#setState("waiting_for_idle", {
+          message: `SIMY CLI ${targetVersion} is ready and will install when no task is active.`,
+        });
+        return this.snapshot();
+      }
+
+      await this.#options.installVersion(targetVersion);
+      if (typeof this.#restartDaemon !== "function") {
+        throw new Error("The daemon restart handoff is unavailable.");
+      }
+      this.#setState("restarting", {
+        message: `SIMY CLI ${targetVersion} is installed. Verifying the restarted daemon...`,
+      });
+      this.#announce();
+      await this.#restartDaemon?.(targetVersion);
+      this.#clearIdleTimer();
+      this.#setState("updated", {
+        message: `SIMY CLI ${targetVersion} is running.`,
+        action: null,
+        error: null,
+      });
+      return this.snapshot();
+    } catch (error) {
+      this.#clearIdleTimer();
+      this.#setState("failed", {
+        message: `Automatic update failed. SIMY ${this.#options.currentVersion} is still running.`,
+        action: updateAction(targetVersion),
+        error: errorMessage(error),
+      });
+      this.#announce();
+      return this.snapshot();
+    } finally {
+      await releaseLock?.();
+    }
+  }
+
+  #startIdleTimer() {
+    if (this.#idleTimer) return;
+    this.#idleTimer = setInterval(() => void this.maybeApply(), this.#options.idleRetryMs);
+    this.#idleTimer.unref?.();
+  }
+
+  #isIdle() {
+    return this.#activeWork === 0 && isRegistryIdle(this.#registry);
+  }
+
+  #clearIdleTimer() {
+    if (this.#idleTimer) clearInterval(this.#idleTimer);
+    this.#idleTimer = null;
+  }
+
+  #setState(state, values = {}) {
+    this.#snapshot = { ...this.#snapshot, ...values, state };
+    this.emit("change", this.snapshot());
+  }
+
+  #announce() {
+    if (this.#options.quiet) return;
+    const suffix =
+      ["update_available", "failed"].includes(this.#snapshot.state) &&
+      this.#snapshot.action?.command
+      ? ` Run manually: ${this.#snapshot.action.command}`
+      : "";
+    const detail = this.#snapshot.error ? ` (${this.#snapshot.error})` : "";
+    this.#options.logger(`${this.#snapshot.message}${suffix}${detail}`);
+  }
+}
+
+export async function createCliAutoUpdater({
+  daemon,
+  interactive,
+  requestedPort = 0,
+  disabled = false,
+  packageRoot = PACKAGE_ROOT,
+  dependencies = {},
+} = {}) {
+  const packageInfo = dependencies.packageInfo || (await readCliPackageInfo(packageRoot));
+  const installMode = dependencies.installMode || (await detectInstallMode({
+    packageRoot,
+    execFileCommand: dependencies.execFileCommand,
+  }));
+  const stateRoot = dependencies.stateRoot || defaultStateRoot();
+  return new CliAutoUpdater({
+    daemon: Boolean(daemon),
+    interactive: Boolean(interactive),
+    requestedPort,
+    disabled,
+    currentVersion: packageInfo.version,
+    installMode,
+    checkLatestVersion: dependencies.checkLatestVersion || checkLatestVersion,
+    installVersion:
+      dependencies.installVersion ||
+      ((version) => installGlobalNpmVersion(version, { execFileCommand: dependencies.execFileCommand })),
+    acquireUpdateLock:
+      dependencies.acquireUpdateLock || (() => acquireUpdateLock(stateRoot, dependencies)),
+    logger: dependencies.logger || console.log,
+    quiet: Boolean(interactive),
+    now: dependencies.now || Date.now,
+    initialDelayMs: dependencies.initialDelayMs ?? AUTO_UPDATE_INITIAL_DELAY_MS,
+    checkIntervalMs: dependencies.checkIntervalMs ?? AUTO_UPDATE_CHECK_INTERVAL_MS,
+    idleRetryMs: dependencies.idleRetryMs ?? AUTO_UPDATE_IDLE_RETRY_MS,
+  });
+}
+
+export async function readCliPackageInfo(packageRoot = PACKAGE_ROOT) {
+  const payload = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
+  const version = String(payload.version || "").trim();
+  if (!parseStableVersion(version)) throw new Error("SIMY CLI package.json has an invalid version.");
+  return { name: String(payload.name || ""), version };
+}
+
+export async function detectInstallMode({
+  packageRoot = PACKAGE_ROOT,
+  execFileCommand = execFileAsync,
+} = {}) {
+  const resolvedRoot = await realpathOrResolve(packageRoot);
+  if (resolvedRoot.split(path.sep).includes("_npx")) return "npx";
+
+  try {
+    const { stdout } = await execFileCommand("npm", ["root", "--global"], {
+      timeout: 10_000,
+      encoding: "utf8",
+    });
+    const globalRoot = await realpathOrResolve(String(stdout || "").trim());
+    if (isPathInside(globalRoot, resolvedRoot)) return "global_npm";
+  } catch {
+    // The actionable fallback is the same for source checkouts and unknown package managers.
+  }
+
+  return resolvedRoot.split(path.sep).includes("node_modules") ? "package" : "source";
+}
+
+export async function checkLatestVersion({ fetchImpl = fetch } = {}) {
+  const response = await fetchImpl(
+    "https://registry.npmjs.org/@awak-app%2fsimy-cli/latest",
+    {
+      headers: { Accept: "application/vnd.npm.install-v1+json" },
+      signal: AbortSignal.timeout(10_000),
+    },
+  );
+  if (!response.ok) throw new Error(`npm registry returned HTTP ${response.status}`);
+  const payload = await response.json();
+  return {
+    version: payload?.version,
+    integrity: payload?.dist?.integrity || null,
+  };
+}
+
+export async function installGlobalNpmVersion(
+  version,
+  { execFileCommand = execFileAsync } = {},
+) {
+  if (!parseStableVersion(version)) throw new Error("Refusing to install an invalid CLI version.");
+  await execFileCommand(
+    "npm",
+    [
+      "install",
+      "--global",
+      `${CLI_PACKAGE_NAME}@${version}`,
+      "--no-audit",
+      "--no-fund",
+    ],
+    { timeout: 10 * 60_000, encoding: "utf8" },
+  );
+}
+
+export function isRegistryIdle(registry) {
+  const runs = registry?.list?.() || [];
+  return runs.every((run) => {
+    if (run?.operation || run?.child || run?.pendingLedgerUpdate || run?.ledgerUpdateRunning) {
+      return false;
+    }
+    if (NON_IDLE_STATES.has(run?.status)) return false;
+    if (NON_IDLE_CONTROL_STATES.has(run?.controlState)) return false;
+    return true;
+  });
+}
+
+export function compareStableVersions(left, right) {
+  const leftParts = parseStableVersion(left);
+  const rightParts = parseStableVersion(right);
+  if (!leftParts || !rightParts) throw new Error("A stable semantic version is required.");
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] - rightParts[index];
+  }
+  return 0;
+}
+
+export function isPatchUpgrade(currentVersion, targetVersion) {
+  const current = parseStableVersion(currentVersion);
+  const target = parseStableVersion(targetVersion);
+  return Boolean(
+    current &&
+      target &&
+      current[0] === target[0] &&
+      current[1] === target[1] &&
+      target[2] > current[2]
+  );
+}
+
+export async function restartDaemonProcess({
+  entryPath,
+  argv,
+  targetVersion,
+  stateRoot = defaultStateRoot(),
+  spawnProcess = spawn,
+  timeoutMs = RESTART_HANDOFF_TIMEOUT_MS,
+  env = process.env,
+} = {}) {
+  const handoffDirectory = path.join(stateRoot, "updates", "handoff");
+  await mkdir(handoffDirectory, { recursive: true, mode: 0o700 });
+  const nonce = randomBytes(24).toString("hex");
+  const handoffPath = path.join(handoffDirectory, `${process.pid}-${nonce}.json`);
+  const child = spawnProcess(process.execPath, [entryPath, ...argv], {
+    detached: true,
+    stdio: "ignore",
+    env: {
+      ...env,
+      SIMY_DAEMON_CHILD: "1",
+      SIMY_UPDATE_HANDOFF_FILE: handoffPath,
+      SIMY_UPDATE_HANDOFF_NONCE: nonce,
+    },
+  });
+  child.unref?.();
+  const spawnFailure = new Promise((_, reject) => {
+    child.once?.("error", reject);
+  });
+
+  try {
+    const handoff = await Promise.race([
+      waitForHandoff(handoffPath, nonce, timeoutMs),
+      spawnFailure,
+    ]);
+    if (handoff.version !== targetVersion) {
+      throw new Error(
+        `Restarted SIMY reported version ${handoff.version || "unknown"}, expected ${targetVersion}.`,
+      );
+    }
+    return handoff;
+  } finally {
+    await rm(handoffPath, { force: true });
+  }
+}
+
+export async function writeUpdateHandoffFromEnvironment({
+  version,
+  port,
+  env = process.env,
+  stateRoot = defaultStateRoot(),
+} = {}) {
+  const handoffPath = String(env.SIMY_UPDATE_HANDOFF_FILE || "").trim();
+  const nonce = String(env.SIMY_UPDATE_HANDOFF_NONCE || "").trim();
+  if (!handoffPath || !nonce) return false;
+  const handoffDirectory = path.resolve(stateRoot, "updates", "handoff");
+  if (!isPathInside(handoffDirectory, path.resolve(handoffPath))) {
+    throw new Error("Refusing to write an update handoff outside the SIMY state directory.");
+  }
+  await mkdir(handoffDirectory, { recursive: true, mode: 0o700 });
+  await writeFile(
+    handoffPath,
+    `${JSON.stringify({ nonce, version, port, pid: process.pid, ready_at: new Date().toISOString() })}\n`,
+    { encoding: "utf8", mode: 0o600 },
+  );
+  return true;
+}
+
+export function autoUpdateHelpText() {
+  return [
+    "Recommended installation (enables daemon auto-update):",
+    `  npm install -g ${CLI_PACKAGE_NAME}`,
+    "  simy --daemon",
+  ].join("\n");
+}
+
+function manualUpdateMessage({
+  currentVersion,
+  targetVersion,
+  installMode,
+  daemon,
+  requestedPort,
+}) {
+  if (installMode !== "global_npm") {
+    return `SIMY CLI ${targetVersion} is available. Install the global version to enable automatic updates.`;
+  }
+  if (!daemon) {
+    return `SIMY CLI ${targetVersion} is available. Update it after leaving this foreground session.`;
+  }
+  if (requestedPort !== 0) {
+    return `SIMY CLI ${targetVersion} is available. A daemon using a fixed port requires a manual restart.`;
+  }
+  return `SIMY CLI ${targetVersion} is available. This version change requires manual confirmation.`;
+}
+
+function updateAction(version) {
+  return {
+    id: "install_global_cli",
+    label: "Install and restart SIMY",
+    command: `npm install -g ${CLI_PACKAGE_NAME}@${version} && simy --daemon`,
+  };
+}
+
+function parseStableVersion(value) {
+  const match = String(value || "").match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/);
+  return match ? match.slice(1).map(Number) : null;
+}
+
+async function acquireUpdateLock(stateRoot, dependencies = {}) {
+  const now = dependencies.now || Date.now;
+  const lockDirectory = path.join(stateRoot, "updates");
+  const lockPath = path.join(lockDirectory, "global-npm-update.lock");
+  await mkdir(lockDirectory, { recursive: true, mode: 0o700 });
+
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const handle = await open(lockPath, "wx", 0o600);
+      const token = randomBytes(16).toString("hex");
+      await handle.writeFile(`${JSON.stringify({ token, pid: process.pid, created_at: now() })}\n`);
+      await handle.close();
+      return async () => {
+        try {
+          const payload = JSON.parse(await readFile(lockPath, "utf8"));
+          if (payload.token === token) await rm(lockPath, { force: true });
+        } catch (error) {
+          if (error?.code !== "ENOENT") throw error;
+        }
+      };
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      if (!(await isStaleLock(lockPath, now))) return null;
+      await rm(lockPath, { force: true });
+    }
+  }
+  return null;
+}
+
+async function isStaleLock(lockPath, now) {
+  try {
+    const details = await stat(lockPath);
+    return now() - details.mtimeMs > UPDATE_LOCK_STALE_MS;
+  } catch (error) {
+    if (error?.code === "ENOENT") return true;
+    throw error;
+  }
+}
+
+async function waitForHandoff(handoffPath, nonce, timeoutMs) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      const payload = JSON.parse(await readFile(handoffPath, "utf8"));
+      if (payload.nonce === nonce) return payload;
+    } catch (error) {
+      if (error?.code !== "ENOENT" && !(error instanceof SyntaxError)) throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error("The updated SIMY daemon did not become healthy in time.");
+}
+
+async function realpathOrResolve(value) {
+  try {
+    return await realpath(value);
+  } catch {
+    return path.resolve(value);
+  }
+}
+
+function isPathInside(parent, child) {
+  const relative = path.relative(parent, child);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function defaultStateRoot() {
+  return process.env.SIMY_HOME?.trim() || path.join(homedir(), ".simy");
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/cli-contract.js

@@ -0,0 +1,11 @@
+export const CLI_VERSION = "0.2.0";
+export const CLI_API_CONTRACT_VERSION = 2;
+
+export function withCliContract(capabilities = {}, installMode = null) {
+  return {
+    ...capabilities,
+    cli_version: CLI_VERSION,
+    api_contract_version: CLI_API_CONTRACT_VERSION,
+    ...(installMode ? { install_mode: installMode } : {}),
+  };
+}

package/src/console/app.js

@@ -24,6 +24,7 @@ export function AgenticLoopConsole({ agent, onQuit = () => {} }) {
   const { stdout } = useStdout();
   const [terminal, setTerminal] = useState(() => terminalSize(stdout));
   const [runs, setRuns] = useState(() => agent.registry.list());
+  const [cliUpdate, setCliUpdate] = useState(() => agent.updates?.snapshot?.() ?? null);
   const [selectedId, setSelectedId] = useState(() => runs[0]?.id ?? NEW_TASK);
   const [inputMode, setInputMode] = useState(() => runs.length === 0);
   const [input, setInput] = useState("");
@@ -51,6 +52,13 @@ export function AgenticLoopConsole({ agent, onQuit = () => {} }) {
     return () => agent.registry.off("change", update);
   }, [agent.registry]);
 
+  useEffect(() => {
+    if (!agent.updates?.on) return undefined;
+    const update = (nextState) => setCliUpdate(nextState);
+    agent.updates.on("change", update);
+    return () => agent.updates.off("change", update);
+  }, [agent.updates]);
+
   useEffect(() => {
     const resize = () => setTerminal(terminalSize(stdout));
     stdout.on("resize", resize);
@@ -68,7 +76,8 @@ export function AgenticLoopConsole({ agent, onQuit = () => {} }) {
     1 +
     (waitingForHuman ? 1 : 0) +
     (!selectedRun ? 1 : 0) +
-    (notice || busy ? 1 : 0);
+    (notice || busy ? 1 : 0) +
+    (visibleUpdateNotice(cliUpdate) ? 1 : 0);
   const mainHeight = Math.max(8, terminal.rows - 5 - actionRows);
   const detailInnerWidth = Math.max(20, terminal.columns - 4);
   const detailRows = useMemo(
@@ -529,6 +538,7 @@ export function AgenticLoopConsole({ agent, onQuit = () => {} }) {
         draft,
         repositoryMissing: isRepositoryMissing(selectedRun),
         modalOpen: Boolean(scanPrompt || repositoryPicker),
+        cliUpdate,
       }),
     ],
   });
@@ -544,6 +554,12 @@ function Header({ agent, runCount }) {
     children: [
       jsx(Text, { bold: true, color: "cyan", children: "SIMY" }),
       jsx(Text, { bold: true, children: " Coding Chat" }),
+      agent.updates?.snapshot?.().current_version
+        ? jsx(Text, {
+            dimColor: true,
+            children: `  v${agent.updates.snapshot().current_version}`,
+          })
+        : null,
       jsx(Text, { dimColor: true, children: `  localhost:${agent.port}` }),
       jsx(Spacer, {}),
       jsx(Text, { color: runCount > 0 ? "green" : "yellow", children: `${runCount} runs` }),
@@ -780,6 +796,7 @@ function ActionBar({
   draft,
   repositoryMissing,
   modalOpen,
+  cliUpdate,
 }) {
   const waiting = run && (run.controlState === "waiting_human" || run.status === "waiting_human");
   return jsxs(Box, {
@@ -825,10 +842,29 @@ function ActionBar({
         : busy
           ? jsx(Text, { color: "cyan", children: "Working..." })
           : null,
+      visibleUpdateNotice(cliUpdate)
+        ? jsx(Text, {
+            color: cliUpdate.state === "failed" ? "red" : "yellow",
+            children: visibleUpdateNotice(cliUpdate),
+          })
+        : null,
     ],
   });
 }
 
+function visibleUpdateNotice(update) {
+  if (
+    !update ||
+    !["update_available", "waiting_for_idle", "updating", "restarting", "failed"].includes(
+      update.state,
+    )
+  ) {
+    return "";
+  }
+  const command = update.action?.command ? ` Run: ${update.action.command}` : "";
+  return `${update.message || "SIMY CLI update status changed."}${command}`;
+}
+
 function initialDraft(agent) {
   const backends = agent.capabilities?.backends ?? {};
   return {

package/src/index.js

@@ -4,6 +4,13 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 import { startAgent } from "./agent.js";
+import {
+  autoUpdateHelpText,
+  createCliAutoUpdater,
+  readCliPackageInfo,
+  restartDaemonProcess,
+  writeUpdateHandoffFromEnvironment,
+} from "./auto-update.js";
 import { openAuthorizationUrl } from "./browser.js";
 import { DEFAULT_WEB_ORIGIN, resolveWebOrigin } from "./web-origin.js";
 
@@ -22,6 +29,9 @@ 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
+
+${autoUpdateHelpText()}
 `);
   process.exit(0);
 }
@@ -29,6 +39,7 @@ Options:
 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"));
@@ -48,7 +59,32 @@ if (daemon && process.env.SIMY_DAEMON_CHILD !== "1") {
   process.exit(0);
 }
 
-const agent = await startAgent({ requestedPort: port, daemon, webOrigin, quiet: interactive });
+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,
+});
+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 closeServer(agent.server);
+  },
+});
 if (agent.loginUrl && !args.has("--no-open")) {
   await openAuthorizationUrl(agent.loginUrl);
 }