@fungi.computer/bonsai 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @fungi.computer/bonsai
 
+## 0.2.0
+
+### Minor Changes
+
+- Changes since 0.1.0:
+
+  - fix(oyster): keep Stage out of the starter release
+  - fix(shed): compact the model-facing command reply
+  - refactor(shed): send Workflow Git commands without any credential
+  - feat: show the Fungi sigil in the Bonsai and Tourtois tab
+  - fix(bonsai,oyster)!: share the repository App source wire through
+    workflows-wire
+  - fix(oyster,bonsai): export the types public signatures use
+  - refactor(bonsai): share authoring browser fixtures
+  - test(bonsai): follow Workflow-only Settings authoring
+  - fix(authoring): preserve Workflow refusals across lifecycle and native RPC
+  - Revert "fix(bonsai): remove impossible local App release command"
+  - fix(bonsai): remove impossible local App release command
+  - chore(b3a): checkpoint native workflow consumers and shared renderer types
+  - fix(b3a): align template and native proof consumers
+  - chore(b3a): checkpoint manual workflow integration
+  - refactor: move repository installation into Workflow nodes
+  - feat(apps): discover repository builds and install local Releases
+  - feat(apps): retain typed build installation outcomes in Settings
+  - test(apps): prove honest build refusals through host and Settings
+  - feat(bonsai): add repository App registration method and settings action
+  - fix(bonsai): clean up HTTPS Git fixture certificates
+  - feat(oyster): derive App build recipes from package metadata
+  - refactor(oyster)!: move the shell client into @fungi.computer/nacre
+  - refactor(computer)!: move the operation contract into computer-contract
+  - feat(oyster): add stage to the starter apps
+  - feat(oyster): public release 0.2.0
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+  - @fungi.computer/agar@0.3.0
+  - @fungi.computer/braid@0.2.0
+  - @fungi.computer/cairn@0.1.0
+  - @fungi.computer/caps@0.2.0
+  - @fungi.computer/gills@0.2.0
+  - @fungi.computer/issues@0.1.0
+  - @fungi.computer/maosaico@0.1.0
+  - @fungi.computer/nacre@0.0.1
+  - @fungi.computer/oyster@0.3.0
+  - @fungi.computer/puffball@0.2.0
+  - @fungi.computer/sigils@0.2.0
+  - @fungi.computer/stipe@0.1.0
+  - @fungi.computer/trellis@0.2.0
+  - @fungi.computer/watchdog@0.1.0
+  - @fungi.computer/workflows-wire@0.2.0
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -112,9 +112,10 @@ retried after 10 s, 1 min, 5 min, 30 min and 2 h;
 
 Bonsai also edits the other Apps on your Oyster. `apps.fork` copies an installed
 App's source into a new Bonsai repository you own. Push your changes to it, then
