@dev.fast/whiteboard 0.2.5-preview.20261013.113 → 0.2.5-preview.20261015.115

package/src/remote-uninstall.ts

@@ -0,0 +1,280 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { lstat, mkdir, readFile, readdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import {
+  REVIEW_REMOTE_INSTALL_LOCK,
+  REVIEW_REMOTE_LOCK_STALE_SECONDS,
+  REVIEW_REMOTE_WRAPPER_MARK,
+} from "@dev.fast/review-protocol";
+
+import { whiteboardRemoteHome } from "./remote-extensions";
+import {
+  remoteLanguageServerGroups,
+  stopProcessGroup,
+} from "./remote-language-server";
+import { DEV_REVIEW_HOME_ENV } from "./review-home-paths";
+import {
+  recordedBackgroundServer,
+  stopBackgroundServer,
+} from "./server/background-server";
+
+const LOCK_STALE_MS = REVIEW_REMOTE_LOCK_STALE_SECONDS * 1000;
+
+const REVIEW_STORE = [
+  "review-api.db",
+  "review-api.db-wal",
+  "review-api.db-shm",
+  "review-api.db.workspaces",
+  "review-api.db.workspaces-wal",
+  "review-api.db.workspaces-shm",
+];
+
+export type RemoteUninstallResult =
+  | {
+      event: "remote.uninstall";
+      ok: true;
+      removed: string[];
+      keptReviews: boolean;
+      stoppedServer?: { pid: number; version: string | null };
+    }
+  | { event: "remote.uninstall"; ok: false; reason: string };
+
+export async function remoteUninstall(input: {
+  home: string;
+  env: NodeJS.ProcessEnv;
+  stateDir: string;
+  deleteReviews: boolean;
+}): Promise<RemoteUninstallResult> {
+  const refuse = (reason: string): RemoteUninstallResult => ({
+    event: "remote.uninstall",
+    ok: false,
+    reason,
+  });
+
+  // A relative home would aim every removal at the working directory.
+  if (!path.isAbsolute(input.home))
+    return refuse(
+      `HOME is ${input.home ? JSON.stringify(input.home) : "not set"}; Whiteboard removes nothing without an absolute home.`,
+    );
+
+  if (!path.isAbsolute(input.stateDir))
+    return refuse(
+      `The review home ${JSON.stringify(input.stateDir)} is not an absolute path.`,
+    );
+
+  const override = input.env[DEV_REVIEW_HOME_ENV]?.trim();
+
+  if (
+    override &&
+    (/[\x00-\x1f\x7f-\x9f]/.test(override) ||
+      override.includes("//") ||
+      path.resolve(override) !== (override.replace(/\/$/, "") || "/"))
+  )
+    return refuse(
+      `DEV_REVIEW_HOME is ${JSON.stringify(override)}; Whiteboard removes nothing under a review home that is not an absolute, normalised path.`,
+    );
+
+  const install = whiteboardRemoteHome(input.env);
+  const wrapper = path.join(input.home, ".local", "bin", "whiteboard");
+  const lock = path.join(install, REVIEW_REMOTE_INSTALL_LOCK);
+
+  const busy = async () =>
+    refuse(
+      `Desktop on ${(await readText(path.join(lock, "owner"))) || "another computer"} is installing Whiteboard here. Try again when it is done.`,
+    );
+
+  if (existsSync(lock)) {
+    if (!(await stale(lock))) return busy();
+    await rm(lock, { recursive: true, force: true });
+  }
+
+  const held = existsSync(install);
+
+  if (
+    held &&
+    !(await mkdir(lock).then(
+      () => true,
+      () => false,
+    ))
+  )
+    return busy();
+
+  try {
+    return await removeInstall(input, install, wrapper, refuse);
+  } finally {
+    if (held) await rm(lock, { recursive: true, force: true });
+  }
+}
+
+async function removeInstall(
+  input: Parameters<typeof remoteUninstall>[0],
+  install: string,
+  wrapper: string,
+  refuse: (reason: string) => RemoteUninstallResult,
+): Promise<RemoteUninstallResult> {
+  const server = await recordedBackgroundServer(input.stateDir);
+
+  const recorded = server && {
+    ...server.discovery,
+    version: server.health.version ?? null,
+  };
+
+  const stoppable =
+    recorded && recorded.startedBy !== "user" ? recorded.serverPid : undefined;
+
+  const groups = await remoteLanguageServerGroups(input.env);
+  const running = await processesFrom(`${install}/`);
+
+  if (running === undefined)
+    return refuse(
+      `Cannot list this host's processes to check that none runs from ${install}.`,
+    );
+
+  const others = running
+    .filter(({ pid, pgid }) => pid !== stoppable && !groups.includes(pgid))
+    .map(({ pid }) => pid);
+
+  if (others.length)
+    return refuse(
+      `${others.map((pid) => (pid === recorded?.serverPid ? `A Whiteboard server you started (process ${pid})` : `Process ${pid}`)).join(", ")} ${others.length > 1 ? "run" : "runs"} from ${install}. Stop ${others.length > 1 ? "them" : "it"}, then run whiteboard remote uninstall again.`,
+    );
+
+  if (recorded?.startedBy === "user" && input.deleteReviews)
+    return refuse(
+      `A Whiteboard server you started (process ${recorded.serverPid}) uses the reviews in ${input.stateDir}. Stop it, then run whiteboard remote uninstall again.`,
+    );
+
+  await Promise.all(groups.map(stopProcessGroup));
+  let stoppedServer: { pid: number; version: string | null } | undefined;
+
+  if (recorded && stoppable !== undefined) {
+    try {
+      await stopBackgroundServer({ serverPid: stoppable });
+    } catch (error) {
+      return refuse(error instanceof Error ? error.message : String(error));
+    }
+
+    stoppedServer = { pid: stoppable, version: recorded.version };
+  }
+
+  const left = await processesFrom(`${install}/`);
+
+  if (left?.length !== 0)
+    return refuse(
+      `${left ? `Process ${left.map(({ pid }) => pid).join(", ")}` : "A process"} still runs from ${install}. Stop it, then run whiteboard remote uninstall again.`,
+    );
+
+  const removed: string[] = [];
+
+  if (existsSync(install)) {
+    await rm(install, { recursive: true, force: true });
+    removed.push(install);
+  }
+
+  if (await desktopWrote(wrapper)) {
+    await rm(wrapper, { force: true });
+    removed.push(wrapper);
+  }
+
+  if (input.deleteReviews)
+    for (const name of REVIEW_STORE) {
+      const file = path.join(input.stateDir, name);
+
+      if (existsSync(file)) {
+        await rm(file, { force: true });
+        removed.push(file);
+      }
+    }
+
+  const result: RemoteUninstallResult = {
+    event: "remote.uninstall",
+    ok: true,
+    removed,
+    keptReviews: !input.deleteReviews,
+  };
+
+  if (stoppedServer) result.stoppedServer = stoppedServer;
+
+  return result;
+}
+
+async function stale(lock: string) {
+  const started = await readText(path.join(lock, "started"));
+
+  if (started !== "")
+    return (
+      /^\d+$/.test(started) &&
+      Date.now() - Number(started) * 1000 >= LOCK_STALE_MS
+    );
+
+  if (existsSync(path.join(lock, "started"))) return false;
+
+  const since = (await stat(lock).catch(() => undefined))?.mtimeMs;
+
+  return since !== undefined && Date.now() - since >= LOCK_STALE_MS;
+}
+
+const readText = (file: string) =>
+  readFile(file, "utf8").then(
+    (text) => text.trim(),
+    () => "",
+  );
+
+async function processesFrom(prefix: string) {
+  let lines: { pid: number; pgid: number; args: string }[];
+
+  try {
+    const pids = (await readdir("/proc")).filter((name) => /^\d+$/.test(name));
+
+    lines = await Promise.all(
+      pids.map(async (pid) => {
+        const [args = "", stat = ""] = await Promise.all(
+          [`/proc/${pid}/cmdline`, `/proc/${pid}/stat`].map((file) =>
+            readFile(file, "utf8").catch(() => ""),
+          ),
+        );
+
+        // The group follows the state and the parent, after the command's parentheses.
+        const pgid = Number(
+          stat.slice(stat.lastIndexOf(")") + 2).split(" ")[2],
+        );
+
+        return { pid: Number(pid), pgid, args: args.replaceAll("\0", " ") };
+      }),
+    );
+  } catch {
+    try {
+      const { stdout } = await promisify(execFile)(
+        "ps",
+        ["-eo", "pid=,pgid=,args="],
+        { maxBuffer: 16 << 20 },
+      );
+
+      lines = stdout.split("\n").map((line) => {
+        const [, pid = "", pgid = "", args = ""] =
+          /^\s*(\d+)\s+(\d+)\s(.*)$/.exec(line) ?? [];
+
+        return { pid: Number(pid), pgid: Number(pgid), args };
+      });
+    } catch {
+      return undefined;
+    }
+  }
+
+  return lines.filter(
+    ({ pid, args }) => pid && pid !== process.pid && args.includes(prefix),
+  );
+}
+
+async function desktopWrote(file: string) {
+  const entry = await lstat(file).catch(() => undefined);
+
+  if (!entry?.isFile()) return false;
+
+  return (await readFile(file, "utf8"))
+    .split("\n")
+    .includes(REVIEW_REMOTE_WRAPPER_MARK);
+}

package/src/review-api/README.md

@@ -46,8 +46,7 @@ All paths below are relative to `/reviews-api`.
 | `GET /capabilities`                                           | Desktop availability and permission for optional software-map generation, independent of opening a review                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `GET /:id/activity`                                           | Currently reported authoring work, not stored in document history                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `POST /:id/activity/{begin,update,end} {activityId?,focus?}`  | Begin a presence (returns its `activityId`), update its focus and expiry, or end it; each returns the review's live presences                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `GET /watch`                                                  | NDJSON review summaries: initial list, then saved changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `GET /watch?subscriptions=…`                                  | One NDJSON connection for multiple `{reviewId}` subscriptions; `reviewId:null` selects the catalog. Each line is an ordered array of `{value}` or `{error}` results, with `null` where a subscription is unchanged since the previous line.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `GET /watch?subscriptions=[{reviewId,mode?}]`                 | NDJSON live updates. `reviewId:null` subscribes to the review list in `mode` (`structural` when absent); a string subscribes to that review. Each line names what it is about: `{kind:"list",mode,reviews}`, `{kind:"review",reviewId,value}` (the snapshot plus `activity` and `coverageRevision`), or `{kind:"review",reviewId,error}`. On connect there is one line per list mode and per review, however often each is subscribed; afterwards a line only for what changed (an edit changes the list entry's `version`, so it sends both; activity and coverage send only the review; an unchanged list is not resent). A missing or deleted review is an `error` line and the stream stays open; a reader that falls behind receives each item's latest state once.                                                                                                                                                                                                                          |
 | `GET /:id`                                                    | Compact outline                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `GET /:id?targetId=step-3`                                    | Full block, sequence step, flow node or flow edge                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `GET /:id?full=true`                                          | Full snapshot                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -55,7 +54,6 @@ All paths below are relative to `/reviews-api`.
 | `GET /:id/history`                                            | Saved versions with titles and timestamps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `GET /:id/inspect`                                            | Agent reading view: nested text outline with IDs; `targetId` reads one component completely, `full=true` includes all content, `version` selects history. `format=json` returns raw data instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `POST /:id/open`                                              | Open the review in the attached Desktop; report an error when none is attached                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `GET /:id/watch`                                              | NDJSON snapshots: current state immediately, then committed updates                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `POST /commands`                                              | Apply one command; return review ID, version, and for an edit the target ID, its `type`, and — after an insert or replace — `children`: its first-level children as `{id,type}` (a container's blocks; a diagram's steps, or nodes then edges), so new components are addressable without a read. A `create` with `pullRequestUrl` returns the newest existing review for that PR instead (owner/repository matched case-insensitively) unless `operation.reuseExisting` is `false`: `created:false`, a `note`, its stored `target`, `headMoved`, and `working`/`otherReviewIds` when they apply; its target is never moved. A new review reports `created:true`. Either way the result carries `review`, the review's `GET /` catalog entry (target, origin, repository name and path). An interactive `create` also opens the new review in an attached Desktop unless `operation.open` is `false`, and reports `opened` with the open result or an `openError`; the review is saved either way |
 | `POST /commands {operation:{type:"lens_edit",reviewId,edit}}` | Write one file lens, credited to `activityId` when given: `insert {title,targets,afterId?}` (host id `lens-N`), `update {targetId,title?,targets?}` or `remove {targetId}`. Returns `{targetId, type:"lens", uncategorized}`, where `uncategorized` lists changed files and ranges no lens covers yet (at most 50 files)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `GET /:id/lenses`                                             | The current version's file lenses with each one's file count, plus the same `uncategorized` report                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

