flowsprite 0.1.3 → 0.1.4

package/dist/cli.js

@@ -1,15 +1,17 @@
 import { homedir } from "node:os";
 import { parseArgs } from "node:util";
-import { credentialsPath, deleteCredential, readCredentials, resolveToken, writeCredential, } from "./credentials.js";
-import { formatDoctor, MIN_NODE_MAJOR, nodeMajor } from "./doctor.js";
+import { clearPendingLogin, credentialsPath, deleteCredential, readCredentials, readPendingLogin, resolveToken, writeCredential, writePendingLogin, } from "./credentials.js";
+import { doctorOk, formatDoctor, MIN_NODE_MAJOR, nodeMajor } from "./doctor.js";
 import { parseEndpoint } from "./endpoint.js";
 import { deviceCodeLogin, ghCliLogin } from "./login.js";
 import { createMcpClient, toolJson } from "./mcpClient.js";
 import { jsonConfigHasServer, McpConfigError, SERVER_NAME, tomlConfigHasServer, upsertJsonConfig, } from "./mcpConfig.js";
 import { CLIENTS, commandFor, configPathFor, isClientId, planInstall, renderSnippet, TOKEN_PLACEHOLDER, } from "./mcpInstall.js";
+import { SAME_ACCOUNT_NOTE } from "./messages.js";
 import { printable, redact } from "./redact.js";
-import { asArray, asObject, planBindArgs, planNextStep, rungConnectionIds, runLinkStep, waitForRepository, } from "./setup.js";
-import { doorRefusalSentence, FROM_SF_CLI_EXCLUSIVE, parseSfOrgDisplay, projectDoorResult, scrubForceUrls, SF_ALIAS_RE, SF_ALIAS_RULE, sfLoginLine, sfRelogin, sfRemedy, } from "./sfCli.js";
+import { asArray, asObject, browserWaitNotice, createStepTracker, planBindArgs, planNextStep, rerunHint, rungConnectionIds, runLinkStep, stepOfRung, waitForRepository, } from "./setup.js";
+import { MAX_EXPIRES_IN_SECONDS } from "./ghLogin.js";
+import { doorRefusalSentence, FROM_SF_CLI_EXCLUSIVE, parseSfAuthUrl, projectDoorResult, scrubForceUrls, SF_ALIAS_RE, SF_ALIAS_RULE, SF_TOO_OLD_REMEDY, sfLoginLine, sfRelogin, sfRemedy, } from "./sfCli.js";
 import { renderStatus } from "./status.js";
 import { USAGE } from "./usage.js";
 /**
@@ -26,7 +28,8 @@ import { USAGE } from "./usage.js";
 export const EXIT_OK = 0;
 export const EXIT_FAILED = 1;
 export const EXIT_USAGE = 2;
-const OPTIONS = {
+/** The parser's option table — exported so usage.test.ts can prove USAGE names every flag. */
+export const OPTIONS = {
     endpoint: { type: "string" },
     json: { type: "boolean" },
     token: { type: "string" },
@@ -176,6 +179,7 @@ async function cmdLogin(deps, origin, values) {
         version: deps.version,
         ...(values["no-open"] === true || deps.openUrl === undefined ? {} : { openUrl: deps.openUrl }),
         ...(deps.progress === undefined ? {} : { progress: deps.progress }),
+        pending: pendingLoginPort(deps, origin),
     };
     // FLO-517: the gh road first, unless opted out. Null means it fell to the
     // browser login at its own start, having said why in one line.
@@ -201,7 +205,9 @@ async function cmdLogin(deps, origin, values) {
         savedAt: deps.now(),
     };
     // The token is NOT in this sentence, and the writer would redact it anyway.
-    const who = `Logged in to ${origin} as ${result.userId} in workspace ${result.orgId}`;
+    // C4: the email and workspace name are DISPLAY ONLY — scrubbed in login.ts,
+    // and never in `cred` above, so they are never stored.
+    const who = `Logged in to ${origin} as ${result.userEmail ?? result.userId} in workspace ${result.orgName ?? result.orgId}`;
     try {
         writeCredential(deps.env, origin, cred, deps.home);
     }
@@ -224,37 +230,90 @@ async function cmdLogin(deps, origin, values) {
         return EXIT_FAILED;
     }
     deps.writer.out(who);
+    deps.writer.out(SAME_ACCOUNT_NOTE);
     return EXIT_OK;
 }
