pi-cc-loop 0.3.0 → 0.4.0

package/README.md

@@ -1,59 +1,102 @@
 # 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 ...` |
+| 界面设置 | 本地命令，不进对话 | `/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 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/agent/pi-cc.json`，文件不存在时用默认值：
+
+```jsonc
+{
+  "compactMessages": true,   // 触发块和 Monitor 事件用上面的样式；false 为旧的带底色卡片
+  "footer": true             // 底部摘要：loop 的一行和 Monitor 的 `monitor N`
+}
+```
+
+用 `/loop settings messages on|off`、`/loop settings footer on|off`（或 `/loop footer on|off`）切换，两个扩展同时生效。
+
 ## 底部摘要
 
 `ctx.ui.setStatus("loop", …)` 是 Pi 核心 API，不依赖任何其他扩展：
@@ -68,42 +111,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` | 设置文件路径 |
 
 ## 兼容性
 
 - 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/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

@@ -44,12 +44,13 @@ 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,
@@ -171,9 +172,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 +201,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 +423,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 +456,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 +480,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 +500,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.
@@ -585,13 +613,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();
 		},
 	});
 
@@ -725,6 +775,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 +1043,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 +1060,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.4.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);