pi-cc-loop 0.7.6 → 0.7.8

package/README.md

@@ -60,6 +60,15 @@ ln -sfn "$PWD" ~/.pi/agent/extensions/pi-cc-loop
 
 可以在请求里加 `--durable`（写入 `.pi/scheduled_tasks.json`，重启后继续）和 `--max N`（触发 N 次后自动删除）。
 
+### 持久任务与子代理
+
+同一项目的持久任务只由一个调度器实例执行。锁用 PID、主机名和每个实例独有的令牌识别归属，
+所以主会话与 subagent 即使在同一个 Pi 进程里，也不会同时接管同一批任务；其他会话仍能添加、查看或取消任务。
+派发持久任务前会重新核验并续期锁，失去归属的实例停止执行已载入的持久任务，不影响它的会话级任务。
+
+`/reload` 先由旧实例释放锁，新实例再获取；持锁进程退出或心跳超过 60 秒未更新时，其他实例可以接管。
+旧实例不会续写或删除新实例的锁。旧版没有实例令牌的锁仍被尊重，释放或过期后才换成新版格式；任务文件无需迁移。
+
 ## 工具
 
 | 工具 | 界面显示 | 说明 |
@@ -69,7 +78,9 @@ ln -sfn "$PWD" ~/.pi/agent/extensions/pi-cc-loop
 | `cron_list` | `CronList` | 列出任务和实际的下次运行时间（已含错峰） |
 | `schedule_wakeup` | `ScheduleWakeup` | 自定步调：`delaySeconds`（限制在 60–3600）、`reason`（必填，显示在触发块表头）、`prompt`；`stop: true` 结束 |
 
-四个工具都声明了 `outputSchema`：开了 codemode 时，脚本里 `tools.cron_create(...)`、`tools.cron_list()` 拿到的是结构化结果（`{ id, nextFireAt, … }`、`{ jobs: [...] }`），一个脚本里就能列任务、按条件批量取消，不用从文本里抠 id。没开 codemode 时没有影响。
+四个工具都声明了 `outputSchema`。三个 cron 工具保持可从 codemode 调用：`tools.cron_create(...)`、`tools.cron_list()` 返回结构化结果（`{ id, nextFireAt, … }`、`{ jobs: [...] }`），可以在脚本中批量查询/取消。
+
+`schedule_wakeup` 是 **model-only 的回合控制工具**：仍直接向模型声明，但不能通过 codemode 或其他工具间接调用。新建/续期必须是当前 assistant 响应中的唯一工具调用；先完成 Monitor 等操作并向用户更新，再单独调用。运行时无法确认独立调用、或发现同批有其他调用时，会拒绝且不创建/修改 wakeup。`stop: true` 不强制结束回合，仍可向用户说明停止结果；固定 cron tick 的重复 wakeup 仍保持无操作。
 
 ## 渲染
 
@@ -197,7 +208,7 @@ node scripts/cache-check.mjs    # 真实 provider 的缓存检查，默认用免
 
 - Esc 只取消被打断回合所属的自定步调 loop；CC 按 Esc（包括空闲时、打断无关回合时）会取消所有自定步调 loop。其他情况用 `/loop stop`。
 - 固定间隔的触发里调用 `schedule_wakeup` 会被当作空操作并返回说明，防止同一个任务又被自定步调重复调度；CC 没有这条硬规则。
-- 不带 `/loop` 的请求（比如"每分钟打印一次hello"）也会在建好任务后立即做一次。CC 靠模型自己调用 loop 技能做到（`CronCreate` 在 CC 里是延迟加载的工具，模型会先走技能）；Pi 没有延迟加载工具，这里改为在 `cron_create` 的结果里加一句提示，只在普通对话里建周期任务时出现。
+- 不带 `/loop` 的请求（比如"每分钟打印一次hello"）也会在建好任务后立即做一次。CC 靠模型自己调用 loop 技能做到（`CronCreate` 在 CC 里是延迟加载的工具，模型会先走技能）；本包默认直接声明 cron 工具，这里改为在 `cron_create` 的结果里加一句提示，只在普通对话里建周期任务时出现。
 - 底部摘要和 `maxFires` 次数上限是额外加的；CC 主会话不显示 loop 状态，也没有次数上限。
 - 自定步调 loop 结束（stop、Esc、`cron_delete`、兜底心跳用完）时，绑定的 Monitor 会被静默停止；CC 靠模型自己调用 `TaskStop`。
 - Monitor 事件不会取消待触发的 wakeup，它始终是兜底心跳（与 CC 一致）。

