pi-cc-loop 0.3.0 → 0.5.0

package/README.md

@@ -1,59 +1,123 @@
 # pi-cc-loop
 
-> 在 Pi 里复刻 Claude Code 的 `/loop`：固定间隔 cron、自选间隔、兜底心跳和底部状态摘要。
+> 在 Pi 里复刻 Claude Code 的 `/loop`：固定间隔、自选间隔、兜底心跳和底部状态摘要。
 
-## 快速开始
+## 安装
 
 ```bash
-# 本地开发：把仓库软链接到 Pi 扩展目录
-ln -sfn "$PWD" ~/.pi/agent/extensions/pi-cc-loop
-
-# 发布后
 pi install npm:pi-cc-loop
 ```
 
-安装后执行 `/reload`。
+安装后执行 `/reload`。本地开发时把仓库软链接到扩展目录即可：
+
+```bash
+ln -sfn "$PWD" ~/.pi/agent/extensions/pi-cc-loop
+```
 
 ## 工作方式
 
 `/loop` 和 CC 一样是一个**技能**，不是用代码直接排任务：你输入的内容会作为一条普通 user 消息进入对话，
 模型自己解析间隔并调用工具完成。所以对话里始终能看到你要求了什么、模型做了什么。
 
+给模型的规则（怎么建任务、自定步调怎么续期）以一条隐藏消息附在这一轮后面，不改 system prompt：
+不支持对话中途 system 消息的 provider 会把 system prompt 整体重建，规则一来一去会让整段提示缓存失效。
+固定间隔的每次触发不附加任何东西，信封里一句"它会自己触发下一次，取消用 cron_delete"就够了。
+
 | 功能 | 说明 | 入口 |
 | --- | --- | --- |
-| 固定间隔 | 模型用 `cron_create` 建一个 cron（`5m` → `*/5 * * * *`），然后立即执行一次；触发时按"定时任务"呈现 | `/loop 5m <prompt>`、`/loop 每分钟 ...` |
+| 固定间隔 | 模型用 `cron_create` 建一个 cron（`5m` → `*/5 * * * *`），然后立即执行一次；触发时按"定时任务"呈现。不带 `/loop`、直接说"每分钟打印一次hello"也一样 | `/loop 5m <prompt>`、`/loop 每分钟 ...` |
 | 自选间隔 | 运行一次后用 `schedule_wakeup` 决定下次延迟（60–3600s） | `/loop <prompt>` |
-| loop.md | 请求本身没有任务时（裸 `/loop` 或只给间隔）由 `.pi/loop.md` 提供，每次触发重读；首轮由模型自己读文件 | `/loop`、`/loop 15m` |
-| 停止 / 查看 | 也走对话：模型用 `cron_list` / `cron_delete`（自选间隔用 `schedule_wakeup` + `stop: true`） | `/loop stop`、`/loop status` |
+| loop.md | 请求本身没有任务时（裸 `/loop` 或只给间隔）由 `.pi/loop.md`（或 `~/.pi/loop.md`）提供，每次触发重读；没有时用内置维护 prompt | `/loop`、`/loop 15m` |
+| 停止 / 查看 | 也走对话：模型用 `cron_list` / `cron_delete`（自选间隔用 `schedule_wakeup` + `stop: true`）；停掉后再输入同一个 `/loop` 会重新开始 | `/loop stop`、`/loop status` |
+| 回合中输入 | 模型正在回复时输入 `/loop ...`：底部提示"will start when the current turn ends"，当前回合结束后作为新的一轮开始（不会混进正在进行的回合） | 自动 |
 | 漏跑合并 | agent 忙时到点只记一次 pending，空闲后发一条 | 自动 |
 | 兜底心跳 | 模型忘记调度时 arm 一次 20 分钟心跳，预算 1 次 | 自动 |
 | Esc 取消 | 打断属于某个自定步调 loop 的回合（它的 tick、它的 Monitor 唤醒的回合）时取消该 loop；无关回合、空闲时不受影响；固定间隔不受影响 | Esc |
 | 错峰 | 周期任务按 id 固定延后最多半个周期（≤30 分钟），间隔本身不变；`:00`/`:30` 的一次性任务最多提前 90 秒 | 自动 |
 | 过期 | 周期任务 7 天后最后执行一次再删除；一次性任务不过期 | 自动 |
-| 次数上限 | `maxFires`，到顶自动删除 | 模型传参 |
-| 持久化 | `durable: true` 写入 `.pi/scheduled_tasks.json`；同一项目只由一个 Pi 会话执行 | 模型传参 |
+| 次数上限 | `maxFires`，到顶自动删除 | `--max N` |
+| 持久化 | `durable: true` 写入 `.pi/scheduled_tasks.json`，重启后继续；同一项目只由一个 Pi 会话执行 | `--durable` |
 | 底部摘要 | Pi 底部状态栏一行：`loop 2 · next 3m`，无任务时不占位 | `/loop footer on\|off` |
