@alphacoder-v0/pi-loops 0.22.1 → 0.22.2

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to pi-loops are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.22.2] - 2026-09-16
+
+### Changed
+- **The extension puts `pi-loops` on your PATH, instead of you typing a node path out of the
+  README.** `pi install` leaves this package under pi's directory and nothing on your `PATH`, so
+  `pi-loops` only existed after `install-launcher` had been run once — and the first time there was
+  no `pi-loops` to run it with, which is why the install instructions ended in a bare `node
+  ~/.pi/agent/npm/node_modules/@alphacoder-v0/pi-loops/src/cli-entry.mjs install-launcher`. The
+  launcher that wrote then went stale by itself when pi reinstalled the package by the other route
+  (0.22.1). pi loads this extension at every session start and knows, at that moment, both where it
+  runs and where a launcher would go: so the first session that finds none anywhere on your `PATH`
+  asks once — the same question `/pi-loops install-launcher` asks — and a no is remembered in
+  `ui.json` and never asked again. A launcher of ours is rewritten at the next start in two cases
+  and only two — the copy it names is not on disk any more, or the copy it names is this one and the
+  node or the shape of the script changed — with one line saying that it was and why; one naming
+  another copy that is still there belongs to that copy, so an install and a checkout on the same
+  machine never trade the file back and forth. Nothing else is touched: a `pi-loops` this project
+  did not write is left alone, a checkout is never asked for a launcher that is not there (one
+  written from a checkout is still kept current), and `/pi-loops install-launcher` still writes one
+  whenever you want it, clearing the remembered no. The script itself now also lists the copy it
+  runs once rather than twice, which is what an installed copy — where the entry it records is one
+  of pi's own two locations — used to get.
+
 ## [0.22.1] - 2026-09-16
 
 ### Fixed

package/README.md

@@ -38,7 +38,7 @@ the first sign of credentials that do not work should not be an empty inbox tomo
 
 ```bash
 pi install npm:@alphacoder-v0/pi-loops                      # from npm, following new releases
-pi install git:github.com/alphacoder-v0/pi-loops@v0.22.1    # or from GitHub, at a pinned tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.22.2    # or from GitHub, at a pinned tag
 pi install /path/to/pi-loops                                # or a local checkout — `pi install .` in this repo
 pi -e /path/to/pi-loops                                     # or none of them: try it for one run, installing nothing
 ```
