octwin-cli 0.8.7 → 0.8.9

package/CHANGELOG.md

@@ -5,6 +5,67 @@ 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.9] - 2026-09-07
+
+### Added
+- **Every authenticated request now says which CLI and which capability reference you are on.**
+  Two headers off `authHeaders` — `x-octwin-cli` and `x-octwin-kb` (the `content_hash` of your
+  pulled reference) — so `deploy`, `validate --remote`, `status`, `chat`, `logs` and `memos` all
+  carry them, from one place. The platform stores them against your deploy token and shows them in
+  the console (Settings → API tokens, and Platform → Packs → Feedback → Author tooling for us).
+
+  **Why the platform needs this from you.** Almost every field report so far turned out to be
+  either already fixed in a newer CLI or written against a stale reference — three very different
+  answers that look identical without these two facts. They were captured on `octwin feedback`
+  only, so an author who never filed a report was invisible. Nothing here affects auth: a request
+  that sends neither header authenticates exactly as before, and a value that could not travel as
+  a header (a corrupt `package.json`, an interrupted pull) is dropped rather than sent.
+
+### Fixed
+- **The upgrade notice was skipped under `npx` — silencing the population most likely to be
+  stale.** The premise was that "`@latest` already resolves the newest", which holds for
+  `npx octwin-cli@latest` and is false for the bare `npx octwin-cli` the docs put in front of
+  external developers: npm serves that from its **cache**, so it can be arbitrarily old. Under
+  `@latest` the check is self-silencing anyway (you are already newest), so keeping it costs
+  nothing — only the advice line differs, because there is no global install to reinstall.
+
+## [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';
@@ -69,6 +69,7 @@ import { loadAllowedRenderKeys, findRenderKeyViolations, describeRenderFinding }
 import { loadPrimitiveArgSpecs, findArgViolations, describeArgFinding } from './lib/args-check.js';
 import { yamlLineOf } from './lib/yaml-pos.js';
 import { localhostFamilyHint } from './lib/net-hint.js';
+import { authHeaders as buildAuthHeaders } from './lib/client-headers.js';
 import { loadBuiltinNames, findBuiltinViolations, describeBuiltinFinding } from './lib/builtin-check.js';
 import { loadTemplateSpecs, findTemplateViolations, describeTemplateFinding } from './lib/template-check.js';
 import { loadSystemEntities, findEntityViolations, describeEntityFinding } from './lib/entity-check.js';
