@alphacoder-v0/pi-loops 0.22.7 → 0.24.0

package/src/tools.ts

@@ -5,6 +5,7 @@
  * in-process sub-session (hop 1, passed as customTools) and the headless host (hop 1, no UI).
  */
 import { QUIET_MARK_AFTER, SIGNAL_WINDOW_MS, loopSignal } from "./job-signal.ts";
+import { formatWait, queuedPrompt, type QueuedPrompt } from "./engine.ts";
 import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -13,10 +14,14 @@ import { previewRedacted } from "./redact.ts";
 import { computeNext, formatLocal, formatSchedule, parseSchedule, stamp } from "./schedule.ts";
 import type { LoopScheduler, SessionSnapshot } from "./scheduler.ts";
 import { MAX_PROMPT_BYTES, type LoopJob, newId, owningSessionId, resolveJobRef } from "./store.ts";
-import { asleepNote, ownerSession, runsIn } from "./job-owner.ts";
+import { asleepNote, ownerSession, runsSomewhere, whereRuns, type OwnerView } from "./job-owner.ts";
+import { inProject } from "./inbox.ts";
+import { plural } from "./job-lines.ts";
 import type { TriggerRuntime } from "./trigger-runtime.ts";
-import { sameProject, withinProject } from "./presence.ts";
-import { type TriggerStore, looksLikeFixedScheduleRequest, parseTriggerRule, resolveRuleRef, type DynamicTriggerRule } from "./triggers.ts";
+import { sameProject, withinProject } from "./paths.ts";
+import { type TriggerStore, cleanCondition, looksLikeFixedScheduleRequest, parseTriggerRule, resolveRuleRef, type DynamicTriggerRule } from "./triggers.ts";
+import { PI_BUILTIN_TOOL_NAMES } from "./mcp.ts";
+import { WATCH_ASK_MS, type WatchChoice, type WatchPlan, askTitle, planCard, watchChoice, watchOptions } from "./watch-plan.ts";
 
 export interface ControlPlaneRequest {
 	/** What is being approved, value-free. */
@@ -40,6 +45,14 @@ export interface ToolHost {
 	/** The confirmation gate; resolves to a denial text or undefined (allowed). */
 	confirmTool(ctx: ExtensionContext, req: ControlPlaneRequest, atHop: number): Promise<string | undefined>;
 	refreshBadge(): void;
+	/** Make sure the host is up now that there is a loop or a rule for it. Absent in the host itself. */
+	ensureHost?(): void;
+	/**
+	 * A turn pi-loops started in an open window for a scheduled job or a delivery: nobody may be
+	 * there, so `cron_create` and `new_trigger` do not wait on a person and keep the window guard's
+	 * gate (docs/design.md decision 24). Absent where no such turn runs.
+	 */
+	scheduledTurn?(): boolean;
 }
 
 export interface CreateJobInput {
@@ -63,6 +76,8 @@ export interface CreateJobInput {
 export interface JobScope {
 	parentSessionId?: string;
 	parentCwd?: string;
+	/** The loop belongs to its project, not a conversation: one made where no saved conversation is (recipe.ts installScope). */
+	projectOwned?: true;
 }
 
 /**
@@ -116,7 +131,17 @@ export function checkJobName(name: string | undefined, existing: LoopJob[]): voi
 }
 
 /** `/cron add` and `cron_create`: validate, fill the defaults, record who created it and where. */
-export async function createLoopJob(host: Pick<ToolHost, "scheduler" | "session">, input: CreateJobInput, scope?: JobScope): Promise<LoopJob> {
+/** The tools a job was asked for and does not have: built-ins the chat making it lacks. */
+export function toolsDropped(asked: readonly string[] | undefined, kept: readonly string[] | undefined): string[] {
+	return (asked ?? []).filter((t) => !(kept ?? []).includes(t));
+}
+
+/**
+ * Everything a job is refused for, with nothing written: the checks `createLoopJob` runs before it
+ * builds the job, in one place so a person is never asked about a job their yes cannot make.
+ * Returns the directory the job would run in.
+ */
+export function checkJobInput(input: Pick<CreateJobInput, "schedule" | "prompt" | "stateful" | "name" | "cwd">, existing: LoopJob[], session: Pick<SessionSnapshot, "sessionId" | "cwd">): string {
 	if (!input.prompt.trim()) throw new Error("cron action cannot be empty");
 	if (Buffer.byteLength(input.prompt, "utf8") > MAX_PROMPT_BYTES) throw new Error(`cron action exceeds ${MAX_PROMPT_BYTES} bytes`);
 	// An expression can parse and still never match ("0 0 30 2 *"): the job would go quiet with
@@ -126,20 +151,29 @@ export async function createLoopJob(host: Pick<ToolHost, "scheduler" | "session"
 	if (input.schedule.kind === "cron" && computeNext({ schedule: input.schedule, createdAt: Date.now() }, Date.now()) === undefined) {
 		throw new Error(`${formatSchedule(input.schedule)} has no next run`);
 	}
-	const existing = host.scheduler.store.load();
 	checkJobName(input.name, existing);
-	if (!input.stateful && !host.session().sessionId) throw new Error("a non-stateful cron job needs a persistent chat session to inject into (not --no-session, not the background host); use stateful=true");
+	if (!input.stateful && !session.sessionId) throw new Error("a non-stateful cron job needs a persistent chat session to inject into (not --no-session, not a background process); use stateful=true");
+	return resolveJobCwd(session.cwd, input.cwd);
+}
+
+export async function createLoopJob(host: Pick<ToolHost, "scheduler" | "session" | "ensureHost">, input: CreateJobInput, scope?: JobScope): Promise<LoopJob> {
+	const cwd = checkJobInput(input, host.scheduler.store.load(), host.session());
 	const job: LoopJob = {
 		id: newId("cron"),
 		name: input.name,
 		schedule: input.schedule,
 		stateful: input.stateful,
 		prompt: input.prompt,
-		cwd: resolveJobCwd(host.session().cwd, input.cwd),
-		// Captured now: the run happens in whichever pi owns the timer, and that one may be on another model.
-		model: input.model ?? host.session().model,
-		thinking: input.thinking ?? host.session().thinking,
-		tools: input.tools,
+		cwd,
+		// Captured now for a loop: it runs in the background, which may be on another model. A plain
+		// job runs in its conversation, on whatever model that conversation is on when it fires.
+		model: input.model ?? (input.stateful ? host.session().model : undefined),
+		thinking: input.thinking ?? (input.stateful ? host.session().thinking : undefined),
+		// Named tools may not add a built-in tool the chat (or the run) making it does not have. Trimmed,
+		// as 0.22 did, and said by the caller (`toolsDropped`): refusing would fail a recipe's install.
+		tools: input.tools && host.session().builtinTools ? input.tools.filter((t) => !PI_BUILTIN_TOOL_NAMES.includes(t) || host.session().builtinTools!.includes(t)) : input.tools,
+		// The loop's declared tools: those of the chat it is made in, unless it names its own.
+		builtinTools: input.tools ? undefined : host.session().builtinTools,
 		enabled: true,
 		verify: input.stateful && input.verify ? true : undefined,
 		checkerModel: input.stateful && input.verify ? input.checkerModel : undefined,
@@ -148,18 +182,57 @@ export async function createLoopJob(host: Pick<ToolHost, "scheduler" | "session"
 		recipe: input.recipe,
 		createdAt: stamp(),
 		// A sub-agent schedules on behalf of the session that runs it.
-		createdBy: { sessionId: scope?.parentSessionId ?? host.session().sessionId, cwd: scope?.parentCwd ?? host.session().cwd },
+		...(scope?.projectOwned ? { owner: "project" as const } : { createdBy: { sessionId: scope?.parentSessionId ?? host.session().sessionId, cwd: scope?.parentCwd ?? host.session().cwd } }),
 		sessionId: owningSessionId(input.stateful, host.session().sessionId, scope?.parentSessionId),
 		runCount: 0,
 		skippedOverlap: 0,
 	};
 	await host.scheduler.store.add(job);
+	if (job.stateful) host.ensureHost?.();
 	return job;
 }
 
 
 const deny = (text: string) => ({ content: [{ type: "text" as const, text }], isError: true, details: { id: undefined as string | undefined } });
 
+/** `cron_create` says it at hop 0, where a person's message can arrive: the page's Watch box sends `Watch for: <sentence>` as a chat message, and only the question the create tools ask may answer it. Said once: both tools are in the same list. */
+const WATCH_SENTENCE = " A message that starts with `Watch for:` comes from the page's Watch box: answer it with one of these two tools (new_trigger or cron_create); if it names no time and nothing to wait for, call neither, do nothing, and say it reads like something to do now. Never do the action of a `Watch for:` message yourself.";
+
+/** The create tools ask first: hop 0, a person present, and the person's own turn, on every surface pi has a dialog. */
+function asking(scope: ToolScope, host: ToolHost, ctx: ExtensionContext): boolean {
+	return scope.hop === 0 && ctx.hasUI && !host.scheduledTurn?.();
+}
+
+/** What the tool says when the person did not set the watch up: nothing exists, and the model is told not to do it some other way. */
+function notSetUp(reason: "Cancel" | "aborted" | "timed out") {
+	return {
+		content: [{ type: "text" as const, text: `cancelled: the person did not set up this watch (${reason}). Nothing was created. Do not do the action now and do not call this tool again for it.` }],
+		details: { id: undefined as string | undefined },
+	};
+}
+
+/**
+ * The question, through pi's own select: the card as its title, the fixed options, the tool's own
+ * abort signal and the thirty-minute timeout. pi answers `undefined` for Esc, an abort and the
+ * timeout alike; Esc is the person's Cancel. An answer that was not offered is a cancel too.
+ */
+async function askWatch(ctx: ExtensionContext, signal: AbortSignal | undefined, host: ToolHost, plan: WatchPlan): Promise<Extract<WatchChoice, { verdict: "set" }> | ReturnType<typeof notSetUp>> {
+	const options = watchOptions(plan);
+	const asked = Date.now();
+	const answer = await ctx.ui.select(askTitle(planCard(plan, { now: asked, pollSecs: host.triggers.pollIntervalSecs })), options, { signal, timeout: WATCH_ASK_MS });
+	const choice = watchChoice(answer !== undefined && options.includes(answer) ? answer : undefined);
+	if (choice.verdict === "set") return choice;
+	return notSetUp(signal?.aborted ? "aborted" : answer === undefined && Date.now() - asked >= WATCH_ASK_MS ? "timed out" : "Cancel");
+}
+
+/**
+ * What a create result adds while nothing runs in the background, so the model does not tell the person
+ * that a paused job will run. The same reason `cron_list` shows, and both ways to end it.
+ */
+function pausedLine(reason: string | undefined): string {
+	return reason ? `\nPAUSED: ${reason}. Nothing runs in the background until pi-loops starts again: /pi-loops start in pi, or pi-loops start in a shell.` : "";
+}
+
 /** Trigger rules, rendered for a tool result. */
 function renderTriggerRulesForTool(rules: ReturnType<TriggerStore["load"]>, host: Pick<ToolHost, "session">): string {
 	if (!rules.length) return "dynamic trigger rules: none";
@@ -167,15 +240,20 @@ function renderTriggerRulesForTool(rules: ReturnType<TriggerStore["load"]>, host
 }
 
 /**
- * When the job next runs *here*, or undefined: disabled, or a plain job of a session this process
- * does not hold. The list is filtered the way dispatch filters — a next run for a job nothing here
- * will dispatch is a time nothing intends to keep, and a model reads it as a promise.
+ * When the job next runs, or undefined: disabled, or a plain job that is asleep or paused. A next
+ * run for a job nothing will dispatch is a time nothing intends to keep, and a model reads it as a
+ * promise; one held by another window is shown, with the pid it runs in.
  */
-function nextRunForTool(job: LoopJob, now: number, sessionId: string | undefined): number | undefined {
-	if (!job.enabled || !runsIn(job, sessionId)) return undefined;
+function nextRunForTool(job: LoopJob, now: number, view: OwnerView): number | undefined {
+	if (!job.enabled || !runsSomewhere(job, view)) return undefined;
 	return computeNext({ schedule: job.schedule, createdAt: Date.parse(job.createdAt), lastFiredAt: job.lastFiredAt ? Date.parse(job.lastFiredAt) : undefined }, now);
 }
 
+/** A plain job's prompt waiting in its conversation's queue (src/engine.ts `queuedPrompt`); a loop has no queue. */
+function queuedForTool(job: LoopJob, host: Pick<ToolHost, "scheduler">, now: number): QueuedPrompt | undefined {
+	return !job.stateful && job.sessionId ? queuedPrompt(job, host.scheduler.requests.list(job.sessionId), now) : undefined;
+}
+
 /** Cron jobs, rendered for a tool result. */
 function renderCronJobsForTool(jobs: LoopJob[], host: Pick<ToolHost, "session" | "scheduler">): string {
 	if (!jobs.length) return "cron jobs: none";
@@ -186,11 +264,15 @@ function renderCronJobsForTool(jobs: LoopJob[], host: Pick<ToolHost, "session" |
 	const inbox = jobs.some((j) => j.stateful) ? host.scheduler.inbox.list() : [];
 	for (const job of jobs) {
 		lines.push(`- ${job.id}${job.name ? ` "${job.name}"` : ""} [${job.enabled ? "enabled" : "disabled"}${job.stateful ? ", stateful" : ""}${job.verify ? ", verify" : ""}] schedule: ${formatSchedule(job.schedule)} action: ${previewRedacted(job.prompt, 120)}${job.cwd !== host.session().cwd ? ` cwd: ${job.cwd}` : ""}`);
-		const asleep = asleepNote(job, host.session().sessionId);
-		if (asleep) lines.push(`  ${asleep} (no next run here)`);
-		const next = nextRunForTool(job, now, host.session().sessionId);
+		const view = host.scheduler.ownerView();
+		const asleep = asleepNote(job, view);
+		const kind = whereRuns(job, view).kind;
+		if (asleep) lines.push(`  ${asleep}${kind === "asleep" ? " (no next run here)" : kind === "paused" ? " (no next run until pi-loops starts again)" : kind === "aside" ? "" : " (runs there, not here)"}`);
+		const next = nextRunForTool(job, now, view);
 		if (next) lines.push(`  next_run: ${stamp(next)}`);
 		if (job.running) lines.push(`  running_run_id: ${job.running.runId}`);
+		const queued = queuedForTool(job, host, now);
+		if (queued) lines.push(`  queued: ${formatWait(now - Date.parse(queued.since))} (since ${queued.since})${queued.reason ? ` — ${queued.reason}` : ""}`);
 		if (job.lastError) lines.push(`  last_error: ${previewRedacted(job.lastError, 120)}`);
 		if (job.consecutiveFailures) lines.push(`  consecutive_failures: ${job.consecutiveFailures}`);
 		if (job.skippedOverlap) lines.push(`  skipped_overlap_count: ${job.skippedOverlap}`);
@@ -205,6 +287,36 @@ function renderCronJobsForTool(jobs: LoopJob[], host: Pick<ToolHost, "session" |
 	return lines.join("\n");
 }
 
+/** The rule, made: the one write both ways to `new_trigger` end in, and the text the model reads on every surface. */
+async function addRule(host: ToolHost, input: Parameters<TriggerStore["add"]>[0]) {
+	const rule = await host.triggers.store.add(input);
+	host.refreshBadge();
+	host.ensureHost?.();
+	return {
+		content: [{ type: "text" as const, text: `created dynamic trigger ${rule.id}\ncondition: ${rule.condition}\naction: ${rule.action}\nfire_once: ${rule.fireOnce}\npromote_to_chat: ${rule.promoteToChat}\n(checked every ${host.triggers.pollIntervalSecs}s by a sub-agent in the background)${pausedLine(host.scheduler.ownerView().hostPaused)}` }],
+		details: { id: rule.id as string | undefined, condition: rule.condition, action: rule.action, enabled: rule.enabled, fire_once: rule.fireOnce, fired_at: rule.firedAt, promote_to_chat: rule.promoteToChat },
+	};
+}
+
+/** The job, made: the one write both ways to `cron_create` end in, and the text the model reads on every surface. */
+async function createCron(host: ToolHost, scope: ToolScope, input: CreateJobInput) {
+	const job = await host.createJob(input, scope);
+	const auditEntryId = host.cronControlAudit("add", scope.actor, undefined, job);
+	host.refreshBadge();
+	const next = computeNext({ schedule: job.schedule, createdAt: Date.parse(job.createdAt) }, Date.now());
+	// The model tells the person, so it has to know the costs a person would otherwise hear in /cron add.
+	const tools = job.tools ? `the tools ${job.tools.join(", ")}` : job.builtinTools ? `this chat's built-in tools (${job.builtinTools.join(", ") || "none"})` : "pi's default tools";
+	const where = job.stateful
+		? `Findings will appear in /inbox${job.verify ? " after an independent checker reviews them" : ""}. It runs in the background with ${tools}, not this window's -e extensions or flags.`
+		: `Its result will appear in this chat. While this chat is closed it still runs, in the background, and each run is a model turn. Its turns run with ${tools} under the dangerous-command guard: in an open window a dangerous command or a tool outside them asks the user first, and in the background it is refused. In the background they also run without this window's -e extensions or flags.`;
+	const runsAt = whereRuns(job, host.scheduler.ownerView());
+	// Three lines — what was created, when it runs, what it will do — then where its output goes.
+	return {
+		content: [{ type: "text" as const, text: `created cron job ${job.id}${job.name ? ` "${job.name}"` : ""}\nschedule: ${formatSchedule(job.schedule)}\naction: ${previewRedacted(job.prompt, 120)}\n${job.stateful ? "[stateful] " : ""}next run ${next ? stamp(next) : "—"}. ${where}${pausedLine(runsAt.kind === "paused" ? runsAt.reason : undefined)}` }],
+		details: { id: job.id as string | undefined, name: job.name, schedule: formatSchedule(job.schedule), action: job.prompt, enabled: job.enabled, stateful: job.stateful, verify: job.verify ?? false, scope: job.stateful ? "machine" : "session", owner_session: ownerSession(job), next_run: next ? stamp(next) : undefined, audit_entry_id: auditEntryId },
+	};
+}
+
 export interface ToolScope {
 	hop: number;
 	actor: "tool" | "sub-agent";
@@ -218,6 +330,8 @@ export interface ToolScope {
  */
 export function automationTools(scope: ToolScope, host: ToolHost): ToolDefinition<any, any>[] {
 	const defs: ToolDefinition<any, any>[] = [];
+	// Only where a person's message can arrive: a sub-agent is told nothing about it.
+	const watchSentence = scope.hop === 0 ? WATCH_SENTENCE : "";
 	// Generic so each definition keeps its inferred parameter type, exactly as pi.registerTool does.
 	const register = <T extends TSchema, D>(d: ToolDefinition<T, D>): void => void defs.push(d as ToolDefinition<any, any>);
 	register({
@@ -231,13 +345,13 @@ export function automationTools(scope: ToolScope, host: ToolHost): ToolDefinitio
 				action: Type.String({ description: "The action to perform when the condition matches. This may be a shell command or a natural-language instruction." }),
 				spec: Type.Optional(Type.String({ description: "Fallback complete trigger rule text when condition and action cannot be supplied separately." })),
 				fire_once: Type.Optional(Type.Boolean({ description: "Whether to disable the rule after the first successful match. Defaults to true unless the user explicitly asks for a repeating trigger." })),
-				promote_to_chat: Type.Optional(Type.Boolean({ description: "Whether successful trigger output should be inserted into the parent chat context so future turns can see it. Defaults to false unless the user explicitly asks for that behavior." })),
+				promote_to_chat: Type.Optional(Type.Boolean({ description: "Whether a match's result goes into this conversation (true) or the inbox (false). With a person present the question starts at this conversation whatever this says; with nobody to ask, the default is false." })),
 			},
 			{ additionalProperties: false },
 		),
-		async execute(_id, params, _signal, _onUpdate, ctx) {
+		async execute(_id, params, signal, _onUpdate, ctx) {
 			if ([params.condition, params.action, params.spec].some((t) => t && looksLikeFixedScheduleRequest(t))) return deny("fixed scheduled jobs must use cron_create, not new_trigger");
-			let condition = params.condition?.trim() ?? "";
+			let condition = cleanCondition(params.condition ?? "");
 			let action = params.action?.trim() ?? "";
 			const fromSpec = !condition || !action;
 			if (fromSpec) {
@@ -248,15 +362,21 @@ export function automationTools(scope: ToolScope, host: ToolHost): ToolDefinitio
 					return deny(err?.message ?? String(err));
 				}
 			}
+			const s = host.session();
+			const draft = { condition, action, cwd: s.cwd, sessionId: s.sessionId, model: s.model, thinking: s.thinking };
+			if (asking(scope, host, ctx)) {
+				// The question replaces the confirm, never adds to it: one question. Its defaults are the
+				// person's to change, not the model's: Result starts at this conversation whatever
+				// `promote_to_chat` said (its documented default is not a choice anyone made); Repeats
+				// follows `fire_once`, whose default is the rule's own.
+				const asked = await askWatch(ctx, signal, host, { kind: "rule", rule: draft, where: "chat", once: params.fire_once ?? true });
+				if (!("verdict" in asked)) return asked;
+				return addRule(host, { ...draft, fireOnce: asked.once, promoteToChat: asked.where === "chat" });
+			}
 			const reason = fromSpec ? "create dynamic trigger from `spec` field" : "create dynamic trigger from `condition` + `action` fields";
 			const denied = await host.confirmTool(ctx, { label: "create dynamic trigger", tool: "new_trigger", reason, preview: `when ${previewRedacted(condition, 80)} -> ${previewRedacted(action, 80)}`, args: params }, scope.hop);
 			if (denied) return deny(denied);
-			const rule = await host.triggers.store.add({ condition, action, fireOnce: params.fire_once ?? true, promoteToChat: params.promote_to_chat ?? false, cwd: host.session().cwd, sessionId: host.session().sessionId, model: host.session().model, thinking: host.session().thinking });
-			host.refreshBadge();
-			return {
-				content: [{ type: "text", text: `created dynamic trigger ${rule.id}\ncondition: ${rule.condition}\naction: ${rule.action}\nfire_once: ${rule.fireOnce}\npromote_to_chat: ${rule.promoteToChat}\n(checked every ${host.triggers.pollIntervalSecs}s by a background sub-agent)` }],
-				details: { id: rule.id as string | undefined, condition: rule.condition, action: rule.action, enabled: rule.enabled, fire_once: rule.fireOnce, fired_at: rule.firedAt, promote_to_chat: rule.promoteToChat },
-			};
+			return addRule(host, { ...draft, fireOnce: params.fire_once ?? true, promoteToChat: params.promote_to_chat ?? false });
 		},
 	});
 	register({
@@ -296,7 +416,7 @@ export function automationTools(scope: ToolScope, host: ToolHost): ToolDefinitio
 			}
 			if (!params.id) return err("missing required arg: id");
 			const rule = resolveRuleRefScoped(host.triggers.store.load(), params.id, host.session().cwd);
-			if (!rule) return err(`no dynamic trigger rule with id '${params.id}'`);
+			if (!rule) return err(`no dynamic trigger rule with id '${params.id}'; list_triggers shows the ids`);
 			const denied = await host.confirmTool(ctx, { label: `remove dynamic trigger ${rule.id}`, tool: "remove_trigger", reason: "remove a dynamic trigger rule by `id`", preview: `when ${previewRedacted(rule.condition, 120)}`, args: params }, scope.hop);
 			if (denied) return err(denied);
 			await host.triggers.store.remove(rule.id);
@@ -314,7 +434,7 @@ export function automationTools(scope: ToolScope, host: ToolHost): ToolDefinitio
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const ruleCwd = host.session().cwd;
 			const rule = resolveRuleRefScoped(host.triggers.store.load(), params.id, ruleCwd);
-			if (!rule) return deny(`no dynamic trigger rule with id '${params.id}'`);
+			if (!rule) return deny(`no dynamic trigger rule with id '${params.id}'; list_triggers shows the ids`);
 			// Re-enabling is gated; pausing another project's rule is just as much a surprise, so it
 			// is gated too (a sub-agent is refused outright, having nobody to ask).
 			if (params.enabled || rule.cwd !== ruleCwd) {
@@ -333,48 +453,53 @@ export function automationTools(scope: ToolScope, host: ToolHost): ToolDefinitio
 		name: "cron_create",
 		label: "Create cron job",
 		description:
-			"Create a scheduled job. Use when the user asks for a fixed time, recurring, scheduled, hourly, daily, weekly, crontab, 定时任务, 每小时, 每天, or similar time-based job. Jobs persist across pi restarts. A plain job runs its prompt in this chat when due. Set stateful=true for loop mode: a fresh sub-agent runs it, keeps persistent notes across runs (injected each time), and routes findings to the user's /inbox instead of the chat — use that for recurring watch/triage jobs like \"check for new issues and report only what changed\".",
+			"Create a scheduled job. Use when the user asks for a fixed time, recurring, scheduled, hourly, daily, weekly, crontab, 定时任务, 每小时, 每天, or similar time-based job. Jobs persist across pi restarts. A plain job runs its prompt in this chat when due. Set stateful=true for loop mode: a fresh sub-agent runs it, keeps persistent notes across runs (injected each time), and routes findings to the user's /inbox instead of the chat — use that for recurring watch/triage jobs like \"check for new issues and report only what changed\"." + watchSentence,
 		parameters: Type.Object({
 			schedule: Type.String({
 				description: 'Local-time schedule: 5-field cron ("0 9 * * *", "*/30 * * * 1-5"), "@daily", "every 30m", "in 10m", or "at 2026-09-08T18:00".',
 			}),
 			action: Type.String({ description: "Natural-language instruction to run when the schedule is due. For stateful jobs, write it for a fresh agent whose only memory is its own notes." }),
-			stateful: Type.Optional(Type.Boolean({ description: "Loop mode: sub-agent + notes between runs + findings to /inbox (default false)." })),
+			stateful: Type.Optional(Type.Boolean({ description: "Loop mode: sub-agent + notes between runs + findings to the inbox. With a person present the question starts at the inbox unless this is false; with nobody to ask, the default is false." })),
 			verify: Type.Optional(Type.Boolean({ description: "Maker/checker: a second adversarial sub-agent verifies each finding before it enters the inbox (stateful jobs only, default false). Use when the user asks for verified, double-checked, or high-precision findings." })),
 			name: Type.Optional(Type.String({ description: "Short unique label (letters, digits, . _ -)." })),
 			cwd: Type.Optional(Type.String({ description: "Directory a stateful job's sub-agent runs in. Default: current project." })),
-			catch_up: Type.Optional(Type.Boolean({ description: "Run once for a tick that was missed: a loop when a pi next takes the clock, a plain job when the session that created it is next opened (default: true for stateful jobs, false for plain jobs)." })),
+			catch_up: Type.Optional(Type.Boolean({ description: "Run once for a tick that was missed while nothing could run the job: a loop when pi-loops next starts, a plain job when its conversation is next opened or pi-loops next starts (default: true for stateful jobs, false for plain jobs)." })),
 		}),
-		async execute(_id, params) {
-			const schedule = parseSchedule(params.schedule);
-			const job = await host.createJob(
-				{
-					schedule,
-					prompt: params.action,
-					stateful: params.stateful ?? params.verify ?? false, // verify implies a loop: a checker only reviews loop findings (`args.ts` does the same for `--verify`)
-					verify: params.verify ?? false,
-					name: params.name,
-					cwd: params.cwd,
-					catchUp: params.catch_up,
-				},
-				scope,
-			);
-			const auditEntryId = host.cronControlAudit("add", scope.actor, undefined, job);
-			host.refreshBadge();
-			const next = computeNext({ schedule: job.schedule, createdAt: Date.parse(job.createdAt) }, Date.now());
-			const where = job.stateful ? `Findings will appear in /inbox${job.verify ? " after an independent checker reviews them" : ""}.` : "Its result will appear in this chat.";
-			// Three lines — what was created, when it runs, what it will do — then where its output goes.
-			return {
-				content: [{ type: "text", text: `created cron job ${job.id}${job.name ? ` "${job.name}"` : ""}\nschedule: ${formatSchedule(job.schedule)}\naction: ${previewRedacted(job.prompt, 120)}\n${job.stateful ? "[stateful] " : ""}next run ${next ? stamp(next) : "—"}. ${where}` }],
-				details: { id: job.id, name: job.name, schedule: formatSchedule(job.schedule), action: job.prompt, enabled: job.enabled, stateful: job.stateful, verify: job.verify ?? false, scope: job.stateful ? "machine" : "session", owner_session: ownerSession(job), next_run: next ? stamp(next) : undefined, audit_entry_id: auditEntryId },
-			};
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			let schedule: LoopJob["schedule"];
+			try {
+				schedule = parseSchedule(params.schedule);
+			} catch (err: any) {
+				return deny(err?.message ?? String(err));
+			}
+			if (asking(scope, host, ctx)) {
+				// A schedule's Result starts at the inbox (a loop) unless the model said plainly that it
+				// belongs in this chat. Checked now as a create would be, so the person is never asked
+				// about a job their yes cannot make.
+				const where = params.stateful === false && !params.verify ? "chat" : "inbox";
+				const draft = { schedule, prompt: params.action, verify: params.verify ?? false, name: params.name, catchUp: params.catch_up };
+				let cwd: string;
+				try {
+					cwd = checkJobInput({ ...draft, stateful: where === "inbox", cwd: params.cwd }, host.scheduler.store.load(), host.session());
+				} catch (err: any) {
+					return deny(err?.message ?? String(err));
+				}
+				// The question is the consent, and it does not show a directory: a job it sets up runs in
+				// this project, so a `cwd` elsewhere (a prompt-injected one, say) is refused here.
+				if (!withinProject(host.session().cwd, cwd)) return deny(`a watch you are asked about runs in this project (${host.session().cwd}): cwd ${cwd} is outside it; /cron add --cwd sets one up elsewhere`);
+				const asked = await askWatch(ctx, signal, host, { kind: "schedule", job: { ...draft, cwd }, where });
+				if (!("verdict" in asked)) return asked;
+				return createCron(host, scope, { ...draft, cwd, stateful: asked.where === "inbox", verify: asked.where === "inbox" && asked.checks });
+			}
+			// verify implies a loop: a checker only reviews loop findings (`args.ts` does the same for `--verify`)
+			return createCron(host, scope, { schedule, prompt: params.action, stateful: params.stateful ?? params.verify ?? false, verify: params.verify ?? false, name: params.name, cwd: params.cwd, catchUp: params.catch_up });
 		},
 	});
 
 	register({
 		name: "cron_list",
 		label: "List cron jobs",
-		description: "List the current project's scheduled jobs with schedule, next run, [stateful] marker and last error. Also reports how many unread inbox findings exist. Set all_projects only when the user asks about other projects.",
+		description: "List the current project's scheduled jobs with schedule, next run, [stateful] marker and last error. A plain job whose prompt is waiting in its conversation's queue reports `queued` (since when, and the wait reason when the queue says one). Also reports how many unread inbox findings exist. Set all_projects only when the user asks about other projects.",
 		parameters: Type.Object({
 			all_projects: Type.Optional(Type.Boolean({ description: "Include jobs of every project on this machine (default false)." })),
 		}),
@@ -382,10 +507,13 @@ export function automationTools(scope: ToolScope, host: ToolHost): ToolDefinitio
 			const listCwd = host.session().cwd;
 			const everywhere = params.all_projects === true && scope.hop === 0;
 			const jobs = everywhere ? host.scheduler.store.load() : host.scheduler.store.load().filter((j) => sameProject(j.cwd, listCwd));
-			const text = `${renderCronJobsForTool(jobs, host)}\ninbox: ${host.scheduler.inbox.newCount()} new finding(s)`;
+			const newFindings = everywhere ? host.scheduler.inbox.newCount() : inProject(host.scheduler.inbox.listNew(), listCwd, sameProject).length;
+			const text = `${renderCronJobsForTool(jobs, host)}\ninbox: ${plural(newFindings, "new finding")}`;
 			const nowMs = Date.now();
-			const nextRun = (j: LoopJob) => nextRunForTool(j, nowMs, host.session().sessionId);
-			return { content: [{ type: "text", text }], details: { count: jobs.length, scope: everywhere ? "machine" : listCwd, storage_path: host.scheduler.store.jobsFile, jobs: jobs.map((j) => ({ id: j.id, name: j.name, schedule: formatSchedule(j.schedule), action_preview: previewRedacted(j.prompt, 120), enabled: j.enabled, stateful: j.stateful, verify: j.verify ?? false, cwd: j.cwd, running_run_id: j.running?.runId, last_due_at: j.lastDueAt, last_fired_at: j.lastFiredAt, last_completed_at: j.lastCompletedAt, last_error: j.lastError ? previewRedacted(j.lastError, 120) : undefined, consecutive_failures: j.consecutiveFailures, skipped_overlap_count: j.skippedOverlap, next_run: (() => { const n = nextRun(j); return n ? stamp(n) : undefined; })(), owner_session: ownerSession(j), asleep: !runsIn(j, host.session().sessionId) || undefined, created_at: j.createdAt })) } };
+			const view = host.scheduler.ownerView();
+			const nextRun = (j: LoopJob) => nextRunForTool(j, nowMs, view);
+			const heldBy = (j: LoopJob) => { const where = whereRuns(j, view); return where.kind === "terminal" ? where.pid : undefined; };
+			return { content: [{ type: "text", text }], details: { count: jobs.length, scope: everywhere ? "machine" : listCwd, storage_path: host.scheduler.store.jobsFile, jobs: jobs.map((j) => ({ id: j.id, name: j.name, schedule: formatSchedule(j.schedule), action_preview: previewRedacted(j.prompt, 120), enabled: j.enabled, stateful: j.stateful, verify: j.verify ?? false, cwd: j.cwd, running_run_id: j.running?.runId, last_due_at: j.lastDueAt, last_fired_at: j.lastFiredAt, last_completed_at: j.lastCompletedAt, last_error: j.lastError ? previewRedacted(j.lastError, 120) : undefined, consecutive_failures: j.consecutiveFailures, skipped_overlap_count: j.skippedOverlap, next_run: (() => { const n = nextRun(j); return n ? stamp(n) : undefined; })(), owner_session: ownerSession(j), asleep: whereRuns(j, view).kind === "asleep" || undefined, held_by_pid: heldBy(j), queued: queuedForTool(j, host, nowMs), created_at: j.createdAt })) } };
 		},
 	});
 
@@ -400,7 +528,7 @@ export function automationTools(scope: ToolScope, host: ToolHost): ToolDefinitio
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const job = resolveJobRefScoped(host.scheduler.store.load(), params.ref, host.session().cwd);
-			if (!job) return { content: [{ type: "text", text: `no cron job with id '${params.ref}'` }], isError: true, details: { id: undefined as string | undefined, removed_count: 0, confirmation_required: false, audit_entry_id: undefined as string | undefined } };
+			if (!job) return { content: [{ type: "text", text: `no cron job matching '${params.ref}' in this project; cron_list shows the ids and names` }], isError: true, details: { id: undefined as string | undefined, removed_count: 0, confirmation_required: false, audit_entry_id: undefined as string | undefined } };
 			const label = `${job.id}${job.name ? ` "${job.name}"` : ""}`;
 			if (!params.confirm) {
 				return {
@@ -440,14 +568,17 @@ export function automationTools(scope: ToolScope, host: ToolHost): ToolDefinitio
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const jobCwd = host.session().cwd;
 			const job = resolveJobRefScoped(host.scheduler.store.load(), params.ref, jobCwd);
-			if (!job) return deny(`no cron job with id '${params.ref}'`);
+			if (!job) return deny(`no cron job matching '${params.ref}' in this project; cron_list shows the ids and names`);
 			if (params.enabled || job.cwd !== jobCwd) {
 				const denied = await host.confirmTool(ctx, { label: `${params.enabled ? "enable" : "disable"} cron job ${job.name ?? job.id}`, tool: "set_cron_job_state", reason: params.enabled ? "enable a cron job from a model-facing tool (`enabled` = true)" : "disable a cron job of another project", preview: `${formatSchedule(job.schedule)}: ${previewRedacted(job.prompt, 120)}`, args: params }, scope.hop);
-				if (denied) return deny(`${denied}; use /cron enable <id>`);
+				if (denied) return deny(denied);
 			}
 			const updated = (await host.scheduler.store.update(job.id, (j) => {
 				j.enabled = params.enabled;
-				if (params.enabled) j.lastError = undefined;
+				if (params.enabled) {
+					j.lastError = undefined;
+					j.interruptions = undefined;
+				}
 			})) ?? job;
 			const auditEntryId = host.cronControlAudit(params.enabled ? "enable" : "disable", scope.actor, job, updated);
 			return {