@@ -184,22 +184,24 @@ you are at the machine, and hands it back the next time you open pi (`/cron host
 ## The browser window, and the command line
 
 `pi-loops` is the part that needs a launcher: `pi install` puts the package under pi's managed
-directory rather than on your `PATH`, so the command does not exist yet — the one thing
-`install-launcher` cannot do for itself. Either way round works:
+directory rather than on your `PATH`, so the command does not exist yet. You are not asked to fix
+that by hand — the first pi session after `pi install` offers to put `pi-loops` on your `PATH`, and
+keeps that launcher working afterwards if pi ever moves the package. Say no and nothing is written,
+and you are not asked again; `/pi-loops install-launcher` writes one whenever you change your mind:
 
 ```text
 /pi-loops install-launcher            # from inside pi, where the extension is already loaded
 ```
 
 ```bash
-# or from a shell, in the directory pi installed the package into
+# or from a shell, on a machine where pi is never opened — the same command, by absolute path
 cd ~/.pi/agent/npm/node_modules/@alphacoder-v0/pi-loops    # installed from npm
 cd ~/.pi/agent/git/github.com/alphacoder-v0/pi-loops       # installed from GitHub
 node src/cli-entry.mjs install-launcher
 ```
 
-Either writes a launcher into the first of `~/.local/bin` and `/usr/local/bin` that is already on
-your `PATH`, and refuses rather than guessing if neither is — pass `--dir <dir>` to say where.
+Any of them writes a launcher into the first of `~/.local/bin` and `/usr/local/bin` that is already
+on your `PATH`, and refuses rather than guessing if neither is — pass `--dir <dir>` to say where.
 After that, `pi-loops` works from anywhere:
 
 ```bash

package/README.zh-CN.md

@@ -45,28 +45,28 @@ pi-loops 自己没有任何运行时依赖。
 
 ```bash
 pi install npm:@alphacoder-v0/pi-loops                      # 从 npm 装，跟着新版本走
-pi install git:github.com/alphacoder-v0/pi-loops@v0.22.1    # 或者从 GitHub 装，钉住一个 tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.22.2    # 或者从 GitHub 装，钉住一个 tag
 pi install /path/to/pi-loops                                # 或者本地检出；本仓库里就是 pi install .
 ```
 
 **几种装法挑一种，不要装两份。** 两份副本注册同名工具，pi 会拒绝加载第二份并直接退出（`Tool "cron_create" conflicts with …`）。如果你在改这份代码，留本地检出那份。
 
-重启 pi，装到这里就够了——那四个斜杠命令现在就能用。下面这步只跟 `pi-loops` 这个命令有关：浏览器窗口和几个 shell 子命令靠它，不要浏览器窗口可以先跳过。
+重启 pi，装到这里就够了——那四个斜杠命令现在就能用。下面这段只跟 `pi-loops` 这个命令有关：浏览器窗口和几个 shell 子命令靠它，不要浏览器窗口可以先跳过。
 
-`pi install` 把包放在 pi 自己的托管目录里、**不进 `PATH`**，所以此刻 `pi-loops` 这个命令还不存在——这恰好是 `install-launcher` 唯一没法替自己做的事。两条路随便走一条：
+`pi install` 把包放在 pi 自己的托管目录里、**不进 `PATH`**，所以此刻 `pi-loops` 这个命令还不存在。这一步不用你自己动手：`pi install` 之后的第一个 pi 会话会问你要不要把 `pi-loops` 放进 `PATH`，写下之后也一直替你维护着——包被 pi 挪到另一个位置，下一个会话会把启动器改回能用的样子，并用一行告诉你改了什么。答 no 就什么都不写，也不会再问第二次；改了主意，`/pi-loops install-launcher` 随时给你写一个：
 
 ```text
 /pi-loops install-launcher                         # 在 pi 里面，扩展本来就加载着
 ```
 
 ```bash
-# 或者在 shell 里，进到 pi 装包的那个目录
+# 或者在 shell 里用绝对路径跑同一个命令——给那种根本不开 pi 的机器留的路
 cd ~/.pi/agent/npm/node_modules/@alphacoder-v0/pi-loops    # 从 npm 装的
 cd ~/.pi/agent/git/github.com/alphacoder-v0/pi-loops       # 从 GitHub 装的
 node src/cli-entry.mjs install-launcher
 ```
 
-两条都会往 `~/.local/bin`（或其它已在 `PATH` 里的目录，用 `--dir` 指定）写一个启动器。之后 `pi-loops` 在任何目录都能用。
+几条路都会往 `~/.local/bin`（或其它已在 `PATH` 里的目录，用 `--dir` 指定）写一个启动器。之后 `pi-loops` 在任何目录都能用。
 
 ### 3. 开一个会话
 

package/docs/cli.md

@@ -153,16 +153,25 @@ by the id in its header.
 ## Getting the command onto your PATH
 
 `pi install` puts this package under pi's managed directory rather than on your `PATH`, so the
-command that is meant to start your sessions is at first reachable only by absolute path — and
-putting itself there is the one thing it cannot do for itself. Run it from inside pi, where the
-extension is already loaded:
+command that is meant to start your sessions is at first reachable only by absolute path. The
+extension does that step for you: the first pi session that finds no `pi-loops` anywhere on your
+`PATH` asks once whether to write one, and a no is remembered — nothing is written and you are not
+asked again. Afterwards it keeps that launcher current: if the copy it runs is not there any more
+(pi installed the package by the other route), or that copy is the one now running and the node has
+changed, the next session rewrites it and says so in one line. A `pi-loops` this project did not
+write — your own wrapper — is left alone, and so is one that runs another copy of this package still
+on disk, which is that copy's to keep. A checkout is never asked to write a launcher that is not
+there, though one written from a checkout is still kept working.
+
+To write one yourself, or after a no, run it from inside pi, where the extension is already loaded:
 
 ```text
 /pi-loops install-launcher
 ```
 
 or from the directory pi installed the package into — `~/.pi/agent/npm/node_modules/@alphacoder-v0/pi-loops`
-for a `pi install npm:` package, `~/.pi/agent/git/<host>/<owner>/<repo>` for a `pi install git:` one:
+for a `pi install npm:` package, `~/.pi/agent/git/<host>/<owner>/<repo>` for a `pi install git:` one,
+which is the way in on a machine where pi itself is never opened:
 
 ```bash
 node src/cli-entry.mjs install-launcher

package/docs/design.md

@@ -174,6 +174,31 @@ machine. Everything here follows from that, and each one has a price.
     The cost: two machines syncing one `$HOME` both run every job. That is not supported, and it
     is said rather than half-handled.
 
+20. **The extension keeps the launcher.** `pi install` puts this package under pi's directory and
+    nothing on your PATH, so `pi-loops` existed only after someone ran `install-launcher` once — and
+    the first time there was no `pi-loops` to run it with, which is why the README handed people a
+    bare `node ~/.pi/agent/npm/node_modules/@alphacoder-v0/pi-loops/src/cli-entry.mjs
+    install-launcher`. The launcher then went stale by itself: a package reinstalled by the other
+    route moved, and every `pi-loops` after that ended in Node's `Cannot find module` (0.22.1). Both
+    endings were a path a person had to type out. pi loads this extension at every session start,
+    and at that moment it knows where it runs and where a launcher would go — so `session_start`
+    does it. A launcher of ours is rewritten in two cases and only two: the copy it names is not on
+    disk any more (the package moved, which is the reading that ends in `Cannot find module`), or
+    the copy it names is this one and the node or the shape of the script has changed. Either way
+    one line says that it was rewritten and why. One naming another copy that is still there is that
+    copy's to keep current, so an install and a checkout both being opened never trade the file back
+    and forth. With no launcher anywhere, the question `install-launcher` already asks is asked once,
+    and a no is remembered in `ui.json` and never asked again; `/pi-loops install-launcher` still
+    writes one whenever you want it, and clears that mark. A `pi-loops` carrying no marker of ours
+    is somebody's own wrapper and is left alone, and a checkout is never asked for one that is not
+    there — nobody ran `pi install`. The decision is `launcherState` / `refreshLauncher` in
+    [../src/cli.ts](../src/cli.ts), beside the one function that renders the script, so it is
+    testable without pi; the extension is the caller.
+
+    The cost: a write outside the loops directory, which the Non-invasive invariant now names as its
+    one exception, and a question on somebody's first start — an interruption this project otherwise
+    does not make.
+
 ## Where the browser front end came from
 
 pi owns the `pi` command and its terminal, so a second front end cannot replace the first one. It

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphacoder-v0/pi-loops",
-  "version": "0.22.1",
+  "version": "0.22.2",
   "description": "An automation layer for pi: cron + stateful loops with a triage inbox, maker/checker verification, dynamic triggers, MCP notifications and tools, lifecycle hooks, session archives. A non-invasive pi extension.",
   "type": "module",
   "license": "MIT",

package/src/cli.ts

@@ -21,7 +21,7 @@ import { FINDING_FIELDS, Inbox, type InboxEntry, inProject, resolveInboxRef } fr
 import { sameProject } from "./presence.ts";
 import { redact } from "./redact.ts";
 import { liveHost, stopHost } from "./host-control.ts";
-import { type UiPrefs, readUiPrefs } from "./ui-prefs.ts";
+import { type UiPrefs, clearUiPref, readUiPrefs } from "./ui-prefs.ts";
 import { JobStore, defaultLoopsDir } from "./store.ts";
 import { automationBadge, previewText, readSessionHead } from "./session-head.ts";
 import { AUTONOMY_LEVELS, type AutonomyLevel, INSTALL_ROOT, TRACKER_FILE, addLineFor, ensureExcluded, installDirFor, installFiles, installedRecipes, listRecipes, loadRecipe, planInstall, playbookFiles, readRecord, resolveRecipeRef } from "./recipe.ts";
@@ -828,18 +828,48 @@ export async function installLauncher(dir: string | undefined, out: (line: strin
 		return 1;
 	}
 	if (dir && !isOnPath(target)) out(`note: ${target} is not on your PATH, so the command will not be found there yet`);
-	const entry = path.join(path.dirname(fileURLToPath(import.meta.url)), "cli-entry.mjs");
+	const { entryDir, node, agentDir } = launcherSource();
 	const file = path.join(target, "pi-loops");
-	// A launcher rather than a symlink: it names the node that is running now, which is the one known
-	// to be new enough for this code. What it survives is this package being installed again by the
-	// other route — `pi install npm:` over a `git:` copy moves it, and a launcher that knew only where
-	// it used to be died in Node's `Cannot find module`. So the entry it recorded is the first place
-	// it looks and not the only one, and the recorded node is a path it checks rather than trusts.
-	const candidates = [entry, ...piInstallEntries(getAgentDir())].map((e) => JSON.stringify(e)).join(" ");
-	const script = [
+	try {
+		fs.mkdirSync(target, { recursive: true });
+		fs.writeFileSync(file, launcherScript(entryDir, node, agentDir), { mode: 0o755 });
+		fs.chmodSync(file, 0o755);
+	} catch (err: any) {
+		out(`could not write ${file}: ${err?.message ?? err}`);
+		return 1;
+	}
+	// Whatever a session start was told once, this is the answer now: a launcher exists because
+	// someone asked for it, so the offer is live again if the file ever goes.
+	clearUiPref(defaultLoopsDir(getAgentDir()), "launcher");
+	out(`wrote ${file}`);
+	out(`  it runs ${path.join(entryDir, "cli-entry.mjs")}`);
+	out("  `pi-loops` now starts a session; `pi-loops --tui` opens the terminal one instead");
+	return 0;
+}
+
+/** The marker line that says a `pi-loops` on someone's PATH is one this project wrote. */
+const LAUNCHER_MARKER = "# pi-loops launcher, written by";
+
+/**
+ * The launcher, as text. The one place the script is spelled: `installLauncher` writes this, and a
+ * session start compares what is on disk against it, so the two cannot drift into scripts that
+ * differ by a tab and call each other stale for ever.
+ *
+ * A launcher rather than a symlink: it names the node that is running now, which is the one known
+ * to be new enough for this code. What it survives is this package being installed again by the
+ * other route — `pi install npm:` over a `git:` copy moves it, and a launcher that knew only where
+ * it used to be died in Node's `Cannot find module`. So the entry it recorded is the first place it
+ * looks and not the only one, and the recorded node is a path it checks rather than trusts. On a
+ * copy pi installed, that recorded entry *is* one of the two it falls back to, so the duplicate is
+ * dropped rather than printed twice in a file people read.
+ */
+export function launcherScript(entryDir: string, node: string, agentDir: string): string {
+	const entry = path.join(entryDir, "cli-entry.mjs");
+	const candidates = [entry, ...piInstallEntries(agentDir).filter((e) => e !== entry)].map((e) => JSON.stringify(e)).join(" ");
+	return [
 		"#!/bin/sh",
-		"# pi-loops launcher, written by `pi-loops install-launcher`.",
-		`node=${JSON.stringify(process.execPath)}`,
+		`${LAUNCHER_MARKER} \`pi-loops install-launcher\`.`,
+		`node=${JSON.stringify(node)}`,
 		'[ -x "$node" ] || node=$(command -v node) || node=node',
 		`for entry in ${candidates}; do`,
 		'\t[ -f "$entry" ] || continue',
@@ -849,18 +879,108 @@ export async function installLauncher(dir: string | undefined, out: (line: strin
 		"exit 1",
 		"",
 	].join("\n");
+}
+
+/** What a launcher for *this* copy is written from, so a caller needs to know none of the three. */
+export function launcherSource(): { entryDir: string; node: string; agentDir: string } {
+	return { entryDir: path.dirname(fileURLToPath(import.meta.url)), node: process.execPath, agentDir: getAgentDir() };
+}
+
+/**
+ * Whether pi installed this copy, by either route. The same two locations `upgradeSpec` reads — it
+ * is asked through it so the two can never disagree — and the tag is a placeholder, only the
+ * yes-or-no is used. A checkout is not an install: nobody ran `pi install`, so nobody is waiting
+ * for a command that was never put on their PATH.
+ */
+export function installedByPi(): boolean {
+	return upgradeSpec(packageRoot(), manifest().name ?? "", getAgentDir(), "v0.0.0") !== undefined;
+}
+
+export type LauncherState = "absent" | "current" | "stale" | "other" | "foreign";
+
+/**
+ * What is at `<target>/pi-loops`, as far as this copy is concerned: nothing at all (`absent`), a
+ * launcher this project wrote that matches this node and this copy (`current`), one of ours that
+ * this copy should rewrite (`stale`), one of ours that belongs to another copy still on disk
+ * (`other`), or a file carrying no marker of ours — someone's own wrapper, which is not ours to
+ * rewrite either (`foreign`).
+ *
+ * It takes the three things a launcher is written from rather than reading them, so the decision is
+ * a function of its arguments and the session-start caller is a few lines.
+ */
+export function launcherState(entryDir: string, node: string, agentDir: string, target: string): { file: string; state: LauncherState } {
+	const file = path.join(target, "pi-loops");
+	const found = readLauncher(file);
+	if (found === undefined) return { file, state: "absent" };
+	if (!found.includes(LAUNCHER_MARKER)) return { file, state: "foreign" };
+	if (found === launcherScript(entryDir, node, agentDir)) return { file, state: "current" };
+	return { file, state: oursToRewrite(found, entryDir) ? "stale" : "other" };
+}
+
+/**
+ * Whether a launcher of ours that no longer matches is this copy's to rewrite. Two cases, and only
+ * these two: the entry it recorded is gone — the package moved, which is the reading that ends in
+ * `Cannot find module` — or that entry is this copy's own, so the node or the shape of the script
+ * changed under it. A launcher recording another copy that is still there belongs to that copy: an
+ * install and a checkout both get opened, and two live copies each rewriting the file to point at
+ * itself would trade it back and forth for ever, with a line about it every time.
+ */
+function oursToRewrite(script: string, entryDir: string): boolean {
+	const recorded = launcherRecords(script).entries[0];
+	// One of ours recording nothing this can read is nobody else's either, so it is ours to fix.
+	if (recorded === undefined) return true;
+	return recorded === path.join(entryDir, "cli-entry.mjs") || !fs.existsSync(recorded);
+}
+
+/** The file, or undefined when there is nothing there to read — which is the same news. */
+function readLauncher(file: string): string | undefined {
 	try {
-		fs.mkdirSync(target, { recursive: true });
-		fs.writeFileSync(file, script, { mode: 0o755 });
+		return fs.readFileSync(file, "utf8");
+	} catch {
+		// Missing, a directory, unreadable: in all three there is no launcher of ours here.
+		return undefined;
+	}
+}
+
+/**
+ * Keep a launcher of ours current, and say what changed. Undefined when there is nothing to do —
+ * no launcher, somebody else's, another copy's, or already this one — so this is safe to call on
+ * every start.
+ *
+ * It writes exactly one file, and only one that is already a launcher of ours: nothing new appears
+ * anywhere from a start nobody answered a question at.
+ */
+export function refreshLauncher(entryDir: string, node: string, agentDir: string, target: string): { message: string; ok: boolean } | undefined {
+	const { file, state } = launcherState(entryDir, node, agentDir, target);
+	if (state !== "stale") return undefined;
+	const why = staleReason(readLauncher(file) ?? "", entryDir, node);
+	try {
+		fs.writeFileSync(file, launcherScript(entryDir, node, agentDir), { mode: 0o755 });
 		fs.chmodSync(file, 0o755);
 	} catch (err: any) {
-		out(`could not write ${file}: ${err?.message ?? err}`);
-		return 1;
+		return { ok: false, message: `could not refresh the \`pi-loops\` launcher at ${file}: ${err?.message ?? err}` };
 	}
-	out(`wrote ${file}`);
-	out(`  it runs ${entry}`);
-	out("  `pi-loops` now starts a session; `pi-loops --tui` opens the terminal one instead");
-	return 0;
+	return { ok: true, message: `refreshed the \`pi-loops\` launcher at ${file}: ${why}` };
+}
+
+/** The node and the entries a launcher records, from this script or from the one 0.22.0 wrote. */
+function launcherRecords(script: string): { node?: string; entries: string[] } {
+	const quoted = (s: string): string[] => (s.match(/"(?:[^"\\]|\\.)*"/g) ?? []).map((q) => JSON.parse(q) as string);
+	const node = /^node=("(?:[^"\\]|\\.)*")$/m.exec(script)?.[1];
+	const list = /^for entry in (.*); do$/m.exec(script)?.[1];
+	if (node !== undefined && list !== undefined) return { node: JSON.parse(node) as string, entries: quoted(list) };
+	// Older launchers are one `exec <node> <entry> "$@"` line and nothing else.
+	const exec = quoted(/^exec (.*)$/m.exec(script)?.[1] ?? "");
+	return { node: exec[0], entries: exec[1] ? [exec[1]] : [] };
+}
+
+/** Why a launcher of ours no longer matches — the half-sentence a person gets told. */
+function staleReason(old: string, entryDir: string, node: string): string {
+	const rec = launcherRecords(old);
+	if (rec.node === undefined && !rec.entries.length) return "this version of pi-loops writes it differently";
+	if (rec.entries[0] !== path.join(entryDir, "cli-entry.mjs")) return "the package moved";
+	if (rec.node !== node) return "the node it runs changed";
+	return "this version of pi-loops writes it differently";
 }
 
 /**

package/src/pi-loops.ts

@@ -33,7 +33,7 @@ import { McpSource, PI_BUILTIN_TOOL_NAMES, type McpServerConfig, type McpToolDef
 import { capRedacted, previewRedacted, redact } from "./redact.ts";
 import { shouldEmitSnapshot, snapshotFingerprint } from "./snapshot.ts";
 import { type ShareMessage, renderShare, shareSummary } from "./share.ts";
-import { installLauncherWithConfirm } from "./cli.ts";
+import { installLauncherWithConfirm, installedByPi, launcherSource, launcherState, launcherTarget, refreshLauncher } from "./cli.ts";
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { computeDue, computeNext, formatLocal, formatSchedule, localOffset, parseSchedule, stamp } from "./schedule.ts";
@@ -2484,6 +2484,52 @@ export default function piLoops(pi: ExtensionAPI) {
 
 	/* -------------------------------------------------------- lifecycle */
 
