@odla-ai/cli 0.38.3 → 0.40.0

package/dist/index.js

@@ -56,7 +56,7 @@ import {
   startHostedSecurityJob,
   surfacePaths,
   validateInvocation
-} from "./chunk-WJAN5CZ2.js";
+} from "./chunk-2IHE5U3M.js";
 import {
   exitCodeFor,
   redactSecrets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/cli",
-  "version": "0.38.3",
+  "version": "0.40.0",
   "description": "Agent-operable CLI for odla provisioning, calendar consent and connection lifecycle, System AI administration, Worker secrets, security jobs, and smoke checks.",
   "license": "MIT",
   "homepage": "https://odla.ai/docs/packages/cli",
@@ -61,7 +61,7 @@
     "@odla-ai/ai": "0.15.0",
     "@odla-ai/apps": "0.12.0",
     "@odla-ai/brand": "0.6.0",
-    "@odla-ai/db": "0.11.0",
+    "@odla-ai/db": "0.12.0",
     "@odla-ai/security": "0.3.3"
   },
   "devDependencies": {

package/skills/odla/SKILL.md

@@ -36,9 +36,12 @@ State which path you're taking and what you'll build in one line; get a nod.
 
 ## Non-negotiable rules
 
-1. **Never print, paste, or commit a secret.** Never `cat` `.dev.vars`,
-   `.odla/credentials.local.json`, or `.odla/dev-token.json` — use `ls -l` to
-   confirm they exist (and are `0600`). The only value a human ever pastes is a
+1. **Never print, paste, or commit a secret.** Never `cat` `.dev.vars` or
+   anything under `~/.odla` (`device.json`, `session.json`,
+   `apps/<appId>/credentials.json`, `admin-token.local.json`) — use `ls -l` to
+   confirm they exist (and are `0600`). Credentials live per machine, under
+   `~/.odla`, not per checkout; a repository copy from an older CLI is moved
+   there automatically on first run. The only value a human ever pastes is a
    Clerk **publishable** key (`pk_…`) — public by design.
    A fresh odla device request also needs the existing account email via
    `--email` or `ODLA_USER_EMAIL`; email is a non-secret identifier. Never ask
@@ -49,9 +52,9 @@ State which path you're taking and what you'll build in one line; get a nod.
    registry matches the exact string. An address that is not a registered
    account does NOT error: it mints an indistinguishable decoy, so the CLI
    prints a normal approval URL that can never be approved by anyone. Ask the
-   human, or reuse the same-audience account identity already recorded with a
-   collected developer token. Current clients never persist pending device
-   codes in `.odla/handshake.local.json`.
+   human — once. The CLI records the account an approval actually succeeded for
+   in `~/.odla/identity.json`, so later commands on this machine need no
+   `--email` at all. Current clients never persist pending device codes.
 2. **Sandbox before live.** Every app has two databases on production odla.ai:
    a sandbox (env `dev`, tenant `<appId>--dev`) and a live one (env `prod`,
    tenant `<appId>`). "prod" names the app's live DATABASE, never a different
@@ -71,10 +74,43 @@ State which path you're taking and what you'll build in one line; get a nod.
    platform/Google consent URL returned by odla; booking runs server-side
    through the SDK with the app's existing key, never from a browser.
 
-## Agent handshake protocol
+## Enrol the machine once. Then stop asking.
 
-Use the current published CLI and suppress browser auto-launch. Start the exact
-authorization as one foreground tool process:
+**This is step zero, and it is one command.** Run it before anything else that
+touches odla:
+
+```bash
+npx --yes @odla-ai/cli@latest device enroll --no-open --wait 600
+```
+
+One browser approval, and no flags to remember. After it, every worktree on
+this machine mints its own short-lived credentials with nobody's attention, for
+every app the approver owns — including apps created later — carrying every
+capability that approval was allowed to carry. Narrowing is deliberate:
+`--app <id>` or `--capability <c>`, and the CLI says what that gave up. The deadline is a **gap, not a clock**: each use rolls it
+forward, so continuous work never interrupts anyone.
+
+A platform administrator can do the same across all of odla:
+
+```bash
+npx --yes @odla-ai/cli@latest device enroll --platform-wide --device-ttl 6w --no-open --wait 600
+```
+
+Check what this machine already holds before asking anyone for anything:
+
+```bash
+npx --yes @odla-ai/cli@latest whoami        # what it holds, and when it lapses
+```
+
+Do **not** ask for capabilities one at a time, and do not re-enrol per worktree.
+Both were the old shape and both mean interrupting a human who is usually not
+there. If a command still starts a handshake, the CLI prints why and prints the
+enrollment line that ends it — run that instead of approving repeatedly.
+
+## The approval itself
+
+Whichever command needs it, the handshake protocol is the same. Start it as one
+foreground tool process with browser auto-launch suppressed:
 
 ```bash
 npx --yes @odla-ai/cli@latest auth login --app <appId> --email <odla-account> --no-open --wait 600
@@ -88,8 +124,12 @@ the OS `open` command, use browser control, curl a handshake endpoint, create a
 shell polling/wait loop, detach the process, or start a substitute handshake.
 The device code exists only in the running CLI. If it exits 75, the old request
 cannot be collected; start one fresh foreground invocation and surface only its
-new URL. Apply the same `--no-open --wait 600` flags when another command, such
-as first provision, must request a different reviewed capability.
+new URL.
+
+Enrollment is the only human decision the CLI can obtain. Revoking a machine,
+purging an app, transferring ownership, and rotating credentials still need a
+signed-in human in Studio — no machine credential can do them, however wide its
+approval was.
 
 ## Tooling sources
 

package/skills/odla/references/agent-identity.md

@@ -1,132 +1,115 @@
-# Reconnect an agent across worktrees and projects
+# Keep one identity across worktrees, projects, and days
 
-Use this procedure when an agent must keep the same attributable identity while
-its short-lived device credential expires, or when it operates outside the
-checkout that first obtained the credential.
+Use this when an agent must keep the same attributable identity while working in
+more than one checkout, or across the expiry of a short-lived credential.
 
-## Preconditions
+## The short version
 
-- The human approving the request owns or co-owns every selected project.
-- The handshake contains one deliberate handle suffix, such as `customer-app`
-  or `release-reviewer`. The Registry places it under the approving human's
-  verified namespace (for example, `@cory/customer-app`). The CLI derives this
-  suffix deterministically from the exact project; SDK callers may explicitly
-  request a different stable `agentHandle` for a cross-project agent.
-- No token, credential file, or browser session is copied between worktrees,
-  machines, people, or chat messages.
+Enrol the machine once. Nothing else on this page is required for the ordinary
+case:
 
-## 1. Save non-secret context outside the checkout
+```cmd
+npx --yes @odla-ai/cli@latest device enroll --no-open --wait 600
+```
+
+One human approval binds THIS machine. From then on every worktree on it mints
+its own short-lived sessions with no browser, for every app the approver owns —
+including apps created afterwards — carrying every capability that approval was
+allowed to carry. The credential's deadline measures **silence**: each use rolls
+it forward, so an agent that keeps working never has to interrupt anyone.
 
 ```cmd
-npx --yes @odla-ai/cli@latest context save delivery --platform https://odla.ai --app <appId> --env prod
-npx --yes @odla-ai/cli@latest context show --context delivery --json
+npx --yes @odla-ai/cli@latest whoami        # what this machine holds, and when it lapses
+npx --yes @odla-ai/cli@latest device list   # every machine you have enrolled
 ```
 
-The context stores only platform/app/environment metadata. Its private token
-cache lives under `~/.odla/profiles/delivery/`, independently of any repository
-or linked worktree. Select it explicitly with `--context delivery` or
-`ODLA_CONTEXT=delivery`; there is no ambient current context.
+## Where state lives
 
-## 2. Establish the durable principal
+Per machine, under `~/.odla`, never per checkout:
 
-Run the intended command with the named context. If no valid cached credential
-exists, the CLI starts the normal email-bound device handshake and prints the
-exact Studio approval URL.
+| file | what it is |
+|---|---|
+| `device.json` | the durable enrollment secret. Never printed, never copied |
+| `session.json` | the short-lived session minted from it, reused until it lapses |
+| `identity.json` | the odla account an approval succeeded for — so no command has to ask again |
+| `apps/<appId>/dev-token.json` | that app's cached developer credential |
+| `apps/<appId>/credentials.json` | that app's local service credentials |
+| `admin-token.local.json` | scoped capability grants, one file for the machine |
+| `pm-context.json` | the PM project selected by `pm project use` |
+| `profiles/<name>/` | the same, isolated per named operator context |
 
-```cmd
-npx --yes @odla-ai/cli@latest whoami --context delivery --email <account-email> --json
-```
+A repository `.odla/` cache written by an older CLI is moved here on first run
+and the old copy removed; the CLI says so on stderr. `.dev.vars` stays in the
+checkout — it is a Worker's file, not a credential of yours.
+
+`ODLA_HOME` relocates the whole store. The per-file `ODLA_DEVICE_CREDENTIAL`,
+`ODLA_DEV_TOKEN_FILE`, `ODLA_ADMIN_TOKEN_FILE`, and `ODLA_CONTEXT_FILE`
+overrides still win where they are read.
+
+## Preconditions for the approval
+
+- The human approving owns or co-owns everything the request covers. `--all-apps`
+  is not platform-wide authority: the registry resolves it against that human's
+  live owned apps at every request, so an app transferred away stops being
+  reachable and one created tomorrow is already covered.
+- `--email` is the signed-in **odla account**, never git or GitHub identity. An
+  address that is not a registered account does not error — it mints an
+  indistinguishable decoy whose approval URL nobody can approve. Ask the human,
+  or let `~/.odla/identity.json` answer.
+- No token, credential file, or browser session is ever copied between
+  worktrees, machines, people, or chat messages.
 
-In Studio, review the exact code, requested handle, projects, and capabilities.
-The request is immutable: approval cannot edit its identity or grants. The
-handle—not the request label or local context name—is the durable agent identity
-key. Record the full verified handle in the agent handoff; never record the
-token. A normal CLI handshake derives the same handle from the configured
-project in every checkout and worktree.
+## Named contexts, for operators outside a checkout
 
-After approval and collection, verify the selected identity and context:
+A named context isolates scope metadata and credential caches — useful when one
+machine acts for more than one platform or account, not for ordinary worktrees:
 
 ```cmd
+npx --yes @odla-ai/cli@latest context save delivery --platform https://odla.ai --app <appId> --env prod
 npx --yes @odla-ai/cli@latest whoami --context delivery --json
-npx --yes @odla-ai/cli@latest pm next --context delivery --json
 ```
 
-If the agent request omits the handle, Registry deliberately creates a new
-principal for that handshake. An untrusted request label can therefore never
-select an existing agent.
-
-## 3. Reconnect after expiry
-
-Re-run the command with the same named context and project. The cache keeps the
-approved account identifier and starts a fresh handshake when the token is
-expired. During human review:
-
-1. verify the immutable request contains the expected existing handle suffix;
-2. verify every exact requested project should receive access now;
-3. review optional capabilities again; and
-4. approve the request unchanged, or decline it with corrective feedback.
-
-Registry binds the new credential to the existing managed-agent principal and
-stores the human's reviewed exact-project set without activating it yet. The
-existing principal's authoritative name and purpose are retained; reusing its
-handle is not a profile-edit operation. Approval alone leaves the current
-credential and its project grants usable. When the replacement plaintext is
-successfully collected, Registry atomically clears that plaintext, retires
-older collected ordinary-handshake credentials, and replaces the principal's
-manager-issued project grants with the reviewed set. Newly selected projects
-are unavailable before collection, and omitted projects are revoked during the
-switch. If collection never succeeds, the working credential and grants are not
-stranded by the approval.
-
-Verify `whoami` reports the same principal/handle before resuming work. Ordinary
-reviewed project access includes `pm.execute` but not `pm.plan`: re-read `pm
-next` and claim the current Ready task revision, while leaving Ready approval to
-a human owner or explicit planner. Identity continuity alone does not preserve
-a stale claim or imply authority outside the newly reviewed grants.
-
-## 4. Review remaining credentials
-
-Successful collection automatically retires the preceding collected ordinary
-handshake credential for that principal. Verify the old row in Studio's
-agent-credential inventory has a `system:handshake-reconnect:<handshake-id>`
-revocation reason. Do not delete a local cache as a substitute for this
-server-side evidence.
-
-The rotation set deliberately excludes manually minted credentials and
-separately scoped handshakes: those may represent another deliberate runtime,
-not a stale copy of this context. Review and revoke them explicitly when they
-are no longer intended.
-
-Project grants are still time-bounded. Collection makes the newly reviewed
-selection authoritative for the principal: selected projects receive new
-revisions and every live manager-issued project omitted from that selection is
-revoked. There is not yet a non-interactive `auth rotate` command or OS
-credential-store integration. The named context plus stable handle solves
-worktree/project portability and principal continuity, but it is not ambient or
-permanent authority.
+It stores platform/app/environment metadata only, never credentials, under
+`~/.odla/profiles/delivery/`. Select it explicitly with `--context delivery` or
+`ODLA_CONTEXT`; there is no ambient current context.
+
+## When a human is asked again
+
+Three cases, and only three:
+
+1. **The machine has never been enrolled.** Run the enrollment above.
+2. **The machine lapsed.** It went unused for longer than its window. This is
+   the one deliberate interruption in the design — the platform's guaranteed
+   moment to tell the human what changed since they last looked. Re-enrol.
+3. **The command needs something the approval did not carry.** A platform scope
+   on an owner's enrollment, most often. The CLI says which scope and prints the
+   enrollment line that would carry it; an administrator's approval is required
+   for `--platform-wide`.
+
+Anything else asking repeatedly is a defect — file it with `odla-ai bug report`
+rather than approving on a loop.
+
+## What enrollment still cannot do
+
+Revoking a machine, permanently deleting an app, transferring ownership, and
+rotating credentials require a signed-in human in Studio. No machine credential
+performs them however wide its approval was, and no flag widens that.
+
+Ordinary reviewed access includes `pm.execute` but not `pm.plan`: re-read `pm
+next` and claim the current Ready task revision, leaving Ready approval to a
+human owner or explicit planner.
 
 ## Recovery and audit evidence
 
-- `handshake_pending`: approve the existing code and rerun the same command; do
-  not create a substitute request.
-- Wrong handle requested: decline it and correct the project/SDK request before
-  starting a fresh handshake. If already approved, revoke the new credential in
-  Studio; do not rename or merge principals by editing local metadata.
-- Missing project on first provision: approve the exact id. Collection records
-  a one-time reservation plus the explicit `app.manage` provision capability;
-  the credential creates only that app, Registry binds the grant to its new
-  incarnation, and provision may continue through non-lifecycle configuration.
-  Never pre-create a substitute or widen to all projects. Ownership and
-  lifecycle operations still require the direct human session.
-- Approval returns 404: treat it as a Registry routing regression, not a missing
-  project outcome. Preserve the code and pending state, report the incident,
-  and retry the same request after Registry is healthy.
-- Project ownership/lifecycle changed after approval: collection expires the
-  unusable replacement while preserving the current credential and grant set.
-  Restore the intended project state, then start and review a fresh handshake.
-- Lost local cache: save/select the same non-secret context, complete a new
-  handshake with the same handle, verify `whoami`, then revoke the lost
-  credential from Studio.
-
-Audit evidence is the stable principal id/handle, the new credential id, and the
-monotonic project-grant revision shown by Registry—not possession of a token.
+- **`handshake_pending`**: approve the existing code and rerun the same command;
+  never create a substitute request.
+- **Exit 75**: the wait cap elapsed with the handshake still approvable. Rerun
+  it; the old code cannot be collected and a new one is issued.
+- **A revoked or lapsed machine**: `whoami` says so. Re-enrol; do not delete a
+  local file as a substitute for revoking server-side.
+- **Lost `~/.odla`**: re-enrol, verify `whoami`, then revoke the old machine in
+  Studio — the credential it holds is still live until you do.
+
+Audit evidence is the stable principal id and handle, the device id shown by
+`device list`, and the grant revision Registry reports — never possession of a
+token.