package/durable.ts

@@ -16,7 +16,8 @@
  *   - The session holding the lock runs the durable jobs and picks up jobs
  *     other sessions add or remove. The lock carries a heartbeat; a lock whose
  *     heartbeat is older than a minute (or whose process is gone) is stale and
- *     can be taken over.
+ *     can be taken over. A PID identifies a process, not a session: main and
+ *     subagent sessions in that process each get their own ownership token.
  *   - The runtime files are added to `.git/info/exclude`.
  */
 
@@ -132,6 +133,8 @@ export class DurableStore {
 interface LockInfo {
 	pid: number;
 	hostname: string;
+	/** Absent on legacy locks, which remain valid until released or stale. */
+	ownerToken?: string;
 	acquiredAt: number;
 	heartbeatAt: number;
 }
@@ -159,6 +162,7 @@ export class SchedulerLock {
 	owned = false;
 	private readonly pid: number;
 	private readonly hostname: string;
+	private readonly ownerToken = randomUUID();
 	private readonly isAlive: (pid: number) => boolean;
 	private readonly staleMs: number;
 
@@ -184,57 +188,76 @@ export class SchedulerLock {
 		return info.hostname === this.hostname && !this.isAlive(info.pid);
 	}
 
+	private matches(info: LockInfo | null): boolean {
+		return info?.pid === this.pid && info.hostname === this.hostname && info.ownerToken === this.ownerToken;
+	}
+
+	/** Check the file, not only the instance's last acquisition result. */
+	owns(): boolean {
+		if (this.owned && !this.matches(this.holder())) this.owned = false;
+		return this.owned;
+	}
+
+	/** Serialize takeovers, heartbeats and releases across processes too. */
+	private guarded<T>(action: () => T): T {
+		fs.mkdirSync(path.dirname(this.file), { recursive: true });
+		return withFileLock(this.file, action);
+	}
+
 	tryAcquire(now = Date.now()): boolean {
-		if (this.owned) return true;
-		for (let attempt = 0; attempt < 2; attempt++) {
-			try {
-				fs.mkdirSync(path.dirname(this.file), { recursive: true });
+		try {
+			return this.guarded(() => {
+				const held = this.holder();
+				if (this.matches(held)) return (this.owned = true);
+				this.owned = false;
+				// /reload releases the old instance first. Sharing its PID does not
+				// let a concurrent child session steal its still-live lock.
+				if (held && !this.isStale(held, now)) return false;
+				fs.rmSync(this.file, { force: true });
 				const fd = fs.openSync(this.file, "wx");
-				const info: LockInfo = { pid: this.pid, hostname: this.hostname, acquiredAt: now, heartbeatAt: now };
-				fs.writeSync(fd, `${JSON.stringify(info)}\n`);
-				fs.closeSync(fd);
-				this.owned = true;
-				return true;
-			} catch (error) {
-				if ((error as NodeJS.ErrnoException).code !== "EEXIST") return false;
-				const info = this.holder();
-				// The same process after /reload, a dead process, or a missed heartbeat.
-				const takeOver = !info || info.pid === this.pid || this.isStale(info, now);
-				if (!takeOver) return false;
 				try {
-					fs.rmSync(this.file, { force: true });
-				} catch {
-					return false;
+					const info: LockInfo = { pid: this.pid, hostname: this.hostname, ownerToken: this.ownerToken, acquiredAt: now, heartbeatAt: now };
+					fs.writeSync(fd, `${JSON.stringify(info)}\n`);
+				} finally {
+					fs.closeSync(fd);
 				}
-			}
+				return (this.owned = true);
+			});
+		} catch {
+			this.owned = false;
+			return false;
 		}
-		return false;
 	}
 
-	heartbeat(now = Date.now()): void {
-		if (!this.owned) return;
-		const info = this.holder();
-		if (!info || info.pid !== this.pid) {
-			// Someone took the lock over (we were considered stale).
-			this.owned = false;
-			return;
-		}
+	/** Renew only our own lease; a failed renewal must not permit dispatch. */
+	heartbeat(now = Date.now()): boolean {
+		if (!this.owned) return false;
 		try {
-			writeAtomic(this.file, `${JSON.stringify({ ...info, heartbeatAt: now })}\n`);
+			return this.guarded(() => {
+				const info = this.holder();
+				if (!this.matches(info)) {
+					this.owned = false;
+					return false;
+				}
+				writeAtomic(this.file, `${JSON.stringify({ ...info, heartbeatAt: now })}\n`);
+				return true;
+			});
 		} catch {
-			// a missed heartbeat only matters after a minute
+			this.owned = false;
+			return false;
 		}
 	}
 
 	release(): void {
 		if (!this.owned) return;
-		this.owned = false;
-		if (this.holder()?.pid === this.pid) {
-			try {
-				fs.rmSync(this.file, { force: true });
-			} catch {
-				// a stale lock is taken over after a minute anyway
-			}
+		try {
+			this.guarded(() => {
+				if (this.matches(this.holder())) fs.rmSync(this.file, { force: true });
+			});
+		} catch {
+			// a stale lock is taken over after a minute anyway
+		} finally {
+			this.owned = false;
 		}
 	}
 }
@@ -272,7 +295,7 @@ export function ensureGitExclude(cwd: string): void {
 		const file = path.join(common, "info", "exclude");
 		const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
 		const lines = current.split("\n").map((line) => line.trim());
-		const wanted = ["**/.pi/scheduled_tasks.json", "**/.pi/scheduled_tasks.lock", "**/.pi/scheduled_tasks.json.write.lock"];
+		const wanted = ["**/.pi/scheduled_tasks.json", "**/.pi/scheduled_tasks.lock", "**/.pi/scheduled_tasks.json.write.lock", "**/.pi/scheduled_tasks.lock.write.lock"];
 		const missing = wanted.filter((entry) => !lines.includes(entry));
 		if (!missing.length) return;
 		fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -316,7 +339,15 @@ export class DurableRuntime {
 	}
 
 	get owner(): boolean {
-		return this.lock.owned;
+		return this.lock.owns();
+	}
+
+	/** Revalidate and renew immediately before a durable fire, even when sync is throttled. */
+	canDispatch(): boolean {
+		this.lastHeartbeat = Date.now();
+		if (this.lock.heartbeat(this.lastHeartbeat)) return true;
+		this.dropLoadedJobs();
+		return false;
 	}
 
 	holderPid(): number | undefined {
@@ -341,6 +372,7 @@ export class DurableRuntime {
 		this.lastMaintenance = now;
 		this.store.assertWritable();
 		if (!this.owner) {
+			this.dropLoadedJobs();
 			if (this.store.exists()) this.acquireAndLoad(now);
 			return;
 		}
@@ -383,6 +415,10 @@ export class DurableRuntime {
 
 	/** Record a fire: update the job in the file, or remove it after its last run. */
 	afterFire(job: LoopJob, finished: boolean): void {
+		if (!this.owner) {
+			this.dropLoadedJobs();
+			return;
+		}
 		try {
 			if (finished) this.store.remove(job.id);
 			else this.store.upsert(job);

package/index.ts

@@ -143,6 +143,22 @@ function normalizePrompt(prompt: string): string {
 	return prompt.trim().replace(/^\/loop\s+/i, "").trim();
 }
 
+/** Pi only terminates a batch when every call agrees; never arm from a mixed or nested call. */
+function requireStandaloneWakeup(toolCallId: string, ctx: Pick<ExtensionContext, "sessionManager">): void {
+	const branch = ctx.sessionManager.getBranch?.() ?? [];
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+		const calls = entry.message.content.filter((block) => block.type === "toolCall");
+		if (calls.length === 1 && calls[0].id === toolCallId && calls[0].name === "schedule_wakeup") return;
+		break;
+	}
+	throw new Error(
+		"No wakeup was scheduled: schedule_wakeup must be called directly as the only tool call in its assistant response, " +
+			"not through codemode or in a batch. Finish other tools and write your update first, then call it alone.",
+	);
+}
+
 /** A stored job as a codemode script sees it: every field, minus those holding no value (the value is JSON). */
 function jobValue(job: LoopJob): Record<string, string | number | boolean> {
 	return Object.fromEntries(Object.entries(storedJob(job)).filter(([, value]) => value !== undefined)) as Record<
@@ -194,11 +210,12 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			persist(jobs);
 			refreshStatus(jobs);
 		},
-		canDispatch: () => {
+		canDispatch: (job) => {
 			const ctx = lastCtx;
 			if (!ctx) return false;
 			try {
-				return ctx.isIdle() && !ctx.hasPendingMessages();
+				if (!ctx.isIdle() || ctx.hasPendingMessages()) return false;
+				return !job.durable || durable?.canDispatch() === true;
 			} catch {
 				return false;
 			}
@@ -865,6 +882,8 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "schedule_wakeup",
 		label: "ScheduleWakeup",
+		// A turn-control tool: codemode cannot propagate its terminate flag.
+		exposure: "model-only",
 		description: SCHEDULE_WAKEUP_DESCRIPTION,
 		promptSnippet: SCHEDULE_WAKEUP_SNIPPET,
 		parameters: Type.Object({
@@ -960,6 +979,9 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 				};
 			}
 
+			// Check the finalized assistant batch before changing any chain or timer.
+			requireStandaloneWakeup(_toolCallId, ctx);
+
 			// Claude Code rounds and clamps; only a change after rounding counts as clamped.
 			const requested = params.delaySeconds;
 			const rounded = Number.isFinite(requested) ? Math.round(requested) : requested > 0 ? MAX_DELAY_SECONDS : MIN_DELAY_SECONDS;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cc-loop",
-	"version": "0.7.6",
+	"version": "0.7.8",
 	"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

@@ -69,10 +69,10 @@ const LOOP_COMMAND_GUIDELINES = [
 	"4. Never call `schedule_wakeup` for this loop: the cron fires its own ticks. Scheduling one would run the task twice.",
 	"",
 	"## Self-paced (no interval)",
-	"1. Do the task now, then write your update for the user.",
-	"2. Then call `schedule_wakeup` with `delaySeconds` (60-3600), a one-sentence `reason`, and `prompt` set to the same `/loop` input verbatim ({quoted}). The turn ends as soon as it returns, so call it last.",
+	"1. Do the task now.",
+	"2. If the next iteration waits on an external event and no monitor is running for it, arm `Monitor` once with `loopPrompt` set to {quoted}; keep `delaySeconds` at 1200-1800 as the fallback heartbeat.",
+	"3. Write your update for the user, then call `schedule_wakeup` directly with `delaySeconds` (60-3600), a one-sentence `reason`, and `prompt` set to the same `/loop` input verbatim ({quoted}). It must be the only tool call in that assistant response, not through codemode or in a batch. The turn ends as soon as it returns, so call it last.",
 	"{delayAdvice}",
-	"3. If the next iteration waits on an external event and no monitor is running for it, arm `Monitor` once with `loopPrompt` set to {quoted}; keep `delaySeconds` at 1200-1800 as the fallback heartbeat.",
 	"4. If the task is complete or cannot progress without the user, call `schedule_wakeup` with `stop: true` and say why.",
 	"",
 	"## status and stop",
@@ -94,6 +94,8 @@ const LOOP_GUIDELINES = [
 	"- To continue, call the `schedule_wakeup` tool with `delaySeconds` (60-3600), a one-sentence `reason`,",
 	"  and `prompt` set to the same /loop prompt verbatim: {quoted}",
 	"- Write your update for the user before you call `schedule_wakeup`: the turn ends as soon as it returns.",
+	"- Call it directly as the only tool call in that assistant response, never through codemode or in a batch.",
+	"  Finish any Monitor or other tool calls in earlier responses, before this final wakeup call.",
 	DELAY_ADVICE,
 	"- If the task is complete, or the loop cannot move further without the user, call `schedule_wakeup`",
 	"  with `stop: true` instead and say why.",
@@ -112,7 +114,7 @@ const MONITOR_GUIDELINES = [
 	"this step while a monitor for it is still running.",
 	"While a monitor is armed, keep `delaySeconds` at 1200-1800: the monitor is the wake signal and the",
 	"`schedule_wakeup` delay is only the fallback heartbeat. When a monitor event wakes you, handle the event,",
-	"then decide whether the loop continues.",
+	"then decide whether the loop continues. Finish monitor calls before the final, standalone `schedule_wakeup` call.",
 ].join("\n");
 
 /**
@@ -215,8 +217,8 @@ Returns a job ID you can pass to cron_delete.`;
  * /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
+ * listed every turn and CronCreate is a deferred tool. This package exposes
+ * cron_create directly, so its result supplies that guidance instead. A
  * tool result is appended at the end of the transcript; the cache is untouched.
  */
 export const RUN_NOW_HINT =
@@ -229,7 +231,7 @@ export const CRON_DELETE_DESCRIPTION =
 export const CRON_LIST_DESCRIPTION =
 	"List the scheduled jobs, both durable (.pi/scheduled_tasks.json) and session-only, with their ids, schedules, actual next run times and prompts.";
 
-export const SCHEDULE_WAKEUP_DESCRIPTION = `Schedule when to resume work in a self-paced /loop \u2014 the user invoked /loop without an interval, asking you to self-pace iterations of a task. Call it as the last thing in the turn to keep the loop alive: the turn ends as soon as it returns, so write your update for the user first. To end the loop, call it with stop: true (omit every other field).
+export const SCHEDULE_WAKEUP_DESCRIPTION = `Schedule when to resume work in a self-paced /loop \u2014 the user invoked /loop without an interval, asking you to self-pace iterations of a task. Call it as the last thing in the turn to keep the loop alive: the turn ends as soon as it returns, so write your update for the user first. Call it directly as the only tool call in that assistant response, never through codemode or in a batch. Finish Monitor and other tools in earlier responses; unsafe arm calls are rejected without scheduling. To end the loop, call it with stop: true (omit every other field); stopping does not force the turn to end, so explain the outcome afterward.
 
 Pass the same /loop prompt back via \`prompt\` each turn so the next firing repeats the task. For a bare /loop (no prompt), pass the literal sentinel "${LOOP_FILE_SENTINEL}": it expands at fire time to the current loop.md tasks, or to the built-in maintenance pass when there is no loop.md.
 

package/schedule.ts

@@ -149,8 +149,8 @@ export interface SchedulerHooks {
 	afterDispatch?: (job: LoopJob, finished: boolean) => void;
 	/** Called whenever the job set changes, so state can be persisted. */
 	onChange?: (jobs: LoopJob[]) => void;
-	/** True when the agent is idle and has nothing queued: a tick may go out. */
-	canDispatch?: () => boolean;
+	/** True when idle and this job may fire (durable jobs also need their live lock). */
+	canDispatch?: (job: LoopJob) => boolean;
 	/** The offsets to apply to run times. */
 	timing?: () => TimingConfig;
 	/** Max age of a recurring job in ms; 0 disables the limit. */
@@ -321,7 +321,7 @@ export class LoopScheduler {
 			.filter((candidate) => candidate.pending)
 			.sort((a, b) => (a.dueAt ?? 0) - (b.dueAt ?? 0))[0];
 		if (!job) return;
-		if (this.hooks.canDispatch && !this.hooks.canDispatch()) return;
+		if (this.hooks.canDispatch && !this.hooks.canDispatch(job)) return;
 
 		job.pending = false;
 		job.dueAt = undefined;