+/**
+ * C3 — the pending device login for THIS origin, kept in `pending-login.json`
+ * beside the credential store (0600, see `credentials.ts`). The clock lives here
+ * so `login.ts` stays clock-free: it is handed seconds LEFT and hands back the
+ * payload's own TTL.
+ */
+function pendingLoginPort(deps, origin) {
+    return {
+        load: () => {
+            const saved = readPendingLogin(deps.env, origin, deps.now(), deps.home);
+            if (saved === null)
+                return null;
+            return {
+                deviceCode: saved.deviceCode,
+                ...(saved.userCode === null || saved.openTarget === null
+                    ? {}
+                    : { userCode: saved.userCode, openTarget: saved.openTarget }),
+                expiresIn: Math.ceil((saved.expiresAtMs - deps.now()) / 1000),
+                interval: saved.interval,
+            };
+        },
+        save: (p) => writePendingLogin(deps.env, {
+            origin,
+            deviceCode: p.deviceCode,
+            userCode: p.userCode ?? null,
+            openTarget: p.openTarget ?? null,
+            expiresAtMs: deps.now() + p.expiresIn * 1000,
+            savedAtMs: deps.now(),
+            interval: p.interval,
+        }, deps.home),
+        clear: (deviceCode) => clearPendingLogin(deps.env, origin, deps.home, deviceCode),
+    };
+}
 function cmdLogout(deps, origin) {
+    // C3: a half-finished login goes too, so the next `login` starts fresh. Best
+    // effort: an undeletable file must not turn a logout into a crash. No device
+    // code is named (G2): logout drops whatever is pending for this origin.
+    try {
+        clearPendingLogin(deps.env, origin, deps.home);
+    }
+    catch {
+        // The credential removal below is what logout promises; this is housekeeping.
+    }
     const removed = deleteCredential(deps.env, origin, deps.home);
     deps.writer.out(removed ? `Logged out of ${origin}.` : `There was no stored credential for ${origin}.`);
     return EXIT_OK;
 }
 async function cmdDoctor(deps, origin, values) {
     const stored = readCredentials(deps.env, deps.home)[origin];
-    let reachable = false;
-    let detail = "no credential, so reachability was not tested";
-    const built = clientForQuiet(deps, origin, values, stored?.token);
-    if (built !== null) {
-        const probe = await built.initialize();
-        reachable = probe.ok;
-        // `initialize` is the reachability probe (DM2). An `unauthorized` answer
-        // still proves the endpoint is THERE — it is reported as its own line rather
-        // than folded into "unreachable", which would send someone to check DNS.
-        detail = probe.ok ? "reachable" : `${probe.kind}: ${probe.message}`;
-    }
-    const report = {
+    const token = resolveToken({
+        flag: typeof values.token === "string" ? values.token : undefined,
+        env: deps.env.FLOWSPRITE_TOKEN,
+        stored: stored?.token,
+    });
+    // N7: the endpoint is probed WITH OR WITHOUT a credential — `initialize` with
+    // an empty bearer. HEALTHY is exactly two answers (G8): a successful
+    // `initialize`, or a 401 (`unauthorized` — the auth layer answered, the
+    // credential is the problem or is absent). Anything else — no answer, a body
+    // that is not JSON-RPC, a JSON-RPC error, a tool error — FAILS the endpoint.
+    const probe = await createMcpClient({ origin, token: token?.token ?? "", fetch: deps.fetch, version: deps.version }).initialize();
+    const unauthorized = !probe.ok && probe.kind === "unauthorized";
+    const reachable = probe.ok || unauthorized;
+    const detail = probe.ok || (token !== null && unauthorized)
+        ? "reachable"
+        : unauthorized
+            ? "reachable (it answered HTTP 401 to a request with no credential, as it should)"
+            : `${probe.kind}: ${probe.message}`;
+    const checks = {
         nodeVersion: deps.nodeVersion,
         nodeOk: nodeMajor(deps.nodeVersion) >= MIN_NODE_MAJOR,
         endpoint: origin,
         endpointReachable: reachable,
         endpointDetail: detail,
-        hasCredential: stored !== undefined,
+        hasCredential: token !== null,
+        credentialSource: token?.source ?? null,
+        credentialRefused: token !== null && unauthorized,
         credentialsPath: credentialsPath(deps.env, deps.home),
         sfOnPath: deps.isOnPath("sf"),
         ghOnPath: deps.isOnPath("gh"),
     };
+    const report = { ...checks, ok: doctorOk(checks) };
     if (values.json === true) {
         deps.writer.out(JSON.stringify(report, null, 2));
     }
@@ -262,18 +321,8 @@ async function cmdDoctor(deps, origin, values) {
         for (const line of formatDoctor(report))
             deps.writer.out(line);
     }
-    return report.nodeOk ? EXIT_OK : EXIT_FAILED;
-}
-/** Like `clientFor` but silent and optional — doctor reports absence, it does not refuse. */
-function clientForQuiet(deps, origin, values, storedToken) {
-    const token = resolveToken({
-        flag: typeof values.token === "string" ? values.token : undefined,
-        env: deps.env.FLOWSPRITE_TOKEN,
-        stored: storedToken,
-    });
-    if (token === null)
-        return null;
-    return createMcpClient({ origin, token: token.token, fetch: deps.fetch, version: deps.version });
+    // N16: exit 1 iff any check FAILs (see `doctorOk`); sf/gh are notes only.
+    return report.ok ? EXIT_OK : EXIT_FAILED;
 }
 async function fetchStatus(deps, client) {
     const result = await client.callTool("setup_status", {});
@@ -302,7 +351,14 @@ async function cmdStatus(deps, origin, values) {
     return EXIT_OK;
 }
 function setupDeps(deps, client) {
-    return { client, writer: deps.writer, sleep: deps.sleep, now: deps.now };
+    return {
+        client,
+        writer: deps.writer,
+        sleep: deps.sleep,
+        now: deps.now,
+        // C8: the setup-link countdown shares the login's status line — a terminal only.
+        ...(deps.progress === undefined ? {} : { progress: deps.progress }),
+    };
 }
 async function cmdConnect(deps, origin, values, which) {
     if (which !== "salesforce" && which !== "github") {
@@ -322,10 +378,48 @@ async function cmdConnect(deps, origin, values, which) {
     // (card A3, blocked), which would use a token the person already holds
     // instead of an app install. The Salesforce one is `connectFromSfCli` above.
     const args = which === "salesforce" ? salesforceLinkArgs(values) : {};
-    // No pre-mint snapshot is passed: the link step reads one itself, so `done`
-    // means a NEW connection or installation, never "the ladder is elsewhere".
-    const outcome = await runLinkStep(setupDeps(deps, built.client), tool, args, which);
-    return reportLinkOutcome(deps.writer, outcome, which);
+    // The pre-mint snapshot is read HERE (it was read inside the link step before
+    // N1) so the used-but-no-new-id outcome can compare "connected" before and
+    // after. `done` still means a NEW connection or installation.
+    const before = await fetchStatus(deps, built.client);
+    if (!before.ok)
+        return EXIT_FAILED;
+    const outcome = await runLinkStep(setupDeps(deps, built.client), tool, args, which, before.payload);
+    return await settleLinkOutcome(deps, built.client, outcome, which, before.payload);
+}
+/** `workspace.<provider>.connected === true` in a `setup_status` payload — strictly true. */
+function providerConnected(status, provider) {
+    return asObject(asObject(asObject(status)?.workspace)?.[provider])?.connected === true;
+}
+/**
+ * Card eecc9d6f N1 — a link that was USED but produced no NEW id. The success
+ * sentence is NEUTRAL (G7): "is connected" is what the read shows; whether a row
+ * was refreshed or newly made is not something this read can tell. Re-authorizing
+ * a connection Flowsprite already had a row for refreshes that row, so no new id
+ * appears even when the person did exactly the right thing. The rule: the step
+ * SUCCEEDED iff the provider was NOT connected in the pre-mint snapshot and IS
+ * connected now — the link changed the answer. (Connected BEFORE as well is the
+ * second-org case, which stays the old "used, but nothing new" failure: nothing
+ * shows this link did anything.) Applied to both providers: the GitHub link step
+ * shares this exact outcome path.
+ */
+async function settleLinkOutcome(deps, client, outcome, provider, before) {
+    if ((outcome.kind === "expired" || outcome.kind === "timeout") && outcome.used && !providerConnected(before, provider)) {
+        const read = await client.callTool("setup_status", {});
+        if (read.ok && providerConnected(toolJson(read), provider)) {
+            deps.writer.out(provider === "salesforce"
+                ? "Salesforce is connected."
+                : "GitHub is connected.");
+            return EXIT_OK;
+        }
+        if (read.ok) {
+            deps.writer.err(provider === "salesforce"
+                ? "The link was opened, but Salesforce is still not connected to this workspace — the Salesforce sign-in did not complete a connection. Run the command again for a fresh link."
+                : "The link was opened, but GitHub is still not connected to this workspace — the app install did not complete. Run the command again for a fresh link.");
+            return EXIT_FAILED;
+        }
+    }
+    return reportLinkOutcome(deps.writer, outcome, provider);
 }
 /**
  * `flowsprite connect salesforce --from-sf-cli <alias>` (FLO-515): read the
@@ -341,11 +435,34 @@ async function cmdConnect(deps, origin, values, which) {
  * function's source for `fs` / `console` identifiers: the writer and the
  * tools/call body are its only sinks.
  *
+ * WHICH COMMAND, and why it changed (card 263cefa5, 2026-09-20): ONE spawn of
+ * `sf org auth show-sfdx-auth-url --target-org <alias> --json`, whose stdout
+ * under `--json` is `{status, result:{sfdxAuthUrl}, warnings}` — no
+ * accessToken, no password, no clientId. The command's own "this exposes an
+ * SFDX Auth URL" warning lands BOTH in that `warnings` array and on stderr
+ * (sf-plugins-core `toSuccessJson`/`warn`, measured against 12.2.6), and this
+ * CLI prints neither. What IS read off that envelope: `status` (to tell a
+ * success from an error), the identifier-shaped `name` on a non-zero one (the
+ * error CLASS, printed; never its free text), and `result.sfdxAuthUrl` — the
+ * only one of the three that is a credential, and it is read into one scope
+ * and never printed. FLO-515 read the login from `sf org display --verbose --json`,
+ * and sf 2.147.0 (published 2026-07-31) bundles a @salesforce/plugin-org that
+ * redacts `sfdxAuthUrl` there behind a placeholder unless a
+ * documented-temporary env var is set — so on sf 2.150.6 a good web login was
+ * answered with the logout-then-login remedy (measured in UAT, 2026-09-20).
+ * The stable command ships in the same plugin version and needs no env var,
+ * which is why this door passes NO third argument to `deps.spawn` and overlays
+ * no environment on the child.
+ *
  * Refusals BEFORE the network, in this order: the flag exclusivity (DM5), the
  * alias rule (DM4), `sf` on PATH (DM3: install lines, never an auto-install),
- * the stored credential, then the spawn's own failure and the envelope's shape
- * (DM2: a JWT or empty-client login is refused here with the alias-bearing
- * remedy rather than round-tripped to a server that would refuse it anyway).
+ * the stored credential, the spawn's own failure, an `sf` too old to have the
+ * command (263cefa5 DM2), sf's own non-zero exit (which is where a login with
+ * no refresh token lands: the command throws rather than answering with a url,
+ * so a JWT or access-token login is refused HERE and not by the url check
+ * below), then the envelope's shape (DM2: an empty-client or other-app url is
+ * refused here with the alias-bearing remedy rather than round-tripped to a
+ * server that would refuse it anyway).
  */
 async function connectFromSfCli(deps, origin, values, alias) {
     if (values.sandbox === true || typeof values["my-domain"] === "string") {
@@ -373,8 +490,8 @@ async function connectFromSfCli(deps, origin, values, alias) {
     // construction because SF_ALIAS_RE (checked above) admits no quote, space or
     // shell metacharacter, so the alias cannot end the command or start another.
     const run = win32
-        ? await deps.spawn("cmd.exe", ["/d", "/s", "/c", "sf org display --verbose --json --target-org " + alias])
-        : await deps.spawn("sf", ["org", "display", "--verbose", "--json", "--target-org", alias]);
+        ? await deps.spawn("cmd.exe", ["/d", "/s", "/c", "sf org auth show-sfdx-auth-url --target-org " + alias + " --json"])
+        : await deps.spawn("sf", ["org", "auth", "show-sfdx-auth-url", "--target-org", alias, "--json"]);
     const spawnError = run.error !== undefined && run.error !== null;
     // On win32 "sf is not installed" arrives two ways, both the install remedy
     // the PATH probe gives elsewhere: cmd.exe itself could not start (a spawn
@@ -389,30 +506,57 @@ async function connectFromSfCli(deps, origin, values, alias) {
         return EXIT_USAGE;
     }
     if (spawnError) {
-        deps.writer.err(`sf org display could not be run for '${alias}'. Is that org logged in? ${sfLoginLine(alias)}`);
+        deps.writer.err(`sf org auth show-sfdx-auth-url could not be run for '${alias}'. Is that org logged in? ${sfLoginLine(alias)}`);
+        return EXIT_FAILED;
+    }
+    const parsed = parseSfAuthUrl(run.stdout ?? "");
+    // THE RULE: exit 127 with NO JSON envelope on stdout is READ AS "this `sf`
+    // lacks the subcommand", i.e. it predates 2.147.0. That is an operational
+    // classification, not a proven cause: a missing subcommand is the only shape
+    // measured to produce it, on sf 2.127.2 (2026-09-20), in both its forms — a
+    // clean shell gives rc 127 with EMPTY stdout and "is not a sf command" on
+    // stderr, and the SAME run under `DEBUG=sf:*` gives rc 127 with ~2.5 KB
+    // (2509-2510 bytes across runs; a timestamp digit) of debug noise on stdout
+    // carrying zero `{` characters and absolute filesystem paths, a second
+    // reason never to print it. So the test is "did anything parse", not "was
+    // stdout empty" — fix round 1 F1: the empty-stdout form sent a debug shell
+    // down the logged-out remedy, this card's own defect class. Exit 127 that DOES carry an envelope is not this
+    // arm; it falls to the generic non-zero arm below and is named from its
+    // `name`. The remedy here is to update sf, never to log in again, so this
+    // sentence carries neither the login line nor sf's own stderr. It must sit
+    // above the generic non-zero arm, which would otherwise swallow it.
+    if (run.status === 127 && !parsed.ok && parsed.reason === "not_json") {
+        deps.writer.err(SF_TOO_OLD_REMEDY);
         return EXIT_FAILED;
     }
-    const parsed = parseSfOrgDisplay(run.stdout ?? "");
     if (run.status !== 0) {
-        // sf's JSON error envelope names an error CLASS (`NamedOrgNotFoundError`
-        // for a logged-out alias, exit 2); that identifier is printed, its free
-        // text and stderr never are.
+        // sf's JSON error envelope names an error CLASS. `NamedOrgNotFoundError`
+        // for a logged-out alias at exit 2 is MEASURED (sf 2.127.2, via the shared
+        // `Flags.requiredOrg()` resolution). For a JWT or access-token login the
+        // command throws instead of answering with a url — so that login lands
+        // HERE rather than in the `no_url` arm below — and the card's NC-3 reads
+        // plugin-org 6.0.11 as throwing `error.noRefreshToken` there, i.e. a name
+        // such as `NoRefreshTokenError`; UNVERIFIED on this box, which has
+        // plugin-org 5.9.71 and no `org/auth` command at all. Nothing depends on
+        // the spelling: whatever identifier-shaped `name` arrives is printed, and
+        // its free text, `actions` and stderr never are.
         const named = !parsed.ok && parsed.reason === "status" && parsed.message !== "";
         const what = named ? `reported ${parsed.message}` : `failed for '${alias}'`;
-        deps.writer.err(`sf org display ${what} (exit ${run.status ?? "by signal"}). Is that org logged in? ${sfLoginLine(alias)}`);
+        deps.writer.err(`sf org auth show-sfdx-auth-url ${what} (exit ${run.status ?? "by signal"}). Is that org logged in? ${sfLoginLine(alias)}`);
         return EXIT_FAILED;
     }
     if (!parsed.ok) {
         switch (parsed.reason) {
             case "not_json":
-                deps.writer.err(`sf org display did not return its JSON. ${sfLoginLine(alias)}`);
+                deps.writer.err(`sf org auth show-sfdx-auth-url did not return its JSON. ${sfLoginLine(alias)}`);
                 break;
             case "status":
-                deps.writer.err(`sf org display reported ${parsed.message || "an error"}. ${sfLoginLine(alias)}`);
+                deps.writer.err(`sf org auth show-sfdx-auth-url reported ${parsed.message || "an error"}. ${sfLoginLine(alias)}`);
                 break;
             default:
-                // `no_url` (a JWT login, or an older auth file with an empty client id)
-                // and `client` (another connected app): the server would refuse both.
+                // `no_url`: no url in the envelope, a non-string one, another connected
+                // app's (`force://Other::…`) or an older auth file's empty client id
+                // (`force://:…`) — the server door would refuse every one of them.
                 deps.writer.err("That sf login cannot be handed over: only the Salesforce CLI's default connected app (PlatformCLI) " +
                     `with a web login works. ${sfRelogin(alias)}`);
         }
@@ -439,7 +583,7 @@ async function connectFromSfCli(deps, origin, values, alias) {
     }
     const doc = projectDoorResult(toolJson(res));
     if (doc === null) {
-        deps.writer.err("Unexpected reply from setup_connect_salesforce_cli.");
+        deps.writer.err("Flowsprite sent an unexpected reply while connecting that Salesforce CLI login.");
         return EXIT_FAILED;
     }
     if (values.json === true)
@@ -835,21 +979,68 @@ async function runSync(deps, values, client, rung) {
  * it is a backstop, not a budget.
  */
 const MAX_SETUP_RUNGS = 24;
+/** Which login `setup` would use, in words, or null when there is none (N3 step 1). */
+function loginInWords(deps, origin, values) {
+    const stored = readCredentials(deps.env, deps.home)[origin];
+    const token = resolveToken({
+        flag: typeof values.token === "string" ? values.token : undefined,
+        env: deps.env.FLOWSPRITE_TOKEN,
+        stored: stored?.token,
+    });
+    if (token === null)
+        return null;
+    if (token.source !== "stored")
+        return `using the token from ${token.source}`;
+    // The stored ids are what the file holds (C4: names are never stored).
+    return stored !== undefined && stored.userId.length > 0
+        ? `already logged in as ${stored.userId} in workspace ${stored.orgId}`
+        : "already logged in with a saved token";
+}
 async function cmdSetup(deps, origin, values) {
     // Doctor-lite: the two things that make every later step fail confusingly.
     if (nodeMajor(deps.nodeVersion) < MIN_NODE_MAJOR) {
         deps.writer.err(`flowsprite needs node ${MIN_NODE_MAJOR} or newer; this is ${deps.nodeVersion}.`);
         return EXIT_FAILED;
     }
-    if (readCredentials(deps.env, deps.home)[origin] === undefined && resolveToken({
-        flag: typeof values.token === "string" ? values.token : undefined,
-        env: deps.env.FLOWSPRITE_TOKEN,
-    }) === null) {
+    const steps = createStepTracker(deps.writer);
+    const rc = await runSetup(deps, origin, values, steps);
+    // N14: EVERY non-success exit past the node check ends with how to continue.
+    // No new state: a rerun re-derives its step from setup_status.
+    if (rc !== EXIT_OK)
+        deps.writer.err(rerunHint(rerunLogin(deps, origin, values), steps.current()));
+    return rc;
+}
+/** G6: what a rerun would log in with — a saved credential is claimed only when one is stored. */
+function rerunLogin(deps, origin, values) {
+    // H2: an explicit token wins for THIS run, so a plain rerun would use a
+    // different login (the stored one, or none) — say "supplied" whatever is stored.
+    const flag = typeof values.token === "string" && values.token.length > 0;
+    const env = typeof deps.env.FLOWSPRITE_TOKEN === "string" && deps.env.FLOWSPRITE_TOKEN.length > 0;
+    if (flag || env)
+        return "supplied";
+    return readCredentials(deps.env, deps.home)[origin] !== undefined ? "stored" : "none";
+}
+async function runSetup(deps, origin, values, steps) {
+    let noticePrinted = false;
+    const login = loginInWords(deps, origin, values);
+    /** N4: once, before the first thing that waits on the browser — naming only what this run waits on (G9a). */
+    const browserNotice = () => {
+        if (noticePrinted)
+            return;
+        noticePrinted = true;
+        deps.writer.out(browserWaitNotice(login === null ? MAX_EXPIRES_IN_SECONDS : null));
+    };
+    if (login === null) {
         deps.writer.out(`Not logged in to ${origin} yet.`);
+        browserNotice();
+        steps.enter(1);
         const rc = await cmdLogin(deps, origin, values);
         if (rc !== EXIT_OK)
             return rc;
     }
+    else {
+        steps.skip(1, login);
+    }
     const built = clientFor(deps, origin, values);
     if (!built.ok)
         return EXIT_FAILED;
@@ -871,14 +1062,15 @@ async function cmdSetup(deps, origin, values) {
      * even when a volatile field makes two payloads differ.
      */
     let previousStatus = null;
-    let previousTool = null;
+    /** C7: the step that just ran, in words — the tool name is MCP vocabulary, not a terminal user's. */
+    let previousStep = null;
     for (let rungs = 0;; rungs++) {
         const status = await fetchStatus(deps, built.client);
         if (!status.ok)
             return EXIT_FAILED;
         const serialized = JSON.stringify(status.payload) ?? "";
-        if (previousTool !== null && serialized === previousStatus) {
-            deps.writer.err(`\`${previousTool}\` reported success, but this workspace's setup status did not change. ` +
+        if (previousStep !== null && serialized === previousStatus) {
+            deps.writer.err(`${previousStep} reported success, but this workspace's setup status did not change. ` +
                 "Stopping rather than repeating it: the setup steps are list-wide, so a step that does not " +
                 "move the checklist would repeat forever. Run `flowsprite status` to see what is left.");
             return EXIT_FAILED;
@@ -889,6 +1081,11 @@ async function cmdSetup(deps, origin, values) {
         }
         previousStatus = serialized;
         const step = planNextStep(status.payload);
+        const stepNumber = stepOfRung(step.kind);
+        if (stepNumber !== null)
+            steps.enter(stepNumber);
+        else if (step.kind === "first_sync")
+            steps.finishSteps();
         switch (step.kind) {
             case "done":
                 deps.writer.out("Setup is complete.");
@@ -910,10 +1107,11 @@ async function cmdSetup(deps, origin, values) {
                 // The payload just read IS the pre-mint snapshot: the rung is done when a
                 // NEW connection / installation appears in it, and the identity check at
                 // the top of the loop then sees the ladder move on that same new row.
-                const rc = reportLinkOutcome(deps.writer, await runLinkStep(sdeps, tool, args, provider, status.payload), provider);
+                browserNotice();
+                const rc = await settleLinkOutcome(deps, built.client, await runLinkStep(sdeps, tool, args, provider, status.payload), provider, status.payload);
                 if (rc !== EXIT_OK)
                     return rc;
-                previousTool = tool;
+                previousStep = provider === "salesforce" ? "Connecting Salesforce" : "Connecting GitHub";
                 break;
             }
             default: {
@@ -948,7 +1146,7 @@ async function cmdSetup(deps, origin, values) {
                     : await runSync(deps, values, built.client, rung);
                 if (rc !== EXIT_OK)
                     return rc;
-                previousTool = step.kind === "bind_repo" ? "setup_bind_repo" : "sfdc_trigger_sync";
+                previousStep = step.kind === "bind_repo" ? "Binding a repository" : "Starting the first sync";
                 break;
             }
         }

package/dist/credentials.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { approvePageHref, MAX_EXPIRES_IN_SECONDS, USER_CODE_RE } from "./ghLogin.js";
 export const CREDENTIALS_FILE = "credentials.json";
 const DIR_MODE = 0o700;
 const FILE_MODE = 0o600;
@@ -175,6 +176,113 @@ export function deleteCredential(env, origin, home) {
     writeStore(env, store, home);
     return true;
 }
+// ------------------------------------------------------- the pending login (C3)
+export const PENDING_LOGIN_FILE = "pending-login.json";
+export function pendingLoginPath(env, home) {
+    return join(credentialsDir(env, home), PENDING_LOGIN_FILE);
+}
+const nonEmpty = (v) => typeof v === "string" && v.length > 0;
+/**
+ * The pending login for `origin`, or null. TOLERANT like `readCredentials`: a
+ * missing, unreadable, garbled or wrong-shaped file, or one for another origin,
+ * reads as "none". An EXPIRED entry for this origin is deleted as it is read.
+ *
+ * Held to the WIRE's grammar (eecc9d6f G5): the user code is `USER_CODE_RE`'s
+ * shape and the open target must pass `approvePageHref` — exactly this origin's
+ * approve page, normalised — so a hand-edited file can make `login` print or
+ * open nothing the start route could not have sent. The interval must be finite.
+ */
+export function readPendingLogin(env, origin, now, home) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(pendingLoginPath(env, home), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return null;
+    const v = parsed;
+    if (v.origin !== origin || !nonEmpty(v.deviceCode))
+        return null;
+    if (typeof v.expiresAtMs !== "number" || !Number.isFinite(v.expiresAtMs))
+        return null;
+    if (typeof v.savedAtMs !== "number" || !Number.isFinite(v.savedAtMs))
+        return null;
+    if (typeof v.interval !== "number" || !Number.isFinite(v.interval) || !(v.interval > 0))
+        return null;
+    const userCode = nonEmpty(v.userCode) ? v.userCode : null;
+    const rawTarget = nonEmpty(v.openTarget) ? v.openTarget : null;
+    if ((userCode === null) !== (rawTarget === null))
+        return null;
+    let openTarget = null;
+    if (userCode !== null) {
+        if (!USER_CODE_RE.test(userCode))
+            return null;
+        openTarget = approvePageHref(rawTarget, origin, userCode);
+        if (openTarget === null)
+            return null;
+    }
+    // H1/H6: no entry is live past min(its write, now) + a code's TTL. A savedAt
+    // LATER than now is not rejected — a backward clock step (NTP, resume from
+    // suspend) must not abandon a live, maybe already approved, code — it is read
+    // as now. So a future-dated forged file lives at most now + 900 s per read, and
+    // is ended by the poll answer anyway (`expired_token`/`invalid_*` clear it).
+    const effectiveSavedAt = Math.min(v.savedAtMs, now);
+    const expiresAtMs = Math.min(v.expiresAtMs, effectiveSavedAt + MAX_EXPIRES_IN_SECONDS * 1000);
+    if (expiresAtMs <= now) {
+        try {
+            clearPendingLogin(env, origin, home, v.deviceCode);
+        }
+        catch {
+            // An undeletable expired entry still reads as none; the next write replaces it.
+        }
+        return null;
+    }
+    return { origin, deviceCode: v.deviceCode, userCode, openTarget, expiresAtMs, savedAtMs: v.savedAtMs, interval: v.interval };
+}
+/** Throws on a write failure; the caller (`login.ts`) treats that as "not persisted", never as a failed login. */
+export function writePendingLogin(env, entry, home) {
+    const dir = credentialsDir(env, home);
+    mkdirSync(dir, { recursive: true, mode: DIR_MODE });
+    chmodSync(dir, DIR_MODE);
+    writeFileAtomic(pendingLoginPath(env, home), `${JSON.stringify(entry)}\n`, FILE_MODE);
+}
+/**
+ * Delete the pending login if it is `origin`'s — or if it cannot be read as
+ * anyone's (garbled), since nothing can resume it. Another origin's entry is
+ * left alone. `rmSync` on a symlink removes the link, never its target.
+ *
+ * eecc9d6f G2: given a `deviceCode`, ONLY an entry holding exactly that code is
+ * deleted (a garbled file is then left for the next write to replace), so a
+ * stale run that ends cannot delete the entry a NEWER run saved. `logout` calls
+ * it without one: logging out drops whatever is pending for the origin.
+ */
+// ponytail: read-then-unlink, not an atomic compare-and-delete — node builtins have
+// none across processes. The window is the microseconds between the read and the
+// `rmSync`, open only to another `flowsprite` run of the SAME user saving a newer
+// entry in exactly that gap; the loser just starts a fresh login next time. A
+// lock file (O_EXCL) around save/clear is the upgrade if that ever matters.
+export function clearPendingLogin(env, origin, home, deviceCode) {
+    const path = pendingLoginPath(env, home);
+    let stored;
+    try {
+        stored = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        stored = null;
+    }
+    const readable = typeof stored === "object" && stored !== null && typeof stored.origin === "string";
+    if (deviceCode !== undefined) {
+        if (readable && stored.origin === origin && stored.deviceCode === deviceCode)
+            rmSync(path, { force: true });
+        return;
+    }
+    if (!readable || stored.origin === origin)
+        rmSync(path, { force: true });
+}
 /**
  * Which token this invocation uses: an explicit `--token`, else
  * `FLOWSPRITE_TOKEN`, else the credential stored for this origin. The stored one