@odla-ai/cli 0.34.0 → 0.34.1

package/README.md

@@ -30,10 +30,10 @@ day.
 Ask before you search the web or work from memory:
 
 ```bash
-npx @odla-ai/cli runbook ask "how do I roll back a bad publish?"   # written, cited answer
-npx @odla-ai/cli runbook search "restore a tenant"                 # the passages behind it
-npx @odla-ai/cli runbook get release                               # the whole procedure
-npx @odla-ai/cli runbook list                                      # what exists
+npx --yes @odla-ai/cli@latest runbook ask "how do I roll back a bad publish?"   # written, cited answer
+npx --yes @odla-ai/cli@latest runbook search "restore a tenant"                 # the passages behind it
+npx --yes @odla-ai/cli@latest runbook get release                               # the whole procedure
+npx --yes @odla-ai/cli@latest runbook list                                      # what exists
 ```
 
 Reading works for any signed-in developer and needs no `odla.config.mjs` — the
@@ -45,9 +45,9 @@ Before an agent reads PM, Discussions, o11y, runbooks, or identity from a fresh
 workspace, it can explain the selected context without authenticating:
 
 ```bash
-npx @odla-ai/cli context show --platform https://odla.ai --app <appId> --env prod --json
-npx @odla-ai/cli context save production --platform https://odla.ai --app <appId> --env prod
-npx @odla-ai/cli context show --context production --json
+npx --yes @odla-ai/cli@latest context show --platform https://odla.ai --app <appId> --env prod --json
+npx --yes @odla-ai/cli@latest context save production --platform https://odla.ai --app <appId> --env prod
+npx --yes @odla-ai/cli@latest context show --context production --json
 ```
 
 For each value, an explicit flag wins over the matching
@@ -81,13 +81,13 @@ project. The installed `references/agent-identity.md` runbook gives the full
 cross-worktree recovery procedure.
 
 ```bash
-ODLA_DEV_TOKEN=... npx @odla-ai/cli pm handoff --app <appId>
-ODLA_DEV_TOKEN=... npx @odla-ai/cli discuss list --app <appId> --json
-ODLA_DEV_TOKEN=... npx @odla-ai/cli o11y status --app <appId> --env prod --json
-ODLA_DEV_TOKEN=... npx @odla-ai/cli whoami --json
-npx @odla-ai/cli platform status --context production --json
-npx @odla-ai/cli pm handoff --context production --json
-npx @odla-ai/cli runbook new deploy --context production --title Deploy --file deploy.md
+ODLA_DEV_TOKEN=... npx --yes @odla-ai/cli@latest pm handoff --app <appId>
+ODLA_DEV_TOKEN=... npx --yes @odla-ai/cli@latest discuss list --app <appId> --json
+ODLA_DEV_TOKEN=... npx --yes @odla-ai/cli@latest o11y status --app <appId> --env prod --json
+ODLA_DEV_TOKEN=... npx --yes @odla-ai/cli@latest whoami --json
+npx --yes @odla-ai/cli@latest platform status --context production --json
+npx --yes @odla-ai/cli@latest pm handoff --context production --json
+npx --yes @odla-ai/cli@latest runbook new deploy --context production --title Deploy --file deploy.md
 ```
 
 Runbooks tell an agent how to operate; PM tells every agent what this project is
@@ -96,15 +96,15 @@ app is registered, start each session with the read-only aligned-work intake,
 then read open bugs and recent decisions:
 
 ```bash
-npx odla-ai pm project list --app <productId>
-npx odla-ai pm project add --app <productId> --name "My project"
-npx odla-ai pm project use <projectId>
-npx odla-ai pm next --app <appId> --project <projectId>
-npx odla-ai pm handoff --app <appId>
-npx odla-ai pm watch --app <appId> --entity task --jsonl
-npx odla-ai pm bug list --app <appId> --status open
-npx odla-ai pm goal list --app <appId> --status open
-npx odla-ai pm decision list --app <appId> --limit 20
+npx --yes @odla-ai/cli@latest pm project list --app <productId>
+npx --yes @odla-ai/cli@latest pm project add --app <productId> --name "My project"
+npx --yes @odla-ai/cli@latest pm project use <projectId>
+npx --yes @odla-ai/cli@latest pm next --app <appId> --project <projectId>
+npx --yes @odla-ai/cli@latest pm handoff --app <appId>
+npx --yes @odla-ai/cli@latest pm watch --app <appId> --entity task --jsonl
+npx --yes @odla-ai/cli@latest pm bug list --app <appId> --status open
+npx --yes @odla-ai/cli@latest pm goal list --app <appId> --status open
+npx --yes @odla-ai/cli@latest pm decision list --app <appId> --limit 20
 ```
 
 `pm handoff` is the authoritative unresolved-state view: unmet goals, every
