flowsprite 0.1.3 → 0.1.4

package/dist/doctor.js

@@ -8,6 +8,14 @@ import { spawnSync } from "node:child_process";
  */
 /** The major this package declares in `engines` — one authority, read by both halves. */
 export const MIN_NODE_MAJOR = 20;
+/**
+ * THE FAIL SET (card eecc9d6f N16): node too old, endpoint unreachable, no
+ * credential or a refused one. `sf`/`gh` absence is a NOTE, never a failure —
+ * neither is needed for the browser road.
+ */
+export function doctorOk(report) {
+    return report.nodeOk && report.endpointReachable && report.hasCredential && !report.credentialRefused;
+}
 export function nodeMajor(version) {
     const m = /^v?(\d+)\./.exec(version);
     return m ? Number(m[1]) : 0;
@@ -17,9 +25,15 @@ export function formatDoctor(report) {
     return [
         `${mark(report.nodeOk)} node ${report.nodeVersion} (needs >= ${MIN_NODE_MAJOR})`,
         `${mark(report.endpointReachable)} endpoint ${report.endpoint} — ${report.endpointDetail}`,
-        `${mark(report.hasCredential)} credential for ${report.endpoint} ${report.hasCredential ? "found" : "not found — run `flowsprite login`"} (${report.credentialsPath})`,
-        `${report.sfOnPath ? "ok  " : "note"} sf on PATH: ${report.sfOnPath ? "yes" : "no (only needed for Salesforce CLI work)"}`,
-        `${report.ghOnPath ? "ok  " : "note"} gh on PATH: ${report.ghOnPath ? "yes" : "no (only needed for GitHub CLI work)"}`,
+        !report.hasCredential
+            ? `FAIL credential for ${report.endpoint} not found (${report.credentialsPath}) — run \`flowsprite setup\` (logging in is its step 1), or \`flowsprite login\` alone`
+            : report.credentialRefused
+                ? `FAIL credential for ${report.endpoint} refused by the endpoint (HTTP 401) — run \`flowsprite login\` for a new one`
+                : `ok   credential for ${report.endpoint} found (${report.credentialSource === "stored" || report.credentialSource === null
+                    ? report.credentialsPath
+                    : `from ${report.credentialSource}, not stored`})`,
+        `${report.sfOnPath ? "ok  " : "note"} sf on PATH: ${report.sfOnPath ? "yes" : "no — needed for 'connect salesforce --from-sf-cli'. Install: npm install -g @salesforce/cli (macOS: brew install --cask salesforce-cli); then sf org login web --alias <name>."}`,
+        `${report.ghOnPath ? "ok  " : "note"} gh on PATH: ${report.ghOnPath ? "yes" : "no — needed for a no-browser 'login'. Install: gh (e.g. brew install gh); then gh auth login -s user:email."}`,
     ];
 }
 /**

package/dist/ghLogin.js

@@ -52,7 +52,8 @@ const FLOWSPRITE_TOKEN_RE = /^fp_(?:user|live)_[A-Za-z0-9_-]{32}$/;
 const ORG_ID_RE = /^org_[A-Za-z0-9]+$/;
 const USER_ID_RE = /^user_[A-Za-z0-9]+$/;
 const DEVICE_CODE_RE = /^[0-9a-f]{64}$/;
-const USER_CODE_RE = /^[A-Z]{4}-[A-Z]{4}$/;
+/** The user code's shape on BOTH roads and in `pending-login.json` (eecc9d6f G1/G5). */
+export const USER_CODE_RE = /^[A-Z]{4}-[A-Z]{4}$/;
 /** The approve page's path on the endpoint; the only thing a 409 may ask the CLI to open. */
 const APPROVE_PATH = "/cli/auth";
 /** The device-code TTL the endpoint documents (`expires_in: 900`) — and the ceiling. */
@@ -70,9 +71,15 @@ export function clampExpiresIn(claimed) {
         ? Math.min(MAX_EXPIRES_IN_SECONDS, Math.max(1, claimed))
         : MAX_EXPIRES_IN_SECONDS;
 }
-/** The poll interval as the loop may trust it: a positive number, else the documented 5. ONE rule for both roads. */
-export function intervalSeconds(claimed) {
-    return typeof claimed === "number" && claimed > 0 ? claimed : 5;
+/**
+ * The poll interval as the loop may trust it — ONE rule for both roads and the
+ * resumed `pending-login.json` (eecc9d6f G3): a finite positive number, else the
+ * documented 5; never below 1 s (a tiny value is a busy loop) and never above
+ * `maxSeconds`, the code's remaining lifetime (a huge value would sleep past it).
+ */
+export function intervalSeconds(claimed, maxSeconds = MAX_EXPIRES_IN_SECONDS) {
+    const base = typeof claimed === "number" && Number.isFinite(claimed) && claimed > 0 ? Math.max(1, claimed) : 5;
+    return Math.max(1, Math.min(base, maxSeconds));
 }
 const STOP_CODES = new Set([
     "in_progress",
@@ -103,7 +110,7 @@ const STOP_SERVER_ERROR = { kind: "stop", code: "server_error" };
  * bearer (fix round 2 F6). The href is asserted to be one of the two exact
  * forms, so nothing else can ever reach a sink.
  */
-function approvePageHref(target, origin, userCode) {
+export function approvePageHref(target, origin, userCode) {
     if (typeof target !== "string")
         return null;
     let url;
@@ -144,7 +151,7 @@ export function classifyBootstrapAnswer(status, body, origin) {
     }
     const deviceCode = body.device_code;
     const expiresIn = clampExpiresIn(body.expires_in);
-    const interval = intervalSeconds(body.interval);
+    const interval = intervalSeconds(body.interval, expiresIn);
     if (status === 202) {
         if (typeof deviceCode !== "string" || !DEVICE_CODE_RE.test(deviceCode))
             return STOP_SERVER_ERROR;

package/dist/login.js

@@ -1,5 +1,6 @@
-import { clampExpiresIn, classifyBootstrapAnswer, intervalSeconds, readGhToken, } from "./ghLogin.js";
-import { APPROVER_BLOCKED_NOTE, GH_DOOR_REMEDIES, GH_ROAD, inProgressRemedy, isLoginFailureKind, LOGIN_REMEDIES, POLL_CONTINUE_KINDS, timeLeftLine, } from "./messages.js";
+import { approvePageHref, clampExpiresIn, classifyBootstrapAnswer, intervalSeconds, readGhToken, USER_CODE_RE, } from "./ghLogin.js";
+import { APPROVER_BLOCKED_NOTE, clock, CODE_ENDING_KINDS, GH_DOOR_REMEDIES, GH_ROAD, inProgressRemedy, isLoginFailureKind, LOGIN_REMEDIES, OPEN_TARGET_REFUSED, POLL_CONTINUE_KINDS, RESUMING_LINE, SEED_RESUME_HINT, stillWaitingLine, timeLeftLine, waitHintLine, } from "./messages.js";
+import { printable } from "./redact.js";
 /**
  * RFC 8628 device-code login against `/api/cli/auth/{start,poll}`.
  *
@@ -27,10 +28,42 @@ import { APPROVER_BLOCKED_NOTE, GH_DOOR_REMEDIES, GH_ROAD, inProgressRemedy, isL
  */
 /** Seconds added to the poll interval each time the server says `slow_down`. */
 const SLOW_DOWN_STEP_SECONDS = 5;
-/** `m:ss`, for the countdown. */
-function clock(seconds) {
-    const whole = Math.max(0, Math.floor(seconds));
-    return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}`;
+/** How often, in SLEPT seconds, a run with no status line re-prints the link (C2). */
+const REPRINT_EVERY_SECONDS = 60;
+/** The longest server-supplied display string the success line takes (an email's RFC 5321 cap). */
+const DISPLAY_MAX = 254;
+/**
+ * C4 — a display string from the poll answer, or undefined (the id is shown
+ * instead). It is SERVER text spliced into a CLI sentence, so it is scrubbed of
+ * every control character here (a newline in it would forge a line) — the
+ * writer's per-line scrub keeps newlines, so it is not enough on its own.
+ *
+ * eecc9d6f G4/H5 — THE RULE, not a list: every code point Unicode marks
+ * `Default_Ignorable_Code_Point` (renders as nothing: ZWSP/ZWJ, bidi marks, all
+ * variation selectors incl. Mongolian FVS, tag characters, the soft hyphen, the
+ * combining grapheme joiner…), every format character (`\p{Cf}`), and the line
+ * and paragraph separators U+2028/2029 are REMOVED, before the writer redacts.
+ * Removed, not spaced: a token split by an invisible character would otherwise
+ * reach the writer as two halves its redactor (`redact.ts`, a run of the token
+ * alphabet) matches only the first of; joined, the writer redacts it whole.
+ * Visible combining marks (`\p{Mn}` outside that property — accents in real
+ * names) are kept.
+ */
+const INVISIBLE = /[\p{Default_Ignorable_Code_Point}\p{Cf}\u2028\u2029]/gu;
+function displayText(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const text = printable(value.replace(INVISIBLE, "")).trim();
+    return text.length > 0 && text.length <= DISPLAY_MAX ? text : undefined;
+}
+/** A pending-port call that must never fail the login (C3). */
+function quietly(call) {
+    try {
+        call();
+    }
+    catch {
+        // Persistence is a convenience: an unwritable config dir costs the resume, not the login.
+    }
 }
 function failure(kind) {
     return { ok: false, kind, message: LOGIN_REMEDIES[kind] };
@@ -90,31 +123,38 @@ async function startDeviceCode(deps) {
     const userCode = start.body.user_code;
     const completeUri = start.body.verification_uri_complete;
     const fallbackUri = start.body.verification_uri;
-    if (typeof deviceCode !== "string" || typeof userCode !== "string") {
+    if (typeof deviceCode !== "string" || typeof userCode !== "string" || !USER_CODE_RE.test(userCode)) {
         return failure("server_error");
     }
-    const openTarget = typeof completeUri === "string"
-        ? completeUri
-        : typeof fallbackUri === "string"
-            ? fallbackUri
-            : null;
+    // eecc9d6f G1: the ONE string this CLI prints and hands to `openUrl` is held to
+    // the gh road's rule (`approvePageHref`): exactly this origin's `/cli/auth`,
+    // optionally `?code=<this user code>`, normalised. A foreign host, `file:`,
+    // `javascript:`, userinfo, or an option-shaped `-a…` (macOS `open` reads a
+    // `-a`/`-b` option out of a single argv element) never reaches a sink.
+    const openTarget = approvePageHref(completeUri ?? fallbackUri, deps.origin, userCode);
     if (openTarget === null)
-        return failure("server_error");
+        return { ok: false, kind: "server_error", message: OPEN_TARGET_REFUSED };
     // The device code's own lifetime bounds the loop, so a server that answers
     // `authorization_pending` forever still ends — with the same sentence a real
     // `expired_token` gets, because the window really has passed. CLAMPED TO THE
     // REAL TTL (`clampExpiresIn`): a number this CLI reads off a response is what
     // stands between a bad value and a terminal that polls for a year.
     const expiresIn = clampExpiresIn(start.body.expires_in);
-    const interval = intervalSeconds(start.body.interval);
+    const interval = intervalSeconds(start.body.interval, expiresIn);
     return { deviceCode, userCode, openTarget, expiresIn, interval };
 }
-/** The three lines a person acts on, plus the best-effort browser open. */
-function announceBrowser(deps, payload) {
-    deps.writer.out(`Open ${payload.openTarget} and confirm the code ${payload.userCode}`);
+/**
+ * The lines a person acts on, plus the best-effort browser open. A RESUMED login
+ * is announced again but not re-opened (`open: false`): the browser was opened
+ * by the run that started it, and the approval may already be done.
+ */
+function announceBrowser(deps, payload, open = true) {
+    // printable(): defence in depth — both values were already held to a grammar.
+    deps.writer.out(`Open ${printable(payload.openTarget)} and confirm the code ${printable(payload.userCode)}`);
     deps.writer.out("Waiting for you to approve this login...");
     deps.writer.out(timeLeftLine(payload.expiresIn));
-    if (deps.openUrl) {
+    deps.writer.out(waitHintLine(payload.expiresIn));
+    if (open && deps.openUrl) {
         try {
             deps.openUrl(payload.openTarget);
         }
@@ -124,15 +164,19 @@ function announceBrowser(deps, payload) {
     }
 }
 /** Poll `/api/cli/auth/poll` until the code is approved and minted, refused, or expired. */
-async function pollLoop(deps, { deviceCode, expiresIn, interval }) {
+async function pollLoop(deps, { deviceCode, expiresIn, interval, openTarget }) {
     let intervalSeconds = interval;
     let waitedSeconds = 0;
     let approverNotePrinted = false;
+    let reprintAt = REPRINT_EVERY_SECONDS;
     for (;;) {
         if (waitedSeconds >= expiresIn)
             return failure("expired_token");
-        await deps.sleep(intervalSeconds * 1000);
-        waitedSeconds += intervalSeconds;
+        // G3: never sleep past the code's end — the last nap is cut to the time left,
+        // so the slept total is at most `expiresIn` whatever `slow_down` added.
+        const nap = Math.min(intervalSeconds, expiresIn - waitedSeconds);
+        await deps.sleep(nap * 1000);
+        waitedSeconds += nap;
         const poll = await postJson(deps, `${deps.origin}/api/cli/auth/poll`, {
             device_code: deviceCode,
         });
@@ -149,7 +193,17 @@ async function pollLoop(deps, { deviceCode, expiresIn, interval }) {
                 typeof mcpEndpoint !== "string") {
                 return failure("server_error");
             }
-            return { ok: true, token, orgId, userId, mcpEndpoint };
+            const userEmail = displayText(poll.body.user_email);
+            const orgName = displayText(poll.body.org_name);
+            return {
+                ok: true,
+                token,
+                orgId,
+                userId,
+                mcpEndpoint,
+                ...(userEmail === undefined ? {} : { userEmail }),
+                ...(orgName === undefined ? {} : { orgName }),
+            };
         }
         const kind = poll.body.error;
         if (typeof kind === "string" && POLL_CONTINUE_KINDS.has(kind)) {
@@ -166,7 +220,15 @@ async function pollLoop(deps, { deviceCode, expiresIn, interval }) {
             // ponytail: time left is expires_in minus the SUM OF SLEEPS, so fetch latency
             // and a suspended laptop are not counted and it can overstate; thread `now`
             // into LoginDeps for a wall-clock countdown if that ever reads wrong.
-            deps.progress?.(`Still waiting — ${clock(expiresIn - waitedSeconds)} left`);
+            if (deps.progress) {
+                deps.progress(`Still waiting — ${clock(expiresIn - waitedSeconds)} left`);
+            }
+            else if (waitedSeconds >= reprintAt) {
+                // C2: no status line (a pipe, an agent shell) — one line per minute of
+                // waiting, carrying the link, so it never scrolls out of reach.
+                deps.writer.out(stillWaitingLine(expiresIn - waitedSeconds, openTarget));
+                reprintAt = (Math.floor(waitedSeconds / REPRINT_EVERY_SECONDS) + 1) * REPRINT_EVERY_SECONDS;
+            }
             if (kind === "slow_down") {
                 // The server has ALREADY raised its own required interval by this much;
                 // raising ours to match is what stops the next poll earning another one.
@@ -178,12 +240,65 @@ async function pollLoop(deps, { deviceCode, expiresIn, interval }) {
         return failure(refusalKind(poll.body));
     }
 }
+/**
+ * C3 — poll, then settle the saved pending login. Success and every answer in
+ * `CODE_ENDING_KINDS` clear it (G10); a transient answer keeps it for the next
+ * `flowsprite login`. The clear names THIS run's device code (G2), so a stale
+ * run never deletes the entry a newer run saved.
+ */
+async function pollAndSettle(deps, pending) {
+    const result = await pollLoop(deps, pending);
+    if (result.ok || CODE_ENDING_KINDS.has(result.kind))
+        quietly(() => deps.pending?.clear(pending.deviceCode));
+    return result;
+}
+function savePending(deps, pending) {
+    quietly(() => deps.pending?.save(pending));
+}
+/**
+ * C3 — resume an unexpired login an earlier run announced, or null when none is
+ * saved (or the port fails). A resumed login calls NEITHER `/api/cli/auth/start`
+ * NOR the gh door. The saved numbers are re-clamped by the SAME rules the wire
+ * values get (G3): the wait is at most the seconds left (itself at most 900),
+ * and the interval is 1 s to that — so the slept total of a resumed login never
+ * exceeds the time the file says is left, capped at the code's 900 s TTL.
+ */
+async function resumePending(deps) {
+    let saved;
+    try {
+        saved = deps.pending?.load() ?? null;
+    }
+    catch {
+        return null;
+    }
+    if (saved === null)
+        return null;
+    const pending = {
+        ...saved,
+        expiresIn: clampExpiresIn(saved.expiresIn),
+        interval: intervalSeconds(saved.interval, clampExpiresIn(saved.expiresIn)),
+    };
+    deps.writer.out(RESUMING_LINE);
+    if (pending.userCode !== undefined && pending.openTarget !== undefined) {
+        announceBrowser(deps, { userCode: pending.userCode, openTarget: pending.openTarget, expiresIn: pending.expiresIn }, false);
+    }
+    else {
+        // G9b: the gh road's 202 — the workspace is being set up; nothing to approve.
+        deps.writer.out(GH_ROAD.seedPending);
+        deps.writer.out(SEED_RESUME_HINT);
+    }
+    return pollAndSettle(deps, pending);
+}
 export async function deviceCodeLogin(deps) {
+    const resumed = await resumePending(deps);
+    if (resumed !== null)
+        return resumed;
     const started = await startDeviceCode(deps);
     if ("ok" in started)
         return started;
+    savePending(deps, started);
     announceBrowser(deps, started);
-    return pollLoop(deps, started);
+    return pollAndSettle(deps, started);
 }
 /**
  * `gh auth token`, read by shape. Null on every way it can fail — a non-zero
@@ -244,6 +359,11 @@ function stop(answer) {
  * (`redact.ts`) is the second net, not the first.
  */
 export async function ghCliLogin(deps) {
+    // C3: a login an earlier run left waiting is finished first — before gh is
+    // spawned or the door is asked, either of which would start a second one.
+    const resumed = await resumePending(deps);
+    if (resumed !== null)
+        return resumed;
     if (!deps.isOnPath("gh")) {
         deps.writer.out(GH_ROAD.notFound);
         return null;
@@ -267,8 +387,9 @@ export async function ghCliLogin(deps) {
         case "token":
             return { ok: true, token: answer.token, orgId: answer.orgId, userId: answer.userId, mcpEndpoint: answer.mcpEndpoint };
         case "poll":
+            savePending(deps, answer);
             deps.writer.out(GH_ROAD.seedPending);
-            return pollLoop(deps, answer);
+            return pollAndSettle(deps, answer);
         case "browser":
             if (answer.reason === "github_scope_missing") {
                 deps.writer.out(GH_ROAD.scopeMissing);
@@ -277,8 +398,9 @@ export async function ghCliLogin(deps) {
             else {
                 deps.writer.out(GH_ROAD.browserRequired);
             }
+            savePending(deps, answer);
             announceBrowser(deps, answer);
-            return pollLoop(deps, answer);
+            return pollAndSettle(deps, answer);
         default:
             return stop(answer);
     }

package/dist/mcpClient.js

@@ -1,4 +1,24 @@
 import { redact } from "./redact.js";
+/**
+ * The closed set of `structuredContent.error.code` values the endpoint can send on a refused
+ * `tools/call` (server side: `lib/mcpErrorEnvelope.ts`, `MCP_ERROR_CODES`). Duplicated here because
+ * this package builds standalone from `src/` and cannot import `lib/`; a root-tsc-checked test
+ * pins the two lists equal.
+ */
+export const TOOL_ERROR_CODES = [
+    "not_found",
+    "unauthorized",
+    "forbidden",
+    "invalid_argument",
+    "quota_exceeded",
+    "conflict",
+    "expired",
+    "not_ready",
+    "storage_failed",
+    "vendor_failed",
+    "cancelled",
+    "internal",
+];
 /**
  * EVERY message this module produces goes through `redact` before it is
  * returned. The bearer lives only in a header, so no message SHOULD carry it —
@@ -14,6 +34,19 @@ function fail(kind, message, code) {
     const safe = redact(message);
     return code === undefined ? { ok: false, kind, message: safe } : { ok: false, kind, message: safe, code };
 }
+/** The envelope's code + retryable, or undefined unless BOTH are well-formed (never a partial read). */
+function readToolError(structured) {
+    if (typeof structured !== "object" || structured === null || Array.isArray(structured))
+        return undefined;
+    const error = structured.error;
+    if (typeof error !== "object" || error === null || Array.isArray(error))
+        return undefined;
+    const { code, retryable } = error;
+    if (typeof retryable !== "boolean")
+        return undefined;
+    const known = TOOL_ERROR_CODES.find((c) => c === code);
+    return known === undefined ? undefined : { code: known, retryable };
+}
 export function createMcpClient(deps) {
     const url = `${deps.origin}/api/mcp`;
     let nextId = 0;
@@ -70,7 +103,9 @@ export function createMcpClient(deps) {
             // The tool's own refusal text is the whole value of this branch — an
             // `isError` result with no text would otherwise be an empty message.
             const text = content.find((c) => typeof c.text === "string")?.text;
-            return fail("tool_error", text ?? `${method} failed and said nothing about why.`);
+            const failure = fail("tool_error", text ?? `${method} failed and said nothing about why.`);
+            const toolError = readToolError(r.structuredContent);
+            return toolError === undefined ? failure : { ...failure, toolError };
         }
         return r.structuredContent === undefined
             ? { ok: true, content }

package/dist/messages.js

@@ -20,10 +20,52 @@ export const LOGIN_REMEDIES = {
  * minute", not 2), and anything under a minute says so rather than "0 minutes".
  */
 export function timeLeftLine(seconds) {
+    return `This code is good for ${minutesSpan(seconds)}. Press Ctrl-C to stop waiting.`;
+}
+/** Whole minutes, rounded DOWN (see `timeLeftLine`), or "less than a minute". */
+export function minutesSpan(seconds) {
     const minutes = Math.floor(seconds / 60);
-    const span = minutes < 1 ? "less than a minute" : `${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
-    return `This code is good for ${span}. Press Ctrl-C to stop waiting.`;
+    return minutes < 1 ? "less than a minute" : `${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
+}
+/** `m:ss`, for a countdown. Negative and fractional seconds fold to whole, non-negative ones. */
+export function clock(seconds) {
+    const whole = Math.max(0, Math.floor(seconds));
+    return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}`;
+}
+/**
+ * Card eecc9d6f C2 — printed once after the link is announced. An agent shell
+ * (measured: Claude Code backgrounds a command at 120 s) can stop this process
+ * long before the code expires; the device code is kept on disk
+ * (`pending-login.json`) so the next `flowsprite login` resumes it instead of
+ * starting over.
+ */
+export function waitHintLine(seconds) {
+    return `This waits up to ${minutesSpan(seconds)} for you to approve in the browser. If your terminal or tool stops it sooner, run \`flowsprite login\` again — it picks up the same login.`;
+}
+/**
+ * C2 — re-printed every 60 s of waiting when there is no terminal status line
+ * (a pipe, an agent shell), so the link never scrolls out of reach. `openTarget`
+ * is absent on the gh road's 202, which has no page to open.
+ */
+export function stillWaitingLine(secondsLeft, openTarget) {
+    return `Still waiting — ${clock(secondsLeft)} left.${openTarget === undefined ? "" : ` Open ${openTarget}`}`;
 }
+/**
+ * eecc9d6f G1 — `/api/cli/auth/start` answered with a page that is not THIS
+ * endpoint's approve page (another host, another scheme, a malformed or
+ * option-shaped string). Nothing is printed, opened or saved; the commonest
+ * honest cause is the same host spelled two ways (127.0.0.1 vs localhost).
+ */
+export const OPEN_TARGET_REFUSED = "Flowsprite answered with a sign-in link for a different host than the endpoint this terminal is using, so it was not opened or printed. If you passed --endpoint, use the exact host the server uses (127.0.0.1 and localhost count as different hosts), then run `flowsprite login` again.";
+/**
+ * eecc9d6f G9b — printed when a login is resumed on the gh road's 202 (the
+ * workspace was being set up): nothing waits on a browser there.
+ */
+export const SEED_RESUME_HINT = "If your terminal or tool stops this sooner, run `flowsprite login` again — it picks up the same login.";
+/** C3 — printed when `flowsprite login` picks up a login an earlier run started. */
+export const RESUMING_LINE = "Picking up the login this terminal started earlier.";
+/** C5 — printed after the success line: the setup links are bound to the account AND the workspace. */
+export const SAME_ACCOUNT_NOTE = "Setup links this terminal prints open only in a browser signed in to Flowsprite as this same account, in this same workspace.";
 /**
  * FLO-509 — printed once per login when a pending poll carries
  * `approver_blocked: true`.
@@ -37,6 +79,26 @@ export function timeLeftLine(seconds) {
 export const APPROVER_BLOCKED_NOTE = "Someone who opened this code in the browser could not approve it; that page says why and what to do. This terminal keeps waiting and logs in as soon as the code is approved.";
 /** The wire values that mean "keep polling", kept apart from the terminal ones above. */
 export const POLL_CONTINUE_KINDS = new Set(["authorization_pending", "slow_down"]);
+/**
+ * eecc9d6f G10/H1 — the poll answers that END a device code, and so clear its
+ * saved pending login. The rule: the server said THIS code can no longer be
+ * approved or exchanged — including `invalid_request`/`invalid_argument`, the
+ * wire's two `invalid_*` kinds (`WIRE_KINDS` below), which say the code itself
+ * is unusable. Only the four transient answers keep it: `transport`,
+ * `rate_limited`, `server_error`, `server_misconfigured` — and an entry is never
+ * live past its write + 900 s (`readPendingLogin`).
+ */
+export const CODE_ENDING_KINDS = new Set([
+    "expired_token",
+    "access_denied",
+    "no_grant",
+    "not_member",
+    "suspended",
+    "revoked",
+    "ambiguous_grant",
+    "invalid_request",
+    "invalid_argument",
+]);
 /**
  * The kinds that can arrive FROM THE WIRE — a strict subset of the remedy table.
  *

package/dist/setup.js

@@ -1,4 +1,5 @@
 import { toolJson } from "./mcpClient.js";
+import { clock, minutesSpan } from "./messages.js";
 import { printable } from "./redact.js";
 /**
  * The setup plane, driven from a terminal.
@@ -172,6 +173,101 @@ export function planBindArgs(input) {
         args: { sandboxId: connection, installationId, repoOwner: parts[0], repoName: parts[1] },
     };
 }
+/**
+ * C6 — the ONE instruction block a link step prints, CLI-owned. The server's
+ * `instructions` field is deliberately NOT printed: it repeated this sentence
+ * and named an MCP tool (`setup_status`) a terminal user cannot call.
+ */
+export function linkInstructions(url, expiresInSeconds) {
+    const seconds = expiresInSeconds ?? LINK_POLL_MAX_MS / 1000;
+    return [
+        "Open this link in a browser signed in to Flowsprite as the same account, in this same workspace:",
+        `  ${printable(url)}`,
+        LINK_SECRET_LINE,
+        `The link works once and expires in ${minutesSpan(seconds)}.`,
+    ];
+}
+/** Card eecc9d6f N12 — directly under every setup link. */
+export const LINK_SECRET_LINE = "This link is a one-time secret for your account — don't paste it in chat or share it.";
+// ------------------------------------------------------------- setup's steps (N3)
+/**
+ * Card eecc9d6f N3 — the three steps `setup` names, ONE table. A ladder rung
+ * maps onto a step by `stepOfRung`; `skipped` is what a step that needed no
+ * work this run says (step 1's is built at the call, it names the login).
+ */
+export const SETUP_STEPS = [
+    { label: "approve this login", skipped: "" },
+    { label: "connect Salesforce", skipped: "Salesforce is already connected" },
+    { label: "connect GitHub + create the private repo", skipped: "GitHub is already connected and every org has its repository" },
+];
+/**
+ * The step a rung belongs to. `first_sync` comes AFTER step 3 (null: it opens
+ * no step, but reaching it means steps 2 and 3 needed nothing); `done` and
+ * `web_only` open none.
+ */
+export function stepOfRung(kind) {
+    if (kind === "connect_salesforce")
+        return 2;
+    if (kind === "connect_github" || kind === "bind_repo")
+        return 3;
+    return null;
+}
+/**
+ * Prints "Step n/3: <label>" the first time a step is entered and "Step n/3:
+ * skipped — <why>" for every earlier step the run never entered. `current()` is
+ * the step a rerun would be at (N14).
+ */
+export function createStepTracker(writer) {
+    let at = 0;
+    const total = SETUP_STEPS.length;
+    const skipTo = (step) => {
+        for (let n = at + 1; n < step; n++)
+            writer.out(`Step ${n}/${total}: skipped — ${SETUP_STEPS[n - 1].skipped}`);
+    };
+    return {
+        current: () => Math.min(Math.max(at, 1), total),
+        enter(step) {
+            if (step <= at)
+                return;
+            skipTo(step);
+            writer.out(`Step ${step}/${total}: ${SETUP_STEPS[step - 1].label}`);
+            at = step;
+        },
+        skip(step, why) {
+            if (step <= at)
+                return;
+            skipTo(step);
+            writer.out(`Step ${step}/${total}: skipped — ${why}`);
+            at = step;
+        },
+        /** Past the last step (the first sync): every step not entered is reported skipped. */
+        finishSteps() {
+            skipTo(total + 1);
+            at = Math.max(at, total);
+        },
+    };
+}
+/**
+ * Card eecc9d6f N4 — printed once, before the first wait on the browser. The
+ * numbers are the code's own bounds: the device code's TTL ceiling and the link
+ * step's wait budget. `loginSeconds` is null when this run will NOT log in (step
+ * 1 skipped, G9a): the notice then names only the links.
+ */
+export function browserWaitNotice(loginSeconds) {
+    const links = `up to ${minutesSpan(LINK_POLL_MAX_MS / 1000)} for each link`;
+    return (`Setup waits on your browser: ${loginSeconds === null ? links : `up to ${minutesSpan(loginSeconds)} to approve the login, and ${links}`}. ` +
+        "Keep this command running; if it stops, rerun `flowsprite setup` and it continues from the checklist's current step.");
+}
+/** Card eecc9d6f N14 — the last line of every `setup` run that does not succeed. */
+export function rerunHint(login, step) {
+    const where = `it picks up at step ${step} (or later, if you finish that step in the browser first)`;
+    if (login === "stored")
+        return `Rerun \`flowsprite setup\` to continue — your login is saved, and ${where}.`;
+    if (login === "supplied") {
+        return `Rerun \`flowsprite setup\` with the same --token or FLOWSPRITE_TOKEN to continue (nothing was saved; \`flowsprite login --token <t> --save\` stores it) — ${where}.`;
+    }
+    return "Rerun `flowsprite setup` to continue — it starts at step 1, logging this terminal in.";
+}
 /** The `purpose` a minted link carries in `pendingLinks` — the set is `convex/setupLinks.ts purposeValidator`. */
 const LINK_PURPOSE = {
     salesforce: "salesforce_connect",
@@ -210,8 +306,7 @@ export function idsOf(provider, status) {
  * THE RULE: the writer keeps newlines for whole documents and multi-line
  * refusals; a field spliced INTO a sentence is scrubbed here, or a newline in
  * it forges a line (driven: a displayName "Acme\nDone." printed an exact
- * `Done.` line). `instructions` and `nextAction.text` are whole-field prints
- * and stay as they are.
+ * `Done.` line). `nextAction.text` is a whole-field print and stays as it is.
  */
 function connectedNames(provider, status) {
     const root = asObject(status);
@@ -274,7 +369,7 @@ export async function runLinkStep(deps, tool, args, provider, before) {
         return { kind: "failed", message: minted.message };
     const payload = asObject(toolJson(minted));
     if (payload === null || typeof payload.url !== "string") {
-        return { kind: "failed", message: `${tool} did not return a link.` };
+        return { kind: "failed", message: "Flowsprite did not return a link for this step. Run `flowsprite status` and try again." };
     }
     const url = payload.url;
     const expiresAt = typeof payload.expiresAt === "number" ? payload.expiresAt : null;
@@ -290,10 +385,11 @@ export async function runLinkStep(deps, tool, args, provider, before) {
     const skew = expiresAt === null || ttlMs === null ? null : expiresAt - ttlMs - mintedAt;
     /** `now` on the server's clock, as far as the mint let us measure it. */
     const serverNow = (now) => now + (skew ?? 0);
-    deps.writer.out(`Open this link in a browser where you are signed in to Flowsprite:`);
-    deps.writer.out(`  ${printable(url)}`);
-    if (typeof payload.instructions === "string")
-        deps.writer.out(payload.instructions);
+    const expiresInSeconds = typeof payload.expiresInSeconds === "number" && payload.expiresInSeconds > 0
+        ? payload.expiresInSeconds
+        : null;
+    for (const line of linkInstructions(url, expiresInSeconds))
+        deps.writer.out(line);
     deps.writer.out("Waiting for you to finish in the browser...");
     let used = false;
     const deadline = deps.now() + LINK_POLL_MAX_MS;
@@ -339,6 +435,10 @@ export async function runLinkStep(deps, tool, args, provider, before) {
             return { kind: "expired", used };
         if (now >= deadline)
             return { kind: "timeout", used };
+        // C8: the link's own expiry by the server's clock when the mint named one,
+        // else the CLI's wait budget — whichever this step will actually stop at.
+        const leftMs = expiresAt === null ? deadline - now : Math.min(expiresAt - serverNow(now), deadline - now);
+        deps.progress?.(`Link expires in ${clock(leftMs / 1000)}`);
     }
 }
 // ---------------------------------------------------------- repository creation