-| 界面设置 | 仍是本地命令，不进对话 | `/loop settings ...` |
+| 界面设置 | 和 Pi 的 `/settings` 一样的面板，本地命令，不进对话 | `/loop settings` |
 
 ## 命令
 
 ```text
-/loop [间隔] <prompt>     交给模型：按间隔重复，或自选节奏
-/loop <prompt>            交给模型：自选间隔
-/loop [间隔]              交给模型：跑 .pi/loop.md 或内置维护 prompt
-/loop status              交给模型：列出当前 loop
-/loop stop [id]           交给模型：停止一个或全部
+/loop <间隔> <prompt>     固定间隔重复（模型用 cron_create）
+/loop <prompt>            自选间隔（模型用 schedule_wakeup）
+/loop [间隔]              跑 loop.md，没有就跑内置维护 prompt
+/loop status              列出当前任务
+/loop stop [id]           停止一个或全部
 /loop footer on|off       本地：底部摘要
-/loop settings ...        本地：界面设置
+/loop settings            本地：设置面板
 /loop help                本地：帮助
 ```
 
-前五个会作为普通 user 消息进入对话（内容就是你输入的那行），模型再按技能说明调用
-`cron_create`、`cron_list`、`cron_delete`、`schedule_wakeup`。后三个只改界面，不进对话。
+前五个会作为普通 user 消息进入对话（内容就是你输入的那行），模型再按技能说明调用工具；后三个只改界面，不进对话。
 
 间隔写法没有约束，模型自己解析：`30s`、`5m`、`2h`、`1d`、`check the deploy every 20m`、
 `每2分钟输出一次`、`每分钟打印一次hi` 都可以。小于一分钟会向上取整到每分钟。
 
+可以在请求里加 `--durable`（写入 `.pi/scheduled_tasks.json`，重启后继续）和 `--max N`（触发 N 次后自动删除）。
+
+## 工具
+
+| 工具 | 界面显示 | 说明 |
+| --- | --- | --- |
+| `cron_create` | `CronCreate` | 5 段 cron（本地时区）+ prompt；`recurring` 默认 `true`，`false` 为一次性；可选 `durable`、`maxFires` |
+| `cron_delete` | `CronDelete` | 按 id 取消；也能结束自定步调 loop |
+| `cron_list` | `CronList` | 列出任务和实际的下次运行时间（已含错峰） |
+| `schedule_wakeup` | `ScheduleWakeup` | 自定步调：`delaySeconds`（限制在 60–3600）、`reason`（必填，显示在触发块表头）、`prompt`；`stop: true` 结束 |
+
+## 渲染
+
+定时触发只显示任务本身，给模型看的信封不上屏：
+
+```text
+✻ Running scheduled task · 9:52pm
+   print hi
+
+✻ loop #3 · 9:53pm · watching CI run
+   check the deploy
+```
+
+固定间隔按"定时任务"呈现；只有自选间隔叫 loop，表头带上模型给的 `reason`。折叠时正文最多 3 行，
+Ctrl+O 展开后多一行元信息（任务 id、节奏）。`compactMessages` 关闭时回到旧的带底色卡片。
+
+## 设置
+
+两个 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`
+}
+```
+
+在 TUI 里输入 `/loop settings` 会打开设置面板，样子和操作都和 Pi 的 `/settings` 一样：上下键选择，Enter/空格切换，Esc 关闭；
+改动立即保存，两个扩展同时生效。Pi 的 `/settings` 不接受扩展加项，所以面板放在 `/loop settings` 下。
+
+```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
+─────────────────────────────────────────────────────────────
+```
+
+也可以用文字命令：`/loop settings messages on|off`、`/loop settings footer on|off`（或 `/loop footer on|off`），适合脚本和 RPC；
+非 TUI 模式下，不带参数的 `/loop settings` 输出当前设置。命令只写改动的那一项，文件里的其他内容原样保留。
+
+环境变量 `PI_CC_FOOTER`、`PI_CC_COMPACT_MESSAGES` 优先于文件，但不会被写进文件。设着的时候，面板里这一项显示实际生效的值、不能切换，
+说明里写出是哪个变量；文字输出会在对应项后面标出来（如 `hidden (PI_CC_FOOTER=0)`）；用文字命令切换会写进文件，但提示会说明变量还在覆盖它。
+
 ## 底部摘要
 
 `ctx.ui.setStatus("loop", …)` 是 Pi 核心 API，不依赖任何其他扩展：
