@awak-app/simy-cli 0.1.3 → 0.1.5

package/README.md

@@ -1,12 +1,23 @@
 # SIMY CLI
 
-Local execution agent for SIMY coding loops.
+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
 ```
@@ -18,16 +29,73 @@ available for automation, but the command-line flag takes precedence.
 
 The CLI starts a loopback HTTP agent on a random available port, keeps a
 48-hour, origin-scoped local session, and opens a native coding chat. The first
-chat message creates the remote audit ledger and starts the local coding-loop
+chat message creates the remote audit ledger and starts the local Agentic Loop
 state machine; SIMY Web mirrors the lifecycle but is not required as the task
 entry point. The CLI also accepts backend-issued launch challenges for Web-led
 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
+start. The currently validated compatibility floors are Codex `0.144.0` and
+Claude Code `2.1.200`. A missing, older, or unversioned executable fails the
+preflight and returns the installed version, required version, and a recovery
+command to SIMY Web. Update Codex with
+`npm install -g @openai/codex@latest`; update Claude Code with `claude update`.
+
+## Your Desktop executor
+
+SIMY CLI is the `desktop` execution target, shown to users as **Your Desktop**.
+It can run either Codex or Claude Code as a child process inside the verified
+local Git checkout. Device heartbeats advertise both desktop provider
+capabilities and their installed/required versions. Preflight and every standard
+provider dispatch fail closed unless the selected binary is compatible; there
+is no fallback to an unverified executable name.
+
+Legacy local requests without `execution_target` continue to resolve to
+`desktop`. A request marked for the hosted `simy` target is rejected by the
+local CLI boundary so hosted and desktop execution cannot be confused. The
+target and bound device id are preserved in the run Charter, redacted Web
+ledger snapshot, and restored run.
+
+## Blocked recovery contract
+
+Every `waiting_human`, `blocked`, or `failed` lifecycle event includes a
+versioned `detail.recovery` object. It provides a stable reason code, a
+user-safe explanation, a primary action, executable action metadata, and
+bounded technical details. Preflight failures use the same contract for
+executor updates, repository selection, and CLI reconnection. Web clients must
+validate the action type before rendering or executing it; raw local error text
+is not copied into the recovery contract.
+
 ## Interactive console
 
-Running `simy` in a terminal opens the Coding Loop chat. It discovers the
+Running `simy` in a terminal opens the Agentic Loop chat. It discovers the
 current GitHub repository and branch, selects an available executor, and keeps
 the composer active so a natural-language request can start immediately. Each
 run appears in a selectable list with its lifecycle state, process ID, and a
@@ -74,7 +142,7 @@ The local PR lifecycle is intentionally separate from deployment:
    and human approval all pass.
 
 The Web UI can refresh review and CI evidence with
-`POST /v1/coding-loop/:run_id/recheck`. Passing the local implementation gate
+`POST /v1/agentic-loop/:run_id/recheck`. Passing the local implementation gate
 does not by itself make a PR merge-ready.
 
 Start `simy` from the selected repository or a workspace containing it. Set
@@ -86,7 +154,7 @@ from an empty CLI chat, types repository, branch, executor, attachment, and task
 input through a pseudoterminal, creates the Web ledger, spawns real child
 processes, and exercises HIL plus lifecycle controls. It regenerates the
 screenshots, terminal frames, raw transcript, and SHA-256 manifest under
-`docs/pr-evidence/cli-coding-loop-console/`.
+`docs/pr-evidence/cli-agentic-loop-console/`.
 
 ## Publishing
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.1.3",
-  "description": "Local SIMY coding-loop agent for Codex and Claude Code.",
+  "version": "0.1.5",
+  "description": "Local SIMY Agentic Loop executor for Codex and Claude Code.",
   "type": "module",
   "bin": {
     "simy": "src/index.js"
@@ -14,11 +14,23 @@
     "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",
+    "test:e2e:task-routing": "node ./scripts/task-routing-e2e.js",
+    "test:e2e:executor-version-preflight": "node ./scripts/executor-version-preflight-e2e.js",
+    "test:e2e:blocked-recovery": "node ./scripts/blocked-recovery-e2e.js",
+    "test:e2e:process-localization": "node ./scripts/process-localization-e2e.js",
+    "test:e2e:hypothesis-retries": "node ./scripts/hypothesis-retries-e2e.js",
+    "test:e2e:budgets": "node ./scripts/budget-enforcement-e2e.js",
+    "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": "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/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.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/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: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"
   },
   "engines": {