@@ -79,6 +80,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 +183,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)`;
 }
 /**
@@ -541,9 +543,8 @@ async function latestPublishedVersion() {
     }
 }
 /** True when running via `npx` — the CLI's own file lives in npx's cache dir, or npm
- *  ran it as `npm exec`. Under npx there is no persistent install to upgrade
- *  (`@latest` already resolves the newest), so an upgrade notice would be
- *  misleading — stay silent. The notice is for a GLOBAL install (`npm i -g`). */
+ *  ran it as `npm exec`. Only the ADVICE changes on this: there is no global install
+ *  to upgrade, so the fix is to pin `@latest` rather than to reinstall. */
 function isNpx() {
     try {
         return fileURLToPath(import.meta.url).includes('_npx') || process.env.npm_command === 'exec';
@@ -554,23 +555,31 @@ function isNpx() {
 }
 /** A one-line upgrade notice when a newer octwin-cli is published, or [] when current.
  *
- *  Skipped only under npx, where there is genuinely nothing to upgrade. It USED to bail on
- *  `!process.stdout.isTTY` as well, which silently made this the one notice a piped reader never
- *  saw — the opposite of the rule its two siblings already carry in their docblocks, and measured
- *  2026-08-26: with a newer version cached, `octwin whoami | tail` printed the KB nudge and not
- *  this one. An agent driving the CLI cannot notice an outdated CLI on its own, so it is exactly
- *  the reader that needs telling. One line on stderr, so piped stdout stays clean either way.
+ *  Gated on NOTHING. It USED to bail on `!process.stdout.isTTY`, which silently made this the one
+ *  notice a piped reader never saw — the opposite of the rule its two siblings already carry in
+ *  their docblocks, and measured 2026-08-26: with a newer version cached, `octwin whoami | tail`
+ *  printed the KB nudge and not this one. An agent driving the CLI cannot notice an outdated CLI on
+ *  its own, so it is exactly the reader that needs telling. One line on stderr, so piped stdout
+ *  stays clean either way.
+ *
+ *  IT ALSO USED TO BAIL UNDER npx, on the premise that "`@latest` already resolves the newest".
+ *  That premise holds for `npx octwin-cli@latest` and is false for the bare `npx octwin-cli` that
+ *  `BACKLOG-decided.md` and the authoring skill both put in front of external developers — npm
+ *  serves that from its cache, so it can be arbitrarily old and was the ONE population this
+ *  notice never reached. Under `@latest` the check is self-silencing anyway (`VERSION` is already
+ *  the newest, so `isNewer` is false), which is why keeping it costs nothing and only the advice
+ *  line has to differ: there is no global install to reinstall.
  *
  *  Never throws — a version check must never break a command. */
 async function outdatedNotice() {
-    if (isNpx())
-        return [];
     try {
         const latest = await latestPublishedVersion();
         if (latest && isNewer(latest, VERSION)) {
             return [
                 `\n⬆ octwin-cli ${latest} is available (you have ${VERSION}).`,
-                '  Upgrade: npm i -g octwin-cli@latest   (or just use npx octwin-cli@latest)',
+                isNpx()
+                    ? '  You are running via npx, which serves a CACHED copy — pin it: npx octwin-cli@latest'
+                    : '  Upgrade: npm i -g octwin-cli@latest   (or just use npx octwin-cli@latest)',
             ];
         }
     }
@@ -584,6 +593,18 @@ async function outdatedNotice() {
 // catalogs only) describes how to enumerate a catalog so we can EXPLODE it into
 // one file per entry; the PLATFORM supplies it rather than this CLI hardcoding
 // per-catalog knowledge, so a platform that adds a catalog needs no CLI release.
+/**
+ * The pulled reference for THIS run, read once in `main` before any command.
+ *
+ * Two readers need it and both used to reach for the disk themselves: the drift
+ * nudge, and now `authHeaders` (which runs on every request — see the client
+ * report). Reading it once also keeps the corrupt-`index.json` warning below to
+ * one printing.
+ *
+ * `null` = nothing pulled (or unreadable); a non-null row with a null
+ * `content_hash` = pulled, but the identity file did not carry one.
+ */
+let LOCAL_KB = null;
 /** A previously-pulled KB's identity in `<packDir>/.octwin/platform-kb/index.json`
  *  (content hash + per-entry index), or null if nothing has been pulled yet. */
 function readLocalKb(packDir) {
@@ -657,8 +678,9 @@ async function fetchKbMeta(t, timeoutMs = 2_000) {
  *  `octwin platform-kb pull`. The sibling of `notifyIfOutdated`, for the KB instead
  *  of the CLI: run only after commands that already hit the platform, so this adds
  *  a single tiny `?meta=1` GET on top of work that was networked anyway. Never
- *  throws — observing must never break a command. No-op until the author has pulled
- *  once (nothing to compare) or if the target can't be resolved.
+ *  throws — observing must never break a command. No-op if the target can't be
+ *  resolved, or until the author has pulled once — nothing pulled is the PLATFORM's
+ *  line to say, on deploy + validate, so that it reaches an old CLI too.
  *
  *  NOT TTY-gated, deliberately. It was, on the reasoning that a nudge is for a
  *  human watching a terminal — but the primary reader of this CLI is now an
@@ -667,10 +689,24 @@ async function fetchKbMeta(t, timeoutMs = 2_000) {
  *  told. It is a single line on stderr, so piped stdout stays clean either way. */
 async function kbStaleNotice(flags) {
     try {
-        const packDir = resolve(flags.dir ?? '.');
-        const local = readLocalKb(packDir);
+        const local = LOCAL_KB;
+        /**
+         * NOTHING PULLED IS NOT THIS OBSERVER'S JOB — it is the PLATFORM's.
+         *
+         * This branch is a no-op, which reads like the bug it used to be, so: the "you have
+         * pulled no reference" line now comes from the platform, on `deploy` and
+         * `validate --remote` (`routes/packs/_cli-advisory.ts`), and that is strictly better
+         * placed. A client-side nudge can only reach a CLI new enough to contain it, and the
+         * authors who have pulled nothing are exactly the ones most likely to be on an old
+         * one. The server answer reaches every CLI.
+         *
+         * Saying it here TOO was measured on 2026-09-07 and rejected: a never-pulled
+         * `validate` printed the same fact three times — the SKIPPED-checks line (which is
+         * the most specific of the three, naming how many checks could not run), the
+         * platform's advisory, and this. Three is how the credible ones stop being read.
+         */
         if (!local?.content_hash)
-            return []; // never pulled → the skill already says to pull
+            return [];
         // URL only, deliberately: the KB poll is anonymous, so requiring a token here would
         // silence the nudge for exactly the authors who most need it. This used to call
         // `resolveTargetOrNull` (url AND token) against the tenant-scoped route, which needs
@@ -1224,10 +1260,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,14 +1309,160 @@ async function cmdLogin(flags) {
     }
     catch { /* platform unreachable — the token is saved regardless */ }
 }
-/** Bearer auth + the optional self-surface overrides, as request headers. */
+/** `~/.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 + this run's client report.
+ *
+ * A thin wrapper so the ~90 call sites stay unchanged while the logic (and its
+ * two omit-don't-placeholder rules) lives in a testable module. The KB hash comes
+ * from `LOCAL_KB`, read ONCE per run in `main` — reading it per request would hit
+ * the disk on every call and could print the corrupt-index warning many times.
+ */
 function authHeaders(t) {
-    const h = { authorization: `Bearer ${t.token}` };
-    if (t.tenant)
-        h['x-octwin-tenant'] = t.tenant;
-    if (t.project)
-        h['x-octwin-project'] = t.project;
-    return h;
+    return buildAuthHeaders(t, { cliVersion: VERSION, kbContentHash: LOCAL_KB?.content_hash ?? null });
 }
 /** Resolve platform url + token (+ optional tenant/project overrides):
  *  flags > env > saved login. Tenant is derived from the token server-side, so
@@ -2412,7 +2618,9 @@ async function cmdFeedback(flags) {
     const doc = parseYaml(readFileSync(manifestPath, 'utf8'));
     const packId = typeof doc?.id === 'string' ? doc.id : die('manifest.yaml must declare a string `id`');
     const packVersion = typeof doc?.version === 'string' ? doc.version : undefined;
-    const kbHash = readLocalKb(packDir)?.content_hash ?? undefined;
+    // `LOCAL_KB` is this run's read of the SAME `--dir`, taken in `main` — so this is the
+    // hash the client report already sent in the headers, not a second opinion about it.
+    const kbHash = LOCAL_KB?.content_hash ?? undefined;
     console.log(`→ Submitting ${Math.round(Buffer.byteLength(report, 'utf8') / 1024)}KB of feedback on ${packId} to ${targetLabel(t)} …`);
     const { status, json } = await apiSend('POST', `${url}/api/self/p/packs/feedback`, {
         pack_id: packId,
@@ -4975,7 +5183,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 +5230,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 +5250,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]
@@ -5365,6 +5589,9 @@ async function main() {
     // exit code with 127, so a failing `octwin deploy` in CI reported the wrong thing. Measured
     // 2026-08-26: one pre-command poll exits 1 cleanly, two concurrent ones abort. Awaiting them in
     // turn costs one extra round-trip on an already-networked command and keeps the exit code true.
+    // Read the pulled reference ONCE, here, before anything can ask for it: the drift nudge below
+    // needs its index, and `authHeaders` needs its hash on every request of every command.
+    LOCAL_KB = readLocalKb(resolve(flags.dir ?? '.'));
     const networked = commandTouchesPlatform(command, flags);
     if (networked) {
         PENDING_NOTICES.push(...await kbStaleNotice(flags));

package/dist/lib/client-headers.js

@@ -0,0 +1,80 @@
+/**
+ * What this CLI tells the platform about ITSELF, on every authenticated request.
+ *
+ * ## Why this exists
+ *
+ * A pack built against an old CLI or a stale capability reference is wrong in ways
+ * that look like platform bugs. That is measured, not feared: one author hardcoded
+ * English across all 16 flows of a production pack to work around a bug fixed two
+ * days earlier, and two authors independently filed a CLI bug as platform replica
+ * lag. The platform's own schema says so — `007_pack_feedback.sql` captures
+ * `cli_version` + `kb_content_hash` because "almost every report from the field so
+ * far turned out to be either (a) already fixed in a newer CLI, or (b) written
+ * against a stale capability reference".
+ *
+ * But it captured them on ONE route: `octwin feedback`. `deploy` and `validate`
+ * sent neither, so an author who never filed a report was invisible — and the two
+ * client-side nudges (the npm upgrade check, the KB drift poll) are both blind in
+ * exactly the states that matter most: nothing pulled at all, and `npx`.
+ *
+ * So the report rides the AUTH HEADERS instead. `authHeaders` is the one place
+ * every networked command builds its headers, which is why two lines here cover
+ * deploy, validate, status, chat, logs and memos at once.
+ *
+ * ## Two rules that are not obvious
+ *
+ * **Omit, never send a placeholder.** A missing `x-octwin-kb` means "this author
+ * pulled no reference". A literal `"none"` would be a magic string every reader has
+ * to learn, and it would land in the platform's column as a value that looks like
+ * data.
+ *
+ * **A malformed value is dropped, not sent.** undici THROWS on a header value
+ * containing a newline, and these values come off disk (`package.json`, a pulled
+ * `index.json`) — so an unvalidated pass-through turns a corrupt file into a failed
+ * command. A diagnostic that can break the command it annotates is not a
+ * diagnostic. The platform validates again on its side; that is a bound on what it
+ * stores, not a substitute for this.
+ */
+/** This CLI's version. Read by the platform on every authenticated request. */
+export const HEADER_CLI_VERSION = 'x-octwin-cli';
+/** The `content_hash` of the capability reference the author actually pulled. */
+export const HEADER_KB_HASH = 'x-octwin-kb';
+/**
+ * A semver-ish version safe to put in a header. Deliberately wider than `x.y.z`
+ * (a prerelease tag is a real version) and hard-bounded, because the value comes
+ * from a `package.json` this module does not control.
+ */
+const SAFE_VERSION = /^[0-9A-Za-z.+-]{1,32}$/;
+/**
+ * The published hash shape is 12 hex — `contentHash()` truncates a sha256 — but
+ * the range is loose on purpose: the platform owns that length and may change it,
+ * and a CLI that rejected a longer hash would silence its own report on the very
+ * upgrade it should be reporting.
+ */
+const SAFE_KB_HASH = /^[0-9a-f]{8,64}$/;
+/** The client report as headers — each field omitted when absent or malformed. */
+export function clientReportHeaders(report) {
+    const h = {};
+    if (SAFE_VERSION.test(report.cliVersion))
+        h[HEADER_CLI_VERSION] = report.cliVersion;
+    const kb = report.kbContentHash;
+    if (kb && SAFE_KB_HASH.test(kb))
+        h[HEADER_KB_HASH] = kb;
+    return h;
+}
+/**
+ * Bearer auth + the optional self-surface overrides + the client report.
+ *
+ * The token carries its own tenant (server-side), so the unified `/api/self/**`
+ * surface needs neither tenant nor project in the URL. `tenant`/`project` are kept
+ * only as OPTIONAL overrides (project overrides an unpinned token; a mismatched
+ * override of a pinned token is rejected server-side).
+ */
+export function authHeaders(t, report) {
+    const h = { authorization: `Bearer ${t.token}` };
+    if (t.tenant)
+        h['x-octwin-tenant'] = t.tenant;
+    if (t.project)
+        h['x-octwin-project'] = t.project;
+    return { ...h, ...clientReportHeaders(report) };
+}

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.9",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {