pi-cc-loop 0.4.0 → 0.6.0

package/README.md

@@ -37,8 +37,8 @@ ln -sfn "$PWD" ~/.pi/agent/extensions/pi-cc-loop
 | 过期 | 周期任务 7 天后最后执行一次再删除；一次性任务不过期 | 自动 |
 | 次数上限 | `maxFires`，到顶自动删除 | `--max N` |
 | 持久化 | `durable: true` 写入 `.pi/scheduled_tasks.json`，重启后继续；同一项目只由一个 Pi 会话执行 | `--durable` |
-| 底部摘要 | Pi 底部状态栏一行：`loop 2 · next 3m`，无任务时不占位 | `/loop footer on\|off` |
-| 界面设置 | 本地命令，不进对话 | `/loop settings ...` |
+| 底部摘要 | Pi 底部状态栏一行：`loop 2 · next 3m`，无任务时不占位 | `/pi_cc footer on\|off` |
+| 界面设置 | 和 Pi 的 `/settings` 一样的面板，本地命令，不进对话 | `/pi_cc` |
 
 ## 命令
 
@@ -48,12 +48,12 @@ ln -sfn "$PWD" ~/.pi/agent/extensions/pi-cc-loop
 /loop [间隔]              跑 loop.md，没有就跑内置维护 prompt
 /loop status              列出当前任务
 /loop stop [id]           停止一个或全部
-/loop footer on|off       本地：底部摘要
-/loop settings ...        本地：界面设置
 /loop help                本地：帮助