@@ -68,42 +132,61 @@ pi install npm:pi-cc-loop
 - 倒计时取整到分钟，配合"文本相同就不调用"的去重，最多每分钟重绘一次（Pi 每次 `setStatus` 都会触发重绘）
 - 装了 `pi-cc-extensions`：这一行会作为它的一个 chip 出现在第 2 行，可在它的配置面板里移动或隐藏；它会把 ANSI 去掉，所以这里只用纯文本
 - 没装 `pi-cc-extensions`：Pi 内置 footer 会把它和其他扩展的状态拼成一行，加在用量行下面，只在有任务时出现
-
-> 本扩展不写其他插件的配置文件。如果你之前在 `pi-cc-extensions.json` 里因为旧版本加过
-> `cron_create`、`cron_delete`、`cron_list`、`schedule_wakeup` 这几条 `excludeRenderers`，
-> 现在可以删掉：工具行由 Pi 或 pi-cc-extensions 自己渲染。
+- 装了 `pi-cc-monitor`：运行中的 monitor 另有一项 `monitor 2`，和这一行用同一个开关
 
 ## 环境变量
 
 | 变量 | 默认 | 说明 |
 | --- | --- | --- |
-| `PI_LOOP_MAX_AGE_DAYS` | `7` | 任务最长存活天数，`0` 不过期 |
+| `PI_LOOP_MAX_AGE_DAYS` | `7` | 周期任务最长存活天数，`0` 不过期 |
 | `PI_LOOP_KEEPALIVE_SECONDS` | `1200` | 兜底心跳；`0` 禁用 |
 | `PI_LOOP_JITTER` | `0.5` | 周期任务最多延后的周期比例；`0` 关闭错峰 |
 | `PI_LOOP_SCAN_MS` | `1000` | 调度扫描间隔 |
