@kubitnodes/stellaris 0.3.0 → 0.3.2

package/dist/server/index.js

@@ -703,6 +703,8 @@ var BOARD_EVENT_TYPES = [
   "paused.changed",
   "wake.requested",
   "turn.started",
+  "turn.steered",
+  "turn.stopped",
   "turn.completed",
   "turn.failed",
   "merge.completed",
@@ -734,7 +736,8 @@ var TurnExitReasonSchema = z5.enum([
   "timeout",
   "error",
   "interrupted",
-  "blocked"
+  "blocked",
+  "stopped"
 ]);
 var AgentEventSchema = z5.discriminatedUnion("type", [
   z5.object({
@@ -745,6 +748,16 @@ var AgentEventSchema = z5.discriminatedUnion("type", [
     /** The model the CLI reports running, when it reports one. */
     model: z5.string().optional()
   }),
+  /**
+   * The CLI took a steer into the running turn. Adapters name the steer; the server adds the
+   * messages it delivered and the text the CLI was given.
+   */
+  z5.object({
+    type: z5.literal("steered"),
+    steer: z5.string().min(1),
+    messages: z5.array(UlidSchema).optional(),
+    text: z5.string().optional()
+  }),
   z5.object({ type: z5.literal("text"), delta: z5.string() }),
   z5.object({ type: z5.literal("tool_call"), name: z5.string(), input: z5.unknown() }),
   z5.object({
@@ -799,6 +812,12 @@ var RunnerHelloSchema = z6.object({
   clis: z6.array(CliKindSchema),
   /** The CLIs whose adapter can keep a session warm between turns. */
   residentClis: z6.array(CliKindSchema).default([]),
+  /** The CLIs whose adapter can take input into a running turn; the server steers only these. */
+  steerableClis: z6.array(CliKindSchema).default([]),
+  /** The CLIs whose adapter can stop a running turn; the server stops only these. */
+  stoppableClis: z6.array(CliKindSchema).default([]),
+  /** Whether the runner answers file reads on its projects' branches; one from before never does. */
+  branchReads: z6.boolean().default(false),
   capabilities: z6.array(z6.string()).default([]),
   /** Turns the runner runs at once, or null for no limit. */
   slots: z6.number().int().positive().nullable(),
@@ -902,10 +921,54 @@ var LandRequestSchema = z6.object({
 });
 var MergeOutcomeSchema = z6.object({ ok: z6.boolean(), detail: z6.string() });
 var ModelListSchema = z6.array(ModelOptionSchema);
+var BRANCH_FILE_LIMIT_BYTES = 8 * 1024 * 1024;
+var BranchPathSchema = z6.string().max(4096).refine((value) => value === "" || value.split("/").every((segment) => segment !== "" && segment !== "." && segment !== ".." && !segment.includes("\0")), { message: "a path inside the branch, with no empty, `.`, or `..` segment" });
+var BranchNameSchema = z6.string().regex(/^[A-Za-z0-9][A-Za-z0-9._/-]*$/);
+var BranchReadSchema = z6.object({
+  repo: ProjectRepoSchema,
+  branch: BranchNameSchema,
+  path: BranchPathSchema
+});
+var BranchCommitSchema = z6.object({
+  id: z6.string().min(1),
+  at: IsoDateTimeSchema,
+  author: z6.string()
+});
+var BranchFileSchema = z6.discriminatedUnion("kind", [
+  z6.object({
+    kind: z6.literal("file"),
+    path: BranchPathSchema,
+    commit: BranchCommitSchema,
+    size: z6.number().int().nonnegative(),
+    content: z6.string().nullable()
+  }),
+  z6.object({
+    kind: z6.literal("dir"),
+    path: BranchPathSchema,
+    commit: BranchCommitSchema,
+    entries: z6.array(z6.object({
+      name: z6.string().min(1),
+      kind: z6.enum(["file", "dir"]),
+      size: z6.number().int().nonnegative().nullable()
+    }))
+  })
+]);
+var TurnSteerSchema = z6.object({ id: z6.uuid(), text: z6.string().min(1) });
 var RunnerMessageSchema = z6.discriminatedUnion("type", [
   z6.object({ type: z6.literal("turn"), job: TurnJobSchema }),
   z6.object({ type: z6.literal("land"), request: z6.string().min(1), land: LandRequestSchema }),
-  z6.object({ type: z6.literal("models"), request: z6.string().min(1), cli: CliKindSchema })
+  z6.object({ type: z6.literal("models"), request: z6.string().min(1), cli: CliKindSchema }),
+  /** Answered with a `BranchFile`, or null when the branch or the path does not exist. */
+  z6.object({ type: z6.literal("file"), request: z6.string().min(1), read: BranchReadSchema }),
+  /** Answered with whether the CLI accepted it; that it took it comes as a `steered` event. */
+  z6.object({
+    type: z6.literal("steer"),
+    request: z6.string().min(1),
+    turnId: UlidSchema,
+    steer: TurnSteerSchema
+  }),
+  /** Answered with whether the turn was there to stop; it ends `stopped`. */
+  z6.object({ type: z6.literal("stop"), request: z6.string().min(1), turnId: UlidSchema })
 ]);
 var RunnerAnswerSchema = z6.discriminatedUnion("ok", [
   z6.object({ ok: z6.literal(true), value: z6.unknown() }),
@@ -984,7 +1047,19 @@ var TurnRecordSchema = z7.object({
   /** The model the CLI reported for this turn, else the model configured for the agent, else null. */
   model: z7.string().nullable().default(null),
   /** The task branch the turn left work on, with its commit, as the runner reported it. */
-  work: TurnWorkSchema.optional()
+  work: TurnWorkSchema.optional(),
+  /** Who stopped the turn, for one that ended `stopped`. */
+  stoppedBy: NameSchema.optional()
+});
+var RunningTurnSchema = z7.object({
+  turnId: UlidSchema,
+  agent: NameSchema,
+  scope: NameSchema,
+  thread: UlidSchema.optional(),
+  cli: CliKindSchema,
+  channel: ChannelRefSchema.optional(),
+  steerable: z7.boolean(),
+  stoppable: z7.boolean()
 });
 var SessionsFileSchema = z7.object({
   claude: z7.string().optional(),
@@ -1240,7 +1315,7 @@ var RunnerConfigSchema = z10.object({
 });
 
 // packages/shared/dist/version.js
-var STELLARIS_VERSION = "0.3.0";
+var STELLARIS_VERSION = "0.3.2";
 
 // packages/board-core/dist/errors.js
 var BoardError = class extends Error {
@@ -1787,10 +1862,12 @@ var TaskPayload = z11.object({
   from: z11.string().optional()
 });
 var MessagePayload = z11.object({
+  id: z11.string().optional(),
   channel: z11.string(),
   thread: z11.string().nullable().optional(),
   mentions: z11.array(z11.string()).default([])
 });
+var SteeredPayload = z11.object({ messages: z11.array(z11.string()) });
 var SignalPayload = z11.object({
   kind: z11.string(),
   key: z11.string(),
@@ -1897,6 +1974,23 @@ function computeMetrics(input) {
         }
         break;
       }
+      case "turn.steered": {
+        const steered = SteeredPayload.safeParse(event.payload);
+        if (!steered.success) {
+          break;
+        }
+        const delivered = new Set(steered.data.messages);
+        const at = Date.parse(event.ts);
+        const answered = waiting.filter((mention) => mention.agent === event.actor && mention.message !== null && delivered.has(mention.message));
+        if (answered.length > 0) {
+          latencies.set(event.actor, [
+            ...latencies.get(event.actor) ?? [],
+            ...answered.map((mention) => at - mention.at)
+          ]);
+          waiting = waiting.filter((mention) => !answered.includes(mention));
+        }
+        break;
+      }
       case "task.completed": {
         const task = TaskPayload.safeParse(event.payload);
         if (counted && task.success) {
@@ -1961,6 +2055,7 @@ function computeMetrics(input) {
           waiting.push({
             agent: name,
             at: Date.parse(event.ts),
+            message: message.data.id ?? null,
             thread,
             scopes: [project, wakeScope(citizen, project)].filter((scope) => scope !== null)
           });
@@ -4773,6 +4868,21 @@ ${rationale}`}`);
       });
     });
   }
+  /** Where a conversation's digest resumes: the newest message a turn there was shown. */
+  async digestCursor(agent, scope, thread) {
+    return this.mutex.run(async () => cursorOf(await this.readCursors(agent), scope, thread ?? null));
+  }
+  /** Records that a running turn took posts delivered into it, which wake latency counts to. */
+  async recordSteered(input) {
+    await this.mutex.run(async () => {
+      await this.events.append("turn.steered", input.agent, {
+        turnId: input.turnId,
+        project: input.project,
+        ...input.thread === void 0 ? {} : { thread: input.thread },
+        messages: [...input.messages]
+      });
+    });
+  }
   /** Where a conversation's session ids and last turn are kept: the scope's home, or a thread's. */
   sessionDir(agent, scope, thread) {
     return thread === void 0 ? this.paths.agentProject(agent, scope) : this.paths.agentThread(agent, scope, thread);
@@ -4842,6 +4952,14 @@ ${rationale}`}`);
       }
       await this.writeTurnRecord(parsed);
       await this.refreshMember(parsed.agent);
+      if (parsed.exitReason === "stopped") {
+        await this.events.append("turn.stopped", parsed.stoppedBy ?? USER_NAME, {
+          ...parsed.id === void 0 ? {} : { turnId: parsed.id },
+          agent: parsed.agent,
+          project: parsed.project,
+          ...parsed.thread === void 0 ? {} : { thread: parsed.thread }
+        });
+      }
       await this.events.append(failed ? "turn.failed" : "turn.completed", parsed.agent, {
         ...parsed.id === void 0 ? {} : { turnId: parsed.id },
         project: parsed.project,
@@ -6133,7 +6251,10 @@ var PendingSchema = z13.object({
   dispatch: TurnDispatchSchema,
   readyAt: z13.number(),
   stageWakes: z13.array(TriggerSchema).optional(),
-  holder: z13.boolean().optional()
+  holder: z13.boolean().optional(),
+  newestMessage: UlidSchema.optional(),
+  onlyMessages: z13.boolean().optional(),
+  steeredThrough: UlidSchema.optional()
 });
 var StateSchema = z13.object({
   cursor: z13.string().nullable(),
@@ -6152,6 +6273,16 @@ var StateSchema = z13.object({
   /** When each member last reflected, or was first seen; the cadence counts from here. */
   lastReflection: z13.record(z13.string(), z13.string()).default({})
 });
+function messageOf(trigger) {
+  return trigger.kind === "mention" || trigger.kind === "user_post" ? trigger.messageId : void 0;
+}
+function later(a, b) {
+  if (a === void 0)
+    return b;
+  if (b === void 0)
+    return a;
+  return a > b ? a : b;
+}
 var SILENT_LOG = { info() {
 }, warn() {
 }, error() {
@@ -6191,6 +6322,8 @@ var Scheduler = class {
   pending = /* @__PURE__ */ new Map();
   /** Turns in flight by session key, each with the lane it holds (see `laneOf`). */
   running = /* @__PURE__ */ new Map();
+  /** Steers under way, by session key; a pass does not wait for a runner to answer one. */
+  steering = /* @__PURE__ */ new Map();
   /** Tasks whose completion effect waits for the turn that finished their last stage to end. */
   completions = /* @__PURE__ */ new Map();
   completing = /* @__PURE__ */ new Set();
@@ -6245,7 +6378,8 @@ var Scheduler = class {
     await this.passing?.catch(() => void 0);
     await Promise.allSettled([
       ...[...this.running.values()].map((turn) => turn.promise),
-      ...this.completing
+      ...this.completing,
+      ...this.steering.values()
     ]);
   }
   /** One pass, unless one is under way already. */
@@ -6292,6 +6426,7 @@ var Scheduler = class {
   /** Waits for every running turn and in-flight completion to settle. Used by tests and by stop(). */
   async drain() {
     await Promise.allSettled([
+      ...this.steering.values(),
       ...[...this.running.values()].map((turn) => turn.promise),
       ...this.completing
     ]);
@@ -6708,6 +6843,7 @@ var Scheduler = class {
     const key = sessionKey(agent, project, thread?.id);
     const readyAt = now + debounce;
     const existing = this.pending.get(key);
+    const message = messageOf(trigger);
     if (existing === void 0) {
       this.pending.set(key, {
         dispatch: {
@@ -6719,10 +6855,13 @@ var Scheduler = class {
           onboarding: trigger.kind === "onboarding"
         },
         readyAt,
-        ...trigger.kind === "stage" ? { stageWakes: [trigger] } : {}
+        ...trigger.kind === "stage" ? { stageWakes: [trigger] } : {},
+        ...message === void 0 ? {} : { newestMessage: message },
+        onlyMessages: message !== void 0
       });
       return;
     }
+    const newestMessage = later(existing.newestMessage, message);
     const keepNew = decision.priority > existing.dispatch.priority;
     const priority = keepNew ? decision.priority : existing.dispatch.priority;
     this.pending.set(key, {
@@ -6736,7 +6875,10 @@ var Scheduler = class {
       ...existing.stageWakes !== void 0 && trigger.kind === "stage" ? {
         stageWakes: [...existing.stageWakes, trigger],
         ...existing.holder === true ? { holder: true } : {}
-      } : {}
+      } : {},
+      ...newestMessage === void 0 ? {} : { newestMessage },
+      onlyMessages: existing.onlyMessages === true && message !== void 0,
+      ...existing.steeredThrough === void 0 ? {} : { steeredThrough: existing.steeredThrough }
     });
   }
   /** Debounce coalesces chatter: mentions, stage handoffs, and bursts of signals. Everything else runs at once. */
@@ -7186,7 +7328,51 @@ var Scheduler = class {
     }
     return false;
   }
+  /**
+   * Delivers ready message wakes into the turn already running in their conversation, rather than
+   * keeping them for a turn of their own. Each stays queued until that turn ends and is checked
+   * again then, so a steer refused, or left untaken, loses nothing. A pass never waits on a runner.
+   */
+  steerRunning(now) {
+    const steer = this.runner.steer?.bind(this.runner);
+    if (steer === void 0) {
+      return;
+    }
+    for (const [key, item] of this.pending) {
+      const through = item.newestMessage;
+      if (item.readyAt > now || through === void 0 || !this.running.has(key) || this.steering.has(key) || item.steeredThrough !== void 0 && through <= item.steeredThrough) {
+        continue;
+      }
+      const { dispatch } = item;
+      const attempt = steer({
+        agent: dispatch.agent,
+        project: dispatch.project,
+        ...dispatch.thread === void 0 ? {} : { thread: dispatch.thread.id }
+      }).then((outcome) => {
+        const current = this.pending.get(key);
+        if (outcome !== "busy" && current !== void 0) {
+          current.steeredThrough = later(current.steeredThrough, through);
+        }
+        return void 0;
+      }).catch((error) => {
+        this.log.warn({ key, error: String(error) }, "steering failed");
+      }).finally(() => {
+        this.steering.delete(key);
+      });
+      this.steering.set(key, attempt);
+    }
+  }
+  /** Whether every message that woke a queued turn was read in its conversation, by a turn already. */
+  async alreadyRead(item) {
+    if (item.onlyMessages !== true || item.newestMessage === void 0) {
+      return false;
+    }
+    const { dispatch } = item;
+    const cursor = await this.board.digestCursor(dispatch.agent, dispatch.project, dispatch.thread?.id);
+    return cursor !== null && cursor >= item.newestMessage;
+  }
   async dispatchReady(now) {
+    this.steerRunning(now);
     const ready = [...this.pending.entries()].filter(([key, item]) => item.readyAt <= now && !this.running.has(key)).toSorted(([, a], [, b]) => b.dispatch.priority - a.dispatch.priority || a.readyAt - b.readyAt);
     for (const [key, item] of ready) {
       if (this.running.size >= this.concurrency) {
@@ -7197,6 +7383,10 @@ var Scheduler = class {
         continue;
       }
       this.pending.delete(key);
+      if (await this.alreadyRead(item)) {
+        this.log.info({ agent: item.dispatch.agent, project: item.dispatch.project }, "dropping message wake, its conversation has read the message");
+        continue;
+      }
       let { dispatch } = item;
       if (item.stageWakes !== void 0) {
         const current = await this.stillWaiting(dispatch.agent, item.stageWakes, item.holder === true);
@@ -7258,11 +7448,15 @@ var Scheduler = class {
   }
 };
 
+// packages/turn-host/dist/host.js
+import { randomUUID } from "node:crypto";
+
 // packages/turn-host/dist/render.js
 var TURN_CONTRACT = [
   "- Every turn belongs to one conversation, named at the top of your prompt: your home conversation in a project or the society, for its channels and for work tied to no thread, or the conversation of one thread you take part in, a task's, a proposal's, or a topic's. Each has its own session and its own turns, which may run while this one does. The prompt carries this conversation only: in a thread, its new messages, or the whole thread when the conversation is new, and in a task's thread the task and its stage; at home, the channel messages that concern you. Read anything else you need with get_task, search, and the board's files, and leave other threads' and other projects' work to their own turns.",
   "- Act through the board tools (the `board` MCP server). Holding a stage is a lease; every turn that touches the task renews it.",
   "- Work only inside your worktree. In a task's conversation it is a worktree of its own on the task's branch `task/<id>`: commit your work there. After each turn the runner commits what you left on the branch and lets it go for the next holder. Your home worktree is on your own branch, `agent/<name>`, for work tied to no task.",
+  "- Posts that would wake this conversation may arrive while you work, delivered into the turn under a heading that says so and formatted like the digest. They are part of this turn: act on them now, after the step in hand, or not at all, as with the digest. The user may also stop a turn; the next turn is told.",
   "- Silence is allowed. If the digest needs no reply, post nothing.",
   "- 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 its project's general channel: 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.",
@@ -7412,6 +7606,26 @@ function rosterLine(member) {
   ].filter((part) => part.length > 0);
   return `- ${member.name}: ${parts.join("; ")}. Profile: ${profileLine(member.profile)}`;
 }
+function messageLines(messages, threads) {
+  const lines = [];
+  for (const message of messages) {
+    const thread = message.thread === void 0 ? void 0 : threads?.get(message.thread);
+    const where = message.thread === void 0 ? message.channel : thread === void 0 ? `${message.channel} thread ${message.thread}` : `${message.channel} thread "${thread.title}" (${message.thread})`;
+    const step = message.step === void 0 ? "" : `, who ${stepPhrase(message.step)}`;
+    lines.push(`### [${message.ts}] ${where} from @${message.author}${step} (message ${message.id})`, "", clip(message.body), "");
+  }
+  return lines;
+}
+function buildSteerText(messages, threads) {
+  return `${[
+    `## New in this conversation while you work (${messages.length})`,
+    "",
+    "The board delivered these into your turn as they arrived, as it delivers the digest. Act on them now, after the step in hand, or not at all; the turn still ends with one status object covering everything it did.",
+    "",
+    ...messageLines(messages, threads)
+  ].join("\n").trimEnd()}
+`;
+}
 function buildTurnPrompt(input) {
   const { dispatch } = input;
   const lines = [];
@@ -7464,6 +7678,9 @@ function buildTurnPrompt(input) {
     lines.push("", "## First turn", "", renderOnboardingPreamble(input.onboarding));
   }
   const last = input.lastTurn;
+  if (last?.exitReason === "stopped") {
+    lines.push("", "## The user stopped your previous turn", "", `It was ended on purpose at ${last.endedAt ?? "its end"}, not by a failure. Do not pick its work up again unless this turn asks for it. The worktree may hold uncommitted changes; run git status before doing anything else.`);
+  }
   if (last !== null && (last.exitReason === "error" || last.exitReason === "timeout")) {
     lines.push("", "## Your previous turn did not finish", "", `It ended with ${last.exitReason}${last.error === null ? "" : `: ${last.error}`}.`, "The worktree may hold uncommitted changes. Run git status before doing anything else.");
   }
@@ -7545,12 +7762,7 @@ function buildTurnPrompt(input) {
   if (input.messages.length === 0) {
     lines.push("Nothing new.");
   } else {
-    for (const message of input.messages) {
-      const thread = message.thread === void 0 ? void 0 : input.threads?.get(message.thread);
-      const where = message.thread === void 0 ? message.channel : thread === void 0 ? `${message.channel} thread ${message.thread}` : `${message.channel} thread "${thread.title}" (${message.thread})`;
-      const step = message.step === void 0 ? "" : `, who ${stepPhrase(message.step)}`;
-      lines.push(`### [${message.ts}] ${where} from @${message.author}${step} (message ${message.id})`, "", clip(message.body), "");
-    }
+    lines.push(...messageLines(input.messages, input.threads));
   }
   lines.push("## What to do", "", "Act on the unread messages and your stages through the board tools: claim_task to hold a stage, advance_task when your part is done, plan_task to reshape what comes next, post_message to talk, and propose for what the society lacks. Silence is allowed when nothing needs a reply. End with the status object.");
   return `${lines.join("\n")}
@@ -7757,7 +7969,10 @@ var TurnHost = class {
       runner: runner.name,
       actor,
       record,
-      cursorAfter,
+      delivered: cursorAfter,
+      steers: /* @__PURE__ */ new Map(),
+      outstanding: null,
+      stopRequestedBy: null,
       held: held.map((each) => each.id),
       taskId,
       costSoFarUsd,
@@ -7779,17 +7994,130 @@ var TurnHost = class {
     }, "turn starting");
     return { job, ended };
   }
-  /** Steps of a turn in flight, as the runner received them. */
-  addEvents(turnId, entries) {
+  /**
+   * Steps of a turn in flight, as the runner received them. A steer the CLI took moves what the
+   * turn has been shown past its messages, and its step carries them and the text it delivered.
+   */
+  async addEvents(turnId, entries) {
     const turn = this.open.get(turnId);
     if (turn === void 0) {
       return;
     }
-    for (const entry of entries) {
+    for (const received of entries) {
+      let entry = received;
+      const { event } = received;
+      if (event.type === "steered") {
+        const sent = turn.steers.get(event.steer);
+        if (sent !== void 0) {
+          entry = {
+            ...received,
+            event: { ...event, messages: [...sent.messages], text: sent.text }
+          };
+          if (turn.delivered === null || sent.through > turn.delivered) {
+            turn.delivered = sent.through;
+          }
+          if (turn.outstanding === event.steer) {
+            turn.outstanding = null;
+          }
+          await this.board.recordSteered({
+            turnId,
+            agent: turn.job.agent,
+            project: turn.job.scope,
+            thread: turn.job.thread,
+            messages: sent.messages
+          }).catch((error) => {
+            this.log.warn({ turnId, error: String(error) }, "could not record a steer");
+          });
+        }
+      }
       turn.transcript.push(entry);
       this.onEvent?.(turn.job.agent, turn.job.scope, entry.event, turn.job.thread);
     }
   }
+  /** The turn in flight in a conversation, if any. */
+  turnIn(agent, scope, thread) {
+    for (const turn of this.open.values()) {
+      const { job } = turn;
+      if (job.agent === agent && job.scope === scope && job.thread === thread) {
+        return { turnId: job.turnId, runner: turn.runner, cli: job.cli };
+      }
+    }
+    return null;
+  }
+  /** The turns in flight, for the interface: their conversations and where a mention reaches them. */
+  runningTurns() {
+    return [...this.open.values()].map((turn) => ({
+      turnId: turn.job.turnId,
+      agent: turn.job.agent,
+      scope: turn.job.scope,
+      ...turn.job.thread === void 0 ? {} : { thread: turn.job.thread },
+      cli: turn.job.cli,
+      ...turn.record.trigger.channel === void 0 ? {} : { channel: turn.record.trigger.channel },
+      runner: turn.runner
+    }));
+  }
+  /**
+   * What a steer into a turn would deliver: the conversation's digest from what the turn has been
+   * shown, rendered as the prompt renders its digest. `busy` while a steer it was sent is not yet
+   * taken or refused, and `nothing` when everything new was in what it was shown.
+   */
+  async prepareSteer(turnId) {
+    const turn = this.open.get(turnId);
+    if (turn === void 0 || turn.stopRequestedBy !== null) {
+      return "gone";
+    }
+    if (turn.outstanding !== null) {
+      return "busy";
+    }
+    const { job } = turn;
+    const digest = await this.board.readDigest({
+      ...turn.actor,
+      scope: job.scope,
+      ...job.thread === void 0 ? {} : { thread: job.thread }
+    }, {
+      ...turn.delivered === null ? {} : { since_cursor: turn.delivered },
+      advance: false,
+      limit: 50
+    });
+    const last = digest.messages.at(-1);
+    if (!this.open.has(turnId) || turn.outstanding !== null) {
+      return "gone";
+    }
+    if (last === void 0) {
+      return "nothing";
+    }
+    const threads = /* @__PURE__ */ new Map();
+    for (const id of new Set(digest.messages.flatMap((message) => message.thread ?? []))) {
+      const record = await this.board.readThread(id).catch(() => void 0);
+      if (record !== void 0) {
+        threads.set(id, record);
+      }
+    }
+    const steer = { id: randomUUID(), text: buildSteerText(digest.messages, threads) };
+    turn.steers.set(steer.id, {
+      through: last.id,
+      messages: digest.messages.map((message) => message.id),
+      text: steer.text
+    });
+    turn.outstanding = steer.id;
+    return steer;
+  }
+  /** The runner's answer to a steer: one it did not take frees the turn for the next. */
+  steerAnswered(turnId, steerId, accepted) {
+    const turn = this.open.get(turnId);
+    if (turn !== void 0 && !accepted && turn.outstanding === steerId) {
+      turn.outstanding = null;
+    }
+  }
+  /** Marks a turn stopped by `by`; returns false for a turn not in flight. */
+  requestStop(turnId, by) {
+    const turn = this.open.get(turnId);
+    if (turn === void 0) {
+      return false;
+    }
+    turn.stopRequestedBy ??= by;
+    return true;
+  }
   /**
    * Records a turn's end from its outcome. Returns null for a turn the host does not know, else
    * whether the task the turn worked on has ended, so the runner may drop its worktree.
@@ -7820,10 +8148,11 @@ var TurnHost = class {
       sessionCostUsd: outcome.sessionCostUsd ?? turn.costSoFarUsd,
       toolCalls: turn.transcript.filter((entry) => entry.event.type === "tool_call").length,
       model: outcome.model ?? turn.configuredModel,
-      ...outcome.work === null ? {} : { work: outcome.work }
+      ...outcome.work === null ? {} : { work: outcome.work },
+      ...outcome.exitReason === "stopped" ? { stoppedBy: turn.stopRequestedBy ?? USER_NAME } : {}
     };
-    if (outcome.exitReason === "completed" || outcome.exitReason === "blocked") {
-      await this.board.setDigestCursor(job.agent, job.scope, turn.cursorAfter, job.thread);
+    if (outcome.exitReason === "completed" || outcome.exitReason === "blocked" || outcome.exitReason === "stopped") {
+      await this.board.setDigestCursor(job.agent, job.scope, turn.delivered, job.thread);
       await this.renewLeases(turn.actor, turn.held);
       if (outcome.status?.needsUserDecision === true) {
         await this.askUser(turn.actor, job.scope, job.thread, turn.record.startedAt, outcome.status.summary);
@@ -7999,15 +8328,19 @@ var TurnHost = class {
 };
 
 // packages/turn-host/dist/hub.js
-import { randomUUID } from "node:crypto";
+import { randomUUID as randomUUID2 } from "node:crypto";
 var RunnerProtocolError = class extends Error {
 };
+var RunnerAwayError = class extends Error {
+};
 var SILENT2 = { info() {
 }, warn() {
 }, error() {
 } };
 var DEFAULT_GRACE_MS = 2 * 6e4;
 var DEFAULT_REQUEST_TIMEOUT_MS = 10 * 6e4;
+var CONTROL_TIMEOUT_MS = 15e3;
+var FILE_TIMEOUT_MS = 6e4;
 var RunnerHub = class {
   board;
   host;
@@ -8120,7 +8453,7 @@ var RunnerHub = class {
   }
   async turnEvents(runner, turnId, entries) {
     this.assertOwns(runner, turnId);
-    this.host.addEvents(turnId, entries);
+    await this.host.addEvents(turnId, entries);
   }
   async turnOutcome(runner, turnId, outcome) {
     this.assertOwns(runner, turnId);
@@ -8151,9 +8484,76 @@ var RunnerHub = class {
   mayTouchHome(runner, agent) {
     return this.host.hasTurnFor(runner, agent);
   }
+  /** The turns in flight, and whether each one's runner can steer and stop it. */
+  liveTurns() {
+    return this.host.runningTurns().map(({ runner, ...turn }) => {
+      const seat = this.seats.get(runner);
+      const connected = seat !== void 0 && seat.send !== null;
+      return {
+        ...turn,
+        steerable: connected && seat.hello.steerableClis.includes(turn.cli),
+        stoppable: connected && seat.hello.stoppableClis.includes(turn.cli)
+      };
+    });
+  }
+  /**
+   * Stops a turn in flight, as the user asked: its runner interrupts the CLI and the turn ends
+   * `stopped`. False for a turn not in flight or on a runner that cannot stop it.
+   */
+  async stop(turnId, by) {
+    const runner = this.host.runnerOf(turnId);
+    const seat = runner === void 0 ? void 0 : this.seats.get(runner);
+    const cli = this.host.runningTurns().find((turn) => turn.turnId === turnId)?.cli;
+    if (seat === void 0 || seat.send === null || cli === void 0) {
+      return false;
+    }
+    if (!seat.hello.stoppableClis.includes(cli) || !this.host.requestStop(turnId, by)) {
+      return false;
+    }
+    try {
+      const answered = await this.request(seat, (request) => ({ type: "stop", request, turnId }), CONTROL_TIMEOUT_MS);
+      this.log.info({ turnId, runner: seat.name, by }, "turn stop requested");
+      return answered === true;
+    } catch (error) {
+      this.log.warn({ turnId, error: String(error) }, "could not stop a turn");
+      return false;
+    }
+  }
   // -------------------------------------------------------------------------------------------
   // The scheduler's runner
   // -------------------------------------------------------------------------------------------
+  /**
+   * Delivers what arrived in a conversation into its turn in flight, when that turn's runner can
+   * steer its CLI. `refused` leaves the wake to a turn of its own once this one ends.
+   */
+  async steer(conversation) {
+    const turn = this.host.turnIn(conversation.agent, conversation.project, conversation.thread);
+    const seat = turn === null ? void 0 : this.seats.get(turn.runner);
+    if (turn === null || seat === void 0 || seat.send === null) {
+      return "refused";
+    }
+    if (!seat.hello.steerableClis.includes(turn.cli)) {
+      return "refused";
+    }
+    const steer = await this.host.prepareSteer(turn.turnId);
+    if (steer === "busy" || steer === "nothing") {
+      return steer;
+    }
+    if (steer === "gone") {
+      return "refused";
+    }
+    let accepted = false;
+    try {
+      accepted = await this.request(seat, (request) => ({ type: "steer", request, turnId: turn.turnId, steer }), CONTROL_TIMEOUT_MS) === true;
+    } catch (error) {
+      this.log.warn({ turnId: turn.turnId, error: String(error) }, "could not steer a turn");
+    }
+    this.host.steerAnswered(turn.turnId, steer.id, accepted);
+    if (accepted) {
+      this.log.info({ ...conversation, turnId: turn.turnId }, "steered a turn in flight");
+    }
+    return accepted ? "sent" : "refused";
+  }
   async assign(dispatch) {
     const agent = await this.board.readAgent(dispatch.agent).catch(() => null);
     if (agent === null) {
@@ -8272,6 +8672,37 @@ var RunnerHub = class {
     });
     return "done";
   }
+  /**
+   * One path on a branch of a project's repository, read on the runner the project lives on.
+   * NOT_FOUND when the project has no runner yet or the branch or the path does not exist, and
+   * `RunnerAwayError` while its runner is away.
+   */
+  async readBranch(project, branch, path10) {
+    const record = await this.board.readProject(project);
+    if (record.runner === void 0) {
+      throw new BoardError("NOT_FOUND", `${project} has no repository yet, since no turn has run there`);
+    }
+    const seat = this.seats.get(record.runner);
+    if (seat === void 0 || seat.send === null) {
+      throw new RunnerAwayError(`runner ${record.runner}, where ${project} lives, is not connected`);
+    }
+    if (!seat.hello.branchReads) {
+      throw new BoardError("INVALID_STATE", `runner ${seat.name}, where ${project} lives, cannot read files yet; upgrade it`);
+    }
+    const file = BranchFileSchema.nullable().parse(await this.request(seat, (request) => ({
+      type: "file",
+      request,
+      read: {
+        repo: { slug: record.slug, origin: record.repo, defaultBranch: record.defaultBranch },
+        branch,
+        path: path10
+      }
+    }), FILE_TIMEOUT_MS));
+    if (file === null) {
+      throw new BoardError("NOT_FOUND", `${branch} has no ${path10 === "" ? "commit" : path10}`);
+    }
+    return file;
+  }
   /** The models a CLI offers, asked of a connected runner that has it; none when no runner has it. */
   async models(cli) {
     const seat = this.byLoad().find((each) => each.send !== null && each.hello.clis.includes(cli));
@@ -8288,7 +8719,7 @@ var RunnerHub = class {
       if (pending.runner === seat.name) {
         this.pending.delete(id);
         clearTimeout(pending.timer);
-        pending.reject(new Error(`runner ${seat.name} disconnected`));
+        pending.reject(new RunnerAwayError(`runner ${seat.name} disconnected`));
       }
     }
     await this.board.markRunner(seat.name, { status: "disconnected" }).catch((error) => {
@@ -8354,6 +8785,8 @@ var RunnerHub = class {
     return {
       name: seat.name,
       residentClis: seat.hello.residentClis,
+      steerableClis: seat.hello.steerableClis,
+      stoppableClis: seat.hello.stoppableClis,
       isWarm: (key) => seat.warm.has(key)
     };
   }
@@ -8363,19 +8796,19 @@ var RunnerHub = class {
       throw new RunnerProtocolError(`turn ${turnId} is not ${runner}'s`);
     }
   }
-  request(seat, message) {
-    const request = randomUUID();
+  request(seat, message, timeoutMs = this.requestTimeoutMs) {
+    const request = randomUUID2();
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pending.delete(request);
-        reject(new Error(`runner ${seat.name} did not answer in time`));
-      }, this.requestTimeoutMs);
+        reject(new RunnerAwayError(`runner ${seat.name} did not answer in time`));
+      }, timeoutMs);
       timer.unref?.();
       this.pending.set(request, { runner: seat.name, resolve, reject, timer });
       if (seat.send === null || !seat.send(message(request))) {
         this.pending.delete(request);
         clearTimeout(timer);
-        reject(new Error(`runner ${seat.name} is not connected`));
+        reject(new RunnerAwayError(`runner ${seat.name} is not connected`));
       }
     });
   }
@@ -8939,6 +9372,9 @@ function createApp(deps) {
     if (error instanceof RunnerProtocolError) {
       return c.json({ error: "RUNNER_PROTOCOL", message: error.message }, 409);
     }
+    if (error instanceof RunnerAwayError) {
+      return c.json({ error: "RUNNER_AWAY", message: error.message }, 503);
+    }
     return c.json({ error: "INTERNAL", message: error.message }, 500);
   });
   const authenticate = async (c, next) => {
@@ -9053,6 +9489,15 @@ function createApp(deps) {
   api.get("/projects/:slug/knowledge", async (c) => c.json(await board2.listKnowledge(c.req.param("slug"))));
   api.get("/tasks/:id", async (c) => c.json((await board2.findTask(c.req.param("id"))).task));
   api.get("/tasks/:id/thread", async (c) => c.json(await board2.listThread(c.req.param("id"))));
+  const taskFile = async (c, file) => {
+    const { task } = await board2.findTask(UlidSchema.parse(c.req.param("id")));
+    if (deps.runners === void 0) {
+      throw new BoardError("NOT_FOUND", "this board has no runners to read a task's files from");
+    }
+    return c.json(await deps.runners.readBranch(task.project, `task/${task.id}`, BranchPathSchema.parse(file)));
+  };
+  api.get("/tasks/:id/files", (c) => taskFile(c, ""));
+  api.get("/tasks/:id/files/:path{.+}", (c) => taskFile(c, c.req.param("path")));
   api.get("/threads", async (c) => c.json(await board2.listThreads()));
   api.get("/requests", async (c) => c.json(await board2.listRequests()));
   api.get("/threads/:id", async (c) => {
@@ -9087,8 +9532,21 @@ function createApp(deps) {
     running: scheduler2?.runningPairs ?? [],
     pending: scheduler2?.pendingPairs ?? [],
     resident: scheduler2?.residentPairs ?? [],
-    signals: scheduler2?.activeSignals ?? []
+    signals: scheduler2?.activeSignals ?? [],
+    turns: deps.runners?.liveTurns() ?? []
   }));
+  api.post("/turns/:turnId/stop", async (c) => {
+    const actor = c.get("actor");
+    if (actor.role !== USER_ROLE) {
+      throw new BoardError("FORBIDDEN", "only the user stops a turn");
+    }
+    const turnId = UlidSchema.parse(c.req.param("turnId"));
+    const stopped = await deps.runners?.stop(turnId, actor.name) ?? false;
+    if (!stopped) {
+      throw new BoardError("NOT_FOUND", `turn ${turnId} is not in flight, or its runner cannot stop it`);
+    }
+    return c.json({ stopped });
+  });
   api.post("/pause", async (c) => {
     await board2.setPaused(c.get("actor"), true);
     return c.json({ paused: true });