@clawdbuilder/jig-bedrock 0.0.0-stage → 0.1.1

package/src/statistics.ts

@@ -0,0 +1,315 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { atomicCache } from "./cache.ts";
+import { boundedRegular } from "./catalog.ts";
+import type { ResolvedConfig } from "./config.ts";
+import {
+    executableExists,
+    executableOnPath,
+    runUsage,
+    UsageError,
+    type UsageFailure,
+    type UsageRunner,
+    usageExecutable,
+} from "./usage.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: parsed JSON from the AWS CLI or usage program, checked field by field where it is used
+type Json = any;
+
+export type UsagePeriod = "daily" | "weekly" | "monthly";
+export const periodLabels: Record<UsagePeriod, string> = {
+    daily: "Today",
+    weekly: "Last 7 Days",
+    monthly: "Current Month",
+};
+export interface UsageTotals {
+    requests: number;
+    inputFresh: number;
+    cacheRead: number;
+    cacheWrite: number;
+    input: number;
+    output: number;
+    costUsd: number | null;
+}
+export interface UsageProfile extends UsageTotals {
+    model: string;
+    name: string;
+}
+export interface UsageReport {
+    user: string;
+    period: UsagePeriod;
+    totals: UsageTotals;
+    profiles: UsageProfile[];
+    contract: "v1" | "legacy";
+}
+export interface UsageSnapshot {
+    report: UsageReport;
+    observedAt: number;
+    stale: boolean;
+    refreshFailed: boolean;
+}
+export interface StatisticsSource {
+    load(period: UsagePeriod): UsageSnapshot | undefined;
+    refresh(period: UsagePeriod, options?: { force?: boolean; signal?: AbortSignal }): Promise<UsageSnapshot>;
+    health(): { usage: boolean; aws: boolean; bash: boolean; jq: boolean };
+}
+const label = (v: unknown, max = 256): v is string =>
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: usage labels reject control characters
+    typeof v === "string" && v.length > 0 && v.length <= max && !/[\x00-\x1f\x7f-\x9f]/.test(v);
+const count = (v: unknown): v is number => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+const cost = (v: unknown): v is number | null => v === null || (typeof v === "number" && Number.isFinite(v) && v >= 0);
+function totals(value: Json, summary: boolean): UsageTotals {
+    const names = summary
+        ? [
+              "total_requests",
+              "total_input_tokens_fresh",
+              "total_cache_read_tokens",
+              "total_cache_write_tokens",
+              "total_input_tokens",
+              "total_output_tokens",
+              "total_estimated_cost_usd",
+          ]
+        : [
+              "requests",
+              "input_tokens_fresh",
+              "cache_read_tokens",
+              "cache_write_tokens",
+              "total_input_tokens",
+              "output_tokens",
+              "estimated_cost_usd",
+          ];
+    if (!value || !names.slice(0, 6).every((k) => count(value[k])) || !cost(value[names[6] as string]))
+        throw new UsageError("invalid_result");
+    const [requests, inputFresh, cacheRead, cacheWrite, input, output, costUsd] = names.map((k) => value[k]);
+    if (!Number.isSafeInteger(inputFresh + cacheRead + cacheWrite) || input !== inputFresh + cacheRead + cacheWrite)
+        throw new UsageError("invalid_result");
+    return { requests, inputFresh, cacheRead, cacheWrite, input, output, costUsd };
+}
+/**
+ * What was spent on the rows that have a price. usage program leaves the summary cost null as soon as one row is unpriced (a model it has
+ * no rate for), which would hide hundreds of dollars of known spend behind one unknown row; the footer shows the priced sum
+ * and marks it as a lower bound instead.
+ */
+export function pricedSpend(report: UsageReport): { spentUsd: number; unpriced: boolean } {
+    return {
+        spentUsd: report.profiles.reduce((sum, row) => sum + (row.costUsd ?? 0), 0),
+        unpriced: report.profiles.some((row) => row.costUsd === null),
+    };
+}
+function normalize(value: Json, period: UsagePeriod): UsageReport {
+    if (
+        !value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        !label(value.user) ||
+        value.period !== periodLabels[period] ||
+        !Array.isArray(value.profiles) ||
+        value.profiles.length > 256
+    )
+        throw new UsageError("invalid_result");
+    const contract =
+        value.schema_version === undefined && value.command === undefined
+            ? "legacy"
+            : value.schema_version === 1 && value.command === "usage"
+              ? "v1"
+              : undefined;
+    if (!contract) throw new UsageError("invalid_result");
+    const profiles: UsageProfile[] = value.profiles.map((row: Json) => {
+        if (
+            !row ||
+            row.user !== value.user ||
+            !(label(row.model_slug) || (row.model_slug === "" && row.estimated_cost_usd === null)) ||
+            !label(row.profile_name)
+        )
+            throw new UsageError("invalid_result");
+        return { model: row.model_slug || "Unknown model", name: row.profile_name, ...totals(row, false) };
+    });
+    const summary =
+        value.summary === undefined && !profiles.length && contract === "legacy"
+            ? { requests: 0, inputFresh: 0, cacheRead: 0, cacheWrite: 0, input: 0, output: 0, costUsd: null }
+            : totals(value.summary, true);
+    for (const key of ["requests", "inputFresh", "cacheRead", "cacheWrite", "input", "output"] as const) {
+        const sum = profiles.reduce((n, p) => n + p[key], 0);
+        if (!Number.isSafeInteger(sum) || sum !== summary[key]) throw new UsageError("invalid_result");
+    }
+    if (profiles.some((p) => p.costUsd === null) && summary.costUsd !== null) throw new UsageError("invalid_result");
+    if (summary.costUsd !== null) {
+        const sum = profiles.reduce((total, row) => total + (row.costUsd ?? 0), 0);
+        // usage program sums priced rows; allow only floating-point representation noise.
+        const tolerance = Math.max(1e-8, Number.EPSILON * Math.max(1, sum) * Math.max(1, profiles.length) * 4);
+        if (!Number.isFinite(sum) || Math.abs(sum - summary.costUsd) > tolerance)
+            throw new UsageError("invalid_result");
+    }
+    return { user: value.user, period, totals: summary, profiles, contract };
+}
+/** v1 is one JSON object. Only legacy usage program may prefix the object with human-readable text. */
+export function parseUsage(output: string, period: UsagePeriod): UsageReport {
+    if (Buffer.byteLength(output) > 2_097_152) throw new UsageError("invalid_result");
+    try {
+        return normalize(JSON.parse(output), period);
+    } catch (error) {
+        if (error instanceof UsageError) throw error;
+    }
+    let candidates = 0;
+    for (let index = output.indexOf("{"); index >= 0 && candidates++ < 256; index = output.indexOf("{", index + 1)) {
+        try {
+            const value = JSON.parse(output.slice(index));
+            if (value.schema_version !== undefined || value.command !== undefined)
+                throw new UsageError("invalid_result");
+            return normalize(value, period);
+        } catch (error) {
+            if (error instanceof UsageError) throw error;
+        }
+    }
+    throw new UsageError("invalid_result");
+}
+function cacheReport(value: Json): UsageReport {
+    if (!value || !["v1", "legacy"].includes(value.contract)) throw new UsageError("invalid_result");
+    const fields = (t: Json, summary: boolean) =>
+        summary
+            ? {
+                  total_requests: t.requests,
+                  total_input_tokens_fresh: t.inputFresh,
+                  total_cache_read_tokens: t.cacheRead,
+                  total_cache_write_tokens: t.cacheWrite,
+                  total_input_tokens: t.input,
+                  total_output_tokens: t.output,
+                  total_estimated_cost_usd: t.costUsd,
+              }
+            : {
+                  requests: t.requests,
+                  input_tokens_fresh: t.inputFresh,
+                  cache_read_tokens: t.cacheRead,
+                  cache_write_tokens: t.cacheWrite,
+                  total_input_tokens: t.input,
+                  output_tokens: t.output,
+                  estimated_cost_usd: t.costUsd,
+              };
+    return normalize(
+        {
+            ...(value.contract === "v1" ? { schema_version: 1, command: "usage" } : {}),
+            user: value.user,
+            period: periodLabels[value.period as UsagePeriod],
+            summary: fields(value.totals, true),
+            profiles: value.profiles.map((p: Json) => ({
+                user: value.user,
+                model_slug: p.model,
+                profile_name: p.name,
+                ...fields(p, false),
+            })),
+        },
+        value.period,
+    );
+}
+export function createStatistics(
+    config: ResolvedConfig,
+    runner: UsageRunner = runUsage,
+    directory = join(homedir(), ".cache/jig-bedrock"),
+    now = Date.now,
+): StatisticsSource {
+    const scope = JSON.stringify({
+        profile: config.profile,
+        team: config.team,
+        regions: [...config.regions].sort(),
+        executable: usageExecutable(config),
+    });
+    const file = (period: UsagePeriod) => join(directory, `usage-${period}.json`);
+    const window = (period: UsagePeriod, observedAt: number) =>
+        new Date(observedAt).toISOString().slice(0, period === "monthly" ? 7 : 10);
+    const load = (period: UsagePeriod): UsageSnapshot | undefined => {
+        try {
+            const value = JSON.parse(boundedRegular(file(period), 1_048_576, true) || "{}");
+            if (
+                value.schema !== 1 ||
+                value.scope !== scope ||
+                !Number.isSafeInteger(value.observedAt) ||
+                value.observedAt < 0 ||
+                value.observedAt > now() ||
+                window(period, value.observedAt) !== window(period, now()) ||
+                value.report?.period !== period
+            )
+                return;
+            const report = cacheReport(value.report);
+            return {
+                report,
+                observedAt: value.observedAt,
+                stale: now() - value.observedAt > 300_000 || value.refreshFailed === true,
+                refreshFailed: value.refreshFailed === true,
+            };
+        } catch {
+            return;
+        }
+    };
+    let background: Promise<UsageSnapshot> | undefined;
+    const perform = async (
+        period: UsagePeriod,
+        options: { force?: boolean; signal?: AbortSignal },
+    ): Promise<UsageSnapshot> => {
+        if (options.signal?.aborted) throw new UsageError("cancelled");
+        const started = now(),
+            previous = load(period);
+        if (!options.force && previous && !previous.stale) return previous;
+        try {
+            const output = await runner(
+                usageExecutable(config),
+                ["usage", `--${period}`, "--output", "json", "--aws-profile", config.profile],
+                {
+                    timeout: 120_000,
+                    maxBuffer: 2_097_152,
+                    signal: options.signal,
+                    env: {
+                        ...process.env,
+                        BEDROCK_REGIONS: config.regions.join(","),
+                        AWS_PROFILE: config.profile,
+                        AWS_CLI_AUTO_PROMPT: "off",
+                        AWS_PAGER: "",
+                        NO_COLOR: "1",
+                        PAT_SKIP_UPDATE_CHECK: "1",
+                    },
+                },
+            );
+            if (options.signal?.aborted) throw new UsageError("cancelled");
+            const observedAt = now();
+            // Legacy reports have no explicit range, so a UTC rollover cannot be safely relabelled.
+            if (window(period, started) !== window(period, observedAt)) throw new UsageError("invalid_result");
+            const report = parseUsage(output, period);
+            atomicCache(file(period), { schema: 1, scope, report, observedAt, refreshFailed: false });
+            return { report, observedAt, stale: false, refreshFailed: false };
+        } catch (error) {
+            const kind: UsageFailure = error instanceof UsageError ? error.kind : "unavailable";
+            if (previous && kind !== "cancelled") {
+                try {
+                    atomicCache(file(period), {
+                        schema: 1,
+                        scope,
+                        report: previous.report,
+                        observedAt: previous.observedAt,
+                        refreshFailed: true,
+                    });
+                } catch {}
+            }
+            throw new UsageError(kind);
+        }
+    };
+    return {
+        load,
+        health: () => ({
+            usage: executableExists(usageExecutable(config)),
+            aws: executableOnPath("aws"),
+            bash: executableOnPath("bash"),
+            jq: executableOnPath("jq"),
+        }),
+        refresh(period, options = {}) {
+            // Background monthly display work shares a flight; interactive commands own their cancellation.
+            if (period === "monthly" && !options.force && !options.signal) {
+                if (background === undefined) {
+                    background = perform(period, options).finally(() => {
+                        background = undefined;
+                    });
+                }
+                return background;
+            }
+            return perform(period, options);
+        },
+    };
+}