package/src/review-api/agent-cli.ts

@@ -63,10 +63,10 @@ export async function runReviewAgentCli(input: AgentCliInput): Promise<number> {
     if (extra.length || (mode === "mcp" && name))
       throw new Error("Unexpected arguments. Use whiteboard api --help.");
 
-    const headers = {
-      [REVIEW_VIA_HEADER]: mode === "mcp" ? "mcp" : "api",
-      [REVIEW_AGENT_HEADER]: reviewSessionAgent(env),
-    };
+    const headers = Object.fromEntries([
+      [REVIEW_VIA_HEADER, mode === "mcp" ? "mcp" : "api"],
+      [REVIEW_AGENT_HEADER, reviewSessionAgent(env)],
+    ]);
 
     if (mode === "mcp") {
       const { serveReviewMcp } = await import("./mcp.js");

package/src/review-api/agent-client.ts

@@ -43,9 +43,15 @@ export async function connectReviewApi(
   return (await connectReviewInstance(env, headers)).client;
 }
 
+export interface ConnectReviewOptions {
+  desktopInstalled?: () => boolean;
+  cli?: readonly string[];
+}
+
 export async function connectReviewInstance(
   env = process.env,
   headers: Record<string, string> = {},
+  options: ConnectReviewOptions = {},
 ): Promise<ConnectedReview> {
   const request: ConstructorParameters<typeof ReviewApiClient>[1] = (
     url,
@@ -77,6 +83,23 @@ export async function connectReviewInstance(
   const discovery = healthyReviewInstance(selection);
 
   if (!discovery) {
+    const { ensureServerWithoutDesktop } =
+      await import("@review/server/background-server.js");
+
+    const server = await ensureServerWithoutDesktop({
+      selection,
+      env,
+      ...options,
+    });
+
+    if (server)
+      return {
+        client: new ReviewApiClient(
+          { serverUrl: server.url, token: server.token },
+          request,
+        ),
+      };
+
     const unavailable = reviewInstanceUnavailable(selection);
     const message = `${unavailable.message} For headless authoring, select a running server with --state-dir or DEV_REVIEW_SERVER_DIR.`;
 

package/src/review-api/ask-history.ts

@@ -5,9 +5,11 @@ import {
   type AskEntry,
   type AskHistoryEntry,
   type AskOffer,
+  type AskPermissions,
   askEntrySchema,
   askHistoryEntrySchema,
   askOfferSchema,
+  askPermissionsSchema,
 } from "@review/ask/thread-state.js";
 import { z } from "zod";
 
@@ -23,8 +25,8 @@ export const askRecordSchema = askHistoryEntrySchema.extend({
   cwd: z.string(),
   /** What the panel showed last; absent until a turn ends or it closes. */
   entries: z.array(askEntrySchema).optional(),
-  /** The agent edits and runs commands without asking. */
-  bypass: z.boolean().optional(),
+  /** What the agent may do without asking, when it reopens. */
+  permissions: askPermissionsSchema.optional(),
 });
 
 export type AskRecord = z.infer<typeof askRecordSchema>;
@@ -44,6 +46,7 @@ const rowSchema = z
     updated_at: z.string(),
     entries: z.string().nullable(),
     bypass: z.number(),
+    permissions: z.string().nullable(),
   })
   .transform((row) =>
     askRecordSchema.parse({
@@ -59,7 +62,9 @@ const rowSchema = z
       createdAt: row.created_at,
       updatedAt: row.updated_at,
       entries: row.entries === null ? undefined : JSON.parse(row.entries),
-      bypass: row.bypass === 1,
+      // Saved before auto mode: bypassing permissions, or read-only.
+      permissions:
+        row.permissions ?? (row.bypass === 1 ? "bypass" : "read-only"),
     }),
   );
 
@@ -85,20 +90,27 @@ export class AskHistory {
       updated_at TEXT NOT NULL,
       entries TEXT,
       bypass INTEGER NOT NULL DEFAULT 0,
+      permissions TEXT,
       UNIQUE(agent, session_id));
     CREATE INDEX IF NOT EXISTS ask_conversations_review ON ask_conversations(review_id, updated_at);`);
 
-    // Conversations saved before bypassing permissions lack the column.
-    if (
-      !db
+    // Conversations saved before bypassing permissions, or before auto mode,
+    // lack its column.
+    const columns = new Set(
+      db
         .prepare("PRAGMA table_info(ask_conversations)")
         .all()
-        .some((column) => String(column.name) === "bypass")
-    )
+        .map((column) => String(column.name)),
+    );
+
+    if (!columns.has("bypass"))
       db.exec(
         "ALTER TABLE ask_conversations ADD COLUMN bypass INTEGER NOT NULL DEFAULT 0",
       );
 
+    if (!columns.has("permissions"))
+      db.exec("ALTER TABLE ask_conversations ADD COLUMN permissions TEXT");
+
     // What each agent offered last, so a new question can pick a model and
     // effort, and a command, before its agent starts.
     db.exec(
@@ -132,8 +144,8 @@ export class AskHistory {
     this.assertWritable(record.reviewId);
     this.db
       .prepare(
-        `INSERT OR REPLACE INTO ask_conversations(id,review_id,agent,session_id,version,head,cwd,selection,title,created_at,updated_at,bypass)
-        VALUES(?,?,?,?,?,?,?,?,?,?,?,?)`,
+        `INSERT OR REPLACE INTO ask_conversations(id,review_id,agent,session_id,version,head,cwd,selection,title,created_at,updated_at,bypass,permissions)
+        VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)`,
       )
       .run(
         record.id,
@@ -147,16 +159,19 @@ export class AskHistory {
         record.title,
         record.createdAt,
         record.updatedAt,
-        record.bypass ? 1 : 0,
+        record.permissions === "bypass" ? 1 : 0,
+        record.permissions ?? null,
       );
   }
 
-  /** Whether reopening the conversation bypasses permissions. */
-  setBypass(id: string, bypass: boolean) {
+  /** What the agent may do without asking when the conversation reopens. */
+  setPermissions(id: string, permissions: AskPermissions) {
     this.assertThreadWritable(id);
     this.db
-      .prepare("UPDATE ask_conversations SET bypass=? WHERE id=?")
-      .run(bypass ? 1 : 0, id);
+      .prepare(
+        "UPDATE ask_conversations SET bypass=?, permissions=? WHERE id=?",
+      )
+      .run(permissions === "bypass" ? 1 : 0, permissions, id);
   }
 
   /** Points a conversation at a new session, when its agent could not
@@ -246,7 +261,7 @@ export class AskHistory {
           version: _version,
           cwd: _cwd,
           entries,
-          bypass: _bypass,
+          permissions: _permissions,
           ...entry
         } = rowSchema.parse(row);
 

package/src/review-api/authoring-tools.ts

@@ -36,7 +36,7 @@ export function authoringTools(
 
   const descriptions = {
     create:
-      'Create a review of saved working files, immutable commits or a GitHub PR. Revisions are resolved on acceptance. A worktree target reviews the saved files in its checkout, uncommitted ones included and untracked ones left out (git add -N a new file to include it), against base: the branch to compare against, by default the default branch of the repository. The diff starts at the merge base of base and HEAD, which follows rebases. Omitted commits base means source at head with no diff; supply the parent to review introduced changes. For a GitHub PR, pullRequestUrl alone is enough: target and title become optional, and the host fetches the PR into a registered checkout of its repository and pins the current PR head and GitHub diff base, titled from the PR. When the existing review for that PR is in Trash, creation reports its ID; restore it with review_lifecycle state:"active" before continuing. When an active review for that PR exists, it is returned instead, reporting whether its head moved and whether an agent is working on it; update it in place, move its target with review_set_target, or create a separate review with reuseExisting. kind:"scratchpad" names the one scratchpad, which the host creates itself. The result carries review, the review as review_list shows it: its target with resolved commits, origin (its PR), repositoryName and repositoryPath, so no follow-up read is needed before diffing. When Desktop is available the review opens there and the result reports opened, softwareMapEnabled and environmentIssues, as review_open does; set open:false to author in the background without taking over Desktop.',
+      'Create a review of saved working files, immutable commits or a GitHub PR. Revisions are resolved on acceptance. A worktree target reviews the saved files in its checkout, uncommitted ones included and untracked ones left out (git add -N a new file to include it), against base: the branch to compare against, by default the default branch of the repository. The diff starts at the merge base of base and HEAD, which follows rebases. Omitted commits base means source at head with no diff; supply the parent to review introduced changes. For a branch stacked on another, pass the branch below it as base; Desktop links reviews into a stack through their bases. For a GitHub PR, pullRequestUrl alone is enough: target and title become optional, and the host fetches the PR into a registered checkout of its repository and pins the current PR head and GitHub diff base, titled from the PR. When the existing review for that PR is in Trash, creation reports its ID; restore it with review_lifecycle state:"active" before continuing. When an active review for that PR exists, it is returned instead, reporting whether its head moved and whether an agent is working on it; update it in place, move its target with review_set_target, or create a separate review with reuseExisting. kind:"scratchpad" names the one scratchpad, which the host creates itself. The result carries review, the review as review_list shows it: its target with resolved commits, origin (its PR), repositoryName and repositoryPath, so no follow-up read is needed before diffing. When Desktop is available the review opens there and the result reports opened, softwareMapEnabled and environmentIssues, as review_open does; set open:false to author in the background without taking over Desktop.',
     set_target:
       "Move the review to a new target, such as the commits after a rebase or amend, preserving the document and component IDs. Revisions are resolved on acceptance. Returns warnings for retained source ranges in files the new commits changed, to verify, and resources that no longer match; fix them with review_edit. Earlier versions keep their source. Omitted pullRequestUrl keeps the PR within the same repository; changing repositories clears it. Supply a URL to replace it or null to detach.",
     edit: [

package/src/review-api/blocks/index.ts

@@ -14,7 +14,6 @@ import { type SectionBlock, section, sectionSchema } from "./section.js";
 import { sequence } from "./sequence.js";
 import { software_map } from "./software_map.js";
 import { trace_quote } from "./trace_quote.js";
-import { type TutorialBlock, tutorial, tutorialSchema } from "./tutorial.js";
 
 /** Leaf kinds share one discriminated union so unknown types read as they always have. */
 export const leafSchema = z.discriminatedUnion("type", [
@@ -33,7 +32,7 @@ export const leafSchema = z.discriminatedUnion("type", [
 
 export type LeafBlock = z.infer<typeof leafSchema>;
 
-export type Block = LeafBlock | SectionBlock | CalloutBlock | TutorialBlock;
+export type Block = LeafBlock | SectionBlock | CalloutBlock;
 
 export type BlockType = Block["type"];
 
@@ -56,7 +55,6 @@ export const blocks = {
   flow_diagram,
   section,
   callout,
-  tutorial,
 } satisfies Definitions;
 
 /** Discriminated by type, so a malformed block reports its own kind's
@@ -68,7 +66,7 @@ export const blockSchema: z.ZodType<Block> = z.lazy(() =>
 /** Each block kind's schema, for unions that add kinds of their own. Read
  * lazily: the container modules import this one. */
 export const blockKindSchemas = () =>
-  [leafSchema, sectionSchema, calloutSchema, tutorialSchema] as const;
+  [leafSchema, sectionSchema, calloutSchema] as const;
 
 function checkBlock<K extends BlockType>(
   type: K,

package/src/review-api/document.ts

@@ -450,10 +450,7 @@ export const editSchema = edits(contentSchema, blockSchema, z.json());
 
 export type Edit = z.infer<typeof editSchema>;
 
-// Tutorial blocks are the built-in tutorial's, not for agents to write.
-const writableBlockTypes = Object.keys(blocks).filter(
-  (type) => type !== "tutorial",
-);
+const writableBlockTypes = Object.keys(blocks);
 
 const namedByType = (types: string[]) =>
   z