octwin-cli 0.8.7 → 0.8.8

package/CHANGELOG.md

@@ -5,6 +5,43 @@ Format: [Keep a Changelog](https://keepachangelog.com/) — newest first, bucket
 **Added · Changed · Deprecated · Removed · Fixed · Security**. The platform-wide view lives in the
 repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut that ships with the package.
 
+## [0.8.8] - 2026-09-06
+
+### Added
+- **`octwin login` can sign you in through a browser — no token is pasted anywhere.** Run it with
+  no `--token` and it prints an approval link:
+
+  ```
+    Open this link to approve:  https://app.octwin.ai/cli-login?code=WDJB-MJHT
+    Code shown on that page:    WDJB-MJHT
+  ```
+
+  A workspace admin opens it, checks which machine is asking, and clicks Approve; the CLI collects a
+  30-day token by itself and saves it exactly where `--token` would have. `octwin login --token oct_…`
+  is unchanged, and CI should still skip login entirely and set `PACK_PLATFORM_URL` + `PACK_TOKEN`.
+
+  **The wait is bounded and resumable, because this CLI is mostly driven by an agent.** An agent's
+  shell call is killed after about two minutes, and a wait that outlives its caller is worse than a
+  short one — the process dies mid-handshake and the code the human is still typing belongs to
+  nothing. So `login` waits 90 seconds, then exits **75** (`EX_TEMPFAIL`) with the handshake kept in
+  `~/.octwin/pending-login.json`; running it again resumes the **same** code, which the platform
+  keeps alive for ten minutes. `0` still means signed in and `1` still means failed, so an agent
+  branches on the exit code instead of parsing prose. `--wait <seconds>` overrides the 90 (`--wait 0`
+  prints the code and returns at once), and `--json` prints the same facts as an object.
+
+  **Approve only a link you opened because you ran the command.** The link carries the code
+  (RFC 8628 `verification_uri_complete`), so the click *is* the consent: approving a link somebody
+  sent you would connect their machine to your workspace. The console says so on the page. The code
+  is printed here too, and shown there, so you can always tell one request from another.
+
+  The pending handshake gets its own file rather than a new key in `credentials.json`: every value
+  in that file is a token, and its one reserved key (`default_url`) is collision-free only because a
+  platform url always contains `://`. A second value shape there would end that argument.
+
+- **A 401 now points at `octwin login`, not at the console.** With a 30-day browser token, renewing is
+  one command; the old hint sent people to mint a replacement by hand. Mint a token yourself if you
+  want a different lifetime — the console offers 30 / 90 days / a year / never.
+
 ## [0.8.7] - 2026-09-06
 
 ### Added

package/README.md

@@ -46,9 +46,10 @@ git init && git add -A && git commit -m "init pack"
 # 2. Author it — edit manifest.yaml, flows/tools/main.flow.yaml (+ its locale),
 #    and prompts/identity.md. Everything is pure YAML.
 
-# 3. Point it at your platform — one command, no config file
-#    (Octwin console → your workspace → API tokens → Generate)
-octwin login --url https://your-octwin.example.com --token oct_…
+# 3. Point it at your platform — one command, no config file.
+#    It prints a link; approve it in the console and it saves a 30-day token
+#    by itself. (Already have a token? add --token oct_…)
+octwin login --url https://your-octwin.example.com
 
 # 4. Validate → deploy → confirm it's live
 octwin validate
@@ -65,7 +66,7 @@ octwin status               # "✓ live and current" once it's warm
 | --- | --- |
 | `octwin init <dir>` | Scaffold a new pure-YAML pack into `<dir>` (writes a starter `manifest.yaml`, flow, prompt, `.gitignore` and `README.md` — pack content only). Options: `--id`, `--description`, `--display-name`. |
 | `octwin validate` | Check the pack locally (structure + pure-YAML rules). `--remote` runs **the same validation the platform runs to load your pack** — every declaration file (`xrm.yaml`, `scheduling.yaml`, `worklist.yaml`, `roles.yaml`, `automation.yaml`, `integrations.yaml`, `surveys.yaml`, `taps.yaml`, `commands.yaml`, `journeys/`, `messages.<lang>.yaml`), the cross-file checks between them, and the **flow lint** — conventions the schema can't express, like an `assign:` whose value is a quoted literal or a `$t()` key with no namespace. These need template expansion and the platform's own schemas, which only the server has, so a local ✓ does not cover them. A `--remote` ✓ and a successful deploy are now the same answer by construction, not by convention. |
-| `octwin login` | Save a deploy token for a platform URL **and make that URL the default target** (both stored in `~/.octwin/credentials.json`). `--url`, `--token`. |
+| `octwin login` | Sign in to a platform URL **and make it the default target** (both stored in `~/.octwin/credentials.json`). With no `--token` it prints a link to approve in the console, then collects a 30-day token itself — nothing is pasted. The wait is bounded and resumable: run it again to keep waiting on the same request. `--url`, `--token`, `--wait <seconds>`, `--json`. |
 | `octwin whoami` | Verify the saved/passed token is valid for a tenant. `--url`, `--tenant`. |
 | `octwin deploy` | Upload + install the pack onto your tenant's project. `--seed` also runs the pack's demo seed. Says **nothing** about the public marketplace unless asked: `--request-listing` submits the pack for operator review (needs `listing.public: true` in the manifest too), `--withdraw-listing` retracts. Reports the **listing verdict** whenever one exists. |
 | `octwin status` | Report what the platform has live for this pack — installed version, the **content sha** the instance loaded vs. the one the catalog holds (a redeploy of the *same* version changes it), its flows, and whether it is live on the public marketplace. |
@@ -164,10 +165,12 @@ Three things worth knowing when you read the output:
 holds pack content and nothing else, so the same repo deploys from any machine:
 
 ```bash
-octwin login --url https://your-octwin.example.com --token oct_…
+octwin login --url https://your-octwin.example.com              # approve in a browser
+octwin login --url https://your-octwin.example.com --token oct_…  # or bring your own token
 ```
 
-That stores the token *and* makes the URL your default target, in `~/.octwin/credentials.json`:
+Either way it stores the token *and* makes the URL your default target, in
+`~/.octwin/credentials.json`:
 
 ```jsonc
 {
@@ -176,6 +179,9 @@ That stores the token *and* makes the URL your default target, in `~/.octwin/cre
 }
 ```
 
+A browser sign-in in progress is held separately, in `~/.octwin/pending-login.json`, and is deleted
+as soon as the token arrives — the credentials file holds tokens only.
+
 Tenant and project need no setting at all — the **token carries its own tenant**, plus an optional
 project pin. `--tenant` / `--project` exist only as overrides (a multi-workspace human, or an
 unpinned token that must name a project).
@@ -195,9 +201,24 @@ variables (add `PACK_PROJECT` only if the token isn't pinned).
 ## Authentication
 
 You authenticate with a tenant-scoped **deploy token** (prefixed `oct_…`) — not a password and not
-an operator token. Generate it in the Octwin console (**your workspace → API tokens → Generate**).
-It is **least-privilege** (scope `pack:deploy`): it can deploy packs to your tenant but cannot
-manage members, billing, or other tenants, and it is revocable at any time.
+an operator token. It is **least-privilege** (scope `pack:deploy`): it can deploy packs to your
+tenant but cannot manage members, billing, or other tenants, and it is revocable at any time. A
+token can never mint another token, which is why approving a browser sign-in needs a *human*
+workspace admin.
+
+Two ways to get one:
+
+- **`octwin login` with no `--token`** prints an approval link. A workspace admin opens it, sees
+  which machine is asking, and clicks Approve; the CLI collects a 30-day token by polling. Nothing is
+  copied by hand, so no live credential passes through a chat window or an email. The wait is
+  bounded (90s) and **resumable** — run the command again to keep waiting on the same request, which
+  lives ten minutes. Exit code `75` means *still waiting*; `0` means signed in.
+  **Approve only a link you opened because you ran the command.** The link carries the code, so
+  clicking Approve on a link someone sent you would connect *their* machine to your workspace. The
+  code is printed too, and the page shows it, so you can always tell one request from another.
+- **Generate one yourself** in the Octwin console (**your workspace → API tokens → Generate**) and
+  pass it with `--token`. This is the way to pick narrower scopes or a different expiry, and the
+  way to get a token for CI.
 
 Add the optional **`media:generate`** scope to let a `--seed` deploy AI-generate seed images
 (for a demo record field like `photo: "generate:<prompt>"`); without it, such fields are seeded as

package/dist/index.js

@@ -10,7 +10,7 @@
  *   octwin --version | -v           # print the CLI version (+ any upgrade notice)
  *   octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
  *   octwin validate [--dir .] [--remote] [--require-kb]   # --remote → the platform's FULL schema check + lint, all errors at once
- *   octwin login   --url <platformUrl> --token oct_…
+ *   octwin login   --url <platformUrl> [--token oct_…]   # no token → approve in a browser
  *   octwin whoami  [--url <url>] [--tenant <slug>]
  *   octwin projects [--archived]    # the --project slugs this token can name
  *   octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
@@ -60,7 +60,7 @@
  */
 import { readFileSync, writeFileSync, writeSync, mkdirSync, existsSync, readdirSync, statSync, cpSync, rmSync } from 'node:fs';
 import { join, resolve, dirname, basename } from 'node:path';
-import { homedir } from 'node:os';
+import { homedir, hostname, platform } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 import { applyRenames } from './lib/rename.js';
@@ -79,6 +79,7 @@ import { classifyPackPath, isSkippedDir } from './lib/pack-source.js';
 import { readPage, morePageHint } from './lib/page.js';
 import { kbOneLiner, buildKbIndexMarkdown, buildKbOutlineMarkdown, } from './lib/kb-index.js';
 import { buildSymbols, linkExplainers, renderSymbolsMarkdown } from './lib/kb-symbols.js';
+import { readPending, writePending, clearPending, isPendingExpired, secondsLeft, interpretPoll, clientLabel, EXIT_STILL_PENDING, } from './lib/device-login.js';
 // The in-package starter template ships alongside `dist/` and `src/` (both one
 // level under the package root), so `../templates/starter` resolves for the
 // built CLI and `tsx` dev alike.
@@ -181,7 +182,7 @@ async function fetchOrDie(url, init, what) {
  *  unauthenticated), so say so instead of sending the author on a re-login hunt. */
 function authFailureHint(status, url) {
     return status === 401
-        ? `the token was rejected — invalid / expired / revoked. If it JUST worked, this can be a one-off platform hiccup: retry once before re-logging in (octwin login --url ${url} --token oct_…)`
+        ? `the token was rejected — invalid / expired / revoked. If it JUST worked, this can be a one-off platform hiccup: retry once, then sign in again with \`octwin login --url ${url}\` (a browser-issued token lasts 30 days, so renewal is that one command)`
         : `the token is valid but not authorized here (missing scope, plan feature, or role)`;
 }
 /**
@@ -1224,10 +1225,34 @@ async function cmdValidate(flags) {
     }
     exitNow(1);
 }
+/**
+ * Two ways in, one saved result.
+ *
+ *   octwin login --url <u> --token oct_…   the token you minted in the console
+ *   octwin login --url <u>                 approve it in a browser instead
+ *
+ * The token form is unchanged. The browser form is the one an agent can drive:
+ * see `cmdLoginBrowser`.
+ */
 async function cmdLogin(flags) {
-    const rawUrl = flags.url ?? process.env.PACK_PLATFORM_URL ?? die('usage: octwin login --url <platformUrl> --token <t>');
+    const rawUrl = flags.url ?? process.env.PACK_PLATFORM_URL ?? savedDefaultUrl();
+    if (!rawUrl) {
+        die('usage: octwin login --url <platformUrl>   (add --token oct_… to use a token from the console)');
+    }
     const url = rawUrl.replace(/\/$/, '');
-    const token = flags.token ?? process.env.PACK_TOKEN ?? die('missing --token');
+    const token = flags.token ?? process.env.PACK_TOKEN;
+    if (token)
+        return saveLogin(url, token);
+    return cmdLoginBrowser(url, flags);
+}
+/**
+ * Persist a token as the default deploy target, then say what it reaches.
+ *
+ * Shared by both login paths deliberately: a browser sign-in and a pasted token
+ * must produce the same saved state and the same confirmation, or one of them
+ * becomes the odd one people distrust.
+ */
+async function saveLogin(url, token) {
     const creds = readCreds();
     creds[url] = token;
     creds[DEFAULT_URL_KEY] = url; // login sets the default deploy target
@@ -1249,6 +1274,150 @@ async function cmdLogin(flags) {
     }
     catch { /* platform unreachable — the token is saved regardless */ }
 }