package/src/switch-cost.ts

@@ -0,0 +1,91 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isSubagentChild } from "./child.ts";
+import { isJigBedrock } from "./identity.ts";
+import { type Cost, cacheWriteRate, type PromptCache, retentionOf } from "./prompt-cache.ts";
+
+/** Below this the rewrite is pocket change and a notice would only be noise (Pi's own cache warming uses the same line). */
+export const NOTICE_FLOOR_USD = 0.05;
+const DEFAULT_TTL_SECONDS = { short: 300, long: 3600 };
+
+export const tokensLabel = (tokens: number): string =>
+    tokens >= 1_000_000 ? `${(tokens / 1_000_000).toFixed(1).replace(/\.0$/, "")}M` : `${Math.round(tokens / 1000)}k`;
+const dollars = (value: number): string => `$${value.toFixed(2)}`;
+
+export function switchNotice(
+    tokens: number,
+    cost: Cost,
+    retention: "short" | "long",
+): { text: string; usd: number } | undefined {
+    if (!Number.isFinite(tokens) || tokens <= 0) return;
+    const usd = (tokens * cacheWriteRate(cost, tokens, retention)) / 1_000_000;
+    if (!(usd >= NOTICE_FLOOR_USD)) return;
+    return {
+        usd,
+        text: `Switching model rewrites ~${tokensLabel(tokens)} tokens of cache: about ${dollars(usd)} (once). For one hard question, ask the planner subagent instead.`,
+    };
+}
+
+/**
+ * The cache is per model, so the first request after a switch writes the whole context again at the target's cache-write rate
+ * (a session that stays on its model reads it at a fraction of that). One notice per switch, when that is real money and the
+ * old cache was still alive: an expired cache is rewritten on the next request whichever model answers it.
+ */
+/** The parts of a session entry the cache check reads. Pi's own entry types are wider. */
+interface SessionEntry {
+    type?: string;
+    kind?: string;
+    timestamp?: string;
+    message?: { role?: string; stopReason?: string; timestamp?: number };
+}
+
+export function registerSwitchNotice(pi: Pick<ExtensionAPI, "on">, options: { env?: NodeJS.ProcessEnv } = {}): void {
+    const env = options.env ?? process.env;
+    if (isSubagentChild(env)) return;
+    pi.on("model_select", (event, ctx) => {
+        if (
+            event.source === "restore" ||
+            !event.previousModel ||
+            !isJigBedrock(event.model) ||
+            ctx.mode === "print" ||
+            ctx.mode === "json"
+        )
+            return;
+        if (event.previousModel.provider === event.model.provider && event.previousModel.id === event.model.id) return;
+        const tokens = ctx.getContextUsage?.()?.tokens;
+        if (typeof tokens !== "number" || !event.model.cost) return;
+        const retention = retentionOf(env);
+        // `promptCache` is a field this package adds to the models it registers (see catalog.ts).
+        const promptCache = (event.previousModel as { promptCache?: PromptCache }).promptCache;
+        if (cacheExpired(ctx.sessionManager.getBranch() as readonly SessionEntry[], promptCache, retention)) return;
+        const notice = switchNotice(tokens, event.model.cost, retention);
+        if (notice) ctx.ui.notify(notice.text, "info");
+    });
+}
+
+/**
+ * True only when the newest sign of cache activity is known to be older than the previous model's cache lifetime: the last
+ * response (its timestamp is when the request started, which is when Bedrock refreshed the entry) or a Pi cache-warming refresh.
+ */
+function cacheExpired(
+    entries: readonly SessionEntry[],
+    promptCache: PromptCache | undefined,
+    retention: "short" | "long",
+    now = Date.now(),
+): boolean {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        let at: number | undefined;
+        if (entry?.type === "usage" && entry.kind === "cache_warm") at = Date.parse(entry.timestamp ?? "");
+        else if (
+            entry?.type === "message" &&
+            entry.message?.role === "assistant" &&
+            entry.message.stopReason !== "error" &&
+            entry.message.stopReason !== "aborted"
+        )
+            at = entry.message.timestamp;
+        if (at === undefined) continue;
+        if (!Number.isFinite(at)) return false;
+        return now - at > (promptCache?.[retention] ?? DEFAULT_TTL_SECONDS[retention]) * 1000;
+    }
+    return false;
+}