-| `PI_CC_FOOTER` | `1` | 底部摘要；`0` 关闭（两个 pi-cc 包共用） |
+| `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 的配置目录里，跟随 `PI_CODING_AGENT_DIR` |
 
 ## 兼容性
 
 - Node.js `>=22.19.0`
-- Pi `1.3.0`（开发环境）
-- 与 `pi-cc-extensions` 共存，见上面的设置说明
+- Pi 1.3.0、1.4.0（测试通过）
+- `pi-cc-monitor` 可选：自定步调 loop 需要等外部事件时会用它，loop 结束时连带停止；两者通过 `pi.events` 通信
+- 与 `pi-cc-extensions` 共存。本扩展不写其他插件的配置文件；旧版本在 `pi-cc-extensions.json` 里加过的
+  `cron_create`、`cron_delete`、`cron_list`、`schedule_wakeup` 这几条 `excludeRenderers` 可以删掉
 
 ## 本地开发
 
 ```bash
 node --test tests/*.test.mjs
 npx --yes typescript@5.9.3 tsc --noEmit -p tsconfig.json
+node scripts/cache-check.mjs    # 真实 provider 的缓存检查，默认用免费模型，发版前跑
 ```
 
-## 说明
+### 缓存约束
+
+提示缓存按前缀匹配（工具 → system prompt → 消息），扩展只能往对话末尾追加：
+
+- **不改 system prompt**：每轮需要的规则作为隐藏消息附在这一轮后面（`before_agent_start` 返回 `message`），不写 `promptGuidelines`，不返回 `systemPrompt`。
+- **不动工具集**：工具在加载时一次注册，描述是固定文本；不调用 `setActiveTools`，会话中途不改描述。
+- **不改历史**：不注册 `context` / `context_with_system` / `before_provider_request`。
+
+`tests/cache.test.mjs` 守住这三条。`scripts/cache-check.mjs` 用真实 provider 依次走一遍固定间隔 `/loop`、触发、普通对话、`/loop stop`、Monitor 事件、自定步调 `/loop` 和它的触发，逐个请求看缓存读取量：
+读到的明显少于上一个请求发出的内容就报 MISS（退出码 1）。provider 偶尔会自己丢缓存，同一步骤重跑仍然 MISS 才是扩展的问题。
+默认模型 `opencode-go/beam-free` 免费；`--model` 可换，脚本最后会打印本次花费。
+
+## 与 Claude Code 的差异
+
+行为对齐 Claude Code 2.1.308 的 `/loop`，用 Pi 扩展 API 实现。有意不同的地方：
 
-- 行为对齐 Claude Code v2.1.306 的 `/loop`，用 Pi 扩展 API 实现。
-- Esc 只取消被打断回合所属的自定步调 loop；CC 在任何时候按 Esc（包括空闲、打断无关回合）都会取消所有自定步调 loop。其他情况用 `/loop stop`。
-- 底部摘要默认开启，是 CC 没有的（CC 主会话不显示 loop 状态）；详细面板默认关闭。
-- `cron_create` 的 `maxFires` 是额外加固；CC 没有次数上限。
-- `/loop stop` 会连带静默停掉该 chain 绑定的 Monitor。
+- Esc 只取消被打断回合所属的自定步调 loop；CC 按 Esc（包括空闲时、打断无关回合时）会取消所有自定步调 loop。其他情况用 `/loop stop`。
+- 固定间隔的触发里调用 `schedule_wakeup` 会被当作空操作并返回说明，防止同一个任务又被自定步调重复调度；CC 没有这条硬规则。
+- 不带 `/loop` 的请求（比如"每分钟打印一次hello"）也会在建好任务后立即做一次。CC 靠模型自己调用 loop 技能做到（`CronCreate` 在 CC 里是延迟加载的工具，模型会先走技能）；Pi 没有延迟加载工具，这里改为在 `cron_create` 的结果里加一句提示，只在普通对话里建周期任务时出现。
+- 底部摘要和 `maxFires` 次数上限是额外加的；CC 主会话不显示 loop 状态，也没有次数上限。
+- 自定步调 loop 结束（stop、Esc、`cron_delete`、兜底心跳用完）时，绑定的 Monitor 会被静默停止；CC 靠模型自己调用 `TaskStop`。
 - Monitor 事件不会取消待触发的 wakeup，它始终是兜底心跳（与 CC 一致）。
+- 没有做 CC 的 `noop` 折叠、触发时"不是用户实时输入"的安全提示、间隔边界提示和云端调度。
+- 没有做 CC 针对 5 分钟提示缓存的两处调整（`*/5` 每次提前 15 秒、接近 300 秒的唤醒往回拉）。在 5 分钟缓存的 provider 上（比如 Anthropic 默认），`*/5` 的触发和 300 秒左右的唤醒可能刚好错过缓存。
 
 ## 许可证
 

package/config.ts

@@ -3,7 +3,8 @@
  *
  * 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.
+ * 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
  *   {
@@ -11,14 +12,15 @@
  *     "footer": true
  *   }
  *
- * Environment overrides (useful for tests and quick experiments):
+ * 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
  */
 
+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 {
@@ -36,6 +38,12 @@ export const DEFAULT_CONFIG: PiCcConfig = {
 	footer: true,
 };
 
+/** The environment variable that overrides each setting. */
+const ENV_OVERRIDES: Record<keyof PiCcConfig, string> = {
+	compactMessages: "PI_CC_COMPACT_MESSAGES",
+	footer: "PI_CC_FOOTER",
+};
+
 function envBool(name: string): boolean | undefined {
 	const raw = process.env[name];
 	if (raw === undefined) return undefined;
@@ -44,11 +52,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 +74,10 @@ 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),
 	};
 }
 
@@ -81,9 +94,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 +113,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/cron.ts

@@ -154,7 +154,6 @@ export function isUnreachable(expression: string): boolean {
 	return nextFireAfter(fields, new Date(), 366) === null;
 }
 
-/** The unit words Claude Code's /loop accepts in a trailing "every N <unit>" clause. */
 /**
  * The divisor of `total` closest to `n`.
  *
@@ -176,15 +175,6 @@ function nearestDivisor(n: number, total: number): number {
 	return best;
 }
 
-/**
- * Parse `每2分钟输出一次` / `输出一次 每隔 2 小时`: an explicit interval written
- * in Chinese. The digit is required on purpose: `每天都有一个测试失败` is a
- * prompt, not a schedule, and Claude Code's own splitting is just as literal.
- */
-/**
- * Parse a trailing `every 20m` / `every 5 min` / `every 2 hours` clause, with
- * the unit words Claude Code accepts.
- */
 const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
 
 

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 { configPath, envOverride, invalidateConfig, loadConfig, saveConfig, type PiCcConfig } from "./config.ts";
 import {
 	humanSchedule,
 	isUnreachable,
@@ -44,18 +44,20 @@ import {
 	CRON_DELETE_SNIPPET,
 	CRON_LIST_DESCRIPTION,
 	CRON_LIST_SNIPPET,
-	cronTickGuidelines,
 	LOOP_FILE_SENTINEL,
 	loopGuidelines,
 	missedJobsMessage,
 	monitorGuidelines,
 	provenance,
+	RULES_PROVENANCE,
+	RUN_NOW_HINT,
 	SCHEDULE_WAKEUP_DESCRIPTION,
 	scheduledTaskProvenance,
 	SCHEDULE_WAKEUP_SNIPPET,
 	loopCommandGuidelines,
 } from "./prompts.ts";
 import { formatClock, formatEta, renderScheduledMessage } from "./renderers.ts";
+import { settingsPanel } from "./settings-panel.ts";
 import {
 	DEFAULT_TIMING,
 	generateId,
@@ -171,9 +173,10 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 	 * What the current run belongs to, derived from its starting message:
 	 * `chainId` is the self-paced chain whose tick (or monitor) started it,
 	 * `cronId` the fixed-interval job whose tick started it, `armed` the chains
-	 * it armed, `tick` the tick number of a /loop run.
+	 * it armed, `tick` the tick number of a /loop run, `loopRequest` set when a
+	 * typed /loop started it (its rules already say to do the task now).
 	 */
-	let currentRun: { chainId?: string; cronId?: string; armed?: Set<string>; tick?: number } = {};
+	let currentRun: { chainId?: string; cronId?: string; armed?: Set<string>; tick?: number; loopRequest?: boolean } = {};
 
 	const scheduler = new LoopScheduler({
 		dispatch: (job) => deliverTick(job),
@@ -199,6 +202,10 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			const ctx = lastCtx;
 			if (ctx) notify(ctx, `loop ${job.id} ran its final time: recurring jobs expire after ${maxAgeDays()} days`);
 		},
+		onDispatchError: (job, error) => {
+			const ctx = lastCtx;
+			if (ctx) notify(ctx, `loop ${job.id}: this tick could not be delivered and was skipped (${error.message})`, "warning");
+		},
 		onScan: (now) => {
 			durable?.maintain(now);
 			// The countdown is coarse, so this is a string compare most seconds.
@@ -417,6 +424,27 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 	 */
 	const TICK_MESSAGE_TYPE = "pi-cc-loop-tick";
 
+	/**
+	 * The per-run rules, appended to the run as a hidden message instead of
+	 * being written into the system prompt. Providers that cannot carry a system
+	 * message mid-conversation get the leading system prompt rebuilt from every
+	 * change, so a rule that comes and goes with each tick would invalidate the
+	 * whole cached prefix on the way into the run and again on the way out.
+	 * Claude Code does the same: its /loop instructions are part of the message.
+	 */
+	const RULES_MESSAGE_TYPE = "pi-cc-loop-rules";
+
+	function rulesFor(guidelines: string[]) {
+		if (!guidelines.length) return undefined;
+		return {
+			message: {
+				customType: RULES_MESSAGE_TYPE,
+				content: [RULES_PROVENANCE, ...guidelines].join("\n\n"),
+				display: false,
+			},
+		};
+	}
+
 	/** The text the model gets for a prompt: the loop.md sentinel expands at fire time. */
 	function resolvePrompt(prompt: string, mode: TickMode): string {
 		return isLoopFileSentinel(prompt) ? loopFile.resolve(lastCtx?.cwd ?? process.cwd(), mode) : prompt;
@@ -429,8 +457,6 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 	 */
 	function deliverTick(job: LoopJob): void {
 		const tick = Math.max(tickCounters.get(job.prompt) ?? 0, job.tickCount ?? 0) + 1;
-		tickCounters.set(job.prompt, tick);
-		job.tickCount = tick;
 		const body = resolvePrompt(job.prompt, job.kind === "cron" ? "cron" : "wakeup");
 		// A fixed-interval tick is what it is - a scheduled task - and a
 		// self-paced tick keeps the loop framing. The rules for the run are
@@ -455,6 +481,10 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			// only recorded and nothing ever happens.
 			{ deliverAs: "followUp", triggerTurn: true },
 		);
+		// Counted only once the message is in: a throw here means the tick never
+		// happened, so it must not use up a number.
+		tickCounters.set(job.prompt, tick);
+		job.tickCount = tick;
 
 		if (job.maxFires !== undefined && (job.fireCount ?? 0) >= job.maxFires) {
 			const ctx = lastCtx;
@@ -471,7 +501,6 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		}
 	}
 
-	/** The tool names to exclude from pi-cc-extensions' global styling. */
 	/**
 	 * A run finished without an abort: self-paced chains whose tick the model
 	 * did not reschedule get their one keepalive, or end.
@@ -546,7 +575,8 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 				case "statusline": {
 					const arg = (rest[0] ?? "").toLowerCase();
 					if (!arg) {
-						notify(ctx, `Usage: /loop footer on|off (currently ${loadConfig().footer ? "on" : "off"})`, "info");
+						const current = `${loadConfig().footer ? "on" : "off"}${overrideNote("footer")}`;
+						notify(ctx, `Usage: /loop footer on|off (currently ${current})`, "info");
 						return;
 					}
 					setSetting(ctx, "footer", arg);
@@ -556,7 +586,7 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 				case "config": {
 					const [key, value] = rest;
 					if (!key) {
-						showSettings(ctx);
+						if (!(await openSettingsPanel(ctx))) showSettings(ctx);
 						return;
 					}
 					const name = key.toLowerCase();
@@ -585,13 +615,35 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			// drives cron_create / cron_list / cron_delete / schedule_wakeup itself.
 			// The per-run rules travel with the run through before_agent_start.
 			const text = raw ? `/loop ${raw}` : "/loop";
-			queueRun({ content: text, guidelines: [loopCommandGuidelines(raw)] });
-			// Pi runs an extension command even while a turn is streaming, and its
-			// sendUserMessage throws unless a lane is named: "Agent is already
-			// processing. Specify streamingBehavior". `followUp` is that lane - the
-			// request waits for the current turn to end, which is where a /loop
-			// belongs anyway. When idle the option is ignored and the turn starts.
-			pi.sendUserMessage(text, { expandPromptTemplates: false, deliverAs: "followUp" });
+			const guidelines = [loopCommandGuidelines(raw)];
+			const send = () => {
+				// The user asking for this loop again is a new loop: the mark that
+				// keeps a late schedule_wakeup from reviving a stopped chain must
+				// not block it.
+				stoppedPrompts.delete(normalizePrompt(raw) || LOOP_FILE_SENTINEL);
+				queueRun({ content: text, guidelines });
+				try {
+					pi.sendUserMessage(text, { expandPromptTemplates: false, deliverAs: "followUp" });
+				} catch {
+					// The session was replaced while this request waited.
+				}
+			};
+
+			// A run that is already streaming has passed before_agent_start, so
+			// sending now would split the request in two: the text would be queued
+			// into that run without its rules, and the model would work through it
+			// twice. Wait for the run to end and start a clean one instead - the
+			// same wait a follow-up lane would impose, without losing the rules.
+			if (!ctx.isIdle() && typeof ctx.waitForIdle === "function") {
+				notify(ctx, `${text} will start when the current turn ends`, "info");
+				void ctx.waitForIdle().then(send, () => {});
+				return;
+			}
+			// The followUp lane is the fallback for a Pi without waitForIdle: a
+			// sendUserMessage from a streaming turn throws without one ("Agent is
+			// already processing. Specify streamingBehavior"). When idle the option
+			// is ignored and the turn starts.
+			send();
 		},
 	});
 
@@ -601,7 +653,7 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			"/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              settings panel (a summary outside the TUI)",
 			"/loop settings messages on|off   compact two-line markers",
 			"/loop settings footer on|off     the one-line footer summary",
 			"",
@@ -612,12 +664,46 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		notify(ctx, help, "info");
 	}
 
+	/** ` (PI_CC_FOOTER=0)` when an environment variable decides the setting. */
+	function overrideNote(key: keyof PiCcConfig): string {
+		const override = envOverride(key);
+		return override ? ` (${override})` : "";
+	}
+
+	/**
+	 * A bare /loop settings 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): 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) => {
+					applySetting(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;
+	}
+
 	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"}`,
