@tokenoftrust/cli 1.4.0-rc.1 → 1.4.0-rc.10

package/src/commands/submit.mjs

@@ -46,12 +46,19 @@ import { validateTenant, ERROR } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
 import { fail } from "../errors.mjs";
+import {
+  defaultCandidateStatePath,
+  readActiveChangeId,
+  writeActiveChangeId,
+  mintFreshChangeId,
+  isTerminalCandidateState,
+} from "../candidate-state.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 const DEFAULT_REF = "preview";
 
 export function parseArgs(argv) {
-  const a = { mcp: null, identity: null, ref: DEFAULT_REF, skipValidate: false, noWait: false, watch: false, noOpen: false, message: null, summary: null, help: false };
+  const a = { mcp: null, identity: null, ref: DEFAULT_REF, skipValidate: false, noWait: false, watch: false, noOpen: false, noCommit: false, message: null, summary: null, new: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
@@ -60,28 +67,48 @@ export function parseArgs(argv) {
     else if (t === "-m" || t === "--message") a.message = argv[++i];
     else if (t === "--summary") a.summary = argv[++i];
     else if (t === "--skip-validate") a.skipValidate = true;
+    else if (t === "--no-commit") a.noCommit = true;
     else if (t === "--no-wait") a.noWait = true;
     else if (t === "--watch") a.watch = true;
     else if (t === "--no-open") a.noOpen = true;
+    else if (t === "--new") a.new = true;
     else if (t === "--help" || t === "-h") a.help = true;
   }
   return a;
 }
 
-const USAGE = `tot submit — submit your store for preview
+/**
+ * Render the usage block for whichever verb invoked this flow. `preview` is the
+ * first-class verb; `submit`/`deploy` reach the same flow as teaching aliases, so
+ * the help they print names the verb the developer actually typed (see preview.mjs).
+ * @param {string} [verb]
+ */
+export function renderUsage(verb = "preview") {
+  return `tot ${verb} — submit your store for preview
+
+  tot ${verb}                    validate → push the preview ref → stream the result
+  tot ${verb} --new              open a NEW candidate PR instead of updating your open one
+  tot ${verb} --watch            stay attached through reconcile + compliance + accept (long-poll)
+  tot ${verb} --skip-validate    push without the local lint (not recommended)
+  tot ${verb} --no-commit        don't auto-commit a dirty tree — preview only what's already committed
+  tot ${verb} --ref <name>       push ref (default: ${DEFAULT_REF})
+  tot ${verb} -m "<title>"       one-line summary of what changed (the approver sees this)
+  tot ${verb} --summary "<text>" longer description to accompany the title
+  tot ${verb} --no-wait          push and exit without polling for the reconcile result
+  tot ${verb} --no-open          don't open the preview URL in the browser on success
+  tot ${verb} --mcp <url>        MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+
+  By default a re-run UPDATES your open candidate PR (like pushing more commits
+  to a GitHub PR), rather than opening a new one each time. Use --new to fork a
+  fresh candidate PR; the next plain \`tot ${verb}\` then updates THAT one. Manage your
+  open candidates with \`tot pr\` (list / view / close). If your candidate was already
+  merged or closed, a re-run automatically opens a fresh one.
 
-  tot submit                    validate → push the preview ref → stream the result
-  tot submit --watch            stay attached through reconcile + compliance + accept (long-poll)
-  tot submit --skip-validate    push without the local lint (not recommended)
-  tot submit --ref <name>       push ref (default: ${DEFAULT_REF})
-  tot submit -m "<title>"       one-line summary of what changed (the approver sees this)
-  tot submit --summary "<text>" longer description to accompany the title
-  tot submit --no-wait          push and exit without polling for the reconcile result
-  tot submit --no-open          don't open the preview URL in the browser on success
-  tot submit --mcp <url>        MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+  Once a preview reconciles cleanly, \`tot ship\` promotes it live.
 
   If you omit -m, a summary is generated from git (commit subject + the diff vs
   what's live in preview) so the change record the approver reviews is never blank.`;
+}
 
 // Default bounded wait (~20s, matching the pre-E2 fixed poll's total budget) vs.
 // --watch's longer per-call long-poll + more attempts (~8 min ceiling) for a dev
@@ -123,6 +150,126 @@ function printChangeSummary({ title, body, autoTitle }) {
   if (autoTitle) console.log(`  (auto-generated from git — pass -m "…" / --summary "…" to refine)`);
 }
 
