cinna-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{cinna_cli-0.3.0 → cinna_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cinna-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Local development CLI for Cinna Core agents
 Project-URL: Homepage, https://github.com/opencinna/cinna-cli
 Project-URL: Repository, https://github.com/opencinna/cinna-cli
@@ -63,7 +63,11 @@ Your Editor / Claude Code
 ## Prerequisites
 
 - **Python 3.10+**
-- **[Mutagen](https://mutagen.io)** (version pinned by the platform — `cinna setup` checks and prompts to install)
+- **[Mutagen](https://mutagen.io)** (version pinned by the platform — `cinna setup` checks and prompts to install; set `CINNA_MUTAGEN_BIN=/abs/path/mutagen` to use a specific binary instead of the one on PATH)
+
+### Cinna Desktop
+
+[Cinna Desktop](https://github.com/opencinna/cinna-desktop) installs its **own pinned copy** of cinna-cli (with `uv` and Mutagen alongside, inside its data folder) and drives it as a child process to create and keep alive an account workspace under `<AgentsHome>/Cloud/<host>/` right after you sign in — no `cinna login`, no token to paste. That private copy is not on your `PATH` unless you opt in from the desktop's settings; installing cinna-cli yourself (`uv tool install cinna-cli`) for terminal use is fine and both operate on the same workspace. The version the platform pins is reported by `cinna account status` / `cinna doctor`.
 
 ## Getting Started
 
@@ -135,7 +139,7 @@ cinna login app.example.com --dir my-cinna             # always into a named sub
 #   ✓ Account workspace ready.
 ```
 
-Use it when `cinna account status` or `cinna doctor` reports the account token has expired. Because the per-agent tokens minted from an account (`cinna agent sync`) can only be re-minted while the account token is valid, the flow is: `cinna login` (refresh the account), then `cinna doctor` (re-mint the dependent sub-agent tokens). If the platform doesn't expose the device-login endpoints yet, `cinna login` says so and points you at the `cinna account setup` paste fallback.
+Use it when `cinna account status` or `cinna doctor` reports the account token has expired. Because the per-agent tokens minted from an account (`cinna agent sync`) can only be re-minted while the account token is valid, the flow is: `cinna login` (refresh the account), then `cinna doctor` (re-mint the dependent sub-agent tokens). If the platform doesn't expose the device-login endpoints yet, `cinna login` says so and points you at the `cinna account set-token` paste fallback.
 
 ### `cinna account setup <token_or_url>`
 
@@ -145,7 +149,7 @@ Initialize an **account workspace** — a multi-agent root from which you can di
 curl -sL https://your-platform.com/api/cli-setup/account/TOKEN | python3 -
 ```
 
-Accepts the same input forms as `cinna setup` (full curl command, URL, or bare token — bare tokens need `CINNA_PLATFORM_URL`). Creates `my-cinna/` (override with `--dir`) containing:
+Accepts the same input forms as `cinna setup` (full curl command, URL, or bare token — bare tokens need `CINNA_PLATFORM_URL`). Creates a folder named after the platform domain (override with `--dir`: an absolute path is used as is with parents created, a relative one lands under the current directory; an existing account workspace there is refused before the token is spent) containing:
 
 ```
 my-cinna/
@@ -159,6 +163,17 @@ Setup also downloads the **context package** into `context/` — curated platfor
 
 The account token is only used for the account-level endpoints (listing agents, minting per-agent tokens, the context package). Per-agent work always runs on each child workspace's own token. Revoking the account session in Settings disconnects every agent synced from it.
 
+`account setup`, `account set-token` and `account status` take `--no-input` (never prompt: defaults, or fail with code `needs_input`; also `CINNA_NO_INPUT=1`, accepted before or after the subcommand) and `--json` (one JSON object per line on stdout — progress `{"step","total","status","message"}` lines, then a final `{"result":"ok"|"error",…}`; implies `--no-input`). Exit codes are stable for every command: `0` ok, `10` setup token invalid/expired/used, `11` token for another account, `12` platform unreachable or 5xx, `1` anything else (the JSON `code` says what), `2` usage.
+
+### `cinna account set-token <token_or_url>`
+
+Refresh the **account** token in place from a fresh account setup token — the account counterpart of `cinna set-token`, and the paste alternative to `cinna login`. Run inside the account workspace; it re-exchanges under the stored machine name and rewrites only `account_token` (plus a refreshed platform/frontend URL) in `.cinna/account.json`. The active user workspace, machine name, `context/` and every synced child under `agents/` are untouched; run `cinna doctor` afterwards to re-mint expired child tokens. A token for a different account is refused (exit `11`) and nothing is written. Bare tokens reuse the stored platform URL.
+
+```bash
+cd my-cinna/
+cinna account set-token 'curl -sL https://your-platform.com/api/cli-setup/account/TOKEN | python3 -'
+```
+
 ### `cinna account agents`
 
 List the agents your account can access (run from inside the account workspace). For each agent: display name + ID, building rights (`✓ can build`, `view-only`, or `foreign install` — installed bundles are publisher-managed and can't be synced), whether a remote environment is active, and whether a local workspace already exists under `agents/`.
@@ -167,7 +182,9 @@ List the agents your account can access (run from inside the account workspace).
 
 One-shot summary of the account workspace: platform/frontend URLs, machine name, synced-agent count, and an account-token probe (`valid token` / `expired token` / `no connection`) — the account-level counterpart of `cinna status`.
 
-Also reports the workspace's **context package version** against the platform's current one — the orchestrator guides ship in that tree, so a workspace set up before a guide existed silently lacks it. When it is behind, the command says so and points at `cinna account refresh-context`; `cinna improve list` prints the same nudge, since its playbook lives there.
+Also reports the workspace's **context package version** against the platform's current one — the orchestrator guides ship in that tree, so a workspace set up before a guide existed silently lacks it. When it is behind, the command says so and points at `cinna account refresh-context`; `cinna improve list` prints the same nudge, since its playbook lives there. Likewise it compares the installed **cinna-cli version** with the one the platform pins (its `/.well-known/cinna-desktop` discovery document) and suggests `uv tool install cinna-cli==<pin>` when behind; no pin means "unknown", not an error.
+
+With `--json` it prints a single line: `{"result":"ok","workspace",…,"token":"valid|expired|unreachable","synced_agents":N,"agents":[…],"context_package":{"local","remote","state"},"cli":{"installed","required","state"}}`.
 
 ### `cinna account refresh-context`
 

{cinna_cli-0.3.0 → cinna_cli-0.4.0}/README.md

@@ -26,7 +26,11 @@ Your Editor / Claude Code
 ## Prerequisites
 
 - **Python 3.10+**
-- **[Mutagen](https://mutagen.io)** (version pinned by the platform — `cinna setup` checks and prompts to install)
+- **[Mutagen](https://mutagen.io)** (version pinned by the platform — `cinna setup` checks and prompts to install; set `CINNA_MUTAGEN_BIN=/abs/path/mutagen` to use a specific binary instead of the one on PATH)
+
+### Cinna Desktop
+
+[Cinna Desktop](https://github.com/opencinna/cinna-desktop) installs its **own pinned copy** of cinna-cli (with `uv` and Mutagen alongside, inside its data folder) and drives it as a child process to create and keep alive an account workspace under `<AgentsHome>/Cloud/<host>/` right after you sign in — no `cinna login`, no token to paste. That private copy is not on your `PATH` unless you opt in from the desktop's settings; installing cinna-cli yourself (`uv tool install cinna-cli`) for terminal use is fine and both operate on the same workspace. The version the platform pins is reported by `cinna account status` / `cinna doctor`.
 
 ## Getting Started
 
@@ -98,7 +102,7 @@ cinna login app.example.com --dir my-cinna             # always into a named sub
 #   ✓ Account workspace ready.
 ```
 
-Use it when `cinna account status` or `cinna doctor` reports the account token has expired. Because the per-agent tokens minted from an account (`cinna agent sync`) can only be re-minted while the account token is valid, the flow is: `cinna login` (refresh the account), then `cinna doctor` (re-mint the dependent sub-agent tokens). If the platform doesn't expose the device-login endpoints yet, `cinna login` says so and points you at the `cinna account setup` paste fallback.
+Use it when `cinna account status` or `cinna doctor` reports the account token has expired. Because the per-agent tokens minted from an account (`cinna agent sync`) can only be re-minted while the account token is valid, the flow is: `cinna login` (refresh the account), then `cinna doctor` (re-mint the dependent sub-agent tokens). If the platform doesn't expose the device-login endpoints yet, `cinna login` says so and points you at the `cinna account set-token` paste fallback.
 
 ### `cinna account setup <token_or_url>`
 
@@ -108,7 +112,7 @@ Initialize an **account workspace** — a multi-agent root from which you can di
 curl -sL https://your-platform.com/api/cli-setup/account/TOKEN | python3 -
 ```
 
-Accepts the same input forms as `cinna setup` (full curl command, URL, or bare token — bare tokens need `CINNA_PLATFORM_URL`). Creates `my-cinna/` (override with `--dir`) containing:
+Accepts the same input forms as `cinna setup` (full curl command, URL, or bare token — bare tokens need `CINNA_PLATFORM_URL`). Creates a folder named after the platform domain (override with `--dir`: an absolute path is used as is with parents created, a relative one lands under the current directory; an existing account workspace there is refused before the token is spent) containing:
 
 ```
 my-cinna/
@@ -122,6 +126,17 @@ Setup also downloads the **context package** into `context/` — curated platfor
 
 The account token is only used for the account-level endpoints (listing agents, minting per-agent tokens, the context package). Per-agent work always runs on each child workspace's own token. Revoking the account session in Settings disconnects every agent synced from it.
 
+`account setup`, `account set-token` and `account status` take `--no-input` (never prompt: defaults, or fail with code `needs_input`; also `CINNA_NO_INPUT=1`, accepted before or after the subcommand) and `--json` (one JSON object per line on stdout — progress `{"step","total","status","message"}` lines, then a final `{"result":"ok"|"error",…}`; implies `--no-input`). Exit codes are stable for every command: `0` ok, `10` setup token invalid/expired/used, `11` token for another account, `12` platform unreachable or 5xx, `1` anything else (the JSON `code` says what), `2` usage.
+
+### `cinna account set-token <token_or_url>`
+
+Refresh the **account** token in place from a fresh account setup token — the account counterpart of `cinna set-token`, and the paste alternative to `cinna login`. Run inside the account workspace; it re-exchanges under the stored machine name and rewrites only `account_token` (plus a refreshed platform/frontend URL) in `.cinna/account.json`. The active user workspace, machine name, `context/` and every synced child under `agents/` are untouched; run `cinna doctor` afterwards to re-mint expired child tokens. A token for a different account is refused (exit `11`) and nothing is written. Bare tokens reuse the stored platform URL.
+
+```bash
+cd my-cinna/
+cinna account set-token 'curl -sL https://your-platform.com/api/cli-setup/account/TOKEN | python3 -'
+```
+
 ### `cinna account agents`
 
 List the agents your account can access (run from inside the account workspace). For each agent: display name + ID, building rights (`✓ can build`, `view-only`, or `foreign install` — installed bundles are publisher-managed and can't be synced), whether a remote environment is active, and whether a local workspace already exists under `agents/`.
@@ -130,7 +145,9 @@ List the agents your account can access (run from inside the account workspace).
 
 One-shot summary of the account workspace: platform/frontend URLs, machine name, synced-agent count, and an account-token probe (`valid token` / `expired token` / `no connection`) — the account-level counterpart of `cinna status`.
 
-Also reports the workspace's **context package version** against the platform's current one — the orchestrator guides ship in that tree, so a workspace set up before a guide existed silently lacks it. When it is behind, the command says so and points at `cinna account refresh-context`; `cinna improve list` prints the same nudge, since its playbook lives there.
+Also reports the workspace's **context package version** against the platform's current one — the orchestrator guides ship in that tree, so a workspace set up before a guide existed silently lacks it. When it is behind, the command says so and points at `cinna account refresh-context`; `cinna improve list` prints the same nudge, since its playbook lives there. Likewise it compares the installed **cinna-cli version** with the one the platform pins (its `/.well-known/cinna-desktop` discovery document) and suggests `uv tool install cinna-cli==<pin>` when behind; no pin means "unknown", not an error.
+
+With `--json` it prints a single line: `{"result":"ok","workspace",…,"token":"valid|expired|unreachable","synced_agents":N,"agents":[…],"context_package":{"local","remote","state"},"cli":{"installed","required","state"}}`.
 
 ### `cinna account refresh-context`
 

{cinna_cli-0.3.0 → cinna_cli-0.4.0}/docs/README.md

@@ -137,6 +137,7 @@ Key properties:
 A second token type (`token_type="cli-account"`) issued to an **account workspace** (`.cinna/account.json`). Scoped only to the `/account/*` routes — it discovers agents and mints per-agent CLI tokens (`cinna agent sync`), but cannot itself sync or exec. Same 7-day rolling expiry as a CLI token.
 
 - **Refreshable without a paste** — `cinna login` runs an RFC 8628 device-authorization flow: the CLI prints a short code + URL, the user clicks **Authorize** in the browser (already signed in), and the CLI swaps the fresh token into `.cinna/account.json` in place. Run from an empty/new folder, the same command instead bootstraps a brand-new account workspace.
+- **Refreshable from a setup token** — `cinna account set-token <token_or_url>` re-exchanges a fresh *account* setup token under the stored machine name and rewrites only `account_token` (same in-place swap). Bound to the same account: a different platform origin or token subject aborts with exit `11`. This is the path Cinna Desktop drives (`--no-input --json`) so the user never runs `cinna login`.
 - **Mints child tokens** — per-agent tokens minted from it carry its id as provenance and are re-mintable via `POST /account/agents/{id}/mint` (used by `cinna agent sync` and `cinna doctor`).
 
 ### Knowledge Source
@@ -208,16 +209,17 @@ main.py  (CLI commands — Click)
   ├── config.py          — .cinna/config.json: load/save/find
   ├── auth.py            — JWT storage, Authorization headers
   ├── client.py          — PlatformClient: HTTP + SSE stream_exec
-  ├── mutagen_runtime.py — detect/install Mutagen; gate on version match
+  ├── mutagen_runtime.py — detect/install Mutagen; gate on version match; `CINNA_MUTAGEN_BIN` override
+  ├── cli_version.py     — installed vs platform-pinned cinna-cli version
   ├── sync_session.py    — wrap the `mutagen` CLI (start/stop/status/conflicts)
   ├── sync_tui.py        — live Textual TUI shown by `cinna dev` (Sync/Details/Conflicts tabs)
   ├── sync_ssh_shim.py   — `cinna-sync-ssh` entry point (WebSocket transport)
   ├── sync.py            — tarball/zip extraction helpers (initial clone only)
   ├── context.py         — CLAUDE.md, BUILDING_AGENT.md, .mcp.json, opencode.json
   ├── mcp_proxy.py       — MCP stdio server for knowledge_query
-  ├── console.py         — Rich helpers
+  ├── console.py         — Rich helpers + the `--json` / `--no-input` switches (prompt/confirm wrappers, JSON lines)
   ├── logging.py         — cinna.log (rotating file handler)
-  └── errors.py          — exception hierarchy
+  └── errors.py          — exception hierarchy; `CinnaExit` = stable exit code + machine code
 ```
 
 ### Local Directory Layout
@@ -282,8 +284,8 @@ authoring convention.
 
 | Feature | Command surface | Docs |
 |---|---|---|
-| **Bootstrap & onboarding** | `cinna setup` / `set-token` / `login` / `list` / `status` / `disconnect[-all]` / `completion` / `dev` / `redev` | [business](features/bootstrap_onboarding/bootstrap_onboarding.md) · [tech](features/bootstrap_onboarding/bootstrap_onboarding_tech.md) · [acceptance](features/bootstrap_onboarding/bootstrap_onboarding_acceptance.md) |
-| **Account workspace** | `cinna account` (setup, agents, status, refresh-context, user-workspace, credentials) | [business](features/account_workspace/account_workspace.md) · [tech](features/account_workspace/account_workspace_tech.md) · [acceptance](features/account_workspace/account_workspace_acceptance.md) |
+| **Bootstrap & onboarding** | `cinna setup` / `set-token` / `login` / `list` / `status` / `disconnect[-all]` / `completion` / `dev` / `redev`; the no-TTY contract (`--no-input`, `--json`, exit codes, `CINNA_MUTAGEN_BIN`) | [business](features/bootstrap_onboarding/bootstrap_onboarding.md) · [tech](features/bootstrap_onboarding/bootstrap_onboarding_tech.md) · [acceptance](features/bootstrap_onboarding/bootstrap_onboarding_acceptance.md) |
+| **Account workspace** | `cinna account` (setup, set-token, agents, status, refresh-context, user-workspace, credentials); desktop-managed workspaces | [business](features/account_workspace/account_workspace.md) · [tech](features/account_workspace/account_workspace_tech.md) · [acceptance](features/account_workspace/account_workspace_acceptance.md) |
 | **Agent management** | `cinna agent` (sync, unsync, create, restart-env, show, status) | [business](features/agent_management/agent_management.md) · [tech](features/agent_management/agent_management_tech.md) · [acceptance](features/agent_management/agent_management_acceptance.md) |
 | **Agent schedules** | `cinna agent schedule` (list, generate, create, update, run, logs, delete) | [business](features/agent_schedules/agent_schedules.md) · [tech](features/agent_schedules/agent_schedules_tech.md) · [acceptance](features/agent_schedules/agent_schedules_acceptance.md) |
 | **Live sync** | `cinna sync` (status, conflicts, push, pull, resolve) + Mutagen transport | [business](features/live_sync/live_sync.md) · [tech](features/live_sync/live_sync_tech.md) · [acceptance](features/live_sync/live_sync_acceptance.md) |
@@ -605,6 +607,8 @@ When a CLI token expires (or is revoked) the normal remedy is `cinna set-token <
 | Method | Route | Auth | Purpose |
 |--------|-------|------|---------|
 | POST | `/api/cli-setup/{token}` | Token | Exchange setup token for CLI token |
+| POST | `/api/cli-setup/account/{token}` | Token | Exchange an **account** setup token (`cinna account setup` / `cinna account set-token`); 4xx ⇒ exit 10, 5xx ⇒ exit 12 |
+| GET  | `/.well-known/cinna-desktop` | None | Desktop discovery document; `local_dev.cinna_cli_version` is the cinna-cli pin `cinna account status` / `cinna doctor` compare against (absent ⇒ "unknown") |
 | GET  | `/api/v1/cli/agents/{id}/workspace` | CLI JWT | One-shot tarball for initial clone |
 | GET  | `/api/v1/cli/agents/{id}/building-context` | CLI JWT | Assembled building prompt |
 | POST | `/api/v1/cli/agents/{id}/knowledge/search` | CLI JWT | Knowledge base search (via MCP proxy) |
@@ -645,6 +649,8 @@ uv run ruff format --check src/
 
 The CLI is published to [PyPI](https://pypi.org/project/cinna-cli/) by `.github/workflows/publish.yml`, which runs on any pushed tag matching `v*` (and via manual `workflow_dispatch`). It builds the sdist + wheel with `uv build`, runs `twine check`, then publishes through PyPI **Trusted Publishing** (OIDC — no stored API token) from the GitHub `pypi` environment.
 
+Cinna Desktop installs a **pinned** version (`uv tool install cinna-cli==<version>`) — the version each cinna-core instance advertises as `local_dev.cinna_cli_version` in its discovery document (`CINNA_CLI_VERSION` setting). A release that changes the driver contract (exit codes, `--json` shapes, the three desktop-driven verbs) must be published to PyPI **before** cinna-core's pin moves to it.
+
 ### Cutting a release
 
 Versioning is SemVer (`MAJOR.MINOR.PATCH`); a patch release is the common case. From a clean `main` with the changes you want to ship already merged:

{cinna_cli-0.3.0 → cinna_cli-0.4.0}/docs/features/account_workspace/account_workspace.md

@@ -43,7 +43,16 @@ each with its own token, registry entry, and Mutagen session.
 
 - **Account CLI token** — `cli-account` JWT in `.cinna/account.json`. Same 7-day
   rolling expiry as a per-agent token. Refreshed in place by `cinna login` (a
-  browser device-authorization flow — no paste). Mints child tokens; never syncs.
+  browser device-authorization flow — no paste) or by `cinna account set-token`
+  (paste / hand over a fresh account setup token). Mints child tokens; never
+  syncs.
+- **Desktop-managed workspace** — an account workspace that Cinna Desktop
+  created and keeps alive by driving `cinna` as a child process with no
+  terminal: `account setup` once (into `<AgentsHome>/Cloud/<host>/`), then
+  `account set-token` whenever it mints a new setup token with its own
+  session, and `account status --json` to reconcile. The user never runs
+  `cinna login`, yet the workspace is byte-identical to a terminal-made one —
+  the user's own terminal can `cd` in and use every command.
 - **`agents/` directory** — where `cinna agent sync` materializes per-agent
   checkouts. Account commands that touch local state (`status`, `agents`,
   `refresh-context`) walk this tree to find synced children.
@@ -74,11 +83,52 @@ each with its own token, registry entry, and Mutagen session.
    `agents/`, the orchestrator `CLAUDE.md` + `.claude/settings.json`, the
    knowledge MCP wiring, and the `context/` package. The folder name defaults to
    the platform domain (e.g. `demo-core_opencinna_io`); `--dir` or the prompt
-   overrides it.
+   overrides it. `--dir` is a contract: an **absolute** path is used exactly as
+   given (missing parents are created), a relative one lands under the current
+   directory. Either way an existing `.cinna/account.json` at the target is
+   refused before the token is spent.
 3. Alternatively, `cinna login <domain>` from an empty folder bootstraps the same
    workspace via the browser device flow (no paste); run inside an existing
    account workspace it refreshes the token in place.
 
+### Refresh the token from a setup token — `cinna account set-token`
+1. Mint a fresh **account** setup token (Settings → Local Development, or Cinna
+   Desktop does it with its own session).
+2. Inside the account workspace, `cinna account set-token <token-or-url>`
+   re-exchanges it under the **stored** machine name and swaps only
+   `account_token` (plus a server-refreshed platform / frontend URL) into
+   `.cinna/account.json`. The active user workspace, machine name, `context/`
+   and every child under `agents/` are untouched — the same in-place contract
+   `cinna login` gives, minus the browser. A bare token reuses the stored
+   platform URL.
+3. The new token must be for the **same account**: a different platform origin,
+   or a different `sub` on the token, is refused (exit 11) and nothing is written.
+4. Child tokens are not touched; `cinna doctor` re-mints expired ones as usual.
+
+### Driven by Cinna Desktop (no terminal)
+1. The desktop obtains a setup token from the platform with its own session and
+   spawns `cinna account setup "<setup_command>" --dir <absolute> --name <machine>
+   --no-input --json`.
+2. `--no-input` guarantees the process never waits for a human: every prompt
+   takes its default (machine name, folder), or fails with the machine code
+   `needs_input`. `CINNA_NO_INPUT=1` does the same for any command. `--json`
+   implies it.
+3. `--json` turns the output into one JSON object per line on stdout: progress
+   lines `{step, total, status: start|ok|warn|fail, message}` mirroring the
+   numbered steps, then exactly one final line — `{"result": "ok", …}` with the
+   workspace path, platform / frontend URLs, machine name and context-package
+   outcome, or `{"result": "error", "code", "detail"}`. Nothing else touches
+   stdout; logs stay in `cinna.log`.
+4. The process exit code is stable: `0` ok · `10` setup token invalid / expired /
+   already used · `11` the token is for another account · `12` the platform is
+   unreachable or answered 5xx · `1` anything else, with a specific `code`
+   (`workspace_exists`, `needs_input`, `mutagen_missing`, `mutagen_mismatch`,
+   `not_an_account_workspace`, …) · `2` bad invocation.
+5. Later the desktop runs `cinna account set-token "<setup_command>" --no-input
+   --json` to refresh silently, and `cinna account status --json` to read token
+   validity, synced agents, context-package freshness and whether the installed
+   cinna-cli matches the version the platform pins.
+
 ### Discover and attach agents
 1. `cinna account agents` lists the agents the account can access — name + id,
    build rights (foreign bundle installs are view-only), whether the remote env
@@ -126,7 +176,25 @@ each with its own token, registry entry, and Mutagen session.
   sync/exec always use the per-agent child token via the per-agent client.
 - **Single-use setup token is guarded before it's burned.** `cinna account setup`
   refuses an existing-workspace target *before* exchanging the token, so a doomed
-  run never wastes the one-time token.
+  run never wastes the one-time token (exit 1, code `workspace_exists`).
+- **`set-token` is account-bound, fail-loud.** The refreshed token must match
+  the workspace's platform origin and (when both tokens carry one) the same
+  subject; otherwise nothing is written and the command exits 11
+  (`account_mismatch`). It never rebinds a workspace to another account.
+- **Never hang without a terminal.** Under `--no-input` (or `CINNA_NO_INPUT=1`,
+  or `--json`) no command blocks on stdin: prompts take their default or fail
+  with `needs_input`; confirmations take their default (usually "No", which
+  aborts). The `/dev/tty` fallback the `curl | python3` bootstrap uses for the
+  folder prompt is skipped too.
+- **`--json` is a pure stream.** Rich output is suppressed entirely; each stdout
+  line is one JSON object and the last one is always the `result` line, on
+  success and on failure alike. Human output is unchanged when the flag is off.
+- **Exit codes are a contract.** 0 / 10 / 11 / 12 / 1 (+ `code`) / 2 as listed
+  in the desktop flow; every error the CLI raises on purpose maps onto it, so a
+  driver switches on the number, not on message text.
+- **Version pin is advisory.** `account status` compares the running cinna-cli
+  with the version the platform publishes in its discovery document; a missing
+  pin is `unknown`, never an error.
 - **Fail-loud on backend errors.** Token exchange, mint, and every account call
   surface the backend's `detail` verbatim (expired/used token, foreign-install
   403, ambiguous agent). The CLI does not pre-judge build rights client-side —
@@ -173,7 +241,11 @@ cinna account setup ────────────────────
       ▼
 .cinna/account.json  (account CLI token, cli-account scope)
       │
+      ├── cinna account set-token <token> ───────────────────► POST /cli-setup/account/<token>
+      │       (stored machine name; same-account check; rewrites account_token only)
+      ├── cinna login (device flow) ─────────────────────────► /api/v1/cli/account/login/*
       ├── cinna account agents / status / refresh-context ─► AccountClient ─► /api/v1/cli/account/*
+      │       (status: + GET /.well-known/cinna-desktop for the cinna-cli pin)
       ├── cinna account user-workspace … (client-side active selection)
       ├── cinna account credentials … (metadata-only drafts)
       │
@@ -205,11 +277,17 @@ cinna account setup ────────────────────
   publisher-install flag its ownership step depends on. See
   [improvement_requests](../improvement_requests/improvement_requests.md).
 - **Doctor / login** — `cinna doctor` re-mints expired per-agent tokens through
-  the account token, and groups blocked agents under a single `cinna login` hint
-  when the account token itself has expired.
+  the account token, and groups blocked agents under a single `cinna login` /
+  `cinna account set-token` hint when the account token itself has expired. It
+  also reports a cinna-cli that differs from the platform's pin.
+- **Bootstrap / onboarding** — the no-terminal contract (`--no-input`, `--json`,
+  exit codes, `CINNA_MUTAGEN_BIN`) is CLI-wide and described in
+  [Bootstrap & Onboarding](../bootstrap_onboarding/bootstrap_onboarding.md);
+  this doc covers how the account verbs use it.
+- **Cinna Desktop** — installs its own pinned cinna-cli (with uv and Mutagen) and
+  drives the three verbs above; the desktop-side plan lives in the cinna-desktop
+  repo (`plans/one-click-onboarding-desktop.md`). <!-- nocheck: cross-repo path -->
 
 Implementation: see [account_workspace_tech.md](account_workspace_tech.md).
 Real-usage e2e test scenarios: see
 [account_workspace_acceptance.md](account_workspace_acceptance.md).
-</content>
-</invoke>

{cinna_cli-0.3.0 → cinna_cli-0.4.0}/docs/features/account_workspace/account_workspace_acceptance.md

@@ -26,8 +26,10 @@ the silent-secret and scope-drift bugs live.
 - **Editable install** of the CLI under test:
   `python3 -c "import cinna,os;print(os.path.dirname(cinna.__file__))"` must point
   at this repo's `src/cinna`. Confirm `which cinna` resolves and
-  `cinna account --help` lists `setup / agents / status / refresh-context /
-  user-workspace / credentials`.
+  `cinna account --help` lists `setup / set-token / agents / status /
+  refresh-context / user-workspace / credentials`.
+- For the no-terminal scenarios (15–18): `jq` to inspect the JSON lines, and a
+  second **account** setup token per run (every exchange burns one).
 - `git` and `mutagen` on `PATH` (needed once a child agent is synced and
   exercised).
 
@@ -253,8 +255,114 @@ the silent-secret and scope-drift bugs live.
 - **Watch for:** user files deleted; the registry entry surviving; a revoke error
   aborting the command.
 
+### 15. Desktop-style setup: absolute `--dir`, `--no-input`, `--json`, no TTY
+
+- **Goal:** Cinna Desktop creates the account workspace as a child process with
+  no terminal and parses the result.
+- **Setup:** a fresh account setup token; note the `setup_command` string the
+  platform returns (`curl -sL …/api/cli-setup/account/<TOKEN> | python3 -`).
+- **Steps:**
+  ```
+  TARGET="$HOME/CinnaAgents/Cloud/localhost"          # parents must not exist yet
+  cinna account setup 'curl -sL http://localhost:8000/api/cli-setup/account/<TOKEN> | python3 -' \
+      --dir "$TARGET" --name desktop-test --no-input --json < /dev/null > out.jsonl; echo "exit $?"
+  cat out.jsonl | jq -c .
+  ls -a "$TARGET"; cat "$TARGET/.cinna/account.json"
+  ```
+- **Expected:** exit `0`. Every line of `out.jsonl` parses; the first three are
+  `{"step":1..3,"total":3,"status":"start",…}`, the last is `{"result":"ok",
+  "workspace":"<TARGET>","platform_url":…,"frontend_url":…,"machine_name":
+  "desktop-test","context_package":"ok"}`. The workspace sits exactly at
+  `$TARGET` (dots in the host kept, parents created), with the same files as
+  scenario 1. No table, hint or spinner text on stdout.
+- **Watch for:** the workspace landing under cwd instead of the absolute path;
+  a non-JSON line on stdout (Rich leaking); the process waiting on stdin
+  (folder / machine-name prompt); `context_package` not reflecting a failed
+  download (should be `failed` with a preceding `"status":"warn"` line, exit
+  still 0).
+
+### 16. Desktop-style refresh: `account set-token` in place, same account only
+
+- **Goal:** the desktop refreshes an expiring account token silently; a token
+  for another account can never be swapped in.
+- **Setup:** scenario 15's workspace; `cinna account user-workspace activate
+  <name>` so a client-side selection exists; one synced child (scenario 5).
+  Mint two fresh account setup tokens: one as the **same** user, one as a
+  **different** user on the same platform.
+- **Steps:**
+  ```
+  cd "$TARGET"; cp .cinna/account.json /tmp/before.json
+  cinna account set-token 'curl -sL http://localhost:8000/api/cli-setup/account/<SAME_USER_TOKEN> | python3 -' \
+      --no-input --json < /dev/null; echo "exit $?"
+  diff <(jq 'del(.account_token)' /tmp/before.json) <(jq 'del(.account_token)' .cinna/account.json)
+  cat agents/<slug>/.cinna/config.json | jq .cli_token       # unchanged
+  cinna account set-token 'curl -sL http://localhost:8000/api/cli-setup/account/<OTHER_USER_TOKEN> | python3 -' \
+      --no-input --json < /dev/null; echo "exit $?"
+  cinna account set-token '<SAME_USER_TOKEN again>' --json; echo "exit $?"
+  ```
+- **Expected:** first call exits `0`, prints two `start` steps, an `ok` line
+  and `{"result":"ok",…,"context_package":"skipped"}`; only `account_token`
+  changed (the `diff` is empty), the child token is untouched, and the exchange
+  was made with the **stored** machine name (check the CLI token list in
+  Settings — no new machine). The other-user call exits `11` with
+  `{"result":"error","code":"account_mismatch",…}` and `account.json` is
+  unchanged. The reused (already burned) token exits `10` with
+  `code: "setup_token_invalid"` and the backend detail.
+- **Watch for:** the mismatch being detected only after the file was written;
+  `user_workspace_id` or `machine_name` reset; a new machine appearing in the
+  platform's token list; exit `1` where `10` / `11` is required.
+
+### 17. Exit-code contract
+
+- **Goal:** a driver can act on the exit code alone.
+- **Steps:** run each from a scratch dir with `--no-input --json < /dev/null`
+  and record `$?` plus the final line's `code`:
+  ```
+  cinna account setup '<ALREADY_USED_TOKEN_URL>' --dir /tmp/x1        # 10 setup_token_invalid
+  cinna account setup '<VALID_URL>' --dir "$TARGET"                    # 1  workspace_exists (token NOT burned)
+  cinna account setup 'http://127.0.0.1:1/api/cli-setup/account/X' --dir /tmp/x2   # 12 network
+  cinna account status                                                 # 1  not_an_account_workspace
+  cinna --no-input login                                               # 1  needs_input (no domain, human text)
+  cinna account setup                                                  # 2  usage
+  ```
+  Then, with the backend stopped: `cinna account set-token '<URL>' --json` → `12`.
+- **Expected:** the codes in the comments. For the `workspace_exists` case,
+  re-use the same valid token afterwards in a fresh dir — it must still work.
+- **Watch for:** any of these coming back as a bare `1`; a traceback instead of
+  a JSON error line; the guard case burning the token.
+
+### 18. `account status --json` and the cinna-cli version pin
+
+- **Goal:** the desktop reconciles from one status line, including whether to
+  reinstall cinna-cli.
+- **Steps:**
+  ```
+  cd "$TARGET"; cinna account status --json | jq .
+  curl -s http://localhost:8000/.well-known/cinna-desktop | jq .local_dev
+  cinna account status | tail -20
+  cinna doctor --dry-run
+  ```
+- **Expected:** exactly one JSON line with `result`, `workspace`,
+  `platform_url`, `frontend_url`, `machine_name`, `active_workspace`
+  (`{id,name}` or `null`), `token` (`valid|expired|unreachable`),
+  `synced_agents`, `agents[]`, `context_package{local,remote,state}` and
+  `cli{installed,required,state}`. When the platform publishes
+  `local_dev.cinna_cli_version`, `cli.required` equals it and `state` is
+  `current` / `behind` / `ahead`; on an older platform `required` is `null`
+  and `state` is `unknown` — still exit 0. The human `status` shows the same
+  as a `cinna-cli` table row and a `uv tool install cinna-cli==<pin>` hint when
+  behind; `doctor` lists the platform under "manual action needed" only when
+  the pin differs.
+- **Watch for:** a missing discovery document turning into an error; `doctor`
+  nagging when no pin is published; the JSON line missing `cli`.
+
 ## Cross-cutting invariants (must hold across all scenarios)
 
+- **`--json` stdout is JSON only, last line is the verdict** — every stdout line
+  parses; exactly one `result` line; human hints never leak.
+- **Never wait for a human without a terminal** — with `--no-input` / `--json`
+  / `CINNA_NO_INPUT=1` every command either proceeds or fails with
+  `needs_input`; nothing reads stdin or `/dev/tty`.
 - **No secret ever sent** — credential create/update bodies carry only metadata;
   the CLI cannot read or write a credential's secret value.
 - **Account token stays account-scoped** — it is used only on `/account/*`; every
@@ -284,4 +392,3 @@ the silent-secret and scope-drift bugs live.
 - Verify `~/.cinna/agents.json` has no leftover entries for the test children —
   especially if any helper ran **outside** pytest's global-state isolation (it
   would write the real registry).
-</content>

{cinna_cli-0.3.0 → cinna_cli-0.4.0}/docs/features/account_workspace/account_workspace_tech.md

@@ -29,15 +29,25 @@ and tests in `tests/test_account.py`.
 - `src/cinna/mcp_proxy.py` — account-mode knowledge proxy
   (`run_mcp_proxy` / `_resolve_proxy_context` / `create_account_mcp_server`)
   wired by the account `.mcp.json`.
-- `src/cinna/errors.py` — `AccountConfigNotFoundError` ("Not in a cinna account
-  workspace…").
+- `src/cinna/errors.py` — `CinnaExit` (stable exit code + machine `code`) and
+  its subclasses used here: `SetupTokenError` (10), `AccountMismatchError` (11),
+  `NetworkError` / `PlatformError` 5xx (12), `WorkspaceExistsError`,
+  `AccountConfigNotFoundError`.
+- `src/cinna/console.py` — the `json_mode` / `no_input` switches, the JSON line
+  writer (`emit_json` / `emit_result`) and the `prompt` / `confirm` /
+  `interactive` wrappers every prompt site goes through.
+- `src/cinna/cli_version.py` — installed-vs-pinned cinna-cli version
+  (`cli_version_status`, `fetch_required_cli_version`).
 - `src/cinna/templates/ACCOUNT_CLAUDE.md.template` — the orchestrator
   `CLAUDE.md` source.
 - Tests: `tests/test_account.py` (setup, refresh-context, agents listing +
   workspace scoping, status, agent sync/unsync, exec `--agent`, child-workspace
   resolution incl. multi-segment subdir, user-workspace, credentials,
-  `AccountClient` HTTP-level), `tests/test_client.py` (account client), and the
-  MCP-proxy account-mode tests in `tests/test_account.py`.
+  `AccountClient` HTTP-level), `tests/test_client.py` (account client), the
+  MCP-proxy account-mode tests in `tests/test_account.py`, and
+  `tests/test_onboarding.py` (the driver contract: exit codes, absolute `--dir`,
+  `account set-token`, `--no-input`, `--json` line snapshots, version pin in
+  status / doctor).
 
 ## Command surface
 
@@ -46,6 +56,8 @@ Each verb → its handler in `src/cinna/main.py` → the body in
 
 - `cinna account setup` → `src/cinna/main.py:account_setup()` →
   `src/cinna/account.py:run_account_setup()`
+- `cinna account set-token` → `src/cinna/main.py:account_set_token()` →
+  `src/cinna/account.py:run_account_set_token()`
 - `cinna account agents` → `src/cinna/main.py:account_agents()` →
   `src/cinna/account.py:run_account_agents()`
 - `cinna account status` → `src/cinna/main.py:account_status()` →
@@ -80,6 +92,14 @@ Each verb → its handler in `src/cinna/main.py` → the body in
   `src/cinna/main.py:account_credentials_share_with_agent()` →
   `src/cinna/account.py:run_credentials_share()`
 
+`setup`, `set-token` and `status` also take `--no-input` and `--json`
+(`src/cinna/main.py:no_input_option()` / `json_option()` — eager, value-less
+options whose callbacks flip `src/cinna/console.py:set_no_input()` /
+`set_json_mode()`); the root group takes `--no-input` too (also
+`CINNA_NO_INPUT=1`). The per-command copy exists because
+`ignore_unknown_options` + the `nargs=-1` setup argument would otherwise
+swallow a flag placed after the subcommand, which is how the desktop invokes it.
+
 Related (documented here as integration points): `cinna agent sync` →
 `src/cinna/account.py:run_agent_sync()`, `cinna agent unsync` →
 `run_agent_unsync()`, `cinna login` → `run_login()`.
@@ -99,10 +119,32 @@ Related (documented here as integration points): `cinna agent sync` →
   bare token falls back to `CINNA_PLATFORM_URL`.
 - `src/cinna/account.py:default_account_dir_name()` — derives the default folder
   from the platform host (collapses non-`[A-Za-z0-9-]` to `_`).
-- `src/cinna/account.py:run_account_setup()` — parse → derive/prompt the dir →
-  **guard the target before** `_exchange_account_setup_token()` → build
-  `AccountConfig` → `_write_account_files()` → best-effort
-  `_install_context_package()`.
+- `src/cinna/account.py:resolve_account_dir()` — the `--dir` contract: absolute
+  (after `~` expansion) → as is, relative → under cwd. No symlink resolution, so
+  the path reported back equals the one passed.
+- `src/cinna/account.py:run_account_setup()` — parse → derive/prompt the dir
+  (`_prompt_account_dir()` returns the default outright under `no_input`) →
+  `resolve_account_dir()` → **guard the target before**
+  `_exchange_account_setup_token()` (`WorkspaceExistsError`) → build
+  `AccountConfig` → `_write_account_files()` (creates parents) → best-effort
+  `_install_context_package()` → `console.emit_result()` with
+  `_account_result_fields()`.
+- `src/cinna/account.py:_exchange_account_setup_token()` — the exchange with the
+  exit-code mapping: transport error → `NetworkError` (12), 5xx →
+  `PlatformError` (12), any other non-200 → `SetupTokenError` (10, backend
+  detail verbatim, `http_status` in the JSON error line).
+- `src/cinna/account.py:run_account_set_token()` — `find_account_root()` →
+  `parse_account_setup_input(…, fallback_platform_url=<stored>/api)` →
+  exchange under the **stored** `machine_name` → `_same_origin()` check on
+  `platform_url` and `_jwt_claims()` `sub` comparison (both raise
+  `AccountMismatchError`, 11, before any write) → rewrite `account_token` +
+  refreshed `platform_url` / `frontend_url` → `save_account_config()`.
+  `user_workspace_*`, `machine_name`, `context/`, children untouched.
+- `src/cinna/account.py:_jwt_claims()` — unverified base64 decode of a JWT
+  payload, only to compare `sub`; opaque tokens yield `None` (no comparison).
+- `src/cinna/account.py:_account_result_fields()` — the shared `--json` final
+  line of setup / set-token (`workspace`, `platform_url`, `frontend_url`,
+  `machine_name`, `context_package: ok|failed|skipped`).
 - `src/cinna/account.py:_write_account_files()` — mkdir + `save_account_config` +
   `agents/` + `_write_account_claude_md` + `_write_account_claude_settings` +
   `_write_account_mcp_config`.
@@ -118,7 +160,15 @@ Related (documented here as integration points): `cinna agent sync` →
   **client-side** scope to `user_workspace_id` (unless `--all`), and annotate each
   row with the local checkout from `list_child_workspaces()`.
 - `src/cinna/account.py:run_account_status()` — `probe_account_token()` +
-  `_synced_agents_table()` + `_print_token_reauth_hint()`.
+  `context_package_status()` + `cli_version_status()`; in JSON mode emits the
+  single `result` line (`token`, `active_workspace`, `synced_agents`, `agents[]`,
+  `context_package{local,remote,state}`, `cli{installed,required,state}`) and
+  returns; otherwise the Rich table + `_synced_agents_table()` +
+  `_print_token_reauth_hint()` (which now names `cinna account set-token` next
+  to `cinna login`).
+- `src/cinna/cli_version.py:cli_version_status()` — `GET
+  {origin}/.well-known/cinna-desktop` → `local_dev.cinna_cli_version`, compared
+  with the running `__version__` (`current` / `behind` / `ahead` / `unknown`).
 - `src/cinna/account.py:probe_account_token()` — cheap `GET /account/agents`;
   2xx → valid, 401 → expired, else → unreachable.
 - `src/cinna/account.py:run_agent_sync()` — resolve via `_resolve_account_agent`,
@@ -185,7 +235,14 @@ All consumed by `src/cinna/client.py:AccountClient` with the account token
 - `POST /cli-setup/account/{token}` — exchange the account setup token
   (`src/cinna/account.py:_exchange_account_setup_token()`, plain `httpx.post`, not
   the client). Body: `{machine_name, machine_info}`. Returns `account_token`,
-  `platform_url`, `frontend_url`, `machine_name`.
+  `platform_url`, `frontend_url`, `machine_name`. Used by both `account setup`
+  and `account set-token`; the CLI relies on the response being identical for a
+  first and a repeat exchange (no `user`/owner field is required — the
+  same-account check works from the origin and the token's own `sub`).
+- `GET /.well-known/cinna-desktop` (unauthenticated, platform origin) — the
+  desktop discovery document; `local_dev.cinna_cli_version` is the cinna-cli
+  pin (`src/cinna/cli_version.py:fetch_required_cli_version()`). Absent block,
+  404 or no network → `unknown`, silently.
 - `GET /api/v1/cli/account/agents` — accessible agents (`list_account_agents`;
   also the token probe).
 - `POST /api/v1/cli/account/agents/{id}/mint` — mint a per-agent child token
@@ -221,7 +278,31 @@ All consumed by `src/cinna/client.py:AccountClient` with the account token
 - **Guard before burning the setup token** — `run_account_setup` checks the
   target dir exists-check *before* calling `_exchange_account_setup_token`, so a
   doomed run never spends the single-use token.
-  (`tests/test_account.py:test_account_setup_refuses_existing_workspace`)
+  (`tests/test_account.py:test_account_setup_refuses_existing_workspace`,
+  `tests/test_onboarding.py:test_setup_existing_absolute_dir_is_workspace_exists`)
+- **Absolute `--dir` is used as is, parents created** — `resolve_account_dir()`;
+  the `workspace` reported in JSON is the path the caller passed.
+  (`tests/test_onboarding.py:test_setup_absolute_dir_used_as_is_and_parents_created`)
+- **`set-token` never rebinds** — the origin / `sub` checks precede the write;
+  on mismatch `account.json` is byte-identical afterwards.
+  (`tests/test_onboarding.py:test_account_set_token_platform_mismatch_exits_11`,
+  `test_account_set_token_subject_mismatch_exits_11`)
+- **`set-token` preserves everything but the token** — active user workspace,
+  machine name and child configs survive.
+  (`tests/test_onboarding.py:test_account_set_token_swaps_token_in_place`)
+- **Exit codes are mapped centrally** — `src/cinna/main.py:CinnaGroup.invoke()`
+  wraps plain `ClickException`s, `httpx.TransportError`s and (in JSON mode)
+  unexpected exceptions into `CinnaExit`; `CinnaExit.show()` prints the JSON
+  error line instead of `Error: …` when `json_mode` is on.
+  (`tests/test_onboarding.py`, the "exit codes" block)
+- **`--json` stdout is JSON only** — `set_json_mode()` swaps the Rich console
+  for a quiet one; `spinner()` is a no-op; every stdout line must parse.
+  (`tests/test_onboarding.py:test_setup_json_progress_and_result`,
+  `test_status_json`)
+- **`--no-input` never blocks** — `_prompt_account_dir()` short-circuits, the
+  machine-name prompt takes its default, `console.confirm()` returns the
+  default. (`tests/test_onboarding.py:test_no_input_after_subcommand_skips_dir_prompt`,
+  `test_group_level_no_input_fails_needs_input`)
 - **Context refresh is non-destructive** — `_install_context_package(replace=True)`
   removes `context/` only after a successful download; the orchestrator/child
   `CLAUDE.md` regeneration is independent of the download.
@@ -252,4 +333,3 @@ All consumed by `src/cinna/client.py:AccountClient` with the account token
 - **Safe extraction** — the context tarball reuses the path-traversal/absolute/
   symlink-rejecting extractor.
   (`tests/test_account.py:test_context_extraction_rejects_malicious_members`)
-</content>