+			`  messages:  ${config.compactMessages ? "compact" : "card"}${overrideNote("compactMessages")}`,
+			`  footer:    ${config.footer ? "summary" : "hidden"}${overrideNote("footer")}`,
 			"",
 			"Usage: /loop settings messages on|off",
 			"       /loop settings footer on|off",
@@ -633,15 +719,29 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			showSettings(ctx);
 			return;
 		}
-		const patch: Partial<PiCcConfig> = key === "messages" ? { compactMessages: on } : { footer: on };
+		const field: keyof PiCcConfig = key === "messages" ? "compactMessages" : "footer";
+		const next = applySetting(field, on);
+		const label = key === "messages" ? "Compact message style" : "Footer summary";
+		const override = envOverride(field);
+		if (override && next[field] !== on) {
+			// The file has the choice, but the variable decides while it is set.
+			notify(ctx, `${label} saved as ${on ? "on" : "off"}, but ${override} overrides it while set`, "warning");
+		} else {
+			notify(ctx, `${label} ${on ? "enabled" : "disabled"}`, "info");
+		}
+	}
+
+	/** Save one setting, tell the other pi-cc packages, and repaint the footer. Returns the settings in effect. */
+	function applySetting(field: keyof PiCcConfig, on: boolean): PiCcConfig {
+		const patch: Partial<PiCcConfig> = field === "compactMessages" ? { 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();
+		if (field === "footer") refreshStatus();
+		return next;
 	}
 
 	// ------------------------------------------------------------------ tools
@@ -725,6 +825,8 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 				lines.push(`Recurring jobs auto-expire after ${maxAgeDays()} days: the job runs one final time, then it is deleted.`);
 			}
 			lines.push(`Cancel it with cron_delete { "id": "${job.id}" }.`);
