[lihautan]

Fixes simular-ai/box-portal#152
Fixes simular-ai/box-portal#179
Fixes simular-ai/box-portal#185
Fixes simular-ai/box-portal#191
Fixes simular-ai/box-portal#195

Five installer CLI bugs from the layer 3 onboarding runs. They were filed in box-portal, but the code is here in cli/. The wording follows box-portal's install.md update (simular-ai/box-portal#333): restart before sign-in, "Allow" (the consent page's button), and the same OpenClaw and Codex hand-offs.

What changes

• Claude Code: restart before signing in (#152). Next now has two steps in a fixed order. First: "Restart Claude Code now: box is not visible in a session that was already running. Quit it (/exit) and start claude again…" (in the desktop Code tab, start a new session instead). Then: /mcp → plugin:box:box → Authenticate → Allow.
• Codex in its sandbox: progress and fail fast (#179).
  • Without a TTY, connect prints <App>: setting up box before any slow step, so an agent's tool call shows output right away.
  • Clients that write their own config file (Codex, the JSON clients, Hermes) check before changing anything that the file can be written. The check creates and deletes a file in the folder, because sandboxes may allow a write in access(2) and then block the real write.
  • EROFS now counts as a permission error.
  • Inside an agent sandbox (CODEX_SANDBOX / CODEX_SANDBOX_NETWORK_DISABLED, or EROFS), connect prints one line: "This looks like an AI agent's sandbox … Run this command in a normal terminal instead: npx -y @simular-ai/box connect --client codex --yes". It doesn't print the Codex app steps there.
  • doctor prints its first line before the network checks.
  • Network steps already had timeouts: the probe allows 10 s and child CLIs 60 to 180 s.
• Cursor: CLI sign-in and the current editor path (#185). Next has two lines, because ~/.cursor/mcp.json serves both the editor and the CLI:
  • Editor: Customize → MCPs → Authenticate (older versions: Settings → Tools & MCP → Login).
  • CLI: cursor-agent mcp login box, then start a new cursor-agent session.
• doctor: plain DNS lookup (#191). doctor now runs dns.lookup on the MCP host (5 s timeout), in parallel with the HTTPS probe.
  • If the lookup fails but the HTTPS check works, doctor prints: "this computer can't look up mcp.box.simular.ai (ENOTFOUND), though the check above reached box through a proxy (HTTPS_PROXY=http://127.0.0.1:3128). Your apps may not be able to reach box directly…", followed by a fix line.
  • The proxy is printed as scheme://host:port only, never with its user or password.
  • A failed lookup makes ok false and appears in the --json output as dns.
• OpenClaw: running session holds the lock (#195). When openclaw mcp set fails with a state or config lock error, connect prints one message: "OpenClaw is running and holds its config lock… Type /exit to quit OpenClaw. In this terminal, run npx -y @simular-ai/box connect --client openclaw --yes, then openclaw mcp login box, and click Allow in the browser. Then start openclaw again and ask: Use box to take a screenshot of the box." The generic "file may belong to another user" advice no longer follows it. With --auth key, the command keeps --auth key and leaves out the browser sign-in.
• Wording: every sign-in step says "click Allow" instead of "Approve". The README's client table is updated to match.

Not verified

• OpenClaw's real lock text. It isn't documented, and the layer 3 run didn't capture it. The match covers a lock on "state" or "config", or a lock "held", "owned" or "in use", and nothing else that says "lock" (a test covers package-lock.json). A timeout gets its own message. If a real run prints something else, the old openclaw mcp set failed: … message appears instead, so nothing gets worse.
• Real sandbox and proxy runs. I didn't run the CLI inside a real codex exec sandbox, or behind a real proxy with broken DNS. Fake CLIs and injected probes cover both.
• npx download time. When npx itself hangs while fetching the package with no network (the likely cause of the silent minute in #179), nothing in the CLI has started yet. install.md (simular-ai/box-portal#333) tells Codex to run the installer with sandbox escalation for that reason.

Tests

cd cli && npx eslint . --max-warnings 0 && node --test: 77 tests, all passing (66 before). New tests:

• Claude Code: the restart line comes before /mcp, and no "Approve" remains.
• Cursor: both lines.
• OpenClaw: the lock message (unit and real CLI, with no generic permission advice); --auth key kept; package-lock.json not taken as a lock.
• Codex in a sandbox: read-only ~/.codex with CODEX_SANDBOX set fails in under 10 s, with the progress line right after the intro and the terminal command; the file is left unchanged.
• doctor: DNS fails while the probe works, and the proxy password is never shown; lookupHost for ENOTFOUND and a timeout; real doctor against a .invalid host.
• assertWritable and connectCommand, including the quoted BOX_MCP_URL and Windows $env:.

Review

simular-code-review (with secure-coding) ran on the first commit in a separate agent that didn't write the change. Blocking: none. Secure-coding: nothing found (the proxy credentials are removed before printing, and a test covers it). All eight non-blocking findings are fixed in the second commit:

• the write check uses a temp file instead of access(2);
• a narrower lock match, and a timeout gets its own message;
• --auth key is kept in the OpenClaw hand-off;
• BOX_MCP_URL is quoted, with $env: on Windows;
• doctor names a set proxy whenever DNS fails;
• lookupHost doesn't throw on a malformed URL;
• Hermes also pre-checks .env;
• the Claude Code step also covers an app that isn't running yet.

🤖 Generated with Claude Code