+/pi_cc                    本地：pi-cc 设置面板（见下）
 ```
 
-前五个会作为普通 user 消息进入对话（内容就是你输入的那行），模型再按技能说明调用工具；后三个只改界面，不进对话。
+前五个会作为普通 user 消息进入对话（内容就是你输入的那行），模型再按技能说明调用工具；后两个只改界面，不进对话。
+旧的 `/loop footer`、`/loop settings` 会提示改用 `/pi_cc`，不会当成 loop 请求。
 
 间隔写法没有约束，模型自己解析：`30s`、`5m`、`2h`、`1d`、`check the deploy every 20m`、
 `每2分钟输出一次`、`每分钟打印一次hi` 都可以。小于一分钟会向上取整到每分钟。
@@ -86,16 +86,44 @@ Ctrl+O 展开后多一行元信息（任务 id、节奏）。`compactMessages`
 
 ## 设置
 
-两个 pi-cc 扩展共用 `~/.pi/agent/pi-cc.json`，文件不存在时用默认值：
+三个 pi-cc 扩展共用 Pi 配置目录下的 `pi-cc.json`（默认 `~/.pi/agent/pi-cc.json`，跟随 `PI_CODING_AGENT_DIR`），文件不存在时用默认值：
 
 ```jsonc
 {
   "compactMessages": true,   // 触发块和 Monitor 事件用上面的样式；false 为旧的带底色卡片
-  "footer": true             // 底部摘要：loop 的一行和 Monitor 的 `monitor N`
+  "footer": true,            // 底部摘要：loop 的一行和 Monitor 的 `monitor N`
+  "draft": true,             // pi-cc-plugins：Ctrl+C 找回
+  "turnSummary": true        // pi-cc-plugins：回合摘要一行
 }
 ```
 
-用 `/loop settings messages on|off`、`/loop settings footer on|off`（或 `/loop footer on|off`）切换，两个扩展同时生效。
+后两项只被 pi-cc-plugins 读取；没装它的会话里，面板中的这两项不生效，值原样保留。
+
+在 TUI 里输入 `/pi_cc` 会打开设置面板，样子和操作都和 Pi 的 `/settings` 一样：上下键选择，Enter/空格切换，Esc 关闭；
+改动立即保存，所有 pi-cc 扩展同时生效。Pi 的 `/settings` 不接受扩展加项，所以 pi-cc 的设置放在 `/pi_cc` 下。
+
+`/pi_cc` 由三个 pi-cc 包（loop、monitor、plugins）共同提供：装了其中任意一个，命令就在；装了多个，也只有一个 `/pi_cc`
+（Pi 会把不同扩展的同名命令变成 `/pi_cc:1`、`/pi_cc:2`，所以由最先加载的包认领注册，会话结束时释放，`/reload` 会重新认领）。
+
+```text
+─────────────────────────────────────────────────────────────
+pi-cc settings · ~/.pi/agent/pi-cc.json
+
+→ Message style   compact
+  Footer summary  on
+
+  How scheduled fires and Monitor events are drawn. compact: ✻ header
+  and indented body; card: the old padded card.
+
+  Enter/Space to change · Esc to cancel
+─────────────────────────────────────────────────────────────
+```
+
+也可以用文字命令：`/pi_cc messages on|off`、`/pi_cc footer on|off`，适合脚本和 RPC；
+非 TUI 模式下，不带参数的 `/pi_cc` 输出当前设置。命令只写改动的那一项，文件里的其他内容原样保留。
+
+环境变量 `PI_CC_FOOTER`、`PI_CC_COMPACT_MESSAGES`（pi-cc-plugins 的两项是 `PI_CC_DRAFT`、`PI_CC_TURN_SUMMARY`）优先于文件，但不会被写进文件。设着的时候，面板里这一项显示实际生效的值、不能切换，
+说明里写出是哪个变量；文字输出会在对应项后面标出来（如 `hidden (PI_CC_FOOTER=0)`）；用文字命令切换会写进文件，但提示会说明变量还在覆盖它。
 
 ## 底部摘要
 
@@ -124,7 +152,7 @@ Ctrl+O 展开后多一行元信息（任务 id、节奏）。`compactMessages`
 | `PI_LOOP_DURABLE_SYNC_MS` | `5000` | 持久化任务文件的同步间隔 |
 | `PI_CC_FOOTER` | — | `0` / `1`，覆盖设置文件里的 `footer` |
 | `PI_CC_COMPACT_MESSAGES` | — | `0` / `1`，覆盖设置文件里的 `compactMessages` |
-| `PI_CC_CONFIG_FILE` | `~/.pi/agent/pi-cc.json` | 设置文件路径 |
+| `PI_CC_CONFIG_FILE` | `~/.pi/agent/pi-cc.json` | 设置文件路径；不设时在 Pi 的配置目录里，跟随 `PI_CODING_AGENT_DIR` |
 
 ## 兼容性
 

package/config.ts

@@ -1,24 +1,35 @@
 /**
  * Shared settings for the pi-cc extensions.
  *
- * Both pi-cc-loop and pi-cc-monitor read the same small JSON file so a single
- * toggle changes the look of both packages. The file is optional; when it is
- * missing or malformed the defaults apply.
+ * pi-cc-loop, pi-cc-monitor and pi-cc-plugins read the same small JSON file
+ * so a single toggle changes the whole family at once. The file is optional;
+ * when it is missing or malformed the defaults apply. It sits in Pi's agent
+ * directory (PI_CODING_AGENT_DIR, default ~/.pi/agent), next to Pi's own
+ * settings.
  *
  *   ~/.pi/agent/pi-cc.json
  *   {
  *     "compactMessages": true,
- *     "footer": true
+ *     "footer": true,
+ *     "draft": true,
+ *     "turnSummary": true
  *   }
  *
- * Environment overrides (useful for tests and quick experiments):
+ * compactMessages and footer drive loop and monitor; draft and turnSummary
+ * drive pi-cc-plugins. A package that is not installed simply ignores its
+ * keys, and they are kept as the user left them.
+ *
+ * Environment overrides (useful for tests and quick experiments) win over the
+ * file while they are set, and are never written to it:
  *   PI_CC_CONFIG_FILE=/path/to/pi-cc.json
  *   PI_CC_COMPACT_MESSAGES=0|1
  *   PI_CC_FOOTER=0|1
+ *   PI_CC_DRAFT=0|1
+ *   PI_CC_TURN_SUMMARY=0|1
  */
 
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 
 export interface PiCcConfig {
@@ -29,11 +40,25 @@ export interface PiCcConfig {
 	 * Shared so one switch silences both packages.
 	 */
 	footer: boolean;
+	/** pi-cc-plugins: Ctrl+C keeps what it clears, Up brings it back. */
+	draft: boolean;
+	/** pi-cc-plugins: one line closes every agent run. */
+	turnSummary: boolean;
 }
 
 export const DEFAULT_CONFIG: PiCcConfig = {
 	compactMessages: true,
 	footer: true,
+	draft: true,
+	turnSummary: true,
+};
+
+/** The environment variable that overrides each setting. */
+const ENV_OVERRIDES: Record<keyof PiCcConfig, string> = {
+	compactMessages: "PI_CC_COMPACT_MESSAGES",
+	footer: "PI_CC_FOOTER",
+	draft: "PI_CC_DRAFT",
+	turnSummary: "PI_CC_TURN_SUMMARY",
 };
 
 function envBool(name: string): boolean | undefined {
@@ -44,11 +69,16 @@ function envBool(name: string): boolean | undefined {
 	return undefined;
 }
 
-/** The settings file shared by pi-cc-loop and pi-cc-monitor. */
+/** The variable overriding a setting right now, as `PI_CC_FOOTER=0`; undefined when none is. */
+export function envOverride(key: keyof PiCcConfig): string | undefined {
+	const name = ENV_OVERRIDES[key];
+	return envBool(name) === undefined ? undefined : `${name}=${process.env[name]}`;
+}
+
+/** The settings file shared by pi-cc-loop and pi-cc-monitor, in Pi's agent directory. */
 export function configPath(): string {
 	if (process.env.PI_CC_CONFIG_FILE) return process.env.PI_CC_CONFIG_FILE;
-	const agentDir = process.env.PI_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent");
-	return path.join(agentDir, "pi-cc.json");
+	return path.join(getAgentDir(), "pi-cc.json");
 }
 
 function readConfig(): PiCcConfig {
@@ -61,10 +91,14 @@ function readConfig(): PiCcConfig {
 	}
 	return {
 		compactMessages:
-			envBool("PI_CC_COMPACT_MESSAGES") ??
+			envBool(ENV_OVERRIDES.compactMessages) ??
 			(typeof file.compactMessages === "boolean" ? file.compactMessages : DEFAULT_CONFIG.compactMessages),
 		footer:
-			envBool("PI_CC_FOOTER") ?? (typeof file.footer === "boolean" ? file.footer : DEFAULT_CONFIG.footer),
+			envBool(ENV_OVERRIDES.footer) ?? (typeof file.footer === "boolean" ? file.footer : DEFAULT_CONFIG.footer),
+		draft: envBool(ENV_OVERRIDES.draft) ?? (typeof file.draft === "boolean" ? file.draft : DEFAULT_CONFIG.draft),
+		turnSummary:
+			envBool(ENV_OVERRIDES.turnSummary) ??
+			(typeof file.turnSummary === "boolean" ? file.turnSummary : DEFAULT_CONFIG.turnSummary),
 	};
 }
 
@@ -81,9 +115,14 @@ export function invalidateConfig(): void {
 	cached = undefined;
 }
 
-/** Merge a patch into the settings file and update the cache. */
+/**
+ * Write the changed keys to the settings file and return the settings now in
+ * effect. Only the patch is written: every other key stays as the user left
+ * it, and an environment override is never copied into the file. It still
+ * wins over the file while it is set, so the returned value can differ from
+ * the patch (see `envOverride`).
+ */
 export function saveConfig(patch: Partial<PiCcConfig>): PiCcConfig {
-	const next = { ...loadConfig(), ...patch };
 	const file = configPath();
 	fs.mkdirSync(path.dirname(file), { recursive: true });
 	// Keep keys this version does not know about: the file is the user's.
@@ -95,8 +134,8 @@ export function saveConfig(patch: Partial<PiCcConfig>): PiCcConfig {
 		// A missing or malformed file is rewritten from scratch.
 	}
 	const temp = `${file}.tmp`;
-	fs.writeFileSync(temp, `${JSON.stringify({ ...raw, ...next }, null, 2)}\n`, "utf8");
+	fs.writeFileSync(temp, `${JSON.stringify({ ...raw, ...patch }, null, 2)}\n`, "utf8");
 	fs.renameSync(temp, file);
-	cached = next;
-	return next;
+	cached = undefined;
+	return loadConfig();
 }

package/index.ts

@@ -29,7 +29,7 @@
 
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { configPath, invalidateConfig, loadConfig, saveConfig, type PiCcConfig } from "./config.ts";
+import { invalidateConfig, loadConfig } from "./config.ts";
 import {
 	humanSchedule,
 	isUnreachable,
@@ -57,6 +57,7 @@ import {
 	loopCommandGuidelines,
 } from "./prompts.ts";
 import { formatClock, formatEta, renderScheduledMessage } from "./renderers.ts";
+import { CONFIG_CHANNEL, registerPiCcCommand } from "./settings.ts";
 import {
 	DEFAULT_TIMING,
 	generateId,
@@ -73,7 +74,6 @@ const STATE_ENTRY = "pi-cc-loop-state";
 const MONITOR_EVENT_TYPE = "Monitor";
 /** Footer status key, shared with every other extension's status line. */
 const STATUS_KEY = "loop";
-const CONFIG_CHANNEL = "pi-cc:config";
 
 /**
  * The event channel this extension publishes on when a chain ends. pi-cc-monitor
@@ -568,37 +568,15 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			const raw = args.trim();
 			const [head, ...rest] = raw.split(/\s+/);
 
-			// Settings configure the extension, not a loop: they stay in code.
+			// Settings moved to /pi_cc: these words stay recognized so they cannot
+			// start a loop by mistake (everything else is a loop request).
 			switch ((head ?? "").toLowerCase()) {
 				case "footer":
-				case "statusline": {
-					const arg = (rest[0] ?? "").toLowerCase();
-					if (!arg) {
-						notify(ctx, `Usage: /loop footer on|off (currently ${loadConfig().footer ? "on" : "off"})`, "info");
-						return;
-					}
-					setSetting(ctx, "footer", arg);
-					return;
-				}
+				case "statusline":
 				case "settings":
-				case "config": {
-					const [key, value] = rest;
-					if (!key) {
-						showSettings(ctx);
-						return;
-					}
-					const name = key.toLowerCase();
-					if (name === "messages" || name === "message") {
-						setSetting(ctx, "messages", value);
-						return;
-					}
-					if (name === "footer" || name === "status") {
-						setSetting(ctx, "footer", value);
-						return;
-					}
-					notify(ctx, "Usage: /loop settings [messages|footer] [on|off]", "info");
+				case "config":
+					notify(ctx, "Settings live under /pi_cc now: /pi_cc footer on|off, /pi_cc messages on|off", "info");
 					return;
-				}
 				case "help":
 				case "--help":
 				case "-h":
@@ -650,10 +628,7 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			"/loop [interval] <prompt>   run <prompt> every <interval> (e.g. 30s, 5m, 2h, 1d)",
 			"/loop <prompt>              self-paced: the agent picks the next delay",
 			"/loop [interval]            the .pi/loop.md tasks, or the built-in maintenance prompt",
-			"/loop footer on|off         show or hide the one-line summary in the footer",
-			"/loop settings              show UI settings",
-			"/loop settings messages on|off   compact two-line markers",
-			"/loop settings footer on|off     the one-line footer summary",
+			"/pi_cc                      pi-cc settings panel (message style, footer summary)",
 			"",
 			"Esc on a self-paced loop's own turn cancels that loop; fixed-interval loops keep running.",
 			"Flags: --durable  write the job to .pi/scheduled_tasks.json so it survives a restart.",
@@ -662,37 +637,15 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		notify(ctx, help, "info");
 	}
 
-	function showSettings(ctx: ExtensionContext): void {
-		const config = loadConfig();
-		const lines = [
-			`pi-cc settings \u00b7 ${configPath()}`,
-			`  messages:  ${config.compactMessages ? "compact" : "card"}`,
-			`  footer:    ${config.footer ? "summary" : "hidden"}`,
-			"",
-			"Usage: /loop settings messages on|off",
-			"       /loop settings footer on|off",
-		];
-		notify(ctx, lines.join("\n"), "info");
-	}
+	// The shared pi-cc settings and their /pi_cc command. The first pi-cc
+	// package to load registers it; this one re-claims its own claim on /reload.
+	registerPiCcCommand(pi, "pi-cc-loop");
 
-	function setSetting(ctx: ExtensionContext, key: "messages" | "footer", raw: string | undefined): void {
-		const value = (raw ?? "").toLowerCase();
-		const on = value === "on" || value === "true" || value === "1";
-		const off = value === "off" || value === "false" || value === "0";
-		if (!on && !off) {
-			showSettings(ctx);
-			return;
-		}
-		const patch: Partial<PiCcConfig> = key === "messages" ? { compactMessages: on } : { footer: on };
-		const next = saveConfig(patch);
-		try {
-			pi.events.emit(CONFIG_CHANNEL, next);
-		} catch {
-			// another extension must not break the command
-		}
-		notify(ctx, `${key === "messages" ? "Compact message style" : "Footer summary"} ${on ? "enabled" : "disabled"}`, "info");
-		if (key === "footer") refreshStatus();
-	}
+	// A setting changed (here or in another pi-cc package): the footer follows.
+	pi.events.on(CONFIG_CHANNEL, () => {
+		invalidateConfig();
+		refreshStatus();
+	});
 
 	// ------------------------------------------------------------------ tools
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cc-loop",
-	"version": "0.4.0",
+	"version": "0.6.0",
 	"description": "Claude Code compatible /loop for the Pi coding agent: cron-scheduled fixed intervals, self-paced chains, and the same dispatch semantics as Claude Code.",
 	"author": "tarnish233",
 	"type": "module",

package/settings.ts

@@ -0,0 +1,314 @@
+/**
+ * The /pi_cc command: the settings every pi-cc package shares.
+ *
+ * This file is copied verbatim between pi-cc-loop, pi-cc-monitor and
+ * pi-cc-plugins (separate npm packages); each repo's tests/shared.test.mjs
+ * fails when the copies drift apart. The settings live in one pi-cc.json and
+ * apply to every pi-cc package installed. A change is announced on the
+ * "pi-cc:config" channel, so the packages repaint what the settings change
+ * (loop and monitor both redraw the footer).
+ *
+ * Pi's /settings cannot take items from an extension (its panel is a fixed
+ * list, and the command is handled before extension commands), so /pi_cc
+ * opens the same kind of screen, built from the same parts: SettingsList
+ * between two borders, the selected setting's description below it, and
+ * Enter/Space to change a value. A change is saved at once and Esc closes.
+ * A setting that an environment variable overrides shows the value in effect
+ * and cannot be changed here; its description names the variable. Outside the
+ * TUI, /pi_cc prints the summary.
+ *
+ * Only one /pi_cc exists however many pi-cc packages are installed: Pi turns
+ * same-named commands from different extensions into /pi_cc:1 and /pi_cc:2,
+ * and plain /pi_cc then matches neither. The first pi-cc package to load
+ * claims the command on a global symbol (extensions share one process), and
+ * releases the claim at session shutdown, so /reload and pi-config changes
+ * run the race again. The claim holds the owner's name, so a package
+ * re-loading over its own claim re-claims it. The API offers no other way:
+ * getCommands() cannot be called during loading.
+ */
+
+import { DynamicBorder, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Container, SettingsList, Spacer, Text, type SettingItem, type SettingsListTheme } from "@earendil-works/pi-tui";
+import os from "node:os";
+import path from "node:path";
+import { configPath, envOverride, loadConfig, saveConfig, type PiCcConfig } from "./config.ts";
+
+/** Saved settings travel between the packages on this channel. */
+export const CONFIG_CHANNEL = "pi-cc:config";
+
+/** One /pi_cc per session: the first pi-cc package to load claims the name. */
+const SLASH_CLAIM = Symbol.for("pi-cc:slash-command");
+
+/** The part of Pi's theme the panel uses. */
+export interface PanelTheme {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+interface SettingSpec {
+	field: keyof PiCcConfig;
+	label: string;
+	/** Display values for true and false. */
+	on: string;
+	off: string;
+	description: string;
+}
+
+const SETTINGS: SettingSpec[] = [
+	{
+		field: "compactMessages",
+		label: "Message style",
+		on: "compact",
+		off: "card",
+		description:
+			"How scheduled fires and Monitor events are drawn. compact: \u273b header and indented body; card: the old padded card.",
+	},
+	{
+		field: "footer",
+		label: "Footer summary",
+		on: "on",
+		off: "off",
+		description: "One line in Pi's footer while loops or monitors run: loop 2 \u00b7 next 3m, monitor 2.",
+	},
+	{
+		field: "draft",
+		label: "Draft recall",
+		on: "on",
+		off: "off",
+		description: "pi-cc-plugins: Ctrl+C keeps what it clears; Up on the empty editor brings it back.",
+	},
+	{
+		field: "turnSummary",
+		label: "Turn summary",
+		on: "on",
+		off: "off",
+		description: "pi-cc-plugins: one line closes every agent run \u2014 tools, duration, done time.",
+	},
+];
+
+/**
+ * Pi's getSettingsListTheme(), built from the theme the panel is given: the
+ * global theme that function reads is not shared with extensions in every
+ * Pi runtime (see the note on Pi's DynamicBorder).
+ */
+function listTheme(theme: PanelTheme): SettingsListTheme {
+	return {
+		label: (text, selected) => (selected ? theme.fg("accent", text) : text),
+		value: (text, selected) => (selected ? theme.fg("accent", text) : theme.fg("muted", text)),
+		description: (text) => theme.fg("dim", text),
+		cursor: theme.fg("accent", "\u2192 "),
+		hint: (text) => theme.fg("dim", text),
+	};
+}
+
+/** A path with the home directory shortened to ~. */
+function displayPath(file: string): string {
+	const home = os.homedir();
+	return file === home || file.startsWith(home + path.sep) ? `~${file.slice(home.length)}` : file;
+}
+
+function item(spec: SettingSpec): SettingItem {
+	const value = loadConfig()[spec.field] ? spec.on : spec.off;
+	const override = envOverride(spec.field);
+	if (override) {
+		// No values: Enter/Space leaves it alone, and the description says why.
+		return {
+			id: spec.field,
+			label: spec.label,
+			currentValue: value,
+			description: `${spec.description}\n${override} overrides this while set; unset it to change it here.`,
+		};
+	}
+	return { id: spec.field, label: spec.label, currentValue: value, values: [spec.on, spec.off], description: spec.description };
+}
+
+export interface SettingsPanelOptions {
+	theme: PanelTheme;
+	/** Where the settings are saved, shown in the title. */
+	file: string;
+	/** Save one setting (and tell the other packages). */
+	onChange(field: keyof PiCcConfig, value: boolean): void;
+	onClose(): void;
+}
+
+export interface SettingsPanel {
+	render(width: number): string[];
+	invalidate(): void;
+	handleInput(data: string): void;
+}
+
+export function settingsPanel(options: SettingsPanelOptions): SettingsPanel {
+	const { theme } = options;
+	const list = new SettingsList(
+		SETTINGS.map(item),
+		SETTINGS.length,
+		listTheme(theme),
+		(id, value) => {
+			const spec = SETTINGS.find((candidate) => candidate.field === id);
+			if (!spec) return;
+			options.onChange(spec.field, value === spec.on);
+			// Show what is in effect now.
+			list.updateValue(id, loadConfig()[spec.field] ? spec.on : spec.off);
+		},
+		() => options.onClose(),
+	);
+
+	const border = () => new DynamicBorder((text: string) => theme.fg("border", text));
+	const container = new Container();
+	container.addChild(border());
+	container.addChild(
+		new Text(`${theme.fg("accent", theme.bold("pi-cc settings"))}${theme.fg("dim", ` \u00b7 ${displayPath(options.file)}`)}`, 0, 0),
+	);
+	container.addChild(new Spacer(1));
+	container.addChild(list);
+	container.addChild(border());
+
+	return {
+		render: (width) => container.render(width),
+		invalidate: () => container.invalidate(),
+		handleInput: (data) => list.handleInput(data),
+	};
+}
+
+function notify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error" = "info"): void {
+	try {
+		if (ctx.hasUI) ctx.ui.notify(message, level);
+	} catch {
+		// a stale context must never break the command
+	}
+}
+
+/** ` (PI_CC_FOOTER=0)` when an environment variable decides the setting. */
+function overrideNote(key: keyof PiCcConfig): string {
+	const override = envOverride(key);
+	return override ? ` (${override})` : "";
+}
+
+function showSettings(ctx: ExtensionContext): void {
+	const config = loadConfig();
+	const lines = [
+		`pi-cc settings \u00b7 ${configPath()}`,
+		`  messages:  ${config.compactMessages ? "compact" : "card"}${overrideNote("compactMessages")}`,
+		`  footer:    ${config.footer ? "summary" : "hidden"}${overrideNote("footer")}`,
+		`  draft:     ${config.draft ? "on" : "off"}${overrideNote("draft")}`,
+		`  summary:   ${config.turnSummary ? "on" : "off"}${overrideNote("turnSummary")}`,
+		"",
+		"Usage: /pi_cc messages on|off",
+		"       /pi_cc footer on|off",
+		"       /pi_cc draft on|off",
+		"       /pi_cc summary on|off",
+	];
+	notify(ctx, lines.join("\n"), "info");
+}
+
+/** Save one setting and tell every pi-cc package; each repaints itself. Returns the settings in effect. */
+type ApplySetting = (field: keyof PiCcConfig, on: boolean) => PiCcConfig;
+
+/**
+ * A bare /pi_cc in the TUI: a panel like Pi's /settings, which extensions
+ * cannot add to. Resolves when the panel closes; false when there is no TUI
+ * to show it in, so the caller prints the summary instead.
+ */
+async function openSettingsPanel(ctx: ExtensionCommandContext, apply: ApplySetting): Promise<boolean> {
+	if (ctx.mode !== "tui" || typeof ctx.ui.custom !== "function") return false;
+	await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+		const panel = settingsPanel({
+			theme,
+			file: configPath(),
+			onChange: (field, value) => {
+				apply(field, value);
+			},
+			onClose: () => done(undefined),
+		});
+		return {
+			render: (width: number) => panel.render(width),
+			invalidate: () => panel.invalidate(),
+			handleInput: (data: string) => {
+				panel.handleInput(data);
+				tui.requestRender();
+			},
+		};
+	});
+	return true;
+}
+
+/** The command word for each setting: the field it writes and its notice label. */
+const KEYS: Record<string, { field: keyof PiCcConfig; label: string }> = {
+	messages: { field: "compactMessages", label: "Compact message style" },
+	message: { field: "compactMessages", label: "Compact message style" },
+	footer: { field: "footer", label: "Footer summary" },
+	status: { field: "footer", label: "Footer summary" },
+	statusline: { field: "footer", label: "Footer summary" },
+	draft: { field: "draft", label: "Draft recall" },
+	summary: { field: "turnSummary", label: "Turn summary" },
+	turnsummary: { field: "turnSummary", label: "Turn summary" },
+};
+
+function setSetting(ctx: ExtensionContext, apply: ApplySetting, key: string, raw: string | undefined): void {
+	const spec = KEYS[key];
+	if (!spec) {
+		showSettings(ctx);
+		return;
+	}
+	const value = (raw ?? "").toLowerCase();
+	const on = value === "on" || value === "true" || value === "1";
+	const off = value === "off" || value === "false" || value === "0";
+	if (!on && !off) {
+		showSettings(ctx);
+		return;
+	}
+	const field = spec.field;
+	const next = apply(field, on);
+	const override = envOverride(field);
+	if (override && next[field] !== on) {
+		// The file has the choice, but the variable decides while it is set.
+		notify(ctx, `${spec.label} saved as ${on ? "on" : "off"}, but ${override} overrides it while set`, "warning");
+	} else {
+		notify(ctx, `${spec.label} ${on ? "enabled" : "disabled"}`, "info");
+	}
+}
+
+/**
+ * Register /pi_cc on behalf of one pi-cc package. The first package to load
+ * wins; the others leave the command to it, so there is never a /pi_cc:2.
+ */
+export function registerPiCcCommand(pi: ExtensionAPI, owner: string): void {
+	const claims = globalThis as typeof globalThis & Record<symbol, string | undefined>;
+	if (claims[SLASH_CLAIM] !== undefined && claims[SLASH_CLAIM] !== owner) return;
+	claims[SLASH_CLAIM] = owner;
+	// Release the name when this session ends, so /reload re-runs the race.
+	pi.on("session_shutdown", () => {
+		if (claims[SLASH_CLAIM] === owner) claims[SLASH_CLAIM] = undefined;
+	});
+
+	const applySetting: ApplySetting = (field, on) => {
+		const patch: Partial<PiCcConfig> = { [field]: on };
+		const next = saveConfig(patch);
+		try {
+			pi.events.emit(CONFIG_CHANNEL, next);
+		} catch {
+			// another extension must not break the command
+		}
+		return next;
+	};
+
+	pi.registerCommand("pi_cc", {
+		description: "pi-cc settings: message style, footer summary",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const words = args.trim().split(/\s+/).filter(Boolean);
+			// "/pi_cc settings footer on" reads like the old /loop settings: drop the noun.
+			if (words[0] === "settings" || words[0] === "config") words.shift();
+			if (words.length === 0) {
+				if (!(await openSettingsPanel(ctx, applySetting))) showSettings(ctx);
+				return;
+			}
+			// "/pi_cc help", or a word that is not a setting: the summary says what is.
+			const key = words[0].toLowerCase();
+			if (key === "help" || !KEYS[key]) {
+				showSettings(ctx);
+				return;
+			}
+			setSetting(ctx, applySetting, key, words[1]);
+		},
+	});
+}