@coreplane/switchboard 1.254.1 → 1.255.0

package/dist/assets/deploy/cloudflare-memory/worker.ts

@@ -77,15 +77,21 @@ import {
   reclaimPhase,
   selectReclaim,
 } from "../../src/core/runLedger/decisions.ts";
-import { intakeReceiptRetentionMs } from "../../src/core/budgets.ts";
+import { intakeReceiptRetentionMs, minutesToMs, PLANE } from "../../src/core/budgets.ts";
 import {
   decide,
+  effectCapRefusal,
+  planeAskAnswerOf,
   planeAskWordOf,
+  RESIDENT_DRAIN_WINDOW,
+  type PlaneAskAnswer,
+  type PlaneLevelRow,
   type PlaneAckOutcome,
   type PlaneEffect,
   type PlaneEvent,
   type PlaneOutcomePost,
   type PlaneQueueRow,
+  type PlaneReservation,
   type PlaneStage,
   type PlaneState,
   type PlaneWrite,
@@ -220,6 +226,11 @@ export interface Env {
   /** The dataset's name, rendered beside the binding, so `/healthz` can answer
    *  `runMetrics:<dataset>` and the bot's boot probe can compare names. */
   RUN_METRICS_DATASET?: string;
+  /** The bot Worker, for the plane's effect push (record 0064, "Where it
+   *  lives"): committed effects are POSTed to its bearer-gated
+   *  `/plane/effects`, which forwards to the container. Optional like
+   *  SHIP_COORDINATOR — without it effects ride the heartbeat answers alone. */
+  BOT?: Fetcher;
   MEMORY_TOKEN?: string;
 }
 
@@ -1777,6 +1788,22 @@ export class RunHistoryDO extends DurableObject<Env> {
    *  dispatch it describes claimed the thread must not read its own claim as
    *  "thread live" (orchestration-plane item 8). */
   private planeState(excludeRunId?: string): PlaneState {
+    const now = systemClock();
+    // A reservation not yet promoted into a live row expires after its window:
+    // a dispatch that died between the admission answer and its claim must not
+    // hold the thread forever. Promotion deletes the row (the live row holds
+    // the thread from there), so age alone is the test.
+    const reservations = this.sql
+      .exec<{ kind: string; key: string; run_id: string; at: number }>(
+        `SELECT * FROM plane_reservations WHERE kind = 'thread' AND at > ?`,
+        now - minutesToMs(PLANE.reservationMinutes),
+      )
+      .toArray()
+      .map((r): PlaneReservation => ({ kind: "thread", key: r.key, runId: r.run_id, at: r.at }));
+    const openWindows = this.sql
+      .exec<{ kind: string }>(`SELECT kind FROM plane_windows WHERE phase = 'open'`)
+      .toArray()
+      .map((r) => r.kind);
     const queue = this.sql
       .exec<{
         run_id: string;
@@ -1805,7 +1832,19 @@ export class RunHistoryDO extends DurableObject<Env> {
       .exec<{ thread_key: string }>(`SELECT thread_key FROM live_runs WHERE run_id IS NOT ?`, excludeRunId ?? null)
       .toArray()
       .map((r) => r.thread_key);
-    return { queue, liveThreads };
+    const levels = this.sql
+      .exec<{ resident: string; name: string; side: string; reported_at: number; generation: string }>(
+        `SELECT * FROM plane_levels`,
+      )
+      .toArray()
+      .map((r): PlaneLevelRow => ({
+        resident: r.resident,
+        name: r.name as PlaneLevelRow["name"],
+        side: r.side as PlaneLevelRow["side"],
+        reportedAt: r.reported_at,
+        generation: r.generation,
+      }));
+    return { queue, liveThreads, reservations, openWindows, levels };
   }
 
   /** The decider's writes, applied inside the same `transactionSync` that read
@@ -1829,7 +1868,67 @@ export class RunHistoryDO extends DurableObject<Env> {
         );
       } else if (w.table === "plane_queue" && w.op === "state") {
         this.sql.exec(`UPDATE plane_queue SET state = ? WHERE run_id = ?`, w.state, w.runId);
+      } else if (w.table === "plane_reservations" && w.op === "put") {
+        this.sql.exec(
+          `INSERT OR REPLACE INTO plane_reservations (kind, key, run_id, at) VALUES (?, ?, ?, ?)`,
+          w.row.kind,
+          w.row.key,
+          w.row.runId,
+          w.row.at,
+        );
+      } else if (w.table === "plane_reservations" && w.op === "del") {
+        this.sql.exec(`DELETE FROM plane_reservations WHERE kind = 'thread' AND key = ?`, w.key);
+      } else if (w.table === "plane_windows" && w.op === "put") {
+        this.sql.exec(
+          `INSERT OR REPLACE INTO plane_windows (kind, key, phase, opened_at, reason_json) VALUES (?, ?, 'open', ?, '{}')`,
+          w.window,
+          w.window,
+          w.at,
+        );
+      } else if (w.table === "plane_windows" && w.op === "del") {
+        this.sql.exec(`DELETE FROM plane_windows WHERE kind = ?`, w.window);
+      } else if (w.table === "plane_levels") {
+        this.sql.exec(
+          `INSERT OR REPLACE INTO plane_levels (resident, name, side, reported_at, generation) VALUES (?, ?, ?, ?, ?)`,
+          w.row.resident,
+          w.row.name,
+          w.row.side,
+          w.row.reportedAt,
+          w.row.generation,
+        );
       } else {
+        // The effect bounds (record 0064): an offer past the per-run or total
+        // cap is refused by the cap's name — the throw aborts the transaction,
+        // so the queue row stays waiting and the next event re-decides.
+        const total = Number(
+          this.sql.exec<{ n: number }>(`SELECT COUNT(*) AS n FROM plane_effects WHERE acked_at IS NULL`).toArray()[0]
+            ?.n ?? 0,
+        );
+        const forRun =
+          w.effect.kind === "admit"
+            ? Number(
+                this.sql
+                  .exec<{
+                    n: number;
+                  }>(
+                    // Exact id matching (`admit:<runId>`): the seal runs with bot-minted
+                    // run ids, and a LIKE would read `%`/`_` in one as wildcards.
+                    `SELECT COUNT(*) AS n FROM plane_effects WHERE acked_at IS NULL AND id = 'admit:' || ?`,
+                    w.effect.runId,
+                  )
+                  .toArray()[0]?.n ?? 0,
+              )
+            : 0;
+        const refusal = effectCapRefusal({ total, forRun }, w.effect);
+        if (refusal !== undefined) throw new Error(refusal);
+        // A re-offer lands after an ack for any kind — a probe re-probes after
+        // its ack (one open probe per resident, record 0064), and an observation
+        // re-enters an admitted run whose acked `admit:<runId>` row would
+        // otherwise swallow the walk's re-offer, stranding the run `admitted`
+        // with no effect delivered. The decider only re-emits an effect when
+        // its subject is waiting again, and the bot's own getById dedup guards
+        // a genuine duplicate admit, so the acked row is history, not a fence.
+        this.sql.exec(`DELETE FROM plane_effects WHERE id = ? AND acked_at IS NOT NULL`, w.effect.id);
         // An offer keeps its first `offered_at`: a re-decided admit after a
         // roll is the same effect, not a younger one.
         this.sql.exec(
@@ -1838,6 +1937,22 @@ export class RunHistoryDO extends DurableObject<Env> {
           JSON.stringify(w.effect),
           w.at,
         );
+        // The admitted run's attaching row, in the same transaction as the
+        // effect (record 0064, "The queue"): owner `plane`, lease already
+        // expired, request in the meta — exactly the row a reserved run whose
+        // owner died leaves (run-history item 42), so the bot's reclaim sweep
+        // restarts it from the stored request under this id.
+        if (w.effect.kind === "admit") {
+          this.sql.exec(
+            `INSERT OR IGNORE INTO live_runs (run_id, thread_key, owner_gen, lease_until, started_at, phase, stop, meta_json, card_json, system_text, tools_json, state_json)
+             VALUES (?, ?, 'plane', ?, ?, 'attaching', NULL, ?, NULL, '', '[]', '{}')`,
+            w.effect.runId,
+            w.effect.threadKey,
+            w.at,
+            w.at,
+            JSON.stringify({ request: w.effect.request }),
+          );
+        }
       }
     }
   }
@@ -1851,9 +1966,200 @@ export class RunHistoryDO extends DurableObject<Env> {
       this.applyPlaneWrites(decision.writes);
       effects = decision.effects;
     });
+    this.pushPlaneEffects(effects);
     return { effects };
   }
 
+  /** The admission ask (`POST /plane/admit`, record 0064 "The queue"): one
+   *  transaction decides and writes — `admitted` reserves the thread,
+   *  `queued` stores the request under the minted id. */
+  planeAdmit(
+    post: {
+      runId: string;
+      requester: string;
+      threadKey: string;
+      request: Record<string, unknown>;
+      stage?: PlaneStage;
+      resident?: string;
+      restartOf?: boolean;
+      reaskMs?: number;
+    },
+    now: number,
+  ): PlaneAskAnswer {
+    let answer!: PlaneAskAnswer;
+    this.ctx.storage.transactionSync(() => {
+      if (post.reaskMs !== undefined)
+        this.sql.exec(`INSERT OR REPLACE INTO meta (key, value) VALUES ('plane_reask_ms', ?)`, String(post.reaskMs));
+      const decision = decide(this.planeState(), {
+        kind: "ask",
+        at: now,
+        runId: post.runId,
+        requester: post.requester,
+        threadKey: post.threadKey,
+        stage: post.stage ?? "admission",
+        request: post.request,
+        ...(post.resident !== undefined ? { resident: post.resident } : {}),
+        ...(post.restartOf !== undefined ? { restartOf: post.restartOf } : {}),
+      });
+      this.applyPlaneWrites(decision.writes);
+      answer = planeAskAnswerOf(decision, post.runId);
+    });
+    if (answer.kind === "queued") void this.ensurePlaneReaskAlarm(now);
+    console.log(
+      `[plane/admit] ${post.threadKey} → ${answer.kind}${answer.kind === "queued" ? ` position ${answer.position}` : ""} (run ${post.runId})`,
+    );
+    return answer;
+  }
+
+  /** A resident's level report (`POST /plane/level`, record 0064): `seat` and `memory`
+   *  land as level events — a `below` side walks the queue; the registry's
+   *  drain posts land as the resident-drain window's open (`above`) and lift
+   *  (`below` — a `cleared` or the alarm's `expired`). */
+  planeLevel(
+    post: { resident: string; name: "seat" | "memory" | "drain"; side: "below" | "above"; generation: string },
+    now: number,
+  ): { admitted: number } {
+    const r =
+      post.name === "drain"
+        ? this.planeApply({
+            kind: "window",
+            at: now,
+            window: RESIDENT_DRAIN_WINDOW,
+            phase: post.side === "above" ? "opened" : "lifted",
+          })
+        : this.planeApply({
+            kind: "level",
+            at: now,
+            resident: post.resident,
+            name: post.name,
+            side: post.side,
+            generation: post.generation,
+          });
+    const admitted = r.effects.filter((e) => e.kind === "admit").length;
+    console.log(`[plane/level] ${post.resident} ${post.name} ${post.side} — ${admitted} admission(s)`);
+    return { admitted };
+  }
+
+  /** A refusal-by-name the bot met at attach or exec (`POST /plane/observe`,
+   *  record 0064): an admitted run re-enters the queue at its old position. */
+  planeObserve(post: { runId: string; resident: string; refusal: string }, now: number): { reentered: boolean } {
+    let reentered = false;
+    this.ctx.storage.transactionSync(() => {
+      const decision = decide(this.planeState(), {
+        kind: "observation",
+        at: now,
+        runId: post.runId,
+        resident: post.resident,
+        refusal: post.refusal,
+      });
+      this.applyPlaneWrites(decision.writes);
+      reentered = decision.writes.length > 0;
+    });
+    if (reentered) void this.ensurePlaneReaskAlarm(now);
+    console.log(
+      `[plane/observe] run ${post.runId} on ${post.resident}: ${post.refusal.slice(0, 60)} — ${reentered ? "re-entered" : "no-op"}`,
+    );
+    return { reentered };
+  }
+
+  /** The re-ask cadence (record 0064): while a queued row waits on a resident,
+   *  the object's alarm fires within the cadence — the sweep's own 6 h alarm
+   *  is pulled forward, never pushed back. */
+  private planeReaskMs(): number {
+    const row = this.sql.exec<{ value: string }>(`SELECT value FROM meta WHERE key = 'plane_reask_ms'`).toArray()[0];
+    const stored = row ? Number(row.value) : NaN;
+    return Number.isFinite(stored) && stored > 0 ? stored : minutesToMs(PLANE.reaskMinutes);
+  }
+
+  private planeWaitsOnResident(): boolean {
+    return this.planeState().queue.some(
+      (r) => r.state === "waiting" && r.conditions.some((c) => c.kind === "seat" || c.kind === "memory"),
+    );
+  }
+
+  private async ensurePlaneReaskAlarm(now: number): Promise<void> {
+    if (!this.planeWaitsOnResident()) return;
+    const due = now + this.planeReaskMs();
+    const set = await this.ctx.storage.getAlarm();
+    if (set === null || set > due) await this.ctx.storage.setAlarm(due);
+  }
+
+  /** A window's open or lift over the RPC seam (`/plane/deploy`; a later
+   *  unit's `plane window lift`): kind `deploy` is the pending deploy. */
+  planeWindow(window: string, phase: "opened" | "lifted", now: number): { admitted: number } {
+    const r = this.planeApply({ kind: "window", at: now, window, phase });
+    return { admitted: r.effects.length };
+  }
+
+  /** `runs stop` on a queued id (record 0064): the waiting row is withdrawn;
+   *  an id the queue does not hold waiting answers false. */
+  planeWithdraw(runId: string, now: number): { withdrawn: boolean } {
+    let withdrawn = false;
+    this.ctx.storage.transactionSync(() => {
+      const decision = decide(this.planeState(), { kind: "withdraw", at: now, runId });
+      this.applyPlaneWrites(decision.writes);
+      withdrawn = decision.writes.length > 0;
+    });
+    return { withdrawn };
+  }
+
+  /** One queued row, for the queued id's page. */
+  planeQueueRowOf(runId: string): PlaneQueueRow | null {
+    return this.planeState().queue.find((r) => r.runId === runId) ?? null;
+  }
+
+  /** The seal (record 0064, "The queue"): the run's own open effects are
+   *  dropped — an admit for a run that just ended is stale — then the sealed
+   *  event frees the thread and walks the queue, all in one transaction. */
+  private planeSealed(runId: string, threadKey: string, now: number): void {
+    let effects: PlaneEffect[] = [];
+    try {
+      this.ctx.storage.transactionSync(() => {
+        // Exact id matching (`admit:<runId>`), never LIKE: a bot-minted run id
+        // can carry `%` or `_`, which a pattern would read as wildcards.
+        this.sql.exec(`DELETE FROM plane_effects WHERE acked_at IS NULL AND id = 'admit:' || ?`, runId);
+        const decision = decide(this.planeState(), { kind: "sealed", at: now, threadKey });
+        this.applyPlaneWrites(decision.writes);
+        effects = decision.effects;
+      });
+    } catch (err) {
+      // A cap refusal here must not undo the finish that already committed.
+      console.warn(`[plane/sealed] ${threadKey}: ${err instanceof Error ? err.message : String(err)}`);
+      return;
+    }
+    this.pushPlaneEffects(effects);
+  }
+
+  /** The transport's push (record 0064, "Where it lives"): committed effects
+   *  are pushed to the bot Worker over the service binding, which forwards to
+   *  the container. Fire and forget — a push that fails is not retried by a
+   *  timer; the effect rides the next heartbeat or reclaim-sweep answer. */
+  private pushPlaneEffects(effects: PlaneEffect[]): void {
+    if (effects.length === 0) return;
+    const bot = this.env.BOT;
+    if (!bot) return;
+    void bot
+      .fetch("https://bot/plane/effects", {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.env.MEMORY_TOKEN ?? ""}`,
+        },
+        body: JSON.stringify({ effects }),
+      })
+      .then((r) => {
+        if (!r.ok)
+          console.warn(
+            `[plane/push] ${effects.length} effect(s) → bot answered ${r.status} — they ride the next heartbeat`,
+          );
+      })
+      .catch((err: unknown) => {
+        console.warn(
+          `[plane/push] ${effects.length} effect(s) not delivered: ${err instanceof Error ? err.message : String(err)} — they ride the next heartbeat`,
+        );
+      });
+  }
+
   /** The unacknowledged effects, oldest first, at most `PLANE_EFFECTS_PER_ANSWER`
    *  (orchestration-plane item 7) — what every heartbeat and reclaim answer carries. Public: the
    *  reclaim route composes it beside the runs it took. */
@@ -1970,6 +2276,29 @@ export class RunHistoryDO extends DurableObject<Env> {
     return row ? (JSON.parse(row.json) as CoordinatorInstance) : null;
   }
 
+  /** The hard stop's mark on the instance row (record 0060; issue 1924).
+   *  Idempotent: a marked row keeps its first mark. */
+  async markInstanceStopped(id: string, at: number): Promise<{ ok: true } | { ok: false; reason: "unknown_instance" }> {
+    let out: { ok: true } | { ok: false; reason: "unknown_instance" } = { ok: true };
+    this.ctx.storage.transactionSync(() => {
+      const row = this.sql
+        .exec<{ json: string }>(`SELECT json FROM coordinator_instances WHERE instance_id = ?`, id)
+        .toArray()[0];
+      if (!row) {
+        out = { ok: false, reason: "unknown_instance" };
+        return;
+      }
+      const instance = JSON.parse(row.json) as CoordinatorInstance;
+      if (instance.stop !== undefined) return;
+      this.sql.exec(
+        `UPDATE coordinator_instances SET json = ? WHERE instance_id = ?`,
+        JSON.stringify({ ...instance, stop: { at } }),
+        id,
+      );
+    });
+    return out;
+  }
+
   // ---- the units of the plan an instance runs (run-history item 50) -----------
 
   /** Each row replaced whole under its (instance, unit); a replace keeps the row's place. */
@@ -2152,6 +2481,10 @@ export class RunHistoryDO extends DurableObject<Env> {
         req,
       );
       if (!out.ok) return;
+      // The claim promotes the thread's reservation (record 0064, "The queue"):
+      // the live row holds the thread from here, so the reservation row retires
+      // in the same transaction that writes the claim.
+      this.sql.exec(`DELETE FROM plane_reservations WHERE kind = 'thread' AND key = ?`, req.threadKey);
       switch (decideClaimWrite(existing, req)) {
         case "keep":
           return;
@@ -2359,6 +2692,9 @@ export class RunHistoryDO extends DurableObject<Env> {
       out = { ok: true, stored: put.stored };
     });
     if (!out.ok) return out;
+    // The seal flips `thread_free` (record 0064, "The queue"): the plane frees
+    // the thread, drops the sealed run's own open effects and walks the queue.
+    this.planeSealed(runId, record.threadKey, systemClock());
     // The point after the commit, never inside it (`sendRunFinished`'s placement):
     // the finish usually replaces the start tombstone, so this is where most
     // runs are counted (run-metrics.md item 2).
@@ -2376,11 +2712,16 @@ export class RunHistoryDO extends DurableObject<Env> {
    *  started. Fenced. */
   async abandon(runId: string, gen: string): Promise<FenceResult> {
     let out: FenceResult = { ok: true };
+    let threadKey: string | undefined;
     this.ctx.storage.transactionSync(() => {
-      out = checkFence(this.liveRow(runId), gen);
+      const row = this.liveRow(runId);
+      out = checkFence(row, gen);
       if (!out.ok) return;
+      threadKey = row?.threadKey;
       this.deleteLiveRows([runId]);
     });
+    // An abandoned reservation seals like a finish does: the thread frees and the queue walks.
+    if (out.ok && threadKey !== undefined) this.planeSealed(runId, threadKey, systemClock());
     return out;
   }
 
@@ -2848,7 +3189,18 @@ export class RunHistoryDO extends DurableObject<Env> {
       console.log(
         `[runs/alarm] swept ${deleted} rows outside policy, pruned ${receipts} intake receipt(s), dropped ${dropped} session log(s)`,
       );
+      // The plane's re-ask (record 0064): while a queued row waits on a resident
+      // that has said nothing within the cadence, one probe effect per
+      // resident — and the next alarm is pulled forward to the cadence, so a
+      // silent resident is probed, never waited on forever. The sweep rides
+      // the same alarm; a probing cadence re-runs it, which is only indexed
+      // deletes and only while something waits.
+      if (this.planeWaitsOnResident()) {
+        const probes = this.planeApply({ kind: "reask", at: now, cadenceMs: this.planeReaskMs() }).effects;
+        if (probes.length > 0) console.log(`[plane/reask] ${probes.map((e) => e.id).join(", ")}`);
+      }
       await this.ctx.storage.setAlarm(now + RUN_SWEEP_INTERVAL_MS);
+      await this.ensurePlaneReaskAlarm(now);
       root.end("ok", { swept: deleted });
     } catch (err) {
       root.fail(err);
@@ -3782,6 +4134,17 @@ export class SessionLogDO extends DurableObject<Env> {
       );
       CREATE TABLE IF NOT EXISTS notepad (k INTEGER PRIMARY KEY CHECK (k = 1), text TEXT NOT NULL, updated_at INTEGER NOT NULL);
     `);
+    // The keyed append's identity (session-log item 13): a row group's id, on
+    // its first part; a partial unique index holds the idempotency line. Added
+    // by ALTER so a log written before the column keeps its rows.
+    const columns = new Set(
+      this.sql
+        .exec<{ name: string }>(`SELECT name FROM pragma_table_info('turns')`)
+        .toArray()
+        .map((r) => r.name),
+    );
+    if (!columns.has("row_id")) this.sql.exec(`ALTER TABLE turns ADD COLUMN row_id TEXT`);
+    this.sql.exec(`CREATE UNIQUE INDEX IF NOT EXISTS turns_row_id ON turns(row_id) WHERE row_id IS NOT NULL`);
   }
 
   /** The index the next row lands at: one past the newest turn, 0 for an empty
@@ -3877,6 +4240,31 @@ export class SessionLogDO extends DurableObject<Env> {
     this.sql.exec(`INSERT INTO turns_fts (rowid, text) VALUES (?, ?)`, id, text);
   }
 
+  /** The idempotent keyed append (session-log item 13): the parts of ONE turn
+   *  land at the tail under `rowId` — a fold of a `ship_unit` event, a
+   *  connector's turn, a migrated row. A row id the log has seen appends
+   *  nothing, so a fold read twice yields one row; two appends keep their
+   *  arrival order, since each lands at the tail inside one transaction. No
+   *  owner fence: a thread session has no one owning run. */
+  async appendKeyed(
+    rowId: string,
+    rows: Array<{ part: number; json: string }>,
+  ): Promise<{ ok: true; appended: boolean }> {
+    let appended = false;
+    this.ctx.storage.transactionSync(() => {
+      const seen = this.sql.exec(`SELECT 1 FROM turns WHERE row_id = ? LIMIT 1`, rowId).toArray().length > 0;
+      if (seen) return;
+      const idx = this.next();
+      for (const [i, r] of rows.entries()) {
+        this.putRow({ idx, part: r.part, json: r.json }, r.json, false);
+        if (i === 0) this.sql.exec(`UPDATE turns SET row_id = ? WHERE idx = ? AND part = ?`, rowId, idx, r.part);
+      }
+      appended = true;
+      this.enforceBytePolicy();
+    });
+    return { ok: true, appended };
+  }
+
   async write(
     gen: string,
     rows: TranscriptRow[],
@@ -3963,7 +4351,10 @@ export class SessionLogDO extends DurableObject<Env> {
       if (ids.length === 0) break;
       for (const id of ids) {
         const row = this.sql
-          .exec<SessionTurnRow>(`SELECT id, idx, part, json, text FROM turns WHERE id = ?`, id)
+          .exec<SessionTurnRow & { row_id: string | null }>(
+            `SELECT id, idx, part, json, text, row_id FROM turns WHERE id = ?`,
+            id,
+          )
           .toArray()[0];
         if (!row) continue;
         const marker = droppedToolResultRow(row.json);
@@ -3974,6 +4365,11 @@ export class SessionLogDO extends DurableObject<Env> {
         }
         const refs = attachmentRefsOf(row.json);
         this.putRow({ idx: row.idx, part: row.part, json: marker }, marker, true);
+        // The marker keeps the row's keyed-append id (item 13): `putRow` deletes
+        // the old row, so without this the partial unique index forgets the id
+        // and a replayed migration or fold would re-append the trimmed turn.
+        if (row.row_id !== null)
+          this.sql.exec(`UPDATE turns SET row_id = ? WHERE idx = ? AND part = ?`, row.row_id, row.idx, row.part);
         // The marker references nothing, so an attachment only this row showed is now orphaned.
         for (const ref of refs) {
           if (!this.referencedElsewhere(ref, -1)) this.sql.exec(`DELETE FROM attachments WHERE ref = ?`, ref);
@@ -4135,6 +4531,7 @@ const LEDGER_ROUTES = new Set([
   "/runs/coordinator/put",
   "/runs/coordinator/replace",
   "/runs/coordinator/get",
+  "/runs/coordinator/stop",
   "/runs/coordinator/units/put",
   "/runs/coordinator/units/list",
   "/runs/coordinator/events/append",
@@ -4165,6 +4562,7 @@ const LEDGER_ROUTES = new Set([
   "/runs/session/tail",
   "/runs/session/owner",
   "/runs/session/write",
+  "/runs/session/append",
   "/runs/session/read",
   "/runs/session/read-tail",
   "/runs/session/clear-owner",
@@ -4176,7 +4574,19 @@ const LEDGER_ROUTES = new Set([
 /** The plane's routes (record 0064; orchestration-plane items 7 and 8): the shadow outcome post and the
  *  effect acknowledgement. Both land on the ledger object of the given store
  *  key, like every `/runs/*` route. */
-const PLANE_ROUTES = new Set(["/plane/outcome", "/plane/ack"]);
+const PLANE_ROUTES = new Set([
+  "/plane/outcome",
+  "/plane/ack",
+  "/plane/admit",
+  "/plane/withdraw",
+  "/plane/deploy",
+  "/plane/queued",
+  "/plane/level",
+  "/plane/observe",
+]);
+
+const PLANE_LEVEL_NAMES = new Set(["seat", "memory", "drain"]);
+const PLANE_LEVEL_SIDES = new Set(["below", "above"]);
 
 const PLANE_STAGES = new Set(["admission", "runner", "resident"]);
 const PLANE_OUTCOME = /^(proceeded|refused:[a-z0-9-]+|fell_cold:[a-z0-9_-]+)$/;
@@ -4224,6 +4634,103 @@ async function handlePlane(pathname: string, body: unknown, env: Env): Promise<R
       return json({ error: "outcome must be done, skipped or deferred" }, 400);
     return json(await stub.planeAck(b.id, b.outcome as PlaneAckOutcome, now));
   }
+  if (pathname === "/plane/admit") {
+    // The admission-stage ask (record 0064, "The queue"): the thread key, the
+    // requester and the request in the durable inbox's shape. The route mints
+    // the run id: `queued` stores the request under it, `admitted` names it as
+    // the reservation.
+    if (typeof b.threadKey !== "string" || b.threadKey.length === 0)
+      return json({ error: "threadKey must be a non-empty string" }, 400);
+    if (typeof b.requester !== "string" || b.requester.length === 0)
+      return json({ error: "requester must be a non-empty string" }, 400);
+    if (typeof b.request !== "object" || b.request === null || Array.isArray(b.request))
+      return json({ error: "request must be a JSON object" }, 400);
+    if (b.stage !== undefined && (typeof b.stage !== "string" || !PLANE_STAGES.has(b.stage)))
+      return json({ error: "stage must be admission, runner or resident" }, 400);
+    if (b.resident !== undefined && (typeof b.resident !== "string" || b.resident.length === 0))
+      return json({ error: "resident must be a non-empty string" }, 400);
+    if (b.restartOf !== undefined && typeof b.restartOf !== "boolean")
+      return json({ error: "restartOf must be a boolean" }, 400);
+    if (b.reaskMs !== undefined && (typeof b.reaskMs !== "number" || !(b.reaskMs > 0)))
+      return json({ error: "reaskMs must be a positive number of milliseconds" }, 400);
+    try {
+      const answer = await stub.planeAdmit(
+        {
+          runId: crypto.randomUUID(),
+          requester: b.requester,
+          threadKey: b.threadKey,
+          request: b.request as Record<string, unknown>,
+          ...(b.stage !== undefined ? { stage: b.stage as PlaneStage } : {}),
+          ...(b.resident !== undefined ? { resident: b.resident } : {}),
+          ...(b.restartOf !== undefined ? { restartOf: b.restartOf } : {}),
+          ...(b.reaskMs !== undefined ? { reaskMs: b.reaskMs } : {}),
+        },
+        now,
+      );
+      return json(answer);
+    } catch (err) {
+      // The effect caps refuse by name (record 0064): the ask is answered with
+      // the cap's own sentence, never queued silently.
+      return json({ error: err instanceof Error ? err.message : String(err) }, 409);
+    }
+  }
+  if (pathname === "/plane/level") {
+    // A resident's level report (record 0064): forwarded by the bot from the levels a
+    // resident answer carried, or from the registry's drain outbox.
+    if (typeof b.resident !== "string" || b.resident.length === 0)
+      return json({ error: "resident must be a non-empty string" }, 400);
+    if (typeof b.name !== "string" || !PLANE_LEVEL_NAMES.has(b.name))
+      return json({ error: "name must be seat, memory or drain" }, 400);
+    if (typeof b.side !== "string" || !PLANE_LEVEL_SIDES.has(b.side))
+      return json({ error: "side must be below or above" }, 400);
+    if (typeof b.generation !== "string") return json({ error: "generation must be a string" }, 400);
+    return json(
+      await stub.planeLevel(
+        {
+          resident: b.resident,
+          name: b.name as "seat" | "memory" | "drain",
+          side: b.side as "below" | "above",
+          generation: b.generation,
+        },
+        now,
+      ),
+    );
+  }
+  if (pathname === "/plane/observe") {
+    // A refusal-by-name met at attach or exec (record 0064).
+    const parsed = parseRunId(b.runId);
+    if (!parsed.ok) return json({ error: parsed.error }, 400);
+    if (typeof b.resident !== "string" || b.resident.length === 0)
+      return json({ error: "resident must be a non-empty string" }, 400);
+    if (typeof b.refusal !== "string" || b.refusal.length === 0)
+      return json({ error: "refusal must be a non-empty string" }, 400);
+    return json(await stub.planeObserve({ runId: parsed.value, resident: b.resident, refusal: b.refusal }, now));
+  }
+  if (pathname === "/plane/withdraw") {
+    const parsed = parseRunId(b.runId);
+    if (!parsed.ok) return json({ error: parsed.error }, 400);
+    return json(await stub.planeWithdraw(parsed.value, now));
+  }
+  if (pathname === "/plane/queued") {
+    const parsed = parseRunId(b.runId);
+    if (!parsed.ok) return json({ error: parsed.error }, 400);
+    return json({ row: await stub.planeQueueRowOf(parsed.value) });
+  }
+  if (pathname === "/plane/deploy") {
+    // The deploy runner's post (record 0064, "The queue"): `landed` lifts the
+    // pending-deploy window — `deploy_settled` flips and the queue walks;
+    // `pending` opens it. Version and workers ride the log line only.
+    if (b.phase !== "landed" && b.phase !== "pending") return json({ error: "phase must be landed or pending" }, 400);
+    try {
+      const r = await stub.planeWindow("deploy", b.phase === "landed" ? "lifted" : "opened", now);
+      console.log(
+        `[plane/deploy] ${b.phase}${typeof b.version === "string" ? ` ${b.version}` : ""} — ${r.admitted} admission(s)`,
+      );
+      return json({ ok: true, admitted: r.admitted });
+    } catch (err) {
+      return json({ error: err instanceof Error ? err.message : String(err) }, 409);
+    }
+  }
   return json({ error: "not found" }, 404);
 }
 
@@ -4234,6 +4741,7 @@ const WIDE_BODY_ROUTES = new Set([
   "/runs/append",
   "/runs/transcript/write",
   "/runs/session/write",
+  "/runs/session/append",
 ]);
 /** A delivery snapshot written whole, or a refresh's patch: every merged pull request's reviews and
  *  its branch's workflow runs — about 7 KB a pull request (measured: 291 pull requests, 2.1 MB), so
@@ -4357,6 +4865,24 @@ function parseTranscriptRows(v: unknown): Validated<TranscriptRow[]> {
   return { ok: true, value: v as TranscriptRow[] };
 }
 
+/** The keyed append's rows (session-log item 13): the parts of one turn, no index — the object assigns the tail's. */
+function parseKeyedRows(v: unknown): Validated<Array<{ part: number; json: string }>> {
+  if (!Array.isArray(v) || v.length === 0) return invalid("rows must be a non-empty array");
+  for (const r of v) {
+    const row = r as Record<string, unknown>;
+    if (typeof row?.part !== "number" || !Number.isInteger(row.part) || row.part < 0 || typeof row?.json !== "string")
+      return invalid("rows entries must be {part, json}");
+  }
+  return { ok: true, value: v as Array<{ part: number; json: string }> };
+}
+
+/** The keyed append's row id (session-log item 13): non-empty, bounded — an event id, a message id with its edit stamp, a migrated row's name. */
+function parseRowId(v: unknown): Validated<string> {
+  if (typeof v !== "string" || v.length === 0 || v.length > 512)
+    return invalid("rowId must be a string of 1..512 characters");
+  return { ok: true, value: v };
+}
+
 function parseSessionKey(v: unknown): Validated<string> {
   if (typeof v !== "string" || !SESSION_KEY_PATTERN.test(v)) return invalid("key must be a session key");
   return { ok: true, value: v };
@@ -4422,6 +4948,17 @@ async function handleLedger(pathname: string, body: unknown, env: Env): Promise<
       );
       return fenced(r);
     }
+    if (pathname === "/runs/session/append") {
+      const rowId = parseRowId(b.rowId);
+      if (!rowId.ok) return json({ error: rowId.error }, 400);
+      const rows = parseKeyedRows(b.rows);
+      if (!rows.ok) return json({ error: rows.error }, 400);
+      const r = await stub.appendKeyed(rowId.value, rows.value);
+      console.log(
+        `[runs/session/append] ${key.value} <- ${rows.value.length} row(s) under ${rowId.value}, appended=${r.appended}`,
+      );
+      return json(r);
+    }
     if (pathname === "/runs/session/read") {
       const from = parseLogIndex(b.from, "from");
       if (!from.ok) return json({ error: from.error }, 400);
@@ -4571,6 +5108,16 @@ async function handleLedger(pathname: string, body: unknown, env: Env): Promise<
       return json({ error: "id must be a Workflow instance id" }, 400);
     return json({ instance: await stub.getInstance(b.id) });
   }
+  // The hard stop's mark on the instance row (record 0060; issue 1924): the
+  // bot writes it when the hosted parent is sealed; the runner reads it back.
+  if (pathname === "/runs/coordinator/stop") {
+    if (typeof b.instanceId !== "string" || !INSTANCE_ID_PATTERN.test(b.instanceId))
+      return json({ error: "instanceId must be a Workflow instance id" }, 400);
+    if (typeof b.at !== "number" || !Number.isFinite(b.at)) return json({ error: "at must be a time" }, 400);
+    const r = await stub.markInstanceStopped(b.instanceId, b.at);
+    console.log(`[runs/coordinator/stop] ${key.value} ${b.instanceId} → ${r.ok ? "marked" : r.reason}`);
+    return r.ok ? json(r) : json(r, 409);
+  }
   // The units of the plan an instance runs (run-history item 50): rows
   // validated by the shared contract, each replaced whole; a list by instance.
   if (pathname === "/runs/coordinator/units/put") {