@intentic/sandbox-contract 1.326.0 → 1.327.0

package/src/protocol/sse.ts

@@ -2,25 +2,40 @@
 // a blank line, each carrying one `data: <JSON>` line. Protocol-only (no domain shapes), shared by every
 // consumer of the wire: the web's chat/intentic streams and the ACP bridge's daemon client.
 
+// A live daemon writes to a stream at least this often (oRPC's keep-alive comment every 5 s, a heartbeat on the rest), so
+// this long with no bytes means the connection is dead even though nothing closed it.
+export const SSE_IDLE_MS = 120_000;
+
 // Yields each raw SSE frame (the text between blank-line separators) as it arrives, reassembling frames split
-// across network chunks.
-export async function* sseFrames(body: ReadableStream<Uint8Array>): AsyncGenerator<string> {
+// across network chunks. Ends, cancelling the reader, after `idleMs` of silence, so a reader of a daemon that went quiet
+// without closing (a sleeping laptop's tunnel, a wedged proxy) finishes instead of hanging.
+export async function* sseFrames(body: ReadableStream<Uint8Array>, idleMs: number = SSE_IDLE_MS): AsyncGenerator<string> {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
-    for (;;) {
-        // oxlint-disable-next-line eslint/no-await-in-loop -- streaming reader; each chunk must be awaited in order as it arrives
-        const { done, value } = await reader.read();
-        if (done) {
-            break;
-        }
-        buffer += decoder.decode(value, { stream: true });
-        let separator = buffer.indexOf("\n\n");
-        while (separator !== -1) {
-            yield buffer.slice(0, separator);
-            buffer = buffer.slice(separator + 2);
-            separator = buffer.indexOf("\n\n");
+    try {
+        for (;;) {
+            let timer: ReturnType<typeof setTimeout> | undefined;
+            const idle = new Promise<"idle">((resolve) => {
+                timer = setTimeout(() => resolve("idle"), idleMs);
+            });
+            // oxlint-disable-next-line eslint/no-await-in-loop -- streaming reader; each chunk must be awaited in order as it arrives
+            const result = await Promise.race([reader.read(), idle]);
+            clearTimeout(timer);
+            if (result === "idle" || result.done) {
+                return;
+            }
+            buffer += decoder.decode(result.value, { stream: true });
+            let separator = buffer.indexOf("\n\n");
+            while (separator !== -1) {
+                yield buffer.slice(0, separator);
+                buffer = buffer.slice(separator + 2);
+                separator = buffer.indexOf("\n\n");
+            }
         }
+    } finally {
+        // allow(silent-catch): A stream already errored or closed has nothing left to cancel.
+        await reader.cancel().catch(() => undefined);
     }
 }
 

package/src/protocol/tunnel-bulk.test.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { servedRoute } from "./routes.js";
-import { RAW_ROUTE_LIST } from "./raw-routes.js";
+import { RAW_ROUTE_LIST } from "./raw/raw-routes.js";
 import { hostOwnerId } from "./ingress-contract.js";
 import { tunnelBulkRoutes } from "./tunnel-bulk.js";
 

package/src/protocol/tunnel-bulk.ts

@@ -1,6 +1,6 @@
-import { RAW_ROUTE_LIST } from "./raw-routes.js";
+import { RAW_ROUTE_LIST } from "./raw/raw-routes.js";
 
-// What the daemon announces to the edge as its transfers (RouteMeta `lane`), handed to the front with the tunnel's door
+// What the daemon announces to the edge as its transfers (RouteMeta `lane`), handed to netd with the tunnel's door
 // and carried on each of its sockets' upgrades (the tunnel crate's `x-intentic-bulk`), so the edge sends a transfer
 // down the bulk socket and a keystroke never queues behind it on one TCP connection. The edge compiles in nothing of it.
 export const tunnelBulkRoutes = (): string[] =>

package/src/protocol/vitals.test.ts

@@ -1,13 +1,13 @@
-import { RAW_ROUTES, rawRoutePath } from "./raw-routes.js";
+import { RAW_ROUTES, rawRoutePath } from "./raw/raw-routes.js";
 import { parseVitals, type SandboxVitals, VITALS_PATH } from "./vitals.js";
 
 // The JSON browser-wire's own test pins (`vitals_are_the_camel_case_json_the_editor_parses_with_null_for_what_is_unknown`):
-// what the front writes, the editor reads.
+// what netd writes, the editor reads.
 const RUST_GOLDEN_JSON = `{"node":"restarting","lagMs":null,"restarts":2,"uptimeS":3600,"pressure":{"cpu":12.34,"memory":0.0,"io":1.5}}`;
 
 const up: SandboxVitals = { node: "up", lagMs: 12, restarts: 0, uptimeS: 60, pressure: { cpu: 0.29, memory: 0.49, io: 0.88 } };
 
-it("reads the front's own answer as it writes it", () => {
+it("reads netd's own answer as it writes it", () => {
     expect(parseVitals(JSON.parse(RUST_GOLDEN_JSON))).toEqual({
         node: "restarting",
         lagMs: null,
@@ -23,11 +23,11 @@ it("reads a lag or pressure it cannot make out as unknown, and keeps the rest",
     const { lagMs: _lag, pressure: _pressure, ...bare } = up;
     expect(parseVitals(bare)).toEqual({ ...bare, lagMs: null, pressure: null });
     expect(parseVitals({ ...up, lagMs: -1, pressure: { cpu: 1 } })).toEqual({ ...up, lagMs: null, pressure: null });
-    // A later front's extra fields are not this reader's business.
+    // A later netd's extra fields are not this reader's business.
     expect(parseVitals({ ...up, since: "later" })).toEqual(up);
 });
 
-it("is undefined for anything that is not the front's answer", () => {
+it("is undefined for anything that is not netd's answer", () => {
     // An older sandbox forwards the path to Node, which answers 404 as JSON, or a preview's HTML page.
     expect(parseVitals({ error: "Not Found" })).toBeUndefined();
     expect(parseVitals("<!doctype html><title>Not found</title>")).toBeUndefined();
@@ -40,7 +40,7 @@ it("is undefined for anything that is not the front's answer", () => {
     expect(parseVitals({ ...up, restarts: "2" })).toBeUndefined();
 });
 
-it("is a route the front serves itself, with no credential, before the daemon boots", () => {
+it("is a route netd serves itself, with no credential, before the daemon boots", () => {
     expect(rawRoutePath("GET /system/vitals")).toBe(VITALS_PATH);
-    expect(RAW_ROUTES["GET /system/vitals"]).toEqual({ auth: "door", beforeBoot: true, front: true });
+    expect(RAW_ROUTES["GET /system/vitals"]).toEqual({ auth: "door", beforeBoot: true, netd: true });
 });

package/src/protocol/vitals.ts

@@ -1,18 +1,23 @@
-// The sandbox's proof of life, which intentic-front answers itself on the daemon's own address and never forwards to
-// Node: whether Node is up, how long its event loop takes to answer the front's ping, how often the front restarted it,
+// The sandbox's proof of life, which intentic-netd answers itself on the daemon's own address and never forwards to
+// Node: whether Node is up, how long its event loop takes to answer netd's ping, how often netd restarted it,
 // how long the container has run, and its pressure stall. The daemon's heartbeat on /events rides Node's event loop,
 // so a busy sandbox and a dead one look alike from there; this route tells them apart. The Rust crate `browser-wire`
 // is the definition (SandboxVitals), and wire-manifests.test.ts holds the path here to the manifest it writes.
 
 import { z } from "zod";
-import type { NodeLink, Pressure, SandboxVitals } from "../front/generated/browser-wire.js";
+import type { NodeLink, Pressure, SandboxVitals } from "../netd/generated/browser-wire.js";
 
 export type { NodeLink, Pressure, SandboxVitals };
 
-// A plain GET any origin may read, answered by the front whatever state Node is in. The route is registered as
-// `front: true` in raw-routes.ts, so the daemon serves none.
+// A plain GET any origin may read, answered by netd whatever state Node is in. The route is registered as
+// `netd: true` in raw-routes.ts, so the daemon serves none.
 export const VITALS_PATH = "/system/vitals";
 
+// Where netd also writes them inside the container, for a host that reaches the container but not its address (the
+// platform through Fly's exec): a daemon that dies before it names netd's ports leaves netd listening on nothing, and
+// this file is then the only count of its restarts. browser-wire's VITALS_FILE.
+export const VITALS_FILE = "/run/intentic/vitals.json";
+
 // Every state, so a new one in the Rust enum fails this file's typecheck until it is read here too.
 const NODE_LINKS = { starting: "starting", up: "up", restarting: "restarting" } as const satisfies { readonly [K in NodeLink]: K };
 
@@ -27,10 +32,10 @@ const VitalsSchema = z.object({
     pressure: PressureSchema.nullable().catch(null),
 });
 
-// A response body as `Response.json()` hands it over: any JSON value, not yet known to be the front's answer.
+// A response body as `Response.json()` hands it over: any JSON value, not yet known to be netd's answer.
 type JsonBody = string | number | boolean | null | readonly JsonBody[] | { readonly [key: string]: JsonBody };
 
-// The front's answer, or undefined for anything else: an older sandbox forwards the path to Node, which answers 404 or
+// netd's answer, or undefined for anything else: an older sandbox forwards the path to Node, which answers 404 or
 // an HTML page, and an edge in between may answer for a box that is not there.
 export const parseVitals = (body: JsonBody): SandboxVitals | undefined => {
     const parsed = VitalsSchema.safeParse(body);

package/src/schemas/activity.ts

@@ -101,6 +101,7 @@ export const ActivityConnectionSchema = z.object({
         ),
     lastError: z.string().optional().describe("The most recent thing that went wrong on it."),
 });
+export type ActivityConnection = z.infer<typeof ActivityConnectionSchema>;
 export const ActivityStatusSchema = z.object({
     connections: z
         .array(ActivityConnectionSchema)

package/src/schemas/agent.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { CONVERSATION_ID } from "../ids/conversation-ids.js";
 import { ModelRoleSchema } from "../models/model-roles.js";
 import { NATIVE_PROVIDERS } from "../models/provider-specs.js";
-import { AgentPlacementSchema } from "../protocol/runner-protocol.js";
+import { AgentPlacementSchema } from "../protocol/doors/runner-protocol.js";
 import { MENTION_LIMIT } from "../text/mentions.js";
 import { entryId } from "./internal.js";
 // Agent runtimes the daemon can serve: native providers have dedicated adapters, `endpoint/<id>` names an installed
@@ -509,6 +509,13 @@ export const QueuedMessageSchema = z.object({
         .int()
         .nonnegative()
         .describe("The queue's revision when this message was last written. An edit or a removal names it, and is refused if the message has changed since."),
+    until: z
+        .number()
+        .optional()
+        .describe("When this message goes out by itself, in milliseconds: it was scheduled for that time. Each message keeps its own booking."),
+    after: ConversationIdSchema.optional().describe(
+        "The conversation whose finished work must land before this message goes out by itself, in place of `until`.",
+    ),
 });
 export type QueuedMessage = z.infer<typeof QueuedMessageSchema>;
 // Why a queue holds its messages rather than letting them go when the conversation is free.
@@ -520,14 +527,14 @@ export const ConversationQueueSchema = z.object({
     items: z.array(QueuedMessageSchema).describe("What waits, in the order it goes out."),
     revision: z.number().int().nonnegative().describe("Moves with every change to the queue, so of two copies the higher is the newer."),
     paused: QueuePauseSchema.optional().describe(
-        "Why nothing goes out by itself: somebody stopped the turn, the turn these messages started was refused before it ran, or they were scheduled for a time or for after another conversation's work lands. Resuming lets them go, and so does sending another message.",
+        "Why the messages with no booking of their own do not go out by themselves: somebody stopped the turn, or the turn they started was refused before it ran. Resuming lets them go, and so does sending another message. `scheduled` holds nothing: it says messages are booked, and `until` or `after` is the soonest of their bookings, for clients older than per-message bookings. When any message carries its own `until` or `after`, read those instead.",
     ),
     until: z
         .number()
         .optional()
-        .describe("When scheduled messages go out by themselves, in milliseconds. Only on a queue paused as `scheduled`."),
+        .describe("The soonest booked message's time, in milliseconds. Only on a queue paused as `scheduled`; each message carries its own."),
     after: ConversationIdSchema.optional().describe(
-        "The conversation whose finished work must land before scheduled messages go out by themselves. Only on a queue paused as `scheduled`, in place of `until`.",
+        "The conversation the first booked message waits for, when none waits for a time. Only on a queue paused as `scheduled`, in place of `until`.",
     ),
 });
 export type ConversationQueue = z.infer<typeof ConversationQueueSchema>;

package/src/schemas/agents-list.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { AgentSummarySchema } from "./agents.js";
+import { AutomationApprovalSchema } from "./automations.js";
+
+// The fleet list: its own module, since it joins conversations (agents.ts) with held automation wakes (automations.ts),
+// and agents.ts reaches automations.ts through needs.ts (a need can propose an automation), so neither may hold it.
+// `rev` is the registry revision this roster was read at: fleet snapshots are last-frame-wins, so the browser drops any
+// roster older than the newest it applied and holds a pending change until a roster past `rev` arrives. `held` is the
+// approvals queue projected onto the board, defaulted for an older daemon's roster.
+export const AgentsListSchema = z.object({
+    agents: z.array(AgentSummarySchema).describe("The conversations."),
+    rev: z
+        .number()
+        .describe(
+            "Which version of the fleet this is. The fleet is published as whole snapshots, so without a version a list read before a change but delivered after it would silently undo that change. Drop any list older than the newest you have already applied.",
+        ),
+    held: z
+        .array(AutomationApprovalSchema)
+        .default([])
+        .describe(
+            "Automations waiting at the door for a yes, put alongside the running conversations so needs-you sits beside working rather than on a page nobody opens.",
+        ),
+});
+export type AgentsList = z.infer<typeof AgentsListSchema>;

package/src/schemas/agents.ts

@@ -1,4 +1,5 @@
 // agents: the conversation fleet
+import { LandingDeliverySchema } from "./project-delivery.js";
 import { z } from "zod";
 import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, ConversationQueueSchema, ForkedFromSchema } from "./agent.js";
 import { LoopStateSchema } from "./loops.js";
@@ -6,6 +7,7 @@ import { LimitPolicySchema, RetryPolicySchema, TurnBreakPolicySchema, TurnBreakS
 import { KeepWarmSchema } from "./keep-warm.js";
 import { AgentNeedSchema } from "./needs.js";
 import { EMOJI_MAX_LENGTH, isSingleEmoji } from "../text/emoji.js";
+import { ProgramAskSchema } from "../events/requests.js";
 // A fleet agent is any conversation with a registry entry, keyed by conversationId. Isolated ones own a git worktree
 // (branch agent/<id>); workspace conversations have none, but both share one status/activity/cost lifecycle.
 
@@ -115,6 +117,61 @@ export const TurnProofSchema = z.object({
         .describe("How many rendered files it changed (pages, components, styles) without looking at the result afterwards. Absent when none."),
 });
 export type TurnProof = z.infer<typeof TurnProofSchema>;
+// How many entries each of a reach's lists carries; past it, the list's `…More` count says how many were left out.
+export const TURN_REACH_LIST_MAX = 10;
+// Where the last turn's work went when it went somewhere other than its own branch, read off what the turn touched and
+// never asked of the model. Lists only the exceptions: a turn whose work all lives on its branch leaves no reach at all.
+export const TurnReachSchema = z.object({
+    at: z.number().describe("When the turn that left this ended, in milliseconds."),
+    live: z
+        .array(
+            z.object({
+                path: z
+                    .string()
+                    .describe(
+                        "What it wrote, as it named it: relative to the workspace for the sandbox's shared state, absolute for the owner's own checkout.",
+                    ),
+                extension: z
+                    .string()
+                    .optional()
+                    .describe("The extension, by its manifest id, when what it changed is the installed copy of one. Absent for anything else."),
+            }),
+        )
+        .max(TURN_REACH_LIST_MAX)
+        .optional()
+        .describe(
+            "Files it changed in place where every conversation reads them, outside its own branch: an installed extension's copy, the sandbox's shared state, the owner's own checkout. Live the moment they were written, never reviewed, and an installed extension's next update replaces them.",
+        ),
+    liveMore: z.number().optional().describe("How many more such files there were beyond the ones listed. Absent when all are listed."),
+    stranded: z
+        .array(
+            z.object({
+                dir: z.string().describe("The clone, as a folder relative to its own copy of the workspace."),
+                uncommitted: z.number().describe("Files changed in it and never committed."),
+                unpushed: z.number().describe("Commits in it its upstream does not have, or that no remote has when it follows none."),
+            }),
+        )
+        .max(TURN_REACH_LIST_MAX)
+        .optional()
+        .describe(
+            "Repositories it cloned inside its own copy and left work in. A clone of its own never rides its land, so what is in one stays there.",
+        ),
+    strandedMore: z.number().optional().describe("How many more such clones there were beyond the ones listed. Absent when all are listed."),
+    published: z
+        .array(
+            z.object({
+                dir: z.string().optional().describe("The folder it pushed from, as the command named it. Absent for its own working folder."),
+                remote: z.string().optional().describe("The remote it pushed to, as the command named it. Absent when the command named none."),
+                branch: z.string().optional().describe("The branch it pushed to, as the command named it. Absent when the command named none."),
+                command: z.string().describe("The push itself, trimmed to one line."),
+            }),
+        )
+        .max(TURN_REACH_LIST_MAX)
+        .optional()
+        .describe("Pushes it made with git that went through: work it sent out of the sandbox itself, never through a land."),
+    publishedMore: z.number().optional().describe("How many more such pushes there were beyond the ones listed. Absent when all are listed."),
+});
+export type TurnReach = z.infer<typeof TurnReachSchema>;
 // A landing's commit message: subject plus the two trailer sentences a changelog repo gets. One schema, not three
 // duplicated fields, since both the live roster and the review carrier must read the same shape and can't disagree.
 export const LandedMessageSchema = z.object({
@@ -440,6 +497,9 @@ export const AgentSummarySchema = z.object({
         .object({
             requestId: z.string().describe("Which request this is: the id an answer to it names."),
             ask: z.string().describe("What it asks to do, on one line: the runtime's own sentence, else the tool's short name."),
+            program: ProgramAskSchema.optional().describe(
+                "The program it is holding, as its own request shows it, so the card can show what would run before anyone answers. Absent on a request about no program.",
+            ),
         })
         .optional()
         .describe(
@@ -460,6 +520,11 @@ export const AgentSummarySchema = z.object({
         .describe(
             "The last attempt to bring its work into the workspace failed, and why. Cleared by the next land that goes through. Absent when nothing failed, and from a sandbox older than it.",
         ),
+    // The land's own last word on the owner's folder, for a project attached to this computer's sandbox: written there,
+    // partly kept out, waiting for the computer, or refused (schemas/project-delivery.ts).
+    delivery: LandingDeliverySchema.optional().describe(
+        "What became of its last land in the folder on the owner's computer, for a project folder attached to this computer's sandbox. Absent for any other land, and from a sandbox older than it.",
+    ),
     // Only the causes that still hold, re-read live (conversations/land/standing.ts), never the stored report's own list: a
     // blocker the user has since cleared is not something to offer them an action about.
     conflictCauses: z
@@ -477,6 +542,11 @@ export const AgentSummarySchema = z.object({
     proof: TurnProofSchema.optional().describe(
         "What its last turn showed of its work: whether a check it ran passed after its last edit, and whether it looked at interface files it changed. Absent until a turn that edited or checked anything has ended.",
     ),
+    // Written by the turn's own settle from its tool calls and a read of the clones and installs it could have touched;
+    // replaced by every turn, so it says where the LAST turn's work went.
+    reach: TurnReachSchema.optional().describe(
+        "Where its last turn's work went when it went somewhere besides its own branch: files changed live outside it, clones of its own holding work that will not land, pushes it made itself. Absent when everything it did is on its branch.",
+    ),
     // Completed turns and lifetime tool calls, the card's msgs/tools counters.
     turns: z.number().optional().describe("Turns it has finished."),
     toolUses: z.number().optional().describe("Tools it has used, over its whole life."),
@@ -657,8 +727,7 @@ export type LandedRemover = NonNullable<NonNullable<AgentSummary["landedPresence
 export type LandFailure = NonNullable<AgentSummary["landFailure"]>;
 // The permission a running turn waits on, as a card can answer it.
 export type WaitingPermission = NonNullable<AgentSummary["permissionAsk"]>;
-// AgentsListSchema is declared later, after AutomationApprovalSchema, since the fleet list carries held wakes and zod
-// needs that type declared first.
+// AgentsListSchema lives in agents-list.ts, since the fleet list carries held wakes (automations.ts).
 export const AgentIdSchema = z.object({ id: z.string().min(1).describe("Which conversation.") });
 
 // Naming no watch disarms every one, which is what a press made about the whole card means; a press made about one

package/src/schemas/automations.ts

@@ -1,7 +1,6 @@
 // automations: scheduled agent wake-ups (.intentic/config/automations.json)
 import { z } from "zod";
 import { AgentOriginSchema, ModelPinSchema } from "./agent.js";
-import { AgentSummarySchema } from "./agents.js";
 import { entryId } from "./internal.js";
 import { IssuesConfigSchema } from "./issues.js";
 import { ZoneSchema } from "../time/zone.js";
@@ -124,6 +123,81 @@ export const TriggerSchema = z.discriminatedUnion("kind", [
     }),
 ]);
 export type Trigger = z.infer<typeof TriggerSchema>;
+// A watch is an automation whose check decides, without a model, whether anything happened: either its `guard` command
+// or one of these ready-made sources, which the daemon checks itself (automations/watch/watch-sources.ts). Only once the check
+// says so does anything run, and what it saw goes with the wake. No source needs an extension, a token or a shell.
+// npm: the registry's view of one package. With `range`, the check passes once a published version satisfies it, and
+// what it saw is that version; without, what it saw is the version under `tag` (latest by default), for `fireOn: change`.
+// github-release: a public repository's newest release (prereleases only when asked), for `fireOn: change`.
+// url: one page, its text or the first `select` match, for `fireOn: change`.
+export const WatchSourceSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("npm").describe("A package on the npm registry."),
+        package: z.string().min(1).max(214).describe("The package name, scoped or not, like bun or @scope/name."),
+        range: z
+            .string()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe("A semver range, like >=1.4.3. Passes once a published version satisfies it. Prereleases count only when the range names one."),
+        tag: z.string().min(1).max(100).optional().describe("Which dist-tag to read without a range. Absent means latest."),
+    }),
+    z.object({
+        kind: z.literal("github-release").describe("The newest release of a public GitHub repository."),
+        repo: z
+            .string()
+            .regex(/^[\w.-]+\/[\w.-]+$/, "repo must look like owner/name")
+            .describe("The repository, as owner/name."),
+        prereleases: z.boolean().optional().describe("Count prereleases too. Absent means only full releases."),
+    }),
+    z.object({
+        kind: z.literal("url").describe("One web page."),
+        url: z.string().url().describe("The page, http or https."),
+        select: z
+            .string()
+            .min(1)
+            .max(500)
+            .optional()
+            .describe("A regular expression; what it matches (its first group, if it has one) is what is watched rather than the whole page's text."),
+    }),
+]);
+export type WatchSource = z.infer<typeof WatchSourceSchema>;
+// What a passing check sets off. `agent` (the default) is a new agent with the prompt, as every automation always did;
+// `conversation` continues one that already exists, the way a watch wakes the conversation that armed it, so a plan
+// made weeks ago resumes where it stopped; `notify` runs no model at all, and only tells the owner what the check saw.
+export const AutomationTargetSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("agent").describe("A new agent, told the prompt and what the check saw.") }),
+    z.object({
+        kind: z.literal("conversation").describe("An existing conversation, continued with what the check saw and the prompt."),
+        conversationId: z.string().min(1).describe("Which conversation."),
+    }),
+    z.object({ kind: z.literal("notify").describe("No agent: a notification to the owner with what the check saw.") }),
+]);
+export type AutomationTarget = z.infer<typeof AutomationTargetSchema>;
+// `pass` (the default): every check that passes fires. `change`: a check fires only when what it saw differs from what
+// it saw last time, and the first one only records where things stand, so a watch says when something moves rather
+// than that it is still there.
+export const FireOnSchema = z.enum(["pass", "change"]);
+export type FireOn = z.infer<typeof FireOnSchema>;
+// What the daemon remembers of a watch between checks (.intentic/records/automation-watch.json), and what the list
+// shows under it. Values are kept whole up to a bound, so the next check can say what changed.
+export const WatchStateSchema = z.object({
+    armedAt: z.number().describe("When it was first checked, in milliseconds."),
+    checkedAt: z.number().describe("When it was last checked, in milliseconds."),
+    value: z.string().optional().describe("What the last passing check saw. Absent until one has passed."),
+    changedAt: z.number().optional().describe("When what it saw last changed, in milliseconds."),
+    firedAt: z.number().optional().describe("When it last set something off, in milliseconds."),
+    // Why the last check did not pass, when it did not.
+    waiting: z.string().optional().describe("What the last check said when it did not pass: what it is still waiting for."),
+});
+export type WatchState = z.infer<typeof WatchStateSchema>;
+// POST /automations/check: one source checked now, nothing remembered.
+export const WatchCheckInputSchema = z.object({ source: WatchSourceSchema.describe("The source to check.") });
+export const WatchCheckResultSchema = z.object({
+    pass: z.boolean().describe("Whether the check passes now."),
+    saw: z.string().describe("What it saw when it passed, or what it is still waiting for when it did not."),
+});
+export type WatchCheckResult = z.infer<typeof WatchCheckResultSchema>;
 // The Visitor chat widget's settings, present only on `webchat` listener automations. Split into what the widget itself
 // may read (public by construction) and what only the daemon may (turnstileSecret); GET /webchat/<id>/config serves the
 // first group by naming it, never by omitting the second.
@@ -269,8 +343,38 @@ export const AutomationSchema = z.object({
         .min(1)
         .optional()
         .describe(
-            "A command run before the wake that decides whether there is anything to do. Skipped by the guard is often the most useful thing an automation can report.",
+            "A command run before the wake that decides whether there is anything to do. Skipped by the guard is often the most useful thing an automation can report. What it prints when it passes goes with the wake; $AUTOMATION_STATE names a file it may keep between runs, and $AUTOMATION_LAST holds what it printed last time it passed.",
         ),
+    // The guard's alternative: a condition the daemon checks itself. Refused at upsert beside a guard, since two checks
+    // would leave "what the check saw" meaning two things.
+    source: WatchSourceSchema.optional().describe(
+        "A ready-made check instead of a guard command: an npm package's version, a GitHub repository's newest release, or a web page.",
+    ),
+    fireOn: FireOnSchema.optional().describe(
+        "Fire on every passing check, or only when what the check saw changed since the last one. Absent means every passing check.",
+    ),
+    // Retirement, so a watch never outlives what it was for: `first-fire` switches it off as it fires, the way a one-time
+    // wake retires; `expiresAt` switches it off at a deadline and says so.
+    until: z
+        .enum(["first-fire"])
+        .optional()
+        .describe("Switch it off the first time it fires, for a watch waiting on one thing. Absent means it keeps firing."),
+    expiresAt: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("When it gives up, in milliseconds. Switched off then, and whoever it was for is told it never fired."),
+    target: AutomationTargetSchema.optional().describe(
+        "What a passing check sets off: a new agent (the default), an existing conversation, or only a notification to the owner.",
+    ),
+    // One line a notification and a woken conversation read; an automation has no title of its own.
+    note: z
+        .string()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("One line on what it watches for, like 'Bun 1.4.3 is published'. Shown in its notifications."),
     prompt: z.string().min(1).describe("What the woken agent is told."),
     // The Visitor chat widget's settings, `webchat` listener automations only, ignored on every other trigger.
     webchat: WebchatConfigSchema.optional().describe("Settings for the public chat widget, for an automation that answers visitors."),
@@ -287,15 +391,18 @@ export const AutomationSchema = z.object({
         .describe(
             "Narrow the woken turn to these tools. For one driven by an outside message this list is the real boundary, because prompt wording is only advice and an empty toolbox is not.",
         ),
-    // Required ordered ladder (replaces separate agent/harness/model fields): an automation spends real money
-    // unwatched, so it must name what it spends rather than inherit a chat's default. Walked in order at fire time to
-    // the first rung that can start; each rung is a whole pin (provider+model+effort+harness together).
+    // Ordered ladder (replaces separate agent/harness/model fields): an automation spends real money unwatched, so it must
+    // name what it spends rather than inherit a chat's default. Walked in order at fire time to the first rung that can
+    // start; each rung is a whole pin (provider+model+effort+harness together). Required for a new agent, the default
+    // target, and refused there at upsert when absent; a conversation target runs on that conversation's own model and a
+    // notification runs none, so neither needs one.
     models: z
         .array(ModelPinSchema)
         .min(1)
         .max(10)
+        .optional()
         .describe(
-            "Which models this automation may run on, best first. Required, and nothing is chosen for you: work that fires while nobody is watching spends a real allowance, so it names the models it spends rather than inheriting one. Tried in order, so a spent account does not silently stop the job.",
+            "Which models this automation may run on, best first. Required when it starts a new agent, and nothing is chosen for you: work that fires while nobody is watching spends a real allowance, so it names the models it spends rather than inheriting one. Tried in order, so a spent account does not silently stop the job. Not needed to continue a conversation, which runs on its own model, or to only notify.",
         ),
     // Absent means the daemon's pick: the account its conversation runs on for a continuing thread (moved off one that
     // can no longer serve), else the one that can serve with the most room. Named, it is a pin, run whatever its state,
@@ -341,6 +448,8 @@ export const AutomationApprovalSchema = z.object({
         "Where the message came from, kept alongside the payload so an approved wake appears on the board exactly as an automatic one would have.",
     ),
     title: z.string().optional().describe("What the conversation would be called."),
+    // What the automation's check saw when it passed, so the approved wake carries it as an automatic one would have.
+    observed: z.string().optional().describe("What the automation's check saw when it passed, kept so the approved wake is told the same thing."),
     // The thread this wake belongs to, so approving continues it rather than minting a fresh conversation per approved
     // message.
     conversationId: z
@@ -367,24 +476,10 @@ export const AutomationApprovalSchema = z.object({
         ),
 });
 export type AutomationApproval = z.infer<typeof AutomationApprovalSchema>;
-// `rev` is the registry revision this roster was read at: fleet snapshots are last-frame-wins, so the browser drops any
-// roster older than the newest it applied and holds a pending change until a roster past `rev` arrives. `held` is the
-// approvals queue projected onto the board, defaulted for an older daemon's roster.
-export const AgentsListSchema = z.object({
-    agents: z.array(AgentSummarySchema).describe("The conversations."),
-    rev: z
-        .number()
-        .describe(
-            "Which version of the fleet this is. The fleet is published as whole snapshots, so without a version a list read before a change but delivered after it would silently undo that change. Drop any list older than the newest you have already applied.",
-        ),
-    held: z
-        .array(AutomationApprovalSchema)
-        .default([])
-        .describe(
-            "Automations waiting at the door for a yes, put alongside the running conversations so needs-you sits beside working rather than on a page nobody opens.",
-        ),
-});
-export type AgentsList = z.infer<typeof AgentsListSchema>;
+
+// Whether a held wake waits on a person. A countdown hold (`autoRunAt`) releases itself, so counting it would ask the
+// owner about something already about to happen on its own.
+export const awaitsOwner = (wake: Pick<AutomationApproval, "autoRunAt">): boolean => wake.autoRunAt === undefined;
 export const AutomationApprovalsListSchema = z.object({ approvals: z.array(AutomationApprovalSchema).describe("Everything waiting for a yes.") });
 export const AutomationApprovalIdParamSchema = z.object({ id: z.string().describe("Which waiting item.") });
 export const AutomationRunSchema = z.object({
@@ -406,6 +501,8 @@ export const FIRE_DAILY_MAX_DEFAULT = 200;
 export const AutomationSummarySchema = AutomationSchema.extend({
     runs: z.array(AutomationRunSchema),
     nextRun: z.number().optional(),
+    // Absent for an automation with no check, and for one never checked.
+    watch: WatchStateSchema.optional().describe("What its check saw last and when, for an automation that checks something before it fires."),
     // Door credentials, attached for a maintainer or owner only, never a viewer or a control-token program; kept in the
     // secrets store, not the manifest.
     webhookToken: z
@@ -484,6 +581,11 @@ export const AutomationTemplateSchema = z.object({
     trigger: TriggerSchema,
     // Prefills the guard command (a shell one-liner; non-zero exit skips the wake).
     guard: z.string().min(1).optional(),
+    // Prefill a watch: a ready-made check, when it fires, whether it retires, and what it sets off.
+    source: WatchSourceSchema.optional(),
+    fireOn: FireOnSchema.optional(),
+    until: z.enum(["first-fire"]).optional(),
+    target: AutomationTargetSchema.optional(),
     // Prefills the countdown hold: each fire waits this long, visibly and cancellably, before starting itself.
     holdForSeconds: z.number().int().positive().optional(),
     prompt: z.string().min(1),