scenescout 3.13.1 → 3.14.1

package/dist/cli.js

@@ -8,6 +8,7 @@
  *   scenescout doctor               Check every piece of the setup and say how to fix what is missing
  *   scenescout check <url>          Visit every route, measure it, and pass or fail (no model involved)
  *   scenescout ci <url>             An exploratory run driven by a model's API, unattended, that reports
+ *   scenescout login <url> --role r Sign in once in a visible browser and save it as a named role
  */
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
@@ -20,11 +21,15 @@ import { CLIENT_LABELS, firstMessageHint, manualFor, parseClients, registerWithC
 import { CLI_NAME, diagnose, ensureCommand, findOnUserPath, installSkill, isEphemeralRoot, launchCommand, manualRegisterCommand, planCommand, registerMcp, resolveClaudeDir, spawnRunner, } from "./installer.js";
 import { defaultCheckDir, readCheckInputs, runCheck } from "./check-run.js";
 import { httpClient, runCi } from "./ci-run.js";
+import { runLogin, runScriptedLogin, savedLine } from "./login-run.js";
+import { credentialRedactor, LOGIN_ENV, readScriptedLogin } from "./engine/scripted-login.js";
+import { parseLoginArgs } from "./engine/profiles.js";
 import { detectProvider, EXIT_CI, KEY_ENV, parseCiArgs, redactKeys, secretValues } from "./engine/ci.js";
 import { EXIT, exitCodeOf, formatCheck, parseCheckArgs, refusedFlowReason, toSarif, toSummaryJson, unmeasuredReason } from "./engine/check.js";
 import { LEGACY_MEMORY_DIRNAME, MEMORY_DIRNAME, writeSelfIgnore } from "./engine/memory.js";
 import { formatStatus, liveEngines, liveTokenFileName, localClock, LIVE_TOKEN_FILE, pidAlive, watchTarget, wholeSessions, } from "./engine/live.js";
 import { formatScan, scanProject } from "./scan.js";
+import { dispatch } from "./commands.js";
 const here = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(here, "..");
 /** This package's version, as published. */
@@ -57,6 +62,9 @@ Usage:
                                      --ignore rule,rule; --storage-state file to check signed in;
                                      --project dir (default: here); --out dir (default: .scenescout/check);
                                      --browser chromium|firefox|webkit;
+                                     --action-timeout-ms N (default 5000), --nav-timeout-ms N (default 20000;
+                                      15000 per crawled route): raise on a loaded runner, or set
+                                      SCENESCOUT_ACTION_TIMEOUT_MS / SCENESCOUT_NAV_TIMEOUT_MS;
                                      --flows dir|off: replay the flows saved there (default: .scenescout/flows);
                                      --retest on|off: re-test open findings a page load reproduces (default on);
                                      --flow-writes never|allow: never (default) replays flows under observe's
@@ -84,8 +92,28 @@ Usage:
                                       destructive only with --allow-destructive as well); --level minimal|medium|
                                       extensive (default medium); --focus "an area or flow";
                                      --storage-state file; --browser chromium|firefox|webkit;
-                                     --project dir (default: here); --out dir (default: .scenescout/ci))
+                                     --action-timeout-ms N, --nav-timeout-ms N: as for check;
+                                     --project dir (default: here); --out dir (default: .scenescout/ci);
+                                     --show "the Save button": instead of exploring, capture that element as a PNG
+                                      under shots/; --compare-url https://…: with --show, capture it there too and
+                                      write a diff picture)
                                     Exit code: 0 the run ran (findings never change it), 2 could not run.
