@kubitnodes/stellaris 0.3.20 → 0.3.21

package/dist/server/index.js

@@ -146,7 +146,7 @@ var SEED_ROLES = [
   },
   {
     name: "steward",
-    purpose: "Watches the operations signals and the task board for capacity, skill, and capability gaps, and turns signals into proposals: a member when a project's plans need a role nobody fills or a backlog persists, a role when a project's work needs one no existing role covers, a retirement when a member has been idle for a long time. Opens a channel with create_channel when a topic or a workstream needs one, and archives it once its work is done. Owns how work is shaped over time: answers stages waiting too long, stages assigned to roles nobody fills, and work sent back again and again by replanning with plan_task, adjusting gates, or proposing the role a plan needs; sets each project's completion effect with configure_project; turns recurring plan shapes into society skills and planning norms into the society's norms. Prefers scaling an existing role over inventing a new one. Never approves its own proposals; hiring, roles, and retirements are decided by the user, and channels, reallocations, and skills the steward may decide. Curates society knowledge and skills.",
+    purpose: "Watches the operations signals and the task board for capacity, skill, and capability gaps, and turns signals into proposals: a member when a project's plans need a role nobody fills or a backlog persists, a role when a project's work needs one no existing role covers, a retirement when a member has been idle for a long time. Opens a channel with create_channel when a topic or a workstream needs one, and archives it once its work is done. Owns how work is shaped over time: answers stages waiting too long, stages assigned to roles nobody fills, and work sent back again and again by replanning with plan_task, adjusting gates, or proposing the role a plan needs; sets each project's completion effect with configure_project; turns recurring plan shapes into society skills and planning norms into the society's norms. Prefers scaling an existing role over inventing a new one, by a reallocation of its replicas, backlog threshold, wakes, or verbs. Never approves its own proposals; hiring, roles, retirements, and reallocations that change a role's verbs or replicas are decided by the user, and channels, skills, and other reallocations the steward may decide. Curates society knowledge and skills.",
     verbs: [...MEMBER_VERBS, ...GOVERNANCE_VERBS, ...PLANNING_VERBS, ...CURATING_VERBS],
     wakeTriggers: ["ops_event", "heartbeat"],
     maxReplicas: 1,
@@ -631,9 +631,54 @@ var ChannelProposalSchema = z4.object({
   name: NameSchema,
   purpose: z4.string().min(1)
 });
+var RoleChangesSchema = z4.strictObject({
+  maxReplicas: z4.number().int().min(1).optional(),
+  backlogThreshold: z4.number().positive().optional(),
+  wakeTriggers: z4.array(CharterTriggerSchema).optional(),
+  verbs: z4.array(VerbNameSchema).optional()
+}).refine((changes) => Object.values(changes).some((value) => value !== void 0), {
+  message: "a reallocation changes at least one of maxReplicas, backlogThreshold, wakeTriggers, verbs"
+});
 var ReallocationProposalSchema = z4.object({
+  role: NameSchema,
+  changes: RoleChangesSchema,
   description: z4.string().min(1)
 });
+var LegacyReallocationSchema = z4.object({ description: z4.string().min(1) });
+function applyRoleChanges(role, changes) {
+  return {
+    ...role,
+    ...changes.maxReplicas === void 0 ? {} : { maxReplicas: changes.maxReplicas },
+    ...changes.backlogThreshold === void 0 ? {} : { backlogThreshold: changes.backlogThreshold },
+    ...changes.wakeTriggers === void 0 ? {} : { wakeTriggers: [...changes.wakeTriggers] },
+    ...changes.verbs === void 0 ? {} : { verbs: [...changes.verbs] }
+  };
+}
+function listedOrNone(values) {
+  return values.length === 0 ? "none" : values.join(", ");
+}
+function roleChangeLines(role, changes) {
+  const lines = [];
+  if (changes.maxReplicas !== void 0 && changes.maxReplicas !== role.maxReplicas) {
+    lines.push(`maxReplicas ${role.maxReplicas} \u2192 ${changes.maxReplicas}`);
+  }
+  if (changes.backlogThreshold !== void 0 && changes.backlogThreshold !== role.backlogThreshold) {
+    lines.push(`backlogThreshold ${role.backlogThreshold} \u2192 ${changes.backlogThreshold}`);
+  }
+  const wakes = changes.wakeTriggers;
+  if (wakes !== void 0 && (wakes.length !== role.wakeTriggers.length || wakes.some((trigger) => !role.wakeTriggers.includes(trigger)))) {
+    lines.push(`wakeTriggers ${listedOrNone(role.wakeTriggers)} \u2192 ${listedOrNone(wakes)}`);
+  }
+  if (changes.verbs !== void 0) {
+    const next = changes.verbs;
+    const added = next.filter((verb) => !role.verbs.includes(verb)).map((verb) => `+${verb}`);
+    const removed = role.verbs.filter((verb) => !next.includes(verb)).map((verb) => `\u2212${verb}`);
+    if (added.length + removed.length > 0) {
+      lines.push(`verbs ${[...added, ...removed].join(" ")}`);
+    }
+  }
+  return lines;
+}
 var RetirementProposalSchema = z4.object({
   agent: NameSchema,
   reason: z4.string().min(1)
@@ -665,6 +710,32 @@ var ROLE_KIND_APPROVERS = {
   reallocation: [USER_ROLE, "steward"],
   skill: [USER_ROLE, "steward"]
 };
+var USER_DECIDED_ROLE_CHANGES = ["verbs", "maxReplicas"];
+function proposalApprovers(kind, charter) {
+  if (kind === "reallocation") {
+    const parsed = ReallocationProposalSchema.safeParse(charter);
+    if (parsed.success && USER_DECIDED_ROLE_CHANGES.some((field) => parsed.data.changes[field] !== void 0)) {
+      return [USER_ROLE];
+    }
+  }
+  return ROLE_KIND_APPROVERS[kind];
+}
+function describeRoleChanges(changes) {
+  const parts = [];
+  if (changes.maxReplicas !== void 0) {
+    parts.push(`up to ${changes.maxReplicas} per project`);
+  }
+  if (changes.backlogThreshold !== void 0) {
+    parts.push(`backlog threshold ${changes.backlogThreshold}`);
+  }
+  if (changes.wakeTriggers !== void 0) {
+    parts.push(changes.wakeTriggers.length === 0 ? "no ambient wakes" : `wakes on ${changes.wakeTriggers.join(", ")}`);
+  }
+  if (changes.verbs !== void 0) {
+    parts.push(`${changes.verbs.length} verbs`);
+  }
+  return parts.join(", ");
+}
 function describeCharter(kind, charter) {
   switch (kind) {
     case "member": {
@@ -696,9 +767,14 @@ function describeCharter(kind, charter) {
     }
     case "reallocation": {
       const parsed = ReallocationProposalSchema.safeParse(charter);
-      if (!parsed.success)
+      if (parsed.success) {
+        const { role, changes, description } = parsed.data;
+        return `reallocation of role ${role} (${describeRoleChanges(changes)}): ${description}`;
+      }
+      const legacy = LegacyReallocationSchema.safeParse(charter);
+      if (!legacy.success)
         break;
-      return `reallocation: ${parsed.data.description}`;
+      return `reallocation: ${legacy.data.description}`;
     }
     case "skill": {
       const parsed = SkillProposalSchema.safeParse(charter);
@@ -1007,7 +1083,7 @@ var VERB_DESCRIPTIONS = {
   create_task: "Create a task in a project with its plan: stages of {name, role or agent, gate}. Without stages it gets one stage, work, that anyone in the project may take. File it in a channel of the project, such as a release's, or general by default; its thread opens there with it, under the task's id, for everything said about the work.",
   claim_task: "Hold the task's current stage. Claims are leases renewed by every turn that touches the task.",
   release_task: "Let go of the stage you hold so someone else can take it.",
-  update_task: "Move a task back to an earlier stage, abandon it, set what it is blocked by, or link its pull request (pull_request: url, with the merge commit's merge_subject and merge_body), which a ghpr task needs before its last stage completes. A note is posted to the task's thread.",
+  update_task: "Move a task back to an earlier stage, abandon it, set the tasks it is blocked by (blocked_by: its stage wakes nobody until they have all ended), or link its pull request (pull_request: url, with the merge commit's merge_subject and merge_body), which a ghpr task needs before its last stage completes. A note is posted to the task's thread.",
   get_task: "Read a task with its plan, its brief, and the messages of its thread.",
   subscribe: "Subscribe to a channel. Subscriptions feed your digest; they never wake you.",
   unsubscribe: "Unsubscribe from a channel.",
@@ -1869,7 +1945,7 @@ var RunnerConfigSchema = z11.object({
 });
 
 // packages/shared/dist/version.js
-var STELLARIS_VERSION = "0.3.20";
+var STELLARIS_VERSION = "0.3.21";
 
 // packages/board-core/dist/errors.js
 var BoardError = class extends Error {
@@ -4606,18 +4682,16 @@ ${DASHBOARD_LINE}
   async readDigest(actor, input = {}) {
     const args = VerbInputs.read_inbox.parse(input);
     await this.authorize(actor, "read_inbox");
-    return this.mutex.run(async () => {
-      const stored = await this.readCursors(actor.name);
-      const from = args.since_cursor === void 0 ? stored : { ...NO_CURSORS, digest: args.since_cursor };
-      const conversation = actor.scope === void 0 ? void 0 : { scope: actor.scope, part: conversationPart(actor) ?? null };
-      const filed = (await this.digestSince(actor, from, conversation)).slice(0, args.limit);
-      if (args.advance) {
-        await this.advanceCursors(actor.name, filed);
-      }
-      const last = filed.at(-1)?.message.id;
-      const cursor = last ?? (conversation === void 0 ? from.digest : cursorOf(from, conversation.scope, conversation.part));
-      return { messages: filed.map((entry) => entry.message), cursor };
-    });
+    const { cursors: stored, upto } = await this.digestSnapshot(actor.name);
+    const from = args.since_cursor === void 0 ? stored : { ...NO_CURSORS, digest: args.since_cursor };
+    const conversation = actor.scope === void 0 ? void 0 : { scope: actor.scope, part: conversationPart(actor) ?? null };
+    const filed = (await this.digestSince(actor, from, upto, conversation)).slice(0, args.limit);
+    if (args.advance) {
+      await this.mutex.run(() => this.advanceCursors(actor.name, filed));
+    }
+    const last = filed.at(-1)?.message.id;
+    const cursor = last ?? (conversation === void 0 ? from.digest : cursorOf(from, conversation.scope, conversation.part));
+    return { messages: filed.map((entry) => entry.message), cursor };
   }
   /**
    * How many unread digest messages a member has in each conversation: a scope's home, for its
@@ -4629,28 +4703,39 @@ ${DASHBOARD_LINE}
    * whose signals that call for action wake their readers directly.
    */
   async unreadByConversation(actor) {
-    return this.mutex.run(async () => {
-      const counts = /* @__PURE__ */ new Map();
-      const unscoped = { name: actor.name, role: actor.role };
-      for (const { scope, part, message, news } of await this.digestSince(unscoped, await this.readCursors(actor.name))) {
-        if (news === true || message.step !== void 0 || message.author === SYSTEM_ACTOR.name) {
-          continue;
-        }
-        const posted = parseChannelRef(message.channel).project ?? SOCIETY_SCOPE;
-        if (posted !== scope && scope !== SOCIETY_SCOPE) {
-          continue;
-        }
-        const key = conversationKey(scope, part);
-        const entry = counts.get(key) ?? {
-          scope,
-          thread: threadOfPart(part) ?? null,
-          channel: channelOfPart(part) ?? null,
-          count: 0
-        };
-        counts.set(key, { ...entry, count: entry.count + 1 });
+    const { cursors, upto } = await this.digestSnapshot(actor.name);
+    const counts = /* @__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) {
+        continue;
       }
-      return [...counts.values()];
-    });
+      const posted = parseChannelRef(message.channel).project ?? SOCIETY_SCOPE;
+      if (posted !== scope && scope !== SOCIETY_SCOPE) {
+        continue;
+      }
+      const key = conversationKey(scope, part);
+      const entry = counts.get(key) ?? {
+        scope,
+        thread: threadOfPart(part) ?? null,
+        channel: channelOfPart(part) ?? null,
+        count: 0
+      };
+      counts.set(key, { ...entry, count: entry.count + 1 });
+    }
+    return [...counts.values()];
+  }
+  /**
+   * A reader's cursors and the id below which every message is already on disk, taken under the
+   * mutex, which a digest scan then leaves: messages carry ids from the same monotonic source and are
+   * written under the mutex, so the scan, which counts nothing newer than the mark, cannot pass over
+   * one written while it reads, and a post never waits for a scan.
+   */
+  digestSnapshot(agent) {
+    return this.mutex.run(async () => ({
+      cursors: await this.readCursors(agent),
+      upto: this.newId()
+    }));
   }
   async readCursors(agent) {
     const file = this.paths.agentCursors(agent);
@@ -4692,9 +4777,10 @@ ${DASHBOARD_LINE}
    * by the user wherever it is. With a conversation, only what is filed there: for a thread, every
    * message of the thread, since the conversation is about it; for a channel's, that channel's
    * top-level messages; for a scope's home, general's and those of a project the member is not in,
-   * since each thread and each other channel is a conversation of its own.
+   * since each thread and each other channel is a conversation of its own. Nothing newer than
+   * `upto` counts (see `digestSnapshot`).
    */
-  async digestSince(actor, cursors, conversation) {
+  async digestSince(actor, cursors, upto, conversation) {
     const conversationThread = threadOfPart(conversation?.part);
     if (conversation !== void 0 && conversationThread !== void 0) {
       const { scope, part } = conversation;
@@ -4702,7 +4788,7 @@ ${DASHBOARD_LINE}
       if (found === null) {
         return [];
       }
-      const messages = await this.readMessagesIn(this.paths.threadMessages(found.threads, conversationThread), cursorOf(cursors, scope, part));
+      const messages = await this.readMessagesIn(this.paths.threadMessages(found.threads, conversationThread), cursorOf(cursors, scope, part), upto);
       return messages.filter((message) => message.author !== actor.name).map((message) => ({ scope, part, message })).toSorted(byId);
     }
     const agent = await this.readAgent(actor.name);
@@ -4720,7 +4806,7 @@ ${DASHBOARD_LINE}
     ];
     const known = starts.filter((start) => start !== null);
     const since = known.length < starts.length ? null : known.toSorted((a, b) => a < b ? -1 : a > b ? 1 : 0)[0] ?? null;
-    for await (const message of this.iterateMessages(since)) {
+    for await (const message of this.iterateMessages(since, void 0, upto)) {
       const filedIn = wakeScope(agent, parseChannelRef(message.channel).project);
       const thread = message.thread ?? null;
       const asked = message.mentions.includes(actor.name) || frontDesk && message.author === USER_NAME;
@@ -5844,6 +5930,9 @@ ${args.summary}`);
       }
       if (args.blocked_by !== void 0) {
         for (const id of args.blocked_by) {
+          if (id === current.id) {
+            throw new BoardError("VALIDATION", `task ${current.id} cannot be blocked by itself`);
+          }
           await this.findTask(id);
         }
         next = { ...next, blockedBy: [...args.blocked_by] };
@@ -5880,6 +5969,7 @@ ${args.summary}`);
           from: current.status,
           to: task.status,
           note: args.note ?? null,
+          ...args.blocked_by === void 0 ? {} : { blockedBy: task.blockedBy, previousBlockedBy: current.blockedBy },
           ...args.pull_request === void 0 ? {} : { pullRequest: task.pullRequest?.url ?? null }
         });
       }
@@ -7178,12 +7268,37 @@ Short, curated, loaded on every turn. Keep entries that change future behavior a
       case "archive":
         await this.validateArchive(ArchiveProposalSchema.parse(charter).project);
         return;
-      case "reallocation":
+      case "reallocation": {
+        const parsed = ReallocationProposalSchema.safeParse(charter);
+        if (parsed.success) {
+          await this.reallocatedRole(parsed.data);
+        } else {
+          LegacyReallocationSchema.parse(charter);
+        }
         return;
+      }
       default:
         return;
     }
   }
+  /**
+   * The role as a reallocation would leave it, with what changes: refused for the user's charter,
+   * a role that does not exist, a charter the changes would make invalid, and changes the role
+   * has already.
+   */
+  async reallocatedRole(reallocation) {
+    if (reallocation.role === USER_ROLE) {
+      throw new BoardError("FORBIDDEN", "the user charter is not subject to proposals");
+    }
+    const current = await this.readRole(reallocation.role);
+    const next = RoleCharterSchema.parse(applyRoleChanges(current, reallocation.changes));
+    await this.validateRole(next);
+    const changed = roleChangeLines(current, reallocation.changes);
+    if (changed.length === 0) {
+      throw new BoardError("VALIDATION", `role ${current.name} has these values already; the reallocation changes nothing`);
+    }
+    return { next, changed };
+  }
   async executeProvision(by, proposal) {
     const meta = { proposalId: proposal.id };
     switch (proposal.kind) {
@@ -7220,8 +7335,15 @@ Short, curated, loaded on every turn. Keep entries that change future behavior a
         const { members } = await this.archiveUnlocked(by, input.project, input.reason, meta);
         return { project: input.project, members };
       }
-      case "reallocation":
-        return void 0;
+      case "reallocation": {
+        const parsed = ReallocationProposalSchema.safeParse(proposal.charter);
+        if (!parsed.success) {
+          return void 0;
+        }
+        const { next, changed } = await this.reallocatedRole(parsed.data);
+        await this.writeRoleUnlocked(by, next, meta);
+        return { role: next.name, changed };
+      }
       default:
         return void 0;
     }
@@ -7921,7 +8043,7 @@ ${charter.purpose}
     if (filed.proposedBy === actor.name) {
       throw new BoardError("FORBIDDEN", "a proposer never decides its own proposal");
     }
-    const approvers = ROLE_KIND_APPROVERS[filed.kind];
+    const approvers = proposalApprovers(filed.kind, filed.charter);
     if (!approvers.includes(actor.role)) {
       throw new BoardError("FORBIDDEN", `a ${filed.kind} proposal requires one of: ${approvers.join(", ")}`);
     }
@@ -8004,7 +8126,7 @@ ${charter.purpose}
       }
       if (subject?.kind === "proposal") {
         const proposal = await this.readProposal(subject.id);
-        if (proposal.proposedBy === actor.name || proposal.decidedBy === actor.name || ROLE_KIND_APPROVERS[proposal.kind].includes(actor.role)) {
+        if (proposal.proposedBy === actor.name || proposal.decidedBy === actor.name || proposalApprovers(proposal.kind, proposal.charter).includes(actor.role)) {
           return true;
         }
         return (await this.readRole(actor.role)).wakeTriggers.includes(OPS_WAKE_TRIGGER);
@@ -8061,11 +8183,12 @@ ${charter.purpose}
     });
     await this.endCronsUnlocked(by, `its thread closed: its ${found.thread.subject?.kind ?? "subject"} was ${ended}`, (cron) => cron.thread === subjectId);
   }
-  async readMessagesIn(dir, since) {
+  /** The messages in a folder after `since` and, when given, up to `upto`, read by name first. */
+  async readMessagesIn(dir, since, upto) {
     const messages = [];
     for (const file of await listFiles(dir)) {
       const id = file.slice(0, 26);
-      if (since !== null && id <= since) {
+      if (since !== null && id <= since || upto !== void 0 && id > upto) {
         continue;
       }
       const doc = await readMarkdown(path6.join(dir, file), MessageFrontmatterSchema);
@@ -8073,20 +8196,23 @@ ${charter.purpose}
     }
     return messages;
   }
-  /** Every message newer than `since` across society channels, project channels, and threads. */
-  async *iterateMessages(since, project) {
+  /**
+   * Every message newer than `since`, and no newer than `upto` when given, across society
+   * channels, project channels, and threads.
+   */
+  async *iterateMessages(since, project, upto) {
     if (project === void 0) {
       for (const channel of await listDirs(this.paths.societyChannels())) {
-        yield* await this.readMessagesIn(this.paths.societyChannel(channel), since);
+        yield* await this.readMessagesIn(this.paths.societyChannel(channel), since, upto);
       }
-      yield* this.threadMessagesIn(this.paths.societyThreads(), since);
+      yield* this.threadMessagesIn(this.paths.societyThreads(), since, upto);
     }
     const projects = project === void 0 ? await listDirs(this.paths.projects()) : [project];
     for (const slug of projects) {
       for (const channel of await listDirs(this.paths.projectChannels(slug))) {
-        yield* await this.readMessagesIn(this.paths.projectChannel(slug, channel), since);
+        yield* await this.readMessagesIn(this.paths.projectChannel(slug, channel), since, upto);
       }
-      yield* this.threadMessagesIn(this.paths.threads(slug), since);
+      yield* this.threadMessagesIn(this.paths.threads(slug), since, upto);
     }
   }
   /** Every folder that holds messages: each channel's and each thread's, in the society and every project. */
@@ -8106,9 +8232,9 @@ ${charter.purpose}
       }
     }
   }
-  async *threadMessagesIn(threads, since) {
+  async *threadMessagesIn(threads, since, upto) {
     for (const id of await listDirs(threads)) {
-      yield* await this.readMessagesIn(this.paths.threadMessages(threads, id), since);
+      yield* await this.readMessagesIn(this.paths.threadMessages(threads, id), since, upto);
     }
   }
 };
@@ -8492,7 +8618,7 @@ var Scheduler = class {
           return;
         }
         if (stringOf(payload["thread"]) !== taskId) {
-          await this.wakeHolder(taskId, event.actor, now);
+          await this.wakeHolder(taskId, event.actor, event.actor, now);
         }
         await this.pruneStageWakes(taskId);
         return;
@@ -8518,6 +8644,7 @@ var Scheduler = class {
         if (creator !== null && creator !== event.actor) {
           await this.wakeCreator(taskId, project, creator, event.actor, now);
         }
+        await this.wakeDependents(taskId, event.actor, now);
         const threaded = await this.board.readThread(taskId).then(() => true, () => false);
         if (!threaded) {
           this.sweep({ kind: "thread", id: taskId });
@@ -8537,12 +8664,17 @@ var Scheduler = class {
       }
       case "task.updated": {
         const taskId = stringOf(payload["taskId"]);
-        if (taskId !== null && payload["to"] === "abandoned") {
+        if (taskId === null) {
+          return;
+        }
+        if (payload["to"] === "abandoned") {
           delete this.state.releaseCounts[taskId];
           await this.queueClosing(taskId);
+          await this.wakeDependents(taskId, event.actor, now);
         }
-        if (taskId !== null) {
-          await this.pruneStageWakes(taskId);
+        await this.pruneStageWakes(taskId);
+        if (Array.isArray(payload["blockedBy"]) && (await this.blockersInPlay(stringArray(payload["previousBlockedBy"]))).length > 0) {
+          await this.wakeUnblocked(taskId, event.actor, now);
         }
         return;
       }
@@ -8713,9 +8845,10 @@ var Scheduler = class {
   }
   /**
    * Entering a stage wakes its named citizen, else its last holder when work returns to it, else
-   * the project's members of its role, else every member of the project who may hold it.
+   * the project's members of its role, else every member of the project who may hold it. A stage
+   * of a blocked task wakes nobody until its last blocker ends (`wakeUnblocked`).
    */
-  async wakeStage(taskId, from, now, only) {
+  async wakeStage(taskId, from, now, options = {}) {
     let task;
     try {
       task = (await this.board.findTask(taskId)).task;
@@ -8726,6 +8859,10 @@ var Scheduler = class {
     if (stage === void 0 || task.status !== "open" || task.completing) {
       return;
     }
+    if ((await this.blockersInPlay(task.blockedBy)).length > 0) {
+      return;
+    }
+    const { only, state = "is waiting for you" } = options;
     const lastHolder = stage.holders.at(-1);
     const targets = stage.agent !== void 0 ? [stage.agent] : lastHolder !== void 0 ? [lastHolder] : stage.role !== void 0 ? (await this.board.membersWithRole(task.project, stage.role)).map((a) => a.name) : (await this.board.projectMembers(task.project)).map((a) => a.name);
     for (const name of targets) {
@@ -8736,7 +8873,7 @@ var Scheduler = class {
       if (agent === null || !mayHoldStage(agent, task)) {
         continue;
       }
-      await this.enqueueStage(agent, task, from, now, "is waiting for you");
+      await this.enqueueStage(agent, task, from, now, state);
     }
   }
   /**
@@ -8745,7 +8882,7 @@ var Scheduler = class {
    */
   async wakeNewcomer(name, project, now) {
     for (const task of await this.board.openTasks(project).catch(() => [])) {
-      await this.wakeStage(task.id, name, now, name);
+      await this.wakeStage(task.id, name, now, { only: name });
     }
   }
   /**
@@ -8753,7 +8890,7 @@ var Scheduler = class {
    * worked in that conversation, which nothing else would start before the next heartbeat. Turns
    * of one conversation run one at a time, so the turn this queues is the one that sees the claim.
    */
-  async wakeHolder(taskId, holder, now) {
+  async wakeHolder(taskId, holder, from, now, state = "is yours; its work happens here") {
     let task;
     try {
       task = (await this.board.findTask(taskId)).task;
@@ -8764,12 +8901,66 @@ var Scheduler = class {
     if (agent === null || task.status !== "claimed" || task.claimedBy !== holder) {
       return;
     }
-    const key = await this.enqueueStage(agent, task, holder, now, "is yours; its work happens here");
+    const key = await this.enqueueStage(agent, task, from, now, state);
     const item = key === null ? void 0 : this.pending.get(key);
     if (item?.stageWakes !== void 0) {
       item.holder = true;
     }
   }
+  /**
+   * The ids among these that name a task still open or claimed, a landing one included. A task
+   * blocked by any of them waits for them rather than for a holder: its stage wakes nobody, by
+   * coming up or on a heartbeat, until the last one ends.
+   */
+  async blockersInPlay(ids) {
+    const blocking = [];
+    for (const id of ids) {
+      try {
+        const { task } = await this.board.findTask(id);
+        if (task.status === "open" || task.status === "claimed") {
+          blocking.push(id);
+        }
+      } catch {
+      }
+    }
+    return blocking;
+  }
+  /**
+   * A task's last blocker has ended, or its blockers were changed to none in play: its stage wakes
+   * as on coming up, or its holder in the task's conversation, since nothing woke either for it
+   * while it was blocked.
+   */
+  async wakeUnblocked(taskId, from, now) {
+    let task;
+    try {
+      task = (await this.board.findTask(taskId)).task;
+    } catch {
+      return;
+    }
+    if (task.completing || (await this.blockersInPlay(task.blockedBy)).length > 0) {
+      return;
+    }
+    if (task.status === "open") {
+      await this.wakeStage(task.id, from, now, {
+        state: "is waiting for you, now that nothing blocks it"
+      });
+    } else if (task.status === "claimed" && task.claimedBy !== void 0) {
+      await this.wakeHolder(task.id, task.claimedBy, from, now, "is yours, and nothing blocks it any more");
+    }
+  }
+  /** A task that ended unblocks every task in play that names it, once nothing else blocks them. */
+  async wakeDependents(taskId, from, now) {
+    for (const project of await this.board.listProjects()) {
+      if (project.archived !== void 0) {
+        continue;
+      }
+      for (const task of await this.board.listTasks(project.slug)) {
+        if (task.blockedBy.includes(taskId) && (task.status === "open" || task.status === "claimed")) {
+          await this.wakeUnblocked(task.id, from, now);
+        }
+      }
+    }
+  }
   /** Queues a stage wake in the task's conversation and returns its key, or null for no wake. */
   async enqueueStage(agent, task, from, now, state) {
     if (agent.status !== "active" || agent.cli === null) {
@@ -8805,9 +8996,9 @@ var Scheduler = class {
     }
   }
   /**
-   * The first of these stage wakes still due: its task waits, unheld, on a stage the agent may
-   * hold, or, with `holder`, the agent holds it, having claimed it outside the task's conversation.
-   * A wake for a stage the agent took in the turn the wake waited on is dropped.
+   * The first of these stage wakes still due: its task waits, unheld and unblocked, on a stage the
+   * agent may hold, or, with `holder`, the agent holds it, having claimed it outside the task's
+   * conversation. A wake for a stage the agent took in the turn the wake waited on is dropped.
    */
   async stillWaiting(name, wakes, holder) {
     const agent = await this.tryReadAgent(name);
@@ -8823,7 +9014,7 @@ var Scheduler = class {
         if (task.completing || currentStage(task) === void 0) {
           continue;
         }
-        if (task.status === "open" && mayHoldStage(agent, task)) {
+        if (task.status === "open" && mayHoldStage(agent, task) && (await this.blockersInPlay(task.blockedBy)).length === 0) {
           return wake;
         }
         if (holder && task.status === "claimed" && task.claimedBy === agent.name) {
@@ -9046,9 +9237,9 @@ var Scheduler = class {
   /**
    * A heartbeat per member and scope on the cadence, which then looks at every conversation of the
    * scope: the unread messages of its home, of each other channel, and of each thread, a stage the
-   * member holds, and a stage
-   * waiting that it may take, each in its task's thread. Each conversation with something wakes on
-   * its own, so a heartbeat never brings one task's business into another's turn.
+   * member holds, and a stage of an unblocked task waiting that it may take, each in its task's
+   * thread. Each conversation with something wakes on its own, so a heartbeat never brings one
+   * task's business into another's turn.
    */
   async checkHeartbeats(now) {
     for (const agent of await this.board.listAgents()) {
@@ -9100,7 +9291,7 @@ var Scheduler = class {
         }
         if (project !== SOCIETY_SCOPE) {
           for (const task of await this.board.openTasks(project)) {
-            if (mayHoldStage(agent, task)) {
+            if (mayHoldStage(agent, task) && (await this.blockersInPlay(task.blockedBy)).length === 0) {
               reasonsIn({ thread: { id: task.id, task: true } }).waiting += 1;
             }
           }
@@ -9252,9 +9443,10 @@ var Scheduler = class {
     return latest;
   }
   /**
-   * A current stage without a holder past the threshold is logged as a signal once while it waits.
-   * It wakes nobody by itself: its assignees see the stage on their heartbeat, and the steward reads
-   * the signal at its next turn and decides whether to replan or to mention someone.
+   * A current stage without a holder past the threshold is logged as a signal once while it waits,
+   * naming the tasks that still block it. It wakes nobody by itself: its assignees see the stage on
+   * their heartbeat, or a blocked one when its last blocker ends, and the steward reads the signal
+   * at its next turn and decides whether to replan or to mention someone.
    */
   async checkWaitingStages(now) {
     const stillWaiting = /* @__PURE__ */ new Set();
@@ -9275,10 +9467,12 @@ var Scheduler = class {
         }
         this.state.waitingSeen[key] = iso(now);
         const assignee2 = stage.agent ?? stage.role ?? "anyone in the project";
+        const blockers = await this.blockersInPlay(task.blockedBy);
+        const waited = blockers.length === 0 ? "for a holder" : `blocked by ${blockers.map((id) => `task ${id}`).join(", ")}`;
         await this.board.publishSignal({
           kind: "waiting_stage",
           key: `waiting_stage:${key}`,
-          summary: `stage "${stage.name}" of task ${task.id} "${task.title}" in ${project.slug}, for ${assignee2}, has waited ${describeDuration(age)} for a holder`,
+          summary: `stage "${stage.name}" of task ${task.id} "${task.title}" in ${project.slug}, for ${assignee2}, has waited ${describeDuration(age)} ${waited}`,
           value: age,
           threshold: this.timings.waitingStageMs,
           project: project.slug,
@@ -9741,6 +9935,7 @@ var TURN_CONTRACT = [
   "- To come back to something later, set a cron with create_cron: a note on what to do then, and a five-field cron expression or one time with at. It wakes you in this conversation unless you name another, at most every fifteen minutes, and every fire is a paid turn, so end a cron with remove_cron once it has done its job. Never wait by holding a stage, sleeping, or leaving a process running: a turn's board token ends with the turn, so nothing it leaves behind can act on the board. The society's crons are under society/crons/ in the board projection.",
   "- An @mention wakes the citizen named, and every wake costs a turn. Address someone with @ only when you need them to act; when you merely refer to citizens, write their names plainly. @user wakes nobody, since the user takes no turns; it is what puts a question before the user, so use it only when you need the user to answer or decide.",
   "- A thread is a conversation off a channel that reaches only its participants and whoever is mentioned in it. Every task has one, opened with it under the task's id on the channel of its project it was filed in, general unless it was filed in another: talk about a task there, with post_message and its thread_id, and the notes you give advance_task and update_task are posted there as you. Its participants are the task's creator, its stage holders and assignees, whoever may take the stage that waits, and anyone who posted; it closes when the task ends. Every proposal has one too, in governance, opened with its pitch and closed by its decision. Open other threads with open_thread on a channel with a title, for any other topic; close_thread posts your summary to its channel.",
+  "- To show an image in a post, such as a screenshot or a chart, commit the file to a task's branch and link it by its path in the task's worktree, as `![what it shows](<path>)`: the board shows a file on a task's branch in place once it is committed, at the latest when your turn ends. An image at an https address shows too. Never put an image or any other file into a message as base64 or a data: URL: the board does not show it, and every reader of the conversation gets it in full in their prompt.",
   "- Route every lesson: about you, your craft, or the user, write it to memory/core.md in your home directory, and keep that file short by moving detail to memory/<topic>.md, your archive; a durable fact about a project's codebase or process goes through `write_knowledge` on that project; something the whole project should know now, post it to the project channel, and anything about one task, in the task's thread.",
   '- A procedure you have followed twice is a skill: write it to skills/<name>/SKILL.md in your home, frontmatter with `name` and a one-line `description` and then the steps, and your skills index lists it from the next turn. Files the steps use, such as scripts/ and references/, go in the same folder, named in SKILL.md by paths relative to it. Propose it with kind "skill" when the whole society would use it.',
   "- To take a published skill for yourself, install it in a temporary folder and copy it into your home: in a folder from `mktemp -d`, `npx -y skills add <source> --skill <name> -a universal --copy -y` writes `.agents/skills/<name>/` and a lock file there, and you copy that skill folder to skills/<name>/ in your home, named in lowercase letters, digits, and hyphens. Never install one inside a worktree, where it would be committed into the project, or with -g, which writes to the runner's own home, shared by every citizen on it and listed in no skills index.",
@@ -9754,21 +9949,22 @@ var PLANNING = [
   "- Name stages by what gets done. Plan the next few steps rather than everything, and reshape with plan_task as the work teaches you.",
   "- Assign a stage to a role when anyone in it could do it, to a citizen only when it must be them, and to nobody when anyone in the project could. A citizen named on a stage must be a member of the task's project; add them first. A stage wakes everyone it is open to when it comes up, so the narrower the assignee, the fewer turns it costs.",
   "- Reshape rather than force: another round is an inserted stage, and a wait on something outside the society is a stage named for what it waits on. When a check finds work unfinished, send the task back to an earlier stage with update_task.",
+  "- A task that cannot start until other tasks finish names them with update_task blocked_by. While any of them is in play, its stage wakes nobody, neither when it comes up nor on a heartbeat; once the last has ended, done or abandoned, the stage wakes as if it had just come up, or wakes its holder. Nobody needs to clear the block or mention anyone when they end; change blocked_by only when the plan changes.",
   "- A gated stage is an independent check: nobody who held an earlier stage of the task may hold it, and only the user, the steward, and the concierge may add, remove, move, reassign, or ungate it. Ask them in the task's thread when a gate should change.",
   "- Commit your work on the task's branch before you advance, and say what you did in the advance note; it is the handover the next holder reads in the task's thread."
 ].join("\n");
 var GOVERNANCE = [
-  "- Anything the society lacks is a proposal: call `propose` with a kind and a charter. It opens the proposal's thread in governance with your rationale, where it is discussed and where the decision is posted. Approval provisions it on the spot, and either decision wakes the proposer. The user decides members, roles, retirements, and archives; the steward may also decide channels, reallocations, and skills. Nobody decides their own proposal.",
+  "- Anything the society lacks is a proposal: call `propose` with a kind and a charter. It opens the proposal's thread in governance with your rationale, where it is discussed and where the decision is posted. Approval provisions it on the spot, and either decision wakes the proposer. The user decides members, roles, retirements, archives, and reallocations that change a role's verbs or replicas; the steward may also decide channels, skills, and other reallocations. Nobody decides their own proposal.",
   "- Charter shapes, as JSON objects:",
   '  - member: {"name", "role", "cli": "claude" or "codex", "memberships": [project slugs], "model"?, "homeRunner"?, "subscriptions"?, "seedInstructions"?}',
   '  - role: {"name", "purpose", "verbs": [board verbs], "wakeTriggers"?: any of "user_post", "ops_event", "heartbeat" (heartbeat when omitted), "maxReplicas"?, "backlogThreshold"?, "societyScope"?: true for a society role, whose members are never in a project and keep watch over the whole society}. Mentions, stages that become yours, and finished tasks you created wake every role; a heartbeat wakes you when something is unread, held, or waiting for you.',
   '  - channel: {"project": slug or null, "name", "purpose"}',
   '  - retirement: {"agent", "reason"}',
   '  - archive: {"project", "reason"}: approval archives the project: its members leave, its open threads close, and nothing more is posted, filed, or joined there, while its files and history stay; refused while a task there is in play',
-  '  - reallocation: {"description"}',
-  '  - skill: {"name", "summary"}: the folder skills/<name>/ in your home, SKILL.md and every file beside it, which the board takes as it stands when this turn ends into society/proposals/<id>/, where whoever decides reads it; a proposal whose folder has no SKILL.md then is rejected by the board. Approval publishes it under society/skills/<name>/, where every citizen\'s skills index lists it until the steward or the user removes it with `remove_skill`; ask the steward to remove one that is wrong or superseded. A proposal from before folders carries "body", its SKILL.md text alone',
+  `  - reallocation: {"role", "changes": {"maxReplicas"?, "backlogThreshold"?, "wakeTriggers"?, "verbs"?}, "description"}: approval applies the changes to the existing role, each the field's new value and verbs and wakeTriggers whole lists, for its members from their next turn; refused for a role that does not exist or that has those values already. Only the user decides one that changes verbs or maxReplicas`,
+  '  - skill: {"name", "summary"}: the folder skills/<name>/ in your home, SKILL.md and every file beside it, which the board takes as it stands when this turn ends into society/proposals/<id>/, where whoever decides reads it; a proposal whose folder has no SKILL.md then is rejected by the board. Approval publishes it under society/skills/<name>/, where every citizen\'s skills index lists it until the steward or the user removes it with `remove_skill`; ask the steward to remove one that is wrong or superseded. Once yours is approved, delete skills/<name>/ from your home and report memoryUpdated: the board leaves your copy there, and your index would list it beside the published one and follow it as it drifts from what was reviewed. To revise a published skill, copy its folder home, edit it, and propose it again. A proposal from before folders carries "body", its SKILL.md text alone',
   "- Projects and membership: a project is a lasting area of work, not one request; `create_project` opens one with its general channel (front desk and user), and `configure_project` sets its completion effect, its display name, or its default branch, never its slug (user, steward, concierge). A workstream within a project or the society, such as a release, gets a channel of its own: `create_channel` opens it, which its opener follows, and announces it in the place's general, where members subscribe when it concerns them, `create_task` with `channel` files the workstream's tasks there, and `archive_channel` ends it once none of its tasks is in play, leaving its history readable (user, steward, concierge; others propose a channel). A project whose work is finished or has moved to another project is archived by proposal, once no task there is in play. `join_project` and `leave_project` move yourself, or another citizen when you are the concierge, the steward, or the user; joining gives the pair a worktree and an onboarding turn. A society role, one that keeps watch over the whole society as the concierge and the steward do, is never in a project: it moves others, never itself.",
-  "- Prefer scaling an existing role over inventing one; a new role is justified by work a project needs that no existing role covers. A role that needs a tool the board lacks is an engineering task, not a hiring request.",
+  "- Prefer scaling an existing role over inventing one, with a reallocation of its replicas, backlog threshold, wakes, or verbs; a new role is justified by work a project needs that no existing role covers. A role that needs a tool the board lacks is an engineering task, not a hiring request.",
   "- Operations signals are counters and timers the board logs, listed in the prompt of a role that reads them: stages waiting for a holder, backlog per role, stages waiting on a role nobody fills, churn, stale threads, idle members, missing capabilities, replicas added, spend. They are not posts in any channel; interpreting them is your judgment."
 ].join("\n");
 function renderOnboardingPreamble(context) {
@@ -9951,7 +10147,7 @@ function buildTurnPrompt(input) {
     lines.push("A task you created is done. Tell whoever asked for it, if anyone did.");
   }
   if (dispatch.trigger.kind === "proposal_decided") {
-    lines.push("A proposal you made was decided; the decision is the last post in the proposal's thread. A decision wakes you in the conversation you filed the proposal from, or at home once that has ended. Carry on with what an approval enables or a rejection asks, and stay silent if nothing follows.");
+    lines.push("A proposal you made was decided; the decision is the last post in the proposal's thread. A decision wakes you in the conversation you filed the proposal from, or at home once that has ended. Carry on with what an approval enables or a rejection asks, and stay silent if nothing follows. An approved skill is published under society/skills/<name>/: delete your own skills/<name>/ from your home and report memoryUpdated, so your index lists the published copy alone.");
   }
   if (dispatch.trigger.kind === "cron") {
     lines.push("A cron came due: what it asks is under Crons below.");
@@ -10737,7 +10933,7 @@ var TurnHost = class {
       if (await this.board.hasMentioned(actor.name, USER_NAME, since)) {
         return;
       }
-      const proposed = (await this.board.listProposals()).some((proposal) => proposal.proposedBy === actor.name && proposal.createdAt >= since && ROLE_KIND_APPROVERS[proposal.kind].includes(USER_ROLE));
+      const proposed = (await this.board.listProposals()).some((proposal) => proposal.proposedBy === actor.name && proposal.createdAt >= since && proposalApprovers(proposal.kind, proposal.charter).includes(USER_ROLE));
       if (proposed) {
         return;
       }