pi-roundtable 0.7.8 → 0.7.10

package/CHANGELOG.md

@@ -5,6 +5,24 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.7.10] - 2026-10-03
+
+### Added
+
+- Kit: the core's compaction tiers for a host that builds its own Pi session, such as a sandbox worker: `CompactionTiers`, `compactionEngine`, `SOFT_COMPACT_TOKENS`, `HARD_COMPACT_TOKENS`, `COMPACT_HEADROOM_TOKENS`, and the types `CompactionEngine`, `CompactionHistory` and `LatestCompaction`.
+- Sandbox: Pi worker sessions compact with those tiers, through an optional host compactor (`compaction` on `PiSandboxRuntime`) at 300,000 tokens and Pi's summary past 500,000, and the host logs each compaction and fallback per channel.
+
+### Changed
+
+- Sandbox: a failed Pi turn keeps its cause and is logged, the broker logs upstream failures, a timed-out worker's last log lines are logged before its container is removed, and Pi containers log to journald tagged `sandbox/<channel>` by default instead of local files (the Docker daemon must have journald).
+
+## [0.7.9] - 2026-10-03
+
+### Added
+
+- Schedule prechecks: host code registers a named check with `PRECHECKS` (`register`, as `register({ name, description, timeoutMs?, run })`, provided by the new built-in `prechecks` plugin), and a schedule may name one in the new `precheck` parameter of `schedule_create` and `schedule_update` (`null` removes it). When the schedule falls due, the scheduler takes it as before and then runs the check: `{ wake: false, note? }` skips the turn and posts the note as the bot's own small message, `{ wake: true, context }` runs the turn with the context under a "Precheck found" heading, and a throw or a timeout (`PRECHECK_TIMEOUT_MS`, 60 seconds by default) runs it with the error. `schedule_list` and `/<root> schedule list` show a schedule's precheck and the last outcome, and `schedule_list` names the registered prechecks with their descriptions. New types: `Precheck`, `PrecheckContext`, `PrecheckResult`, `PrecheckRegistry`, `PrecheckFinding`. `Schedule`, `NewSchedule`, and `ScheduleChange` gain an optional `precheck`; `BackgroundTurns.runScheduled` takes the `PrecheckFinding` as an optional third argument. The `schedules` table gains a nullable `precheck` column through the new `schedules-precheck` migration.
+- `pi-roundtable/testing`: `fakePrecheck` (`fakePrecheck(name, answer, options?)`, a precheck that answers as the test says and records its calls) and `fakePrechecks` (a real in-memory registry with the given prechecks registered), with the types `FakePrecheck` and `FakePrecheckAnswer`.
+
 ## [0.7.8] - 2026-10-03
 
 ### Fixed

package/docs/plugins.md

@@ -10,7 +10,7 @@ Each example has a test next to it that runs it without Discord or PostgreSQL, e
 A plugin is an object with a name and a `setup` function.
 `setup` returns the parts the plugin adds to the bot: tools agents can call, text added to their prompt, agents to create, handlers for events, long-lived services, slash commands, HTTP routes, and so on.
 The bot itself is assembled from plugins too.
-The core ships built-in plugins for its memory and schedule stores, Discord connection, agent server, notifications, delegation, and schedules.
+The core ships built-in plugins for its memory and schedule stores, schedule prechecks, Discord connection, agent server, notifications, delegation, and schedules.
 You can switch off three [addons](#addons-memory-skills-and-discord-administration): memory, skills, and Discord administration.
 Your plugins are added after them and can read or replace the built-ins' [keyed services](#services-what-plugins-provide-to-each-other).
 
@@ -61,10 +61,13 @@ Use the kit's building blocks for a plugin that runs Pi itself, such as a coding
   Ordinary 48 MP images and thin 9000×1 images remain admitted.
   This helper is not a downloader or filesystem validator.
 - Work: `promptSlot` (how a run asks the owner while it works), `workTimeout` (a time limit that does not count the time spent waiting on the owner), `runWorkerTask`, `archiveSessions`, and `approvalCard` and `canonicalJson` for the cards of held actions.
+- Diagnostics: `scrubDiagnostic(text, max = 600)` masks credentials (URL userinfo, token shapes, secret-named assignments and JSON fields, `Authorization`/`Cookie`/`x-api-key` headers, JWTs, PEM blocks), turns control characters other than tab and newline into spaces, and cuts the result at `max` characters.
+  It scans only the first `max * 4` characters (at least 4,096), in linear time, so pass it git, gh or provider error text before showing that text to a user.
 - Shell: `SHELL_TOOLS` and `shellHoldRule`, the hold rule that keeps risky host-shell commands behind the owner's approval.
 - Tools: `textToolsExtension`, `requiredString`, `stringList` (with `toolText` and `toolError`) for tools that return text.
 - Mirroring a built-in tool in a worker that cannot reach the host: `SCHEDULE_TOOLS`, `scheduleToolSpecs({ locale, timeZone })`, `isScheduleTool`, `callScheduleTool`, `DELEGATE_TOOL` and `DELEGATE_TOOL_SPEC`.
   The specs take the locale and time zone for their descriptions, so the worker needs no process-wide setting.
+- Compaction: `CompactionTiers` gives a session the core's compaction tiers (`settings()` for Pi's `SettingsManager`, `wrapCompactor(factory, onBypass)` to hold a compaction extension back past the ceiling, `latest()`), with `SOFT_COMPACT_TOKENS` (300,000), `HARD_COMPACT_TOKENS` (500,000), `COMPACT_HEADROOM_TOKENS` (50,000), `compactionEngine(details, engine)` and the types `CompactionEngine`, `CompactionHistory` and `LatestCompaction`.
 - Effort: `effortJudge` picks a turn's thinking level from a message with your own brief (`EffortBrief`, `JUDGE_WORK`).
 - Presentation and small helpers: `thinkingLine`, `zonedStamp(date, timeZone)`, `channelQueue()` (a queue of your own, so work does not wait behind a running turn), `checkRepoName` and `SKILL_LIST_TOOL` with `skillListExtension` for repositories and skills, and `searchTerms` for memory search.
 