+			// Asked for in plain words, not through /loop: do it once now, as /loop would.
+			if (recurring && !currentRun.loopRequest && !currentRun.cronId && !currentRun.chainId) lines.push(RUN_NOW_HINT);
 
 			return {
 				content: [{ type: "text", text: lines.join("\n") }],
@@ -991,11 +1093,8 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		if (event.messageType === "user") {
 			const queued = takeQueuedRun(event.prompt);
 			if (!queued) return;
-			currentRun = { chainId: queued.chainId, cronId: queued.cronId, tick: queued.tick };
-			if (!queued.guidelines.length) return;
-			const options = event.systemPromptOptions;
-			options.promptGuidelines = [...(options.promptGuidelines ?? []), ...queued.guidelines];
-			return;
+			currentRun = { chainId: queued.chainId, cronId: queued.cronId, tick: queued.tick, loopRequest: true };
+			return rulesFor(queued.guidelines);
 		}
 		if (event.messageType !== "custom") return;
 
@@ -1011,21 +1110,16 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 				cronId: details.kind === "cron" ? details.jobId : undefined,
 				tick: details.tickCount,
 			};
-			const guidelines =
-				details.kind === "cron" && details.jobId
-					? [cronTickGuidelines(details.jobId, humanSchedule(details.cron ?? "* * * * *"))]
-					: [];
-			if (details.kind === "wakeup") {
-				const chain = details.jobId ? scheduler.get(details.jobId) : undefined;
-				if (chain) {
-					guidelines.push(loopGuidelines(chain.prompt));
-					if (monitorToolAvailable()) guidelines.push(monitorGuidelines(chain.prompt));
-				}
-			}
-			if (!guidelines.length) return;
-			const options = event.systemPromptOptions;
-			options.promptGuidelines = [...(options.promptGuidelines ?? []), ...guidelines];
-			return;
+			// A cron fire needs nothing beyond its envelope ("it fires the next tick
+			// on its own, so do not call schedule_wakeup; to cancel it, call
+			// cron_delete"): an extra message every minute would only grow the
+			// context. A self-paced tick carries the rules that keep the loop alive.
+			if (details.kind !== "wakeup") return;
+			const chain = details.jobId ? scheduler.get(details.jobId) : undefined;
+			if (!chain) return;
+			const guidelines = [loopGuidelines(chain.prompt)];
+			if (monitorToolAvailable()) guidelines.push(monitorGuidelines(chain.prompt));
+			return rulesFor(guidelines);
 		}
 
 		if (event.message.customType === MONITOR_EVENT_TYPE) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cc-loop",