+// ─── auto-commit the known content trees (unit u2) ───────────────────────────────
+
+/**
+ * The content trees `tot preview` may auto-commit on a dirty tree — and ONLY
+ * these. A store's reviewable content lives here; anything a developer edits
+ * OUTSIDE these (src/, config, stray files) is out of scope for an automatic
+ * commit and is REFUSED rather than silently swept in. Explicit paths only —
+ * never `git add -A`/`git add .`.
+ */
+export const KNOWN_CONTENT_TREES = ["content/", "public/", ".tot/"];
+export const KNOWN_CONTENT_FILES = ["theme.json"];
+
+/** Is this repo-relative path inside a known content tree (or the one known
+ *  top-level file)? Pure — unit-tested. */
+export function isKnownContentPath(path) {
+  const p = String(path).replace(/^\.\//, "");
+  return KNOWN_CONTENT_FILES.includes(p) || KNOWN_CONTENT_TREES.some((t) => p.startsWith(t));
+}
+
+/**
+ * Flatten `git status --porcelain` (v1) output to the ordered, deduped set of
+ * dirty repo-relative paths. Each line is `XY <path>`; a rename/copy is
+ * `XY <old> -> <new>` and contributes BOTH paths (the old one is being removed
+ * from its tree too, so it's part of the scope decision). Run with
+ * `core.quotePath=false` upstream so unicode paths arrive literal. Pure —
+ * unit-tested.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function parsePorcelainPaths(text) {
+  const seen = new Set();
+  const out = [];
+  for (const line of String(text).split("\n")) {
+    if (line.length < 4) continue; // "XY p" is the shortest real entry
+    const rest = line.slice(3);
+    const parts = rest.includes(" -> ") ? rest.split(" -> ") : [rest];
+    for (const raw of parts) {
+      const p = raw.trim();
+      if (p && !seen.has(p)) {
+        seen.add(p);
+        out.push(p);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Partition dirty paths into the known content trees vs everything else. Pure —
+ * unit-tested.
+ * @param {string[]} paths
+ * @returns {{ known: string[], unknown: string[] }}
+ */
+export function classifyDirtyPaths(paths) {
+  const known = [];
+  const unknown = [];
+  for (const p of paths) (isKnownContentPath(p) ? known : unknown).push(p);
+  return { known, unknown };
+}
+
+/** A concise auto commit subject when the developer gave no -m — derived from the
+ *  staged files so the commit is never a blank "(untitled change)". Pure. */
+export function autoCommitSubject(files = []) {
+  if (files.length === 0) return "update store content";
+  if (files.length === 1) return `update ${files[0]}`;
+  return `update ${files.length} content files`;
+}
+
+/**
+ * The message for `tot preview`'s pre-preview auto-commit. An explicit `-m` wins
+ * as the subject; otherwise autoCommitSubject derives one from the staged files.
+ * The body (shortstat + file list) is built by the SAME buildChangeSummary the
+ * approver summary uses, so a commit and the change record it later feeds read
+ * consistently. Returns a git commit message (subject, blank line, body). Pure —
+ * unit-tested.
+ * @param {{ message?: string|null, files?: string[], statLine?: string }} input
+ * @returns {string}
+ */
+export function buildAutoCommitMessage({ message, files = [], statLine = "" } = {}) {
+  const subject = (message && message.trim()) || autoCommitSubject(files);
+  const { body } = buildChangeSummary({ message: subject, files, statLine });
+  return body.length ? `${subject}\n\n${body.join("\n")}` : subject;
+}
+
+/**
+ * Auto-commit the known content trees before previewing (unit u2). On a DIRTY
+ * tree `tot preview` commits your content edits for you, so a preview always
+ * reflects your working changes — but ONLY the known trees (content/, public/,
+ * theme.json, .tot/), staged by EXPLICIT path (never `git add -A`). If anything
+ * dirty falls OUTSIDE those, it REFUSES (out-of-scope src/config/stray edits are
+ * never silently swept into a store commit). --no-commit opts out entirely
+ * (preview whatever's already committed — u1's behavior).
+ *
+ * Returns exactly one of:
+ *   { skipped: true }               — --no-commit.
+ *   { clean: true }                 — nothing dirty; preview HEAD as-is.
+ *   { refused, unknown, known }     — out-of-scope dirt; caller refuses + hints.
+ *   { committed: true, sha, files } — staged the known dirty paths and committed.
+ *
+ * @param {(cargs:string[])=>string} git  a `git -C <workspace>` runner
+ * @param {{ message?: string|null, noCommit?: boolean }} [opts]
+ */
+export function autoCommitKnownTrees(git, { message = null, noCommit = false } = {}) {
+  if (noCommit) return { skipped: true };
+  const status = git(["-c", "core.quotePath=false", "status", "--porcelain", "--untracked-files=all"]);
+  const dirty = parsePorcelainPaths(status);
+  if (dirty.length === 0) return { clean: true };
+  const { known, unknown } = classifyDirtyPaths(dirty);
+  if (unknown.length) return { refused: true, unknown, known };
+  // Stage ONLY the known dirty paths, each by explicit path — this records adds,
+  // modifications AND deletions within them, and can never reach outside the set.
+  git(["add", "--", ...known]);
+  const files = parseNameStatus(git(["diff", "--cached", "--name-status"])).map((e) => e.path);
+  const statLine = git(["diff", "--cached", "--shortstat"]).trim();
+  const msg = buildAutoCommitMessage({ message, files, statLine });
+  git(["commit", "--no-verify", "-m", msg]);
+  const sha = git(["rev-parse", "HEAD"]).trim();
+  return { committed: true, sha, files };
+}
+
 // ─── PR-backed candidate (g1b candidate_open, unit c1) ──────────────────────────
 
 /**
@@ -277,19 +424,26 @@ function reportCandidate(result, changeId) {
   console.log(`  ~ PR-backed candidate not opened: ${msg}`);
 }
 
-/** @param {string[]} argv @param {any} ctx */
-export async function run(argv, ctx) {
+/**
+ * The preview flow — validate, push the preview ref, open/update the PR-backed
+ * candidate, and stream back the reconcile/compliance/preview result. Reached by
+ * `tot preview` and, as teaching aliases, `tot submit` / `tot deploy` (preview.mjs
+ * wraps this and adds the verb-teaching hints). `verb` only brands the user-facing
+ * copy (usage + the not-in-checkout error) with whatever the developer typed.
+ * @param {string[]} argv @param {any} ctx @param {{ verb?: string }} [opts]
+ */
+export async function run(argv, ctx, { verb = "preview" } = {}) {
   const env = process.env;
   const args = parseArgs(argv);
   if (args.help) {
-    console.log(USAGE);
+    console.log(renderUsage(verb));
     return 0;
   }
   if (ctx.mode !== "checkout") {
     console.error(
       fail(
-        "`tot submit` runs from inside a tenant checkout",
-        "tot checkout <tenant> --clone <dir>   (then `cd` in, commit your work, and re-run)",
+        `\`tot ${verb}\` runs from inside a tenant checkout`,
+        "tot clone <tenant> <dir>   (then `cd` in, commit your work, and re-run)",
       ),
     );
     return 2;
@@ -298,6 +452,41 @@ export async function run(argv, ctx) {
   const tenant = ctx.tenant;
   const git = (cargs) => execFileSync("git", ["-C", workspace, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
 
+  // 0. auto-commit the known content trees (unit u2) — on a dirty tree, commit your
+  //    content edits BEFORE previewing so the preview reflects your working changes.
+  //    Only content/, public/, theme.json, .tot/ (staged by explicit path, never
+  //    `git add -A`); anything dirty outside those is refused, not silently swept in.
+  //    --no-commit opts out (preview whatever's already committed).
+  let auto;
+  try {
+    auto = autoCommitKnownTrees(git, { message: args.message, noCommit: args.noCommit });
+  } catch (e) {
+    console.error(
+      fail(
+        `auto-commit failed: ${String(e?.stderr || e?.message || e)}`,
+        "commit your content manually (git add / git commit), or re-run with --no-commit",
+      ),
+    );
+    return 1;
+  }
+  if (auto.refused) {
+    console.error(
+      fail(
+        `${auto.unknown.length} change(s) are outside the store content trees — refusing to auto-commit`,
+        "commit (or stash/revert) those yourself, then re-run — or use --no-commit to preview only what's already committed",
+      ) + "\n",
+    );
+    for (const p of auto.unknown) console.error(`  ✗ out of scope: ${p}`);
+    console.error(`\n  \`tot ${verb}\` auto-commits only: ${[...KNOWN_CONTENT_TREES, ...KNOWN_CONTENT_FILES].join(", ")}`);
+    if (auto.known.length) console.error(`  (in scope, would have been committed: ${auto.known.join(", ")})`);
+    return 1;
+  }
+  if (auto.committed) {
+    console.error(
+      `~ auto-committed ${auto.sha.slice(0, 9)} (${auto.files.length} content file(s)) — pass -m "…" to set the message, --no-commit to skip`,
+    );
+  }
+
   // 1. validate locally — refuse on errors.
   if (!args.skipValidate) {
     const { ok, findings } = validateTenant(workspace, { tenantId: tenant, scope: ctx.config?.scope });
@@ -381,13 +570,40 @@ export async function run(argv, ctx) {
     // 2b. PR-backed candidate (g1b candidate_open, unit c1) — best-effort: a
     // failure here (older MCP, VC not configured, preview-access capability) is
     // reported and swallowed, never blocking the preview push that already landed.
-    await submitCandidate(client, {
-      repo: repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim()),
-      changeId: deriveChangeId(tenant, actorKeyFor(session)),
-      changeSummary,
-      patchEntries,
-      readBlob: (path) => execFileSync("git", ["-C", workspace, "show", `HEAD:${path}`], { stdio: ["ignore", "pipe", "pipe"] }),
-    });
+    //
+    // Which candidate this submit lands on (gh-pr-like):
+    //   --new           → fork a FRESH candidate and remember it as active;
+    //   otherwise       → the remembered active candidate (from a prior --new /
+    //                     roll), else the STABLE per-dev-per-tenant default.
+    // If the chosen candidate turns out to be merged/closed, roll to a fresh one
+    // so a re-submit is never wedged on a dead PR.
+    const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
+    const readBlob = (path) => execFileSync("git", ["-C", workspace, "show", `HEAD:${path}`], { stdio: ["ignore", "pipe", "pipe"] });
+    const statePath = defaultCandidateStatePath(env);
+    const stableId = deriveChangeId(tenant, actorKeyFor(session));
+    const active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo }) : null;
+    let changeId = args.new ? mintFreshChangeId(stableId) : (active || stableId);
+    // Persist when we diverge from the stable default (a --new fork, or a
+    // previously-remembered active pointer) so the next plain submit follows it.
+    let persist = args.new || (!!active && active !== stableId);
+
+    let candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob });
+
+    if (candidate && isTerminalCandidateState(candidate.state)) {
+      const rolled = mintFreshChangeId(stableId);
+      console.log(`  ~ candidate ${changeId} is ${candidate.state} — opening a fresh candidate PR instead.`);
+      changeId = rolled;
+      persist = true;
+      candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob });
+    }
+
+    // Remember the active candidate only on a real, non-terminal open (best-effort;
+    // never let a state-write failure break the submit).
+    if (persist && repo && candidate && !isTerminalCandidateState(candidate.state)) {
+      try {
+        writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, changeId });
+      } catch { /* best-effort local hint — a miss just re-derives the stable id */ }
+    }
 
     let status;
     if (args.noWait) {

package/src/commands/validate.mjs

@@ -68,11 +68,11 @@ export function run(argv, ctx) {
 
   const target = resolveTarget(args, ctx);
   if (target.error) {
-    console.error(fail(target.error, "tot checkout <tenant> --clone <dir>, or pass --workspace <dir>"));
+    console.error(fail(target.error, "tot clone <tenant>, or pass --workspace <dir>"));
     return 2;
   }
   if (!existsSync(target.dir)) {
-    console.error(fail(`no tenant directory at ${target.dir}`, "confirm the path, or `tot checkout <tenant> --clone <dir>`"));
+    console.error(fail(`no tenant directory at ${target.dir}`, "confirm the path, or `tot clone <tenant>`"));
     return 2;
   }
 

package/src/commands/whoami.mjs

@@ -11,7 +11,7 @@
 import { defaultCredentialsPath, readCredentials, isExpired, activeProfile } from "../token-store.mjs";
 import { establishSession } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
-import { normalizeStores, storeListError } from "./checkout.mjs";
+import { normalizeStores, storeListError, noStoresGuidance } from "./clone.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
 
 /**
@@ -67,7 +67,11 @@ export async function run(argv, _ctx) {
     } else if (listErr) {
       console.log(`  (couldn't list your stores: ${listErr} — try \`tot login\` again)`);
     } else {
-      console.log("  (no stores resolved yet — if you were just invited, it may still be propagating)");
+      // Status-aware (card c2): an UNLINKED identity is told to link (not "may
+      // still be propagating" — that's only the genuine zero-grants case).
+      const g = noStoresGuidance(listResp);
+      console.log(`  (${g.headline})`);
+      console.log(`  → next: ${g.next}`);
     }
   } catch {
     console.log("  (couldn't reach the MCP to list your stores right now — your cached session is above)");

package/src/context.mjs

@@ -6,13 +6,13 @@
  *
  *   monorepo   — inside a full storefront checkout (pnpm-workspace.yaml +
  *                apps/storefront + tenants/). This is us / a platform dev.
- *                `tot dev` here runs the in-tree astro dev; `tot checkout`
+ *                `tot dev` here runs the in-tree astro dev; `tot clone`
  *                can suggest cloning a sibling dir.
  *   checkout   — inside a STANDALONE tenant checkout: the flat, content-only
  *                shape `content/ public/ theme.json .tot/config.json` a
  *                developer clones. The tenant is read from .tot/config.json.
  *                `tot dev` here boots the bundled runner against this dir.
- *   loose      — anywhere else. `tot checkout <tenant>` still works (it's how
+ *   loose      — anywhere else. `tot clone <tenant>` still works (it's how
  *                you GET a checkout); commands that need a workspace say so.
  *
  * Detection walks UP from the cwd so `tot` works from any subdirectory of a

package/src/oauth.mjs

@@ -84,8 +84,15 @@ export async function registerClient(
     headers: { "Content-Type": "application/json", Accept: "application/json" },
     body: JSON.stringify({
       client_name: CLIENT_NAME,
+      // Include the device-code grant: the browserless rendezvous + B3 device flows
+      // redeem their device_code at /oauth/token with this grant, so a client
+      // registered WITHOUT it gets "unauthorized_client: grant_type is invalid".
+      grant_types: [
+        "authorization_code",
+        "refresh_token",
+        "urn:ietf:params:oauth:grant-type:device_code",
+      ],
       redirect_uris: [redirectUri],
-      grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],
       token_endpoint_auth_method: "none",
       scope: SCOPE,
@@ -285,41 +292,50 @@ export async function loginFlow({
   }
 }
 
-// ── WS2b: browserless invite-code redemption (`tot login --code <token>`) ─────
+// ── Browserless CLI sign-in — RFC 8628 RENDEZVOUS (`tot login --code <handle>`) ──
 //
-// The invited developer pastes the single-use sign-in token their invite minted;
-// we hand it to the MCP's redeem endpoint, which validates + BURNS it via ToT and
-// returns a normal MCP OAuth grant. No browser, no loopback, no OTP — the token IS
-// the operator's authorization. Same credentials shape as loginFlow/deviceLoginFlow,
-// and the grant is bound to our registered client_id so later silent refreshes go
-// through the standard token endpoint like any other session.
+// The invited developer pastes the NON-SECRET rendezvous handle their cockpit
+// rendered. Unlike the retired bearer-redeem (a secret received elsewhere, replayed
+// once), the terminal generates its OWN PKCE key here, ATTACHES only the public
+// challenge to the pending rendezvous, prints a human-verifiable fingerprint, and
+// polls the standard token endpoint (device_code grant + PKCE) until the developer
+// approves that fingerprint in the cockpit. Same credentials shape as
+// loginFlow/deviceLoginFlow, same dynamically-registered client_id, so later silent
+// refreshes go through the standard token endpoint like any other session.
 //
-// Wire contract (CLI → MCP):
-//   POST {mcp-origin}/oauth/redeem-code   (application/json)
-//     { code: "<invite sign-in token>", client_id, scope? }
-//   → 200 { access_token, refresh_token, token_type, expires_in, scope }
-//   → 400 { error, error_description }   (invalid_grant | invalid_client)
+// Wire contract (CLI → MCP), all off the MCP origin (from the AS token endpoint):
+//   POST /oauth/device/attach  (application/json)
+//     { rendezvous_code, client_id, code_challenge, code_challenge_method: "S256" }
+//     → 200 { device_code, user_fingerprint, interval, expires_in }
+//     → 400 { error, error_description }   (invalid_grant | invalid_client)
+//   POST /oauth/token  (form)  grant_type=…:device_code, device_code, code_verifier,
+//     client_id → RFC 8628 polling until approved/denied/expired.
 //
-// The token→CLI binding is inherent to the single request: the tokens are returned
-// only in the direct TLS response to the client that presented the code, and the
-// grant is pinned to our dynamically-registered client_id (only that client can
-// refresh it). A separate PKCE nonce would add nothing here — there is no second
-// exchange step at which a verifier could be presented.
-
-/** The MCP's redeem endpoint — the MCP origin (from the AS token endpoint) + a
- * fixed path. Kept beside the flow so the path lives in exactly one place. */
-export function redeemCodeEndpoint(mcpUrl, meta) {
+// Device-bound by construction: the pasted handle attaches only a PUBLIC PKCE
+// challenge (intercepting it grants nothing — an interceptor's terminal shows a
+// DIFFERENT fingerprint the developer won't approve), and only the terminal holding
+// the matching verifier can redeem the device_code at /oauth/token.
+
+/** An MCP device/rendezvous endpoint — the MCP origin (from the AS token endpoint)
+ * + a fixed path. Kept beside the flow so the paths live in exactly one place. */
+export function deviceEndpoint(mcpUrl, meta, path) {
   const origin = meta?.token_endpoint ? new URL(meta.token_endpoint) : new URL(mcpUrl);
-  return new URL("/oauth/redeem-code", origin).toString();
+  return new URL(path, origin).toString();
 }
 
-/** POST the invite token to the MCP redeem endpoint and return the raw token
- * response (→ credentialsFromToken). Throws a clear, non-stack error on rejection. */
-export async function redeemInviteCode(redeemEndpoint, { code, clientId, scope = SCOPE }, fetchImpl = fetch) {
-  const res = await fetchImpl(redeemEndpoint, {
+/** Attach the terminal's PKCE challenge to a pending rendezvous. Returns the raw
+ * response { device_code, user_fingerprint, interval, expires_in }. Throws a clear,
+ * non-stack error on rejection (an expired / already-used handle). */
+export async function attachRendezvous(attachEndpoint, { rendezvousCode, clientId, challenge }, fetchImpl = fetch) {
+  const res = await fetchImpl(attachEndpoint, {
     method: "POST",
     headers: { "Content-Type": "application/json", Accept: "application/json" },
-    body: JSON.stringify({ code, client_id: clientId, scope }),
+    body: JSON.stringify({
+      rendezvous_code: rendezvousCode,
+      client_id: clientId,
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+    }),
   });
   const text = await res.text();
   let body;
@@ -328,31 +344,61 @@ export async function redeemInviteCode(redeemEndpoint, { code, clientId, scope =
     const detail = [body.error, body.error_description].filter(Boolean).join(" — ");
     throw new Error(`your sign-in code was not accepted (HTTP ${res.status}${detail ? `: ${detail}` : ""})`);
   }
-  if (!body.access_token) throw new Error("the redeem endpoint returned no access_token");
+  if (!body.device_code || !body.user_fingerprint) {
+    throw new Error("the attach endpoint returned no device_code/fingerprint");
+  }
   return body;
 }
 
 /**
- * Run the full browserless redemption and return a persistable credentials record
- * — the invite-token sibling of loginFlow()/deviceLoginFlow(), same credentials
- * shape, same dynamically-registered client_id (reused when the caller cached one
- * for this MCP). Injectable (`fetchImpl`, `now`) so it's testable with no network.
+ * Run the full browserless rendezvous sign-in and return a persistable credentials
+ * record — the invite sibling of loginFlow()/deviceLoginFlow(), same credentials
+ * shape + dynamically-registered client_id (reused when the caller cached one for
+ * this MCP). The terminal generates its own PKCE key, attaches, surfaces the
+ * fingerprint via `log` for the developer to confirm in the cockpit, then polls the
+ * token endpoint until approved. Injectable (`fetchImpl`, `log`, `sleep`, `now`) so
+ * it's testable with no network and no real waiting.
  * @returns {Promise<object>} credentials to hand to writeCredentials()
  */
-export async function redeemCodeFlow({
+export async function rendezvousLoginFlow({
   mcpUrl,
-  clientId,
   code,
   fetchImpl = fetch,
+  log = () => {},
+  sleep = delay,
   now = () => Date.now(),
 }) {
   const meta = await discoverMetadata(mcpUrl, fetchImpl);
-  const resolvedClientId = clientId || (await registerClient(meta.registration_endpoint, LOOPBACK_REDIRECT, fetchImpl));
-  const token = await redeemInviteCode(
-    redeemCodeEndpoint(mcpUrl, meta),
-    { code, clientId: resolvedClientId },
+  // Always register a FRESH client for a rendezvous sign-in — do NOT reuse a cached
+  // clientId. A client cached by an older CLI build was registered without the
+  // device-code grant, so /oauth/token would reject the device grant with
+  // "unauthorized_client". Registration is cheap and a rendezvous has no consent
+  // screen to re-trigger (unlike the loopback/device flows, which reuse the cache).
+  const resolvedClientId = await registerClient(meta.registration_endpoint, LOOPBACK_REDIRECT, fetchImpl);
+  const { verifier, challenge } = generatePkce();
+
+  const attach = await attachRendezvous(
+    deviceEndpoint(mcpUrl, meta, "/oauth/device/attach"),
+    { rendezvousCode: code, clientId: resolvedClientId, challenge },
     fetchImpl,
   );
+
+  log("");
+  log(`  Confirm this code in your browser to finish signing in:  ${attach.user_fingerprint}`);
+  log("  Waiting for you to approve it in Token of Trust …");
+
+  const token = await pollDeviceToken(
+    meta.token_endpoint,
+    {
+      deviceCode: attach.device_code,
+      clientId: resolvedClientId,
+      codeVerifier: verifier,
+      intervalSec: attach.interval,
+      expiresInSec: attach.expires_in,
+    },
+    fetchImpl,
+    { sleep, now },
+  );
   return credentialsFromToken({
     mcpUrl,
     clientId: resolvedClientId,
@@ -395,7 +441,7 @@ export async function deviceAuthorize(deviceAuthorizationEndpoint, { clientId, s
  * normal "keep waiting" responses — so this resolves `{ pending: true }`
  * (with `slowDown` set) for those instead of throwing.
  */
-async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId }, fetchImpl) {
+async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId, codeVerifier }, fetchImpl) {
   const res = await fetchImpl(tokenEndpoint, {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
@@ -403,6 +449,10 @@ async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId }, fetchImp
       grant_type: "urn:ietf:params:oauth:grant-type:device_code",
       device_code: deviceCode,
       client_id: clientId,
+      // The rendezvous flow binds the grant to the terminal's PKCE key: the
+      // verifier proves this is the same terminal that attached the challenge.
+      // Absent for the plain RFC 8628 device flow (no PKCE) — omitted then.
+      ...(codeVerifier ? { code_verifier: codeVerifier } : {}),
     }).toString(),
   });
   const text = await res.text();
@@ -428,7 +478,7 @@ async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId }, fetchImp
  */
 export async function pollDeviceToken(
   tokenEndpoint,
-  { deviceCode, clientId, intervalSec, expiresInSec },
+  { deviceCode, clientId, codeVerifier, intervalSec, expiresInSec },
   fetchImpl = fetch,
   { sleep = delay, now = () => Date.now() } = {},
 ) {
@@ -437,7 +487,7 @@ export async function pollDeviceToken(
   for (;;) {
     await sleep(intervalMs);
     if (now() >= deadline) throw new Error("the device code expired before it was approved");
-    const r = await deviceTokenPoll(tokenEndpoint, { deviceCode, clientId }, fetchImpl);
+    const r = await deviceTokenPoll(tokenEndpoint, { deviceCode, clientId, codeVerifier }, fetchImpl);
     if (!r.pending) return r.token;
     if (r.slowDown) intervalMs += 5000;
   }

package/src/obstacle-beacon.cjs

@@ -1,6 +1,6 @@
 /**
  * The obstacle beacon — a fire-and-forget POST that tells the hosted cockpit a
- * `tot start` / `tot checkout` failed, so it can show the exact fix in the bridge
+ * `tot start` / `tot clone` failed, so it can show the exact fix in the bridge
  * strip (obstacle lane, server side already shipped). Best-effort telemetry that
  * rides ALONGSIDE the house-style `✗ … → next:` error; it must NEVER change,
  * delay past its timeout, or fail that error path.