-open the repository's **Settings** and use **Build & install**: Oyster builds
-that exact commit on your Computer and installs the Release, or switches a live
-installation onto it while keeping its data. To fork Bonsai itself:
+open the repository's **Settings** and use **Build & install**: the retained
+Workflow builds that exact commit on a hosted Computer, verifies its Release,
+and installs it or switches a live installation while keeping its data. To fork
+Bonsai itself:
 
 ```sh
 curl -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' \
@@ -129,6 +130,59 @@ your forks with `--repositories <base URL>` and `--ref <branch or tag>`. The
 installer reads all seven starter Apps from that base, so fork them under one
 account.
 
+## Make a repository an App
+
+On a standalone Oyster, open the repository's **Settings → Make this an App**.
+The owner-only `apps.register({ repo })` call reads the committed main root's
+`package.json` through Oyster's shared manifest reader. The App owns its
+`fungi.appId` identity and `fungi.build` recipe; a registered fork keeps its own
+identity. Registration neither builds nor installs and never selects or starts a
+Computer. Caller-supplied identities, recipes and source installations are not
+registration inputs.
+
+**Build & install** fills the readonly App ID and editable revision/name from
+registration or the latest recorded job. Accepted main pushes and merges use the
+host's accepted-ref journal, not a trusted App merge payload, to build the exact
+commit on a hosted backend. A failed build leaves the running Release unchanged.
+Automatic installation reuses approval only: new permissions show **Needs owner
+consent** without switching Releases or offering a misleading install button.
+
+The explicit owner button calls `apps.startBuildWorkflow` with the repository,
+revision, installation name and a replay key. It starts the same published
+build/verify/install definition as accepted main pushes; the panel does not call
+`apps.build` or `apps.install` separately. `apps.buildWorkflowRun({ runId })`
+reads its recorded steps for the shared Trellis cards. To discover automatic
+runs without a browser-held ID, the owner can call `apps.buildWorkflowRuns({})`:
+it reads at most fifty stock build Workflow runs from this installation's
+`WORKFLOWS.runs` door. Neither read starts work or maintains a trigger ledger.
+
+Settings discovers job status by `apps.buildStatus({ repo })` after reload; no
+remembered browser job ID is required. No recorded job returns `null`, not an
+invented success or failure. Workflows still poll their specific job with
+`apps.buildStatus({ jobId })`; that call is Pending until build and automatic
+installation settle. These are two current selectors for different callers. A
+local-only Computer is not a build backend and returns typed `no_backend`. This
+flow does not deploy a host or implement a separate consent ledger.
+
+The retained Trellis **Build on merge** template is requested through the
+Workflows capability by Bonsai's host-attested accepted-main lifecycle, with the
+registered App identity and the exact accepted head. Its verification step is
+**apps.verifyBuild({ jobId, sourceRevision })**: it waits only for the build,
+not for installation, then returns the canonically decoded Release only if its
+provenance matches. Build, verification and install each declare a result card.
+The template has no review configuration or review step; installation requires
+the Workflow's authority, not an App-origin installation exception.
+
+**Breaking declaration contract:** Bonsai declares **WORKFLOWS.catalog**,
+**WORKFLOWS.runGraph**, **WORKFLOWS.graphStatus**, **WORKFLOWS.runs**, Workflow
+run/publication capabilities and **APPS.repository**. The latter is a read-only
+lookup for the owner action or **onGitPush**, scoped to the live calling
+installation; it neither registers a source nor selects a Computer. The retained
+runGraph compiler requires catalog permission and reads the Apps bound by the
+request; Bonsai declares that read operation rather than bypassing the host's
+check. Updated declarations must go through the ordinary owner-consent path. Old
+App-origin installation remains refused.
+
 ## Agent tools
 
 Every method is `POST $OYSTER_URL/apps/bonsai/methods/<name>` with a JSON body
@@ -136,15 +190,15 @@ and a key, and the same methods reach agents through Oyster's MCP endpoint; see
 [Git, keys and MCP](https://github.com/fungi-computer/oyster#git-keys-and-mcp).
 Bonsai's own UI uses the same API.
 
-| Area         | Methods                                                                                                    |
-| ------------ | ---------------------------------------------------------------------------------------------------------- |
-| Repositories | `repos.list`, `repos.get`, `repos.create`, `repos.fork`, `repos.delete`, `branches.options`                |
-| Files        | `files.tree`, `files.list`, `files.read`, `files.save`, `files.sync`, `files.discard`, `issues.read`       |
-| History      | `commits.list`, `commits.get`, `graph.get`, `activity.list`, `actors.list`                                 |
-| Changes      | `changes.list`, `changes.get`, `changes.open`, `changes.approve`, `changes.merge`, `changes.close`, `sync` |
-| Checks       | `checks.request`, `checks.report`                                                                          |
-| Insights     | `insights.code`, `insights.layout.get`, `insights.layout.save`                                             |
-| Apps (owner) | `apps.fork`, `apps.build`, `apps.buildStatus`, `apps.install`                                              |
+| Area         | Methods                                                                                                                                                                          |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Repositories | `repos.list`, `repos.get`, `repos.create`, `repos.fork`, `repos.delete`, `branches.options`                                                                                      |
+| Files        | `files.tree`, `files.list`, `files.read`, `files.save`, `files.sync`, `files.discard`, `issues.read`                                                                             |
+| History      | `commits.list`, `commits.get`, `graph.get`, `activity.list`, `actors.list`                                                                                                       |
+| Changes      | `changes.list`, `changes.get`, `changes.open`, `changes.approve`, `changes.merge`, `changes.close`, `sync`                                                                       |
+| Checks       | `checks.request`, `checks.report`                                                                                                                                                |
+| Insights     | `insights.code`, `insights.layout.get`, `insights.layout.save`                                                                                                                   |
+| Apps (owner) | `apps.register`, `apps.fork`, `apps.startBuildWorkflow`, `apps.buildWorkflowRuns`, `apps.buildWorkflowRun`, `apps.build`, `apps.buildStatus`, `apps.verifyBuild`, `apps.install` |
 
 ## How it is built
 

package/backend/build-workflow.ts

@@ -0,0 +1,137 @@
+import * as S from "effect/Schema";
+import { parseSha256Digest } from "@fungi.computer/puffball";
+import {
+  appGitPushFactSchema,
+  type AppGitPushFact,
+} from "@fungi.computer/agar/git";
+import { contentDigest, workflowDefinitionSchema } from "@fungi.computer/braid";
+import type { GraphStartRequest } from "@fungi.computer/braid/runtime";
+import {
+  repositoryWorkflowSourceSchema,
+  runReply,
+  statusReply,
+  runsReplySchema,
+} from "@fungi.computer/workflows-wire";
+import { AppMethodRefusal } from "@fungi.computer/agar/backend";
+import type { AppBuildWorkflowInput } from "../shared/contract.js";
+import template from "@fungi.computer/trellis/templates/bonsai-build-on-merge" with { type: "json" };
+
+export type RepositoryWorkflowSource =
+  typeof repositoryWorkflowSourceSchema.Type;
+export type BuildWorkflowRunReply = ReturnType<typeof runReply.parse>;
+
+export type BuildWorkflowBindings = Readonly<{
+  APPS?: Readonly<{
+    repository(input: {
+      repo: string;
+    }): Promise<RepositoryWorkflowSource | null>;
+  }>;
+  WORKFLOWS?: Readonly<{
+    runs(input: {
+      workflowId?: string;
+    }): Promise<ReturnType<typeof runsReplySchema.parse>>;
+    runGraph(input: GraphStartRequest): Promise<BuildWorkflowRunReply>;
+    graphStatus(input: {
+      runId: string;
+    }): Promise<ReturnType<typeof statusReply.parse>>;
+  }>;
+}>;
+
+/** One request path for accepted main pushes and an explicit owner action.
+ * The host owns lifecycle identity; manual request IDs are ordinary call replay
+ * keys. Neither entrypoint constructs a call frame or installs as this App. */
+async function requestBuildWorkflow(
+  env: BuildWorkflowBindings,
+  input: AppBuildWorkflowInput,
+) {
+  if (env.APPS === undefined)
+    throw new AppMethodRefusal(
+      "unavailable",
+      "App source lookup is unavailable",
+    );
+  const source = S.decodeUnknownSync(S.NullOr(repositoryWorkflowSourceSchema))(
+    await env.APPS.repository({ repo: input.repo }),
+  );
+  if (source === null) return null;
+  if (env.WORKFLOWS === undefined)
+    throw new AppMethodRefusal("unavailable", "Workflow access is not granted");
+  const stock = S.decodeUnknownSync(workflowDefinitionSchema)(
+    template.definition,
+  );
+  const definition = {
+    ...stock,
+    apps: { bonsai: { appId: source.callerAppId } },
+  };
+  const response = runReply.parse(
+    await env.WORKFLOWS.runGraph({
+      requestId: input.requestId,
+      definition,
+      bindings: { bonsai: source.installationId },
+      input: {
+        appId: source.appId,
+        sourceRevision: input.sourceRevision,
+        installationId: input.installationId,
+      },
+      published: {
+        workflowId: template.id,
+        commit: source.callerSourceRevision.slice(4),
+        digest: parseSha256Digest(await contentDigest(definition)),
+      },
+    }),
+  );
+  if (
+    !("kind" in response) ||
+    (response.kind !== "started" && response.kind !== "replay")
+  )
+    throw new AppMethodRefusal(
+      "kind" in response && response.kind === "invalid"
+        ? "invalid"
+        : "unavailable",
+      "Build Workflow refused: " + JSON.stringify(response).slice(0, 2000),
+    );
+  return response;
+}
+
+/** The host journal supplies the accepted main head, never an App merge event. */
+export async function startBuildWorkflow(
+  env: BuildWorkflowBindings,
+  raw: AppGitPushFact,
+): Promise<void> {
+  const fact = appGitPushFactSchema.parse(raw);
+  const update = fact.updates.find(
+    (row) =>
+      row.ref === "refs/heads/main" &&
+      row.after !== "0".repeat(40) &&
+      row.before !== row.after,
+  );
+  if (update === undefined) return;
+  await requestBuildWorkflow(env, {
+    repo: fact.repository,
+    sourceRevision: "git:" + update.after,
+    installationId: fact.repository,
+    requestId: fact.eventId,
+  });
+}
+
+/** Owner calls use the same retained definition, verification and node authority. */
+export async function startManualBuildWorkflow(
+  env: BuildWorkflowBindings,
+  input: AppBuildWorkflowInput,
+) {
+  const started = await requestBuildWorkflow(env, input);
+  if (started === null)
+    throw new AppMethodRefusal(
+      "not_found",
+      "This repository is not registered as an App",
+    );
+  return started;
+}
+
+/** Discover host-owned runs after a push, without materializing a trigger ledger. */
+export async function readBuildWorkflowRuns(env: BuildWorkflowBindings) {
+  if (env.WORKFLOWS === undefined)
+    throw new AppMethodRefusal("unavailable", "Workflow access is not granted");
+  return runsReplySchema.parse(
+    await env.WORKFLOWS.runs({ workflowId: template.id }),
+  );
+}

package/backend/index.ts

@@ -32,15 +32,20 @@ import type {
   BackgroundBinding,
 } from "@fungi.computer/puffball/background-replay";
 import { refuseBackground } from "./background.js";
+import {
+  startBuildWorkflow,
+  type BuildWorkflowBindings,
+} from "./build-workflow.js";
 
 /** The bindings the host grants Bonsai (see the Oyster binding proposal). */
-export type BonsaiEnv = Readonly<{
-  GIT: GitBinding;
-  EVENTS: EventSink;
-  BACKGROUND?: BackgroundBinding;
-  /** Fork, build and install Apps; present only on a host that supplies it. */
-  APPS?: BonsaiAppsBinding;
-}>;
+export type BonsaiEnv = BuildWorkflowBindings &
+  Readonly<{
+    GIT: GitBinding;
+    EVENTS: EventSink;
+    BACKGROUND?: BackgroundBinding;
+    /** Fork, build and install Apps; present only on a host that supplies it. */
+    APPS?: BonsaiAppsBinding;
+  }>;
 
 const uiRequest = z.strictObject({
   method: z.string().min(1).max(80),
@@ -88,6 +93,7 @@ class BonsaiFacet extends DurableObject<BonsaiEnv> {
 
   async onGitPush(fact: AppGitPushFact): Promise<void> {
     await observePush(this.bonsai, fact);
+    await startBuildWorkflow(this.env, fact);
   }
 
   authorizeGitPush(raw: GitPushQuestion): Promise<GitPushVerdict> {

package/backend/methods.ts

@@ -1,3 +1,13 @@
+import {
+  runReply,
+  statusReply,
+  runsReplySchema,
+} from "@fungi.computer/workflows-wire";
+import {
+  startManualBuildWorkflow,
+  readBuildWorkflowRuns,
+  type BuildWorkflowBindings,
+} from "./build-workflow.js";
 import { resultRows } from "@fungi.computer/agar/method-presentation";
 import { openChangesGill, recentCommitsGill } from "./gills.js";
 import {
@@ -35,6 +45,8 @@ import {
 } from "@fungi.computer/agar/backend-definition";
 import type { AppMethodCallContext } from "@fungi.computer/puffball/app-method-runtime";
 import * as z from "zod";
+import * as S from "effect/Schema";
+import { releaseSchema } from "@fungi.computer/puffball/effect";
 import {
   gitSha1Schema,
   gitRepositoryNameSchema,
@@ -42,6 +54,10 @@ import {
 import {
   activityPage,
   appBuildView,
+  appBuildWorkflowInput,
+  appBuildStatusInput,
+  appRegistrationInput,
+  appRegistration,
   approvalResult,
   checkRequestResult,
   checkReportResult,
@@ -102,6 +118,9 @@ export type AppsBindingReply = Readonly<{
 
 /** The host `APPS` binding: fork a source, build it, and install a Release. */
 export type BonsaiAppsBinding = Readonly<{
+  register(
+    input: z.infer<typeof appRegistrationInput>,
+  ): Promise<AppsBindingReply>;
   fork(input: {
     platformAppId: string;
     name: string;
@@ -109,9 +128,13 @@ export type BonsaiAppsBinding = Readonly<{
   build(input: {
     appId: string;
     sourceRevision: string;
+    installationId?: string;
   }): Promise<AppsBindingReply>;
-  buildStatus(input: { jobId: string }): Promise<AppsBindingReply>;
+  buildStatus(
+    input: z.infer<typeof appBuildStatusInput>,
+  ): Promise<AppsBindingReply>;
   select(input: {
+    jobId: string;
     installationId: string;
     release: unknown;
   }): Promise<AppsBindingReply>;
@@ -120,10 +143,11 @@ export type BonsaiAppsBinding = Readonly<{
 /** What a Bonsai method runs against: the facet supplies it. */
 type BonsaiMethodContext = Readonly<{
   bonsai: Bonsai;
-  env?: Readonly<{
-    BACKGROUND?: BackgroundBinding;
-    APPS?: BonsaiAppsBinding;
-  }>;
+  env?: BuildWorkflowBindings &
+    Readonly<{
+      BACKGROUND?: BackgroundBinding;
+      APPS?: BonsaiAppsBinding;
+    }>;
 }>;
 
 const bindingErrorBody = z.object({ error: z.string() });
@@ -133,13 +157,15 @@ function refuseBindingReply(reply: AppsBindingReply): never {
   const parsed = bindingErrorBody.safeParse(reply.body);
   const message = parsed.success ? parsed.data.error : "Request refused";
   throw new AppMethodRefusal(
-    reply.status === 404
-      ? "not_found"
-      : reply.status === 409
-        ? "conflict"
-        : reply.status === 403
-          ? "forbidden"
-          : "invalid",
+    reply.status >= 500
+      ? "unavailable"
+      : reply.status === 404
+        ? "not_found"
+        : reply.status === 409
+          ? "conflict"
+          : reply.status === 403
+            ? "forbidden"
+            : "invalid",
     message,
   );
 }
@@ -220,6 +246,72 @@ const definition = defineAppBackend<BonsaiMethodContext>({
     },
   },
   methods: {
+    "apps.register": defineAppMethod({
+      description:
+        "Make this repository an App using its main commit's package.json build recipe. Owner only; does not build or install it.",
+      effect: "write",
+      requires: ["git.repository"],
+      input: appRegistrationInput,
+      output: appRegistration,
+      handler: async (input, context: BonsaiMethodContext, caller) => {
+        if (caller.role !== "owner")
+          throw new AppMethodRefusal("forbidden", "Owner only");
+        if (!context.env?.APPS)
+          throw new AppMethodRefusal(
+            "unavailable",
+            "App registration is unavailable",
+          );
+        const reply = await context.env.APPS.register(input);
+        if (reply.status >= 400) refuseBindingReply(reply);
+        return appRegistration.parse(reply.body);
+      },
+    }),
+    "apps.startBuildWorkflow": defineAppMethod({
+      description:
+        "Build, verify and install this repository through the published Workflow. Owner only.",
+      effect: "write",
+      requires: ["git.repository", "workflow.run", "workflow.publish"],
+      input: appBuildWorkflowInput,
+      output: runReply,
+      handler: (input, context: BonsaiMethodContext, caller) => {
+        if (caller.role !== "owner")
+          throw new AppMethodRefusal("forbidden", "Owner only");
+        return startManualBuildWorkflow(context.env ?? {}, input);
+      },
+    }),
+    "apps.buildWorkflowRuns": defineAppMethod({
+      description:
+        "Discover up to fifty runs of this installation's build Workflow, including accepted main pushes. Read-only; owner only.",
+      effect: "read",
+      requires: ["workflow.run"],
+      input: z.strictObject({}),
+      output: runsReplySchema,
+      handler: (_input, context: BonsaiMethodContext, caller) => {
+        if (caller.role !== "owner")
+          throw new AppMethodRefusal("forbidden", "Owner only");
+        return readBuildWorkflowRuns(context.env ?? {});
+      },
+    }),
+    "apps.buildWorkflowRun": defineAppMethod({
+      description:
+        "Read this installation's build Workflow and its recorded step results. Owner only.",
+      effect: "read",
+      requires: ["workflow.run"],
+      input: z.strictObject({ runId: z.string().min(1).max(256) }),
+      output: statusReply,
+      handler: async (input, context: BonsaiMethodContext, caller) => {
+        if (caller.role !== "owner")
+          throw new AppMethodRefusal("forbidden", "Owner only");
+        if (context.env?.WORKFLOWS === undefined)
+          throw new AppMethodRefusal(
+            "unavailable",
+            "Workflow access is not granted",
+          );
+        return statusReply.parse(
+          await context.env.WORKFLOWS.graphStatus(input),
+        );
+      },
+    }),
     "apps.build": defineAppMethod({
       description:
         "Build an App's registered source at one exact commit on this Oyster's Computer; the job keeps running after this call returns. Owner only.",
@@ -230,28 +322,44 @@ const definition = defineAppBackend<BonsaiMethodContext>({
       input: z.strictObject({
         appId: z.string().min(1).max(256),
         sourceRevision: z.string().min(1).max(256),
+        installationId: z.string().min(1).max(256).optional(),
       }),
       output: appBuildView,
+      present: {
+        rows: resultRows,
+        verb: "started",
+        row: ({ output }) => ({
+          id: output.jobId,
+          title: "Build " + output.status,
+          detail: output.sourceRevision,
+        }),
+      },
       handler: async (input, context: BonsaiMethodContext, caller) => {
         if (caller.role !== "owner")
           throw new AppMethodRefusal("forbidden", "Owner only");
         if (!context.env?.APPS)
           throw new AppMethodRefusal("unavailable", "Build is unavailable");
-        const reply = await context.env.APPS.build(input);
+        const request: Parameters<BonsaiAppsBinding["build"]>[0] = {
+          appId: input.appId,
+          sourceRevision: input.sourceRevision,
+        };
+        if (input.installationId !== undefined)
+          request.installationId = input.installationId;
+        const reply = await context.env.APPS.build(request);
         if (reply.status >= 400) refuseBindingReply(reply);
         return appBuildView.parse(reply.body);
       },
     }),
     "apps.buildStatus": defineAppMethod({
       description:
-        "Wait for one build job: Pending while it runs, then its settled status and Release. Owner only.",
+        "Read one build job or discover this repository's latest job. Pending until build and automatic installation settle. Owner only.",
       effect: "read",
       // The host grants its APPS operation only under these approvals.
       requires: ["git.repository", "computer.execute"],
       // A Workflow step waits on the job by polling this same call.
       pending: true,
-      input: z.strictObject({ jobId: z.string().min(1).max(256) }),
-      output: appBuildView,
+      input: appBuildStatusInput,
+      output: appBuildView.nullable(),
       handler: async (input, context: BonsaiMethodContext, caller) => {
         if (caller.role !== "owner")
           throw new AppMethodRefusal("forbidden", "Owner only");
@@ -259,27 +367,104 @@ const definition = defineAppBackend<BonsaiMethodContext>({
           throw new AppMethodRefusal("unavailable", "Build is unavailable");
         const reply = await context.env.APPS.buildStatus(input);
         if (reply.status >= 400) refuseBindingReply(reply);
-        const build = appBuildView.parse(reply.body);
-        return build.status === "running" ? pending(5_000) : build;
+        const build = appBuildView.nullable().parse(reply.body);
+        if (build === null) return null;
+        return build.status === "running" ||
+          (build.status === "succeeded" &&
+            build.installation?.kind === "pending")
+          ? pending(5_000)
+          : build;
+      },
+    }),
+    "apps.verifyBuild": defineAppMethod({
+      description:
+        "Wait for the build's boot gate and verify that its Release is the exact requested commit. A failed or mismatched build never installs.",
+      effect: "read",
+      requires: ["git.repository", "computer.execute"],
+      pending: true,
+      input: z.strictObject({
+        jobId: z.string().min(1).max(256),
+        sourceRevision: z.string().regex(/^git:[0-9a-f]{40}$/),
+      }),
+      output: z.strictObject({
+        release: z.unknown(),
+        summary: z.string().max(4000),
+      }),
+      present: {
+        rows: resultRows,
+        verb: "verified",
+        row: ({ output }) => ({
+          id: "apps.verifyBuild",
+          title: "Release verified",
+          detail: output.summary,
+        }),
+      },
+      handler: async (input, context: BonsaiMethodContext, caller) => {
+        if (caller.role !== "owner")
+          throw new AppMethodRefusal("forbidden", "Owner only");
+        if (!context.env?.APPS)
+          throw new AppMethodRefusal("unavailable", "Build is unavailable");
+        const reply = await context.env.APPS.buildStatus({
+          jobId: input.jobId,
+        });
+        if (reply.status >= 400) refuseBindingReply(reply);
+        const build = appBuildView.nullable().parse(reply.body);
+        if (build === null)
+          throw new AppMethodRefusal("not_found", "Build not found");
+        if (build.status === "running") return pending(5_000);
+        if (build.status !== "succeeded" || build.release === null)
+          throw new AppMethodRefusal(
+            "invalid",
+            "The build did not pass" +
+              (build.detail === null ? "" : ": " + build.detail.slice(-2000)),
+          );
+        const release = S.decodeUnknownSync(releaseSchema)(build.release);
+        if (release.artifact.provenance.sourceRevision !== input.sourceRevision)
+          throw new AppMethodRefusal(
+            "invalid",
+            "The build's Release is not the requested commit",
+          );
+        return {
+          release,
+          summary:
+            "Built " +
+            release.releaseId +
+            " of " +
+            release.appId +
+            " from " +
+            input.sourceRevision,
+        };
       },
     }),
     "apps.install": defineAppMethod({
       description:
         "Install a built Release at an installation id, or switch an already-live one onto it. Owner only.",
       effect: "write",
+      pending: true,
       // The host grants its APPS operation only under these approvals.
       requires: ["git.repository", "computer.execute"],
       input: z.strictObject({
+        jobId: z.string().min(1).max(256),
         installationId: z.string().min(1).max(256),
         release: z.unknown(),
       }),
       output: z.unknown(),
+      present: {
+        rows: resultRows,
+        verb: "installed",
+        row: ({ input }) => ({
+          id: "apps.install",
+          title: "Release installed",
+          detail: input.installationId,
+        }),
+      },
       handler: async (input, context: BonsaiMethodContext, caller) => {
         if (caller.role !== "owner")
           throw new AppMethodRefusal("forbidden", "Owner only");
         if (!context.env?.APPS)
           throw new AppMethodRefusal("unavailable", "Install is unavailable");
         const reply = await context.env.APPS.select(input);
+        if (reply.status === 202) return pending(5000);
         if (reply.status >= 400) refuseBindingReply(reply);
         return reply.body;
       },
@@ -697,7 +882,12 @@ const definition = defineAppBackend<BonsaiMethodContext>({
       effect: "write",
       // The continuation covers every write's requirements (apps.build's
       // computer.execute included); it only replays queued Git writes.
-      requires: ["git.repository", "computer.execute"],
+      requires: [
+        "git.repository",
+        "computer.execute",
+        "workflow.run",
+        "workflow.publish",
+      ],
       input: z.strictObject({}),
       output: z.strictObject({ more: z.boolean() }),
       handler: (_input, context, caller) =>