package/src/usage.ts

@@ -0,0 +1,138 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
+import type { ResolvedConfig } from "./config.ts";
+
+export type UsageFailure =
+    | "missing"
+    | "timeout"
+    | "cancelled"
+    | "sso_expired"
+    | "permission"
+    | "network"
+    | "invalid_result"
+    | "unavailable";
+export class UsageError extends Error {
+    readonly kind: UsageFailure;
+    constructor(kind: UsageFailure) {
+        super(usageHelp(kind));
+        this.kind = kind;
+        this.name = "UsageError";
+    }
+}
+export function usageHelp(kind: UsageFailure): string {
+    switch (kind) {
+        case "missing":
+            return "usage program statistics unavailable. No usage program: put an executable named usage in usageDir that prints the documented JSON.";
+        case "timeout":
+            return "usage program statistics timed out. Check AWS network access and retry the command.";
+        case "cancelled":
+            return "usage program statistics cancelled.";
+        case "sso_expired":
+            return "usage program statistics need AWS sign-in. Run /aws-login, complete browser sign-in, then retry the statistics command.";
+        case "permission":
+            return "usage program statistics access denied. Ask your AWS administrator to check the configured profile's read permissions.";
+        case "network":
+            return "usage program statistics could not reach AWS. Check network access and retry the command.";
+        case "invalid_result":
+            return "usage program returned an unsupported or invalid statistics report. Update usage program and the Bedrock extension together.";
+        default:
+            return "usage program statistics unavailable. Run /bedrock-doctor and check usage program setup.";
+    }
+}
+export interface UsageRunOptions {
+    timeout: number;
+    maxBuffer: number;
+    signal?: AbortSignal;
+    env?: NodeJS.ProcessEnv;
+}
+export type UsageRunner = (program: string, args: string[], options: UsageRunOptions) => Promise<string>;
+function classify(stderr: string): UsageFailure {
+    return /sso|token/i.test(stderr) && /expired|invalid|login|unauthorized|does not exist/i.test(stderr)
+        ? "sso_expired"
+        : /access.?denied|not authorized|unauthorizedoperation/i.test(stderr)
+          ? "permission"
+          : /network|connect|dns|resolve|unreachable|proxy/i.test(stderr)
+            ? "network"
+            : "unavailable";
+}
+/** Run only the configured executable; child output never becomes an exception or transcript. */
+export const runUsage: UsageRunner = (program, args, options) =>
+    new Promise((accept, reject) => {
+        if (options.signal?.aborted) {
+            reject(new UsageError("cancelled"));
+            return;
+        }
+        let child: ReturnType<typeof spawn>,
+            output = "",
+            stderr = "",
+            bytes = 0,
+            settled = false;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const stop = () => {
+            if (!child?.pid) return;
+            try {
+                process.kill(process.platform === "win32" ? child.pid : -child.pid, "SIGKILL");
+            } catch {}
+        };
+        const finish = (error?: UsageError) => {
+            if (settled) return;
+            settled = true;
+            if (timer) clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abort);
+            if (error) {
+                stop();
+                reject(error);
+            } else accept(output);
+        };
+        const abort = () => finish(new UsageError("cancelled"));
+        try {
+            child = spawn(program, args, {
+                env: options.env ?? process.env,
+                stdio: ["ignore", "pipe", "pipe"],
+                detached: process.platform !== "win32",
+                windowsHide: true,
+            });
+        } catch {
+            finish(new UsageError("missing"));
+            return;
+        }
+        child.stdout!.setEncoding("utf8");
+        child.stderr!.setEncoding("utf8");
+        child.stdout!.on("data", (chunk: string) => {
+            bytes += Buffer.byteLength(chunk);
+            if (bytes > options.maxBuffer) finish(new UsageError("invalid_result"));
+            else output += chunk;
+        });
+        child.stderr!.on("data", (chunk: string) => {
+            if (stderr.length < 4096) stderr += chunk.slice(0, 4096 - stderr.length);
+        });
+        child.on("error", (error: NodeJS.ErrnoException) =>
+            finish(new UsageError(error.code === "ENOENT" || error.code === "EACCES" ? "missing" : "unavailable")),
+        );
+        child.on("close", (code) => finish(code === 0 ? undefined : new UsageError(classify(stderr))));
+        options.signal?.addEventListener("abort", abort, { once: true });
+        timer = setTimeout(() => finish(new UsageError("timeout")), options.timeout);
+        timer.unref();
+        if (options.signal?.aborted) abort();
+    });
+export const usageExecutable = (config: ResolvedConfig): string =>
+    join(
+        config.usageDir.startsWith("~/") ? join(homedir(), config.usageDir.slice(2)) : resolve(config.usageDir),
+        "usage",
+    );
+export function executableExists(file: string): boolean {
+    try {
+        accessSync(file, constants.X_OK);
+        return statSync(file).isFile();
+    } catch {
+        return false;
+    }
+}
+export function executableOnPath(program: string, env = process.env): boolean {
+    return (env.PATH || "")
+        .split(delimiter)
+        .filter(Boolean)
+        .some((dir) => executableExists(join(dir, program)));
+}

package/src/wsl.ts

@@ -0,0 +1,107 @@
+// What the AWS sign-in needs from WSL, where Pi often runs. Two things go wrong there, and both are repaired for the sign-in's
+// child process only, never for Pi itself:
+//
+//   The browser.  `aws sso login` opens $BROWSER. Inside WSL there is usually none, so the sign-in prints a link nobody sees.
+//                 With no BROWSER set (by the user, or by bedrock.browser) the child gets bin/windows-browser, which hands the
+//                 address to the Windows default browser. bedrock.browser names another program and wins everywhere.
+//   The interop.  WSL_INTEROP names the socket through which Linux starts Windows programs. A long-lived terminal or tmux server
+//                 can hold the socket of a session that is gone, and then every Windows program, the browser among them, hangs
+//                 and fails. A live socket answers `cmd.exe /c exit` in well under a second. When it does not, the child gets
+//                 the distro's own socket, which lives as long as WSL does. This follows the same rule.
+//
+// Outside WSL nothing here changes anything, except that bedrock.browser, which the user wrote, is still used.
+import { spawn } from "node:child_process";
+import { accessSync, constants, existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** The program that probes the interop socket: any Windows program would do, this one is always there. */
+export const WINDOWS_CMD = "/mnt/c/Windows/System32/cmd.exe";
+/** The distro's own interop socket. */
+export const INTEROP_FALLBACK = "/run/WSL/1_interop";
+/** How long the probe may take: a live socket answers in well under a second. */
+export const PROBE_TIMEOUT_MS = 2_000;
+/** The script that opens an address in the Windows default browser. */
+export const BROWSER_SCRIPT = fileURLToPath(new URL("../bin/windows-browser", import.meta.url));
+
+/** The parts of the machine this reads and runs, which a test replaces. */
+export interface WslDeps {
+    isWsl(env: NodeJS.ProcessEnv): boolean;
+    executable(file: string): boolean;
+    exists(file: string): boolean;
+    /** Whether Windows answers through the socket `env.WSL_INTEROP` names: runs `cmd.exe /c exit` for at most 2 seconds. */
+    interopAnswers(env: NodeJS.ProcessEnv): Promise<boolean>;
+    browserScript: string;
+}
+
+export const systemWsl: WslDeps = {
+    isWsl(env) {
+        if (env.WSL_DISTRO_NAME || env.WSL_INTEROP) return true;
+        try {
+            return /microsoft/i.test(readFileSync("/proc/sys/kernel/osrelease", "utf8"));
+        } catch {
+            return false;
+        }
+    },
+    executable(file) {
+        try {
+            accessSync(file, constants.X_OK);
+            return true;
+        } catch {
+            return false;
+        }
+    },
+    exists: existsSync,
+    interopAnswers: (env) =>
+        new Promise((resolve) => {
+            const child = spawn(WINDOWS_CMD, ["/c", "exit"], { stdio: "ignore", env });
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                resolve(false);
+            }, PROBE_TIMEOUT_MS);
+            child.once("error", () => {
+                clearTimeout(timer);
+                resolve(false);
+            });
+            child.once("exit", (code) => {
+                clearTimeout(timer);
+                resolve(code === 0);
+            });
+        }),
+    browserScript: BROWSER_SCRIPT,
+};
+
+export interface LoginEnvironment {
+    /** The environment for the sign-in's child: `base` with the repairs. `base` itself is not changed. */
+    env: NodeJS.ProcessEnv;
+    /** One line for the user for each repair that was made. */
+    notes: string[];
+}
+
+/** The environment `aws sso login` starts with: `base`, the browser and the interop socket as described above. */
+export async function loginEnvironment(
+    settings: { browser?: string },
+    base: NodeJS.ProcessEnv,
+    deps: WslDeps = systemWsl,
+): Promise<LoginEnvironment> {
+    const env = { ...base };
+    const notes: string[] = [];
+    // A program the user named wins everywhere: they wrote it in jig.json.
+    if (settings.browser) env.BROWSER = settings.browser;
+    if (!deps.isWsl(base)) return { env, notes };
+    const socket = base.WSL_INTEROP;
+    if (
+        socket &&
+        socket !== INTEROP_FALLBACK &&
+        deps.executable(WINDOWS_CMD) &&
+        deps.exists(INTEROP_FALLBACK) &&
+        !(await deps.interopAnswers(base))
+    ) {
+        env.WSL_INTEROP = INTEROP_FALLBACK;
+        notes.push(
+            `The Windows interop socket ${socket} does not answer; using ${INTEROP_FALLBACK} for the AWS sign-in.`,
+        );
+    }
+    // A BROWSER the user set is theirs. An unset one, or an empty one, which programs ignore, is filled.
+    if (!settings.browser && !base.BROWSER) env.BROWSER = deps.browserScript;
+    return { env, notes };
+}