-	"version": "0.3.0",
+	"version": "0.5.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/prompts.ts

@@ -33,7 +33,10 @@ export const PROVENANCE = "[loop tick #{n} \u00b7 scheduled by /loop, not typed
  * it "loop" here is what made the model try to reschedule.
  */
 export const SCHEDULED_TASK_PROVENANCE =
-	"[scheduled task {id} \u00b7 {schedule} \u00b7 started by the schedule, not typed by the user; it fires the next tick on its own, so do not call schedule_wakeup]";
+	"[scheduled task {id} \u00b7 {schedule} \u00b7 started by the schedule, not typed by the user; it fires the next tick on its own, so do not call schedule_wakeup; to cancel it, call cron_delete with id {id}]";
+
+/** The first line of the hidden rules message a /loop request or a self-paced tick carries. */
+export const RULES_PROVENANCE = "[/loop instructions for this run \u00b7 added by pi-cc-loop, not typed by the user]";
 
 const DELAY_ADVICE = [
 	"- Pick the delay from what you are waiting for. For idle ticks with nothing specific to watch, use 1200-1800s.",
@@ -103,18 +106,6 @@ const LOOP_GUIDELINES = [
 	"  with `stop: true` instead and say why.",
 ].join("\n");
 
-/**
- * Fixed-interval loops fire their own next tick, so a wakeup scheduled from
- * one would run the same prompt twice. Claude Code's tick says the same:
- * "The recurring cron will fire the next tick automatically — do not call
- * ScheduleWakeup from this tick."
- */
-const CRON_TICK_GUIDELINES = [
-	"This is a fixed-interval /loop (job {id}, {schedule}): the schedule fires the next tick on its own.",
-	"Do not call `schedule_wakeup` from this tick — it would run this prompt a second time on a self-paced",
-	"schedule. To cancel the loop, call `cron_delete` with id {id}.",
-].join("\n");
-
 /**
  * How a self-paced loop uses the Monitor tool, after Claude Code's /loop
  * skill: arm a monitor only when the next iteration waits on an event, arm it
@@ -176,10 +167,6 @@ export function loopGuidelines(prompt: string): string {
 	return fill(LOOP_GUIDELINES, { prompt: describePrompt(prompt), quoted: quote(prompt) });
 }
 
-export function cronTickGuidelines(id: string, schedule: string): string {
-	return fill(CRON_TICK_GUIDELINES, { id, schedule });
-}
-
 export function monitorGuidelines(prompt: string): string {
 	return fill(MONITOR_GUIDELINES, { quoted: quote(prompt) });
 }
@@ -230,6 +217,19 @@ Jobs only fire while the agent is idle (not mid-turn). The scheduler shifts each
 Recurring jobs auto-expire after 7 days \u2014 they fire one final time, then are deleted. Tell the user about the 7-day limit when scheduling recurring jobs.
 Returns a job ID you can pass to cron_delete.`;
 
+/**
+ * Appended to the result of a recurring `cron_create` in a plain turn (not a
+ * /loop request, not a scheduled tick). Claude Code's /loop skill says "Then
+ * immediately run it now ... Don't wait for the first cron fire", and its model
+ * reaches that skill for "every 5 minutes ..." typed without /loop: the skill is
+ * listed every turn and CronCreate is a deferred tool. Pi has no deferred tools,
+ * so the model calls cron_create directly and the result says it instead. A
+ * tool result is appended at the end of the transcript; the cache is untouched.
+ */
+export const RUN_NOW_HINT =
+	'If the user asked for this to repeat on an interval ("every 5 minutes"), do the task once now as well \u2014 ' +
+	'don\'t wait for the first fire, as /loop does. A job at set times ("every day at 9am") only runs at those times.';
+
 export const CRON_DELETE_DESCRIPTION =
 	"Cancel a job scheduled with cron_create, or end a self-paced /loop, by its id. Removes it from .pi/scheduled_tasks.json (durable jobs) or from this session (session-only jobs).";
 

package/renderers.ts

@@ -67,7 +67,9 @@ export function renderScheduledMessage(message: any, options: any, theme: Theme)
 				: "\u273b loop";
 
 	if (!loadConfig().compactMessages) {
-		const header = details.missed ? label : `loop tick #${details.tickCount ?? "?"} \u00b7 ${displayPrompt(prompt)}`;
+		// Same naming as the block: a cron fire is a scheduled task, only a
+		// self-paced tick is a loop.
+		const header = details.missed ? label : `${label.replace("\u273b ", "")} \u00b7 ${displayPrompt(prompt)}`;
 		return renderCard({ header, body: prompt, expanded: options.expanded, outputPad: options.outputPad, theme });
 	}
 

package/schedule.ts

@@ -159,6 +159,8 @@ export interface SchedulerHooks {
 	onExpire?: (job: LoopJob) => void;
 	/** Runs at the start of every scan (housekeeping such as durable jobs). */
 	onScan?: (now: number) => void;
+	/** A delivery threw (Pi's API is stale once the session is replaced); the tick is dropped. */
+	onDispatchError?: (job: LoopJob, error: Error) => void;
 }
 
 /** Claude Code checks for due tasks once a second. */
@@ -277,7 +279,12 @@ export class LoopScheduler {
 
 	/** Run one scan: housekeeping, mark due jobs pending, dispatch the oldest when idle. */
 	tick(now = Date.now()): void {
-		this.hooks.onScan?.(now);
+		try {
+			this.hooks.onScan?.(now);
+		} catch {
+			// Housekeeping (the durable file, the footer) is best effort. This runs
+			// from a timer, where an exception would take Pi down with it.
+		}
 		this.markDue(now);
 		this.tryDispatch(now);
 	}
@@ -336,7 +343,14 @@ export class LoopScheduler {
 			finished = next === null;
 		}
 
-		this.hooks.dispatch(job);
+		try {
+			this.hooks.dispatch(job);
+		} catch (error) {
+			// Dropped, like any tick that fails to start; the job keeps its next
+			// run. Not rethrown: this runs from a timer, where an exception would
+			// take Pi down with it.
+			this.hooks.onDispatchError?.(job, error instanceof Error ? error : new Error(String(error)));
+		}
 		if (finished) this.jobs.delete(job.id);
 		this.hooks.afterDispatch?.(job, finished);
 		if (expired) this.hooks.onExpire?.(job);

package/settings-panel.ts

@@ -0,0 +1,135 @@
+/**
+ * The /loop settings panel: the same kind of screen as Pi's /settings.
+ *
+ * Pi's /settings cannot take items from an extension (its panel is a fixed
+ * list, and the command is handled before extension commands), so the shared
+ * pi-cc settings get their own panel, 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.
+ */
+
+import { DynamicBorder } 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 { envOverride, loadConfig, type PiCcConfig } from "./config.ts";
+
+/** 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.",
+	},
+];
+
+/**
+ * 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),
+	};
+}