+  scenescout login <url> --role <name>
+                                    Open a visible browser at the URL, sign in there (SSO, MFA, anything), then
+                                    press Enter in this terminal to save the session as that role's profile, in
+                                    .scenescout/auth/<name>.json (owner-only; never printed, never committed).
+                                    Closing the window or Ctrl+C saves nothing. Agents then attach with
+                                    scout_attach { role: "<name>" }, as many sessions as they like from one login.
+                                    (--project dir (default: here); --browser chromium|firefox|webkit)
+  scenescout login <url> --role <name> --script
+                                    For CI: sign in headless from SCENESCOUT_LOGIN_USERNAME, SCENESCOUT_LOGIN_PASSWORD
+                                    and, if the form asks for a code, SCENESCOUT_LOGIN_TOTP_SECRET (base32 or an
+                                    otpauth:// URI), then save the profile as above. A test user only. No value
+                                    is ever printed. Exit 0 signed in and saved, 1 not.
+                                    (--success-url text|url; --success-selector css; --username-selector,
+                                    --password-selector, --otp-selector, --submit-selector css; each of these also
+                                    from SCENESCOUT_LOGIN_<FLAG>, e.g. SCENESCOUT_LOGIN_SUCCESS_URL;
+                                    --timeout seconds (default 60))
   scenescout status [projectPath]   What is the engine doing right now? (every session + recent actions)
   scenescout watch [projectPath]    Open the live view in a browser: what each session is doing, a thumbnail
                                     of its page, and a live stream you can switch on per session
@@ -268,13 +296,6 @@ function flagValue(flags, name) {
     const next = flags[at + 1];
     return next === undefined || next.startsWith("--") ? "" : next;
 }
-function browsersFlag(flags) {
-    // `--browser-only` is a different flag; a bare `--browser` is a slip that would otherwise be ignored and download Chromium.
-    const slip = flags.find((f) => f === "--browser" || f.startsWith("--browser="));
-    if (slip)
-        throw new Error(`unknown flag ${slip.split("=")[0]} — did you mean --browsers?`);
-    return flagValue(flags, "--browsers");
-}
 /** The `code` command on PATH, with its real path: the real path is what tells VS Code from a fork. */
 function codeOnPath() {
     const names = process.platform === "win32" ? ["code.cmd", "code.exe"] : ["code"];
@@ -322,7 +343,7 @@ async function install(flags) {
     // only thing it cannot bring is the browser download.
     const browserOnly = flags.includes("--browser-only");
     // Read the choice before doing anything, so a typo costs nothing.
-    const selection = parseBrowserSelection(browsersFlag(flags));
+    const selection = parseBrowserSelection(flagValue(flags, "--browsers"));
     if ("error" in selection)
         throw new Error(selection.error);
     const chosen = parseClients(flagValues(flags, ["--client", "--clients"]));
@@ -493,8 +514,6 @@ async function doctor(flags) {
 }
 /** `scenescout check`: exit 0 passed, 1 failed the gate, 2 could not run. */
 async function check(args) {
-    if (args.includes("--help") || args.includes("-h"))
-        usage(0);
     const parsed = parseCheckArgs(args, process.cwd());
     if (!parsed.ok) {
         console.error(`scenescout check: ${parsed.error}`);
@@ -557,8 +576,6 @@ async function check(args) {
 }
 /** `scenescout ci`: exit 0 when the run ran, 2 when it could not. Findings never change the exit code. */
 async function ci(args) {
-    if (args.includes("--help") || args.includes("-h"))
-        usage(0);
     const secrets = secretValues(process.env);
     const say = (line) => console.log(redactKeys(line, secrets));
     const fail = (message) => {
@@ -598,6 +615,44 @@ async function ci(args) {
     }
     process.exit(exitCode);
 }
+/** `scenescout login`: exit 0 saved, 1 nothing saved. */
+async function login(args) {
+    const parsed = parseLoginArgs(args, process.cwd());
+    if (!parsed.ok) {
+        console.error(`scenescout login: ${parsed.error}`);
+        process.exit(1);
+    }
+    const options = parsed.options;
+    if (options.script) {
+        // Everything is checked before a browser launches; each problem names a variable, never a value.
+        const read = readScriptedLogin(options.script, process.env);
+        if (!read.ok) {
+            for (const e of read.errors)
+                console.error(`scenescout login: ${e}`);
+            process.exit(1);
+        }
+        const redactor = credentialRedactor(read.config, process.env[LOGIN_ENV.totpSecret]);
+        try {
+            const saved = await runScriptedLogin(options, read.config, redactor, (line) => console.log(line));
+            console.log(redactor.redact(savedLine(options, saved)));
+        }
+        catch (err) {
+            // Redacted again here: an error thrown by the browser itself has not been through the run's redaction.
+            console.error(redactor.redact(`scenescout login: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+    try {
+        const saved = await runLogin(options, (line) => console.log(line));
+        console.log(savedLine(options, saved));
+    }
+    catch (err) {
+        console.error(`scenescout login: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    process.exit(0);
+}
 const [, , command, ...args] = process.argv;
 // A CLI's failure mode should be a sentence, not a stack trace. `scan` on a
 // path that does not exist and `status` on a half-written status.json both
@@ -605,57 +660,35 @@ const [, , command, ...args] = process.argv;
 // one line the user needs. `serve` is deliberately outside this: it hands off
 // to the MCP server, whose own transport owns error reporting from then on.
 try {
-    switch (command) {
-        // Asking for help is not an error; scripts and shells treat a non-zero
-        // exit as one.
-        case "--help":
-        case "-h":
-        case "help":
-            usage(0);
-        case "--version":
-        case "-v": {
-            console.log(packageVersion());
-            break;
-        }
-        case "scan": {
-            const target = args[0];
-            if (!target)
-                usage();
-            console.log(formatScan(scanProject(target)));
-            break;
-        }
-        case "serve": {
-            await import("./mcp-server.js");
-            break;
-        }
-        case "install": {
-            await install(args);
-            break;
-        }
-        case "doctor": {
-            await doctor(args);
-            break;
-        }
-        case "check": {
-            await check(args);
-            break;
-        }
-        case "ci": {
-            await ci(args);
-            break;
-        }
-        case "status": {
-            status(path.resolve(args[0] ?? process.cwd()));
-            break;
-        }
-        case "watch": {
-            const positional = args.filter((a) => !a.startsWith("--"));
-            watch(path.resolve(positional[0] ?? process.cwd()), !args.includes("--no-open"));
-            break;
-        }
-        default:
-            usage();
-    }
+    await dispatch(command, args, {
+        usage,
+        version: () => console.log(packageVersion()),
+        refuse: (message) => {
+            console.error(`scenescout ${command}: ${message}`);
+            console.error("Run `scenescout --help` for the options.");
+            process.exit(1);
+        },
+        commands: {
+            scan: (a) => {
+                if (!a[0])
+                    usage();
+                console.log(formatScan(scanProject(a[0])));
+            },
+            serve: async () => {
+                await import("./mcp-server.js");
+            },
+            install,
+            doctor,
+            check,
+            ci,
+            login,
+            status: (a) => status(path.resolve(a[0] ?? process.cwd())),
+            watch: (a) => {
+                const positional = a.filter((x) => !x.startsWith("--"));
+                watch(path.resolve(positional[0] ?? process.cwd()), !a.includes("--no-open"));
+            },
+        },
+    });
 }
 catch (err) {
     console.error(`scenescout ${command ?? ""}: ${err instanceof Error ? err.message : String(err)}`);

package/dist/commands.js

@@ -0,0 +1,104 @@
+/**
+ * How the CLI decides what a command line asks for, before any command runs.
+ *
+ * It lives apart from cli.ts so it can be table-tested: `scenescout install
+ * --help` once ran a real install, because install read only the flags it knew
+ * and ignored the rest. Every subcommand now answers `--help` / `-h` with the
+ * usage text and exit 0 before it does anything, and a command that parses its
+ * own flags by hand refuses one it does not know.
+ */
+const HANDLERS_OF = {
+    scan: true,
+    serve: true,
+    install: true,
+    doctor: true,
+    check: true,
+    ci: true,
+    login: true,
+    status: true,
+    watch: true,
+};
+export const SUBCOMMANDS = Object.keys(HANDLERS_OF);
+/**
+ * Commands that read their arguments by hand. `check`, `ci` and `login` are
+ * absent: their own parsers refuse unknown options. `serve` is absent on
+ * purpose: it is the line an MCP client launches, and a stray argument there
+ * should not stop the server from starting.
+ */
+export const HAND_PARSED = {
+    install: {
+        switches: ["--skip-browser", "--no-register", "--no-command", "--browser-only"],
+        valued: ["--browsers", "--client", "--clients"],
+        // `--browser` is what `check` and `login` call it; for install it would otherwise download Chromium regardless.
+        hints: { "--browser": "--browsers" },
+        positional: 0,
+    },
+    doctor: { switches: ["--engine"], valued: [], positional: 0 },
+    scan: { switches: [], valued: [], positional: 1 },
+    status: { switches: [], valued: [], positional: 1 },
+    watch: { switches: ["--no-open"], valued: [], positional: 1 },
+};
+/** True when the arguments ask for help. */
+export function wantsHelp(args) {
+    return args.includes("--help") || args.includes("-h");
+}
+/** The first argument `spec` does not accept, as an error sentence; null when every one is accepted. */
+export function unknownArgument(args, spec) {
+    let positional = 0;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith("-") || arg === "-") {
+            if (++positional > spec.positional)
+                return `unexpected argument ${arg}`;
+            continue;
+        }
+        const name = arg.split("=")[0];
+        if (spec.valued.includes(name)) {
+            // The value after a valued flag is not itself a flag, even when it starts with a dash.
+            if (!arg.includes("="))
+                i++;
+            continue;
+        }
+        if (spec.switches.includes(name) && !arg.includes("="))
+            continue;
+        const hint = spec.hints?.[name];
+        return `unknown option ${name}${hint ? ` — did you mean ${hint}?` : ""}`;
+    }
+    return null;
+}
+/** Whether `command` names a subcommand. */
+export function isSubcommand(command) {
+    return command !== undefined && Object.hasOwn(HANDLERS_OF, command);
+}
+/** Settle help and flag errors for a subcommand before its handler is reached. */
+export function preflight(command, args) {
+    if (wantsHelp(args))
+        return { kind: "help" };
+    const spec = Object.hasOwn(HAND_PARSED, command) ? HAND_PARSED[command] : undefined;
+    const problem = spec ? unknownArgument(args, spec) : null;
+    return problem ? { kind: "error", message: problem } : { kind: "run" };
+}
+/**
+ * Run the command line: help and flag errors are settled here, so a subcommand's
+ * handler is reached only when it is actually meant to run.
+ */
+export async function dispatch(command, args, h) {
+    switch (command) {
+        // Asking for help is not an error; scripts and shells treat a non-zero exit as one.
+        case "--help":
+        case "-h":
+        case "help":
+            return h.usage(0);
+        case "--version":
+        case "-v":
+            return h.version();
+    }
+    if (!isSubcommand(command))
+        return h.usage(1);
+    const verdict = preflight(command, args);
+    if (verdict.kind === "help")
+        return h.usage(0);
+    if (verdict.kind === "error")
+        return h.refuse(verdict.message);
+    await h.commands[command](args);
+}

package/dist/engine/authloss.js

@@ -14,6 +14,18 @@
 export const LOGIN_ROUTE_RE = /\/(login|signin|sign-in|auth)(\/|$)/;
 /** Consecutive login bounces before we stop assuming it is a permission wall. */
 export const AUTH_LOSS_STREAK = 3;
+/**
+ * Should this loss be answered by re-attaching from the role's saved profile?
+ *
+ * Only a session attached by role has a profile that `scenescout login` (or
+ * another process) may have refreshed since, so only it has something to
+ * re-read. A storage-state file or an anonymous session is reported as
+ * before. Once per session: a second loss means the refresh did not hold,
+ * and retrying on a loop would hide a dead profile behind endless recoveries.
+ */
+export function shouldReattach(opts) {
+    return opts.streak >= AUTH_LOSS_STREAK && opts.signIn === "role" && !opts.alreadyReattached;
+}
 export class AuthLossTracker {
     /** Consecutive navigations that ended on a login page. */
     streak = 0;
@@ -21,6 +33,37 @@ export class AuthLossTracker {
     reported = false;
     /** Notice for the in-flight call, consumed exactly once by take(). */
     pending = "";
+    /** How the session signed in; set by beginSession. */
+    signIn = "none";
+    /** The role label of the session, for the notices. */
+    role = "";
+    /** What each navigation of the current streak asked for, in order. */
+    streakTargets = [];
+    /** A re-attach this navigation earned and the engine has not taken yet. */
+    due = null;
+    /** Taken by the engine: the next recorded navigation says whether it worked. */
+    awaiting = null;
+    /** What happened to this session's one re-attach. */
+    outcome = null;
+    /** Notices a batch (crawl) must still say at its end, since it discards the per-route ones. */
+    batchNotes = [];
+    /**
+     * Start tracking a newly attached session. An explicit attach is new
+     * credentials: the streak, the verdict and the one re-attach start afresh,
+     * so a new session neither inherits a dead one's bounces nor names its routes.
+     */
+    beginSession(signIn, role) {
+        this.signIn = signIn;
+        this.role = role;
+        this.streak = 0;
+        this.streakTargets = [];
+        this.reported = false;
+        this.pending = "";
+        this.due = null;
+        this.awaiting = null;
+        this.outcome = null;
+        this.batchNotes = [];
+    }
     /**
      * Did a navigation to `requested` end up on a login screen?
      *
@@ -46,14 +89,14 @@ export class AuthLossTracker {
      *
      * `bounced` decides both the streak and whether the route counts as covered;
      * the caller owns the memory writes, because ownership of the store belongs
-     * to the engine, not to this tracker.
+     * to the engine, not to this tracker. `target` is what the caller navigated
+     * to (a path with its real ids, where `requestedRoute` is the normalized
+     * route), which a re-attach goes back to; it defaults to the route.
      */
     record(opts) {
         const { requestedRoute, landedRoute, bounced, role } = opts;
-        if (bounced)
-            this.streak += 1;
-        else
-            this.streak = 0;
+        const target = opts.target ?? requestedRoute;
+        this.due = null;
         const divergence = landedRoute === requestedRoute
             ? ""
             : `⚠ REDIRECTED: asked for ${requestedRoute}, landed on ${landedRoute}` +
@@ -61,8 +104,101 @@ export class AuthLossTracker {
                     ? ` — this is a login page, so the route is NOT counted as covered.`
                     : ` — the app redirected; the route counts as covered for role '${role}'.`) +
                 `\n`;
+        if (this.awaiting) {
+            this.settleReattach(requestedRoute, target, bounced, divergence);
+            return;
+        }
+        if (bounced) {
+            this.streak += 1;
+            this.streakTargets.push(target);
+        }
+        else {
+            this.streak = 0;
+            this.streakTargets = [];
+        }
+        if (shouldReattach({ streak: this.streak, signIn: this.signIn, alreadyReattached: this.outcome !== null })) {
+            // The verdict is replaced by the recovery's own notice once the engine
+            // has re-attached; if it never does (the call threw), the verdict stands.
+            this.due = { returnTo: target, retry: [...new Set(this.streakTargets)].filter((t) => t !== target) };
+        }
         this.pending = this.banner() + divergence;
     }
+    /**
+     * The re-attach this navigation earned, if any: consumed once, and from then
+     * on this session has used its one re-attach. `revisits` says which of the
+     * streak's other targets the caller will visit again itself (a crawl, its own
+     * paths); the plan it gets back holds only those, and the notice asks for the rest.
+     */
+    takeReattach(opts = {}) {
+        const plan = this.due;
+        this.due = null;
+        if (!plan)
+            return null;
+        const revisits = opts.revisits;
+        this.awaiting = revisits
+            ? { returnTo: plan.returnTo, retry: plan.retry.filter(revisits), left: plan.retry.filter((t) => !revisits(t)) }
+            : { returnTo: plan.returnTo, retry: [], left: plan.retry };
+        this.outcome = { kind: "failed", why: "it had not finished" };
+        return { returnTo: this.awaiting.returnTo, retry: this.awaiting.retry };
+    }
+    /** Whether a re-attach was taken and the navigation that decides it has not been recorded. */
+    get reattaching() {
+        return this.awaiting !== null;
+    }
+    /** The profile could not be applied, or the page to go back to never loaded: the loss is reported, with why. */
+    abortReattach(why) {
+        this.awaiting = null;
+        this.outcome = { kind: "failed", why };
+        const note = `The session tried to re-attach once from role '${this.role}''s saved profile, but ${why}.`;
+        this.pending = this.banner(this.lossTail(note));
+        this.batchNotes.push(`⚠ ${note}\n`);
+    }
+    /** The navigation after a re-attach decides it: signed in again, or not. */
+    settleReattach(requestedRoute, target, bounced, divergence) {
+        const plan = this.awaiting;
+        this.awaiting = null;
+        if (bounced) {
+            // Still on a login page with the latest profile: that profile is dead too.
+            this.streak = Math.max(this.streak, AUTH_LOSS_STREAK);
+            this.streakTargets.push(target);
+            const why = `its latest saved profile landed on a login page as well, so that profile has expired too`;
+            this.outcome = { kind: "failed", why };
+            const note = `The session re-attached once from role '${this.role}''s saved profile, but ${why}.`;
+            this.pending = this.banner(this.lossTail(note)) + divergence;
+            this.batchNotes.push(`⚠ ${note}\n`);
+            return;
+        }
+        this.streak = 0;
+        this.streakTargets = [];
+        // The loss was answered: a later batch verdict must not claim this session is dead.
+        this.reported = false;
+        this.outcome = { kind: "recovered", route: requestedRoute };
+        const others = (plan.retry.length === 0 ? "" : ` The other routes that bounced (${plan.retry.join(", ")}) are visited again in this sweep.`) +
+            (plan.left.length === 0 ? "" : ` The other routes that bounced before it (${plan.left.join(", ")}) are still NOT covered: visit them again.`);
+        const note = `↻ SESSION RE-ATTACHED — its sign-in was lost, so it re-attached once from role '${this.role}''s latest saved profile and ` +
+            `is signed in again at ${requestedRoute}.${others} This happens once per session: a second loss is reported, not retried.\n`;
+        this.pending = note + divergence;
+        this.batchNotes.push(note);
+    }
+    /** The end of a loss once the one re-attach is spent: what happened, and that it is not retried. */
+    lossTail(note) {
+        return ` ${note} It is not retried: record the profile again with \`scenescout login\` for role '${this.role}' and re-attach.`;
+    }
+    /**
+     * One line on what this session's re-attach did, for whoever hands its
+     * results on (a lane's report). Empty when it never re-attached.
+     */
+    reattachSummary() {
+        if (!this.outcome)
+            return "";
+        if (this.outcome.kind === "recovered")
+            return `its sign-in was lost and it re-attached once from role '${this.role}''s saved profile, continuing from ${this.outcome.route}`;
+        return `its sign-in was lost and re-attaching from role '${this.role}''s saved profile did not recover it: ${this.outcome.why}`;
+    }
+    /** Start a batch (crawl): its end-of-batch notes cover only what happened during it. */
+    beginBatch() {
+        this.batchNotes = [];
+    }
     /**
      * The verdict, once the streak says the session is dead.
      *
@@ -74,15 +210,18 @@ export class AuthLossTracker {
      * collapses repeats to "nothing new" — the signal decayed exactly as the
      * problem got worse.
      */
-    banner() {
+    banner(tail) {
         if (this.streak < AUTH_LOSS_STREAK)
             return "";
         const first = !this.reported;
         this.reported = true;
+        // After the session's one re-attach, a later loss says so rather than implying a retry is still to come.
+        const spent = tail ?? (this.outcome !== null ? this.lossTail(`This session already re-attached once from role '${this.role}''s saved profile.`) : "");
         return (`⚠ SESSION AUTH LOST — ${this.streak} consecutive navigations were redirected to a login page. ` +
             `The credentials this session attached with have almost certainly expired. ` +
             `Nothing tested past this point is meaningful: re-attach with a fresh storage state before continuing.` +
             (first ? ` Routes bounced this way are recorded as NOT covered, so the completion contract still sees them as gaps.` : "") +
+            spent +
             `\n`);
     }
     /**
@@ -115,9 +254,11 @@ export class AuthLossTracker {
      * whatever the final route did.
      */
     batchVerdict() {
+        const notes = this.batchNotes.join("");
         if (!this.reported)
-            return "";
-        return (`⚠ SESSION AUTH LOST during this sweep — navigations were redirected to a login page. ` +
+            return notes;
+        return (notes +
+            `⚠ SESSION AUTH LOST during this sweep — navigations were redirected to a login page. ` +
             `The credentials this session attached with have almost certainly expired, so routes crawled after that ` +
             `point tested a logged-out app. They are recorded as NOT covered; re-attach with a fresh storage state ` +
             `and crawl again.\n`);

package/dist/engine/brief.js

@@ -85,6 +85,12 @@ export function laneName(modules, index) {
     const name = modules.length > 1 ? `${base}+${modules.length - 1}` : base || `lane-${index + 1}`;
     return name.slice(0, LANE_NAME_MAX);
 }
+/** How a lane signs in, as scout_attach arguments: by saved role, by a storage-state file, or not at all. */
+function signInArgument(opts) {
+    if (!opts.role || opts.role === "anonymous")
+        return "";
+    return opts.roleProfile ? `, role: "${opts.role}"` : `, storageStatePath: "<${opts.role}>"`;
+}
 /** The lanes to run, each with the objective to attach with. */
 export function planLanes(routes, laneCount, opts = {}) {
     return splitRoutes(routes, laneCount).map((lane, i) => ({
@@ -124,7 +130,7 @@ export function formatBriefs(briefs, opts = {}) {
         `LANE PLAN — ${briefs.length} lane(s) over ${briefs.reduce((n, b) => n + b.routes.length, 0)} route(s).`,
         ``,
         `Give each lane its own agent. Every lane attaches with its own session name, so the browsers run genuinely in parallel, and lands on its own first route rather than the home page:`,
-        `  scout_attach { session: "<lane>", url: "<origin><landing>", projectPath, mode: "${mode}"${opts.role ? `, storageStatePath: "<${opts.role}>"` : ""}, objective: "<objective>" }`,
+        `  scout_attach { session: "<lane>", url: "<origin><landing>", projectPath, mode: "${mode}"${signInArgument(opts)}, objective: "<objective>" }`,
         ``,
         `Rules to pass on, which a hand-written brief tends to drop:`,
         `  · A lane works ITS routes only. Two lanes auditing the same register while a third module is never opened is the failure this plan exists to prevent — and route coverage will look complete either way. A defect on a page it does not own is that page's lane's to file.`,