+/** `~/.octwin/pending-login.json` — a handshake in flight, per platform url. */
+function pendingLoginPath() { return join(homedir(), '.octwin', 'pending-login.json'); }
+/**
+ * The gap between polls.
+ *
+ * **Deliberately NOT `.unref()`ed.** The timer this returns is the only pending work
+ * during a wait, so an unref'd one lets Node decide the event loop is empty and exit
+ * mid-handshake — silently, with code 0, printing neither the ✓ nor the "not approved
+ * yet" line. Measured 2026-09-06: the first resume happened to win the race and every
+ * later one exited quietly. `unref` belongs on a timer RACING something else (as in
+ * `SseFrameReader`, where a pending read holds the loop open); here it is the thing
+ * being waited for.
+ */
+function sleep(ms) {
+    return new Promise(res => { setTimeout(res, ms); });
+}
+/**
+ * How long one `octwin login` waits before handing the terminal back.
+ *
+ * 90 seconds, because THE CLI IS MOSTLY DRIVEN BY AN AGENT and an agent's shell
+ * call is killed around two minutes. A wait that outlives its caller is worse than
+ * a short one: the process dies mid-handshake and the code the human is still
+ * typing belongs to nothing. So the wait is bounded, the handshake is written to
+ * disk, and running the command again resumes the SAME code — which the platform
+ * keeps alive for its full ten minutes.
+ */
+const LOGIN_WAIT_SECONDS = 90;
+async function cmdLoginBrowser(url, flags) {
+    const asJson = flags.json === true;
+    const path = pendingLoginPath();
+    let pending = readPending(path, url);
+    let resuming = pending != null;
+    if (pending && isPendingExpired(pending)) {
+        clearPending(path, url);
+        pending = null;
+        resuming = false;
+        if (!asJson)
+            console.log('⚠ The previous code expired. Here is a new one.');
+    }
+    if (!pending) {
+        const res = await fetchOrDie(`${url}/api/public/cli-login/start`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ client_label: clientLabel(hostname(), platform()) }),
+        }, 'starting sign-in');
+        const started = await res.json().catch(() => null);
+        if (!res.ok || !started?.device_code || !started.user_code) {
+            if (res.status === 404) {
+                die(`this platform has no browser sign-in yet (older version) — mint a token in the console and use \`octwin login --url ${url} --token oct_…\``);
+            }
+            die(`could not start sign-in (HTTP ${res.status})${started?.error ? ` — ${started.error}` : ''}`);
+        }
+        pending = {
+            device_code: started.device_code,
+            user_code: started.user_code,
+            verify_url: started.verify_url ?? `${url}/cli-login`,
+            expires_at: started.expires_at ?? new Date(Date.now() + 600_000).toISOString(),
+            interval_seconds: started.interval_seconds ?? 5,
+        };
+        writePending(path, url, pending);
+    }
+    const waitSeconds = flags.wait !== undefined ? Math.max(0, Number(flags.wait) || 0) : LOGIN_WAIT_SECONDS;
+    if (asJson) {
+        console.log(JSON.stringify({
+            status: 'pending',
+            verify_url: pending.verify_url,
+            user_code: pending.user_code,
+            expires_at: pending.expires_at,
+        }, null, 2));
+    }
+    else {
+        // The link and the code go on their own labelled lines because an AGENT reads
+        // this and relays it into a conversation verbatim. The format is an interface.
+        //
+        // The code is printed even though the link already carries it: it is what the
+        // approver checks the page against, and the only thing they can compare if the
+        // link reached them some other way.
+        console.log('');
+        console.log(`  Open this link to approve:  ${pending.verify_url}`);
+        console.log(`  Code shown on that page:    ${pending.user_code}`);
+        console.log('');
+        console.log(`  Valid for ${Math.max(1, Math.round(secondsLeft(pending) / 60))} more minute(s). Approving gives this machine access to your workspace,`);
+        console.log('  so only approve a link you opened because YOU ran this command.');
+        if (waitSeconds > 0)
+            console.log(`  Waiting ${waitSeconds}s… (run \`octwin login\` again to keep waiting)`);
+    }
+    const intervalMs = Math.max(1, pending.interval_seconds) * 1000;
+    const deadline = Date.now() + waitSeconds * 1000;
+    // A resumed handshake may ALREADY be approved, so ask before waiting; a fresh one
+    // cannot be, so give the human one interval first.
+    let delay = resuming ? 0 : intervalMs;
+    while (Date.now() + delay <= deadline) {
+        await sleep(delay);
+        delay = intervalMs;
+        const res = await fetchOrDie(`${url}/api/public/cli-login/poll`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ device_code: pending.device_code }),
+        }, 'checking sign-in');
+        const body = await res.json().catch(() => null);
+        const outcome = interpretPoll(res.status, body, res.headers.get('retry-after'), intervalMs);
+        switch (outcome.kind) {
+            case 'approved': {
+                clearPending(path, url);
+                if (asJson) {
+                    console.log(JSON.stringify({
+                        status: 'approved', tenant_slug: outcome.tenantSlug,
+                        project_slug: outcome.projectSlug, token_expires: outcome.tokenExpires,
+                    }, null, 2));
+                    const creds = readCreds();
+                    creds[url] = outcome.token;
+                    creds[DEFAULT_URL_KEY] = url;
+                    writeCreds(creds);
+                    return;
+                }
+                await saveLogin(url, outcome.token);
+                if (outcome.tokenExpires) {
+                    console.log(`  → Expires ${outcome.tokenExpires.slice(0, 10)} — run \`octwin login\` again to renew.`);
+                }
+                return;
+            }
+            case 'gone':
+                clearPending(path, url);
+                die(outcome.reason === 'expired'
+                    ? 'that code expired before it was approved — run `octwin login` again for a new one'
+                    : 'that sign-in request is no longer on the platform — run `octwin login` again');
+                break;
+            case 'failed':
+                die(`sign-in failed — ${outcome.detail}`);
+                break;
+            case 'retry':
+                delay = outcome.afterMs;
+                break;
+            case 'pending':
+                break;
+        }
+    }
+    if (!asJson) {
+        console.log('');
+        console.log('⏳ Not approved yet. Run `octwin login` again to keep waiting — the same code stays valid.');
+        console.log('   Running in CI? Skip login and set PACK_PLATFORM_URL + PACK_TOKEN instead.');
+    }
+    exitNow(EXIT_STILL_PENDING);
+}
 /** Bearer auth + the optional self-surface overrides, as request headers. */
 function authHeaders(t) {
     const h = { authorization: `Bearer ${t.token}` };
@@ -4975,7 +5144,8 @@ function help() {
   octwin --version                                      # print the CLI version (+ any upgrade notice)
   octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
   octwin validate [--dir .] [--remote] [--require-kb]   # --remote runs the platform's FULL schema check + lint (all errors at once)
-  octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
+  octwin login   --url <platformUrl>                    # approve in a browser; the CLI collects the token
+  octwin login   --url <platformUrl> --token oct_…      # or paste a deploy token from the console
   octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
   octwin projects [--archived] [--json]                  # the --project slugs this token can name
   octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
@@ -5021,7 +5191,8 @@ Writes — exercise the state your pack creates (each needs the matching :write
 Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
 \`octwin chat --as <h>\` calls continue the same conversation; press a rendered
 button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
-Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
+Signing in: \`octwin login --url <u>\` prints a link + code to approve in a browser. To pick your own
+scopes instead, mint a token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
 octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
 Config (deploy): flags > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login (\`octwin login\` sets the default target).
 Per-command usage: octwin <command> --help`);
@@ -5040,10 +5211,24 @@ const COMMAND_HELP = {
   --strict-primitives (with --remote) additionally type-checks LITERAL args:
   values against each primitive's declared input schema; expression strings
   ('$found.id', '{$t(…)}') are always exempt.`,
-    login: `octwin login --url <platformUrl> --token oct_…
-  Save a deploy token (console → Settings → API tokens) for that platform url,
-  make that url the DEFAULT deploy target for every later command, and echo the
-  workspace + project pin + scopes the token reaches.`,
+    login: `octwin login --url <platformUrl> [--token oct_…] [--wait <seconds>] [--json]
+  Sign in to a platform and make that url the DEFAULT deploy target for every
+  later command.
+
+  WITH --token: saves a token you minted yourself (console → Settings → API
+  tokens). Unchanged, and still the right answer for CI — there, skip login and
+  set PACK_PLATFORM_URL + PACK_TOKEN instead.
+
+  WITHOUT --token: prints a link to approve in a browser. A workspace admin opens
+  it, checks which machine is asking, and clicks Approve; the CLI then collects a
+  30-day token by itself, so no token is ever pasted between people. The code is
+  printed too — it is what the page shows, so you can tell it is your own request.
+  Approve only a link you opened because YOU ran this command: a link someone
+  sends you would connect THEIR machine to your workspace.
+
+  The wait is bounded (90s by default) and RESUMABLE: if nobody has approved yet
+  it exits 75 and keeps the request, so running \`octwin login\` again picks up the
+  same code. --wait 0 prints the code and returns at once.`,
     whoami: `octwin whoami [--url <url>] [--tenant <slug>]
   Verify the resolved token authenticates against the tenant.`,
     projects: `octwin projects [--archived] [--json]

package/dist/lib/device-login.js

@@ -0,0 +1,127 @@
+/**
+ * The pure half of a browser `octwin login` — everything about the device-code
+ * handshake that isn't a socket.
+ *
+ * `index.ts` keeps the URL construction and the actual `fetch` calls (the route
+ * guard in `cli-routes.test.ts` reads that file and only that file, so a URL that
+ * moved here would stop being checked against the platform's route table). What
+ * lives here is the part worth testing without a server: how a poll response is
+ * read, how long to wait next, and the on-disk record of a handshake in flight.
+ *
+ * ## Why a handshake is written to disk at all
+ *
+ * Because the CLI is mostly driven by an agent, and an agent's shell call is cut
+ * off long before a human finishes clicking. So `octwin login` waits a bounded
+ * time and then RETURNS, keeping the request; running it again resumes the same
+ * one with the same code. Without a file, a second run would mint a second code
+ * and the code the human is looking at would be dead.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * `~/.octwin/pending-login.json`, a map of platform url → handshake.
+ *
+ * Deliberately NOT `credentials.json`: every value in that file is a token, and its
+ * one reserved key is safe only because a url always contains `://` and the key
+ * never does. A second value shape there would make that argument stop holding.
+ */
+export function readPending(path, url) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const map = JSON.parse(raw);
+        const found = map[url];
+        return found && typeof found.device_code === 'string' ? found : null;
+    }
+    catch {
+        return null;
+    } // a corrupt file just means "no handshake in flight"
+}
+export function writePending(path, url, pending) {
+    let map = {};
+    try {
+        map = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch { /* first one */ }
+    map[url] = pending;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(map, null, 2), 'utf8');
+}
+export function clearPending(path, url) {
+    let map;
+    try {
+        map = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    if (!(url in map))
+        return;
+    delete map[url];
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(map, null, 2), 'utf8');
+}
+/** True once the platform would refuse this handshake — checked before reusing one. */
+export function isPendingExpired(pending, now = Date.now()) {
+    const at = Date.parse(pending.expires_at);
+    return Number.isNaN(at) || at <= now;
+}
+/** Whole seconds left, floored at 0 — for the "expires in 7 min" line. */
+export function secondsLeft(pending, now = Date.now()) {
+    const at = Date.parse(pending.expires_at);
+    if (Number.isNaN(at))
+        return 0;
+    return Math.max(0, Math.round((at - now) / 1000));
+}
+/**
+ * Read one poll response.
+ *
+ * A 429 is NOT a failure — the platform's own limiter sets `Retry-After`, and a
+ * client that treats being asked to slow down as an error turns a wait into a
+ * broken login. 5xx is the same shape for a different reason.
+ */
+export function interpretPoll(status, json, retryAfterHeader, defaultDelayMs) {
+    if (status === 429 || status >= 500) {
+        const secs = Number(retryAfterHeader);
+        const afterMs = Number.isFinite(secs) && secs > 0 ? secs * 1000 : defaultDelayMs * 2;
+        return { kind: 'retry', afterMs };
+    }
+    const body = (json ?? {});
+    if (status !== 200) {
+        return { kind: 'failed', detail: String(body.error ?? `the platform answered HTTP ${status}`) };
+    }
+    switch (body.status) {
+        case 'approved':
+            if (typeof body.token !== 'string' || !body.token) {
+                return { kind: 'failed', detail: 'the platform approved the login but returned no token' };
+            }
+            return {
+                kind: 'approved',
+                token: body.token,
+                tenantSlug: typeof body.tenant_slug === 'string' ? body.tenant_slug : '',
+                projectSlug: typeof body.project_slug === 'string' ? body.project_slug : null,
+                tokenExpires: typeof body.token_expires === 'string' ? body.token_expires : null,
+            };
+        case 'pending': return { kind: 'pending' };
+        case 'expired': return { kind: 'gone', reason: 'expired' };
+        case 'not_found': return { kind: 'gone', reason: 'not_found' };
+        default:
+            return { kind: 'failed', detail: `the platform answered with an unknown status '${String(body.status)}'` };
+    }
+}
+/**
+ * How this machine introduces itself on the approval screen. Untrusted by the
+ * platform (this call carries no credential), so it is a courtesy to the approver,
+ * never a claim — which is exactly how the console renders it.
+ */
+export function clientLabel(hostname, platform) {
+    const os = { win32: 'Windows', darwin: 'macOS', linux: 'Linux' }[platform] ?? platform;
+    return `${hostname || 'unknown host'} · ${os}`;
+}
+/** Exit code for "the wait ended, nothing is wrong" — `EX_TEMPFAIL`. An agent branches on it. */
+export const EXIT_STILL_PENDING = 75;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {