glm-coding-router 1.0.0 → 1.1.0

package/dist/bin/glm-worker.js

@@ -11,8 +11,20 @@ import { spawnAgent } from "../core/process.js";
 import { resolveZaiApiKey } from "../core/zai-key.js";
 /** Worker tool surface (spec §16). */
 export const WORKER_TOOLS = "Read,Glob,Grep,Edit,Write,Bash";
+/** Same surface minus Bash, used when no Bash command is allowed. */
+export const WORKER_TOOLS_NO_BASH = "Read,Glob,Grep,Edit,Write";
+/**
+ * Build the child arguments (spec §16, specs/worker-bash-permissions.md).
+ *
+ * `--permission-mode acceptEdits` auto-approves file edits but NOT shell
+ * commands, and headless `-p` has no prompt to answer — so without an explicit
+ * `--allowedTools` every Bash call comes back "This command requires
+ * approval". When the allowlist is empty we drop Bash from `--tools` entirely
+ * rather than advertising a tool the worker can never use.
+ */
 export function buildWorkerArgs(prompt, config) {
-    return [
+    const allowedBash = config.worker.allowedBash;
+    const args = [
         "-p",
         prompt,
         "--max-turns",
@@ -20,8 +32,25 @@ export function buildWorkerArgs(prompt, config) {
         "--permission-mode",
         "acceptEdits",
         "--tools",
-        WORKER_TOOLS,
+        allowedBash.length > 0 ? WORKER_TOOLS : WORKER_TOOLS_NO_BASH,
     ];
+    if (allowedBash.length > 0) {
+        args.push("--allowedTools", ...allowedBash.map((pattern) => `Bash(${pattern})`));
+    }
+    return args;
+}
+/** Strip `--no-bash`, which empties the allowlist for one invocation. */
+export function extractNoBashFlag(argv) {
+    const rest = [];
+    let noBash = false;
+    for (const arg of argv) {
+        if (arg === "--no-bash") {
+            noBash = true;
+            continue;
+        }
+        rest.push(arg);
+    }
+    return { rest, noBash };
 }
 /**
  * glm-worker (spec §15, §16): headless implementation worker.
@@ -29,9 +58,13 @@ export function buildWorkerArgs(prompt, config) {
  * --dangerously-skip-permissions.
  */
 export async function runWorker(argv) {
-    const { rest, profile } = extractProfileFlag(argv);
+    const { rest: withoutProfile, profile } = extractProfileFlag(argv);
+    const { rest, noBash } = extractNoBashFlag(withoutProfile);
     const prompt = await resolvePrompt(rest);
-    const config = applyProfile(loadConfig(), profile);
+    const loaded = applyProfile(loadConfig(), profile);
+    const config = noBash
+        ? { ...loaded, worker: { ...loaded.worker, allowedBash: [] } }
+        : loaded;
     const resolved = resolveZaiApiKey();
     if (!resolved) {
         throw Errors.zaiKeyMissing();

package/dist/commands/doctor.js

@@ -2,7 +2,8 @@ import os from "node:os";
 import { execFileSync } from "node:child_process";
 import { defaultConfig, loadConfig } from "../core/config.js";
 import { locateClaude, locateCodex, searchPathFor } from "../core/claude.js";
-import { isWindows, windowsVersionName } from "../core/platform.js";
+import { platformName, platformSupport } from "../core/platform.js";
+import { describeKeyStore, detectUserEnvStore } from "../core/user-env.js";
 import { resolveZaiApiKey } from "../core/zai-key.js";
 import { configPath } from "../core/paths.js";
 import fs from "node:fs";
@@ -28,8 +29,13 @@ export function runDoctorChecks(options = {}) {
     const results = [];
     const home = options.home ?? os.homedir();
     const env = options.env ?? process.env;
-    // --- System ---
-    results.push(check("System", isWindows() ? windowsVersionName() : `Platform ${process.platform}`, isWindows() ? "ok" : "fail", undefined, isWindows() ? undefined : "v0.1 targets Windows only."));
+    // --- System (specs/cross-platform.md) ---
+    const support = platformSupport();
+    results.push(check("System", platformName(), support === "supported" ? "ok" : support === "experimental" ? "warn" : "fail", undefined, support === "experimental"
+        ? "macOS support is experimental — the suite has not been run on a Mac."
+        : support === "unsupported"
+            ? "Supported: Windows, Linux. macOS is experimental."
+            : undefined));
     const nodeMajor = nodeVersionMajor();
     results.push(check("System", `Node.js ${process.versions.node}`, nodeMajor >= 20 ? "ok" : "fail", undefined, nodeMajor >= 20 ? undefined : "glm-coding-router requires Node.js >= 20."));
     results.push(check("System", "Git", gitFound() ? "ok" : "warn"));
@@ -60,9 +66,19 @@ export function runDoctorChecks(options = {}) {
     const codexPath = locateCodex(config, env);
     results.push(check("Agents", "Codex", codexPath ? "ok" : "warn", codexPath, codexPath ? undefined : "Optional — Claude-only setups are supported."));
     // --- Z.ai key ---
+    const store = options.store ?? detectUserEnvStore();
     const resolved = resolveZaiApiKey({ env, readUserEnv: options.readUserEnv });
-    results.push(check("Z.ai", "ZAI_API_KEY", resolved ? "ok" : "fail", resolved ? `configured (${resolved.source})` : "not found", resolved ? undefined : "Run: glm-router key set"));
+    const sourceLabel = resolved?.source === "process-env" ? "process environment" : describeKeyStore(store);
+    results.push(check("Z.ai", "ZAI_API_KEY", resolved ? "ok" : "fail", resolved ? `configured (${sourceLabel})` : "not found", resolved
+        ? undefined
+        : store === "none"
+            ? 'Set it: export ZAI_API_KEY="<your-key>" (see: glm-router key set)'
+            : "Run: glm-router key set"));
     results.push(check("Z.ai", "Anthropic endpoint", "ok", config.provider.anthropicBaseUrl));
+    // specs/worker-bash-permissions.md — what the worker is allowed to execute.
+    results.push(check("Z.ai", "Worker shell access", "ok", config.worker.allowedBash.length > 0
+        ? `${config.worker.allowedBash.length} allowed Bash patterns`
+        : "disabled (Bash not offered to the worker)"));
     // --- Commands (PATH shims; a dev checkout warns instead of failing) ---
     for (const command of ["glm-chat", "glm-worker", "glm-review"]) {
         const found = searchPathFor(command);
@@ -86,7 +102,7 @@ export function runDoctorChecks(options = {}) {
         results.push(check("Environment", "Process environment", "ok", "ZAI_API_KEY visible in current process"));
     }
     else if (resolved) {
-        results.push(check("Environment", "Process environment", "warn", "Current process does not contain ZAI_API_KEY", "This is safe. GLM workers reload the key automatically from the Windows User Environment."));
+        results.push(check("Environment", "Process environment", "warn", "Current process does not contain ZAI_API_KEY", `This is safe. GLM workers reload the key automatically from ${describeKeyStore(store)}.`));
     }
     return { results, config, keySource: resolved?.source };
 }

package/dist/commands/init.js

@@ -6,7 +6,8 @@ import { configPath } from "../core/paths.js";
 import { ExitCode } from "../core/errors.js";
 import { runDoctorChecks } from "./doctor.js";
 import { setWindowsUserEnv, ZAI_API_KEY_ENV } from "../core/zai-key.js";
-import { isWindows } from "../core/platform.js";
+import { detectUserEnvStore } from "../core/user-env.js";
+import { printShellKeyGuidance } from "./key.js";
 import { CodexSkillInstaller, glmDelegationSkill } from "../integrations/skill.js";
 import { version } from "../core/version.js";
 function renderEnvironment(results) {
@@ -84,8 +85,9 @@ export async function initCommand(options, deps = {}) {
         process.stdout.write(`✓ ${ZAI_API_KEY_ENV} already configured (${report.keySource})\n`);
     }
     else if (choices.configureKey) {
-        if (!isWindows()) {
-            process.stdout.write("⚠ Key storage requires Windows in v0.1 — skipped\n");
+        if ((deps.store ?? detectUserEnvStore()) === "none") {
+            // No persistent store here; tell the user the one line that works.
+            printShellKeyGuidance({ env: deps.env });
         }
         else {
             const keyResponse = await prompt({

package/dist/commands/key.js

@@ -1,12 +1,41 @@
 import prompts from "prompts";
-import { assertWindows } from "../core/platform.js";
-import { Errors } from "../core/errors.js";
+import { Errors, formatGlmError } from "../core/errors.js";
 import { logger } from "../core/logging.js";
+import { describeKeyStore, describeShellExport, detectUserEnvStore, } from "../core/user-env.js";
 import { ZAI_API_KEY_ENV, deleteWindowsUserEnv, resolveZaiApiKey, setWindowsUserEnv, } from "../core/zai-key.js";
 import { emitJson } from "./context.js";
+/**
+ * Print the shell-profile guidance used when the platform has no persistent
+ * secret store (the common Linux case: `secret-tool` is not installed by
+ * default). specs/cross-platform.md.
+ */
+export function printShellKeyGuidance(deps = {}) {
+    const { line, profile } = describeShellExport(ZAI_API_KEY_ENV, {
+        env: deps.env,
+        home: deps.home,
+    });
+    process.stdout.write([
+        `This platform has ${describeKeyStore("none")} that ${ZAI_API_KEY_ENV} can be saved to,`,
+        "so set it yourself — it takes one line:",
+        "",
+        `  ${line}`,
+        "",
+        `Add that to ${profile} so new shells inherit it, then run:`,
+        "",
+        "  glm-router key check",
+        "",
+        "The current shell keeps its old environment until you re-source that file",
+        "or open a new terminal.",
+        "",
+    ].join("\n"));
+}
 /** glm-router key set (spec §11): prompt, save to Windows User Environment. */
 export async function keySetCommand(_options, deps = {}) {
-    assertWindows();
+    const store = deps.store ?? detectUserEnvStore();
+    if (store === "none") {
+        printShellKeyGuidance(deps);
+        return 0;
+    }
     const prompt = deps.prompt ?? prompts;
     const setEnv = deps.setEnv ?? setWindowsUserEnv;
     const response = await prompt({
@@ -24,10 +53,10 @@ export async function keySetCommand(_options, deps = {}) {
         setEnv(ZAI_API_KEY_ENV, key);
     }
     catch (error) {
-        logger.error(`Failed to write the Windows User Environment: ${error instanceof Error ? error.message : String(error)}`);
+        logger.error(`Failed to write ${describeKeyStore(store)}: ${error instanceof Error ? error.message : String(error)}`);
         return 1;
     }
-    process.stdout.write(`\n✓ Saved to Windows User Environment:\n  ${ZAI_API_KEY_ENV}\n`);
+    process.stdout.write(`\n✓ Saved to ${describeKeyStore(store)}:\n  ${ZAI_API_KEY_ENV}\n`);
     process.stdout.write("\nOpen a NEW terminal (or restart your Orca terminal) so the current process picks it up.\n");
     return 0;
 }
@@ -42,18 +71,26 @@ export function keyCheckCommand(options, deps = {}) {
         return resolved ? 0 : 10;
     }
     if (!resolved) {
-        // Formatted per spec §36; exit 10 (spec §35).
+        // Formatted per spec §36; exit 10 (spec §35). The hint is platform-aware,
+        // so it never points at a command that cannot finish the job here.
         const error = Errors.zaiKeyMissing();
-        process.stderr.write(`ERROR [${error.codeName}]\n\n${error.message}\n\nRun:\n\n  glm-router key set\n`);
+        process.stderr.write(formatGlmError(error) + "\n");
         return error.exitCode;
     }
-    const sourceLabel = resolved.source === "process-env" ? "process environment" : "Windows User Environment";
+    const sourceLabel = resolved.source === "process-env"
+        ? "process environment"
+        : describeKeyStore(deps.store ?? detectUserEnvStore());
     process.stdout.write(`${ZAI_API_KEY_ENV}: configured\nSource: ${sourceLabel}\n`);
     return 0;
 }
 /** Used by uninstall; keeps the key by default (spec §44). */
 export async function keyRemoveCommand(deps = {}) {
-    assertWindows();
+    const store = deps.store ?? detectUserEnvStore();
+    if (store === "none") {
+        // Nothing this tool owns; the key lives in a shell profile the user wrote.
+        process.stdout.write(`${ZAI_API_KEY_ENV} is not stored by glm-router on this platform — remove the export line from your shell profile.\n`);
+        return;
+    }
     const deleteEnv = deps.deleteEnv ?? deleteWindowsUserEnv;
     deleteEnv(ZAI_API_KEY_ENV);
 }

package/dist/commands/uninstall.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import { configDir } from "../core/paths.js";
 import { ExitCode } from "../core/errors.js";
+import { describeKeyStore, detectUserEnvStore } from "../core/user-env.js";
 import { CodexSkillInstaller, glmDelegationSkill } from "../integrations/skill.js";
 import { keyRemoveCommand } from "./key.js";
 import { removeClaudeIntegration, removeCodexIntegration } from "../integrations/index.js";
@@ -85,7 +86,7 @@ export async function uninstallCommand(options, deps = {}) {
     }
     if (choices.removeKey) {
         await keyRemoveCommand({ deleteEnv: deps.deleteEnv });
-        process.stdout.write("✓ ZAI_API_KEY removed from Windows User Environment\n");
+        process.stdout.write(`✓ ZAI_API_KEY removed from ${describeKeyStore(detectUserEnvStore())}\n`);
     }
     else {
         process.stdout.write("✓ ZAI_API_KEY kept\n");

package/dist/core/config.js

@@ -6,6 +6,34 @@ import { configDir, configPath } from "./paths.js";
 export const DEFAULT_ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic";
 export const DEFAULT_MAIN_MODEL = "glm-5.3";
 export const DEFAULT_FAST_MODEL = "glm-5.3-flash";
+/**
+ * Bash commands the worker may run without an approval prompt
+ * (specs/worker-bash-permissions.md). Headless `-p` has no prompt to answer,
+ * so without this every Bash call is denied and the worker cannot validate its
+ * own work. Validation commands only: no git writes, no rm, no network, no
+ * package installs.
+ */
+export const DEFAULT_ALLOWED_BASH = [
+    "npm test",
+    "npm run *",
+    "npx vitest *",
+    "go test *",
+    "pytest*",
+    "python3 *",
+    "cargo test*",
+    "git status",
+    "git diff*",
+];
+/** Shell metacharacters defeat pattern matching, so they may not appear. */
+const BASH_PATTERN_FORBIDDEN = /[&;|`$><\n]/;
+const AllowedBashSchema = z
+    .array(z
+    .string()
+    .min(1)
+    .refine((value) => !BASH_PATTERN_FORBIDDEN.test(value), {
+    message: "must not contain shell metacharacters (& ; | ` $ > <)",
+}))
+    .default([...DEFAULT_ALLOWED_BASH]);
 /** Named model/maxTurns overlay selected via --profile (specs/glm-fast-profiles.md). */
 export const ProfileSchema = z.object({
     main: z.string().min(1).optional(),
@@ -25,7 +53,8 @@ export const ConfigSchema = z.object({
     }),
     worker: z.object({
         maxTurns: z.number().int().positive(),
-    }).default({ maxTurns: 20 }),
+        allowedBash: AllowedBashSchema,
+    }).default({ maxTurns: 20, allowedBash: [...DEFAULT_ALLOWED_BASH] }),
     review: z.object({
         maxTurns: z.number().int().positive(),
     }).default({ maxTurns: 15 }),
@@ -51,7 +80,7 @@ export function defaultConfig() {
             main: DEFAULT_MAIN_MODEL,
             fast: DEFAULT_FAST_MODEL,
         },
-        worker: { maxTurns: 20 },
+        worker: { maxTurns: 20, allowedBash: [...DEFAULT_ALLOWED_BASH] },
         review: { maxTurns: 15 },
         integrations: {
             claude: true,

package/dist/core/errors.js

@@ -1,3 +1,15 @@
+/*
+ * This module deliberately does NOT import platform.ts: platform.ts imports
+ * Errors, so the dependency would be circular. The couple of platform checks
+ * below read process.platform directly (specs/cross-platform.md).
+ */
+const onWindows = () => process.platform === "win32";
+/** Config dir as the user's own platform spells it. */
+function configPathHint() {
+    return onWindows()
+        ? "%USERPROFILE%\\.glm-coding-router\\config.json"
+        : "~/.glm-coding-router/config.json";
+}
 /** Standard exit codes (spec §35). */
 export const ExitCode = {
     Success: 0,
@@ -29,17 +41,26 @@ export const Errors = {
     zaiKeyMissing: () => new GlmRouterError({
         name: "ZAI_KEY_MISSING",
         message: "ZAI_API_KEY was not found.",
-        hint: ["Run:", "", "  glm-router key set"],
+        // On platforms without a persistent store `key set` can only print
+        // guidance, so the export line is shown here too — otherwise this hint
+        // points at a command that cannot finish the job.
+        hint: onWindows()
+            ? ["Run:", "", "  glm-router key set"]
+            : [
+                "Run:",
+                "",
+                "  glm-router key set",
+                "",
+                "or set it in this shell and your shell profile:",
+                "",
+                '  export ZAI_API_KEY="<your-key>"',
+            ],
         exitCode: ExitCode.ZaiKeyMissing,
     }),
     configInvalid: (detail) => new GlmRouterError({
         name: "CONFIG_INVALID",
         message: `Configuration is invalid: ${detail}`,
-        hint: [
-            "Fix or remove the config file:",
-            "",
-            "  %USERPROFILE%\\.glm-coding-router\\config.json",
-        ],
+        hint: ["Fix or remove the config file:", "", `  ${configPathHint()}`],
         exitCode: ExitCode.ConfigInvalid,
     }),
     claudeNotFound: (detail) => new GlmRouterError({
@@ -49,11 +70,13 @@ export const Errors = {
         hint: [
             "Expected:",
             "",
-            "  claude.exe",
+            onWindows() ? "  claude.exe" : "  claude",
             "",
             "Install Claude Code or set an override:",
             "",
-            "  glm-router config set claudePath C:\\path\\to\\claude.exe",
+            onWindows()
+                ? "  glm-router config set claudePath C:\\path\\to\\claude.exe"
+                : "  glm-router config set claudePath /path/to/claude",
         ],
         exitCode: ExitCode.ClaudeNotFound,
     }),
@@ -81,8 +104,8 @@ export const Errors = {
     }),
     unsupportedPlatform: (platform) => new GlmRouterError({
         name: "UNSUPPORTED_PLATFORM",
-        message: `This command requires Windows (detected: ${platform}).`,
-        hint: ["Linux and macOS support is planned for v0.2."],
+        message: `This platform is not supported (detected: ${platform}).`,
+        hint: ["Supported: Windows, Linux. macOS is experimental."],
         exitCode: ExitCode.UnsupportedPlatform,
     }),
     promptRequired: (command = "glm-worker") => new GlmRouterError({

package/dist/core/platform.js

@@ -3,18 +3,47 @@ import { Errors } from "./errors.js";
 export function isWindows() {
     return process.platform === "win32";
 }
-/** Human-readable Windows version from os.release() ("10.0.26200" → "Windows 11"). */
-export function windowsVersionName() {
-    if (!isWindows()) {
-        return process.platform;
+/**
+ * Support level per platform:
+ *   win32  — verified through the registry-verification ritual
+ *   linux  — verified 2026-09-20 on Ubuntu 24.04
+ *   darwin — designed but never executed; no Mac has run the suite
+ */
+export function platformSupport(platform = process.platform) {
+    if (platform === "win32" || platform === "linux")
+        return "supported";
+    if (platform === "darwin")
+        return "experimental";
+    return "unsupported";
+}
+export function isSupportedPlatform(platform = process.platform) {
+    return platformSupport(platform) !== "unsupported";
+}
+/** Human-readable platform name for doctor/status. */
+export function platformName(platform = process.platform, release = os.release()) {
+    if (platform === "win32") {
+        const build = Number.parseInt(release.split(".")[2] ?? "0", 10);
+        return build >= 22000 ? "Windows 11" : "Windows 10";
     }
-    const release = os.release();
-    const build = Number.parseInt(release.split(".")[2] ?? "0", 10);
-    return build >= 22000 ? "Windows 11" : "Windows 10";
+    if (platform === "darwin")
+        return `macOS (darwin ${release.split(".")[0] ?? "?"})`;
+    if (platform === "linux")
+        return `Linux ${release.split("-")[0] ?? release}`;
+    return `Platform ${platform}`;
 }
-/** Guard for commands that require Windows-specific machinery (PowerShell user env, etc.). */
+/** @deprecated use platformName(); kept so existing callers keep compiling. */
+export function windowsVersionName() {
+    return platformName();
+}
+/** Guard for the few code paths that are genuinely Windows-only. */
 export function assertWindows() {
     if (!isWindows()) {
         throw Errors.unsupportedPlatform(process.platform);
     }
 }
+/** Guard for commands that need a platform this package supports at all. */
+export function assertSupportedPlatform() {
+    if (!isSupportedPlatform()) {
+        throw Errors.unsupportedPlatform(process.platform);
+    }
+}

package/dist/core/profile.js

@@ -51,7 +51,12 @@ export function applyProfile(config, name) {
             main: profile.main ?? config.models.main,
             fast: profile.fast ?? config.models.fast,
         },
-        worker: { maxTurns: profile.workerMaxTurns ?? config.worker.maxTurns },
+        worker: {
+            maxTurns: profile.workerMaxTurns ?? config.worker.maxTurns,
+            // Profiles tune models and turn budgets, never the Bash allowlist —
+            // that is a security setting, not a performance knob.
+            allowedBash: config.worker.allowedBash,
+        },
         review: { maxTurns: profile.reviewMaxTurns ?? config.review.maxTurns },
     };
 }

package/dist/core/user-env.js

@@ -0,0 +1,181 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+/** Keychain/libsecret service name; the variable name is the account. */
+export const KEY_STORE_SERVICE = "glm-coding-router";
+/** Only well-formed variable names may reach a child process (spec §38). */
+function assertEnvVarName(name) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new Error(`Invalid environment variable name: ${name}`);
+    }
+}
+function defaultRun(file, args, options) {
+    const result = execFileSync(file, [...args], {
+        encoding: "utf8",
+        windowsHide: true,
+        input: options.input,
+        stdio: options.input === undefined
+            ? ["ignore", options.capture ? "pipe" : "ignore", "ignore"]
+            : ["pipe", options.capture ? "pipe" : "ignore", "ignore"],
+    });
+    return typeof result === "string" ? result : "";
+}
+/** Is `name` an executable file somewhere on PATH? */
+function defaultHasCommand(name, env = process.env) {
+    const dirs = (env.PATH ?? "").split(path.delimiter).filter((d) => d.length > 0);
+    return dirs.some((dir) => {
+        try {
+            return fs.statSync(path.join(dir, name)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Which store this machine has. `libsecret` requires `secret-tool` on PATH —
+ * it is NOT installed by default on Ubuntu, so "none" is a normal Linux
+ * outcome, not an error (specs/cross-platform.md).
+ */
+export function detectUserEnvStore(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const env = deps.env ?? process.env;
+    const hasCommand = deps.hasCommand ?? ((name) => defaultHasCommand(name, env));
+    if (platform === "win32")
+        return "windows-user-env";
+    if (platform === "darwin")
+        return hasCommand("security") ? "macos-keychain" : "none";
+    if (platform === "linux")
+        return hasCommand("secret-tool") ? "libsecret" : "none";
+    return "none";
+}
+/** Human wording for the store, used by key/doctor/uninstall messages. */
+export function describeKeyStore(store) {
+    switch (store) {
+        case "windows-user-env":
+            return "Windows User Environment";
+        case "macos-keychain":
+            return "macOS login keychain";
+        case "libsecret":
+            return "the system keyring (libsecret)";
+        case "none":
+            return "no persistent store";
+    }
+}
+/**
+ * Read a variable from the per-user store. Returns undefined on any failure —
+ * callers fall back or raise their own error.
+ */
+export function readUserEnv(name, deps = {}) {
+    assertEnvVarName(name);
+    const store = detectUserEnvStore(deps);
+    const run = deps.run ?? defaultRun;
+    try {
+        let value;
+        switch (store) {
+            case "windows-user-env":
+                value = run("powershell.exe", [
+                    "-NoProfile",
+                    "-NonInteractive",
+                    "-Command",
+                    `[Environment]::GetEnvironmentVariable('${name}','User')`,
+                ], { capture: true });
+                break;
+            case "macos-keychain":
+                value = run("security", ["find-generic-password", "-s", KEY_STORE_SERVICE, "-a", name, "-w"], { capture: true });
+                break;
+            case "libsecret":
+                value = run("secret-tool", ["lookup", "service", KEY_STORE_SERVICE, "account", name], { capture: true });
+                break;
+            case "none":
+                return undefined;
+        }
+        const trimmed = value.trim();
+        return trimmed || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Write a variable to the per-user store. Throws when there is no store —
+ * callers print platform-appropriate guidance instead.
+ *
+ * The value never goes through a shell. On Windows and Linux it is passed via
+ * a child environment variable / stdin respectively, so it never appears in
+ * any process's argv. The macOS backend has no stdin form, so the value is in
+ * `security`'s argv for the duration of that call — a known limitation of the
+ * experimental darwin support (specs/cross-platform.md).
+ */
+export function writeUserEnv(name, value, deps = {}) {
+    assertEnvVarName(name);
+    const store = detectUserEnvStore(deps);
+    const run = deps.run ?? defaultRun;
+    switch (store) {
+        case "windows-user-env":
+            execFileSync("powershell.exe", [
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                `[Environment]::SetEnvironmentVariable('${name}', $env:GLM_ROUTER_VALUE, 'User')`,
+            ], {
+                windowsHide: true,
+                stdio: ["ignore", "ignore", "pipe"],
+                env: { ...process.env, GLM_ROUTER_VALUE: value },
+            });
+            return;
+        case "macos-keychain":
+            run("security", ["add-generic-password", "-U", "-s", KEY_STORE_SERVICE, "-a", name, "-w", value], { capture: false });
+            return;
+        case "libsecret":
+            run("secret-tool", ["store", "--label", `${KEY_STORE_SERVICE} ${name}`, "service", KEY_STORE_SERVICE, "account", name], { input: value, capture: false });
+            return;
+        case "none":
+            throw new Error("no persistent secret store is available on this platform");
+    }
+}
+/** Remove the variable from the per-user store. No store → nothing to do. */
+export function deleteUserEnv(name, deps = {}) {
+    assertEnvVarName(name);
+    const store = detectUserEnvStore(deps);
+    const run = deps.run ?? defaultRun;
+    switch (store) {
+        case "windows-user-env":
+            run("powershell.exe", [
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                `[Environment]::SetEnvironmentVariable('${name}', $null, 'User')`,
+            ], { capture: false });
+            return;
+        case "macos-keychain":
+            run("security", ["delete-generic-password", "-s", KEY_STORE_SERVICE, "-a", name], { capture: false });
+            return;
+        case "libsecret":
+            run("secret-tool", ["clear", "service", KEY_STORE_SERVICE, "account", name], {
+                capture: false,
+            });
+            return;
+        case "none":
+            return;
+    }
+}
+/**
+ * The shell line a user must add when there is no store, plus the profile file
+ * to put it in. Chosen from $SHELL, preferring a file that already exists.
+ */
+export function describeShellExport(name, deps = {}) {
+    const env = deps.env ?? process.env;
+    const home = deps.home ?? env.HOME ?? "~";
+    const exists = deps.exists ?? ((file) => fs.existsSync(file));
+    const shell = path.basename(env.SHELL ?? "bash");
+    const candidates = shell === "zsh"
+        ? [".zshrc", ".zprofile", ".profile"]
+        : shell === "fish"
+            ? [".config/fish/config.fish"]
+            : [".bashrc", ".bash_profile", ".profile"];
+    const found = candidates.find((rel) => exists(path.join(home, rel)));
+    const profile = path.join(home, found ?? candidates[0]);
+    const line = shell === "fish" ? `set -gx ${name} <your-key>` : `export ${name}="<your-key>"`;
+    return { line, profile };
+}