@@ -129,8 +129,8 @@ Refine a Backlog task with `--goal` (or an accepted
 and claim the reviewed revision:
 
 ```bash
-npx odla-ai pm task ready <id> --expected-revision <n>
-npx odla-ai pm task claim <id> --expected-revision <n>
+npx --yes @odla-ai/cli@latest pm task ready <id> --expected-revision <n>
+npx --yes @odla-ai/cli@latest pm task claim <id> --expected-revision <n>
 ```
 
 Ready is stored as `todo` for API compatibility. Claims are atomic and assign
@@ -160,7 +160,7 @@ When diagnosing a deployed app, agents can request one parseable observability
 snapshot instead of scraping Studio or composing collector routes themselves:
 
 ```bash
-npx odla-ai o11y status --app <appId> --env prod --minutes 60 --json
+npx --yes @odla-ai/cli@latest o11y status --app <appId> --env prod --minutes 60 --json
 ```
 
 Schema v9 keeps application RED, an `applicationVersions` breakdown of
@@ -242,19 +242,19 @@ slos: [{
 rollout is `ops/monitoring/odla-db.config.mjs`:
 
 ```bash
-npx odla-ai monitor plan --config ops/monitoring/odla-db.config.mjs --env prod --json
+npx --yes @odla-ai/cli@latest monitor plan --config ops/monitoring/odla-db.config.mjs --env prod --json
 ```
 
 Preview and apply the normalized policy, then inspect or exercise it through
 stable JSON:
 
 ```bash
-npx odla-ai monitor plan --env prod --json
-npx odla-ai monitor apply --env prod --yes --json
-npx odla-ai monitor status --app <appId> --env prod --json
-npx odla-ai monitor run home --app <appId> --env prod --json
-npx odla-ai monitor incidents --app <appId> --env prod --runs --json
-npx odla-ai monitor report --app <appId> --env prod --period weekly --json
+npx --yes @odla-ai/cli@latest monitor plan --env prod --json
+npx --yes @odla-ai/cli@latest monitor apply --env prod --yes --json
+npx --yes @odla-ai/cli@latest monitor status --app <appId> --env prod --json
+npx --yes @odla-ai/cli@latest monitor run home --app <appId> --env prod --json
+npx --yes @odla-ai/cli@latest monitor incidents --app <appId> --env prod --runs --json
+npx --yes @odla-ai/cli@latest monitor report --app <appId> --env prod --period weekly --json
 ```
 
 Only scheduled `good` and `bad` outcomes enter the application SLO denominator.
@@ -285,10 +285,10 @@ For repository-managed settings, compare checked-in intent with the live
 owner-visible Registry projection before provisioning:
 
 ```bash
-npx odla-ai config diff --json
-npx odla-ai config plan --json > .odla/config-plan.json
-npx odla-ai config apply --plan .odla/config-plan.json --json
-npx odla-ai operations wait <operation-id> --json
+npx --yes @odla-ai/cli@latest config diff --json
+npx --yes @odla-ai/cli@latest config plan --json > .odla/config-plan.json
+npx --yes @odla-ai/cli@latest config apply --plan .odla/config-plan.json --json
+npx --yes @odla-ai/cli@latest operations wait <operation-id> --json
 ```
 
 `diff` and `plan` are read-only and request only a short-lived,
@@ -339,8 +339,8 @@ JSDoc, and neither from memory.
 **After you change something, ask which runbooks you invalidated:**
 
 ```bash
-npx @odla-ai/cli runbook impact               # vs origin/main, uncommitted work included
-npx @odla-ai/cli runbook impact --base HEAD~1
+npx --yes @odla-ai/cli@latest runbook impact               # vs origin/main, uncommitted work included
+npx --yes @odla-ai/cli@latest runbook impact --base HEAD~1
 ```
 
 It diffs the working tree, works out which surfaces moved — a package, its
@@ -351,7 +351,7 @@ before you call the change finished. Fixing what it finds is one command and
 takes effect immediately:
 
 ```bash
-npx @odla-ai/cli runbook edit db --note "retract replaced the null write"
+npx --yes @odla-ai/cli@latest runbook edit db --note "retract replaced the null write"
 ```
 
 Platform runbook edits need admin or the `platform:runbook:write` capability,
@@ -364,7 +364,7 @@ but never grants authority.
 **Is the corpus itself still true?**
 
 ```bash
-npx odla-ai runbook lint
+npx --yes @odla-ai/cli@latest runbook lint
 ```
 
 Because a runbook is edited without a release, its text can name a command that
@@ -381,16 +381,20 @@ the procedure and nothing else.
 ## Install
 
 No install needed — the package ships a single `odla-ai` binary, so npx can run
-it directly:
+it directly. Agents and one-off setup should resolve the current published CLI
+explicitly:
 
 ```bash
-npx @odla-ai/cli init --app-id my-app --name "My App"
+npx --yes @odla-ai/cli@latest init --app-id my-app --name "My App"
 ```
 
 For a project you keep working in, install it as a dev dependency so the
-shorter `npx odla-ai` form works. ODLA is under active development: use a normal
-dependency declaration, commit the lockfile, and let `npm ci` reproduce the
-resolved graph:
+lockfile records the CLI/runtime graph used by that application. Use
+`npx --no-install odla-ai` only when deliberately testing that pinned graph;
+agent orchestration examples use `@latest` so a stale workspace or cache does
+not silently select an older CLI. ODLA is under active development: use a
+normal dependency declaration, commit the lockfile, and let `npm ci` reproduce
+the resolved graph:
 
 ```bash
 npm view @odla-ai/cli version
@@ -419,61 +423,62 @@ npm ls @odla-ai/cli
 ## Commands
 
 ```bash
-npx odla-ai runbook ask "how do I roll back a bad publish?"
-npx odla-ai runbook search "restore a tenant" --limit 5
-npx odla-ai runbook get release
-npx odla-ai runbook list
-npx odla-ai runbook impact --base origin/main
-npx odla-ai runbook lint
-npx odla-ai runbook edit db --note "what changed"
-npx odla-ai runbook comment release --body "step 4 no longer applies"
-npx odla-ai context show --app my-app --env prod --json
-npx odla-ai whoami
-npx odla-ai setup
-npx odla-ai init --app-id my-app --name "My App"
-npx odla-ai doctor
-npx odla-ai ai models --env dev # exact models this app may select; no admin grant
-npx odla-ai config diff --json
-npx odla-ai config plan --json > .odla/config-plan.json
-npx odla-ai config apply --plan .odla/config-plan.json --json
-npx odla-ai operations get <operation-id> --json
-npx odla-ai operations wait <operation-id> --timeout 60 --json
-npx odla-ai calendar status --env dev
-npx odla-ai calendar calendars --env dev
-npx odla-ai calendar connect --env dev
-npx odla-ai calendar disconnect --env dev --yes
-npx odla-ai capabilities --json
-npx odla-ai code connect --platform https://odla.ai --app-id my-app --env dev --email owner@example.com
-npx odla-ai code connect --env prod --once # bounded enrollment + heartbeat proof
+npx --yes @odla-ai/cli@latest auth login --app my-app --email owner@example.com --no-open --wait 600
+npx --yes @odla-ai/cli@latest runbook ask "how do I roll back a bad publish?"
+npx --yes @odla-ai/cli@latest runbook search "restore a tenant" --limit 5
+npx --yes @odla-ai/cli@latest runbook get release
+npx --yes @odla-ai/cli@latest runbook list
+npx --yes @odla-ai/cli@latest runbook impact --base origin/main
+npx --yes @odla-ai/cli@latest runbook lint
+npx --yes @odla-ai/cli@latest runbook edit db --note "what changed"
+npx --yes @odla-ai/cli@latest runbook comment release --body "step 4 no longer applies"
+npx --yes @odla-ai/cli@latest context show --app my-app --env prod --json
+npx --yes @odla-ai/cli@latest whoami
+npx --yes @odla-ai/cli@latest setup
+npx --yes @odla-ai/cli@latest init --app-id my-app --name "My App"
+npx --yes @odla-ai/cli@latest doctor
+npx --yes @odla-ai/cli@latest ai models --env dev # exact models this app may select; no admin grant
+npx --yes @odla-ai/cli@latest config diff --json
+npx --yes @odla-ai/cli@latest config plan --json > .odla/config-plan.json
+npx --yes @odla-ai/cli@latest config apply --plan .odla/config-plan.json --json
+npx --yes @odla-ai/cli@latest operations get <operation-id> --json
+npx --yes @odla-ai/cli@latest operations wait <operation-id> --timeout 60 --json
+npx --yes @odla-ai/cli@latest calendar status --env dev
+npx --yes @odla-ai/cli@latest calendar calendars --env dev
+npx --yes @odla-ai/cli@latest calendar connect --env dev --no-open
+npx --yes @odla-ai/cli@latest calendar disconnect --env dev --yes
+npx --yes @odla-ai/cli@latest capabilities --json
+npx --yes @odla-ai/cli@latest code connect --platform https://odla.ai --app-id my-app --env dev --email owner@example.com --no-open
+npx --yes @odla-ai/cli@latest code connect --env prod --once --no-open # bounded enrollment + heartbeat proof
 # install SDKs, write the Worker, and create wrangler.jsonc before secret push
-npx odla-ai provision --dry-run
-npx odla-ai provision --email owner@example.com --write-dev-vars --push-secrets
+npx --yes @odla-ai/cli@latest provision --dry-run
+npx --yes @odla-ai/cli@latest provision --email owner@example.com --write-dev-vars --push-secrets --no-open --wait 600
 # recovery when the selected agent credential has no live app.manage grant
-npx odla-ai provision --request-grant --email owner@example.com --write-dev-vars --push-secrets
-npx odla-ai smoke --env dev
-npx odla-ai agent jobs --env dev --state dead_letter --json
-npx odla-ai agent retry <job-id> --env dev --json
-npx odla-ai discuss watch <topic-id> --jsonl
-npx odla-ai discuss watch <topic-id> --cursor <saved-cursor> --jsonl
-npx odla-ai secrets push --env dev
-npx odla-ai secrets set clerk_webhook_secret --env dev --stdin
-npx odla-ai secrets set-clerk-key --env dev --from-env CLERK_SECRET_KEY
-npx odla-ai security run . --env dev --ack-redacted-source
-npx odla-ai security github connect --env dev # infers owner/name from git origin
-npx odla-ai security plan --env dev
-npx odla-ai security sources --env dev
-npx odla-ai security run --source <source-id> --ref main --env dev --plan-digest <digest-from-security-plan> --ack-redacted-source
-npx odla-ai security status <job-id>
-npx odla-ai security report <job-id>
-npx odla-ai admin ai show --context production --email owner@example.com
-npx odla-ai admin ai models --context production
-npx odla-ai admin ai set security --context production --discovery-provider anthropic --discovery-model claude-opus-4-8 --validation-provider openai --validation-model gpt-5.5 --enabled
-npx odla-ai admin ai credentials --context production
-npx odla-ai admin ai credential set anthropic --context production --from-env ANTHROPIC_API_KEY
-npx odla-ai admin ai usage --context production --app-id my-app --env prod --limit 50
-npx odla-ai admin ai audit --context production --limit 25
-npx odla-ai skill install
-npx odla-ai version
+npx --yes @odla-ai/cli@latest provision --request-grant --email owner@example.com --write-dev-vars --push-secrets --no-open --wait 600
+npx --yes @odla-ai/cli@latest smoke --env dev
+npx --yes @odla-ai/cli@latest agent jobs --env dev --state dead_letter --json
+npx --yes @odla-ai/cli@latest agent retry <job-id> --env dev --json
+npx --yes @odla-ai/cli@latest discuss watch <topic-id> --jsonl
+npx --yes @odla-ai/cli@latest discuss watch <topic-id> --cursor <saved-cursor> --jsonl
+npx --yes @odla-ai/cli@latest secrets push --env dev
+npx --yes @odla-ai/cli@latest secrets set clerk_webhook_secret --env dev --stdin
+npx --yes @odla-ai/cli@latest secrets set-clerk-key --env dev --from-env CLERK_SECRET_KEY
+npx --yes @odla-ai/cli@latest security run . --env dev --ack-redacted-source
+npx --yes @odla-ai/cli@latest security github connect --env dev --no-open # infers owner/name from git origin
+npx --yes @odla-ai/cli@latest security plan --env dev
+npx --yes @odla-ai/cli@latest security sources --env dev
+npx --yes @odla-ai/cli@latest security run --source <source-id> --ref main --env dev --plan-digest <digest-from-security-plan> --ack-redacted-source
+npx --yes @odla-ai/cli@latest security status <job-id>
+npx --yes @odla-ai/cli@latest security report <job-id>
+npx --yes @odla-ai/cli@latest admin ai show --context production --email owner@example.com --no-open
+npx --yes @odla-ai/cli@latest admin ai models --context production
+npx --yes @odla-ai/cli@latest admin ai set security --context production --discovery-provider anthropic --discovery-model claude-opus-4-8 --validation-provider openai --validation-model gpt-5.5 --enabled
+npx --yes @odla-ai/cli@latest admin ai credentials --context production
+npx --yes @odla-ai/cli@latest admin ai credential set anthropic --context production --from-env ANTHROPIC_API_KEY
+npx --yes @odla-ai/cli@latest admin ai usage --context production --app-id my-app --env prod --limit 50
+npx --yes @odla-ai/cli@latest admin ai audit --context production --limit 25
+npx --yes @odla-ai/cli@latest skill install
+npx --yes @odla-ai/cli@latest version
 ```
 
 Before a non-dry provisioning run, the executable verifies two independent
@@ -553,8 +558,8 @@ New configs contain only the `dev` environment. After the development flow is
 healthy, initialize the existing app's live instance without editing the config:
 
 ```sh
-npx @odla-ai/cli provision --live --dry-run
-npx @odla-ai/cli provision --live --yes --push-secrets
+npx --yes @odla-ai/cli@latest provision --live --dry-run
+npx --yes @odla-ai/cli@latest provision --live --yes --push-secrets
 ```
 
 `--live` targets only `prod`, enables every configured service, provisions its
@@ -595,16 +600,22 @@ credential set.
    the exact project id does not exist yet, approval reserves that id for this
    credential instead of failing: the credential may create only that app once,
    and Registry binds its reviewed grant to the new app incarnation.
-   Every real CLI handshake prints exactly one canonical `/studio?code=…` URL
-   and attempts to open it — including from CI, SSH, display-less, scripted,
-   and agent-driven shells. Only `--no-open` suppresses the attempt. Browser
-   launch is best-effort: an agent with browser control must open that exact URL
-   immediately; otherwise it gives the URL to the human verbatim. The device
-   code stays only in the running process. Outside an interactive terminal the
-   approval wait is capped (90 seconds by default; `--wait <seconds>`
-   overrides), and a still-pending handshake exits with code 75. Rerunning
-   always requests and opens a new code; it never resumes an older request from
-   `.odla/`.
+   Every real CLI handshake prints exactly one canonical `/studio?code=…` URL.
+   Interactive humans may use the CLI's best-effort browser launch. Agents use
+   the current published CLI with `--no-open --wait 600`, immediately surface
+   that exact URL and code as a clickable human approval action, and preserve
+   the same foreground process:
+
+   ```bash
+   npx --yes @odla-ai/cli@latest auth login --app <appId> --email <odla-account> --no-open --wait 600
+   ```
+
+   The CLI owns protocol polling. An agent must not call OS `open`, use browser
+   control, curl a handshake endpoint, build a shell wait loop, detach the
+   process, or start a substitute handshake. The device code stays only in the
+   running process. If that process exits 75, the old code cannot be collected;
+   a later invocation requests a new code and never resumes an older request
+   from `.odla/`.
 2. Creates the platform app if needed. For a new id, this consumes the exact-id
    reservation approved in step 1; it is not ambient project-creation authority.
 3. Enables configured services in every configured environment. Calendar
@@ -649,8 +660,8 @@ working sibling runtime.
 Inventory and retire one successful deployment without disturbing any sibling:
 
 ```sh
-npx @odla-ai/cli credentials list --env dev
-npx @odla-ai/cli credentials revoke <receipt-id>
+npx --yes @odla-ai/cli@latest credentials list --env dev
+npx --yes @odla-ai/cli@latest credentials revoke <receipt-id>
 ```
 
 The inventory contains only receipt, target, state, and timestamp metadata.
@@ -661,7 +672,7 @@ Verify a deployment that intentionally keeps db/o11y credentials only on the
 Worker:
 
 ```sh
-npx @odla-ai/cli smoke --env dev --runtime
+npx --yes @odla-ai/cli@latest smoke --env dev --runtime
 ```
 
 Runtime smoke never reads `.odla/credentials.local.json`. It checks Registry
@@ -823,10 +834,10 @@ or SSH `origin`; pass `--repo owner/name` when it cannot. It opens GitHub's
 installation/authorization page and polls that exact odla attempt:
 
 ```bash
-npx odla-ai security github connect --env dev
-npx odla-ai security plan --env dev
-npx odla-ai security sources --env dev
-npx odla-ai security run --source <source-id> --ref main --env dev --plan-digest <digest-from-security-plan> --ack-redacted-source
+npx --yes @odla-ai/cli@latest security github connect --env dev --no-open
+npx --yes @odla-ai/cli@latest security plan --env dev
+npx --yes @odla-ai/cli@latest security sources --env dev
+npx --yes @odla-ai/cli@latest security run --source <source-id> --ref main --env dev --plan-digest <digest-from-security-plan> --ack-redacted-source
 ```
 
 `security plan` is the owner-readable disclosure preflight. It shows the exact
@@ -949,7 +960,7 @@ LLM-usage records. The human owns the device approval, production consent, and
 explicit destructive rotation. Studio is where people view telemetry and
 perform manual recovery, configure System AI, and inspect app/run-attributed
 platform usage; its o11y token control is not the normal setup path.
-Run `npx odla-ai capabilities` for the human-readable contract or add `--json`
+Run `npx --yes @odla-ai/cli@latest capabilities` for the human-readable contract or add `--json`
 when an agent or tool needs to branch on it without scraping prose.
 
 `setup` (and `skill install`) installs one complete offline runbook bundle at

package/REQUIREMENTS.md

@@ -60,6 +60,12 @@ Agnacl, but none should mention or special-case Agnacl.
 - Every real CLI handshake must attempt to open that canonical approval URL,
   including in CI, SSH, display-less, and agent-driven shells. `--no-open` is
   the only production suppression; failures must visibly repeat the manual action.
+- Installed agent instructions must require `--no-open --wait 600`, an explicit
+  clickable human approval checkpoint, and preservation of the same foreground
+  CLI process. They must prohibit OS `open`, browser-control opening, direct
+  handshake polling, shell wait loops, detached execution, and replacement
+  handshakes while that process is alive. Exit 75 must be described as loss of
+  the in-memory device code; a later invocation creates a fresh code.
 - Cached developer tokens must be mode `0600`, gitignored, and reused until
   expiry.
 - Minted developer tokens must have a metadata-only inventory (owner, label,

package/dist/bin.cjs

@@ -207,9 +207,10 @@ function approvalLines(prompt) {
     lines.push(`   No browser was opened (${prompt.browserSkipped}).`);
   }
   lines.push("");
-  lines.push("   AGENTS: use browser control to open the URL above now; do not wait silently.");
-  lines.push("   If browser control is unavailable, give the exact URL to the human verbatim.");
-  lines.push("   You cannot approve it yourself, retry it away, or start a substitute handshake.");
+  lines.push("   AGENTS: immediately give the human this URL as a clickable approval action and repeat the code.");
+  lines.push("   Keep this CLI process running and wait on this same process; the CLI owns protocol polling.");
+  lines.push("   Do not use OS open, browser control, curl, a shell wait loop, detached execution, or a substitute handshake.");
+  lines.push("   You cannot approve it yourself. If this process exits, a later invocation creates a new code.");
   lines.push("");
   return lines;
 }
@@ -5483,18 +5484,29 @@ For work that creates an odla app or adds odla services, read and follow
 \`.agents/skills/odla-o11y-debug/SKILL.md\`.
 
 Track the work in odla's PM as you go. Before project-mutating work, run
-\`npx @odla-ai/cli pm next --app <appId>\`, confirm alignment to an open goal,
+\`npx --yes @odla-ai/cli@latest pm next --app <appId>\`, confirm alignment to an open goal,
 and atomically claim a refined Ready task. Record decisions when you make them
 and file bugs when you notice them. The conventions and the full command set are
 in \`.agents/skills/odla/references/pm.md\`.
 
-Use the human's signed-in odla account email for device authorization; never
-infer it from git config, commit metadata, or GitHub. If authorization is not
-already active, run
-\`npx @odla-ai/cli auth login --app <appId> --email <odla-account>\` and open
-the exact Studio URL it prints. Never file an odla project or product defect in
-GitHub Issues: run \`npx @odla-ai/cli bug report --app <appId> ...\` so the bug
-lands in odla PM with the rest of the project's goals, tasks, and decisions.
+Use the human's known signed-in odla account email for device authorization;
+never infer it from git config, commit metadata, or GitHub. If authorization is
+not already active, run this exact command as one foreground process:
+
+\`npx --yes @odla-ai/cli@latest auth login --app <appId> --email <odla-account> --no-open --wait 600\`
+
+When it prints the approval URL and code, immediately give the human a clickable
+link, name the code they must verify, and tell them to click **Approve**. Keep
+that CLI process running and wait on the same tool process for its result. The
+CLI owns protocol polling: never call the OS \`open\` command, use browser
+control, curl a handshake endpoint, build a shell wait/poll loop, detach the
+process, or start another handshake while it is alive. The device code exists
+only in that process. If it exits 75 before approval, the old code cannot be
+collected; start one fresh foreground command and surface its new URL.
+
+Never file an odla project or product defect in GitHub Issues: run
+\`npx --yes @odla-ai/cli@latest bug report --app <appId> ...\` so the bug lands
+in odla PM with the rest of the project's goals, tasks, and decisions.
 
 The setup runbooks and their references are installed in this repository, pinned
 to this CLI version. Use them as your setup context.
@@ -5506,9 +5518,9 @@ When this repository has an \`appId\`, pass it: app-scoped discovery includes
 that project's instructions plus the shared platform procedures.
 
 \`\`\`
-npx odla-ai runbook ask "<what you are about to do>" --app <appId>
-npx odla-ai runbook list
-npx odla-ai runbook get <slug>
+npx --yes @odla-ai/cli@latest runbook ask "<what you are about to do>" --app <appId>
+npx --yes @odla-ai/cli@latest runbook list
+npx --yes @odla-ai/cli@latest runbook get <slug>
 \`\`\`
 
 Never scrape odla.ai HTML for any of this. The CLI reads the same content
@@ -10817,8 +10829,8 @@ Usage:
   odla-ai runbook revert <slug> --version <n> [--app <id>]
   odla-ai runbook rm <slug> [--app <id>]
   odla-ai capabilities [--json]
-  odla-ai code connect [--env dev|prod] [--email <odla-account>] [--engine auto|container|podman|docker] [--slots <1-64>] [--once]
-  odla-ai admin ai show [--context <name>] [--platform https://odla.ai] [--email <odla-account>] [--json]
+  odla-ai code connect [--env dev|prod] [--email <odla-account>] [--no-open] [--engine auto|container|podman|docker] [--slots <1-64>] [--once]
+  odla-ai admin ai show [--context <name>] [--platform https://odla.ai] [--email <odla-account>] [--no-open] [--json]
   odla-ai admin ai models [--context <name>] [--provider <id>] [--json]
   odla-ai admin ai set <purpose> [--context <name>] [--provider <id>] [--model <id>] [--enabled|--no-enabled]
     [--max-input-bytes <n>] [--max-output-tokens <n>] [--max-calls-per-run <n>] [--json]
@@ -10837,7 +10849,7 @@ Usage:
   odla-ai security report <job-id> [--json]
   odla-ai security run [target] --ack-redacted-source [--env dev] [--profile odla] [--fail-on high]
   odla-ai security run [target] --self --ack-redacted-source
-  odla-ai provision [--live] [--config odla.config.mjs] [--email <odla-account>] [--request-grant] [--wait <seconds>] [--dry-run] [--push-secrets] [--rotate-o11y-token] [--write-dev-vars[=path]] [--yes]
+  odla-ai provision [--live] [--config odla.config.mjs] [--email <odla-account>] [--request-grant] [--no-open] [--wait <seconds>] [--dry-run] [--push-secrets] [--rotate-o11y-token] [--write-dev-vars[=path]] [--yes]
   odla-ai credentials list [--config odla.config.mjs] [--env dev] [--all] [--json]
   odla-ai credentials revoke <receipt-id> [--config odla.config.mjs] [--json]
   odla-ai smoke [--config odla.config.mjs] [--env dev] [--runtime] [--email <odla-account>] [--no-open]
@@ -10854,7 +10866,7 @@ function printHelp(output = console) {
   output.log(`odla-ai
 ${USAGE_SECTION}
 Commands:
-  auth         Start a fresh, exact-project agent authorization in the browser.
+  auth         Start a fresh, exact-project agent authorization for human review.
                The email is the signed-in odla account, never git or GitHub
                identity. The approval screen confirms the agent name first.
   agent        Inspect durable agent wakeups and explicitly requeue a
@@ -10984,23 +10996,25 @@ Safety:
   the metadata file. Flags and specific ODLA_* scope variables beat a selected
   context, which beats project config. There is no ambient current context.
   "context show" reports only provenance and cache state and never authenticates.
-  Every real CLI handshake prints one canonical /studio?code= approval URL and
-  attempts to open it \u2014 including in CI, SSH, display-less, and agent-driven
-  shells. Only --no-open suppresses the attempt. Browser launch is best-effort:
-  agents with browser control must open that exact URL immediately; otherwise
-  they must give it to the human verbatim. A device code remains only in the
-  running process. Outside an interactive terminal the wait is capped (90s by
-  default, --wait <seconds> to change); a still-pending handshake then exits
-  with code 75. Rerunning always requests and opens a new code; older clients'
-  persisted pending state is discarded.
+  Every real CLI handshake prints one canonical /studio?code= approval URL.
+  Interactive humans may let the CLI attempt its best-effort browser launch.
+  Agent-driven commands must pass --no-open --wait 600, immediately surface the
+  exact URL and code as a clickable human approval action, and keep that CLI
+  process alive. Wait only on that same process: the CLI owns protocol polling.
+  Do not call OS open, use browser control, curl handshake endpoints, build a
+  shell wait loop, detach the command, or start a substitute handshake. The
+  device code remains only in the running process. If the process exits 75, its
+  old code cannot be collected; a later invocation requests a new code. Older
+  clients' persisted pending state is discarded.
   A fresh device handshake requires --email <odla-account> or ODLA_USER_EMAIL.
   The email is a non-secret identity hint: never provide a password or session
   token. It is the email shown by the signed-in odla account \u2014 never infer it
   from git config, a commit author, or GitHub. The matching account must already exist, be signed in, explicitly
   review the exact code, and finish any current request before claiming another.
-  Use "auth login --app <id> --email <odla-account>" when an outside agent needs
-  a deliberate fresh request; it ignores cached credentials and opens the same
-  focused authorization sequence used by every first-time command.
+  Use "auth login --app <id> --email <odla-account> --no-open --wait 600" when
+  an outside agent needs a deliberate fresh request; it ignores cached
+  credentials and uses the same focused authorization sequence as every
+  first-time command.
   If provision reports that the current agent principal has no live app.manage
   grant, run it once with --request-grant. That flag ignores ODLA_DEV_TOKEN and
   the local cache, prints and opens a fresh exact-project owner-review URL, then
@@ -14660,7 +14674,7 @@ var init_runbook_impact = __esm({
 
 // src/runbook-lint.ts
 function invocationsIn(body) {
-  const re = /(`|npx[^\S\n]+)?(?:@odla-ai\/cli(?:@[\w.-]+)?|odla-ai)((?:[^\S\n]+[a-z][\w-]*)+)/g;
+  const re = /(`|npx[^\S\n]+(?:--yes[^\S\n]+)?)?(?:@odla-ai\/cli(?:@[\w.-]+)?|odla-ai)((?:[^\S\n]+[a-z][\w-]*)+)/g;
   const found = [];
   for (const match of body.matchAll(re)) {
     if (!match[1]) continue;
@@ -14894,6 +14908,7 @@ async function buildContext3(parsed, deps, action2) {
     };
   }
   const needsCapability = WRITES2.has(action2) && !dryRun && appId === PLATFORM_SCOPE && !stringOpt(parsed.options.token);
+  const open = parsed.options.open === false ? false : parsed.options.open === true ? true : void 0;
   const token = needsCapability ? await getScopedPlatformToken({
     platform: cfg.platformUrl,
     scope: "platform:runbook:write",
@@ -14901,6 +14916,7 @@ async function buildContext3(parsed, deps, action2) {
     label: `odla CLI (runbook ${action2})`,
     fetch: doFetch,
     stdout: out,
+    open,
     openApprovalUrl: deps.openUrl,
     // A project, named context, or the global operator context owns the
     // exact-scope cache; it never follows an arbitrary shell directory.
@@ -14912,11 +14928,7 @@ async function buildContext3(parsed, deps, action2) {
       configPath: cfg.configPath,
       token: stringOpt(parsed.options.token),
       email: stringOpt(parsed.options.email),
-      // Let the normal browser policy decide (it already suppresses tests,
-      // CI and SSH). Hardcoding `false` meant a first-time handshake printed
-      // a link and opened nothing — the one moment a browser is the whole
-      // point.
-      open: void 0
+      open
     },
     doFetch,
     out
@@ -15064,7 +15076,8 @@ var init_runbook_command = __esm({
       "base",
       "requires",
       "platform",
-      "context"
+      "context",
+      "open"
     ];
     WRITES2 = /* @__PURE__ */ new Set(["new", "edit", "publish", "archive", "visibility", "revert", "rm", "import"]);
   }