@kubitnodes/stellaris 0.3.27 → 0.4.0

package/dist/cli/index.js

@@ -65,7 +65,8 @@ var VERB_NAMES = [
   "update_cron",
   "remove_cron",
   "remove_skill",
-  "upload_image"
+  "upload_image",
+  "read_image"
 ];
 var VerbNameSchema = z2.enum(VERB_NAMES);
 var CharterTriggerSchema = z2.enum(["user_post", "ops_event", "heartbeat"]);
@@ -95,6 +96,7 @@ var USER_NAME = "user";
 var MEMBER_VERBS = [
   "post_message",
   "upload_image",
+  "read_image",
   "read_inbox",
   "search",
   "open_thread",
@@ -225,7 +227,12 @@ var CronScheduleSchema = z3.union([
 var CronRunSchema = z3.object({
   turnId: UlidSchema,
   at: IsoDateTimeSchema,
-  outcome: z3.enum(["completed", "failed", "stopped"])
+  outcome: z3.enum(["completed", "failed", "stopped"]),
+  /**
+   * For a failed one, the first turn of the cron's citizen in its conversation that was shown the
+   * failure and completed, and when it ended.
+   */
+  caughtUp: z3.object({ turnId: UlidSchema, at: IsoDateTimeSchema }).optional()
 });
 var CronFrontmatterSchema = z3.object({
   id: UlidSchema,
@@ -272,6 +279,16 @@ function shortestGapMs(schedule, societyZone, after) {
   }
   return shortest;
 }
+function firesInTask(cron2, task2) {
+  return cron2.scope === task2.project && cron2.thread === task2.id;
+}
+function cronFailure(cron2) {
+  return cron2.lastRun?.outcome === "failed" && cron2.lastRun.caughtUp === void 0 ? cron2.lastRun : null;
+}
+function cronStoppedAt(cron2) {
+  const times = [cron2.paused?.at, cron2.ended?.at, cronFailure(cron2)?.at].filter((at) => at !== void 0);
+  return times.reduce((first, at) => first === null || Date.parse(at) < Date.parse(first) ? at : first, null);
+}
 function nextFire(cron2, societyZone, floorMs = CRON_FLOOR_MS) {
   if (cron2.ended !== void 0 || cron2.paused !== void 0) {
     return null;
@@ -651,6 +668,7 @@ var MemberSchema = z5.object({
 });
 var RunnerOsSchema = z5.enum(["linux", "windows", "darwin"]);
 var GitIdentityPartSchema = z5.enum(["name", "email"]);
+var RunnerPauseSchema = z5.object({ at: IsoDateTimeSchema, by: NameSchema });
 var RunnerSchema = z5.object({
   name: NameSchema,
   os: RunnerOsSchema,
@@ -669,8 +687,25 @@ var RunnerSchema = z5.object({
    * Each CLI's plan quota as its login on this runner last reported it, from a turn's stream or a
    * read; absent until one has.
    */
-  quotas: z5.partialRecord(CliKindSchema, CliQuotaSchema).optional()
+  quotas: z5.partialRecord(CliKindSchema, CliQuotaSchema).optional(),
+  /** The user's pause of the whole runner: no turn starts on it until the user resumes it. */
+  paused: RunnerPauseSchema.optional(),
+  /**
+   * The user's pauses of single CLIs on the runner, each apart from the runner's own: no turn of
+   * that CLI starts on it until the user resumes it.
+   */
+  pausedClis: z5.partialRecord(CliKindSchema, RunnerPauseSchema).optional()
 });
+function runnerPause(runner2, cli) {
+  return runner2.paused ?? runner2.pausedClis?.[cli];
+}
+function heldOn(runners, runner2, cli) {
+  if (runner2 === void 0 || cli === null) {
+    return false;
+  }
+  const record = runners.find((each) => each.name === runner2);
+  return record !== void 0 && runnerPause(record, cli) !== void 0;
+}
 var ProposalKindSchema = z5.enum([
   "role",
   "member",
@@ -1014,7 +1049,21 @@ function imageTypeOf(bytes) {
   return null;
 }
 var ImagePathSchema = z6.string().min(1).max(4096).refine((value) => !value.includes("\0"), { message: "a path with no NUL character" });
+var ImageNameSchema = z6.string().max(1024);
+function imageDescription(name) {
+  return name.replaceAll(/[[\]\\\r\n`]/g, "");
+}
 var IMAGE_SCHEME = "image:";
+var ImageRefSchema = z6.string().regex(/^(?:image:)?[0-9A-HJKMNP-TV-Z]{26}$/, "expected an image's id or image:<id>");
+function imageIdOf(ref) {
+  return ref.startsWith(IMAGE_SCHEME) ? ref.slice(IMAGE_SCHEME.length) : ref;
+}
+var ImageFileSchema = z6.object({
+  id: UlidSchema,
+  type: ImageTypeSchema,
+  size: z6.number().int().positive(),
+  path: ImagePathSchema
+});
 var UploadedImageSchema = z6.object({
   id: UlidSchema,
   type: ImageTypeSchema,
@@ -1179,6 +1228,10 @@ var VerbInputs = {
   upload_image: z7.object({
     /** The image file on the machine your turn runs on: absolute, or relative to your working directory. */
     path: ImagePathSchema
+  }),
+  read_image: z7.object({
+    /** The image's id, or its `image:<id>` address as a post shows it. */
+    image_id: ImageRefSchema
   })
 };
 
@@ -1230,6 +1283,8 @@ var BOARD_EVENT_TYPES = [
   "user.token_rotated",
   "runner.changed",
   "runner.quota",
+  "runner.paused",
+  "runner.resumed",
   "ops.signal",
   "paused.changed",
   "wake.requested",
@@ -1371,6 +1426,11 @@ var RunnerHelloSchema = z9.object({
   quotaReads: z9.boolean().default(false),
   /** Whether the runner reads an image a turn running there uploads; one from before never does. */
   imageReads: z9.boolean().default(false),
+  /**
+   * Whether the runner writes an image the board sends for a turn running there to open, for
+   * `read_image`; one from before never does.
+   */
+  imageWrites: z9.boolean().default(false),
   /**
    * Whether the runner carries a project's repository out to another runner and in from one, and
    * removes its copy once the project has moved; one from before never does.
@@ -1484,6 +1544,12 @@ var TurnJobSchema = z9.object({
   usageSoFar: UsageSchema.optional(),
   /** The rendered charter, norms, memory core, and skills index, with `PATH_TOKENS` for places. */
   instructions: z9.string(),
+  /**
+   * The hash of `instructions` without the first turn's section (`instructionsHash` in
+   * `turn-host`): a warm process started on other instructions starts afresh, so a compaction in
+   * it puts back the current ones. Absent from a server from before, when the text is compared.
+   */
+  instructionsHash: z9.string().optional(),
   prompt: z9.string(),
   mcp: z9.object({ url: z9.string().min(1), token: z9.string().min(1) }),
   limits: z9.object({
@@ -1668,6 +1734,13 @@ var TurnImageSchema = z9.discriminatedUnion("kind", [
   }),
   z9.object({ kind: z9.literal("refused"), why: ImageRefusalSchema, detail: z9.string() })
 ]);
+var TurnImageWriteSchema = z9.object({
+  turnId: UlidSchema,
+  id: UlidSchema,
+  type: ImageTypeSchema,
+  content: z9.string()
+});
+var TurnImageFileSchema = z9.object({ path: ImagePathSchema });
 var WorkspaceConversationSchema = z9.discriminatedUnion("kind", [
   z9.object({ kind: z9.literal("thread"), id: UlidSchema }),
   z9.object({ kind: z9.literal("channel"), scope: NameSchema, name: NameSchema }),
@@ -1681,6 +1754,7 @@ var HeldWorkspaceSchema = z9.object({
 var HeldWorkspacesSchema = z9.object({ workspaces: z9.array(HeldWorkspaceSchema) });
 var SweepResultSchema = z9.object({ kept: z9.array(HeldWorkspaceSchema) });
 var MOVE_PACK_LIMIT_BYTES = 256 * 1024 * 1024;
+var MOVE_FLOOR_BYTES_PER_SECOND = 16 * 1024;
 var RepoRefsSchema = z9.record(z9.string().regex(/^refs\/(heads|tags)\/\S+$/), z9.string().regex(/^[0-9a-f]{40}([0-9a-f]{24})?$/));
 var ProjectExportSchema = z9.object({ move: UlidSchema, repo: ProjectRepoSchema });
 var HeldWorkSchema = z9.object({
@@ -1704,7 +1778,9 @@ var ProjectExportedSchema = z9.discriminatedUnion("ok", [
 var ProjectImportSchema = z9.object({
   move: UlidSchema,
   repo: ProjectRepoSchema,
-  pullRequests: z9.boolean()
+  pullRequests: z9.boolean(),
+  /** The packs' size the old runner measured, which the clone's clock is sized from; the cap if unsaid. */
+  bytes: z9.number().int().nonnegative().optional()
 });
 var ProjectImportedSchema = z9.object({ refs: RepoRefsSchema });
 var ProjectReleaseSchema = z9.object({ slug: NameSchema });
@@ -1744,6 +1820,15 @@ var RunnerMessageSchema = z9.discriminatedUnion("type", [
    * whose hello says `imageReads`.
    */
   z9.object({ type: z9.literal("image"), request: z9.string().min(1), read: TurnImageReadSchema }),
+  /**
+   * Answered with a `TurnImageFile`, or null when the turn is not running there. Sent only to
+   * runners whose hello says `imageWrites`.
+   */
+  z9.object({
+    type: z9.literal("image_write"),
+    request: z9.string().min(1),
+    write: TurnImageWriteSchema
+  }),
   /** Answered with whether the CLI accepted it; that it took it comes as a `steered` event. */
   z9.object({
     type: z9.literal("steer"),
@@ -1809,6 +1894,7 @@ var TriggerKindSchema = z10.enum([
   "closing",
   "cron"
 ]);
+var HeartbeatCauseSchema = z10.enum(["unread", "held", "waiting"]);
 var TriggerSchema = z10.object({
   kind: TriggerKindSchema,
   from: NameSchema.optional(),
@@ -1819,7 +1905,9 @@ var TriggerSchema = z10.object({
   /** The channel the waking message was posted in. */
   channel: ChannelRefSchema.optional(),
   /** The cron that came due, for a `cron` wake. */
-  cronId: UlidSchema.optional()
+  cronId: UlidSchema.optional(),
+  /** What a `heartbeat` woke for; absent on records from before the board kept it. */
+  heartbeat: HeartbeatCauseSchema.optional()
 });
 var TurnThreadSchema = z10.object({ id: UlidSchema, task: z10.boolean() });
 var TurnDispatchSchema = z10.object({
@@ -1885,6 +1973,12 @@ var TurnRecordSchema = z10.object({
    * one. A resumed session's next turn measures its own usage from here.
    */
   sessionUsage: UsageSchema.optional(),
+  /**
+   * The SHA-256 of the instructions the session holds after this turn, the first turn's section
+   * left out (`instructionsHash` in `turn-host`): those it began with, or the latest a prompt
+   * carried. Absent when the board does not know them, as for records from before it kept them.
+   */
+  sessionInstructionsHash: z10.string().optional(),
   /**
    * The whole input of the turn's latest model call in the session's own thread, as the runner
    * reported it: how large the session had grown. Absent for a turn that made no call.
@@ -1909,7 +2003,13 @@ var TurnRecordSchema = z10.object({
    */
   sessionDropped: z10.boolean().optional(),
   /** The crons whose fire started the turn, which record how it ended. */
-  crons: z10.array(UlidSchema).optional()
+  crons: z10.array(UlidSchema).optional(),
+  /**
+   * The failed fires its prompt named: each of its citizen's crons in its conversation whose latest
+   * fire's turn failed with nothing catching it up (`cronFailure`), but those it carries, with that
+   * turn. Completing it catches each up.
+   */
+  cronFailures: z10.array(z10.object({ cron: UlidSchema, turnId: UlidSchema })).optional()
 });
 var RunningTurnSchema = z10.object({
   turnId: UlidSchema,
@@ -1951,6 +2051,8 @@ var TurnHistoryEntrySchema = z10.object({
   /** The project whose channels' conversation the turn was in, for a turn in the society scope. */
   place: NameSchema.optional(),
   trigger: z10.string(),
+  /** What a `heartbeat` woke for; absent on turns logged before the board kept it. */
+  heartbeat: HeartbeatCauseSchema.optional(),
   exitReason: z10.string().nullable(),
   costUsd: z10.number(),
   /** The tokens the turn used; absent for turns logged before turns recorded them. */
@@ -2021,7 +2123,7 @@ var METRICS_WINDOW_MS = {
   "7d": 7 * 24 * 36e5,
   all: null
 };
-var READ_VERBS = ["read_inbox", "search", "get_task"];
+var READ_VERBS = ["read_inbox", "search", "get_task", "read_image"];
 function isBoardAction(tool) {
   const verb = /^mcp__board__(.+)$/.exec(tool)?.[1];
   return verb !== void 0 && !READ_VERBS.some((read2) => read2 === verb);
@@ -2035,12 +2137,19 @@ var MetricsSchema = z12.object({
   /**
    * Finished turns that changed nothing on the board. Reflections are left out, since they write
    * memory, not the board; turns without a transcript are counted apart, their actions unknown.
+   * Heartbeats are split by what each woke for, and those recorded before the board kept it are a
+   * row without one.
    */
   idle: z12.object({
     turns: CountSchema,
     idle: CountSchema,
     unknown: CountSchema,
-    byTrigger: z12.array(z12.object({ trigger: z12.string(), turns: CountSchema, idle: CountSchema })),
+    byTrigger: z12.array(z12.object({
+      trigger: z12.string(),
+      heartbeat: HeartbeatCauseSchema.optional(),
+      turns: CountSchema,
+      idle: CountSchema
+    })),
     byAgent: z12.array(z12.object({
       agent: NameSchema,
       role: NameSchema.nullable(),
@@ -2175,7 +2284,7 @@ var RunnerConfigSchema = z13.object({
 });
 
 // packages/shared/dist/version.js
-var STELLARIS_VERSION = "0.3.27";
+var STELLARIS_VERSION = "0.4.0";
 
 // packages/shared/dist/mentions.js
 import { parse, postprocess, preprocess } from "micromark";
@@ -2936,7 +3045,8 @@ var TurnPayload = z14.object({
   thread: z14.string().optional(),
   channel: z14.string().optional(),
   place: z14.string().optional(),
-  trigger: z14.string()
+  trigger: z14.string(),
+  heartbeat: HeartbeatCauseSchema.optional().catch(void 0)
 });
 var TaskPayload = z14.object({
   taskId: z14.string(),
@@ -3036,13 +3146,12 @@ function computeMetrics(input) {
         const nothing = actions === 0 ? 1 : 0;
         turns += 1;
         idle += nothing;
-        for (const [rows, key] of [
-          [turnRows, turn2.data.trigger],
-          [agentRows, event.actor]
-        ]) {
-          const row = rows.get(key) ?? { turns: 0, idle: 0 };
-          rows.set(key, { turns: row.turns + 1, idle: row.idle + nothing });
-        }
+        const { trigger, heartbeat } = turn2.data;
+        const key = heartbeat === void 0 ? trigger : `${trigger}\0${heartbeat}`;
+        const row = turnRows.get(key) ?? { trigger, heartbeat, turns: 0, idle: 0 };
+        turnRows.set(key, { ...row, turns: row.turns + 1, idle: row.idle + nothing });
+        const own = agentRows.get(event.actor) ?? { turns: 0, idle: 0 };
+        agentRows.set(event.actor, { turns: own.turns + 1, idle: own.idle + nothing });
         break;
       }
       case "turn.started": {
@@ -3198,7 +3307,10 @@ function computeMetrics(input) {
       turns,
       idle,
       unknown,
-      byTrigger: [...turnRows].map(([trigger, row]) => ({ trigger, ...row })).toSorted((a, b) => b.idle - a.idle || b.turns - a.turns),
+      byTrigger: [...turnRows.values()].map(({ heartbeat, ...row }) => ({
+        ...row,
+        ...heartbeat === void 0 ? {} : { heartbeat }
+      })).toSorted((a, b) => b.idle - a.idle || b.turns - a.turns),
       byAgent: [...agentRows].map(([agent2, row]) => ({ agent: agent2, role: citizens.get(agent2)?.role ?? null, ...row })).toSorted((a, b) => b.idle - a.idle || b.turns - a.turns)
     },
     sentBack: {
@@ -3258,6 +3370,8 @@ var TurnHistoryPayloadSchema = z15.object({
   channel: NameSchema.optional(),
   place: NameSchema.optional(),
   trigger: z15.string().default("manual"),
+  // One a later board added reads as none, so the turn stays in the history.
+  heartbeat: HeartbeatCauseSchema.optional().catch(void 0),
   exitReason: z15.string().nullable().default(null),
   costUsd: z15.number().default(0),
   usage: UsageSchema.optional(),
@@ -3683,7 +3797,10 @@ var SignInsSchema = z16.object({
     expiresAt: IsoDateTimeSchema
   })).default([])
 });
-var TurnStartPayloadSchema = z16.object({ turnId: UlidSchema });
+var TurnStartPayloadSchema = z16.object({
+  turnId: UlidSchema,
+  heartbeat: TurnHistoryPayloadSchema.shape.heartbeat
+});
 var CursorsSchema = z16.object({
   digest: z16.string().nullable(),
   scopes: z16.record(z16.string(), z16.string()).default({}),
@@ -3755,6 +3872,9 @@ function skillFolderOf(proposal2) {
 function proposedFrom(origin, where) {
   return origin !== void 0 && origin.scope === where.scope && origin.thread === where.thread && origin.channel === where.channel && origin.place === where.place;
 }
+function latestLease(a, b) {
+  return a === null ? b : b === null || a >= b ? a : b;
+}
 function megabytes(bytes) {
   return (bytes / (1024 * 1024)).toFixed(1).replace(/\.0$/, "");
 }
@@ -3894,6 +4014,7 @@ var Board = class _Board {
   /** The turns in flight, which the server hosting them supplies; none until it does. */
   turnsInFlight = () => [];
   imageSource = null;
+  imageSink = null;
   newId = monotonicFactory();
   events;
   actionCounts = /* @__PURE__ */ new Map();
@@ -3944,10 +4065,13 @@ var Board = class _Board {
   /**
    * Applies each one-time alignment an existing society has not had yet, and remembers it, so a
    * member that later chooses otherwise keeps its choice. A new alignment is a name and a method in
-   * this list; once every board has applied it, both are deleted. None is pending.
+   * this list; once every board has applied it, both are deleted.
    */
   async applyAlignments() {
-    const alignments = [];
+    const alignments = [
+      // Whoever may show an image in a post may open one a post shows.
+      { name: "image-reads-granted", apply: () => this.grantBeside("upload_image", "read_image") }
+    ];
     const file = path8.join(this.paths.state(), "alignments.json");
     const { applied } = await exists(file) ? await readJson(file, AlignmentsSchema) : { applied: [] };
     const pending = alignments.filter(({ name }) => !applied.includes(name));
@@ -3959,6 +4083,17 @@ var Board = class _Board {
     }
     await writeJson(file, { applied: [...applied, ...pending.map(({ name }) => name)] });
   }
+  /**
+   * Grants `verb` once to every charter granting `beside`, the work roles' charters in practice;
+   * seed roles have it from their seed.
+   */
+  async grantBeside(beside, verb) {
+    for (const charter of await this.listRoles()) {
+      if (charter.verbs.includes(beside) && !charter.verbs.includes(verb)) {
+        await this.writeRoleUnlocked(USER_NAME, { ...charter, verbs: [...charter.verbs, verb] }, { verbsAdded: [verb] });
+      }
+    }
+  }
   /** Writes every missing seed charter and aligns the existing ones with their seed. */
   async ensureSeedRoles() {
     await ensureDir(this.paths.roles());
@@ -4726,6 +4861,46 @@ ${DASHBOARD_LINE}
       return next;
     });
   }
+  /**
+   * Pauses or resumes a runner, the user's alone: the whole runner, or with `cli` that CLI on it
+   * alone, each apart from the other. While either holds, no turn it covers starts there; their
+   * wakes wait in the scheduler's queue, and a turn under way finishes. Pausing what is paused, or
+   * resuming what is not, changes nothing and logs nothing.
+   */
+  async setRunnerPaused(actor, name, change) {
+    this.assertUser(actor, "only the user may pause or resume a runner");
+    const cli = change.cli === void 0 ? void 0 : CliKindSchema.parse(change.cli);
+    return this.mutex.run(async () => {
+      const file = this.paths.runner(name);
+      if (!await exists(file)) {
+        throw new BoardError("NOT_FOUND", `runner ${name} not found`);
+      }
+      const doc = await readMarkdown(file, RunnerSchema);
+      const { paused, pausedClis, ...rest } = doc.data;
+      if (cli !== void 0 && change.paused && !doc.data.clis.includes(cli)) {
+        throw new BoardError("INVALID_STATE", `runner ${name} has no ${cli} to pause`);
+      }
+      const current = cli === void 0 ? paused : pausedClis?.[cli];
+      if (current !== void 0 === change.paused) {
+        return doc.data;
+      }
+      const pause = change.paused ? { at: this.now().toISOString(), by: actor.name } : void 0;
+      const clis = cli === void 0 ? { ...pausedClis } : { ...pausedClis, [cli]: pause };
+      const kept = Object.entries(clis).filter(([, each]) => each !== void 0);
+      const whole = cli === void 0 ? pause : paused;
+      const next = RunnerSchema.parse({
+        ...rest,
+        ...whole === void 0 ? {} : { paused: whole },
+        ...kept.length === 0 ? {} : { pausedClis: Object.fromEntries(kept) }
+      });
+      await writeMarkdown(file, next, doc.body);
+      await this.events.append(change.paused ? "runner.paused" : "runner.resumed", actor.name, {
+        name,
+        ...cli === void 0 ? {} : { cli }
+      });
+      return next;
+    });
+  }
   /**
    * Logs an operations signal as an `ops.signal` event. No channel carries it: the scheduler wakes
    * its readers from the event, the runner lists it in their prompts, and the interface's log shows
@@ -4760,8 +4935,9 @@ ${DASHBOARD_LINE}
       }
       if (event.type === "turn.started") {
         const start = TurnStartPayloadSchema.safeParse(event.payload);
-        if (start.success)
-          starts.set(start.data.turnId, event.ts);
+        if (start.success) {
+          starts.set(start.data.turnId, { ts: event.ts, heartbeat: start.data.heartbeat });
+        }
         continue;
       }
       if (event.type !== "turn.completed" && event.type !== "turn.failed") {
@@ -4769,17 +4945,19 @@ ${DASHBOARD_LINE}
       }
       const parsed = TurnHistoryPayloadSchema.safeParse(event.payload);
       if (parsed.success) {
-        const { turnId } = parsed.data;
-        const startedAt = turnId === void 0 ? void 0 : starts.get(turnId);
-        if (turnId !== void 0) {
-          starts.delete(turnId);
+        const { heartbeat: ended, ...turn2 } = parsed.data;
+        const start = turn2.turnId === void 0 ? void 0 : starts.get(turn2.turnId);
+        if (turn2.turnId !== void 0) {
+          starts.delete(turn2.turnId);
         }
+        const heartbeat = ended ?? start?.heartbeat;
         entries.push({
           id: event.id,
           ts: event.ts,
           outcome: event.type === "turn.failed" ? "failed" : "completed",
-          ...parsed.data,
-          ...startedAt === void 0 ? {} : { startedAt }
+          ...turn2,
+          ...heartbeat === void 0 ? {} : { heartbeat },
+          ...start === void 0 ? {} : { startedAt: start.ts }
         });
       }
     }
@@ -4809,14 +4987,31 @@ ${DASHBOARD_LINE}
       return society;
     });
   }
-  /** Releases every claim whose lease has expired. Called by the scheduler on its tick. */
+  /**
+   * Releases every claim whose lease has expired, but for a holder's that its own cron in the
+   * task's thread keeps (`keptLease`). Called by the scheduler on its tick.
+   */
   async expireLeases() {
     return this.mutex.run(async () => {
       const expired = [];
       const now = this.now();
+      let crons;
+      let runners;
       for (const project2 of await listDirs(this.paths.projects())) {
+        let place;
         for (const task2 of await this.listTasks(project2)) {
-          if (task2.status === "claimed" && this.leaseExpired(task2, now)) {
+          if (task2.status !== "claimed") {
+            continue;
+          }
+          crons ??= await this.listCrons();
+          runners ??= await this.listRunners();
+          place ??= await this.readProject(project2);
+          const kept = latestLease(this.keptLease(task2, crons, now), await this.pausedLease(task2, runners, place.runner, now));
+          if (kept !== null) {
+            await this.writeTask(project2, { ...task2, leaseExpiresAt: kept });
+            continue;
+          }
+          if (this.leaseExpired(task2, now)) {
             const released = await this.writeTask(project2, {
               ...task2,
               status: "open",
@@ -4885,20 +5080,24 @@ ${DASHBOARD_LINE}
    * general channel, one of its other channels, one of its threads, or, in the society scope, a
    * project's channels. The heartbeat asks, so that it wakes a member where its unread
    * messages are and nowhere else. Society channels count only for a member woken in the society
-   * scope; a project member reads them at its next turn. Two kinds of post are in the digest but not
+   * scope; a project member reads them at its next turn. Some posts are in the digest but not
    * counted, and are read when the member wakes for something else: a task step's, which wakes
-   * whoever it hands work to, and the board's own, operations signals and landing announcements,
-   * whose signals that call for action wake their readers directly. A closed thread counts for
-   * nothing: its conversation has ended, and a turn there could only read its posts and be refused
-   * a reply, while a wake queued before it closed, as for a mention, still runs there.
+   * whoever it hands work to; the board's own, operations signals and landing announcements, whose
+   * signals that call for action wake their readers directly; and a knowledge topic's notice, which
+   * asks nothing of anyone. In a task's thread a post counts only for whoever the current stage is
+   * for, its holder or, while nobody holds it, a member who may take it, and for the task's creator
+   * when it mentions the user, so the creator can put a wait on the user in; a post that asks the
+   * reader counts wherever it is. A closed thread counts for nothing: its conversation has ended,
+   * and a turn there could only read its posts and be refused a reply, while a wake queued before
+   * it closed, as for a mention, still runs there.
    */
   async unreadByConversation(actor) {
     const { cursors, upto } = await this.digestSnapshot(actor.name);
     const counts = /* @__PURE__ */ new Map();
-    const closed = /* @__PURE__ */ new Map();
+    const threadCounts = /* @__PURE__ */ new Map();
     const unscoped = { name: actor.name, role: actor.role };
-    for (const { scope, part, message, news } of await this.digestSince(unscoped, cursors, upto)) {
-      if (news === true || message.step !== void 0 || message.author === SYSTEM_ACTOR.name) {
+    for (const { scope, part, message, news, asked } of await this.digestSince(unscoped, cursors, upto)) {
+      if (news === true || message.step !== void 0 || message.author === SYSTEM_ACTOR.name || message.notice?.kind === "knowledge") {
         continue;
       }
       const posted = parseChannelRef(message.channel).project ?? SOCIETY_SCOPE;
@@ -4907,12 +5106,13 @@ ${DASHBOARD_LINE}
       }
       const thread2 = threadOfPart(part);
       if (thread2 !== void 0) {
-        let ended = closed.get(thread2);
-        if (ended === void 0) {
-          ended = (await this.tryFindThread(thread2))?.thread.state === "closed";
-          closed.set(thread2, ended);
+        let counted = threadCounts.get(thread2);
+        if (counted === void 0) {
+          counted = await this.threadCount(actor, thread2);
+          threadCounts.set(thread2, counted);
         }
-        if (ended) {
+        const forReader = counted === "every" || counted !== "none" && asked === true || counted === "asks-user" && message.mentions.includes(USER_NAME);
+        if (!forReader) {
           continue;
         }
       }
@@ -5065,7 +5265,7 @@ ${DASHBOARD_LINE}
         include = participates;
       }
       if (include && message.author !== actor.name) {
-        collected.push({ scope: filedIn, part, message });
+        collected.push({ scope: filedIn, part, message, ...asked ? { asked: true } : {} });
       }
     }
     return collected.toSorted(byId);
@@ -5342,12 +5542,30 @@ ${current.body}`);
       throw new BoardError("NOT_FOUND", "this board has no runners to read an image from");
     }
     const bytes = await this.imageSource(actor, args.path);
+    return this.keepImage(actor, bytes, args.path, path8.basename(args.path));
+  }
+  /**
+   * Keeps an image the user posts from a composer, as its bytes, under the same checks as an image
+   * a turn uploads. `name`, the file's, describes it in the markdown answered; without one the
+   * description is empty, for the user to write.
+   */
+  async postImage(actor, bytes, name) {
+    this.assertUser(actor, "only the user posts an image's bytes; a turn uploads one with upload_image");
+    const given = name === void 0 ? "" : ImageNameSchema.parse(name);
+    return this.keepImage(actor, bytes, given === "" ? "the image" : given, given);
+  }
+  /**
+   * Keeps `bytes` under a new id when they are a PNG, JPEG, GIF, or WebP of at most
+   * `IMAGE_LIMIT_BYTES`, and answers the markdown that shows them, described by `name`. `what`
+   * names the image in a refusal.
+   */
+  async keepImage(actor, bytes, what, name) {
     const type = imageTypeOf(bytes);
     if (type === null) {
-      throw new BoardError("VALIDATION", `${args.path} is not a PNG, JPEG, GIF, or WebP image by its first bytes`);
+      throw new BoardError("VALIDATION", `${what} is not a PNG, JPEG, GIF, or WebP image by its first bytes`);
     }
     if (bytes.byteLength > IMAGE_LIMIT_BYTES) {
-      throw new BoardError("VALIDATION", `${args.path} is ${bytes.byteLength} bytes, over the ${IMAGE_LIMIT_BYTES} an image may be`);
+      throw new BoardError("VALIDATION", `${what} is ${bytes.byteLength} bytes, over the ${IMAGE_LIMIT_BYTES} an image may be`);
     }
     return this.mutex.run(async () => {
       const id = this.newId();
@@ -5357,15 +5575,37 @@ ${current.body}`);
         type,
         size: bytes.byteLength
       });
-      const name = path8.basename(args.path).replaceAll(/[[\]\\\r\n]/g, "");
+      const description = imageDescription(name);
       return {
         id,
         type,
         size: bytes.byteLength,
-        markdown: `![${name}](${IMAGE_SCHEME}${id})`
+        markdown: `![${description}](${IMAGE_SCHEME}${id})`
       };
     });
   }
+  /**
+   * Opens an image the board keeps for the calling turn, by its id or its `image:<id>` address:
+   * the runner the turn runs on writes the bytes to a file in a folder of the turn's own in the
+   * system temp folder, removed when the turn ends, and the board answers its path, for the
+   * citizen to open with its own file tools, since a post reaches a turn as markdown and an image
+   * in it as its address. Any image the board keeps may be opened: every post, brief, topic, and
+   * dashboard that could show one is in the projection every turn reads.
+   */
+  async openImage(actor, input) {
+    const args = VerbInputs.read_image.parse(input);
+    await this.authorize(actor, "read_image");
+    if (actor.scope === void 0) {
+      throw new BoardError("INVALID_STATE", "read_image writes the image on the machine a turn runs on, so only a turn can call it");
+    }
+    if (this.imageSink === null) {
+      throw new BoardError("NOT_FOUND", "this board has no runners to write an image to");
+    }
+    const id = imageIdOf(args.image_id);
+    const { type, bytes } = await this.readImage(id);
+    const file = await this.imageSink(actor, { id, type, bytes });
+    return { id, type, size: bytes.byteLength, path: file };
+  }
   /** An uploaded image's bytes and kind, which its first bytes tell. */
   async readImage(id) {
     const file = this.paths.image(UlidSchema.parse(id));
@@ -5711,6 +5951,13 @@ ${current.body}`);
   readImagesWith(source) {
     this.imageSource = source;
   }
+  /**
+   * Where `read_image` writes an image to: the runner the calling turn runs on, through the server
+   * that hosts the runners. Without one, as in the admin CLI, nothing can be opened.
+   */
+  openImagesWith(sink) {
+    this.imageSink = sink;
+  }
   /**
    * Refuses to end conversations while another citizen's turn is in one of them: `cut` picks the
    * turns that would lose theirs. The caller's own turn is exempt, since ending a conversation
@@ -6546,6 +6793,8 @@ ${rationale}`}`);
         return this.removeCron(actor, VerbInputs.remove_cron.parse(input));
       case "upload_image":
         return this.uploadImage(actor, VerbInputs.upload_image.parse(input));
+      case "read_image":
+        return this.openImage(actor, VerbInputs.read_image.parse(input));
       default:
         throw new BoardError("VALIDATION", `unknown verb ${String(verb)}`);
     }
@@ -6781,6 +7030,7 @@ ${rationale}`}`);
         ...parsed.channel === void 0 ? {} : { channel: parsed.channel },
         ...parsed.place === void 0 ? {} : { place: parsed.place },
         trigger: parsed.trigger.kind,
+        ...parsed.trigger.heartbeat === void 0 ? {} : { heartbeat: parsed.trigger.heartbeat },
         session: parsed.session,
         runner: parsed.runner
       });
@@ -6803,6 +7053,11 @@ ${rationale}`}`);
       for (const id of parsed.crons ?? []) {
         await this.recordCronRun(id, parsed, failed);
       }
+      if (parsed.exitReason === "completed" || parsed.exitReason === "blocked") {
+        for (const shown of parsed.cronFailures ?? []) {
+          await this.catchUpCron(shown, parsed);
+        }
+      }
       if (parsed.exitReason === "stopped") {
         await this.events.append("turn.stopped", parsed.stoppedBy ?? USER_NAME, {
           ...parsed.id === void 0 ? {} : { turnId: parsed.id },
@@ -6820,6 +7075,7 @@ ${rationale}`}`);
         ...parsed.channel === void 0 ? {} : { channel: parsed.channel },
         ...parsed.place === void 0 ? {} : { place: parsed.place },
         trigger: parsed.trigger.kind,
+        ...parsed.trigger.heartbeat === void 0 ? {} : { heartbeat: parsed.trigger.heartbeat },
         session: parsed.session,
         exitReason: parsed.exitReason,
         costUsd: parsed.costUsd,
@@ -6943,6 +7199,27 @@ ${rationale}`}`);
       failures: outcome === "failed" ? cron2.failures + 1 : outcome === "completed" ? 0 : cron2.failures
     });
   }
+  /**
+   * Marks a cron's failed fire caught up by a completed turn whose prompt named it, while that
+   * failure is still its latest run. Its schedule and its run of failures stay as they are.
+   */
+  async catchUpCron(shown, record) {
+    if (record.id === void 0 || !await exists(this.paths.cron(shown.cron))) {
+      return;
+    }
+    const cron2 = await this.readCron(shown.cron);
+    const failure = cronFailure(cron2);
+    if (failure === null || failure.turnId !== shown.turnId) {
+      return;
+    }
+    await this.writeCron({
+      ...cron2,
+      lastRun: {
+        ...failure,
+        caughtUp: { turnId: record.id, at: record.endedAt ?? this.now().toISOString() }
+      }
+    });
+  }
   /**
    * Whether a conversation with a workspace of its own has ended: a thread closed, a task ended
    * (for one from before tasks had threads), a channel archived, or a project archived, which ends
@@ -8312,7 +8589,7 @@ ${charter.purpose}
   }
   assertMayGate(actor, what) {
     if (!PLANNING_ROLES.includes(actor.role)) {
-      throw new BoardError("FORBIDDEN", `only the user, the steward, and the concierge may ${what}; ask one of them in the task's thread`);
+      throw new BoardError("FORBIDDEN", `only the user, the steward, and the concierge may ${what}; ask one of them in the task's thread, with a mention`);
     }
   }
   /** The user holds anything; everyone else must be a project member the current stage admits. */
@@ -8354,6 +8631,51 @@ ${charter.purpose}
   leaseEnd(now) {
     return new Date(now.getTime() + this.leaseMs).toISOString();
   }
+  /**
+   * The lease a holder's own crons in the task's thread keep its claim to, when later than the one
+   * it has, else null. While one of them is pending, the lease is renewed for a full lease once less
+   * than half is left, so it never lapses between fires that may be hours apart; once every one is
+   * paused, ended, or failed at its latest fire with nothing catching it up (`cronStoppedAt`), it
+   * runs a full lease from when the last of them stopped.
+   */
+  keptLease(task2, crons, now) {
+    if (task2.leaseExpiresAt === void 0) {
+      return null;
+    }
+    const lease = Date.parse(task2.leaseExpiresAt);
+    let pending = false;
+    let stopped = null;
+    for (const cron2 of crons) {
+      if (cron2.agent !== task2.claimedBy || !firesInTask(cron2, task2)) {
+        continue;
+      }
+      const at = cronStoppedAt(cron2);
+      if (at === null) {
+        pending = true;
+      } else {
+        stopped = Math.max(stopped ?? 0, Date.parse(at));
+      }
+    }
+    const kept = pending ? lease - now.getTime() < this.leaseMs / 2 ? now.getTime() + this.leaseMs : lease : stopped === null ? lease : stopped + this.leaseMs;
+    return kept > lease ? new Date(kept).toISOString() : null;
+  }
+  /**
+   * The lease a holder keeps while the user's pause holds its turns in the task's project
+   * (`heldOn`), when later than the one it has, else null. It is renewed for a full lease once less
+   * than half is left, as for a pending cron, so it never lapses while the holder cannot take a
+   * turn there, and after the resume the holder has at least half a lease to come back to it.
+   */
+  async pausedLease(task2, runners, runner2, now) {
+    if (task2.claimedBy === void 0 || task2.leaseExpiresAt === void 0) {
+      return null;
+    }
+    const holder = await this.readAgent(task2.claimedBy).catch(() => null);
+    if (holder === null || !heldOn(runners, runner2, holder.cli)) {
+      return null;
+    }
+    const lease = Date.parse(task2.leaseExpiresAt);
+    return lease - now.getTime() < this.leaseMs / 2 ? this.leaseEnd(now) : null;
+  }
   leaseExpired(task2, now) {
     return task2.leaseExpiresAt !== void 0 && new Date(task2.leaseExpiresAt).getTime() <= now.getTime();
   }
@@ -8466,11 +8788,7 @@ ${charter.purpose}
         if (task2.claimedBy === actor.name || task2.createdBy === actor.name || task2.stages.some((stage) => stage.agent === actor.name || stage.holders.includes(actor.name))) {
           return true;
         }
-        if (task2.status !== "open" || task2.completing) {
-          return false;
-        }
-        const agent2 = await this.readAgent(actor.name);
-        return agent2.memberships.includes(task2.project) && mayHoldStage(actor, task2);
+        return await this.mayTakeStage(actor, task2);
       }
       if (subject?.kind === "proposal") {
         const proposal2 = await this.readProposal(subject.id);
@@ -8484,6 +8802,34 @@ ${charter.purpose}
     }
     return false;
   }
+  /** Whether a task's current stage waits for a holder and the member may take it. */
+  async mayTakeStage(actor, task2) {
+    if (task2.status !== "open" || task2.completing) {
+      return false;
+    }
+    const agent2 = await this.readAgent(actor.name);
+    return agent2.memberships.includes(task2.project) && mayHoldStage(actor, task2);
+  }
+  /**
+   * Which of a thread's posts count toward a reader's heartbeat (see `unreadByConversation`). A
+   * thread, or a task, the board cannot find counts as an open topic's would.
+   */
+  async threadCount(actor, id) {
+    const found = await this.tryFindThread(id);
+    if (found?.thread.state === "closed") {
+      return "none";
+    }
+    const subject = found?.thread.subject;
+    const task2 = subject?.kind === "task" ? await this.findTask(subject.id).then((location) => location.task, () => null) : null;
+    if (task2 === null) {
+      return "every";
+    }
+    const stageIsTheirs = task2.status === "claimed" ? task2.claimedBy === actor.name : await this.mayTakeStage(actor, task2);
+    if (stageIsTheirs) {
+      return "every";
+    }
+    return task2.createdBy === actor.name ? "asks-user" : "asked";
+  }
   async threadScopes() {
     const projects = await listDirs(this.paths.projects());
     return [this.paths.societyThreads(), ...projects.map((slug) => this.paths.threads(slug))];
@@ -8694,8 +9040,21 @@ runner.command("add <name>").description("Register a runner and print its token
 runner.command("list").description("List runners and what they offer").action(async () => {
   const board = await open3();
   const runners = await board.listRunners();
-  print(runners, () => runners.length === 0 ? "No runners yet; add one with `runner add <name>`." : runners.map((each) => `${each.name}  ${each.status}  ${each.os}${each.version === void 0 ? "" : `  v${each.version}`}  ${each.clis.join(",") || "no CLIs yet"}${each.capabilities.length === 0 ? "" : `  ${each.capabilities.join(",")}`}`).join("\n"));
+  print(runners, () => runners.length === 0 ? "No runners yet; add one with `runner add <name>`." : runners.map((each) => `${each.name}  ${each.status}${each.paused === void 0 ? "" : "  paused"}  ${each.os}${each.version === void 0 ? "" : `  v${each.version}`}  ${each.clis.join(",") || "no CLIs yet"}${each.capabilities.length === 0 ? "" : `  ${each.capabilities.join(",")}`}${Object.keys(each.pausedClis ?? {}).map((cli) => `  ${cli} paused`).join("")}`).join("\n"));
 });
+for (const [verb, paused] of [
+  ["pause", true],
+  ["resume", false]
+]) {
+  runner.command(`${verb} <name> [cli]`).description(paused ? "Start no more turns on a runner, or with one of its CLIs, until resumed; turns in flight finish" : "Let a paused runner, or a paused CLI on it, take turns again").action(async (name, cli) => {
+    const board = await open3();
+    const updated = await board.setRunnerPaused(board.userActor(), name, {
+      paused,
+      ...cli === void 0 ? {} : { cli: CliKindSchema.parse(cli) }
+    });
+    print(updated, () => `${cli === void 0 ? name : `${cli} on ${name}`} ${verb}d`);
+  });
+}
 var agent = program.command("agent").description("Manage agents");
 agent.command("add <name>").description("Add an agent and print its board token once").requiredOption("--role <role>", "role charter name").option("--cli <cli>", "claude or codex").option("--model <model>", "model to run the CLI with; the CLI's own default otherwise").option("--runner <name>", "runner preferred for its turns; any with its CLI otherwise").option("-p, --project <slug...>", "project memberships").action(async (name, opts) => {
   const board = await open3();