+	/**
+	 * The `pi-loops` command, kept on the PATH of whoever asked for it there.
+	 *
+	 * `pi install` puts this package under pi's directory and nothing on the PATH, so until 0.22.1
+	 * the first thing a new user had to do was type a bare `node …/cli-entry.mjs install-launcher`
+	 * out of the README — the one step that only existed because the command could not yet run
+	 * itself. pi loads this extension at every session start, and at that moment it knows both where
+	 * it runs and where a launcher would go, so the step belongs here.
+	 *
+	 * This is the extension's only write outside the loops directory (AGENTS.md). Its limit is one
+	 * file, `pi-loops` in a directory already on the PATH, and only where a launcher of ours already
+	 * is or after a yes. A file with no marker of ours is somebody's own wrapper and is left alone;
+	 * one naming another copy of this package that is still on disk is that copy's to keep current,
+	 * so an install and a checkout both being opened never trade the file back and forth; a no is
+	 * remembered in `ui.json`, so it is asked once rather than in every window; and a checkout is
+	 * never asked for a launcher that is not there at all — nobody ran `pi install`, so nothing is
+	 * missing from their PATH — though one written from a checkout is still kept working.
+	 */
+	async function keepLauncher(ctx: ExtensionContext): Promise<void> {
+		const { entryDir, node, agentDir } = launcherSource();
+		const target = launcherTarget(undefined);
+		// Nothing on the PATH to write into. `/pi-loops install-launcher`, run by hand, is where that
+		// is explained; a session start saying it unprompted would be a warning about nothing.
+		if (!target) return;
+		const { state } = launcherState(entryDir, node, agentDir, target);
+		if (state === "stale") {
+			const done = refreshLauncher(entryDir, node, agentDir, target);
+			if (!done) return;
+			log.info(`launcher: ${done.message}`);
+			// No question: they asked for a launcher once, and keeping that one working is what they
+			// asked for. The line is so that a file changing under them is never a silent change.
+			if (ctx.hasUI) ctx.ui.notify(`[pi-loops] ${done.message}`, done.ok ? "info" : "warning");
+			return;
+		}
+		if (state !== "absent") return; // ours and current, another copy's, or somebody else's entirely
+		if (!ctx.hasUI || readUiPrefs(dir).launcher === "declined" || !installedByPi()) return;
+		const lines: string[] = [];
+		const code = await installLauncherWithConfirm([], (title, body) => ctx.ui.confirm(title, body), (l) => lines.push(l));
+		if (code === undefined) {
+			writeUiPref(dir, "launcher", "declined");
+			ctx.ui.notify("[pi-loops] not installed — `/pi-loops install-launcher` writes one whenever you want it", "info");
+			return;
+		}
+		ctx.ui.notify(`[pi-loops] ${lines.map((l) => l.trim()).join(" · ")}`, code === 0 ? "info" : "warning");
+	}
+
 	pi.on("session_start", async (_event, ctx) => {
 		lastCtx = ctx;
 		if (startHandled) return; // the same start, delivered a second time by a second rebind
@@ -2506,6 +2552,9 @@ export default function piLoops(pi: ExtensionAPI) {
 		loadMcpConfig(ctx.isProjectTrusted());
 		for (const d of mcpDiagnostics) if (ctx.hasUI) ctx.ui.notify(`[pi-loops] ${d}`, "warning");
 		await startMcpSources(); // tools for every process; pushes are consumed by interactive processes only
+		// Not awaited: the question below is a dialog, and the clock must not wait behind someone who
+		// has walked away from it.
+		void keepLauncher(ctx).catch((err: any) => log.info(`launcher: ${err?.message ?? err}`));
 		// tui and rpc processes stay alive and host the timer; `PI_LOOPS_HOST=1` lets a `pi -p`
 		// run (a long headless prompt) host it too.
 		const hostMode = ctx.mode === "tui" || ctx.mode === "rpc" || envFlag("LOOPS_HOST");

package/src/ui-prefs.ts

@@ -25,6 +25,11 @@ export interface UiPrefs {
 	/** The model and thinking level last chosen in the browser front end. */
 	model?: string;
 	thinking?: string;
+	/**
+	 * `"declined"` once someone has said no to the launcher a session start offers, so the offer is
+	 * made once and not in every window. `/pi-loops install-launcher` clears it when it writes one.
+	 */
+	launcher?: string;
 }
 
 const fileIn = (dir: string): string => path.join(dir, "ui.json");
@@ -52,6 +57,7 @@ export function readUiPrefs(dir: string): UiPrefs {
 	if (typeof doc.panel === "boolean") prefs.panel = doc.panel;
 	if (typeof doc.model === "string") prefs.model = doc.model;
 	if (typeof doc.thinking === "string") prefs.thinking = doc.thinking;
+	if (typeof doc.launcher === "string") prefs.launcher = doc.launcher;
 	return prefs;
 }
 
@@ -75,6 +81,22 @@ export function writeUiPref<K extends keyof UiPrefs>(dir: string, key: K, value:
 	const doc = readRaw(dir);
 	if (doc[key] === value) return;
 	doc[key] = value;
+	save(dir, doc);
+}
+
+/**
+ * Forget one preference, keeping every other key. A remembered "no" has to be forgettable by the
+ * thing that answers it — a launcher written by hand is the yes the session-start question was
+ * asking for — and removing the key is what "nobody has answered" is spelled as here.
+ */
+export function clearUiPref(dir: string, key: keyof UiPrefs): void {
+	const doc = readRaw(dir);
+	if (!(key in doc)) return;
+	delete doc[key];
+	save(dir, doc);
+}
+
+function save(dir: string, doc: Record<string, unknown>): void {
 	try {
 		writeFileAtomic(fileIn(dir), `${JSON.stringify(doc, null, 2)}\n`);
 	} catch {