@event4u/agent-switch 2.1.0 → 2.2.0

package/dist/service.js

@@ -68,21 +68,36 @@ export function schtasksCreateArgs(exec, args, label = LABEL) {
     return ["/create", "/tn", label, "/tr", cmd, "/sc", "onlogon", "/f"];
 }
 // ---------- manifest ----------
-function readManifest() {
+function readManifestRaw() {
     try {
         const d = JSON.parse(fs.readFileSync(MANIFEST, "utf8"));
-        return Array.isArray(d?.files) ? d.files : [];
+        const inv = d?.invocation;
+        const invocation = inv && typeof inv.exec === "string" && Array.isArray(inv.args) ? { exec: inv.exec, args: inv.args.map(String) } : null;
+        return { files: Array.isArray(d?.files) ? d.files : [], invocation };
     }
     catch {
-        return [];
+        return { files: [], invocation: null };
     }
 }
+function readManifest() {
+    return readManifestRaw().files;
+}
 function writeManifest(files) {
     fs.mkdirSync(ROOT, { recursive: true });
-    fs.writeFileSync(MANIFEST, JSON.stringify({ label: LABEL, files }, null, 2) + "\n", { mode: 0o600 });
+    // The invocation is what `activate` compares against to re-point the service.
+    fs.writeFileSync(MANIFEST, JSON.stringify({ label: LABEL, files, invocation: runInvocation() }, null, 2) + "\n", { mode: 0o600 });
+}
+/** Whether the installed service runs this very CLI. An install from before the
+ *  manifest recorded its invocation counts as another one. */
+export function serviceTarget() {
+    const m = readManifestRaw();
+    if (!m.files.length)
+        return "not-installed";
+    const me = runInvocation();
+    return m.invocation && m.invocation.exec === me.exec && m.invocation.args.join("\0") === me.args.join("\0") ? "this-cli" : "other-cli";
 }
 // ---------- install / uninstall ----------
-export function serviceInstall() {
+export function serviceInstall(log = console.log) {
     const { exec, args } = runInvocation();
     fs.mkdirSync(ROOT, { recursive: true });
     if (process.platform === "darwin") {
@@ -94,7 +109,7 @@ export function serviceInstall() {
         if (r.status !== 0)
             die(`launchctl load failed: ${r.stderr || r.stdout}`);
         writeManifest([plist]);
-        console.log(`Installed LaunchAgent ${plist} (loaded).`);
+        log(`Installed LaunchAgent ${plist} (loaded).`);
     }
     else if (process.platform === "linux") {
         const unit = path.join(os.homedir(), ".config", "systemd", "user", "agent-switch.service");
@@ -103,16 +118,16 @@ export function serviceInstall() {
         spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
         const r = spawnSync("systemctl", ["--user", "enable", "--now", "agent-switch.service"], { encoding: "utf8" });
         if (r.status !== 0)
-            console.log(`(note: \`systemctl --user enable --now\` returned nonzero — unit written to ${unit}; enable manually if needed)`);
+            log(`(note: \`systemctl --user enable --now\` returned nonzero — unit written to ${unit}; enable manually if needed)`);
         writeManifest([unit]);
-        console.log(`Installed systemd user unit ${unit}.`);
+        log(`Installed systemd user unit ${unit}.`);
     }
     else if (process.platform === "win32") {
         const r = spawnSync("schtasks", schtasksCreateArgs(exec, args), { encoding: "utf8" });
         if (r.status !== 0)
             die(`schtasks /create failed: ${r.stderr || r.stdout}`);
         writeManifest([`schtasks:${LABEL}`]); // a task, not a file
-        console.log(`Installed Task Scheduler logon task ${LABEL}.`);
+        log(`Installed Task Scheduler logon task ${LABEL}.`);
     }
     else {
         die(`service install is not supported on ${process.platform}`);

package/dist/sessions.js

@@ -10,7 +10,7 @@
  *
  * Iron rules (roadmap: road-to-session-handoff):
  *   - Transcripts are OPAQUE, version-unstable blobs FOR TRANSFER. The only
- *     read in THIS module is `readSessionHeader` — first line, capped,
+ *     read in THIS module is `readSessionHeader` — first 64 KiB, capped,
  *     try/catch. There are exactly TWO sanctioned body readers, both guarded +
  *     capped + fenced + degraded-mode, and NO others: read-only TELEMETRY
  *     (context/token counts, `src/telemetry.ts`, road-to-agent-switch-session-
@@ -33,9 +33,9 @@ import { liveSessionPids } from "./api.js";
 export function encodeProjectDir(cwd) {
     return cwd.replace(/[^A-Za-z0-9]/g, "-");
 }
-/** Best-effort metadata from a transcript's FIRST line only. The line is
- *  capped (a >64 KiB first line counts as unparseable), the parse is fenced,
- *  and absence degrades to nulls — the format is internal and version-unstable,
+/** Best-effort metadata (cwd, summary) from the complete lines in a
+ *  transcript's first 64 KiB. Each parse is fenced, a line cut by the cap is
+ *  ignored, and absence degrades to nulls — the format is internal and version-unstable,
  *  so a failed parse must never fail a listing. */
 const HEADER_CAP = 64 * 1024;
 export function readSessionHeader(file) {
@@ -51,15 +51,30 @@ export function readSessionHeader(file) {
         const buf = Buffer.alloc(HEADER_CAP);
         const n = fs.readSync(fd, buf, 0, HEADER_CAP, 0);
         const chunk = buf.subarray(0, n).toString("utf8");
-        const nl = chunk.indexOf("\n");
-        if (nl < 0 && n === HEADER_CAP)
-            return none; // first line larger than the cap
-        const line = nl >= 0 ? chunk.slice(0, nl) : chunk;
-        const parsed = JSON.parse(line);
-        return {
-            cwd: typeof parsed?.cwd === "string" ? parsed.cwd : null,
-            summary: typeof parsed?.summary === "string" ? parsed.summary : null,
-        };
+        // Claude Code 2.1.x opens with metadata lines that carry no cwd, so scan the
+        // complete lines inside the cap. A trailing partial line (cut by the cap) is
+        // dropped rather than guessed at.
+        const lines = chunk.split("\n");
+        if (n === HEADER_CAP)
+            lines.pop();
+        let cwd = null;
+        let summary = null;
+        for (const line of lines) {
+            if (cwd !== null && summary !== null)
+                break;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (cwd === null && typeof parsed?.cwd === "string")
+                cwd = parsed.cwd;
+            if (summary === null && typeof parsed?.summary === "string")
+                summary = parsed.summary;
+        }
+        return { cwd, summary };
     }
     catch {
         return none;
@@ -68,6 +83,60 @@ export function readSessionHeader(file) {
         fs.closeSync(fd);
     }
 }
+/** Tools that always stop for the user's answer. Other tools can't be told
+ *  apart from one that is still running. */
+const QUESTION_TOOLS = new Set(["AskUserQuestion", "ExitPlanMode"]);
+const TAIL_CAP = 64 * 1024;
+/** Whether the transcript ends on an open question to the user. */
+export function awaitingAnswer(file) {
+    return openQuestion(file) !== null;
+}
+/**
+ * The id of the question the transcript ends on — an AskUserQuestion /
+ * ExitPlanMode call with no tool_result after it — or null. The id tells one
+ * question from the next, so two in a row are two moments. Reads only the
+ * last {@link TAIL_CAP} bytes.
+ */
+export function openQuestion(file) {
+    let text;
+    try {
+        const fd = fs.openSync(file, "r");
+        try {
+            const size = fs.fstatSync(fd).size;
+            const len = Math.min(size, TAIL_CAP);
+            const buf = Buffer.alloc(len);
+            fs.readSync(fd, buf, 0, len, size - len);
+            text = buf.toString("utf8");
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return null;
+    }
+    const open = new Set();
+    // The first line may be cut off by the tail window; it fails to parse and is skipped.
+    for (const line of text.split("\n")) {
+        let d;
+        try {
+            d = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const content = d?.message?.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const p of content) {
+            if (p?.type === "tool_use" && p.id && p.name && QUESTION_TOOLS.has(p.name))
+                open.add(p.id);
+            else if (p?.type === "tool_result" && p.tool_use_id)
+                open.delete(p.tool_use_id);
+        }
+    }
+    return open.size ? [...open][open.size - 1] : null;
+}
 /** Recent sessions of one profile config dir, newest first, capped at `limit`.
  *  Pure directory scan — works on seeded fakes, shared trees, and win32. */
 export function listSessions(configDir, limit) {

package/dist/share.js

@@ -15,9 +15,15 @@
  *     re-links (last-sync-wins across profiles). On win32, file symlinks need
  *     Developer Mode/admin, so file links degrade with a message there.
  *
+ *   - Prompt history (`history.jsonl`, what ↑ and Ctrl+R search) — always
+ *     linked: it holds no account state, and Claude Code only ever APPENDS to
+ *     it (under a lock), so the link never forks. A profile's own file is
+ *     merged into the shared one (chronological, de-duplicated) and kept as a
+ *     `history.jsonl.pre-share*` backup instead of blocking the link.
+ *
  * Account-/instance-scoped items (`.claude.json`, `.credentials.json`,
  * `plugins/`, `sessions/`, `ide/`, `statsig/`) are deliberately never shared.
- * History (`projects/`, `history.jsonl`, `plans/`) is a POSIX-only opt-in.
+ * Conversations (`projects/`, `plans/`) are a POSIX-only opt-in (`--history`).
  * (`plans/` defaults to `<CLAUDE_CONFIG_DIR>/plans/` in Claude Code, so plan-mode
  * files are otherwise isolated per profile — verified against claude-code 2.1.215.)
  *
@@ -34,18 +40,21 @@ const BASE_ITEMS = [
     { name: "commands", kind: "dir" },
     { name: "agents", kind: "dir" },
 ];
-/** Conversation history + plan-mode files; opt-in — shares `claude --resume`
+/** Append-only logs shared by every `share on`, but never part of a config
+ *  export (`SHARED_ITEMS` is that export's allowlist). */
+const LOG_ITEMS = [{ name: "history.jsonl", kind: "log" }];
+/** Conversations + plan-mode files; opt-in — shares `claude --resume`
  *  and the plan store across accounts. `plans/` is a `dir`, so writes inside it
  *  reach the source (no atomic-rename fork), exactly like `projects/`. */
 const HISTORY_ITEMS = [
     { name: "projects", kind: "dir" },
-    { name: "history.jsonl", kind: "file" },
     { name: "plans", kind: "dir" },
 ];
 /** Names exported for messaging/tests. */
 export const SHARED_ITEMS = BASE_ITEMS.map((i) => i.name);
-export const HISTORY_ITEM_NAMES = HISTORY_ITEMS.map((i) => i.name);
-const ITEM_KIND = new Map([...BASE_ITEMS, ...HISTORY_ITEMS].map((i) => [i.name, i.kind]));
+export const PROMPT_HISTORY = LOG_ITEMS[0].name;
+export const HISTORY_ITEM_NAMES = [...HISTORY_ITEMS, ...LOG_ITEMS].map((i) => i.name);
+const ITEM_KIND = new Map([...BASE_ITEMS, ...LOG_ITEMS, ...HISTORY_ITEMS].map((i) => [i.name, i.kind]));
 const MANIFEST = ".agent-switch-shared.json";
 function readManifest(dir) {
     try {
@@ -72,6 +81,59 @@ function link(src, dst, kind) {
         fs.symlinkSync(src, dst, process.platform === "win32" ? "file" : undefined);
     }
 }
+const stampOf = (l) => {
+    try {
+        const t = JSON.parse(l)?.timestamp;
+        return typeof t === "number" && Number.isFinite(t) ? t : null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Merge the lines of `extra` into the prompt history at `src`: de-duplicated by
+ * exact line, ordered by timestamp (Claude Code reads the file newest-last, so
+ * ↑ walks back in time). Unparseable lines keep their place after their
+ * predecessor. Written via temp + rename; re-read when the source grew while we
+ * merged, so a concurrent append is not lost. Returns the lines added.
+ */
+export function mergePromptHistory(src, extra) {
+    const linesOf = (f) => fs.existsSync(f) ? fs.readFileSync(f, "utf8").split("\n").filter((l) => l.trim() !== "") : [];
+    const incoming = linesOf(extra);
+    for (let attempt = 0;; attempt++) {
+        const before = fs.existsSync(src) ? fs.statSync(src).size : -1;
+        const own = linesOf(src);
+        const seen = new Set(own);
+        const added = incoming.filter((l) => !seen.has(l) && (seen.add(l), true));
+        if (added.length === 0)
+            return 0;
+        let last = 0;
+        const keyed = [...own, ...added].map((l, i) => {
+            last = stampOf(l) ?? last;
+            return { l, i, t: last };
+        });
+        keyed.sort((a, b) => a.t - b.t || a.i - b.i);
+        const tmp = `${src}.agent-switch-merge`;
+        fs.writeFileSync(tmp, keyed.map((k) => k.l).join("\n") + "\n", { mode: 0o600 });
+        const after = fs.existsSync(src) ? fs.statSync(src).size : -1;
+        if (after !== before && attempt < 3) {
+            fs.unlinkSync(tmp);
+            continue;
+        }
+        fs.renameSync(tmp, src);
+        return added.length;
+    }
+}
+/** Merge a profile's own prompt history into the shared one, keep the original
+ *  as a backup next to it, and leave the slot free for the link. */
+function adoptLog(src, dst, name) {
+    const n = mergePromptHistory(src, dst);
+    let backup = `${dst}.pre-share`;
+    if (fs.existsSync(backup))
+        backup = `${backup}-${Date.now()}`;
+    fs.renameSync(dst, backup);
+    return `merged ${n} prompt(s) from ${name} (original kept as ${path.basename(backup)})`;
+}
 /** True when the existing symlink already points at src (junction paths on
  *  win32 may carry a trailing separator / `\\?\` prefix, so compare loosely). */
 function pointsAt(dst, src) {
@@ -108,14 +170,12 @@ export function settingsSharingRisk(settingsPath) {
 /** Link items from sourceDir into targetDir. Returns human-readable actions. */
 export function applySharing(sourceDir, targetDir, withHistory) {
     const actions = [];
-    const items = withHistory ? [...BASE_ITEMS, ...HISTORY_ITEMS] : [...BASE_ITEMS];
+    const items = withHistory ? [...BASE_ITEMS, ...LOG_ITEMS, ...HISTORY_ITEMS] : [...BASE_ITEMS, ...LOG_ITEMS];
     const managed = new Set(readManifest(targetDir));
     fs.mkdirSync(targetDir, { recursive: true, mode: 0o700 });
     for (const item of items) {
         const src = path.join(sourceDir, item.name);
         const dst = path.join(targetDir, item.name);
-        if (!fs.existsSync(src))
-            continue;
         let st = null;
         try {
             st = fs.lstatSync(dst);
@@ -123,6 +183,12 @@ export function applySharing(sourceDir, targetDir, withHistory) {
         catch {
             /* absent */
         }
+        // The shared prompt history starts empty when the source never had one.
+        if (item.kind === "log" && !fs.existsSync(src) && process.platform !== "win32") {
+            fs.writeFileSync(src, "", { mode: 0o600 });
+        }
+        if (!fs.existsSync(src))
+            continue;
         if (st?.isSymbolicLink()) {
             if (pointsAt(dst, src)) {
                 managed.add(item.name);
@@ -136,14 +202,19 @@ export function applySharing(sourceDir, targetDir, withHistory) {
         }
         else if (st) {
             // A regular file/dir sits where a link would go.
-            if (item.kind === "file" && managed.has(item.name)) {
+            if (item.kind === "log" && st.isFile() && process.platform !== "win32") {
+                actions.push(adoptLog(src, dst, item.name));
+            }
+            else if (item.kind === "file" && managed.has(item.name)) {
                 // We linked it before; it's now a regular file → an in-profile write
                 // forked it. Don't clobber — `share sync` reconciles it.
                 actions.push(`forked ${item.name}: run 'agent-switch share sync' to re-link`);
                 continue;
             }
-            actions.push(`skipped ${item.name}: profile has its own copy (remove it to share)`);
-            continue;
+            else {
+                actions.push(`skipped ${item.name}: profile has its own copy (remove it to share)`);
+                continue;
+            }
         }
         if (item.name === "settings.json") {
             const risk = settingsSharingRisk(src);
@@ -158,7 +229,7 @@ export function applySharing(sourceDir, targetDir, withHistory) {
             actions.push(`linked ${item.name}`);
         }
         catch (err) {
-            if (process.platform === "win32" && item.kind === "file") {
+            if (process.platform === "win32" && item.kind !== "dir") {
                 actions.push(`skipped ${item.name}: Windows file symlinks need Developer Mode or admin ` +
                     `(directories are shared via junction regardless)`);
             }
@@ -199,7 +270,11 @@ export function syncSharing(sourceDir, targetDir) {
         }
         if (st.isSymbolicLink())
             continue; // intact
-        if (st.isFile()) {
+        if (st.isFile() && kind === "log") {
+            actions.push(`${adoptLog(src, dst, name)}, re-linked`);
+            link(src, dst, kind);
+        }
+        else if (st.isFile()) {
             // Forked file: propagate the profile's edit to the source, then re-link.
             if (name === "settings.json") {
                 const risk = settingsSharingRisk(dst);
@@ -244,7 +319,11 @@ export function removeSharing(targetDir) {
             // A symlink (POSIX) or a junction (win32, reported as a symlink by
             // lstat) is ours to remove; a forked regular file is the user's, leave it.
             if (st.isSymbolicLink()) {
+                const shared = ITEM_KIND.get(name) === "log" && fs.existsSync(dst) ? fs.realpathSync(dst) : null;
                 fs.unlinkSync(dst);
+                // Unsharing must not empty a profile's prompt history: it keeps a copy.
+                if (shared)
+                    fs.copyFileSync(shared, dst);
                 actions.push(`unlinked ${name}`);
             }
         }

package/dist/shellenv.js

@@ -34,6 +34,8 @@
  * A side effect worth having: a genuinely broken agent-switch now surfaces its
  * error instead of silently degrading the shell onto the default config dir.
  */
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { allProviders } from "./providers.js";
 import { GUARD_REFUSED_EXIT } from "./single-load.js";
 export const SHELLS = ["zsh", "bash", "fish", "powershell"];
@@ -59,11 +61,56 @@ export function detectShell(requested, env = process.env, platform = process.pla
         return "zsh";
     return "zsh"; // sensible POSIX default when $SHELL is unset
 }
+// The CLI the running app activated (`agent-switch activate` writes its path to
+// <home>/active-cli), so a dev build and an installed app each bring their own;
+// a missing or vanished path falls back to agent-switch on PATH.
+const POSIX_BIN = `__agent_switch_bin() {
+  local p
+  p="$(cat "\${AGENT_SWITCH_HOME:-$HOME/.agent-switch}/active-cli" 2>/dev/null)"
+  if [ -n "$p" ] && [ -x "$p" ]; then printf '%s\\n' "$p"
+  elif command -v agent-switch >/dev/null 2>&1; then printf 'agent-switch\\n'
+  fi
+}
+__agent_switch() {
+  local as
+  as="$(__agent_switch_bin)"
+  command "\${as:-agent-switch}" "$@"
+}`;
+const FISH_BIN = `function __agent_switch_bin
+    set -l home $HOME/.agent-switch
+    set -q AGENT_SWITCH_HOME; and set home $AGENT_SWITCH_HOME
+    if test -r $home/active-cli
+        set -l p (cat $home/active-cli)
+        if test -x "$p"
+            echo $p
+            return
+        end
+    end
+    type -q agent-switch; and echo agent-switch
+end
+function __agent_switch
+    set -l as (__agent_switch_bin)
+    test -n "$as"; or set as agent-switch
+    command $as $argv
+end`;
+const POWERSHELL_BIN = `function __agent_switch_bin {
+    $home_ = if ($env:AGENT_SWITCH_HOME) { $env:AGENT_SWITCH_HOME } else { Join-Path $HOME '.agent-switch' }
+    $p = Get-Content -Path (Join-Path $home_ 'active-cli') -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($p -and (Test-Path $p)) { return $p }
+    if (Get-Command agent-switch -ErrorAction SilentlyContinue) { return 'agent-switch' }
+    return $null
+}
+function __agent_switch {
+    $as = __agent_switch_bin
+    if (-not $as) { $as = 'agent-switch' }
+    if ($as -like '*.js') { & node $as @args } else { & $as @args }
+}`;
 function posixWrapper(binary, envVar, id) {
     return `${binary}() {
-  local dir rc
-  command -v agent-switch >/dev/null 2>&1 || { command ${binary} "$@"; return; }
-  dir="$(command agent-switch dir --provider ${id} --guard)"
+  local dir rc as
+  as="$(__agent_switch_bin)"
+  [ -n "$as" ] || { command ${binary} "$@"; return; }
+  dir="$(command "$as" dir --provider ${id} --guard)"
   rc=$?
   if [ $rc -eq ${GUARD_REFUSED_EXIT} ]; then return $rc; fi
   if [ -n "$dir" ]; then
@@ -75,11 +122,12 @@ function posixWrapper(binary, envVar, id) {
 }
 function fishWrapper(binary, envVar, id) {
     return `function ${binary}
-    if not type -q agent-switch
+    set -l as (__agent_switch_bin)
+    if test -z "$as"
         command ${binary} $argv
         return
     end
-    set -l dir (command agent-switch dir --provider ${id} --guard)
+    set -l dir (command $as dir --provider ${id} --guard)
     set -l rc $status
     if test $rc -eq ${GUARD_REFUSED_EXIT}
         return $rc
@@ -95,8 +143,9 @@ function powershellWrapper(binary, envVar, id) {
     return `function ${binary} {
     $exe = Get-Command ${binary} -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
     if (-not $exe) { Write-Error '${binary} not found on PATH.'; return }
-    if (-not (Get-Command agent-switch -ErrorAction SilentlyContinue)) { & $exe.Source @args; return }
-    $dir = (& agent-switch dir --provider ${id} --guard)
+    $as = __agent_switch_bin
+    if (-not $as) { & $exe.Source @args; return }
+    $dir = (__agent_switch dir --provider ${id} --guard)
     if ($LASTEXITCODE -eq ${GUARD_REFUSED_EXIT}) { return }
     if ($dir) {
         $prev = Get-Item -Path Env:\\${envVar} -ErrorAction SilentlyContinue
@@ -107,8 +156,8 @@ function powershellWrapper(binary, envVar, id) {
     }
 }`;
 }
-function build(header, wrappers, asw) {
-    return [header, ...wrappers, asw].join("\n");
+function build(header, bin, wrappers, asw) {
+    return [header, bin, ...wrappers, asw].join("\n");
 }
 export function shellenvScript(shell) {
     const providers = allProviders();
@@ -117,34 +166,64 @@ export function shellenvScript(shell) {
         const asw = `# Convenience: "asw" lists all; "asw work" switches claude; "asw codex work" switches a provider
 function asw
     if test (count $argv) -eq 0
-        command agent-switch list
+        __agent_switch list
     else if contains -- $argv[1] claude codex antigravity
-        command agent-switch use $argv[2] --provider $argv[1]
+        __agent_switch use $argv[2] --provider $argv[1]
     else
-        command agent-switch use $argv
+        __agent_switch use $argv
     end
 end`;
-        return build(header, providers.map((p) => fishWrapper(p.binary, p.envVar, p.id)), asw);
+        return build(header, FISH_BIN, providers.map((p) => fishWrapper(p.binary, p.envVar, p.id)), asw);
     }
     if (shell === "powershell") {
         const header = `# agent-switch shell integration — add to $PROFILE:  agent-switch shellenv --shell powershell | Out-String | Invoke-Expression`;
         const asw = `# Convenience: "asw" lists all; "asw work" switches claude; "asw codex work" switches a provider
 function asw {
-    if ($args.Count -eq 0) { command agent-switch list; return }
-    if (@('claude','codex','antigravity') -contains $args[0]) { & agent-switch use $args[1] --provider $args[0] }
-    else { & agent-switch use @args }
+    if ($args.Count -eq 0) { __agent_switch list; return }
+    if (@('claude','codex','antigravity') -contains $args[0]) { __agent_switch use $args[1] --provider $args[0] }
+    else { __agent_switch use @args }
 }`;
-        return build(header, providers.map((p) => powershellWrapper(p.binary, p.envVar, p.id)), asw);
+        return build(header, POWERSHELL_BIN, providers.map((p) => powershellWrapper(p.binary, p.envVar, p.id)), asw);
     }
     // zsh + bash share the POSIX snippet.
     const header = `# agent-switch shell integration — add to your rc file:  eval "$(agent-switch shellenv)"`;
     const asw = `# Convenience: "asw" lists all; "asw work" switches claude; "asw codex work" switches a provider
 asw() {
-  if [ $# -eq 0 ]; then command agent-switch list; return; fi
+  if [ $# -eq 0 ]; then __agent_switch list; return; fi
   case "$1" in
-    claude|codex|antigravity) command agent-switch use "$2" --provider "$1" ;;
-    *) command agent-switch use "$@" ;;
+    claude|codex|antigravity) __agent_switch use "$2" --provider "$1" ;;
+    *) __agent_switch use "$@" ;;
   esac
 }`;
-    return build(header, providers.map((p) => posixWrapper(p.binary, p.envVar, p.id)), asw);
+    return build(header, POSIX_BIN, providers.map((p) => posixWrapper(p.binary, p.envVar, p.id)), asw);
+}
+/** The line that loads the integration, per shell (same as the docs table). */
+export const SHELLENV_LINE = {
+    zsh: 'eval "$(agent-switch shellenv)"',
+    bash: 'eval "$(agent-switch shellenv)"',
+    fish: "agent-switch shellenv --shell fish | source",
+    powershell: "agent-switch shellenv --shell powershell | Out-String | Invoke-Expression",
+};
+/** The startup file `shellenv install` writes to. macOS opens login shells,
+ *  which read ~/.bash_profile rather than ~/.bashrc. */
+export function rcFileFor(shell, home, platform = process.platform) {
+    if (shell === "zsh")
+        return path.join(home, ".zshrc");
+    if (shell === "bash")
+        return path.join(home, platform === "darwin" ? ".bash_profile" : ".bashrc");
+    if (shell === "fish")
+        return path.join(home, ".config", "fish", "config.fish");
+    return path.join(home, "Documents", "PowerShell", "Microsoft.PowerShell_profile.ps1");
+}
+/** Append the loader line to the shell's startup file, once. `present` says
+ *  whether any known startup file already loads it (the doctor check). */
+export function installShellIntegration(shell, home, present) {
+    const file = rcFileFor(shell, home);
+    if (present)
+        return { shell, file, alreadyInstalled: true };
+    const before = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    const sep = before === "" || before.endsWith("\n") ? "" : "\n";
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${before}${sep}\n# agent-switch shell integration\n${SHELLENV_LINE[shell]}\n`);
+    return { shell, file, alreadyInstalled: false };
 }

package/dist/single-load.js

@@ -25,7 +25,12 @@ import * as path from "node:path";
 import { liveSessionPids } from "./api.js";
 import { pidCwd } from "./sessions.js";
 export const GUARD_POLICIES = ["block", "warn", "off"];
+/** What a state file without a `guard` key meant before 2.2 — kept so an
+ *  upgrade never changes a user's effective guard. */
 export const DEFAULT_GUARD_POLICY = "block";
+/** A fresh install (no state file and no profile yet) starts on `warn`: a second load is
+ *  reported, never refused, so nothing changes how a tool starts. */
+export const FRESH_INSTALL_GUARD_POLICY = "warn";
 export function isGuardPolicy(v) {
     return typeof v === "string" && GUARD_POLICIES.includes(v);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@event4u/agent-switch",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Switch between multiple Claude Code accounts on macOS, Linux, and Windows via isolated CLAUDE_CONFIG_DIR profiles",
   "repository": {
     "type": "git",