@@ -164,6 +167,7 @@ The built-in plugins provide these, from the main entry:
 | `AGENTS` | `AgentServer` | `agent-server` | The `team` (`AgentTeam`), the read-only `directory` (`AgentDirectory`), the `runtime` every agent turn runs on, `approvals` (whether the owner's reply approves held actions), and `avatars` (`AvatarStudio`) |
 | `SKILLS` | `SkillRegistry` | `skills` (an addon) | What agents carry: `carried`, `carriedNames`, `describeCarried`, `catalog`, `list`, `linkedFrom`, `checkRegistered`, `link`, `attach` |
 | `SCHEDULES` | `ScheduleStore` | `schedule-store` | The stored schedules: `create`, `get`, `forChannel`, `all`, `update`, `remove`, `due`, `claim`, `recordStatus` |
+| `PRECHECKS` | `PrecheckRegistry` | `prechecks` | The host's named [prechecks](#prechecks-wake-a-schedule-only-when-it-has-work): `register`, `get`, `list` |
 | `MEMORY` | `MemoryStore` | `memory` (an addon) | `forSpeaker(id)` gives that speaker's `SpeakerMemory`: `list`, `forPrompt`, `add`, `search`, `update`, `removeById`, `remove`; `MEMORY_KINDS` is `core`, `note`, `event` |
 | `BACKGROUND_TURNS` | `BackgroundTurns` | `modules` | Turns nobody wrote: `runScheduled`, `runDelegated`, `runErrorReport` |
 | `DELEGATION` | `Delegator` | `modules` | `start(request)` a background task, `runningChannels()`, `idle()` |
@@ -740,6 +744,62 @@ export function heartbeat(everyMs: number, beat: () => Promise<void> | void) {
 ```
 <!-- /example -->
 
+#### Prechecks: wake a schedule only when it has work
+
+A schedule whose answer is "all normal" on most days still costs a model turn each time it fires.
+A precheck is host code that runs first and decides whether the turn runs at all.
+Register it with `services.get(PRECHECKS).register({ name, description, timeoutMs?, run })` during setup; the agent attaches it to a schedule by name with the `precheck` parameter of `schedule_create` or `schedule_update` (`null` removes it), and `schedule_list` shows the registered names with their descriptions.
+The model only picks a name: it never supplies code or a command, so attaching a precheck grants nothing beyond what the schedule already has, and the same tier rules apply.
+
+When a schedule with a precheck falls due, the scheduler takes it first (moves it to its next run, or deletes a one-time schedule) exactly as before, so a slow precheck never fires it twice, and then calls `run({ schedule, firedAt, signal })`:
+
+- `{ wake: false, note? }` skips the turn. A `note` is posted in the schedule's channel as the bot's own small message, which starts no turn. The last status reads `skipped by precheck (note)`.
+- `{ wake: true, context }` runs the turn; its text carries `context` under a `### Precheck found (<name>):` heading after the prompt. The last status reads `woken by precheck; ran`.
+- A throw, a wrong answer, a name no longer registered, or running past `timeoutMs` (default `PRECHECK_TIMEOUT_MS`, 60 seconds; `signal` is aborted then) runs the turn with the error under `### Precheck failed: <name>`, so the agent can look into it. The error is logged, and the last status reads `precheck failed (…), woke; ran`.
+
+A name is lower-case letters, digits, `.`, `_`, and `-`; registering one twice throws a `PluginError`.
+A `BackgroundTurns` of your own receives what the precheck found as `runScheduled`'s third argument, a `PrecheckFinding`.
+
+<!-- example: examples/prechecks.ts -->
+```ts
+import { definePlugin, PRECHECKS } from "pi-roundtable";
+
+/** Last night's reading and its usual level, from wherever the host keeps them. */
+export interface RecoveryReading {
+	hrv: number;
+	baseline: number;
+}
+
+/**
+ * A precheck a daily schedule can name: the host reads the numbers first and wakes the agent
+ * only when they are off, so an ordinary morning costs no model turn.
+ */
+export function recoveryPrecheck(read: () => Promise<RecoveryReading>) {
+	return definePlugin({
+		name: "recovery-precheck",
+		setup: ({ services }) => {
+			services.get(PRECHECKS).register({
+				name: "health.recovery",
+				description:
+					"Reads last night's HRV; wakes you when it is a fifth or more under its baseline.",
+				timeoutMs: 15_000,
+				run: async () => {
+					const { hrv, baseline } = await read();
+					if (hrv >= baseline * 0.8)
+						return { wake: false, note: `HRV ${hrv} ms, as usual.` };
+					return {
+						wake: true,
+						context: `HRV ${hrv} ms against a baseline of ${baseline} ms.`,
+					};
+				},
+			});
+			return {};
+		},
+	});
+}
+```
+<!-- /example -->
+
 ### `migrations` and `context.database()`: tables of your own
 
 Declare `migrations` on the plugin object.
@@ -2074,6 +2134,7 @@ Call `useTestLocale()` after a test changes the process-wide locale or time zone
 `recordingLogger()` is a logger that keeps what it is asked to write: its `lines` hold each call's `level`, `fields` (those of a `child` included), and `message`, for a test of what the code logs.
 Use `partial<Port>({ ... })` to stand in for a port your code takes as an argument.
 It provides the members you give it and throws an error naming any missing member you read, so the test needs no `as unknown as Port` cast.
+`fakePrecheck(name, answer, { description?, timeoutMs? })` is a precheck that answers `answer` (a `PrecheckResult`, an `Error` it throws, or a function of its context) and records each context in `calls`; `fakePrechecks(...prechecks)` is a real in-memory `PrecheckRegistry` with them registered, which a test gives a plugin as `servicePair(PRECHECKS, registry)` and reads back with `registry.get(name)`.
 `fakeDiscord({ ownerId?, rootCommand? })` is the `DISCORD` service for a plugin that adds slash commands: give it as `services: [discord.service]`, read what the plugin added with `discord.added()`, and compose the tree Discord would get with `discord.compose()`.
 Only `commands` and `guard` are given; a plugin that reads another member of `DISCORD` in a test gives its own with `servicePair(DISCORD, { ... })`.
 
@@ -2439,6 +2500,13 @@ Import from the entries listed below; source area files are internal.
 | `RuntimeDeps` | `pi-roundtable` | type |
 | `RuntimeFactory` | `pi-roundtable` | type |
 | `SCHEDULES` | `pi-roundtable` | value |
+| `PRECHECKS` | `pi-roundtable` | value |
+| `PRECHECK_TIMEOUT_MS` | `pi-roundtable` | value |
+| `Precheck` | `pi-roundtable` | type |
+| `PrecheckContext` | `pi-roundtable` | type |
+| `PrecheckFinding` | `pi-roundtable` | type |
+| `PrecheckRegistry` | `pi-roundtable` | type |
+| `PrecheckResult` | `pi-roundtable` | type |
 | `SKILLS` | `pi-roundtable` | value |
 | `Schedule` | `pi-roundtable` | type |
 | `ScheduleChange` | `pi-roundtable` | type |
@@ -2513,6 +2581,10 @@ Import from the entries listed below; source area files are internal.
 | `describeDb` | `pi-roundtable/testing` | value |
 | `eagerText` | `pi-roundtable/testing` | value |
 | `fakeDiscord` | `pi-roundtable/testing` | value |
+| `fakePrecheck` | `pi-roundtable/testing` | value |
+| `fakePrechecks` | `pi-roundtable/testing` | value |
+| `FakePrecheck` | `pi-roundtable/testing` | type |
+| `FakePrecheckAnswer` | `pi-roundtable/testing` | type |
 | `fakeThreads` | `pi-roundtable/testing` | value |
 | `openTestStore` | `pi-roundtable/testing` | value |
 | `servicePair` | `pi-roundtable/testing` | value |
@@ -2594,6 +2666,14 @@ Import from the entries listed below; source area files are internal.
 | `formatModelRef` | `pi-roundtable/kit` | value |
 | `headline` | `pi-roundtable/kit` | value |
 | `holdChain` | `pi-roundtable/kit` | value |
+| `COMPACT_HEADROOM_TOKENS` | `pi-roundtable/kit` | value |
+| `CompactionTiers` | `pi-roundtable/kit` | value |
+| `compactionEngine` | `pi-roundtable/kit` | value |
+| `HARD_COMPACT_TOKENS` | `pi-roundtable/kit` | value |
+| `SOFT_COMPACT_TOKENS` | `pi-roundtable/kit` | value |
+| `CompactionEngine` | `pi-roundtable/kit` | type |
+| `CompactionHistory` | `pi-roundtable/kit` | type |
+| `LatestCompaction` | `pi-roundtable/kit` | type |
 | `isScheduleTool` | `pi-roundtable/kit` | value |
 | `lastAssistant` | `pi-roundtable/kit` | value |
 | `mcpAdapterExtension` | `pi-roundtable/kit` | value |

package/examples/prechecks.test.ts

@@ -0,0 +1,30 @@
+import { expect, test } from "bun:test";
+import { PRECHECKS, type Schedule } from "pi-roundtable";
+import { fakePrechecks, servicePair, testPlugin } from "pi-roundtable/testing";
+import { recoveryPrecheck } from "./prechecks.ts";
+
+test("the precheck stays quiet on a normal reading and wakes the agent on a low one", async () => {
+	const prechecks = fakePrechecks();
+	let reading = { hrv: 52, baseline: 55 };
+	const harness = await testPlugin(
+		recoveryPrecheck(async () => reading),
+		{ services: [servicePair(PRECHECKS, prechecks)] },
+	);
+	const precheck = prechecks.get("health.recovery");
+	if (!precheck) throw new Error("the plugin registered no precheck");
+	const context = {
+		schedule: { id: 1, title: "recovery" } as Schedule,
+		firedAt: new Date(),
+		signal: new AbortController().signal,
+	};
+	expect(await precheck.run(context)).toEqual({
+		wake: false,
+		note: "HRV 52 ms, as usual.",
+	});
+	reading = { hrv: 31, baseline: 55 };
+	expect(await precheck.run(context)).toEqual({
+		wake: true,
+		context: "HRV 31 ms against a baseline of 55 ms.",
+	});
+	await harness.stop();
+});

package/examples/prechecks.ts

@@ -0,0 +1,35 @@
+import { definePlugin, PRECHECKS } from "pi-roundtable";
+
+/** Last night's reading and its usual level, from wherever the host keeps them. */
+export interface RecoveryReading {
+	hrv: number;
+	baseline: number;
+}
+
+/**
+ * A precheck a daily schedule can name: the host reads the numbers first and wakes the agent
+ * only when they are off, so an ordinary morning costs no model turn.
+ */
+export function recoveryPrecheck(read: () => Promise<RecoveryReading>) {
+	return definePlugin({
+		name: "recovery-precheck",
+		setup: ({ services }) => {
+			services.get(PRECHECKS).register({
+				name: "health.recovery",
+				description:
+					"Reads last night's HRV; wakes you when it is a fifth or more under its baseline.",
+				timeoutMs: 15_000,
+				run: async () => {
+					const { hrv, baseline } = await read();
+					if (hrv >= baseline * 0.8)
+						return { wake: false, note: `HRV ${hrv} ms, as usual.` };
+					return {
+						wake: true,
+						context: `HRV ${hrv} ms against a baseline of ${baseline} ms.`,
+					};
+				},
+			});
+			return {};
+		},
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.7.8",
+	"version": "0.7.10",
 	"description": "A plugin-driven Pi agent server for Discord",
 	"type": "module",
 	"license": "MIT",

package/src/core/builtin/modules.ts

@@ -3,6 +3,7 @@ import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import type { SurfacePort } from "../contract/surface.ts";
 import { scheduleCommands } from "../discord/schedule-commands.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
+import { messages } from "../i18n/index.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import type { ModelRef, ThinkingLevel } from "../models.ts";
 import { ConversationBackgroundTurns } from "../modules/background/background-turns.ts";
@@ -20,6 +21,7 @@ import {
 	AGENTS,
 	BACKGROUND_TURNS,
 	DELEGATION,
+	PRECHECKS,
 	SCHEDULES,
 } from "../services.ts";
 import type { SessionContext } from "../sessions.ts";
@@ -77,6 +79,8 @@ export function modulesPlugin(options: ModulesOptions): RoundtablePlugin {
 		provides: [BACKGROUND_TURNS, DELEGATION],
 		setup: ({ conversations, services, logger, surfaces }) => {
 			const schedules = services.get(SCHEDULES);
+			// Absent when a plugin list leaves the prechecks plugin out: then none can be attached.
+			const prechecks = services.find(PRECHECKS);
 			const discord = services.get(DISCORD);
 			const { connection } = discord;
 			// Another agent's channel, for schedule_list; asked when a tool runs, after the agent server set up.
@@ -121,6 +125,7 @@ export function modulesPlugin(options: ModulesOptions): RoundtablePlugin {
 								store: schedules,
 								owner: { id: owner.id, name: owner.name },
 								channelFor: ownerChannelFor,
+								...(prechecks ? { prechecks } : {}),
 							},
 							session.homeChannel,
 							served(session),
@@ -155,11 +160,24 @@ export function modulesPlugin(options: ModulesOptions): RoundtablePlugin {
 export function schedulerPlugin(): RoundtablePlugin {
 	return {
 		name: "schedules",
-		setup: ({ conversations, services, env, logger }) => {
+		setup: ({ conversations, services, env, logger, surfaces }) => {
 			const schedules = services.get(SCHEDULES);
+			const prechecks = services.find(PRECHECKS);
 			const scheduler = new Scheduler({
 				store: schedules,
 				runner: services.get(BACKGROUND_TURNS),
+				...(prechecks ? { prechecks } : {}),
+				// The bot's own message: the surface drops it, so it starts no turn.
+				notify: (schedule, note) =>
+					surfaces.sendReply(schedule.channel, {
+						chunks: [
+							messages().schedulePrecheckNote(
+								schedule.id,
+								schedule.title,
+								note,
+							),
+						],
+					}),
 				logger,
 			});
 			// Without Discord there are no schedule commands; the scheduler still fires.

package/src/core/builtin/stores.ts

@@ -1,9 +1,10 @@
 import type { OwnerIdentity } from "../identity.ts";
 import { ownerMemoryExtension } from "../modules/memory/owner-memory.ts";
 import { PgMemoryStore } from "../modules/memory/owner-memory-store.ts";
+import { memoryPrecheckRegistry } from "../modules/schedules/prechecks.ts";
 import { PgScheduleStore } from "../modules/schedules/schedule-store.ts";
 import type { RoundtablePlugin } from "../plugin.ts";
-import { MEMORY, SCHEDULES } from "../services.ts";
+import { MEMORY, PRECHECKS, SCHEDULES } from "../services.ts";
 import { THE_SPEAKER, type Tier } from "../speakers.ts";
 import { fixed } from "./session-tool.ts";
 
@@ -56,7 +57,7 @@ export function memoryPlugin(options: MemoryOptions): RoundtablePlugin {
 export function scheduleStorePlugin(): RoundtablePlugin {
 	return {
 		name: "schedule-store",
-		migrations: [PgScheduleStore.migration],
+		migrations: PgScheduleStore.migrations(),
 		provides: [SCHEDULES],
 		setup: async ({ database, services }) => {
 			services.provide(SCHEDULES, await PgScheduleStore.attach(database()));
@@ -64,3 +65,18 @@ export function scheduleStorePlugin(): RoundtablePlugin {
 		},
 	};
 }
+
+/**
+ * The registry of the host's prechecks, provided as `PRECHECKS`; the plugins after it register
+ * theirs during setup. Apart from the store, so a plugin that replaces the store need not provide it.
+ */
+export function precheckPlugin(): RoundtablePlugin {
+	return {
+		name: "prechecks",
+		provides: [PRECHECKS],
+		setup: ({ services }) => {
+			services.provide(PRECHECKS, memoryPrecheckRegistry());
+			return {};
+		},
+	};
+}

package/src/core/define-roundtable.ts

@@ -8,7 +8,11 @@ import { discordAdminPlugin } from "./builtin/discord-admin.ts";
 import { modulesPlugin, schedulerPlugin } from "./builtin/modules.ts";
 import { seedsPlugin } from "./builtin/seeds.ts";
 import { skillsPlugin } from "./builtin/skills.ts";
-import { memoryPlugin, scheduleStorePlugin } from "./builtin/stores.ts";
+import {
+	memoryPlugin,
+	precheckPlugin,
+	scheduleStorePlugin,
+} from "./builtin/stores.ts";
 import { type RoundtableConfig, resolveConfig } from "./config/config.ts";
 import { ConfigError } from "./domain/errors.ts";
 import { JudgeError } from "./errors.ts";
@@ -163,6 +167,7 @@ export async function defineRoundtable(
 		plugins: [
 			...(config.memory ? [memoryPlugin({ owner })] : []),
 			scheduleStorePlugin(),
+			precheckPlugin(),
 			discordPlugin({
 				token: discord.token,
 				ownerId: owner.id,

package/src/core/discord/schedule-commands.ts

@@ -76,6 +76,9 @@ function section(schedule: Schedule, label: TargetLabel): string {
 			unix(schedule.nextRun),
 		),
 		text.scheduleSetBy(plain(schedule.createdByName), last),
+		...(schedule.precheck
+			? [text.schedulePrecheck(plain(schedule.precheck))]
+			: []),
 		`-# ${plain(prompt)}`,
 	].join("\n");
 }

package/src/core/i18n/schedules.ts

@@ -48,6 +48,9 @@ export function schedulesEn(ctx: CatalogContext) {
 			`${recurrence}; next run <t:${unix}:f>`,
 		scheduleSetBy: (name: string, lastRun: string) =>
 			`Set by ${name}${lastRun}`,
+		schedulePrecheck: (name: string) => `Checked first by precheck ${name}`,
+		schedulePrecheckNote: (id: number, title: string, note: string) =>
+			`-# Schedule #${id} ${title}, skipped by its precheck: ${note.replace(/\n+/g, "\n-# ")}`,
 		scheduleChoice: (id: number, title: string, recurrence: string) =>
 			`#${id} ${title} (${recurrence})`,
 		scheduleTitle: "Schedules",
@@ -87,6 +90,9 @@ export function schedulesZhTW(
 			`${recurrence}；下次 <t:${unix}:f>`,
 		scheduleSetBy: (name: string, lastRun: string) =>
 			`由 ${name} 設定${lastRun}`,
+		schedulePrecheck: (name: string) => `先由預檢 ${name} 判斷`,
+		schedulePrecheckNote: (id: number, title: string, note: string) =>
+			`-# 排程 #${id} ${title} 經預檢略過：${note.replace(/\n+/g, "\n-# ")}`,
 		scheduleChoice: (id: number, title: string, recurrence: string) =>
 			`#${id} ${title}（${recurrence}）`,
 		scheduleTitle: "排程",

package/src/core/modules/background/background-turns.ts

@@ -12,6 +12,7 @@ import {
 	type DelegationOutcome,
 	delegatedTurnText,
 } from "../delegation/delegator.ts";
+import type { PrecheckFinding } from "../schedules/prechecks.ts";
 import type { Schedule } from "../schedules/schedule-store.ts";
 import { scheduledTurnText } from "../schedules/schedule-tools.ts";
 
@@ -33,15 +34,19 @@ export class ConversationBackgroundTurns implements BackgroundTurns {
 		this.#options = options;
 	}
 
-	/** A due schedule's turn, run as its creator's. */
-	runScheduled(schedule: Schedule, firedAt: Date): Promise<ScheduledOutcome> {
+	/** A due schedule's turn, run as its creator's; with what its precheck found, when it has one. */
+	runScheduled(
+		schedule: Schedule,
+		firedAt: Date,
+		finding?: PrecheckFinding,
+	): Promise<ScheduledOutcome> {
 		return this.#options.conversations.background({
 			channel: schedule.channel,
 			target: schedule.target,
 			author: { id: schedule.createdById, name: schedule.createdByName },
 			tier: schedule.createdTier,
 			turnId: `schedule-${schedule.id}-${firedAt.getTime()}`,
-			text: scheduledTurnText(schedule, firedAt),
+			text: scheduledTurnText(schedule, firedAt, finding),
 		});
 	}
 

package/src/core/modules/schedules/prechecks.ts

@@ -0,0 +1,156 @@
+import { PluginError } from "../../errors.ts";
+import type { Schedule } from "./schedule-store.ts";
+
+/** How long a precheck may run before it counts as failed, unless it sets its own `timeoutMs`. */
+export const PRECHECK_TIMEOUT_MS = 60_000;
+
+/** A precheck name: lower-case letters, digits, `.`, `_`, and `-`, starting with a letter or digit. */
+const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+
+/** What a precheck decides about a due schedule. */
+export type PrecheckResult =
+	| {
+			/** Skip the turn. A note is posted in the schedule's channel as the bot's own small message, which starts no turn. */
+			wake: false;
+			note?: string;
+	  }
+	| {
+			/** Start the scheduled turn; its text carries `context` under a "Precheck found" heading. */
+			wake: true;
+			context: string;
+	  };
+
+/** What a precheck is given when its schedule falls due. */
+export interface PrecheckContext {
+	/** The due schedule, already moved to its next run (or deleted, when it runs once). */
+	schedule: Schedule;
+	firedAt: Date;
+	/** Aborted when the precheck runs out of time; its answer is then ignored. */
+	signal: AbortSignal;
+}
+
+/**
+ * A cheap check the host runs before a schedule's turn, so the agent is woken only when there is
+ * something to do. Host code registers it by name; the model can only attach a registered name to
+ * a schedule, never supply code or a command.
+ */
+export interface Precheck {
+	/** Unique on the host, such as `"health.recovery"`: lower-case letters, digits, `.`, `_`, `-`. */
+	name: string;
+	/** What it checks and when it wakes the agent, shown to the model by schedule_list. */
+	description: string;
+	/** How long it may run; default 60 seconds. A timeout counts as a throw. */
+	timeoutMs?: number;
+	/** Decides whether the turn runs. A throw starts the turn with the error, so the agent can look into it. */
+	run(context: PrecheckContext): PrecheckResult | Promise<PrecheckResult>;
+}
+
+/** The host's prechecks, by name. Provided as `PRECHECKS` by the `prechecks` plugin. */
+export interface PrecheckRegistry {
+	/** Adds a precheck; throws PluginError for a bad or repeated name, an empty description, or a bad timeout. */
+	register(precheck: Precheck): void;
+	get(name: string): Precheck | undefined;
+	/** Every registered precheck, by name. */
+	list(): readonly Precheck[];
+}
+
+/** What came of a precheck that let the turn run, carried into the turn's text. */
+export type PrecheckFinding =
+	| { precheck: string; context: string }
+	| { precheck: string; error: string };
+
+/** The decision of one precheck run, with a throw, a timeout, or a bad answer as `failed`. */
+export type PrecheckOutcome =
+	| { kind: "skip"; note?: string }
+	| { kind: "wake"; context: string }
+	| { kind: "failed"; error: string };
+
+/**
+ * Prechecks kept in memory, as the host registers them while its plugins set up. Its methods
+ * close over the map instead of private fields, so a test may hand it over through a proxy.
+ */
+export function memoryPrecheckRegistry(): PrecheckRegistry {
+	const prechecks = new Map<string, Precheck>();
+	return {
+		register(precheck) {
+			const { name, description, timeoutMs, run } = precheck ?? {};
+			if (typeof name !== "string" || !NAME.test(name))
+				throw new PluginError(
+					`a precheck needs a name of lower-case letters, digits, ".", "_", and "-", such as "health.recovery"; got ${JSON.stringify(name)}.`,
+				);
+			if (prechecks.has(name))
+				throw new PluginError(
+					`precheck ${name} is already registered; give each precheck its own name.`,
+				);
+			if (typeof description !== "string" || !description.trim())
+				throw new PluginError(
+					`precheck ${name} needs a description: what it checks and when it wakes the agent.`,
+				);
+			if (
+				timeoutMs !== undefined &&
+				!(Number.isInteger(timeoutMs) && timeoutMs > 0)
+			)
+				throw new PluginError(
+					`precheck ${name}: timeoutMs must be a positive whole number of milliseconds; got ${String(timeoutMs)}.`,
+				);
+			if (typeof run !== "function")
+				throw new PluginError(`precheck ${name} needs a run function.`);
+			prechecks.set(name, Object.freeze({ ...precheck }));
+		},
+		get: (name) => prechecks.get(name),
+		list: () =>
+			[...prechecks.values()].sort((a, b) => a.name.localeCompare(b.name)),
+	};
+}
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? error.message || error.name : String(error);
+}
+
+/** Checks a precheck's answer, so a wrong shape fails like a throw instead of waking silently. */
+function decided(result: unknown): PrecheckOutcome {
+	if (result && typeof result === "object" && "wake" in result) {
+		const answer = result as Record<string, unknown>;
+		if (answer.wake === false) {
+			const note = typeof answer.note === "string" ? answer.note.trim() : "";
+			return note ? { kind: "skip", note } : { kind: "skip" };
+		}
+		if (answer.wake === true && typeof answer.context === "string")
+			return { kind: "wake", context: answer.context };
+	}
+	return {
+		kind: "failed",
+		error: `it answered ${JSON.stringify(result)}, not { wake: false, note? } or { wake: true, context }`,
+	};
+}
+
+/** Runs one precheck within its timeout; never rejects. */
+export async function runPrecheck(
+	precheck: Precheck,
+	context: Omit<PrecheckContext, "signal">,
+): Promise<PrecheckOutcome> {
+	const timeoutMs = precheck.timeoutMs ?? PRECHECK_TIMEOUT_MS;
+	const abort = new AbortController();
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timeout = new Promise<PrecheckOutcome>((resolve) => {
+		timer = setTimeout(() => {
+			abort.abort();
+			resolve({
+				kind: "failed",
+				error: `it did not answer within ${timeoutMs / 1000} seconds`,
+			});
+		}, timeoutMs);
+	});
+	const answer = (async (): Promise<PrecheckOutcome> => {
+		try {
+			return decided(await precheck.run({ ...context, signal: abort.signal }));
+		} catch (error) {
+			return { kind: "failed", error: `it threw: ${errorText(error)}` };
+		}
+	})();
+	try {
+		return await Promise.race([answer, timeout]);
+	} finally {
+		clearTimeout(timer);
+	}
+}

package/src/core/modules/schedules/schedule-store.ts

@@ -19,6 +19,8 @@ export interface Schedule {
 	/** The creator's tier when it was set; the schedule runs at it and lower tiers may not change it. */
 	createdTier: Tier;
 	createdAt: Date;
+	/** The name of the precheck the host runs before its turn; absent, the turn always runs. */
+	precheck?: string;
 	lastRun?: Date;
 	lastStatus?: string;
 }
@@ -33,6 +35,8 @@ export interface NewSchedule {
 	createdById: string;
 	createdByName: string;
 	createdTier: Tier;
+	/** A registered precheck's name, run before each turn. */
+	precheck?: string;
 }
 
 export interface ScheduleChange {
@@ -40,6 +44,8 @@ export interface ScheduleChange {
 	prompt?: string;
 	recurrence?: Recurrence;
 	nextRun?: Date;
+	/** A registered precheck's name to run before each turn; null removes the schedule's precheck. */
+	precheck?: string | null;
 }
 
 interface Row {
@@ -55,6 +61,7 @@ interface Row {
 	created_by_name: string;
 	created_tier: Tier;
 	created_at: Date;
+	precheck: string | null;
 	last_run: Date | null;
 	last_status: string | null;
 }
@@ -73,6 +80,7 @@ function toSchedule(row: Row): Schedule {
 		createdByName: row.created_by_name,
 		createdTier: row.created_tier,
 		createdAt: row.created_at,
+		...(row.precheck ? { precheck: row.precheck } : {}),
 		...(row.last_run ? { lastRun: row.last_run } : {}),
 		...(row.last_status ? { lastStatus: row.last_status } : {}),
 	};
@@ -112,6 +120,19 @@ export class PgScheduleStore implements ScheduleStore {
 		},
 	};
 
+	/** The table, then the precheck each schedule may name; schedules made before prechecks have none. */
+	static migrations(): Migration[] {
+		return [
+			PgScheduleStore.migration,
+			{
+				name: "schedules-precheck",
+				up: async (sql) => {
+					await sql`ALTER TABLE schedules ADD COLUMN IF NOT EXISTS precheck text`;
+				},
+			},
+		];
+	}
+
 	/** The store over the host's migrated pool. */
 	static async attach(sql: SQL): Promise<PgScheduleStore> {
 		return new PgScheduleStore(sql);
@@ -120,10 +141,11 @@ export class PgScheduleStore implements ScheduleStore {
 	async create(schedule: NewSchedule): Promise<Schedule> {
 		const rows: Row[] = await this.#sql`
 			INSERT INTO schedules (channel_key, mode, title, prompt, recurrence, next_run,
-				created_by_id, created_by_name, created_tier)
+				created_by_id, created_by_name, created_tier, precheck)
 			VALUES (${schedule.channel}, ${schedule.target}, ${schedule.title}, ${schedule.prompt},
 				${JSON.stringify(schedule.recurrence)}, ${schedule.nextRun},
-				${schedule.createdById}, ${schedule.createdByName}, ${schedule.createdTier})
+				${schedule.createdById}, ${schedule.createdByName}, ${schedule.createdTier},
+				${schedule.precheck ?? null})
 			RETURNING *`;
 		const [row] = rows;
 		if (!row) throw new Error("the schedule insert returned no row");
@@ -161,7 +183,8 @@ export class PgScheduleStore implements ScheduleStore {
 				title = ${change.title ?? current.title},
 				prompt = ${change.prompt ?? current.prompt},
 				recurrence = ${JSON.stringify(change.recurrence ?? current.recurrence)},
-				next_run = ${change.nextRun ?? current.nextRun}
+				next_run = ${change.nextRun ?? current.nextRun},
+				precheck = ${change.precheck === undefined ? (current.precheck ?? null) : change.precheck}
 			WHERE id = ${id}
 			RETURNING *`;
 		return rows[0] ? toSchedule(rows[0]) : undefined;

package/src/core/modules/schedules/schedule-tools.ts

@@ -6,6 +6,7 @@ import type { ScheduleStore } from "../../services.ts";
 import type { ScheduleToolName } from "../../shared/schedule-tools.ts";
 import { type Tier, tierAtLeast } from "../../speakers.ts";
 import { timeZone, zonedStamp } from "../../time.ts";
+import type { PrecheckFinding, PrecheckRegistry } from "./prechecks.ts";
 import {
 	describeRecurrence,
 	nextRun,
@@ -30,6 +31,8 @@ export interface ScheduleToolContext {
 	/** Who asked, recorded on created schedules; a scheduled run speaks for its creator. */
 	author: { id: string; name: string; tier?: Tier };
 	now: Date;
+	/** The host's prechecks a schedule may name; without them, none can be attached. */
+	prechecks?: Pick<PrecheckRegistry, "get" | "list">;
 }
 
 /** The limits of the context's target; a target without them may not schedule. */
@@ -64,6 +67,30 @@ function id(input: Input): number {
 	return value;
 }
 
+/** A registered precheck's name; an unknown one is refused with the names there are. */
+function precheckName(ctx: ScheduleToolContext, value: unknown): string {
+	const names = (ctx.prechecks?.list() ?? []).map((p) => p.name);
+	if (typeof value !== "string" || !value.trim())
+		throw new ScheduleError(
+			`precheck must be the name of a registered precheck${names.length ? `: ${names.join(", ")}` : "; this host registers none"}`,
+		);
+	const name = value.trim();
+	if (!ctx.prechecks?.get(name))
+		throw new ScheduleError(
+			names.length
+				? `there is no precheck "${name}"; the registered ones are ${names.join(", ")}`
+				: `there is no precheck "${name}"; this host registers none`,
+		);
+	return name;
+}
+
+/** The prechecks a schedule may name, for schedule_list; empty when the host registers none. */
+function precheckCatalog(ctx: ScheduleToolContext): string {
+	const all = ctx.prechecks?.list() ?? [];
+	if (all.length === 0) return "";
+	return `\n\nPrechecks you can attach with precheck on schedule_create or schedule_update; the host runs one before each turn and wakes you only when it finds something:\n${all.map((p) => `- ${p.name}: ${p.description.replace(/\n/g, " ")}`).join("\n")}`;
+}
+
 function hasTiming(input: Input): boolean {
 	return [
 		"in_minutes",
@@ -94,10 +121,11 @@ function line(schedule: Schedule): string {
 		schedule.prompt.length > LIST_PROMPT_PREVIEW
 			? `${schedule.prompt.slice(0, LIST_PROMPT_PREVIEW)}…`
 			: schedule.prompt;
+	const precheck = schedule.precheck ? `; precheck ${schedule.precheck}` : "";
 	const last = schedule.lastRun
 		? `; last run ${zonedStamp(schedule.lastRun)} (${schedule.lastStatus ?? "?"})`
 		: "";
-	return `- #${schedule.id} ${schedule.title}: ${describeRecurrence(schedule.recurrence)}, next ${zonedStamp(schedule.nextRun)}; set by ${schedule.createdByName}${last}\n  ${prompt.replace(/\n/g, " ")}`;
+	return `- #${schedule.id} ${schedule.title}: ${describeRecurrence(schedule.recurrence)}, next ${zonedStamp(schedule.nextRun)}; set by ${schedule.createdByName}${precheck}${last}\n  ${prompt.replace(/\n/g, " ")}`;
 }
 
 async function own(ctx: ScheduleToolContext, input: Input): Promise<Schedule> {
@@ -131,6 +159,10 @@ export async function callScheduleTool(
 			const title = text(input, "title", TITLE_CHARS);
 			const prompt = text(input, "prompt", limits.promptChars);
 			const [recurrence, next] = timing(ctx, input);
+			const precheck =
+				input.precheck === undefined || input.precheck === null
+					? undefined
+					: precheckName(ctx, input.precheck);
 			const existing = await ctx.store.forChannel(ctx.channel);
 			if (existing.length >= limits.perChannel)
 				throw new ScheduleError(
@@ -146,8 +178,10 @@ export async function callScheduleTool(
 				createdById: ctx.author.id,
 				createdByName: ctx.author.name,
 				createdTier: ctx.author.tier ?? "owner",
+				...(precheck ? { precheck } : {}),
 			});
-			return `Scheduled #${created.id} "${title}": ${describeRecurrence(recurrence)}, first run ${zonedStamp(next)} ${messages().zoneTime(timeZone())}.`;
+			const checked = precheck ? `; precheck ${precheck} runs first` : "";
+			return `Scheduled #${created.id} "${title}": ${describeRecurrence(recurrence)}, first run ${zonedStamp(next)} ${messages().zoneTime(timeZone())}${checked}.`;
 		}
 		case "schedule_list": {
 			if (input.id !== undefined) {
@@ -155,9 +189,11 @@ export async function callScheduleTool(
 				return `${line(schedule).split("\n")[0]}\n\nPrompt:\n${schedule.prompt}`;
 			}
 			const all = await ctx.store.forChannel(ctx.channel);
-			return all.length === 0
-				? "This channel has no schedules."
-				: `It is ${zonedStamp(ctx.now)} in ${messages().zoneName(timeZone())}.\n${all.map(line).join("\n")}`;
+			const listed =
+				all.length === 0
+					? "This channel has no schedules."
+					: `It is ${zonedStamp(ctx.now)} in ${messages().zoneName(timeZone())}.\n${all.map(line).join("\n")}`;
+			return `${listed}${precheckCatalog(ctx)}`;
 		}
 		case "schedule_update": {
 			const schedule = changeable(ctx, await own(ctx, input));
@@ -171,11 +207,20 @@ export async function callScheduleTool(
 				change.recurrence = recurrence;
 				change.nextRun = next;
 			}
+			// null removes the precheck; a name must be registered.
+			if (input.precheck !== undefined)
+				change.precheck =
+					input.precheck === null ? null : precheckName(ctx, input.precheck);
 			if (Object.keys(change).length === 0)
-				throw new ScheduleError("give a title, prompt, or timing to change");
+				throw new ScheduleError(
+					"give a title, prompt, timing, or precheck to change",
+				);
 			const updated = await ctx.store.update(ctx.channel, schedule.id, change);
 			if (!updated) throw new ScheduleError(`schedule #${schedule.id} is gone`);
-			return `Updated #${updated.id} "${updated.title}": ${describeRecurrence(updated.recurrence)}, next run ${zonedStamp(updated.nextRun)}.`;
+			const checked = updated.precheck
+				? `; precheck ${updated.precheck} runs first`
+				: "";
+			return `Updated #${updated.id} "${updated.title}": ${describeRecurrence(updated.recurrence)}, next run ${zonedStamp(updated.nextRun)}${checked}.`;
 		}
 		case "schedule_cancel": {
 			const schedule = changeable(ctx, await own(ctx, input));
@@ -187,12 +232,28 @@ export async function callScheduleTool(
 	}
 }
 
-/** What a scheduled run receives as its message. */
-export function scheduledTurnText(schedule: Schedule, firedAt: Date): string {
+/** What the schedule's precheck found, or how it failed, under its own heading after the task. */
+function findingText(finding: PrecheckFinding): string[] {
+	return "error" in finding
+		? [
+				"",
+				`### Precheck failed: ${finding.precheck}`,
+				`The precheck that decides whether this task needs you failed, so you were woken anyway: ${finding.error}. Check what it watches yourself, and say so if it needs fixing.`,
+			]
+		: ["", `### Precheck found (${finding.precheck}):`, finding.context];
+}
+
+/** What a scheduled run receives as its message, with what its precheck found when it has one. */
+export function scheduledTurnText(
+	schedule: Schedule,
+	firedAt: Date,
+	finding?: PrecheckFinding,
+): string {
 	return [
 		`## Scheduled task #${schedule.id}: ${schedule.title}`,
 		`${schedule.createdByName} set this schedule (${describeRecurrence(schedule.recurrence)}). It is due now, ${zonedStamp(firedAt)} ${messages().zoneTime(timeZone())}. Nobody wrote a new message: carry out the task below and write what you would post in this channel. If the task keeps a record for later runs, update it with schedule_update on #${schedule.id}.`,
 		"",
 		schedule.prompt,
+		...(finding ? findingText(finding) : []),
 	].join("\n");
 }

package/src/core/modules/schedules/scheduler.ts

@@ -1,14 +1,24 @@
 import type { ScheduledOutcome } from "../../contract/channels.ts";
 import type { Logger } from "../../log.ts";
 import type { ScheduleStore } from "../../services.ts";
+import {
+	type PrecheckFinding,
+	type PrecheckOutcome,
+	type PrecheckRegistry,
+	runPrecheck,
+} from "./prechecks.ts";
 import { nextRun } from "./recurrence.ts";
 import type { Schedule } from "./schedule-store.ts";
 
 export type { ScheduledOutcome };
 
 export interface ScheduledRunner {
-	/** Runs one due schedule in its channel and posts the answer there; never rejects. */
-	runScheduled(schedule: Schedule, firedAt: Date): Promise<ScheduledOutcome>;
+	/** Runs one due schedule in its channel and posts the answer there, with what its precheck found; never rejects. */
+	runScheduled(
+		schedule: Schedule,
+		firedAt: Date,
+		finding?: PrecheckFinding,
+	): Promise<ScheduledOutcome>;
 }
 
 /** A run found this late, for example after the service was down, is skipped instead of run. */
@@ -17,18 +27,24 @@ export const LATE_LIMIT_MS = 12 * 3_600_000;
 export interface SchedulerOptions {
 	store: Pick<ScheduleStore, "due" | "claim" | "recordStatus">;
 	runner: ScheduledRunner;
+	/** The host's prechecks; without them, a schedule that names one runs with that as its error. */
+	prechecks?: Pick<PrecheckRegistry, "get">;
+	/** Posts a skipping precheck's note in the schedule's channel as the bot's own message, which starts no turn. */
+	notify?: (schedule: Schedule, note: string) => Promise<void>;
 	logger: Logger;
 	intervalMs?: number;
 	/** Replaceable in tests. */
 	now?: () => Date;
 }
 
+const STATUS_CHARS = 300;
+
 function statusText(outcome: ScheduledOutcome): string {
 	switch (outcome.status) {
 		case "ran":
 			return "ran";
 		case "failed":
-			return `failed: ${outcome.error}`.slice(0, 300);
+			return `failed: ${outcome.error}`;
 		case "skipped":
 			return `skipped: ${outcome.reason}`;
 		default:
@@ -36,6 +52,14 @@ function statusText(outcome: ScheduledOutcome): string {
 	}
 }
 
+/** How the precheck let the turn run, before the turn's own outcome. */
+function precheckPrefix(finding: PrecheckFinding | undefined): string {
+	if (!finding) return "";
+	return "error" in finding
+		? `precheck failed (${finding.error}), woke; `
+		: "woken by precheck; ";
+}
+
 /**
  * Checks for due schedules on an interval. Each due schedule is claimed first, moved to its
  * next run or deleted, so a slow or failing run never fires twice; missed runs are not caught up.
@@ -106,7 +130,23 @@ export class Scheduler {
 	}
 
 	async #fire(schedule: Schedule, firedAt: Date): Promise<void> {
-		const { store, runner, logger } = this.#options;
+		const { runner, logger } = this.#options;
+		let finding: PrecheckFinding | undefined;
+		if (schedule.precheck) {
+			const decision = await this.#precheck(
+				schedule,
+				schedule.precheck,
+				firedAt,
+			);
+			if (decision.kind === "skip") {
+				await this.#skip(schedule, decision.note);
+				return;
+			}
+			finding =
+				decision.kind === "wake"
+					? { precheck: schedule.precheck, context: decision.context }
+					: { precheck: schedule.precheck, error: decision.error };
+		}
 		logger.info(
 			{
 				schedule: schedule.id,
@@ -115,10 +155,72 @@ export class Scheduler {
 			},
 			"schedule firing",
 		);
-		const outcome = await runner.runScheduled(schedule, firedAt);
+		const outcome = await runner.runScheduled(schedule, firedAt, finding);
 		logger.info({ schedule: schedule.id, outcome }, "schedule finished");
+		await this.#record(
+			schedule,
+			`${precheckPrefix(finding)}${statusText(outcome)}`,
+		);
+	}
+
+	/** Runs the schedule's precheck; a missing one fails like a throw, so the turn still runs. */
+	async #precheck(
+		schedule: Schedule,
+		name: string,
+		firedAt: Date,
+	): Promise<PrecheckOutcome> {
+		const { prechecks, logger } = this.#options;
+		let decision: PrecheckOutcome;
+		try {
+			const precheck = prechecks?.get(name);
+			decision = precheck
+				? await runPrecheck(precheck, { schedule, firedAt })
+				: { kind: "failed", error: "no precheck of that name is registered" };
+		} catch (error) {
+			decision = {
+				kind: "failed",
+				error: `the precheck could not be looked up: ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+		// A warning, not an error: the woken turn carries the error already, and an error line would
+		// wake the ops agent's report turn for the same failure.
+		if (decision.kind === "failed")
+			logger.warn(
+				{ schedule: schedule.id, precheck: name, error: decision.error },
+				"precheck failed; the scheduled turn runs with the error",
+			);
+		else
+			logger.info(
+				{
+					schedule: schedule.id,
+					precheck: name,
+					wake: decision.kind === "wake",
+				},
+				"precheck decided",
+			);
+		return decision;
+	}
+
+	/** Records a run the precheck skipped and posts its note; a note that cannot be posted is logged. */
+	async #skip(schedule: Schedule, note: string | undefined): Promise<void> {
+		const { notify, logger } = this.#options;
+		if (note && notify)
+			await notify(schedule, note).catch((error: unknown) =>
+				logger.warn(
+					{ schedule: schedule.id, err: error },
+					"precheck note not posted",
+				),
+			);
+		await this.#record(
+			schedule,
+			note ? `skipped by precheck (${note})` : "skipped by precheck",
+		);
+	}
+
+	async #record(schedule: Schedule, status: string): Promise<void> {
+		const { store, logger } = this.#options;
 		await store
-			.recordStatus(schedule.id, statusText(outcome))
+			.recordStatus(schedule.id, status.slice(0, STATUS_CHARS))
 			.catch((error: unknown) =>
 				logger.error(
 					{ schedule: schedule.id, err: error },

package/src/core/modules/schedules/schedules.ts

@@ -16,6 +16,7 @@ import {
 } from "../../shared/schedule-tools.ts";
 import type { Speaker } from "../../speakers.ts";
 import { timeZone } from "../../time.ts";
+import type { PrecheckRegistry } from "./prechecks.ts";
 import { callScheduleTool } from "./schedule-tools.ts";
 
 export interface OwnerSchedules {
@@ -26,6 +27,8 @@ export interface OwnerSchedules {
 	 * messages for a conversation no chat surface carries, where a run could not be posted.
 	 */
 	channelFor: (channel: ChannelKey) => Promise<ChannelKey>;
+	/** The host's prechecks a schedule may name; without them, none can be attached. */
+	prechecks?: Pick<PrecheckRegistry, "get" | "list">;
 }
 
 /** Finds another agent's channel, for reading its schedules; throws ScheduleError when there is none. */
@@ -58,7 +61,7 @@ export function schedulesExtension(
 	/** The person the running turn is for; their schedules run at their tier. */
 	speaker: () => Speaker | undefined = () => undefined,
 ): ExtensionFactory {
-	const { store, owner, channelFor } = schedules;
+	const { store, owner, channelFor, prechecks } = schedules;
 	const defs = scheduleToolSpecs({
 		locale: activeLocale(),
 		timeZone: timeZone(),
@@ -79,6 +82,7 @@ export function schedulesExtension(
 						target: OWNER_TARGET,
 						author: speaker() ?? owner,
 						now: new Date(),
+						...(prechecks ? { prechecks } : {}),
 					},
 					spec.name,
 					input,

package/src/core/services.ts

@@ -16,6 +16,10 @@ import type {
 	MemoryKind,
 	PromptMemory,
 } from "./modules/memory/owner-memory-store.ts";
+import type {
+	PrecheckFinding,
+	PrecheckRegistry,
+} from "./modules/schedules/prechecks.ts";
 import type {
 	NewSchedule,
 	Schedule,
@@ -38,6 +42,13 @@ export const AGENTS: ServiceKey<AgentServer> =
 export const SCHEDULES: ServiceKey<ScheduleStore> = serviceKey<ScheduleStore>(
 	"roundtable.schedules",
 );
+/**
+ * The host's named prechecks, which a schedule may run before its turn to decide whether the
+ * agent is woken at all. Provided by the `prechecks` plugin; register yours during setup:
+ * `services.get(PRECHECKS).register({ name, description, run })`.
+ */
+export const PRECHECKS: ServiceKey<PrecheckRegistry> =
+	serviceKey<PrecheckRegistry>("roundtable.prechecks");
 /** Turns nobody wrote: a due schedule's, a delegated task's report, a logged error's. Provided by the modules plugin. */
 export const BACKGROUND_TURNS: ServiceKey<BackgroundTurns> =
 	serviceKey<BackgroundTurns>("roundtable.background-turns");
@@ -177,8 +188,12 @@ export interface ScheduleStore {
 
 /** Turns nobody wrote, each answered in its channel by the claim that owns it. */
 export interface BackgroundTurns {
-	/** A due schedule's turn, run as its creator's. */
-	runScheduled(schedule: Schedule, firedAt: Date): Promise<ScheduledOutcome>;
+	/** A due schedule's turn, run as its creator's; with what its precheck found, when it has one. */
+	runScheduled(
+		schedule: Schedule,
+		firedAt: Date,
+		finding?: PrecheckFinding,
+	): Promise<ScheduledOutcome>;
 	/** A delegated task's report, answered in its channel under the same rules as a schedule. */
 	runDelegated(job: DelegationJob, result: DelegationOutcome): Promise<void>;
 	/** The process's own logged error, reported to an agent in its channel as a report turn. */

package/src/core/shared/schedule-tools.ts

@@ -91,12 +91,18 @@ export function scheduleToolSpecs(
 					description: "What to do when it runs, self-contained.",
 				}),
 				...timing(zone),
+				precheck: Type.Optional(
+					Type.String({
+						description:
+							"The name of a precheck the host runs first, from schedule_list; you are woken only when it finds something.",
+					}),
+				),
 			}),
 		},
 		{
 			name: "schedule_list",
 			label: "List schedules",
-			description: `List this channel's schedules with their next run, and the current ${zone}. Give id to read one schedule's full prompt.`,
+			description: `List this channel's schedules with their next run, and the current ${zone}, and the prechecks a schedule may attach. Give id to read one schedule's full prompt.`,
 			parameters: Type.Object({
 				id: Type.Optional(Type.Integer({ description: "Schedule id." })),
 			}),
@@ -105,7 +111,7 @@ export function scheduleToolSpecs(
 			name: "schedule_update",
 			label: "Update schedule",
 			description:
-				"Change one of this channel's schedules: its title, its prompt, or its timing (timing fields replace the old timing). A run can use this to keep its own prompt current, such as adding what it already reported.",
+				"Change one of this channel's schedules: its title, its prompt, its timing (timing fields replace the old timing), or its precheck. A run can use this to keep its own prompt current, such as adding what it already reported.",
 			parameters: Type.Object({
 				id: Type.Integer({ description: "Schedule id." }),
 				title: Type.Optional(Type.String()),
@@ -113,6 +119,12 @@ export function scheduleToolSpecs(
 					Type.String({ description: "The whole new prompt." }),
 				),
 				...timing(zone),
+				precheck: Type.Optional(
+					Type.Union([Type.String(), Type.Null()], {
+						description:
+							"A precheck's name from schedule_list to run first, or null to remove the schedule's precheck.",
+					}),
+				),
 			}),
 		},
 		{

package/src/core/testing/prechecks.ts

@@ -0,0 +1,56 @@
+import {
+	memoryPrecheckRegistry,
+	type Precheck,
+	type PrecheckContext,
+	type PrecheckRegistry,
+	type PrecheckResult,
+} from "../modules/schedules/prechecks.ts";
+
+/** What a fake precheck answers: a result, an Error it throws, or a function of its context. */
+export type FakePrecheckAnswer =
+	| PrecheckResult
+	| Error
+	| ((context: PrecheckContext) => PrecheckResult | Promise<PrecheckResult>);
+
+/** A precheck for tests, which records every context it ran with. */
+export interface FakePrecheck extends Precheck {
+	readonly calls: PrecheckContext[];
+}
+
+/**
+ * A precheck that answers as the test says, for registering where host code would:
+ * `services.get(PRECHECKS).register(fakePrecheck("health.recovery", { wake: false }))`, or into
+ * `fakePrechecks(...)`. An Error answer is thrown, as a failing check would.
+ */
+export function fakePrecheck(
+	name: string,
+	answer: FakePrecheckAnswer,
+	options: { description?: string; timeoutMs?: number } = {},
+): FakePrecheck {
+	const calls: PrecheckContext[] = [];
+	return {
+		name,
+		description: options.description ?? `A test precheck, ${name}.`,
+		...(options.timeoutMs === undefined
+			? {}
+			: { timeoutMs: options.timeoutMs }),
+		calls,
+		run: async (context) => {
+			calls.push(context);
+			if (answer instanceof Error) throw answer;
+			return typeof answer === "function" ? answer(context) : answer;
+		},
+	};
+}
+
+/**
+ * A real in-memory precheck registry with the given prechecks registered, for a test that builds
+ * a scheduler or schedule tools itself. It refuses what the host's refuses.
+ */
+export function fakePrechecks(
+	...prechecks: readonly Precheck[]
+): PrecheckRegistry {
+	const registry = memoryPrecheckRegistry();
+	for (const precheck of prechecks) registry.register(precheck);
+	return registry;
+}

package/src/index.ts

@@ -126,6 +126,14 @@ export type {
 	PromptMemory,
 } from "./core/modules/memory/owner-memory-store.ts";
 export { MEMORY_KINDS } from "./core/modules/memory/owner-memory-store.ts";
+export type {
+	Precheck,
+	PrecheckContext,
+	PrecheckFinding,
+	PrecheckRegistry,
+	PrecheckResult,
+} from "./core/modules/schedules/prechecks.ts";
+export { PRECHECK_TIMEOUT_MS } from "./core/modules/schedules/prechecks.ts";
 export type {
 	Recurrence,
 	Weekday,
@@ -187,6 +195,7 @@ export {
 	BACKGROUND_TURNS,
 	DELEGATION,
 	MEMORY,
+	PRECHECKS,
 	SCHEDULES,
 	SKILLS,
 } from "./core/services.ts";

package/src/kit/compaction.ts

@@ -0,0 +1,14 @@
+// The core's compaction tiers, for a host that builds its own Pi session (a sandbox worker, say).
+
+export type {
+	CompactionEngine,
+	CompactionHistory,
+	LatestCompaction,
+} from "../core/runtime/compaction-tiers.ts";
+export {
+	COMPACT_HEADROOM_TOKENS,
+	CompactionTiers,
+	compactionEngine,
+	HARD_COMPACT_TOKENS,
+	SOFT_COMPACT_TOKENS,
+} from "../core/runtime/compaction-tiers.ts";

package/src/kit/index.ts

@@ -14,6 +14,18 @@ export {
 	withAttachmentsBlock,
 	withReference,
 } from "./channels.ts";
+export type {
+	CompactionEngine,
+	CompactionHistory,
+	LatestCompaction,
+} from "./compaction.ts";
+export {
+	COMPACT_HEADROOM_TOKENS,
+	CompactionTiers,
+	compactionEngine,
+	HARD_COMPACT_TOKENS,
+	SOFT_COMPACT_TOKENS,
+} from "./compaction.ts";
 export { scrubDiagnostic } from "./diagnostics.ts";
 export type {
 	ChoiceAnswer,

package/src/testing.ts

@@ -83,6 +83,11 @@ export type { TestLocale } from "./core/testing/locale.ts";
 export { useTestLocale } from "./core/testing/locale.ts";
 export { OWNER_SPEAKER } from "./core/testing/owner.ts";
 export { partial } from "./core/testing/partial.ts";
+export type {
+	FakePrecheck,
+	FakePrecheckAnswer,
+} from "./core/testing/prechecks.ts";
+export { fakePrecheck, fakePrechecks } from "./core/testing/prechecks.ts";
 export type {
 	RecordedLog,
 	RecordingLogger,