From 862195a9994419383ae40c37ed8df2f6d2272a0a Mon Sep 17 00:00:00 2001
From: Quang Lee <winlp4ever@gmail.com>
Date: Thu, 8 Oct 2026 17:59:21 +0200
Subject: [PATCH 01/10] feat(schema)!: add desktop electron apps to a project's
 apps (#54)

BREAKING CHANGE: App is a union of web and electron apps; code reading app.url narrows on kind first.
---
 apps/desktop/src/main/index.ts                |  25 +-
 apps/desktop/src/main/project.ts              |  42 ++-
 apps/desktop/src/main/workspace.ts            |   7 +-
 .../renderer/src/components/apps-panel.tsx    |  10 +-
 .../renderer/src/components/secrets-panel.tsx | 299 +++++++++---------
 .../src/renderer/src/components/stage.tsx     |   9 +-
 .../src/renderer/src/components/title-bar.tsx |  21 +-
 apps/desktop/src/renderer/test/app.test.tsx   |   3 +-
 apps/desktop/src/renderer/test/apps.test.tsx  |   7 +-
 apps/desktop/src/renderer/test/chat.test.tsx  |   3 +-
 .../src/renderer/test/handover.test.tsx       |   3 +-
 .../src/renderer/test/preview.test.tsx        |   6 +-
 .../src/renderer/test/secrets.test.tsx        |  43 ++-
 apps/desktop/src/shared/ipc.ts                |  19 +-
 apps/desktop/src/shared/util.ts               |  12 +
 apps/desktop/test/project.test.ts             |  67 +++-
 docs/OBJECT-MODEL.md                          |   7 +
 packages/project/test/project.test.ts         |   2 +-
 packages/runtime/src/recorder.ts              |   5 +-
 packages/runtime/src/run/actions.ts           |   4 +-
 packages/runtime/src/run/apps.ts              |  22 +-
 packages/runtime/src/run/conditions.ts        |   4 +-
 packages/runtime/src/run/setup.ts             |  14 +-
 packages/runtime/src/runner.ts                |  11 +-
 packages/runtime/test/apps.test.ts            |  89 ++++++
 packages/schema/src/apps.test.ts              |  99 +++++-
 packages/schema/src/docs-examples.test.ts     |   2 +-
 packages/schema/src/project-model.test.ts     |   4 +-
 packages/schema/src/project.ts                | 110 ++++++-
 packages/schema/src/resolve.ts                |   4 +-
 packages/studio/src/add-app.ts                |   4 +-
 packages/studio/src/prompt.ts                 |  16 +-
 packages/studio/src/studio.ts                 |  63 ++--
 packages/studio/src/tools.ts                  |   7 +-
 packages/studio/test/desktop-app.test.ts      |  96 ++++++
 packages/studio/test/studio.test.ts           |   7 +-
 scripts/m1-4/batch-check.ts                   |   4 +-
 scripts/p0-8/ground.ts                        |   4 +-
 scripts/p0-8/login-check.ts                   |   4 +-
 scripts/record.ts                             |   4 +-
 40 files changed, 871 insertions(+), 291 deletions(-)
 create mode 100644 packages/studio/test/desktop-app.test.ts

diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index a1217c8..b8522e2 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -14,7 +14,7 @@ import { resolveAppAddress } from "./app-address.ts"
 import { emit, registerHandlers } from "./ipc.ts"
 import { DEFAULT_MODEL, imageInput, modelConfig } from "./model.ts"
 import {
-  appOriginOf,
+  secretOriginOf,
   appRemovalRefused,
   newProjectDir,
   projectFileName,
@@ -201,8 +201,9 @@ function start(): void {
     if (takes === undefined) throw new Error("the app isn't ready yet")
     return { registry, takes }
   }
-  /** One of the open project's apps for the window's request (`appOriginOf`). */
-  const appOrigin = (session: string, app: string) => appOriginOf(workspace.apps(), session, app)
+  /** A secret's origin: a web app's (a desktop app takes none). */
+  const secretOrigin = (session: string, app: string) =>
+    secretOriginOf(workspace.apps(), session, app)
 
   /**
    * The open project and its agent, switched as one. An agent's events reach the window only while
@@ -394,14 +395,16 @@ function start(): void {
         "secrets:list": async () => {
           const secrets = vault()
           await secrets.ready()
-          return (workspace.apps()?.apps ?? []).map(({ name, origin }) => ({
+          // Web apps only: a desktop app takes no secrets.
+          const apps = (workspace.apps()?.apps ?? []).filter((a) => a.kind === "web")
+          return apps.map(({ name, origin }) => ({
             app: name,
             origin,
             secrets: secrets.list(origin),
           }))
         },
         "secrets:add": async ({ session, app, ...form }) => {
-          const at = appOrigin(session, app)
+          const at = secretOrigin(session, app)
           if ("why" in at) return at.why
           try {
             await vault().add(form, at.origin)
@@ -412,7 +415,7 @@ function start(): void {
           }
         },
         "secrets:remove": async ({ session, app, name }) => {
-          const at = appOrigin(session, app)
+          const at = secretOrigin(session, app)
           if ("why" in at) return at.why
           try {
             await vault().remove(name, at.origin)
@@ -421,12 +424,12 @@ function start(): void {
             return message(e)
           }
         },
-        "apps:remove": async ({ session, name, origin }) => {
+        "apps:remove": async ({ session, name, identity }) => {
           // Checked before asking and again after (the dialog waits on the user meanwhile).
           const refused = () =>
             appRemovalRefused(
               workspace.apps(),
-              { session, name, origin },
+              { session, name, identity },
               workspace.agent?.running === true,
             )
           const before = refused()
@@ -446,7 +449,7 @@ function start(): void {
               : ` ${rules.length === 1 ? "The interrupt rule" : "The interrupt rules"} ${rules.map((r) => `“${r}”`).join(", ")} ${rules.length === 1 ? "goes" : "go"} there: ${rules.length === 1 ? "it" : "they"} will fail until changed.`
           const { response } = await dialog.showMessageBox(parent(), {
             type: "warning",
-            message: `Remove ${name} (${origin}) from the project?`,
+            message: `Remove ${name} (${identity}) from the project?`,
             detail:
               (uses.length === 0
                 ? "No scene uses it. Its saved secrets stay; its approvals in this project go."
@@ -462,8 +465,10 @@ function start(): void {
           if (after !== null || workspace.opened !== opened) return after ?? "the project changed"
           // This project's approvals on that site go first (the secrets stay: other projects may
           // use them): a failure below leaves the app with its approvals asked again, never kept.
+          // A desktop app has none (it takes no secrets).
+          const removed = workspace.apps()?.apps.find((a) => a.name === name)
           try {
-            vault().revokeAt(ids().scope(opened.dir), origin)
+            if (removed?.kind === "web") vault().revokeAt(ids().scope(opened.dir), removed.origin)
           } catch (e) {
             return `not removed: its approvals couldn't be revoked: ${message(e)}`
           }
diff --git a/apps/desktop/src/main/project.ts b/apps/desktop/src/main/project.ts
index c3a3ea7..0df5e91 100644
--- a/apps/desktop/src/main/project.ts
+++ b/apps/desktop/src/main/project.ts
@@ -3,15 +3,22 @@
 import { createHash } from "node:crypto"
 import { existsSync, readdirSync, statSync } from "node:fs"
 import { type OpenedProject, saveProject, scenesNaming } from "@kiframe/project"
-import { App, appOf, appsNamedByPreset, firstApp, unlistedApps } from "@kiframe/schema"
-import type { ProjectView, SceneView } from "../shared/ipc.ts"
+import { type App, appOf, appsNamedByPreset, firstApp, unlistedApps, WebApp } from "@kiframe/schema"
+import { type AppView, appViewIdentity, type ProjectView, type SceneView } from "../shared/ipc.ts"
 
 /** A project folder's extension (a new project's folder gets it). */
 export const PROJECT_EXTENSION = ".kiframe"
 
+/** An app as the window has it: a web app by its exact origin, a desktop app by its bundle id. */
+export function appView(name: string, app: App): AppView {
+  return app.kind === "web"
+    ? { name, kind: "web", origin: new URL(app.url).origin }
+    : { name, kind: "electron", bundleId: app.bundleId }
+}
+
 /** The app's address, by the project schema's own rule (http(s), no credentials in it). */
 export function targetUrl(url: string): string {
-  const parsed = App.shape.url.safeParse(url.trim())
+  const parsed = WebApp.shape.url.safeParse(url.trim())
   if (!parsed.success) {
     throw new Error(`App address: ${parsed.error.issues[0]?.message ?? "not a URL"}`)
   }
@@ -122,11 +129,7 @@ export function projectView(opened: OpenedProject, session: string): ProjectView
     session,
     name: project.name,
     dir: opened.dir,
-    url: firstApp(project).app.url,
-    apps: Object.entries(project.apps).map(([name, app]) => ({
-      name,
-      origin: new URL(app.url).origin,
-    })),
+    apps: Object.entries(project.apps).map(([name, app]) => appView(name, app)),
     scenes: views,
     problems: problems.map((p) => `${p.sceneId}: ${p.message}`),
   }
@@ -141,13 +144,30 @@ export function appOriginOf(
   view: Pick<ProjectView, "session" | "apps"> | undefined,
   session: string,
   app: string,
-): { origin: string } | { why: string } {
+): AppView | { why: string } {
   if (view === undefined) return { why: "open a project first" }
   if (view.session !== session) return { why: "the project changed meanwhile: try again" }
   const found = view.apps.find((a) => a.name === app)
   return found === undefined ? { why: `"${app}" isn't one of the project's apps` } : found
 }
 
+/**
+ * The origin a secret of `app` is kept for: a web app's; a desktop app takes none in v0 (the user
+ * signs in by hand there), said.
+ */
+export function secretOriginOf(
+  view: Pick<ProjectView, "session" | "apps"> | undefined,
+  session: string,
+  app: string,
+): { origin: string } | { why: string } {
+  const at = appOriginOf(view, session, app)
+  if ("why" in at) return at
+  if (at.kind !== "web") {
+    return { why: `"${app}" is a desktop app: it takes no secrets (sign in by hand when Kif asks)` }
+  }
+  return { origin: at.origin }
+}
+
 /** The titles of the scenes that name `app` (`scenesNaming`: every stored scene). */
 export const scenesUsing = scenesNaming
 
@@ -175,13 +195,13 @@ export function removeApp(opened: OpenedProject, app: string): void {
  */
 export function appRemovalRefused(
   view: Pick<ProjectView, "session" | "apps"> | undefined,
-  request: { session: string; name: string; origin: string },
+  request: { session: string; name: string; identity: string },
   running: boolean,
 ): string | null {
   if (running) return "Kif is working: stop it first"
   const at = appOriginOf(view, request.session, request.name)
   if ("why" in at) return at.why
-  if (at.origin !== request.origin) return "that app changed meanwhile: try again"
+  if (appViewIdentity(at) !== request.identity) return "that app changed meanwhile: try again"
   if (view?.apps[0]?.name === request.name) {
     return `"${request.name}" is where scenes start: it can't be removed`
   }
diff --git a/apps/desktop/src/main/workspace.ts b/apps/desktop/src/main/workspace.ts
index a3e63fd..e0f1ce8 100644
--- a/apps/desktop/src/main/workspace.ts
+++ b/apps/desktop/src/main/workspace.ts
@@ -5,7 +5,7 @@ import { randomBytes } from "node:crypto"
 import { realpathSync } from "node:fs"
 import { createProject, openProject, type OpenedProject } from "@kiframe/project"
 import type { ProjectView } from "../shared/ipc.ts"
-import { projectView } from "./project.ts"
+import { appView, projectView } from "./project.ts"
 
 /** What the workspace needs of an agent. */
 export interface Agent {
@@ -44,10 +44,7 @@ export class Workspace<A extends Agent> {
     if (this.#opened === null) return undefined
     return {
       session: this.#session,
-      apps: Object.entries(this.#opened.project.apps).map(([name, app]) => ({
-        name,
-        origin: new URL(app.url).origin,
-      })),
+      apps: Object.entries(this.#opened.project.apps).map(([name, app]) => appView(name, app)),
     }
   }
 
diff --git a/apps/desktop/src/renderer/src/components/apps-panel.tsx b/apps/desktop/src/renderer/src/components/apps-panel.tsx
index d162bf6..658e77f 100644
--- a/apps/desktop/src/renderer/src/components/apps-panel.tsx
+++ b/apps/desktop/src/renderer/src/components/apps-panel.tsx
@@ -2,7 +2,7 @@
 // first: where scenes start). Main asks before removing, naming the scenes that use it.
 import { Globe, WarningCircle, X } from "@phosphor-icons/react"
 import { useEffect, useRef, useState } from "react"
-import type { ProjectView } from "../../../shared/ipc.ts"
+import { appViewIdentity, type ProjectView } from "../../../shared/ipc.ts"
 import { api } from "../api.ts"
 import { useChat } from "../chat-store.ts"
 
@@ -26,11 +26,11 @@ export function AppsPanel({
     return () => document.removeEventListener("keydown", onKey)
   }, [])
 
-  const remove = async (name: string, origin: string) => {
+  const remove = async (name: string, identity: string) => {
     if (busy) return
     setBusy(true)
     const refused = await api()
-      .invoke("apps:remove", { session: project.session, name, origin })
+      .invoke("apps:remove", { session: project.session, name, identity })
       .catch((e: unknown) => String(e))
     setBusy(false)
     setError(refused)
@@ -54,7 +54,7 @@ export function AppsPanel({
             <li key={app.name}>
               <Globe size={15} />
               <span className="mono">{app.name}</span>
-              <span className="mono app-origin">{app.origin}</span>
+              <span className="mono app-origin">{appViewIdentity(app)}</span>
               <div className="spacer" />
               {i === 0 ? (
                 <span className="app-first">Where scenes start</span>
@@ -64,7 +64,7 @@ export function AppsPanel({
                   className="btn btn-ghost"
                   disabled={busy || running}
                   title={running ? "Kif is working: stop it first" : undefined}
-                  onClick={() => void remove(app.name, app.origin)}
+                  onClick={() => void remove(app.name, appViewIdentity(app))}
                 >
                   Remove {app.name}
                 </button>
diff --git a/apps/desktop/src/renderer/src/components/secrets-panel.tsx b/apps/desktop/src/renderer/src/components/secrets-panel.tsx
index dfeb75a..374fbd6 100644
--- a/apps/desktop/src/renderer/src/components/secrets-panel.tsx
+++ b/apps/desktop/src/renderer/src/components/secrets-panel.tsx
@@ -20,7 +20,9 @@ export function SecretsPanel({
   project: Pick<ProjectView, "session" | "apps">
   onClose: () => void
 }) {
-  const { session, apps } = project
+  const { session } = project
+  // Web apps only: a desktop app takes no secrets (the user signs in by hand there).
+  const apps = project.apps.filter((a) => a.kind === "web")
   const several = apps.length > 1
   const [groups, setGroups] = useState<SecretGroup[] | null>(null)
   const [app, setApp] = useState(apps[0]?.name ?? "")
@@ -105,152 +107,163 @@ export function SecretsPanel({
             <X size={16} />
           </button>
         </div>
-        <p className="dialog-text">
-          Logins and keys Kif may type
-          {several ? (
-            ", app by app"
-          ) : (
-            <>
-              {" "}
-              on <span className="mono">{apps[0]?.origin}</span>
-            </>
-          )}
-          . It only ever sees their names: values stay in your system’s keychain, and are blurred in
-          every take.
-        </p>
-        <p className="dialog-text dialog-note">
-          Use a throwaway demo account. Kif sees the page as text and screenshots, with your secrets
-          hidden where the page shows them as text; a value drawn in an image or a canvas can’t be
-          hidden.
-        </p>
-        {groups === null ? null : groups.every((g) => g.secrets.length === 0) ? (
-          <p className="dialog-empty">No secrets yet.</p>
+        {apps.length === 0 ? (
+          <p className="dialog-text">
+            None of this project’s apps takes secrets: in a desktop app, you sign in yourself when
+            Kif asks.
+          </p>
         ) : (
-          groups.map((group) =>
-            group.secrets.length === 0 ? null : (
-              <section key={group.app} className="secret-group">
-                {several && (
-                  <h3 className="secret-app">
-                    {group.app} <span className="mono">{group.origin}</span>
-                  </h3>
-                )}
-                <ul
-                  className="secret-list"
-                  aria-label={several ? `Secrets of ${group.app}` : "The project's secrets"}
+          <>
+            <p className="dialog-text">
+              Logins and keys Kif may type
+              {several ? (
+                ", app by app"
+              ) : (
+                <>
+                  {" "}
+                  on <span className="mono">{apps[0]?.origin}</span>
+                </>
+              )}
+              . It only ever sees their names: values stay in your system’s keychain, and are
+              blurred in every take.
+            </p>
+            <p className="dialog-text dialog-note">
+              Use a throwaway demo account. Kif sees the page as text and screenshots, with your
+              secrets hidden where the page shows them as text; a value drawn in an image or a
+              canvas can’t be hidden.
+            </p>
+            {groups === null ? null : groups.every((g) => g.secrets.length === 0) ? (
+              <p className="dialog-empty">No secrets yet.</p>
+            ) : (
+              groups.map((group) =>
+                group.secrets.length === 0 ? null : (
+                  <section key={group.app} className="secret-group">
+                    {several && (
+                      <h3 className="secret-app">
+                        {group.app} <span className="mono">{group.origin}</span>
+                      </h3>
+                    )}
+                    <ul
+                      className="secret-list"
+                      aria-label={several ? `Secrets of ${group.app}` : "The project's secrets"}
+                    >
+                      {group.secrets.map((s) => (
+                        <li key={s.name}>
+                          <Key size={15} />
+                          <span className="mono secret-name">{s.name}</span>
+                          <span className="secret-kind">
+                            {KINDS.find((k) => k.kind === s.kind)?.label}
+                          </span>
+                          {!s.provided && <span className="secret-missing">no value here</span>}
+                          <div className="spacer" />
+                          {removing === `${group.app}/${s.name}` ? (
+                            <>
+                              <button
+                                type="button"
+                                className="btn btn-ghost"
+                                onClick={() => setRemoving(null)}
+                              >
+                                Keep
+                              </button>
+                              <button
+                                type="button"
+                                className="btn btn-danger"
+                                onClick={() => void remove(group.app, s.name)}
+                              >
+                                Remove {s.name}
+                              </button>
+                            </>
+                          ) : (
+                            <button
+                              type="button"
+                              className="icon-btn"
+                              aria-label={`Remove ${s.name}`}
+                              onClick={() => setRemoving(`${group.app}/${s.name}`)}
+                            >
+                              <Trash size={15} />
+                            </button>
+                          )}
+                        </li>
+                      ))}
+                    </ul>
+                  </section>
+                ),
+              )
+            )}
+            <form className="secret-form" onSubmit={(e) => void add(e)}>
+              <div className="field">
+                <label htmlFor="secret-name">Name</label>
+                <input
+                  id="secret-name"
+                  ref={first}
+                  className="mono"
+                  placeholder="acme.password"
+                  maxLength={120}
+                  spellCheck={false}
+                  autoComplete="off"
+                  value={name}
+                  onChange={(e) => setName(e.target.value)}
+                />
+                <span className="field-hint">
+                  What scenes call it: {"{{secrets.acme.password}}"}
+                </span>
+              </div>
+              {several && (
+                <div className="field">
+                  <label htmlFor="secret-app">App</label>
+                  <select id="secret-app" value={app} onChange={(e) => setApp(e.target.value)}>
+                    {apps.map((a) => (
+                      <option key={a.name} value={a.name}>
+                        {a.name} ({a.origin})
+                      </option>
+                    ))}
+                  </select>
+                  <span className="field-hint">Typed on that app only.</span>
+                </div>
+              )}
+              <div className="field">
+                <label htmlFor="secret-kind">Kind</label>
+                <select
+                  id="secret-kind"
+                  value={kind}
+                  onChange={(e) => setKind(e.target.value as SecretView["kind"])}
                 >
-                  {group.secrets.map((s) => (
-                    <li key={s.name}>
-                      <Key size={15} />
-                      <span className="mono secret-name">{s.name}</span>
-                      <span className="secret-kind">
-                        {KINDS.find((k) => k.kind === s.kind)?.label}
-                      </span>
-                      {!s.provided && <span className="secret-missing">no value here</span>}
-                      <div className="spacer" />
-                      {removing === `${group.app}/${s.name}` ? (
-                        <>
-                          <button
-                            type="button"
-                            className="btn btn-ghost"
-                            onClick={() => setRemoving(null)}
-                          >
-                            Keep
-                          </button>
-                          <button
-                            type="button"
-                            className="btn btn-danger"
-                            onClick={() => void remove(group.app, s.name)}
-                          >
-                            Remove {s.name}
-                          </button>
-                        </>
-                      ) : (
-                        <button
-                          type="button"
-                          className="icon-btn"
-                          aria-label={`Remove ${s.name}`}
-                          onClick={() => setRemoving(`${group.app}/${s.name}`)}
-                        >
-                          <Trash size={15} />
-                        </button>
-                      )}
-                    </li>
+                  {KINDS.map((k) => (
+                    <option key={k.kind} value={k.kind}>
+                      {k.label}
+                    </option>
                   ))}
-                </ul>
-              </section>
-            ),
-          )
+                </select>
+              </div>
+              <div className="field">
+                <label htmlFor="secret-value">Value</label>
+                <input
+                  id="secret-value"
+                  type="password"
+                  maxLength={4096}
+                  autoComplete="off"
+                  value={value}
+                  onChange={(e) => setValue(e.target.value)}
+                />
+              </div>
+              {error !== null && (
+                <div className="error" role="alert">
+                  <WarningCircle size={16} weight="fill" />
+                  <span>{error}</span>
+                </div>
+              )}
+              <div className="setup-actions">
+                <button
+                  type="submit"
+                  className="btn btn-primary"
+                  disabled={busy || name.trim() === "" || value === ""}
+                >
+                  {busy ? "Saving…" : "Add secret"}
+                </button>
+              </div>
+            </form>
+          </>
         )}
-        <form className="secret-form" onSubmit={(e) => void add(e)}>
-          <div className="field">
-            <label htmlFor="secret-name">Name</label>
-            <input
-              id="secret-name"
-              ref={first}
-              className="mono"
-              placeholder="acme.password"
-              maxLength={120}
-              spellCheck={false}
-              autoComplete="off"
-              value={name}
-              onChange={(e) => setName(e.target.value)}
-            />
-            <span className="field-hint">What scenes call it: {"{{secrets.acme.password}}"}</span>
-          </div>
-          {several && (
-            <div className="field">
-              <label htmlFor="secret-app">App</label>
-              <select id="secret-app" value={app} onChange={(e) => setApp(e.target.value)}>
-                {apps.map((a) => (
-                  <option key={a.name} value={a.name}>
-                    {a.name} ({a.origin})
-                  </option>
-                ))}
-              </select>
-              <span className="field-hint">Typed on that app only.</span>
-            </div>
-          )}
-          <div className="field">
-            <label htmlFor="secret-kind">Kind</label>
-            <select
-              id="secret-kind"
-              value={kind}
-              onChange={(e) => setKind(e.target.value as SecretView["kind"])}
-            >
-              {KINDS.map((k) => (
-                <option key={k.kind} value={k.kind}>
-                  {k.label}
-                </option>
-              ))}
-            </select>
-          </div>
-          <div className="field">
-            <label htmlFor="secret-value">Value</label>
-            <input
-              id="secret-value"
-              type="password"
-              maxLength={4096}
-              autoComplete="off"
-              value={value}
-              onChange={(e) => setValue(e.target.value)}
-            />
-          </div>
-          {error !== null && (
-            <div className="error" role="alert">
-              <WarningCircle size={16} weight="fill" />
-              <span>{error}</span>
-            </div>
-          )}
-          <div className="setup-actions">
-            <button
-              type="submit"
-              className="btn btn-primary"
-              disabled={busy || name.trim() === "" || value === ""}
-            >
-              {busy ? "Saving…" : "Add secret"}
-            </button>
-          </div>
-        </form>
       </div>
     </div>
   )
diff --git a/apps/desktop/src/renderer/src/components/stage.tsx b/apps/desktop/src/renderer/src/components/stage.tsx
index 0b0ae05..be37dd3 100644
--- a/apps/desktop/src/renderer/src/components/stage.tsx
+++ b/apps/desktop/src/renderer/src/components/stage.tsx
@@ -7,6 +7,7 @@ import { useChat } from "../chat-store.ts"
 import { LiveControl } from "./live-control.tsx"
 import { PreviewPlayer } from "./preview-player.tsx"
 import { SceneStrip } from "./scene-strip.tsx"
+import { appLabel } from "../../../shared/util.ts"
 
 type Tab = "preview" | "live"
 
@@ -126,7 +127,7 @@ export function Stage({ project }: { project: ProjectView }) {
             ) : (
               <>
                 <h2>Kif’s browser</h2>
-                <p>While Kif works on {project.url}, you watch it here.</p>
+                <p>While Kif works on {liveLabel(project.apps)}, you watch it here.</p>
               </>
             )}
           </>
@@ -164,3 +165,9 @@ function TabButton(props: {
     </button>
   )
 }
+
+/** What the live tab says Kif's browser works on: the first web app (the page it opens). */
+function liveLabel(apps: ProjectView["apps"]): string {
+  const app = apps.find((a) => a.kind === "web") ?? apps[0]
+  return app === undefined ? "the app" : appLabel(app)
+}
diff --git a/apps/desktop/src/renderer/src/components/title-bar.tsx b/apps/desktop/src/renderer/src/components/title-bar.tsx
index a93d7be..10771db 100644
--- a/apps/desktop/src/renderer/src/components/title-bar.tsx
+++ b/apps/desktop/src/renderer/src/components/title-bar.tsx
@@ -1,11 +1,12 @@
 // The window's top: the wordmark, the project menu, the app it films.
-import { CaretDown, Export, FolderSimple, Globe, Key } from "@phosphor-icons/react"
+import { CaretDown, Export, FolderSimple, AppWindow, Globe, Key } from "@phosphor-icons/react"
 import { useCallback, useEffect, useState } from "react"
-import type { ProjectView } from "../../../shared/ipc.ts"
+import { appViewIdentity, type ProjectView } from "../../../shared/ipc.ts"
 import { api } from "../api.ts"
 import { useApp } from "../store.ts"
 import { AppsPanel } from "./apps-panel.tsx"
 import { SecretsPanel } from "./secrets-panel.tsx"
+import { appLabel } from "../../../shared/util.ts"
 
 export function TitleBar() {
   const status = useApp((s) => s.status)
@@ -39,7 +40,7 @@ export function TitleBar() {
 }
 
 /** The first app's host, as a button opening the apps panel (with how many more there are). */
-function AppsButton({ project }: { project: Pick<ProjectView, "session" | "apps" | "url"> }) {
+function AppsButton({ project }: { project: Pick<ProjectView, "session" | "apps"> }) {
   const [open, setOpen] = useState(false)
   const close = useCallback(() => setOpen(false), [])
   const more = project.apps.length - 1
@@ -48,11 +49,11 @@ function AppsButton({ project }: { project: Pick<ProjectView, "session" | "apps"
       <button
         type="button"
         className="chip chip-button"
-        title={project.apps.map((a) => `${a.name}: ${a.origin}`).join("\n")}
+        title={project.apps.map((a) => `${a.name}: ${appViewIdentity(a)}`).join("\n")}
         onClick={() => setOpen(true)}
       >
-        <Globe size={13} />
-        {hostOf(project.url)}
+        {project.apps[0]?.kind === "electron" ? <AppWindow size={13} /> : <Globe size={13} />}
+        {project.apps[0] === undefined ? "" : appLabel(project.apps[0])}
         {more > 0 && <span className="chip-more">+{more}</span>}
       </button>
       {open && <AppsPanel project={project} onClose={close} />}
@@ -132,11 +133,3 @@ function ProjectMenu({ name }: { name: string }) {
     </div>
   )
 }
-
-function hostOf(url: string): string {
-  try {
-    return new URL(url).host
-  } catch {
-    return url
-  }
-}
diff --git a/apps/desktop/src/renderer/test/app.test.tsx b/apps/desktop/src/renderer/test/app.test.tsx
index 967bb92..b2b364f 100644
--- a/apps/desktop/src/renderer/test/app.test.tsx
+++ b/apps/desktop/src/renderer/test/app.test.tsx
@@ -10,8 +10,7 @@ const project: ProjectView = {
   session: "s1",
   name: "Acme Billing demo",
   dir: "/tmp/demo.kiframe",
-  url: "https://app.acme.example",
-  apps: [{ name: "app", origin: "https://app.acme.example" }],
+  apps: [{ name: "app", kind: "web", origin: "https://app.acme.example" }],
   scenes: [
     { id: "intro", title: "Intro", status: "card" },
     {
diff --git a/apps/desktop/src/renderer/test/apps.test.tsx b/apps/desktop/src/renderer/test/apps.test.tsx
index ec70118..ccca81e 100644
--- a/apps/desktop/src/renderer/test/apps.test.tsx
+++ b/apps/desktop/src/renderer/test/apps.test.tsx
@@ -12,10 +12,9 @@ const project: ProjectView = {
   session: "s1",
   name: "Demo",
   dir: "/tmp/demo.kiframe",
-  url: "https://app.test/",
   apps: [
-    { name: "app", origin: "https://app.test" },
-    { name: "docs", origin: "https://docs.test" },
+    { name: "app", kind: "web", origin: "https://app.test" },
+    { name: "docs", kind: "web", origin: "https://docs.test" },
   ],
   scenes: [
     { id: "install", title: "Install", status: "recorded", take: "k1", removedApps: ["auth"] },
@@ -50,7 +49,7 @@ describe("the project's apps", () => {
     expect(invoke).toHaveBeenCalledWith("apps:remove", {
       session: "s1",
       name: "docs",
-      origin: "https://docs.test",
+      identity: "https://docs.test",
     })
   })
 
diff --git a/apps/desktop/src/renderer/test/chat.test.tsx b/apps/desktop/src/renderer/test/chat.test.tsx
index 3cba761..45143ca 100644
--- a/apps/desktop/src/renderer/test/chat.test.tsx
+++ b/apps/desktop/src/renderer/test/chat.test.tsx
@@ -12,8 +12,7 @@ const project: ProjectView = {
   session: "s1",
   name: "Demo",
   dir: "/tmp/demo.kiframe",
-  url: "https://app.test",
-  apps: [{ name: "app", origin: "https://app.test" }],
+  apps: [{ name: "app", kind: "web", origin: "https://app.test" }],
   scenes: [],
   problems: [],
 }
diff --git a/apps/desktop/src/renderer/test/handover.test.tsx b/apps/desktop/src/renderer/test/handover.test.tsx
index 693905c..61f0fb4 100644
--- a/apps/desktop/src/renderer/test/handover.test.tsx
+++ b/apps/desktop/src/renderer/test/handover.test.tsx
@@ -15,8 +15,7 @@ const project: ProjectView = {
   session: "s1",
   name: "Demo",
   dir: "/tmp/demo.kiframe",
-  url: "https://app.test",
-  apps: [{ name: "app", origin: "https://app.test" }],
+  apps: [{ name: "app", kind: "web", origin: "https://app.test" }],
   scenes: [],
   problems: [],
 }
diff --git a/apps/desktop/src/renderer/test/preview.test.tsx b/apps/desktop/src/renderer/test/preview.test.tsx
index 7938ca8..6604a74 100644
--- a/apps/desktop/src/renderer/test/preview.test.tsx
+++ b/apps/desktop/src/renderer/test/preview.test.tsx
@@ -173,8 +173,7 @@ describe("the preview", () => {
       session: "s1",
       name: "Demo",
       dir: "/tmp/demo",
-      url: "https://app.example",
-      apps: [{ name: "app", origin: "https://app.example" }],
+      apps: [{ name: "app", kind: "web", origin: "https://app.example" }],
       problems: [],
       scenes: [
         { id: "intro", title: "Intro", status: "grounded" },
@@ -215,8 +214,7 @@ describe("the preview", () => {
       session: "s1",
       name: "Demo",
       dir: "/tmp/demo",
-      url: "https://app.example",
-      apps: [{ name: "app", origin: "https://app.example" }],
+      apps: [{ name: "app", kind: "web", origin: "https://app.example" }],
       problems: [],
       scenes: [
         { id: "intro", title: "Intro", status: "recorded", take: "k0" },
diff --git a/apps/desktop/src/renderer/test/secrets.test.tsx b/apps/desktop/src/renderer/test/secrets.test.tsx
index 5722590..1f57ef8 100644
--- a/apps/desktop/src/renderer/test/secrets.test.tsx
+++ b/apps/desktop/src/renderer/test/secrets.test.tsx
@@ -11,8 +11,7 @@ const project: ProjectView = {
   session: "s1",
   name: "Demo",
   dir: "/tmp/demo.kiframe",
-  url: "https://app.test/home",
-  apps: [{ name: "app", origin: "https://app.test" }],
+  apps: [{ name: "app", kind: "web", origin: "https://app.test" }],
   scenes: [],
   problems: [],
 }
@@ -140,8 +139,8 @@ describe("the secrets panel", () => {
     const two: ProjectView = {
       ...project,
       apps: [
-        { name: "app", origin: "https://app.test" },
-        { name: "docs", origin: "https://docs.test" },
+        { name: "app", kind: "web", origin: "https://app.test" },
+        { name: "docs", kind: "web", origin: "https://docs.test" },
       ],
     }
     const { invoke } = stubApi({
@@ -192,6 +191,42 @@ describe("the secrets panel", () => {
     expect(within(panel).queryByLabelText("App")).toBeNull()
   })
 
+  it("never offers a desktop app (it takes no secrets): the web app alone, no app asked", async () => {
+    const withDesk: ProjectView = {
+      ...project,
+      apps: [
+        { name: "notes", kind: "electron", bundleId: "com.example.notes" },
+        { name: "app", kind: "web", origin: "https://app.test" },
+      ],
+    }
+    stubApi({
+      "app:status": () => status({ hasKey: true, project: withDesk }),
+      "secrets:list": () => [],
+    })
+    render(<App />)
+    fireEvent.click(await screen.findByRole("button", { name: "Secrets" }))
+    const panel = screen.getByRole("dialog", { name: "Secrets" })
+    expect(within(panel).queryByLabelText("App")).toBeNull()
+    expect(panel.textContent).toMatch(/https:\/\/app\.test/)
+    expect(panel.textContent).not.toMatch(/com\.example\.notes/)
+  })
+
+  it("says no app takes secrets when the project has only desktop apps (no form)", async () => {
+    const deskOnly: ProjectView = {
+      ...project,
+      apps: [{ name: "notes", kind: "electron", bundleId: "com.example.notes" }],
+    }
+    stubApi({
+      "app:status": () => status({ hasKey: true, project: deskOnly }),
+      "secrets:list": () => [],
+    })
+    render(<App />)
+    fireEvent.click(await screen.findByRole("button", { name: "Secrets" }))
+    const panel = screen.getByRole("dialog", { name: "Secrets" })
+    expect(panel.textContent).toMatch(/None of this project’s apps takes secrets/)
+    expect(within(panel).queryByRole("button", { name: "Add secret" })).toBeNull()
+  })
+
   it("never moves focus while a value is typed (a status update re-renders the window)", async () => {
     const { push } = stubApi({
       "app:status": () => status({ hasKey: true, project }),
diff --git a/apps/desktop/src/shared/ipc.ts b/apps/desktop/src/shared/ipc.ts
index a925f84..83180a7 100644
--- a/apps/desktop/src/shared/ipc.ts
+++ b/apps/desktop/src/shared/ipc.ts
@@ -44,6 +44,19 @@ export interface AttachedFile {
 /** An app's name as the project writes it (`AppName`'s form; main looks it up in the project). */
 const AppName = z.string().regex(/^[a-z][a-z0-9_-]{0,39}$/)
 
+/**
+ * An app of the project as the window shows it: a web app by its exact origin (main's: never derived
+ * here), a desktop app by its bundle id.
+ */
+export type AppView =
+  | { name: string; kind: "web"; origin: string }
+  | { name: string; kind: "electron"; bundleId: string }
+
+/** What an app is, as one string (its exact origin, or its bundle id): an app removed is that one. */
+export function appViewIdentity(app: AppView): string {
+  return app.kind === "web" ? app.origin : app.bundleId
+}
+
 /** A scene as the window shows it (the scene strip). */
 export interface SceneView {
   id: string
@@ -74,10 +87,8 @@ export interface ProjectView {
   name: string
   /** The folder (shown in the title bar's menu; never sent back by the window to open it). */
   dir: string
-  /** The app its scenes start in (the project's first). */
-  url: string
   /** Every app of the project, in order, with its exact origin (main's: never derived here). */
-  apps: { name: string; origin: string }[]
+  apps: AppView[]
   scenes: SceneView[]
   /** Parts that didn't read (shown, never hidden). */
   problems: string[]
@@ -382,7 +393,7 @@ export const invokeArgs = {
    * the origin the window shows (refused when the project's app by that name is another now).
    */
   "apps:remove": z.tuple([
-    z.strictObject({ session: z.string().max(64), name: AppName, origin: z.string().max(2048) }),
+    z.strictObject({ session: z.string().max(64), name: AppName, identity: z.string().max(2048) }),
   ]),
   /** A scene of the open project, to play (its id, checked against the project in main). */
   "preview:open": z.tuple([z.string().min(1).max(200)]),
diff --git a/apps/desktop/src/shared/util.ts b/apps/desktop/src/shared/util.ts
index a591860..d9e8da4 100644
--- a/apps/desktop/src/shared/util.ts
+++ b/apps/desktop/src/shared/util.ts
@@ -11,3 +11,15 @@ export function upsert<T extends { id: string }>(items: readonly T[], item: T):
   next[at] = item
   return next
 }
+
+/** An app as the window names it: a web app by its host, a desktop app by its bundle id. */
+export function appLabel(
+  app: { kind: "web"; origin: string } | { kind: "electron"; bundleId: string },
+): string {
+  if (app.kind !== "web") return app.bundleId
+  try {
+    return new URL(app.origin).host
+  } catch {
+    return app.origin
+  }
+}
diff --git a/apps/desktop/test/project.test.ts b/apps/desktop/test/project.test.ts
index 3b850ea..f04dce0 100644
--- a/apps/desktop/test/project.test.ts
+++ b/apps/desktop/test/project.test.ts
@@ -4,7 +4,10 @@ import { join } from "node:path"
 import { createProject, openProject, saveScene } from "@kiframe/project"
 import { parseScenarioYaml } from "@kiframe/schema"
 import { describe, expect, it } from "vitest"
+import { appLabel } from "../src/shared/util.ts"
 import {
+  appView,
+  secretOriginOf,
   appOriginOf,
   appRemovalRefused,
   interruptsUsing,
@@ -42,7 +45,6 @@ describe("the open project", () => {
     })
     expect(projectView(project, "s1")).toMatchObject({
       name: "Demo",
-      url: "https://app.test",
       scenes: [
         { id: "empty", status: "empty" },
         { id: "grounded", status: "grounded" },
@@ -130,13 +132,17 @@ describe("a request of the window for one of the project's apps", () => {
   const view = {
     session: "s1",
     apps: [
-      { name: "app", origin: "https://app.test" },
-      { name: "docs", origin: "https://docs.test" },
+      { name: "app", kind: "web" as const, origin: "https://app.test" },
+      { name: "docs", kind: "web" as const, origin: "https://docs.test" },
     ],
   }
 
   it("gives the app's exact origin, found by its name in the project (never the window's)", () => {
-    expect(appOriginOf(view, "s1", "docs")).toEqual({ name: "docs", origin: "https://docs.test" })
+    expect(appOriginOf(view, "s1", "docs")).toEqual({
+      name: "docs",
+      kind: "web",
+      origin: "https://docs.test",
+    })
   })
 
   it("refuses an app the project doesn't list, a request from another opening, or no project", () => {
@@ -156,7 +162,7 @@ describe("a request of the window for one of the project's apps", () => {
       url: "https://www.app.test/home",
     })
     expect(projectView(project, "s1").apps).toEqual([
-      { name: "app", origin: "https://www.app.test" },
+      { name: "app", kind: "web" as const, origin: "https://www.app.test" },
     ])
   })
 })
@@ -242,19 +248,60 @@ describe("removing one of the project's apps (B5)", () => {
     const view = {
       session: "s1",
       apps: [
-        { name: "app", origin: "https://app.test" },
-        { name: "docs", origin: "https://docs.test" },
+        { name: "app", kind: "web" as const, origin: "https://app.test" },
+        { name: "docs", kind: "web" as const, origin: "https://docs.test" },
       ],
     }
-    const docs = { session: "s1", name: "docs", origin: "https://docs.test" }
+    const docs = { session: "s1", name: "docs", identity: "https://docs.test" }
     expect(appRemovalRefused(view, docs, false)).toBeNull()
     expect(appRemovalRefused(view, docs, true)).toMatch(/Kif is working/)
     expect(appRemovalRefused(view, { ...docs, session: "s0" }, false)).toMatch(/project changed/)
-    expect(appRemovalRefused(view, { ...docs, origin: "https://other.test" }, false)).toMatch(
+    expect(appRemovalRefused(view, { ...docs, identity: "https://other.test" }, false)).toMatch(
       /changed meanwhile/,
     )
     expect(
-      appRemovalRefused(view, { session: "s1", name: "app", origin: "https://app.test" }, false),
+      appRemovalRefused(view, { session: "s1", name: "app", identity: "https://app.test" }, false),
     ).toMatch(/where scenes start/)
   })
 })
+
+describe("a desktop app in the window's view (design 2026-10-08)", () => {
+  it("is shown by its kind and bundle id (no address: never parsed as a URL)", () => {
+    const viewport = { width: 1440, height: 900, deviceScaleFactor: 2 }
+    expect(appView("notes", { kind: "electron", bundleId: "com.example.notes", viewport })).toEqual(
+      {
+        name: "notes",
+        kind: "electron",
+        bundleId: "com.example.notes",
+      },
+    )
+    expect(appView("app", { kind: "web", url: "https://app.test/dashboard", viewport })).toEqual({
+      name: "app",
+      kind: "web",
+      origin: "https://app.test",
+    })
+  })
+})
+
+describe("a desktop app takes no secrets (design 2026-10-08)", () => {
+  const view = {
+    session: "s1",
+    apps: [
+      { name: "app", kind: "web" as const, origin: "https://app.test" },
+      { name: "notes", kind: "electron" as const, bundleId: "com.example.notes" },
+    ],
+  }
+  it("refuses one for it, said why; a web app's origin as before", () => {
+    expect(secretOriginOf(view, "s1", "notes")).toEqual({
+      why: '"notes" is a desktop app: it takes no secrets (sign in by hand when Kif asks)',
+    })
+    expect(secretOriginOf(view, "s1", "app")).toEqual({ origin: "https://app.test" })
+  })
+
+  it("shows it by its bundle id, a web app by its host", () => {
+    expect(appLabel({ kind: "electron" as const, bundleId: "com.example.notes" })).toBe(
+      "com.example.notes",
+    )
+    expect(appLabel({ kind: "web" as const, origin: "https://app.test" })).toBe("app.test")
+  })
+})
diff --git a/docs/OBJECT-MODEL.md b/docs/OBJECT-MODEL.md
index 3a6b005..2c7c526 100644
--- a/docs/OBJECT-MODEL.md
+++ b/docs/OBJECT-MODEL.md
@@ -223,6 +223,13 @@ One scene, three phases. The agent's own instructions say the same (`packages/st
 
 **Desktop apps.** The same `apps` entry with `kind: electron` (launched and attached over its debugging port: `--remote-debugging-port` + `connectOverCDP`, measured working on a hardened packaged app in Phase 0, F4) or `kind: tauri` (WebKit on macOS: no CDP, partial support, APPROACHES §6b). The format is ready for them; driving them is v0.1 work.
 
+**Electron apps (designed 2026-10-08, design reviewed; moved into v0).** `{ kind: "electron", bundleId, args?, origins?, viewport }`:
+- **Named by bundle id, never a path or a program** (a project may come from someone else): the desktop app finds the bundle on each machine and keeps the user's approval in its own settings (bundle id, real path, signing team); only `.app` bundles holding `Electron Framework.framework`; App Store (sandboxed) apps refused. `args` are positional only (no switches). `origins`: the https sites a wrapper app (Slack, Notion) shows as its own.
+- **No address**: a goto or a URL condition on it is refused; a scene starting in it opens on its first window; it takes no secrets in v0 (the user signs in by hand: the handover).
+- **Each run launches it sandboxed** (its own HOME, `CFFIXED_USER_HOME`, XDG and temp folders, `--user-data-dir`; an allowlisted environment, never Kiframe's), attached with `--remote-debugging-port=0` + `connectOverCDP`; the viewport is emulated (a spike measured frames and clicks with the window covered, off-screen, minimized or hidden: a run never needs the user's screen; the window itself can't be moved over CDP). Isolation is verified when the app is added: after a trial launch its state must be inside the sandbox, else refused. Its process group killed after each run, leftovers swept.
+- **Stated limits:** native dialogs and menus are unreachable; links open in the user's real browser; a sign-in through the browser with an app-scheme callback isn't supported in v0; the keychain is the user's (an app reading its own item signs in as them); a window built from several views films one view.
+- **Built in steps** (epic `epic/electron-targets`): the format (2026-10-08), the launcher and target, the desktop approval and trial, the studio and batch on it, a real pass on a sandboxed minmux.
+
 **Existing projects convert** on open: `target` becomes `apps.app` (the rest unchanged).
 
 **Settled with the user (2026-10-05):**
diff --git a/packages/project/test/project.test.ts b/packages/project/test/project.test.ts
index 451d9b9..9874b77 100644
--- a/packages/project/test/project.test.ts
+++ b/packages/project/test/project.test.ts
@@ -70,7 +70,7 @@ describe("project store", () => {
     })
     writeFileSync(join(dir, "project.json"), v1)
     const opened = openProject(dir)
-    expect(opened.project.apps.app?.url).toBe("https://www.app.test")
+    expect(opened.project.apps.app).toMatchObject({ url: "https://www.app.test" })
     expect(opened.project.apps.app?.viewport.width).toBe(1280)
     // Opening never rewrites it.
     expect(readFileSync(join(dir, "project.json"), "utf8")).toBe(v1)
diff --git a/packages/runtime/src/recorder.ts b/packages/runtime/src/recorder.ts
index eda0331..d806d79 100644
--- a/packages/runtime/src/recorder.ts
+++ b/packages/runtime/src/recorder.ts
@@ -12,6 +12,7 @@ import {
 import { writeFile } from "node:fs/promises"
 import { basename, dirname, join, resolve } from "node:path"
 import {
+  appIdentity,
   CursorSample,
   startAppOf,
   TakeEvent,
@@ -465,10 +466,10 @@ export async function recordScenario(
       const start = startAppOf(scenario, project)
       meta = TakeMeta.parse({
         version: 1,
-        takeKey: `${sha256(`${scenarioHash}|${start.app.url}|${JSON.stringify(start.app.viewport)}|q${options.quality ?? 85}`).slice(0, 16)}-${recordedAt.getTime()}`,
+        takeKey: `${sha256(`${scenarioHash}|${appIdentity(start.app)}|${JSON.stringify(start.app.viewport)}|q${options.quality ?? 85}`).slice(0, 16)}-${recordedAt.getTime()}`,
         scenarioHash,
         recordedAt: recordedAt.toISOString(),
-        appUrl: start.app.url,
+        appUrl: appIdentity(start.app),
         app: start.name,
         // The capture scale actually obtained (Phase 0 finding F1: screencast frames are at CSS size).
         viewport: {
diff --git a/packages/runtime/src/run/actions.ts b/packages/runtime/src/run/actions.ts
index d2f656d..7145a4f 100644
--- a/packages/runtime/src/run/actions.ts
+++ b/packages/runtime/src/run/actions.ts
@@ -20,7 +20,7 @@ import {
   toPlaywright,
   viewportOf,
 } from "../targets.ts"
-import { appNamed } from "./apps.ts"
+import { webAppNamed } from "./apps.ts"
 import { waitForCondition } from "./conditions.ts"
 import {
   type AnyAction,
@@ -66,7 +66,7 @@ export async function perform(ctx: Ctx, action: AnyAction, step: StepRef): Promi
   switch (action.action) {
     case "goto": {
       // The app it names, else the one its step means (its scene's or its preset's).
-      const base = new URL(appNamed(ctx.apps, action.app ?? ctx.app, step).url)
+      const base = new URL(webAppNamed(ctx.apps, action.app ?? ctx.app, step, "a goto").url)
       const url = new URL(action.url, base)
       // Enforced here too (not only by the schema): a goto never leaves its app.
       if (url.origin !== base.origin) {
diff --git a/packages/runtime/src/run/apps.ts b/packages/runtime/src/run/apps.ts
index aa57cd0..144939d 100644
--- a/packages/runtime/src/run/apps.ts
+++ b/packages/runtime/src/run/apps.ts
@@ -1,4 +1,4 @@
-import { type App, type Apps, appOf, sameApp } from "@kiframe/schema"
+import { type App, type Apps, appOf, sameApp, type WebApp, webAppsOf } from "@kiframe/schema"
 import type { Ctx } from "./context.ts"
 import { StepError, type StepRef } from "../errors.ts"
 
@@ -17,12 +17,28 @@ export function appNamed(apps: Apps, name: string, step: StepRef): App {
   return app
 }
 
+/**
+ * A web app by its name, for what needs an address (a goto, a URL condition): a desktop app has
+ * none (it starts where it opens: steps move in it by clicking), refused saying so.
+ */
+export function webAppNamed(apps: Apps, name: string, step: StepRef, what: string): WebApp {
+  const app = appNamed(apps, name, step)
+  if (app.kind !== "web") {
+    throw new StepError(
+      step,
+      "invalid-setup",
+      `${what} needs a web app: "${name}" is a desktop app (it opens on its own window: move in it by clicking)`,
+    )
+  }
+  return app
+}
+
 /** The listed app whose exact origin `url` (a URL, or an origin) is on (its name), if any. */
 export function appAtOrigin(apps: Apps, url: string): string | undefined {
   // An opaque origin ("null": about:blank, data:, a sandboxed page) is no app's.
   const origin = URL.parse(url)?.origin
   if (origin === undefined || origin === "null") return undefined
-  return Object.entries(apps).find(([, app]) => new URL(app.url).origin === origin)?.[0]
+  return Object.entries(webAppsOf(apps)).find(([, app]) => new URL(app.url).origin === origin)?.[0]
 }
 
 /** How long a page off the apps may take to come back (a redirect still in flight: an SSO bounce). */
@@ -32,7 +48,7 @@ const BACK_MS = 2500
 export function onApps(apps: Apps, url: string): boolean {
   const parsed = URL.parse(url)
   if (parsed === null || !["http:", "https:", "blob:"].includes(parsed.protocol)) return false
-  return Object.values(apps).some((app) => sameApp(parsed, app.url))
+  return Object.values(webAppsOf(apps)).some((app) => sameApp(parsed, app.url))
 }
 
 /**
diff --git a/packages/runtime/src/run/conditions.ts b/packages/runtime/src/run/conditions.ts
index 13267d6..b5d82c8 100644
--- a/packages/runtime/src/run/conditions.ts
+++ b/packages/runtime/src/run/conditions.ts
@@ -4,7 +4,7 @@ import { EXACT_NAMES_HINT, ProbeRefusal } from "../secret-state.ts"
 import type { Locator as SchemaLocator } from "@kiframe/schema"
 import type { Page } from "playwright"
 import { countUnderRule, describeLocator, documentOf } from "../targets.ts"
-import { appNamed } from "./apps.ts"
+import { webAppNamed } from "./apps.ts"
 import { type Ctx, firstLine } from "./context.ts"
 
 // Conditions for `waitFor` / `expect`, and URL matching.
@@ -49,7 +49,7 @@ export async function waitForCondition(
       })
     } else if ("url" in condition) {
       // Relative to the app it names, else the one its step means.
-      const app = appNamed(ctx.apps, condition.app ?? ctx.app, step)
+      const app = webAppNamed(ctx.apps, condition.app ?? ctx.app, step, "a URL condition")
       const expected = new URL(condition.url, app.url)
       await page.waitForURL((url) => urlMatches(url, expected), { timeout })
     } else if (!(await ctx.network.waitForIdle(timeout))) {
diff --git a/packages/runtime/src/run/setup.ts b/packages/runtime/src/run/setup.ts
index 5b3a4b2..fc381a1 100644
--- a/packages/runtime/src/run/setup.ts
+++ b/packages/runtime/src/run/setup.ts
@@ -83,6 +83,13 @@ export function expandSetup(
         : undefined
       if (preset === undefined) throw invalid(`unknown preset "${item.preset}"`)
       const from = { name: item.preset, session: preset.session }
+      // Its steps run in its app (the first by default): a desktop app has its own driver (next).
+      const runsIn = preset.app ?? firstApp(project).name
+      if (appOf(project, runsIn)?.kind !== "web") {
+        throw invalid(
+          `preset "${item.preset}" runs in "${runsIn}", a desktop app: Kiframe can't run steps in desktop apps yet (give the preset a web app: \`app:\`)`,
+        )
+      }
       if (preset.session && skip.includes(item.preset)) {
         // Its state is kept, not its page: back where it ended (a setup may rely on that page),
         // then its own last checks, which say the session still holds (else: expired).
@@ -101,7 +108,7 @@ export function expandSetup(
             probe: true,
           })
           // The checks under the landing's index: a setup's indexes stay those of the file.
-          const own = preset.app ?? firstApp(project).name
+          const own = runsIn
           for (const check of sessionChecks(preset.steps)) {
             out.push({
               kind: "action",
@@ -117,7 +124,7 @@ export function expandSetup(
         }
         continue
       }
-      const own = preset.app ?? firstApp(project).name
+      const own = runsIn
       for (const s of preset.steps) {
         if ("ensure" in s) n++
         else out.push({ kind: "action", index: n++, action: s, app: own, preset: from })
@@ -146,7 +153,8 @@ export function openingGoto(
   const first = setup.find((e) => e.kind === "action")?.action ?? steps[0]
   if (first?.action === "goto") return undefined
   const app = appOf(project, start)
-  if (app === undefined) return undefined
+  // A desktop app opens on its own window: nothing to go to.
+  if (app === undefined || app.kind !== "web") return undefined
   const url = new URL(app.url)
   const goto = Action.safeParse({ action: "goto", url: `${url.pathname}${url.search}` })
   return goto.success ? goto.data : undefined
diff --git a/packages/runtime/src/runner.ts b/packages/runtime/src/runner.ts
index f05a13d..02e7f54 100644
--- a/packages/runtime/src/runner.ts
+++ b/packages/runtime/src/runner.ts
@@ -48,7 +48,16 @@ export async function runScenario(
     )
   }
   // The scene's start app: what its steps mean when they name no app.
-  const start = startAppOf(scenario, project).name
+  const started = startAppOf(scenario, project)
+  // A desktop app is launched by its own driver (the Electron target, next): never run on a page.
+  if (started.app.kind !== "web") {
+    throw new StepError(
+      { phase: "setup", index: 0, action: "setup" },
+      "invalid-setup",
+      `app "${started.name}" is a desktop app: Kiframe can't run scenes in desktop apps yet`,
+    )
+  }
+  const start = started.name
   const setup = expandSetup(
     scenario.setup ?? [],
     project,
diff --git a/packages/runtime/test/apps.test.ts b/packages/runtime/test/apps.test.ts
index 57bd8a1..b50a20e 100644
--- a/packages/runtime/test/apps.test.ts
+++ b/packages/runtime/test/apps.test.ts
@@ -506,3 +506,92 @@ steps: [{ id: dead, action: click, target: { by: role, role: link, name: Nowhere
     ])
   })
 })
+
+describe("a desktop app among the project's apps (design 2026-10-08)", () => {
+  const withDesk = () =>
+    parseProjectYaml(`version: 2
+apps:
+  app: { kind: web, url: "${app.origin}", viewport: { width: 800, height: 600 } }
+  notes: { kind: electron, bundleId: com.example.notes }
+defaults: { pacing: { settleMs: 0, cursor: instant, typing: instant } }
+`)
+  const failure = async (yaml: string) => {
+    try {
+      await runScenario(page, parseScenarioYaml(`version: 1\n${yaml}`), withDesk(), {
+        timeoutMs: 1000,
+        fresh: true,
+      })
+    } catch (error) {
+      if (error instanceof StepError) return error
+      throw error
+    }
+    throw new Error("expected a failure")
+  }
+
+  it("refuses a goto or a URL condition on it, saying it has no address", async () => {
+    const goto = await failure(`steps:
+  - { id: a, action: goto, app: notes, url: / }`)
+    expect(goto.reason).toBe("invalid-setup")
+    expect(goto.message).toMatch(/a goto needs a web app: "notes" is a desktop app/)
+    const waits = await failure(`steps:
+  - { id: a, action: waitFor, until: { url: /, app: notes } }`)
+    expect(waits.message).toMatch(/a URL condition needs a web app: "notes" is a desktop app/)
+  })
+
+  it("refuses a scene starting in it (never filmed on a page), and never counts as a page's app", async () => {
+    const started = await failure(`app: notes
+steps: [{ id: a, action: pause, ms: 1 }]`)
+    expect(started.reason).toBe("invalid-setup")
+    expect(started.message).toMatch(
+      /app "notes" is a desktop app: Kiframe can't run scenes in desktop apps yet/,
+    )
+    expect(page.url()).toBe("about:blank")
+    // The web app is still its own (a desktop app never matches a page's address).
+    await runScenario(
+      page,
+      parseScenarioYaml(
+        `version: 1\napp: app\nsteps: [{ id: a, action: expect, that: { url: / } }]\n`,
+      ),
+      withDesk(),
+      { fresh: true },
+    )
+    expect(page.url()).toBe(`${app.origin}/`)
+  })
+
+  it("refuses a preset that would run in it (named, or the first app), said why", async () => {
+    const deskFirst = parseProjectYaml(`version: 2
+apps:
+  notes: { kind: electron, bundleId: com.example.notes }
+  app: { kind: web, url: "${app.origin}", viewport: { width: 800, height: 600 } }
+presets:
+  home: { steps: [{ action: click, target: { by: role, role: link, name: Projects } }] }
+  named: { app: notes, steps: [{ action: pause, ms: 1 }] }
+  web: { app: app, steps: [{ action: goto, url: /projects }] }
+defaults: { pacing: { settleMs: 0, cursor: instant, typing: instant } }
+`)
+    const run = (preset: string) =>
+      runScenario(
+        page,
+        parseScenarioYaml(`version: 1
+app: app
+setup: [{ preset: ${preset} }]
+steps: [{ id: a, action: pause, ms: 1 }]
+`),
+        deskFirst,
+        { fresh: true, timeoutMs: 3000 },
+      )
+    for (const preset of ["home", "named"]) {
+      const error = await run(preset).then(
+        () => undefined,
+        (e: unknown) => e,
+      )
+      expect(error, preset).toBeInstanceOf(StepError)
+      expect((error as StepError).message, preset).toMatch(
+        new RegExp(`preset "${preset}" runs in "notes", a desktop app`),
+      )
+    }
+    // Named to the web app: runs.
+    await run("web")
+    expect(page.url()).toBe(`${app.origin}/projects`)
+  })
+})
diff --git a/packages/schema/src/apps.test.ts b/packages/schema/src/apps.test.ts
index 45e1db3..60e30ab 100644
--- a/packages/schema/src/apps.test.ts
+++ b/packages/schema/src/apps.test.ts
@@ -15,6 +15,9 @@ import {
   Project,
   ProjectConfig,
   SchemaError,
+  appIdentity,
+  urlOf,
+  webAppsOf,
 } from "./index.ts"
 
 // B1 (OBJECT-MODEL §0.9): a project's named apps replace its one target (project v2), and a v1
@@ -102,7 +105,7 @@ describe("a project's apps", () => {
 
   it("finds an app by name, never a key every object has", () => {
     const p = Project.parse(v2({ app: app("https://a.dev") }))
-    expect(appOf(p, "app")?.url).toBe("https://a.dev")
+    expect(appOf(p, "app")).toMatchObject({ url: "https://a.dev" })
     expect(appOf(p, "docs")).toBeUndefined()
     expect(appOf(p, "constructor")).toBeUndefined()
     expect(appOf(p, "__proto__")).toBeUndefined()
@@ -174,7 +177,7 @@ describe("a v1 project, read", () => {
     const config = parseProjectYaml(
       'version: 1\nenvironment: staging\ntarget: { kind: web, url: "https://s.dev", viewport: { width: 1280, height: 800 } }\n',
     )
-    expect(ProjectConfig.parse(config).apps.app?.url).toBe("https://s.dev")
+    expect(ProjectConfig.parse(config).apps.app).toMatchObject({ url: "https://s.dev" })
     expect(firstApp(config).app.viewport.width).toBe(1280)
   })
 })
@@ -261,3 +264,95 @@ teardown:
     expect(() => startAppOf({ app: "nope" }, config)).toThrow(/isn't one of the project's apps/)
   })
 })
+
+describe("a desktop Electron app (design 2026-10-08)", () => {
+  const desk = (extra: object = {}) => ({
+    kind: "electron",
+    bundleId: "com.example.notes",
+    ...extra,
+  })
+  const parse = (apps: object) => Project.safeParse(v2(apps))
+
+  it("is named by its bundle id, beside web apps (the viewport defaulted)", () => {
+    const parsed = parse({ web: app("https://a.dev"), notes: desk({ args: ["~/Demo"] }) })
+    expect(parsed.success).toBe(true)
+    const notes = parsed.data?.apps.notes
+    expect(notes).toEqual({
+      kind: "electron",
+      bundleId: "com.example.notes",
+      args: ["~/Demo"],
+      viewport: { width: 1440, height: 900, deviceScaleFactor: 2 },
+    })
+    expect(appIdentity(notes!)).toBe("electron:com.example.notes")
+    expect(Object.keys(webAppsOf(parsed.data!.apps))).toEqual(["web"])
+    expect(() => urlOf(notes!)).toThrow("a desktop app (com.example.notes) has no address")
+    expect(urlOf(parsed.data!.apps.web!)).toBe("https://a.dev")
+  })
+
+  it("never names a program: no path, no switch, a bundle id's form only", () => {
+    const issue = (apps: object) => {
+      const r = parse(apps)
+      return r.success ? "parsed" : r.error.issues.map((i) => i.message).join("; ")
+    }
+    expect(issue({ x: desk({ path: "/bin/sh" }) })).not.toBe("parsed")
+    expect(issue({ x: desk({ args: ["--inspect=9229"] }) })).toMatch(/positional arguments only/)
+    expect(issue({ x: desk({ args: ["-e"] }) })).toMatch(/positional arguments only/)
+    expect(issue({ x: desk({ bundleId: "/Applications/Notes.app" }) })).toMatch(/a bundle id/)
+    expect(issue({ x: desk({ bundleId: "notes" }) })).toMatch(/a bundle id/)
+    expect(issue({ x: desk({ url: "https://a.dev" }) })).not.toBe("parsed")
+    // Chromium trims an argument before telling a switch: spaces and control characters too.
+    for (const sneaky of [
+      " --user-data-dir=/x",
+      "\t--remote-debugging-address=0.0.0.0",
+      "a\nb",
+      "a ",
+    ]) {
+      expect(issue({ x: desk({ args: [sneaky] }) }), JSON.stringify(sneaky)).toMatch(
+        /positional arguments only/,
+      )
+    }
+    expect(issue({ x: desk({ args: ["~/My Demo"] }) })).toBe("parsed")
+    expect(issue({ x: desk({ bundleId: "1.0" }) })).toMatch(/a bundle id/)
+  })
+
+  it("takes a wrapper app's sites as https origins only", () => {
+    expect(parse({ x: desk({ origins: ["https://app.slack.com"] }) }).success).toBe(true)
+    for (const bad of ["http://app.slack.com", "https://app.slack.com/client", "file:///"]) {
+      expect(parse({ x: desk({ origins: [bad] }) }).success, bad).toBe(false)
+    }
+  })
+
+  it("is listed once per project (its bundle id in any case), its sites never a web app's", () => {
+    const r = parse({ a: desk(), b: desk({ bundleId: "com.Example.Notes" }) })
+    expect(r.success).toBe(false)
+    expect(r.error?.issues[0]?.message).toBe(
+      'apps "a" and "b" are the same desktop app: one app each',
+    )
+    const site = parse({
+      slack: desk({ bundleId: "com.tinyspeck.slackmacgap", origins: ["https://app.slack.com"] }),
+      web: app("https://app.slack.com"),
+    })
+    expect(site.error?.issues[0]?.message).toBe(
+      'apps "slack" and "web" are on the same site: one app per site',
+    )
+    // Either order: the web app listed first too.
+    const webFirst = parse({
+      web: app("https://app.slack.com"),
+      slack: desk({ bundleId: "com.tinyspeck.slackmacgap", origins: ["https://app.slack.com"] }),
+    })
+    expect(webFirst.error?.issues[0]?.message).toBe(
+      'apps "web" and "slack" are on the same site: one app per site',
+    )
+  })
+
+  it("never lets two wrapper apps claim one site (the issue on their origins)", () => {
+    const both = parse({
+      a: desk({ bundleId: "com.a.slack", origins: ["https://app.slack.com"] }),
+      b: desk({ bundleId: "com.b.slack", origins: ["https://app.slack.com"] }),
+    })
+    expect(both.error?.issues[0]).toMatchObject({
+      message: 'apps "a" and "b" are on the same site: one app per site',
+      path: ["apps", "b", "origins"],
+    })
+  })
+})
diff --git a/packages/schema/src/docs-examples.test.ts b/packages/schema/src/docs-examples.test.ts
index c8b95b7..a2d8e58 100644
--- a/packages/schema/src/docs-examples.test.ts
+++ b/packages/schema/src/docs-examples.test.ts
@@ -18,7 +18,7 @@ function yamlBlockAfter(marker: string): string {
 describe("docs/OBJECT-MODEL.md examples", () => {
   it("project-level example (§2) is a valid project config", () => {
     const project = parseProjectYaml(yamlBlockAfter("**Project level**"))
-    expect(project.apps.app?.url).toBe("https://staging.acme.com")
+    expect(project.apps.app).toMatchObject({ url: "https://staging.acme.com" })
     expect(project.presets["login-as-manager"]?.session).toBe(true)
     expect(project.defaults.pacing.settleMs).toBe(400)
   })
diff --git a/packages/schema/src/project-model.test.ts b/packages/schema/src/project-model.test.ts
index f032639..7c553ad 100644
--- a/packages/schema/src/project-model.test.ts
+++ b/packages/schema/src/project-model.test.ts
@@ -210,7 +210,7 @@ describe("settings layers", () => {
       }),
     )
     const { config, environment } = resolveProjectConfig(p, org())
-    expect(config.apps.app?.url).toBe("https://app.example.com")
+    expect(config.apps.app).toMatchObject({ url: "https://app.example.com" })
     expect(config.interrupts.map((r) => r.do.action)).toEqual(["press"])
     expect(config.hide).toEqual([".intercom-launcher", ".beta-banner"])
     // The org's sandbox environment gives the project nothing (no flag: nothing is pre-approved).
@@ -294,7 +294,7 @@ describe("settings layers", () => {
 
   it("works without org settings", () => {
     const { config, environment } = resolveProjectConfig(Project.parse(project()), undefined)
-    expect(config.apps.app?.url).toBe("https://app.example.com")
+    expect(config.apps.app).toMatchObject({ url: "https://app.example.com" })
     expect(environment).toMatchObject({ requiredSecrets: [] })
   })
 
diff --git a/packages/schema/src/project.ts b/packages/schema/src/project.ts
index 7421b9f..5294e03 100644
--- a/packages/schema/src/project.ts
+++ b/packages/schema/src/project.ts
@@ -22,16 +22,85 @@ import { sameApp } from "./site.ts"
 // - `ProjectConfig`: what the runtime reads, resolved from org settings + the project
 //   (`resolveProjectConfig` in resolve.ts): the rule bank from the org.
 
-/** An app a demo shows: v0 drives web apps (pages and desktop apps come with their drivers). */
-export const App = z.strictObject({
+/** A web app, opened at its address in a fresh browser. */
+export const WebApp = z.strictObject({
   kind: z.literal("web"),
   /** http(s) only, and no embedded credentials (use the vault). */
   url: withoutCredentials(z.url({ protocol: /^https?$/ })),
   /** The size its takes are recorded at. */
   viewport: Viewport.prefault({ width: 1440, height: 900 }),
 })
+export type WebApp = z.infer<typeof WebApp>
+
+/** An https origin (a wrapper app's pages: Slack's, Notion's). */
+const HttpsOrigin = z
+  .string()
+  .max(255)
+  .refine((s) => {
+    const url = URL.parse(s)
+    return url !== null && url.protocol === "https:" && url.origin === s
+  }, "an https origin (https://host, no path)")
+
+/**
+ * A desktop Electron app (OBJECT-MODEL §0.9, design 2026-10-08), named by its bundle id: never a
+ * path or a program (a project may come from someone else: the app a bundle id means is found and
+ * approved on each machine, by the desktop app). Launched sandboxed for each run.
+ */
+export const ElectronApp = z.strictObject({
+  kind: z.literal("electron"),
+  /** The macOS bundle id (`com.example.app`). */
+  bundleId: z
+    .string()
+    .max(255)
+    .regex(/^[A-Za-z][A-Za-z0-9-]*(\.[A-Za-z0-9-]+)+$/, "a bundle id (com.example.app)"),
+  /** What the app opens (a folder, a file): positional only, never a switch. */
+  args: z
+    .array(
+      z
+        .string()
+        .min(1)
+        .max(1024)
+        // Chromium trims an argument before telling a switch: no space or control character at
+        // either end, none inside, never a leading dash.
+        .refine(
+          (a) =>
+            !a.startsWith("-") &&
+            !/^\s|\s$/.test(a) &&
+            ![...a].some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127),
+          "positional arguments only (no switches, no spaces at the ends)",
+        ),
+    )
+    .max(20)
+    .optional(),
+  /** The sites a wrapper app shows as its own (Slack's app.slack.com): its pages, never another's. */
+  origins: z.array(HttpsOrigin).max(10).optional(),
+  /** The size its takes are recorded at (emulated: the window itself is never moved). */
+  viewport: Viewport.prefault({ width: 1440, height: 900 }),
+})
+export type ElectronApp = z.infer<typeof ElectronApp>
+
+/** An app a demo shows: a web app, or a desktop Electron app. */
+export const App = z.discriminatedUnion("kind", [WebApp, ElectronApp])
 export type App = z.infer<typeof App>
 
+/** The web apps of a project (the ones with an address), by name. */
+export function webAppsOf(apps: Readonly<Record<string, App>>): Record<string, WebApp> {
+  return Object.fromEntries(
+    Object.entries(apps).filter((e): e is [string, WebApp] => e[1].kind === "web"),
+  )
+}
+
+/** A web app's address (a harness that drives web apps only); a desktop app has none: said. */
+export function urlOf(app: App): string {
+  if (app.kind !== "web") throw new Error(`a desktop app (${app.bundleId}) has no address`)
+  return app.url
+}
+
+/** What an app is, as one string (a take's key, a label): its address, or `electron:<bundle id>`. */
+export function appIdentity(app: App): string {
+  return app.kind === "web" ? app.url : `electron:${app.bundleId}`
+}
+
 /** The apps of a project, in order (the first is where a scene starts), never two on one site. */
 export const Apps = z.record(AppName, App).superRefine((apps, ctx) => {
   const entries = Object.entries(apps)
@@ -41,16 +110,33 @@ export const Apps = z.record(AppName, App).superRefine((apps, ctx) => {
     ctx.addIssue({ code: "custom", message: "at most 20 apps" })
     return
   }
+  // One app per site: two web apps on one site, a wrapper app's site (`origins`) that's a web app's
+  // or another wrapper's; one entry per desktop app (its bundle id, in any case).
+  const sites = (app: App): string[] => (app.kind === "web" ? [app.url] : (app.origins ?? []))
+  const overlap = (a: App, b: App) =>
+    sites(a).some((x) => sites(b).some((y) => sameApp(x, y) || sameApp(y, x)))
   entries.forEach(([name, app], i) => {
-    const other = entries
-      .slice(0, i)
-      .find(([, o]) => sameApp(app.url, o.url) || sameApp(o.url, app.url))
-    if (other !== undefined) {
-      ctx.addIssue({
-        code: "custom",
-        message: `apps "${other[0]}" and "${name}" are on the same site: one app per site`,
-        path: [name, "url"],
-      })
+    for (const [otherName, other] of entries.slice(0, i)) {
+      if (
+        app.kind === "electron" &&
+        other.kind === "electron" &&
+        app.bundleId.toLowerCase() === other.bundleId.toLowerCase()
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          message: `apps "${otherName}" and "${name}" are the same desktop app: one app each`,
+          path: [name, "bundleId"],
+        })
+        return
+      }
+      if (overlap(app, other)) {
+        ctx.addIssue({
+          code: "custom",
+          message: `apps "${otherName}" and "${name}" are on the same site: one app per site`,
+          path: [name, app.kind === "web" ? "url" : "origins"],
+        })
+        return
+      }
     }
   })
 })
@@ -81,7 +167,7 @@ export function appOf(project: { apps: Apps }, name: string): App | undefined {
 
 /** A shared off-camera setup. Presets are flat: they can't reference other presets (no recursion). */
 export const Preset = z.strictObject({
-  /** The app its steps start in, by name (default: the project's first). */
+  /** The app its steps start in, by name (default: the project's first; never a desktop app yet). */
   app: AppName.optional(),
   /** Run once per recording batch, then reuse its browser session (login presets). */
   session: z.boolean().default(false),
diff --git a/packages/schema/src/resolve.ts b/packages/schema/src/resolve.ts
index 0ba55f2..9e13f3f 100644
--- a/packages/schema/src/resolve.ts
+++ b/packages/schema/src/resolve.ts
@@ -1,5 +1,5 @@
 import type { OrgSettings } from "./org.ts"
-import { firstApp, ProjectConfig, type Output, type Project } from "./project.ts"
+import { appIdentity, firstApp, ProjectConfig, type Output, type Project } from "./project.ts"
 import { secretRefName } from "./common.ts"
 import type { Scenario } from "./scenario.ts"
 import type { SceneId } from "./scene.ts"
@@ -61,7 +61,7 @@ export function resolveProjectConfig(
     config,
     orgInterrupts: orgRules.filter((r) => !own.has(r.id)).map((r) => r.id),
     environment: {
-      url: firstApp(config).app.url,
+      url: appIdentity(firstApp(config).app),
       requiredSecrets: [],
     },
   }
diff --git a/packages/studio/src/add-app.ts b/packages/studio/src/add-app.ts
index f64e29d..272f0d0 100644
--- a/packages/studio/src/add-app.ts
+++ b/packages/studio/src/add-app.ts
@@ -1,4 +1,4 @@
-import { App } from "@kiframe/schema"
+import { WebApp } from "@kiframe/schema"
 import type { AppCard } from "./studio.ts"
 
 // `add_app`'s card (OBJECT-MODEL §0.9): what the user approves, built from the very address that
@@ -48,7 +48,7 @@ export function appCard(
   url: string,
   why: string,
 ): Omit<AppCard, "secrets" | "usedBy"> | { error: string } {
-  const checked = App.shape.url.safeParse(url)
+  const checked = WebApp.shape.url.safeParse(url)
   if (!checked.success)
     return { error: `url: ${checked.error.issues[0]?.message ?? "not an address"}` }
   const at = new URL(checked.data)
diff --git a/packages/studio/src/prompt.ts b/packages/studio/src/prompt.ts
index 649ca02..533d06d 100644
--- a/packages/studio/src/prompt.ts
+++ b/packages/studio/src/prompt.ts
@@ -1,4 +1,4 @@
-import { firstApp, stepReference } from "@kiframe/schema"
+import { type App, firstApp, stepReference } from "@kiframe/schema"
 import { SCENE_STEPS, type Studio } from "./studio.ts"
 
 /** The agent's instructions for a project (the scene format, how to ground, the tools' rules). */
@@ -118,6 +118,11 @@ Project presets available: ${Object.keys(config.presets).join(", ") || "none"}.
 ${appsPart(studio)}`
 }
 
+/** An app as the agent reads it: its address, or the desktop app it is. */
+function appSaid(app: App): string {
+  return app.kind === "web" ? app.url : `the desktop app ${app.bundleId}`
+}
+
 /**
  * The project's apps: one app said as before; several, with the rule a step on another app follows.
  * Either way, how a site the scene needs is added (add_app, the user approves).
@@ -128,13 +133,18 @@ function appsPart(studio: Studio): string {
   host: an identity provider is its own app): add it with \`add_app\` (the user approves; one line why).
   A step that ends on any other site fails in the replay. Never add a site to get around a refusal.`
   if (apps.length === 1) {
-    return `App: ${studio.scrub(firstApp(studio.options.config).app.url)}\n${adding}`
+    return `App: ${studio.scrub(appSaid(firstApp(studio.options.config).app))}\n${adding}`
   }
   const list = apps
-    .map(([name, app], i) => `  ${name}: ${studio.scrub(app.url)}${i === 0 ? " (the first)" : ""}`)
+    .map(
+      ([name, app], i) =>
+        `  ${name}: ${studio.scrub(appSaid(app))}${i === 0 ? " (the first)" : ""}`,
+    )
     .join("\n")
   return `Apps of the project (a scene may use several; never any other site):
 ${list}
+- A desktop app (one listed as "the desktop app …") can't be grounded or run yet: give every scene
+  and preset a web app (\`app: <name>\` when the first app is a desktop one).
 - A scene starts in the first app unless it says another at the top level, next to version:
   \`app: <name>\`. Pass the same as \`start_app\` to run_step and run_steps while you ground it.
 - A step without an app means the scene's start app, NEVER the app the page went to (a link, a
diff --git a/packages/studio/src/studio.ts b/packages/studio/src/studio.ts
index 4a833df..b912fc8 100644
--- a/packages/studio/src/studio.ts
+++ b/packages/studio/src/studio.ts
@@ -41,7 +41,6 @@ import {
 import {
   ACTION_REFERENCE,
   type ActionKind,
-  App,
   appOf,
   actionReference,
   Action,
@@ -60,6 +59,8 @@ import {
   SetupItem,
   Step,
   sameApp,
+  WebApp,
+  webAppsOf,
   firstApp,
   startAppOf,
 } from "@kiframe/schema"
@@ -269,8 +270,13 @@ export class Studio {
   #checked: Map<string, SnapshotNode> | undefined
   /** Aborted when the studio closes: every tool and dialog stops (the tools' signal includes it). */
   readonly #lifetime = new AbortController()
-  /** The app the live page opens at: the project's first. */
-  readonly #start: App
+  /**
+   * Where the live page opens: the first web app, as the project's apps are now (a desktop app has
+   * its own driver, next).
+   */
+  get #start(): WebApp | undefined {
+    return Object.values(this.options.config.apps).find((a): a is WebApp => a.kind === "web")
+  }
   #files: ProjectFiles | undefined
   #fileReads: Map<string, FileNote> | undefined
 
@@ -307,7 +313,7 @@ export class Studio {
     if (appOf(config, input.name) !== undefined) {
       return { error: `there is already an app named "${input.name}": pick another name` }
     }
-    const typed = App.shape.url.safeParse(input.url)
+    const typed = WebApp.shape.url.safeParse(input.url)
     if (!typed.success) {
       return {
         error: `url: ${typed.error.issues[0]?.message ?? "not an address"} (http(s), no credentials)`,
@@ -323,7 +329,7 @@ export class Studio {
     if (declined(card.url)) {
       return { error: `the user declined ${card.host} for this project: go on without it` }
     }
-    const same = Object.entries(config.apps).find(
+    const same = Object.entries(webAppsOf(config.apps)).find(
       ([, app]) => sameApp(card.url, app.url) || sameApp(app.url, card.url),
     )
     if (same !== undefined) {
@@ -337,7 +343,11 @@ export class Studio {
       ...project.project,
       apps: {
         ...project.project.apps,
-        [card.name]: { kind: "web", url: card.url, viewport: firstApp(config).app.viewport },
+        [card.name]: {
+          kind: "web",
+          url: card.url,
+          viewport: (this.#start ?? firstApp(config).app).viewport,
+        },
       },
     })
     if (!next.success) {
@@ -405,7 +415,6 @@ export class Studio {
 
   constructor(options: StudioOptions) {
     this.options = options
-    this.#start = firstApp(options.config).app
   }
 
   get project(): OpenedProject {
@@ -550,11 +559,6 @@ export class Studio {
     }
   }
 
-  #viewport() {
-    const { width, height } = this.#start.viewport
-    return { width, height }
-  }
-
   /**
    * A scrubber for text the agent reads: never a known secret value in it (the host's, and the live
    * page's, as they are now). Built once for a whole result (the tools' boundary).
@@ -780,7 +784,7 @@ export class Studio {
           ...(ask.doneWhen !== undefined &&
             ask.doneWhen.trim() !== "" && { doneWhen: ask.doneWhen }),
           origin,
-          onApp: siteOf(page.url(), this.options.config.apps) === "app",
+          onApp: siteOf(page.url(), webAppsOf(this.options.config.apps)) === "app",
           where: ask.where,
           ...(ask.scene !== undefined && { scene: ask.scene }),
         },
@@ -871,10 +875,16 @@ export class Studio {
     if (this.#live !== undefined) await this.#settled()
     await this.#live?.context.close().catch(() => undefined)
     this.#live = undefined
-    const context = await this.options.browser.newContext({ viewport: this.#viewport() })
+    // A desktop app has its own driver (the Electron target, next): never a page here.
+    const start = this.#start
+    if (start === undefined) {
+      throw new Error("desktop apps can't be grounded yet: the Electron target comes next")
+    }
+    const { width, height } = start.viewport
+    const context = await this.options.browser.newContext({ viewport: { width, height } })
     try {
       const page = await context.newPage()
-      await page.goto(this.#start.url)
+      await page.goto(start.url)
       // Closed meanwhile: never kept (nothing would close it).
       if (this.#lifetime.signal.aborted) throw new Error("the studio was closed")
       // Kept only once it's at the app (a failed first visit is tried again next time).
@@ -897,12 +907,14 @@ export class Studio {
   }
 
   #where(url: string, site?: Site): string {
-    return whereOf(url, this.options.config.apps, site)
+    // Named whenever the project has several apps (a desktop one too: the prompt lists them all).
+    const { apps } = this.options.config
+    return whereOf(url, webAppsOf(apps), site, Object.keys(apps).length > 1)
   }
 
   /** A step done, and where its page is: a page that failed to load makes it a failure. */
   #landed(url: string, said: string): StepResult {
-    const site = siteOf(url, this.options.config.apps)
+    const site = siteOf(url, webAppsOf(this.options.config.apps))
     if (site === "unloaded") {
       return {
         ok: false,
@@ -1137,11 +1149,17 @@ export class Studio {
         ? saved
         : undefined) ??
       firstApp(this.options.config).name
-    if (appOf(this.options.config, app) === undefined) {
+    const starts = appOf(this.options.config, app)
+    if (starts === undefined) {
       return failed(
         `start_app: "${app}" isn't one of the project's apps (${Object.keys(this.options.config.apps).join(", ")})`,
       )
     }
+    if (starts.kind !== "web") {
+      return failed(
+        `start_app: "${app}" is a desktop app: desktop apps can't be grounded yet (the Electron target comes next)`,
+      )
+    }
     const raw = asObject(input)
     if (isCyclic(raw))
       return failed("invalid step: a YAML alias refers to itself (or it nests too deep)")
@@ -1631,7 +1649,12 @@ export interface StepResult {
  * app's name when the project has several, and what its site is when it
  * isn't a listed app's own origin (`siteOf`).
  */
-export function whereOf(url: string, apps: AppsArg, site = siteOf(url, apps)): string {
+export function whereOf(
+  url: string,
+  apps: AppsArg,
+  site = siteOf(url, apps),
+  several = listed(apps).length > 1,
+): string {
   if (site === "unloaded") return "(the page failed to load: try again)"
   let page: URL
   try {
@@ -1646,7 +1669,7 @@ export function whereOf(url: string, apps: AppsArg, site = siteOf(url, apps)): s
   if (on !== undefined) {
     const [name, app] = on
     // Several apps: always named (the agent tells "back on app" from "still on docs").
-    const path = all.length > 1 ? `${name}: ${page.pathname}` : page.pathname
+    const path = several ? `${name}: ${page.pathname}` : page.pathname
     // The app's site under another address (redirected to www. or https): its steps work, its
     // secrets don't (typed on their exact origin only): said, so a refused secret step has a why.
     return page.origin === app.origin
diff --git a/packages/studio/src/tools.ts b/packages/studio/src/tools.ts
index 89d57b2..e885b48 100644
--- a/packages/studio/src/tools.ts
+++ b/packages/studio/src/tools.ts
@@ -1,6 +1,6 @@
 import { defineTool, isWithImages, type Tool, withImages } from "@kiframe/agent"
 import { saveScene } from "@kiframe/project"
-import { AppName, firstApp, RuleName, SceneId } from "@kiframe/schema"
+import { AppName, firstApp, RuleName, SceneId, webAppsOf } from "@kiframe/schema"
 import { parse as parseYaml } from "yaml"
 import { z } from "zod"
 import { fileTools } from "./file-tools.ts"
@@ -232,8 +232,9 @@ const listSecrets = defineTool({
     "Names of the secrets the user provided (never their values), each with the app it's typed on.",
   parameters: z.object({}),
   run: (_args, studio: Studio) => {
-    // App by app (each its exact origin): a secret is typed only on its own app.
-    const apps = Object.entries(studio.options.config.apps)
+    // App by app (each its exact origin): a secret is typed only on its own app; a desktop app
+    // takes none (the user signs in by hand).
+    const apps = Object.entries(webAppsOf(studio.options.config.apps))
     const secrets = apps.flatMap(([app, { url }]) =>
       (studio.options.secrets?.(new URL(url).origin) ?? []).map((s) => ({ ...s, app })),
     )
diff --git a/packages/studio/test/desktop-app.test.ts b/packages/studio/test/desktop-app.test.ts
new file mode 100644
index 0000000..bbc18d7
--- /dev/null
+++ b/packages/studio/test/desktop-app.test.ts
@@ -0,0 +1,96 @@
+import { mkdtempSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { createProject, TakeStore } from "@kiframe/project"
+import { parseProjectYaml } from "@kiframe/schema"
+import type { Browser } from "playwright"
+import { describe, expect, it } from "vitest"
+import { Studio, studioTools, systemPrompt, whereOf } from "../src/index.ts"
+
+// A desktop Electron app among the project's apps (design 2026-10-08): said to the agent as such,
+// no secrets on it, never grounded as a web page until its driver lands.
+
+function studioWith(appsYaml: string) {
+  const dir = join(mkdtempSync(join(tmpdir(), "kiframe-desk-")), "demo.kiframe")
+  const project = createProject(dir, { id: "p1", name: "Demo", url: "https://app.test" })
+  const secretsAsked: string[] = []
+  const opened: string[] = []
+  const browser = {
+    newContext: () =>
+      Promise.resolve({
+        newPage: () =>
+          Promise.resolve({
+            goto: (url: string) => {
+              opened.push(url)
+              return Promise.resolve(null)
+            },
+          }),
+        close: () => Promise.resolve(),
+      }),
+  } as unknown as Browser
+  const studio = new Studio({
+    project,
+    scope: "folder-1",
+    sceneKey: (id) => `host-${id}`,
+    config: parseProjectYaml(`version: 2\napps:\n${appsYaml}`),
+    takes: new TakeStore(mkdtempSync(join(tmpdir(), "kiframe-desk-data-"))),
+    browser,
+    requestUser: () => Promise.resolve(false),
+    secrets: (origin) => {
+      secretsAsked.push(origin)
+      return [{ name: "pw", provided: true }]
+    },
+    stopRun: () => undefined,
+  })
+  return { studio, secretsAsked, opened }
+}
+
+describe("a desktop app in the studio", () => {
+  it("is said to the agent as the desktop app it is", () => {
+    const one = studioWith("  notes: { kind: electron, bundleId: com.example.notes }\n")
+    expect(systemPrompt(one.studio)).toContain("App: the desktop app com.example.notes")
+    const two = studioWith(
+      '  app: { kind: web, url: "https://app.test" }\n  notes: { kind: electron, bundleId: com.example.notes }\n',
+    )
+    expect(systemPrompt(two.studio)).toContain("  notes: the desktop app com.example.notes")
+  })
+
+  it("lists no secret on it (the user signs in by hand there)", async () => {
+    const { studio, secretsAsked } = studioWith(
+      '  app: { kind: web, url: "https://app.test" }\n  notes: { kind: electron, bundleId: com.example.notes }\n',
+    )
+    const tool = studioTools.find((t) => t.name === "list_secrets")!
+    await tool.run({}, studio, new AbortController().signal)
+    expect(secretsAsked).toEqual(["https://app.test"])
+  })
+
+  it("is never grounded as a web page (its driver comes next): said, never a page opened", async () => {
+    const alone = studioWith("  notes: { kind: electron, bundleId: com.example.notes }\n")
+    await expect(alone.studio.livePage()).rejects.toThrow(/desktop apps can't be grounded yet/)
+    expect(alone.opened).toEqual([])
+    // Listed first, beside a web app: the live page opens on the web app.
+    const both = studioWith(
+      '  notes: { kind: electron, bundleId: com.example.notes }\n  app: { kind: web, url: "https://app.test" }\n',
+    )
+    await both.studio.livePage()
+    expect(both.opened).toEqual(["https://app.test"])
+    // A step grounded in the desktop app: refused, said why.
+    const tool = studioTools.find((t) => t.name === "run_step")!
+    expect(
+      await tool.run(
+        { scene: "s", step: { id: "a", action: "pause", ms: 1 }, start_app: "notes" },
+        both.studio,
+        new AbortController().signal,
+      ),
+    ).toEqual({
+      error:
+        'start_app: "notes" is a desktop app: desktop apps can\'t be grounded yet (the Electron target comes next)',
+    })
+  })
+
+  it("names the app in a step's place whenever the project has several (a desktop one too)", () => {
+    const apps = { app: { url: "https://app.test" } }
+    expect(whereOf("https://app.test/dash", apps, "app", true)).toBe("app: /dash")
+    expect(whereOf("https://app.test/dash", apps, "app")).toBe("/dash")
+  })
+})
diff --git a/packages/studio/test/studio.test.ts b/packages/studio/test/studio.test.ts
index abbdb3c..6a2ed5b 100644
--- a/packages/studio/test/studio.test.ts
+++ b/packages/studio/test/studio.test.ts
@@ -1225,7 +1225,7 @@ describe("add_app (B4)", () => {
         why: "the install guide",
       }),
     ])
-    expect(openProject(dir).project.apps.docs?.url).toBe(docs().origin)
+    expect(openProject(dir).project.apps.docs).toMatchObject({ url: docs().origin })
     expect(
       await tool("run_step").run(
         { scene: "tour", step: { id: "go", action: "goto", app: "docs", url: "/login" } },
@@ -1737,7 +1737,10 @@ ${["a", "b", "c", "d", "e"].map((id) => `  - { id: ${id}, action: pause, ms: 20
     const never = new AbortController().signal
     expect(await studio.replay(sceneWith(), "demo", never)).toBe("ok")
     const { apps } = studio.options.config
-    studio.setApps({ ...apps, other: { ...apps.app!, url: "https://other.test" } })
+    studio.setApps({
+      ...apps,
+      other: { kind: "web", viewport: apps.app!.viewport, url: "https://other.test" },
+    })
     expect(await studio.replay(sceneWith(), "demo", never)).toBe("ok")
     expect(asks()).toBe(2)
   }, 60_000)
diff --git a/scripts/m1-4/batch-check.ts b/scripts/m1-4/batch-check.ts
index 25fe2e2..c55f68e 100644
--- a/scripts/m1-4/batch-check.ts
+++ b/scripts/m1-4/batch-check.ts
@@ -5,7 +5,7 @@ import { join } from "node:path"
 import { readFileSync } from "node:fs"
 import { parseArgs } from "node:util"
 import { recordBatch } from "@kiframe/runtime"
-import { firstApp, parseProjectYaml, parseScenarioYaml } from "@kiframe/schema"
+import { firstApp, urlOf, parseProjectYaml, parseScenarioYaml } from "@kiframe/schema"
 import { chromium } from "playwright"
 import { envSecretResolver, loadDotEnv } from "../lib/secrets.ts"
 
@@ -47,7 +47,7 @@ try {
       scope: "phase0",
       resolveSecret: envSecretResolver(
         ["calcom.username", "calcom.password"],
-        firstApp(project).app.url,
+        urlOf(firstApp(project).app),
       ),
       timeoutMs: 15000,
       onEvent: (e) => {
diff --git a/scripts/p0-8/ground.ts b/scripts/p0-8/ground.ts
index 60895e1..d2e4b3f 100644
--- a/scripts/p0-8/ground.ts
+++ b/scripts/p0-8/ground.ts
@@ -123,7 +123,9 @@ for (const signal of ["SIGINT", "SIGTERM"] as const) {
 }
 const project = parseProjectYaml(readFileSync(values.project, "utf8"))
 /** The app every scene starts in (the project's first). */
-const start = firstApp(project).app
+const firstListed = firstApp(project).app
+if (firstListed.kind !== "web") throw new Error("ground.ts drives web apps only")
+const start = firstListed
 const model = values.model
 // The scene being grounded (its steps and its replays are one scene: they share approvals).
 const sceneId = sceneIdOf(values.out)
diff --git a/scripts/p0-8/login-check.ts b/scripts/p0-8/login-check.ts
index 69679ed..2b0309b 100644
--- a/scripts/p0-8/login-check.ts
+++ b/scripts/p0-8/login-check.ts
@@ -1,7 +1,7 @@
 // P0-8 (throwaway): checks the Cal.com login preset alone. Prints the outcome and URL path only.
 import { readFileSync } from "node:fs"
 import { runScenario, StepError } from "@kiframe/runtime"
-import { firstApp, parseProjectYaml, parseScenarioYaml } from "@kiframe/schema"
+import { firstApp, urlOf, parseProjectYaml, parseScenarioYaml } from "@kiframe/schema"
 import { chromium } from "playwright"
 import { envSecretResolver, loadDotEnv } from "../lib/secrets.ts"
 
@@ -10,7 +10,7 @@ const project = parseProjectYaml(readFileSync("examples/calcom/project.yaml", "u
 const scenario = parseScenarioYaml(
   "version: 1\nsetup: [{ preset: login }]\nsteps: [{ id: wait, action: pause, ms: 500 }]\n",
 )
-const env = envSecretResolver(["calcom.username", "calcom.password"], firstApp(project).app.url)
+const env = envSecretResolver(["calcom.username", "calcom.password"], urlOf(firstApp(project).app))
 const browser = await chromium.launch()
 const page = await browser.newPage({ viewport: { width: 1440, height: 900 } })
 try {
diff --git a/scripts/record.ts b/scripts/record.ts
index 74f76df..69b98e9 100644
--- a/scripts/record.ts
+++ b/scripts/record.ts
@@ -5,7 +5,7 @@ import { existsSync, readFileSync } from "node:fs"
 import { join } from "node:path"
 import { parseArgs } from "node:util"
 import { recordScenario } from "@kiframe/runtime"
-import { firstApp, parseProjectYaml, parseScenarioYaml, startAppOf } from "@kiframe/schema"
+import { firstApp, urlOf, parseProjectYaml, parseScenarioYaml, startAppOf } from "@kiframe/schema"
 import { chromium } from "playwright"
 import { sceneIdOf } from "./lib/scenes.ts"
 import { envSecretResolver, loadDotEnv } from "./lib/secrets.ts"
@@ -46,7 +46,7 @@ const start = startAppOf(scenario, project).app
 // The `.env` secrets are the first app's (its login, as a preset without an app runs there).
 const resolveSecret = envSecretResolver(
   values.secrets.split(",").filter(Boolean),
-  firstApp(project).app.url,
+  urlOf(firstApp(project).app),
 )
 // A high DPR only helps headed (headless frames stay at CSS resolution, F1): the project's DPR
 // headed, 1 headless, unless --dpr says otherwise.

From 2dc9c326ae4f8bc325d918bbc661e14446699d23 Mon Sep 17 00:00:00 2001
From: Quang Lee <winlp4ever@gmail.com>
Date: Thu, 8 Oct 2026 22:37:39 +0200
Subject: [PATCH 02/10] feat(runtime): launch and drive a desktop electron app
 in a sandbox (#56)

* feat(runtime): launch and drive a desktop electron app in a sandbox

* fix(runtime): read working folders from /proc on linux when sweeping a sandbox

* fix(runtime): bound a desktop app's shutdown and say an app that quits as it's attached

* fix(runtime): say a desktop app that quits before showing a window at once
---
 .github/workflows/ci.yml                      |  16 +-
 docs/OBJECT-MODEL.md                          |   5 +-
 eslint.config.js                              |  11 +-
 packages/runtime/src/electron.ts              | 725 ++++++++++++++
 packages/runtime/src/index.ts                 |   8 +
 packages/runtime/src/run/actions.ts           |   4 +-
 packages/runtime/src/run/apps.ts              |  73 +-
 packages/runtime/src/run/conditions.ts        |  19 +-
 packages/runtime/src/run/context.ts           |   6 +
 packages/runtime/src/run/interrupts.ts        |  30 +-
 packages/runtime/src/run/pages.ts             |  24 +
 packages/runtime/src/run/setup.ts             |  17 +-
 packages/runtime/src/run/step.ts              |   5 +-
 packages/runtime/src/runner.ts                |  35 +-
 packages/runtime/test/apps.test.ts            |   4 +-
 packages/runtime/test/batch.test.ts           |   4 +-
 packages/runtime/test/electron.test.ts        | 891 ++++++++++++++++++
 .../test/fixtures/electron-app/index.html     |  51 +
 .../test/fixtures/electron-app/main.cjs       |  91 ++
 .../test/fixtures/electron-app/other.html     |  15 +
 .../test/fixtures/electron-app/package.json   |   5 +
 packages/studio/test/snapshot-find.test.ts    |   3 +-
 22 files changed, 2010 insertions(+), 32 deletions(-)
 create mode 100644 packages/runtime/src/electron.ts
 create mode 100644 packages/runtime/test/electron.test.ts
 create mode 100644 packages/runtime/test/fixtures/electron-app/index.html
 create mode 100644 packages/runtime/test/fixtures/electron-app/main.cjs
 create mode 100644 packages/runtime/test/fixtures/electron-app/other.html
 create mode 100644 packages/runtime/test/fixtures/electron-app/package.json

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b09df56..e72c221 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -31,13 +31,17 @@ jobs:
       - run: pnpm lint
       - run: pnpm format:check
       - run: pnpm typecheck
-      - run: pnpm test:coverage
-      # The desktop app, built and launched under a virtual display. Ubuntu 24 restricts the user
-      # namespaces Chromium's sandbox needs: allowed back, so the app runs sandboxed as shipped.
+      # Ubuntu 24 restricts the user namespaces Chromium's sandbox needs: allowed back (Electron runs
+      # sandboxed as shipped). The tests run under a virtual display: the Electron target's tests
+      # launch a fixture desktop app.
+      - run: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+      - run: xvfb-run -a pnpm test:coverage
+        env:
+          # Slow shutdown phases of a desktop app's launch, said (the Electron target's evidence).
+          KIFRAME_ELECTRON_TIMING: "1"
+      # The desktop app, built and launched under a virtual display.
       - name: Desktop end-to-end
-        run: |
-          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
-          xvfb-run -a pnpm --filter @kiframe/desktop e2e
+        run: xvfb-run -a pnpm --filter @kiframe/desktop e2e
       - name: Upload coverage to Codecov
         if: ${{ !cancelled() }}
         uses: codecov/codecov-action@v5
diff --git a/docs/OBJECT-MODEL.md b/docs/OBJECT-MODEL.md
index 2c7c526..99e661e 100644
--- a/docs/OBJECT-MODEL.md
+++ b/docs/OBJECT-MODEL.md
@@ -227,7 +227,10 @@ One scene, three phases. The agent's own instructions say the same (`packages/st
 - **Named by bundle id, never a path or a program** (a project may come from someone else): the desktop app finds the bundle on each machine and keeps the user's approval in its own settings (bundle id, real path, signing team); only `.app` bundles holding `Electron Framework.framework`; App Store (sandboxed) apps refused. `args` are positional only (no switches). `origins`: the https sites a wrapper app (Slack, Notion) shows as its own.
 - **No address**: a goto or a URL condition on it is refused; a scene starting in it opens on its first window; it takes no secrets in v0 (the user signs in by hand: the handover).
 - **Each run launches it sandboxed** (its own HOME, `CFFIXED_USER_HOME`, XDG and temp folders, `--user-data-dir`; an allowlisted environment, never Kiframe's), attached with `--remote-debugging-port=0` + `connectOverCDP`; the viewport is emulated (a spike measured frames and clicks with the window covered, off-screen, minimized or hidden: a run never needs the user's screen; the window itself can't be moved over CDP). Isolation is verified when the app is added: after a trial launch its state must be inside the sandbox, else refused. Its process group killed after each run, leftovers swept.
-- **Stated limits:** native dialogs and menus are unreachable; links open in the user's real browser; a sign-in through the browser with an app-scheme callback isn't supported in v0; the keychain is the user's (an app reading its own item signs in as them); a window built from several views films one view.
+- **Confinement: a guard, sealed at launch (PR 2, redesigned after three review rounds, design reviewed).** Once the app settles (its windows unchanged 1.5 s), its main window is the last opened still open; its own scheme or dev server is learned from that window alone, then sealed (nothing a run does adds to it). A main window that isn't the app's own (a wrapper's unlisted site) refuses the launch ("list it in its origins"). From then a **guard** checks every navigation of every frame of every window as it happens: a page that isn't the app's own is stopped at once (a popup closed, any other frame blanked: never left for a read or a frame) and recorded; the step fails `off-app`. The app's own: a local `file:` in its bundle or sandbox (decoded, normalized), its sealed scheme or dev server, a listed https site (`sameApp`, never plain http), a blob of those. Stated (as a web run): the guard acts as a page commits, so a page that isn't the app's own has loaded (its scripts ran, with the app's own rights) before it's stopped: following a link the app offers is what its user does too (blocking before the load needs request interception, which never sees `file:`); and the runner's own navigation events name it as they do for web runs (origin and path, known secret values scrubbed). What the main window embeds as it opens (a frame of another site) is the app as shipped: its origin is the app's own. A main window stopped goes back to the app's page (no goto there to bring it back); a failed load is said as one. **One app per run:** a desktop app's run never shows a site (no goto, URL condition or web preset; a web interrupt rule's goto skipped, said), is confined while grounding too, and keeps no sign-in between runs yet.
+- **Windows (PR 2, known limits, to settle on real apps in PR 3 and PR 5: decided by the user 2026-10-08):** the main window is the last opened still open once the app's windows were unchanged for 1.5 s (a splash that stays up longer is taken for the main window); windows the app's main process opens are followed as popups are (a hidden helper window opened during a step may be followed: CDP can't tell it's hidden); only the launch window is sent back when it goes off-app (another window is closed); a stop that lands after its step ended counts against the next step. A window that opens blank gets a moment to load (as a web page does); a frame of a window the run isn't driving is said, never the step's failure.
+- **Measured on a fixture app (PR 2, 2026-10-08):** HOME, XDG and `--user-data-dir` hold; macOS's own places don't move: Electron's `appData` (`~/Library/Application Support`) and the app's preferences (`NSUserDefaults`, written by `cfprefsd` into the user's real `~/Library/Preferences/<bundle id>.plist`) stay the user's whatever `HOME` or `CFFIXED_USER_HOME` say. The trial launch therefore checks both: the app's state inside the sandbox, and its preferences file unchanged; else the user is told.
+- **Stated limits:** native dialogs and menus are unreachable; links open in the user's real browser; a sign-in through the browser with an app-scheme callback isn't supported in v0; the keychain and an app's macOS preferences are the user's (an app reading its own keychain item signs in as them); a window built from several views films one view.
 - **Built in steps** (epic `epic/electron-targets`): the format (2026-10-08), the launcher and target, the desktop approval and trial, the studio and batch on it, a real pass on a sandboxed minmux.
 
 **Existing projects convert** on open: `target` becomes `apps.app` (the rest unchanged).
diff --git a/eslint.config.js b/eslint.config.js
index 0763c2b..3870a05 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -3,7 +3,16 @@ import { defineConfig } from "eslint/config"
 import tseslint from "typescript-eslint"
 
 export default defineConfig(
-  { ignores: ["**/dist/**", "**/coverage/**", ".kiframe-local/**", "apps/desktop/out/**"] },
+  {
+    ignores: [
+      "**/dist/**",
+      "**/coverage/**",
+      ".kiframe-local/**",
+      "apps/desktop/out/**",
+      // A fixture desktop app (plain CommonJS Electron loads as is: never part of a TS project).
+      "packages/runtime/test/fixtures/electron-app/**",
+    ],
+  },
   js.configs.recommended,
   tseslint.configs.recommendedTypeChecked,
   {
diff --git a/packages/runtime/src/electron.ts b/packages/runtime/src/electron.ts
new file mode 100644
index 0000000..daef1db
--- /dev/null
+++ b/packages/runtime/src/electron.ts
@@ -0,0 +1,725 @@
+import { execFile, spawn, type ChildProcess } from "node:child_process"
+import { posix } from "node:path"
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs"
+import { readdir, readlink, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { basename, dirname, join, sep } from "node:path"
+import { sameApp, type Viewport } from "@kiframe/schema"
+import { untilStopped } from "./look.ts"
+import {
+  chromium,
+  type Browser,
+  type BrowserContext,
+  type CDPSession,
+  type Frame,
+  type Page,
+} from "playwright"
+
+// A desktop Electron app as a run's target (OBJECT-MODEL §0.9 "Electron apps", design reviewed
+// 2026-10-08): launched from its executable (found and approved by the host: never a path from a
+// project) in a fresh sandbox, attached over its debugging port (`--remote-debugging-port=0`, read
+// from its own output), its windows emulated at the scene's size, its whole process group killed at
+// the end and anything left holding the sandbox swept.
+
+/** Environment variables passed through to the app: never Kiframe's own (keys, NODE_OPTIONS, ELECTRON_*). */
+const PASSED_ENV = [
+  "PATH",
+  "LANG",
+  "TZ",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  // Linux: the display and session bus the app draws on (no window without them).
+  "DISPLAY",
+  "WAYLAND_DISPLAY",
+  "XAUTHORITY",
+  "XDG_RUNTIME_DIR",
+  "DBUS_SESSION_BUS_ADDRESS",
+]
+
+/** How long an app may take to open its debugging port and its first window. */
+const LAUNCH_MS = 20_000
+/** How long a terminated app may take to quit before it's killed. */
+const QUIT_MS = 2000
+/** How long closing the debugging connection may take (the group is killed after it anyway). */
+const CLOSE_MS = 2000
+/** How long an app that dropped the attach has to tell its exit. */
+const EXIT_TELL_MS = 1000
+
+/** `work`, given at most `ms` (its result then never awaited). */
+async function within(work: Promise<unknown> | undefined, ms: number): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  await Promise.race([work, new Promise((resolve) => (timer = setTimeout(resolve, ms)))])
+  clearTimeout(timer)
+}
+
+/** Whether the app exited, or does within `ms`. */
+async function exitedSoon(child: ChildProcess, ms: number): Promise<boolean> {
+  if (child.exitCode !== null || child.signalCode !== null) return true
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      child.off("exit", exited)
+      resolve(false)
+    }, ms)
+    const exited = () => {
+      clearTimeout(timer)
+      resolve(true)
+    }
+    child.once("exit", exited)
+  })
+}
+
+/** Shutdown phases that took long, said on stderr (KIFRAME_ELECTRON_TIMING): CI's evidence. */
+function timing(phase: string, since: number) {
+  const took = Date.now() - since
+  if (process.env.KIFRAME_ELECTRON_TIMING !== undefined && took > 500) {
+    process.stderr.write(`[electron] ${phase} took ${took} ms\n`)
+  }
+}
+
+const QUIT_EARLY =
+  "the app quit before Kiframe could attach (it may allow only one instance: quit it and try again; be a launcher for another program; or refuse automation)"
+
+/** An app that couldn't be launched or attached: said to the user as is. */
+export class ElectronLaunchError extends Error {}
+
+export interface ElectronLaunch {
+  /** The app's executable (`X.app/Contents/MacOS/X`), resolved and approved by the host. */
+  executable: string
+  /** Its `.app` bundle: a `file:` page inside it is the app's own. */
+  bundle?: string
+  /** What the app opens (positional: the project's `args`). */
+  args?: readonly string[]
+  /** The size its windows are shown at (emulated: the window itself is never moved). */
+  viewport: Pick<Viewport, "width" | "height" | "deviceScaleFactor">
+  /** The https sites a wrapper app shows as its own (the project's `origins`). */
+  origins?: readonly string[]
+  /** A file noting the launches still running: what a crash left is swept at the next start. */
+  stateFile?: string
+  signal?: AbortSignal
+  /** Tests: how long to wait for the app, its port and its first window together (default 20 s). */
+  timeoutMs?: number
+}
+
+/** A page the guard stopped: in which window, whether it was the window itself, and where. */
+export interface GuardStop {
+  page: Page
+  /** The window's own page (sent back or closed), not a frame inside it. */
+  window: boolean
+  place: string
+}
+
+/** A launched app: its browser connection, its context and main window, and how to end it. */
+export interface ElectronTarget {
+  browser: Browser
+  context: BrowserContext
+  page: Page
+  /** The sandbox folder (its HOME, its data). */
+  sandbox: string
+  /** Whether a page's address is the app's own (sealed at launch: nothing a run does adds to it). */
+  allows: (url: string) => boolean
+  /**
+   * Where the app went that isn't its own since the last call (each stopped at once: the frame
+   * blanked, the window sent back or closed), said by place (never a full address: it may hold a
+   * token).
+   */
+  stopped: () => GuardStop[]
+  /** A window the run follows, at the scene's size first (its emulation applied). */
+  prepare: (page: Page) => Promise<void>
+  /**
+   * Ends it (once: a second call does nothing): disconnects, kills the app's process group and
+   * what still points at the sandbox, removes it. `unread`: what holds the sandbox couldn't be read.
+   */
+  close: () => Promise<{ unread: boolean }>
+}
+
+/** A fresh sandbox: the app's HOME (and macOS's), its XDG folders, its temp and its profile. */
+function makeSandbox(): { root: string; env: NodeJS.ProcessEnv; profile: string } {
+  // The real path: macOS's /var is a link (a file: page's path is compared with it).
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "kiframe-app-")))
+  const dirs = {
+    home: join(root, "home"),
+    config: join(root, "home", ".config"),
+    data: join(root, "home", ".local", "share"),
+    cache: join(root, "home", ".cache"),
+    state: join(root, "home", ".local", "state"),
+    tmp: join(root, "tmp"),
+    profile: join(root, "profile"),
+  }
+  for (const dir of Object.values(dirs)) mkdirSync(dir, { recursive: true })
+  const env: NodeJS.ProcessEnv = {}
+  for (const name of PASSED_ENV) if (process.env[name] !== undefined) env[name] = process.env[name]
+  for (const [name, value] of Object.entries(process.env)) {
+    if (name.startsWith("LC_")) env[name] = value
+  }
+  Object.assign(env, {
+    HOME: dirs.home,
+    // macOS: what reads NSHomeDirectory follows it (not appData, not the app's preferences: those
+    // stay the user's, checked by the trial launch).
+    CFFIXED_USER_HOME: dirs.home,
+    XDG_CONFIG_HOME: dirs.config,
+    XDG_DATA_HOME: dirs.data,
+    XDG_CACHE_HOME: dirs.cache,
+    XDG_STATE_HOME: dirs.state,
+    TMPDIR: `${dirs.tmp}${sep}`,
+  })
+  return { root, env, profile: dirs.profile }
+}
+
+/** How long the app's windows must stay as they are before its main window is chosen. */
+const SETTLE_MS = 1500
+
+/** Launches `opts.executable` in a fresh sandbox and attaches to its main window. */
+export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarget> {
+  opts.signal?.throwIfAborted()
+  // Before anything runs: an app moved since it was approved is said, never half-launched.
+  let bundles: string[]
+  try {
+    // As given and as it really is: an app may build its pages' paths either way.
+    bundles = opts.bundle === undefined ? [] : [opts.bundle, realpathSync(opts.bundle)]
+  } catch {
+    throw new ElectronLaunchError(`the app isn't at ${opts.bundle ?? ""} any more`)
+  }
+  const deadline = Date.now() + (opts.timeoutMs ?? LAUNCH_MS)
+  const sandbox = makeSandbox()
+  const child = spawn(
+    opts.executable,
+    [...(opts.args ?? []), `--user-data-dir=${sandbox.profile}`, "--remote-debugging-port=0"],
+    // Its own process group (killed whole), no terminal; its output read for the port only.
+    { detached: true, env: sandbox.env, stdio: ["ignore", "ignore", "pipe"], cwd: sandbox.root },
+  )
+  // Its spawn failing is said by the launch (never an unhandled 'error' event).
+  let spawnError: Error | undefined
+  child.on("error", (error) => (spawnError = error))
+  let browser: Browser | undefined
+  let ended: Promise<{ unread: boolean }> | undefined
+  // Once: the app's group is signalled only while it's known alive (its leader running, or its
+  // windows still connected: a group's id is never reused while the group lives).
+  const end = () =>
+    (ended ??= (async () => {
+      const alive = browser?.isConnected() === true
+      // Bounded: the group is killed right after (a close the app never answers never holds it).
+      const t0 = Date.now()
+      await within(
+        browser?.close().catch(() => undefined),
+        CLOSE_MS,
+      )
+      timing("close", t0)
+      return stop(child, sandbox.root, opts.stateFile, alive)
+    })())
+  try {
+    // Noted at once (a crash from here on is swept at the next start); a note that can't be
+    // written ends the launch (never an app left running unnoted).
+    note(opts.stateFile, sandbox.root, true)
+    const endpoint = await debuggingEndpoint(
+      child,
+      sandbox.profile,
+      deadline,
+      opts.signal,
+      () => spawnError,
+    )
+    browser = await untilStopped(
+      chromium.connectOverCDP(endpoint, { timeout: Math.max(1, deadline - Date.now()) }),
+      opts.signal,
+    )
+    const context = browser.contexts()[0]
+    if (context === undefined) throw new ElectronLaunchError("the app opened no window")
+    const connected = browser
+    const page = await mainWindow(
+      context,
+      deadline,
+      opts.signal,
+      () => child.exitCode !== null || child.signalCode !== null || !connected.isConnected(),
+    )
+    // Sealed now, from the main window alone: its own scheme (app:) or dev server (loopback).
+    const launched = new Set<string>()
+    const schemes = new Set<string>()
+    const embedded = new Set<string>()
+    const origin = loopbackOrigin(page.url())
+    if (origin !== undefined) launched.add(origin)
+    const scheme = ownScheme(page.url())
+    if (scheme !== undefined) schemes.add(scheme)
+    // What the main window embeds as it opens (a video, a widget) is part of the app as shipped.
+    for (const frame of page.frames()) {
+      const url = URL.parse(frame.url())
+      // https only (a listed site's rule: never plain http in the app's name).
+      if (frame !== page.mainFrame() && url !== null && url.protocol === "https:") {
+        embedded.add(url.origin)
+      }
+    }
+    const own = {
+      bundles,
+      sandbox: sandbox.root,
+      launched,
+      schemes,
+      origins: [...(opts.origins ?? []), ...embedded],
+    }
+    const allows = (url: string) => allowedPage(url, own)
+    if (!allows(page.url())) {
+      throw new ElectronLaunchError(
+        `the app shows ${placeOf(page.url())}: if that's the app's own, list it in its origins`,
+      )
+    }
+    // The guard: every frame of every window, every navigation, at once; one that isn't the app's
+    // own is stopped (a popup closed, any other frame blanked) and said.
+    const stops: GuardStop[] = []
+    const frameAllowed = (frame: Frame): boolean => {
+      const url = frame.url()
+      if (url === "" || url === "about:blank") return true
+      // An inline frame (srcdoc) is its parent's content.
+      if (url === "about:srcdoc") {
+        const parent = frame.parentFrame()
+        return parent !== null && frameAllowed(parent)
+      }
+      // A load that failed (Chromium's error page): said as such by the step, never a place.
+      if (url.startsWith("chrome-error:")) return true
+      return allows(url)
+    }
+    const watch = (p: Page) => {
+      const check = (frame: Frame) => {
+        if (frameAllowed(frame)) return
+        stops.push({ page: p, window: frame === p.mainFrame(), place: placeOf(frame.url()) })
+        // A popup closed; the main window back to the app's page (else nothing could bring it
+        // back: no goto in a desktop app); any other frame blanked.
+        if (frame !== p.mainFrame()) void frame.goto("about:blank").catch(() => undefined)
+        else if (p !== page) void p.close().catch(() => undefined)
+        else {
+          void p
+            .goBack()
+            .then((back) => (back === null ? frame.goto("about:blank") : back))
+            .catch(() => undefined)
+        }
+      }
+      p.on("framenavigated", check)
+      for (const frame of p.frames()) check(frame)
+    }
+    for (const p of context.pages()) watch(p)
+    context.on("page", watch)
+    // Every window at the scene's size, for the whole run (an override ends with its session):
+    // started as a window opens, awaited before the run follows it (`prepare`); a failed attach is
+    // tried again.
+    const emulated = new WeakMap<Page, Promise<void>>()
+    const emulate = (p: Page): Promise<void> => {
+      const known = emulated.get(p)
+      if (known !== undefined) return known
+      const done = (async () => {
+        if (isDevtools(p.url())) return
+        const session: CDPSession = await context.newCDPSession(p)
+        p.once("close", () => void session.detach().catch(() => undefined))
+        await session.send("Emulation.setDeviceMetricsOverride", {
+          width: opts.viewport.width,
+          height: opts.viewport.height,
+          deviceScaleFactor: opts.viewport.deviceScaleFactor,
+          mobile: false,
+        })
+      })()
+      emulated.set(p, done)
+      done.catch(() => emulated.delete(p))
+      return done
+    }
+    await emulate(page)
+    context.on("page", (p) => void emulate(p).catch(() => undefined))
+    return {
+      browser,
+      context,
+      page,
+      sandbox: sandbox.root,
+      allows,
+      stopped: () => stops.splice(0),
+      prepare: (p) => emulate(p),
+      close: end,
+    }
+  } catch (error) {
+    // It quit while being attached (after opening its port): said as such, never Playwright's.
+    // A moment for its exit to be told (it may quit as the attach drops: the drop comes first).
+    const quit = await exitedSoon(child, EXIT_TELL_MS)
+    await end()
+    if (opts.signal?.aborted === true) throw opts.signal.reason as Error
+    if (spawnError !== undefined) {
+      throw new ElectronLaunchError(`the app couldn't be launched (${spawnError.message})`)
+    }
+    if (quit && !(error instanceof ElectronLaunchError)) throw new ElectronLaunchError(QUIT_EARLY)
+    throw error
+  }
+}
+
+/** Where a page is, said without its full address (a path or query may hold a token). */
+export function placeOf(url: string): string {
+  const parsed = URL.parse(url)
+  if (parsed === null) return "an unreadable address"
+  if (parsed.protocol === "file:") return "a file on this computer"
+  return parsed.host === "" ? `a ${parsed.protocol} page` : parsed.host
+}
+
+/** The app's debugging endpoint, read whole: from its output's line, else its profile's file. */
+function debuggingEndpoint(
+  child: ChildProcess,
+  profile: string,
+  deadline: number,
+  signal: AbortSignal | undefined,
+  spawnError: () => Error | undefined,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let output = ""
+    const finish = (error?: Error, endpoint?: string) => {
+      clearTimeout(timer)
+      clearInterval(poll)
+      child.stderr?.removeAllListeners("data")
+      child.removeListener("exit", exited)
+      signal?.removeEventListener("abort", aborted)
+      if (error !== undefined) reject(error)
+      else resolve(endpoint as string)
+    }
+    child.stderr?.on("data", (chunk: Buffer) => {
+      output = (output + chunk.toString("utf8")).slice(-8192)
+      // A whole line only (a chunk may end mid-address), on this machine only.
+      const found =
+        /DevTools listening on (ws:\/\/127\.0\.0\.1:\d+\/devtools\/browser\/[0-9a-f-]+)\r?\n/.exec(
+          output,
+        )?.[1]
+      if (found !== undefined) finish(undefined, found)
+    })
+    // The profile's own file, inside the sandbox (never one elsewhere: an app that ignores
+    // --user-data-dir would write it where Kiframe never reads), read whole.
+    const poll = setInterval(() => {
+      const failed = spawnError()
+      if (failed !== undefined) {
+        finish(new ElectronLaunchError(`the app couldn't be launched (${failed.message})`))
+        return
+      }
+      try {
+        const [port, path] = readFileSync(join(profile, "DevToolsActivePort"), "utf8").split("\n")
+        if (
+          port !== undefined &&
+          /^\d+$/.test(port) &&
+          path !== undefined &&
+          /^\/devtools\/browser\/[0-9a-f-]+$/.test(path)
+        ) {
+          finish(undefined, `ws://127.0.0.1:${port}${path}`)
+        }
+      } catch {
+        // not yet
+      }
+    }, 100)
+    const exited = () => finish(new ElectronLaunchError(QUIT_EARLY))
+    const aborted = () => finish(signal?.reason as Error)
+    child.once("exit", exited)
+    signal?.addEventListener("abort", aborted, { once: true })
+    const timer = setTimeout(
+      () =>
+        finish(
+          new ElectronLaunchError(
+            "the app opened no debugging port in time (it may refuse automation)",
+          ),
+        ),
+      Math.max(0, deadline - Date.now()),
+    )
+  })
+}
+
+const isDevtools = (url: string) => url.startsWith("devtools://")
+
+/**
+ * The app's main window, once it settled: its windows unchanged for a moment (a splash that closed
+ * is gone), the last-opened one still open, loaded (an address and its document).
+ */
+async function mainWindow(
+  context: BrowserContext,
+  deadline: number,
+  signal: AbortSignal | undefined,
+  gone: () => boolean,
+): Promise<Page> {
+  const windows = () => context.pages().filter((p) => !isDevtools(p.url()) && !p.isClosed())
+  let seen = ""
+  let since = Date.now()
+  for (;;) {
+    signal?.throwIfAborted()
+    // Quit (or dropped its port) before showing a window: said at once, never a wait to the end.
+    if (gone()) throw new ElectronLaunchError(QUIT_EARLY)
+    const now = windows()
+    const key = now.map((p) => p.url()).join("\n")
+    if (key !== seen) {
+      seen = key
+      since = Date.now()
+    }
+    const last = now.at(-1)
+    const loaded = last !== undefined && last.url() !== "" && last.url() !== "about:blank"
+    if (loaded && Date.now() - since >= SETTLE_MS) {
+      await last
+        .waitForLoadState("domcontentloaded", { timeout: Math.max(1, deadline - Date.now()) })
+        .catch(() => undefined)
+      if (!last.isClosed()) return last
+    }
+    if (Date.now() >= deadline) throw new ElectronLaunchError("the app opened no window in time")
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+}
+
+/** A loopback http(s) page's origin (a dev server the app loads), if it is one. */
+function loopbackOrigin(url: string): string | undefined {
+  const parsed = URL.parse(url)
+  if (parsed === null || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) return
+  return ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname) ? parsed.origin : undefined
+}
+
+/** The schemes Chromium itself serves (never an app's own content: another site's, the browser's). */
+const BUILT_IN = new Set([
+  "about:",
+  "blob:",
+  "chrome:",
+  "chrome-error:",
+  "chrome-extension:",
+  "chrome-untrusted:",
+  "data:",
+  "devtools:",
+  "file:",
+  "filesystem:",
+  "http:",
+  "https:",
+  "javascript:",
+  "view-source:",
+  "ws:",
+  "wss:",
+])
+
+/** A page's scheme if it's an app's own (`app:`, `vscode-file:`): none of Chromium's. */
+function ownScheme(url: string): string | undefined {
+  const parsed = URL.parse(url)
+  return parsed === null || BUILT_IN.has(parsed.protocol) ? undefined : parsed.protocol
+}
+
+/**
+ * Whether a page is the app's own: a blank page; a local `file:` inside its bundle or its sandbox
+ * (never the user's files); a loopback origin or an own scheme (`app:`) its windows first showed;
+ * one of its sites (`origins`, as one site: `sameApp`); a blob made by one of those. Anything else
+ * (another site, Chromium's own pages, a site's `filesystem:`) isn't.
+ */
+export function allowedPage(
+  url: string,
+  own: {
+    bundles: readonly string[]
+    sandbox: string
+    launched: ReadonlySet<string>
+    schemes: ReadonlySet<string>
+    origins: readonly string[]
+  },
+): boolean {
+  if (url === "about:blank") return true
+  const parsed = URL.parse(url)
+  if (parsed === null) return false
+  if (parsed.protocol === "blob:") {
+    // Made by a page of the app's: a file: page's blob (`blob:file:///<id>`) has no path to check,
+    // and only the app's own file: pages run (others are refused before they could make one).
+    const inner = URL.parse(parsed.pathname)
+    if (inner === null) return false
+    return inner.protocol === "file:" ? inner.host === "" : allowedPage(inner.href, own)
+  }
+  if (parsed.protocol === "file:") {
+    // Local only (never a file on another host).
+    if (parsed.host !== "") return false
+    let path: string
+    try {
+      path = decodeURIComponent(parsed.pathname)
+    } catch {
+      return false
+    }
+    // Decoding can make `..` the parser left (`..%2F`): normalized before it's compared.
+    path = posix.normalize(path)
+    const inside = (dir: string) =>
+      path === dir || path.startsWith(dir.endsWith("/") ? dir : `${dir}/`)
+    return own.bundles.some(inside) || inside(own.sandbox)
+  }
+  if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+    return (
+      own.launched.has(parsed.origin) ||
+      // A listed (https) site: `sameApp` one way never takes a plain-http page for it.
+      own.origins.some((site) => sameApp(parsed, site))
+    )
+  }
+  return own.schemes.has(parsed.protocol)
+}
+
+/**
+ * Ends a launch: its group terminated (then killed) while it's known alive (`alive`: its windows
+ * were still connected, or its leader runs: never a group id the system may have given another
+ * program since), what still points at its sandbox, the sandbox.
+ */
+async function stop(
+  child: ChildProcess,
+  sandbox: string,
+  stateFile: string | undefined,
+  alive: boolean,
+): Promise<{ unread: boolean }> {
+  const pid = child.pid
+  const leader = child.exitCode === null && child.signalCode === null
+  let t0 = Date.now()
+  if (pid !== undefined && (leader || alive || (await orphanedGroup(pid)))) {
+    if (leader) {
+      const exited = new Promise((resolve) => child.once("exit", resolve))
+      signalGroup(pid, "SIGTERM")
+      await Promise.race([exited, new Promise((r) => setTimeout(r, QUIT_MS))])
+    }
+    signalGroup(pid, "SIGKILL")
+  }
+  timing("kill", t0)
+  // Helpers that left the group (a daemon, a pty host) still point at the sandbox.
+  t0 = Date.now()
+  const swept = await sweepSandbox(sandbox)
+  timing("sweep", t0)
+  t0 = Date.now()
+  await rm(sandbox, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }).catch(
+    () => undefined,
+  )
+  timing("remove", t0)
+  try {
+    note(stateFile, sandbox, false)
+  } catch {
+    // kept: swept at the next start
+  }
+  return { unread: swept.unread }
+}
+
+/**
+ * Whether `pid`'s group still has members while no process holds `pid` itself: the group of a
+ * leader that died (a recycled id would be alive as that id, never "a group without its leader").
+ */
+async function orphanedGroup(pid: number): Promise<boolean> {
+  const table = await run("ps", ["-axo", "pid=,pgid="])
+  if (table === undefined) return false
+  let members = 0
+  for (const line of table.split("\n")) {
+    const [p, g] = line.trim().split(/\s+/).map(Number)
+    if (p === pid) return false
+    if (g === pid) members++
+  }
+  return members > 0
+}
+
+function signalGroup(pid: number, signal: NodeJS.Signals) {
+  try {
+    process.kill(-pid, signal)
+  } catch {
+    // gone
+  }
+}
+
+/** A command's output (empty when it fails: said by the caller's next check). */
+function run(command: string, args: string[]): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    execFile(command, args, { timeout: 5000, maxBuffer: 16 * 1024 * 1024 }, (error, stdout) => {
+      // lsof exits 1 when nothing matches: its output (empty) is still the answer.
+      resolve(error !== null && (error as { code?: unknown }).code !== 1 ? undefined : stdout)
+    })
+  })
+}
+
+/**
+ * Every process's working folder: Linux's /proc (quick), else `lsof` (macOS: no /proc); undefined
+ * when it can't be read.
+ */
+async function workingDirs(): Promise<[number, string][] | undefined> {
+  if (process.platform === "linux") {
+    const out: [number, string][] = []
+    try {
+      for (const entry of await readdir("/proc")) {
+        if (!/^\d+$/.test(entry)) continue
+        try {
+          out.push([Number(entry), await readlink(`/proc/${entry}/cwd`)])
+        } catch {
+          // gone, or another user's
+        }
+      }
+      return out
+    } catch {
+      return undefined
+    }
+  }
+  const listed = await run("lsof", ["-a", "-d", "cwd", "-Fpn"])
+  if (listed === undefined) return undefined
+  const out: [number, string][] = []
+  let pid: number | undefined
+  for (const line of listed.split("\n")) {
+    if (line.startsWith("p")) pid = Number(line.slice(1))
+    else if (line.startsWith("n") && pid !== undefined) out.push([pid, line.slice(1)])
+  }
+  return out
+}
+
+/**
+ * Kills every process (never this one) that points at `sandbox`: its command line names it (the
+ * app's helpers carry `--user-data-dir=<sandbox>/profile`), or it works in it (a helper detached
+ * with its cwd there). Both are quick to read (never a walk of every file). Unread: said.
+ */
+export async function sweepSandbox(sandbox: string): Promise<{ swept: number; unread: boolean }> {
+  if (!existsSync(sandbox)) return { swept: 0, unread: false }
+  const [ps, cwds] = await Promise.all([run("ps", ["-axo", "pid=,command="]), workingDirs()])
+  const pids = new Set<number>()
+  const within = (path: string) => path === sandbox || path.startsWith(`${sandbox}/`)
+  for (const line of ps?.split("\n") ?? []) {
+    const match = /^\s*(\d+)\s+(.*)$/.exec(line)
+    if (match !== null && match[2]?.includes(sandbox) === true) pids.add(Number(match[1]))
+  }
+  for (const [pid, cwd] of cwds ?? []) if (within(cwd)) pids.add(pid)
+  pids.delete(process.pid)
+  for (const p of pids) {
+    try {
+      process.kill(p, "SIGKILL")
+    } catch {
+      // gone
+    }
+  }
+  return { swept: pids.size, unread: ps === undefined || cwds === undefined }
+}
+
+/** Adds (or removes) a running launch's sandbox in the state file. */
+function note(stateFile: string | undefined, sandbox: string, running: boolean) {
+  if (stateFile === undefined) return
+  const all = readState(stateFile).filter((s) => s !== sandbox)
+  if (running) all.push(sandbox)
+  writeFileSync(stateFile, JSON.stringify(all))
+}
+
+/** A sandbox this module made: a `kiframe-app-*` folder directly in the temp folder, nothing else. */
+function isSandbox(path: string): boolean {
+  try {
+    const real = realpathSync(path)
+    return dirname(real) === realpathSync(tmpdir()) && basename(real).startsWith("kiframe-app-")
+  } catch {
+    return false
+  }
+}
+
+function readState(stateFile: string): string[] {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(stateFile, "utf8"))
+    return Array.isArray(parsed) ? parsed.filter((s): s is string => typeof s === "string") : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * What a crash left (launches still noted): every process pointing at their sandboxes killed (by
+ * the sandbox, never a process id that may be another program's by now), the sandboxes removed.
+ * Only folders this module makes are touched. Called at the host's start.
+ */
+export async function sweepElectronOrphans(stateFile: string): Promise<number> {
+  const left = readState(stateFile).filter(isSandbox)
+  for (const sandbox of left) {
+    await sweepSandbox(sandbox)
+    await rm(sandbox, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }).catch(
+      () => undefined,
+    )
+  }
+  // Only what was swept: a launch noted meanwhile (a run started during the sweep) stays.
+  const now = readState(stateFile).filter((s) => !left.includes(s))
+  writeFileSync(stateFile, JSON.stringify(now))
+  return left.length
+}
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index 8266d76..0c1a248 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -8,6 +8,14 @@ export * from "./recorder.ts"
 export * from "./runner.ts"
 export * from "./scanner.ts"
 export { type CastFrame, watchScreencast } from "./screencast.ts"
+export {
+  allowedPage,
+  type ElectronLaunch,
+  ElectronLaunchError,
+  type ElectronTarget,
+  launchElectron,
+  sweepElectronOrphans,
+} from "./electron.ts"
 export { LookRefusal, maskedScreenshot, type MaskedShot } from "./look.ts"
 export {
   fitImage,
diff --git a/packages/runtime/src/run/actions.ts b/packages/runtime/src/run/actions.ts
index 7145a4f..c16f644 100644
--- a/packages/runtime/src/run/actions.ts
+++ b/packages/runtime/src/run/actions.ts
@@ -66,7 +66,9 @@ export async function perform(ctx: Ctx, action: AnyAction, step: StepRef): Promi
   switch (action.action) {
     case "goto": {
       // The app it names, else the one its step means (its scene's or its preset's).
-      const base = new URL(webAppNamed(ctx.apps, action.app ?? ctx.app, step, "a goto").url)
+      const base = new URL(
+        webAppNamed(ctx.apps, action.app ?? ctx.app, step, "a goto", ctx.options.electron?.app).url,
+      )
       const url = new URL(action.url, base)
       // Enforced here too (not only by the schema): a goto never leaves its app.
       if (url.origin !== base.origin) {
diff --git a/packages/runtime/src/run/apps.ts b/packages/runtime/src/run/apps.ts
index 144939d..4cfbf58 100644
--- a/packages/runtime/src/run/apps.ts
+++ b/packages/runtime/src/run/apps.ts
@@ -1,5 +1,6 @@
 import { type App, type Apps, appOf, sameApp, type WebApp, webAppsOf } from "@kiframe/schema"
 import type { Ctx } from "./context.ts"
+import { placeOf } from "../electron.ts"
 import { StepError, type StepRef } from "../errors.ts"
 
 // The project's apps a scene moves between (OBJECT-MODEL §0.9). Which app a step means is read
@@ -21,7 +22,22 @@ export function appNamed(apps: Apps, name: string, step: StepRef): App {
  * A web app by its name, for what needs an address (a goto, a URL condition): a desktop app has
  * none (it starts where it opens: steps move in it by clicking), refused saying so.
  */
-export function webAppNamed(apps: Apps, name: string, step: StepRef, what: string): WebApp {
+export function webAppNamed(
+  apps: Apps,
+  name: string,
+  step: StepRef,
+  what: string,
+  electron?: string,
+): WebApp {
+  // A desktop app's run has that one app: its window never goes to a site (a page loaded in it
+  // runs with the app's own privileges).
+  if (electron !== undefined) {
+    throw new StepError(
+      step,
+      "invalid-setup",
+      `${what} can't run in a desktop app's scene: it stays in "${electron}" (move in it by clicking)`,
+    )
+  }
   const app = appNamed(apps, name, step)
   if (app.kind !== "web") {
     throw new StepError(
@@ -59,6 +75,54 @@ export function onApps(apps: Apps, url: string): boolean {
  * a moment first; a stop ends the wait as a stop.
  */
 export async function confine(ctx: Ctx, step: StepRef): Promise<void> {
+  // A desktop app's run: its own pages only (its guard stopped any other at once), never a web
+  // app's (one app per run: its window never shows a site).
+  const electron = ctx.options.electron
+  if (electron !== undefined) {
+    // A stop counts against the step when it was the driven window's (or a frame in it), or a
+    // window itself (one the step opened, sent back); a frame of another window is said only.
+    const stops = electron.stopped()
+    for (const s of stops) {
+      if (s.page !== ctx.page && !s.window) {
+        ctx.options.onEvent?.({
+          kind: "warning",
+          message: `a frame of another window of "${electron.app}" went to ${s.place}: Kiframe stopped it`,
+        })
+      }
+    }
+    const went = stops.filter((s) => s.page === ctx.page || s.window)
+    if (went.length > 0) {
+      throw new StepError(
+        step,
+        "off-app",
+        `the app's window went to ${went[0]?.place ?? ""}, not the app's own (Kiframe stopped it): if it's the app's, list it in the app's origins; else keep the scene in "${electron.app}"`,
+      )
+    }
+    // A window that opens blank and loads after some setup gets a moment (as a web page does).
+    const until = Date.now() + BACK_MS
+    while (ctx.page.url() === "about:blank" && Date.now() < until && !ctx.page.isClosed()) {
+      await new Promise((resolve) => setTimeout(resolve, 100))
+    }
+    const now = ctx.page.url()
+    if (now.startsWith("chrome-error:")) {
+      throw new StepError(step, "action-failed", "the page failed to load")
+    }
+    // Still blank (stopped with nothing to go back to): said, never silent.
+    if (now === "about:blank") {
+      throw new StepError(
+        step,
+        "off-app",
+        `the app's window is blank (Kiframe stopped a page that wasn't the app's, or it never loaded): relaunch "${electron.app}"`,
+      )
+    }
+    if (electron.allows(now)) return
+    throw new StepError(
+      step,
+      "off-app",
+      `the app's window is on ${placeOf(now)}, not the app's own: if it's the app's, list it in the app's origins; else keep the scene in "${electron.app}"`,
+    )
+  }
+
   const until = Date.now() + BACK_MS
   for (;;) {
     const now = ctx.page.url()
@@ -73,12 +137,7 @@ export async function confine(ctx: Ctx, step: StepRef): Promise<void> {
       throw new StepError(step, "stopped", "the run was stopped")
     }
     if (Date.now() >= until || ctx.page.isClosed()) {
-      const where =
-        url === null
-          ? "an unreadable address"
-          : url.host === ""
-            ? `a ${url.protocol} page`
-            : url.host
+      const where = placeOf(now)
       throw new StepError(
         step,
         "off-app",
diff --git a/packages/runtime/src/run/conditions.ts b/packages/runtime/src/run/conditions.ts
index b5d82c8..ff97451 100644
--- a/packages/runtime/src/run/conditions.ts
+++ b/packages/runtime/src/run/conditions.ts
@@ -1,4 +1,4 @@
-import { type Condition, sameApp } from "@kiframe/schema"
+import { type Action, type Condition, sameApp } from "@kiframe/schema"
 import { StepError, type StepRef } from "../errors.ts"
 import { EXACT_NAMES_HINT, ProbeRefusal } from "../secret-state.ts"
 import type { Locator as SchemaLocator } from "@kiframe/schema"
@@ -49,7 +49,13 @@ export async function waitForCondition(
       })
     } else if ("url" in condition) {
       // Relative to the app it names, else the one its step means.
-      const app = webAppNamed(ctx.apps, condition.app ?? ctx.app, step, "a URL condition")
+      const app = webAppNamed(
+        ctx.apps,
+        condition.app ?? ctx.app,
+        step,
+        "a URL condition",
+        ctx.options.electron?.app,
+      )
       const expected = new URL(condition.url, app.url)
       await page.waitForURL((url) => urlMatches(url, expected), { timeout })
     } else if (!(await ctx.network.waitForIdle(timeout))) {
@@ -174,3 +180,12 @@ export async function pollLocator(
     await new Promise((resolve) => setTimeout(resolve, 100))
   }
 }
+
+/** The condition an action carries (a waitFor's `until`, an expect's `that`), if any. */
+export function conditionOf(action: Action): Condition | undefined {
+  return action.action === "waitFor"
+    ? action.until
+    : action.action === "expect"
+      ? action.that
+      : undefined
+}
diff --git a/packages/runtime/src/run/context.ts b/packages/runtime/src/run/context.ts
index b712529..93f50fe 100644
--- a/packages/runtime/src/run/context.ts
+++ b/packages/runtime/src/run/context.ts
@@ -1,6 +1,7 @@
 import type { Action, Apps, ProjectConfig, Step } from "@kiframe/schema"
 import type { ElementHandle, Locator, Page } from "playwright"
 import { type ApprovalRequest, type SecretUse, StepError, type StepRef } from "../errors.ts"
+import type { ElectronTarget } from "../electron.ts"
 import type { HandoverRequest } from "./handover.ts"
 import type { Box, CursorPacing, Point, TypingPacing } from "../motion.ts"
 import type { NetworkTracker } from "../network.ts"
@@ -127,6 +128,11 @@ export interface RunOptions {
    * (a replay, a recording); off for a step grounded on the live page, which says where it went.
    */
   confineToApps?: boolean
+  /**
+   * The desktop app this run's page belongs to (its target, `launchElectron`): a scene starting in
+   * it runs only with it, and its pages (`allows`) are the app's own. None: no desktop app runs.
+   */
+  electron?: { app: string } & Pick<ElectronTarget, "allows" | "stopped" | "prepare">
   /** The org interrupt rules this run's config kept from the org (their approvals are the org's). */
   orgInterrupts?: { orgId: string; ruleIds: readonly string[] }
   /** Resolves an `upload` step's project asset (`<sha256>.<ext>`) to a file path. */
diff --git a/packages/runtime/src/run/interrupts.ts b/packages/runtime/src/run/interrupts.ts
index 4f43828..3a98306 100644
--- a/packages/runtime/src/run/interrupts.ts
+++ b/packages/runtime/src/run/interrupts.ts
@@ -1,4 +1,5 @@
 import { firstApp, type ProjectConfig } from "@kiframe/schema"
+import { conditionOf } from "./conditions.ts"
 import type { Page } from "playwright"
 import { StepError, type StepRef } from "../errors.ts"
 import {
@@ -82,12 +83,39 @@ const skippedRulesOf = new WeakMap<object, Set<string>>()
 
 const exactRulesOf = new WeakMap<object, Set<string>>()
 
+/** Whether an action needs a web app's address: a goto, a wait or a check on a URL. */
+function needsAddress(action: ProjectConfig["interrupts"][number]["do"]): boolean {
+  if (action.action === "goto") return true
+  const condition = conditionOf(action)
+  return condition !== undefined && "url" in condition
+}
+
+/**
+ * Whether a rule can run in this run: in a desktop app's run, never one whose `do` goes to an
+ * address (a web app's rule: its window stays in the app), skipped with one warning.
+ */
+function runsHere(ctx: Ctx, rule: ProjectConfig["interrupts"][number]): boolean {
+  if (ctx.options.electron === undefined || !needsAddress(rule.do)) return true
+  // Said once per browser context (as other skipped rules).
+  const context = ctx.page.context()
+  const skippedRules = skippedRulesOf.get(context) ?? new Set<string>()
+  skippedRulesOf.set(context, skippedRules)
+  if (!skippedRules.has(`electron:${rule.id}`)) {
+    skippedRules.add(`electron:${rule.id}`)
+    ctx.options.onEvent?.({
+      kind: "warning",
+      message: `interrupt rule "${rule.id}" is skipped in the desktop app: it needs a web app's address`,
+    })
+  }
+  return false
+}
+
 /** The first rule (in order, not in `skip`) whose `when` is visible right now (no waiting). */
 async function matchingInterrupt(
   ctx: Ctx,
   skip: ReadonlySet<string>,
 ): Promise<ProjectConfig["interrupts"][number] | undefined> {
-  const rules = ctx.interrupts.filter((r) => !skip.has(r.id))
+  const rules = ctx.interrupts.filter((r) => !skip.has(r.id) && runsHere(ctx, r))
   // The exact-names rule (§3 A8) decided once for all the rules.
   const names = await exactNamesFor(
     ctx.page,
diff --git a/packages/runtime/src/run/pages.ts b/packages/runtime/src/run/pages.ts
index 4c8bb84..b99c4f4 100644
--- a/packages/runtime/src/run/pages.ts
+++ b/packages/runtime/src/run/pages.ts
@@ -75,6 +75,22 @@ async function switchTo(ctx: Ctx, next: Page, step: StepRef): Promise<void> {
   })
 }
 
+/**
+ * A desktop app's window made ready before the run follows it (at the scene's size: never read or
+ * filmed at its own); false when it closed meanwhile (its guard closed it: the run stays).
+ */
+async function ready(ctx: Ctx, next: Page, step: StepRef): Promise<boolean> {
+  const prepare = ctx.options.electron?.prepare
+  if (prepare === undefined) return true
+  try {
+    await prepare(next)
+    return true
+  } catch (error) {
+    if (next.isClosed()) return false
+    throw new StepError(step, "action-failed", firstLine(error), { cause: error })
+  }
+}
+
 /**
  * Brings the driven page in line with the browser, at a step boundary (the one place pages change):
  * 1. the driven page closed (a popup's "Done", an OAuth window): back to the nearest open opener;
@@ -95,6 +111,13 @@ export async function syncPage(ctx: Ctx, step: StepRef): Promise<void> {
         "the page was closed and there's no page to return to",
       )
     }
+    if (!(await ready(ctx, back, step))) {
+      throw new StepError(
+        step,
+        "page-closed",
+        "the page was closed and there's no page to return to",
+      )
+    }
     await switchPage(ctx, back, step)
     // The opener reacts (an OAuth callback loads the app): settled before going on.
     await guard(step, () => settle(ctx, step.phase === "steps"))
@@ -109,6 +132,7 @@ export async function syncPage(ctx: Ctx, step: StepRef): Promise<void> {
     throw new StepError(step, "action-failed", firstLine(error), { cause: error })
   }
   if (next.isClosed()) return
+  if (!(await ready(ctx, next, step))) return
   ctx.openers.push(ctx.page)
   await switchPage(ctx, next, step)
   // Settled like any page an action led to (its data may load after DOMContentLoaded).
diff --git a/packages/runtime/src/run/setup.ts b/packages/runtime/src/run/setup.ts
index fc381a1..8c4a25c 100644
--- a/packages/runtime/src/run/setup.ts
+++ b/packages/runtime/src/run/setup.ts
@@ -2,6 +2,7 @@ import { Action, appOf, firstApp, type ProjectConfig, type SetupItem } from "@ki
 import { StepError, type StepRef } from "../errors.ts"
 import { type Ctx, guard, type SessionLanding } from "./context.ts"
 import { syncPage } from "./pages.ts"
+import { conditionOf } from "./conditions.ts"
 import { runOne } from "./step.ts"
 
 // Setup: presets inlined (session presets skipped or replaced by their landing). An `ensure` (from
@@ -43,7 +44,7 @@ export function sessionChecks(steps: readonly (Action | { ensure: unknown })[]):
  */
 export function checksSignedIn(steps: readonly (Action | { ensure: unknown })[]): boolean {
   return sessionChecks(steps).some((c) => {
-    const condition = c.action === "waitFor" ? c.until : c.action === "expect" ? c.that : undefined
+    const condition = conditionOf(c)
     return condition !== undefined && ("visible" in condition || "text" in condition)
   })
 }
@@ -70,6 +71,8 @@ export function expandSetup(
   skip: readonly string[],
   landings: Readonly<Record<string, SessionLanding>>,
   start: string,
+  /** The desktop app this run was launched in (its presets run there); none: no desktop app runs. */
+  electronApp?: string,
 ): SetupEntry[] {
   const out: SetupEntry[] = []
   // Setup indexes count actions and ensures only (`preset_done` is a marker, not a step).
@@ -85,9 +88,14 @@ export function expandSetup(
       const from = { name: item.preset, session: preset.session }
       // Its steps run in its app (the first by default): a desktop app has its own driver (next).
       const runsIn = preset.app ?? firstApp(project).name
-      if (appOf(project, runsIn)?.kind !== "web") {
+      // A desktop app's run has that one app: its presets run there, never a web app's.
+      if (
+        electronApp !== undefined ? runsIn !== electronApp : appOf(project, runsIn)?.kind !== "web"
+      ) {
         throw invalid(
-          `preset "${item.preset}" runs in "${runsIn}", a desktop app: Kiframe can't run steps in desktop apps yet (give the preset a web app: \`app:\`)`,
+          electronApp !== undefined
+            ? `preset "${item.preset}" runs in "${runsIn}": a scene in the desktop app "${electronApp}" stays in it (give the preset \`app: ${electronApp}\`)`
+            : `preset "${item.preset}" runs in "${runsIn}", a desktop app this run isn't in (give the preset a web app: \`app:\`, or start the scene in that app)`,
         )
       }
       if (preset.session && skip.includes(item.preset)) {
@@ -171,7 +179,8 @@ export async function runSetupEntry(ctx: Ctx, entry: SetupEntry): Promise<void>
     if (entry.held !== true) {
       ctx.options.onEvent?.({ kind: "preset_done", name: entry.name, session: entry.session })
     }
-    const ready = ctx.options.onSessionReady
+    // A desktop app's sign-in isn't saved between runs yet.
+    const ready = ctx.options.electron === undefined ? ctx.options.onSessionReady : undefined
     if (entry.session && ready !== undefined) {
       // Named after the preset's last step.
       const ref: StepRef = {
diff --git a/packages/runtime/src/run/step.ts b/packages/runtime/src/run/step.ts
index 92c83b0..0d08dff 100644
--- a/packages/runtime/src/run/step.ts
+++ b/packages/runtime/src/run/step.ts
@@ -50,7 +50,10 @@ export async function runOne(
   }
   await syncPage(ctx, step)
   // Where the step ended (the page it left driven: a popup, the opener back): one of the apps.
-  if (ctx.options.confineToApps !== false) await confine(ctx, step)
+  // A desktop app's run is always confined (its window can open the user's files): grounding too.
+  if (ctx.options.confineToApps !== false || ctx.options.electron !== undefined) {
+    await confine(ctx, step)
+  }
   if (ctx.options.recording === true) {
     await followSecretFields(ctx, step)
     // The page as the step left it: not a scan that started earlier in the step.
diff --git a/packages/runtime/src/runner.ts b/packages/runtime/src/runner.ts
index 02e7f54..6301cb4 100644
--- a/packages/runtime/src/runner.ts
+++ b/packages/runtime/src/runner.ts
@@ -49,14 +49,34 @@ export async function runScenario(
   }
   // The scene's start app: what its steps mean when they name no app.
   const started = startAppOf(scenario, project)
-  // A desktop app is launched by its own driver (the Electron target, next): never run on a page.
-  if (started.app.kind !== "web") {
+  // A desktop app runs only in its own target (launched for the run): never on a browser page; and
+  // a target runs only its own app's scene (a web scene never in a desktop app's window).
+  if (options.electron !== undefined && options.electron.app !== started.name) {
     throw new StepError(
       { phase: "setup", index: 0, action: "setup" },
       "invalid-setup",
-      `app "${started.name}" is a desktop app: Kiframe can't run scenes in desktop apps yet`,
+      `the scene starts in "${started.name}", not in the desktop app "${options.electron.app}" it was given`,
     )
   }
+  // A desktop app's sign-in isn't kept between runs yet: its session presets run each time (a
+  // reuse asked for is refused; the hook that would save one is never called).
+  if (options.electron !== undefined && (options.skipSessionPresets?.length ?? 0) > 0) {
+    throw new StepError(
+      { phase: "setup", index: 0, action: "setup" },
+      "invalid-setup",
+      "a desktop app's sign-in isn't kept between runs yet: its session presets run each time",
+    )
+  }
+  if (started.app.kind !== "web" && options.electron === undefined) {
+    throw new StepError(
+      { phase: "setup", index: 0, action: "setup" },
+      "invalid-setup",
+      `app "${started.name}" is a desktop app: it runs only in its own launch (not on a browser page)`,
+    )
+  }
+  // What the app's guard stopped before this run (a step that failed earlier, its launch) is
+  // never this run's.
+  options.electron?.stopped()
   const start = started.name
   const setup = expandSetup(
     scenario.setup ?? [],
@@ -64,6 +84,7 @@ export async function runScenario(
     options.skipSessionPresets ?? [],
     options.sessionLandings ?? {},
     start,
+    options.electron?.app,
   )
   const settleMs = scenario.overrides?.pacing?.settleMs ?? project.defaults.pacing.settleMs
   const network = new NetworkTracker(page)
@@ -87,10 +108,17 @@ export async function runScenario(
     return tracker
   }
   const onPopup = (popup: Page) => {
+    if (opened.includes(popup)) return
     opened.push(popup)
     trackerOf(popup)
     watch(popup)
   }
+  // A desktop app's windows opened by its main process (no opener: no popup event) are followed
+  // as popups are (Preferences from a menu, the main window after a sign-in window).
+  const onAppWindow = (p: Page) => {
+    if (!p.url().startsWith("devtools://") && p !== page) onPopup(p)
+  }
+  if (options.electron !== undefined) page.context().on("page", onAppWindow)
   // Every main-frame navigation is reported (goto, redirects, links clicked…), attributed to the
   // step running at that moment.
   let current: StepRef | undefined
@@ -266,6 +294,7 @@ export async function runScenario(
     await ctx.fieldsInflight?.catch(() => undefined)
     for (const tracker of trackers.values()) tracker.dispose()
     for (const p of watched) p.off("popup", onPopup)
+    page.context().off("page", onAppWindow)
     ctx.detach(ctx.page)
   }
 }
diff --git a/packages/runtime/test/apps.test.ts b/packages/runtime/test/apps.test.ts
index b50a20e..55d8f25 100644
--- a/packages/runtime/test/apps.test.ts
+++ b/packages/runtime/test/apps.test.ts
@@ -542,9 +542,7 @@ defaults: { pacing: { settleMs: 0, cursor: instant, typing: instant } }
     const started = await failure(`app: notes
 steps: [{ id: a, action: pause, ms: 1 }]`)
     expect(started.reason).toBe("invalid-setup")
-    expect(started.message).toMatch(
-      /app "notes" is a desktop app: Kiframe can't run scenes in desktop apps yet/,
-    )
+    expect(started.message).toMatch(/app "notes" is a desktop app: it runs only in its own launch/)
     expect(page.url()).toBe("about:blank")
     // The web app is still its own (a desktop app never matches a page's address).
     await runScenario(
diff --git a/packages/runtime/test/batch.test.ts b/packages/runtime/test/batch.test.ts
index 34a4c96..29e03c6 100644
--- a/packages/runtime/test/batch.test.ts
+++ b/packages/runtime/test/batch.test.ts
@@ -44,7 +44,9 @@ ${steps}`)
 const signedIn = `  - { id: check, action: expect, that: { visible: { by: text, text: Signed in, exact: true } } }\n`
 const signOut = `  - { id: out, action: click, target: { by: role, role: button, name: Sign out } }\n`
 
-describe("recordBatch", () => {
+// Browser launches share the machine with the Electron target's tests: the budget other browser
+// suites use.
+describe("recordBatch", { timeout: 30_000 }, () => {
   const run = async (steps: (string | [string, string])[]) => {
     const dir = mkdtempSync(join(tmpdir(), "kiframe-batch-"))
     const logins: number[] = []
diff --git a/packages/runtime/test/electron.test.ts b/packages/runtime/test/electron.test.ts
new file mode 100644
index 0000000..b4034fe
--- /dev/null
+++ b/packages/runtime/test/electron.test.ts
@@ -0,0 +1,891 @@
+import {
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs"
+import { createRequire } from "node:module"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { parseProjectYaml, parseScenarioYaml } from "@kiframe/schema"
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest"
+import { execFileSync } from "node:child_process"
+import { createServer, type Server } from "node:http"
+import { createServer as createHttpsServer } from "node:https"
+import type { AddressInfo } from "node:net"
+import {
+  allowedPage,
+  ElectronLaunchError,
+  type ElectronTarget,
+  launchElectron,
+  recordScenario,
+  runScenario,
+  StepError,
+  sweepElectronOrphans,
+} from "../src/index.ts"
+
+// The Electron target (OBJECT-MODEL §0.9 "Electron apps"): a fixture desktop app launched in a
+// sandbox with the repo's own Electron, driven and filmed like a web page, ended whole.
+
+const electron = createRequire(join(import.meta.dirname, "../../../apps/desktop/package.json"))(
+  "electron",
+) as string
+const fixture = join(import.meta.dirname, "fixtures/electron-app")
+const viewport = { width: 800, height: 600, deviceScaleFactor: 1 }
+
+const project = parseProjectYaml(`version: 2
+apps:
+  notes: { kind: electron, bundleId: com.kiframe.fixture, viewport: { width: 800, height: 600, deviceScaleFactor: 1 } }
+defaults: { pacing: { settleMs: 0, cursor: instant, typing: instant } }
+`)
+
+const alive = (pid: number) => {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const waitFor = async (check: () => boolean, ms = 5000) => {
+  const until = Date.now() + ms
+  while (!check() && Date.now() < until) await new Promise((r) => setTimeout(r, 50))
+  return check()
+}
+
+// Another site on this machine (never the network): where the fixture's links and windows go.
+let other = ""
+let secure = ""
+let server: Server
+let secureServer: Server
+beforeAll(async () => {
+  // An https site on this machine too (a throwaway certificate, trusted by the fixture only).
+  const certs = mkdtempSync(join(tmpdir(), "kiframe-el-cert-"))
+  execFileSync(
+    "openssl",
+    [
+      "req",
+      "-x509",
+      "-newkey",
+      "rsa:2048",
+      "-nodes",
+      "-days",
+      "1",
+      "-subj",
+      "/CN=127.0.0.1",
+      "-keyout",
+      join(certs, "key.pem"),
+      "-out",
+      join(certs, "cert.pem"),
+    ],
+    { stdio: "ignore" },
+  )
+  secureServer = createHttpsServer(
+    { key: readFileSync(join(certs, "key.pem")), cert: readFileSync(join(certs, "cert.pem")) },
+    (_req, res) => {
+      res.writeHead(200, { "content-type": "text/html" })
+      res.end("<h1>A widget</h1>")
+    },
+  )
+  await new Promise<void>((resolve) => secureServer.listen(0, "127.0.0.1", resolve))
+  secure = `https://127.0.0.1:${(secureServer.address() as AddressInfo).port}/`
+  server = createServer((_req, res) => {
+    res.writeHead(200, { "content-type": "text/html" })
+    res.end("<h1>Another site</h1>")
+  })
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve))
+  other = `http://127.0.0.1:${(server.address() as AddressInfo).port}/`
+})
+afterAll(async () => {
+  await new Promise<void>((resolve) => server.close(() => resolve()))
+  await new Promise<void>((resolve) => secureServer.close(() => resolve()))
+})
+
+/** A run's desktop app: the fixture's target, as the host gives it to the runner. */
+const inTarget = (target: ElectronTarget) => ({
+  app: "notes",
+  allows: target.allows,
+  stopped: target.stopped,
+  prepare: target.prepare,
+})
+
+let open: ElectronTarget[] = []
+const launch = async (extra: string[] = [], options: { stateFile?: string } = {}) => {
+  const target = await launchElectron({
+    executable: electron,
+    bundle: fixture,
+    args: [fixture, "hidden", `link=${other}`, ...extra],
+    viewport,
+    ...options,
+  })
+  open.push(target)
+  return target
+}
+// Closing sweeps the system's process table: a slow CI machine gets room.
+afterEach(async () => {
+  for (const target of open) await target.close()
+  open = []
+}, 30_000)
+
+/** What the fixture says it saw at start (written into its own data folder). */
+const seenBy = async (target: ElectronTarget) => {
+  const file = join(target.sandbox, "profile", "seen.json")
+  await waitFor(() => existsSync(file))
+  return JSON.parse(readFileSync(file, "utf8")) as {
+    env: string[]
+    home: string
+    userData: string
+    args: string[]
+  }
+}
+
+describe("a desktop app's launch", { timeout: 60_000 }, () => {
+  it("runs in its own sandbox: its home, its data, never Kiframe's environment", async () => {
+    process.env.KIFRAME_TEST_SECRET = "sk-never-for-the-app"
+    process.env.NODE_OPTIONS = "--inspect"
+    // Linux's display reaches the app (never a window without it); macOS ignores it.
+    const display = process.env.DISPLAY
+    process.env.DISPLAY ??= ":kiframe-test"
+    try {
+      const target = await launch()
+      const seen = await seenBy(target)
+      expect(seen.home).toBe(join(target.sandbox, "home"))
+      // Its data in the sandbox (--user-data-dir). Electron's appData and macOS preferences stay
+      // the user's (found 2026-10-08: neither HOME nor CFFIXED_USER_HOME moves them): the trial
+      // launch checks an app keeps its state in the sandbox.
+      expect(seen.userData).toBe(join(target.sandbox, "profile"))
+      expect(seen.env).not.toContain("KIFRAME_TEST_SECRET")
+      expect(seen.env).not.toContain("NODE_OPTIONS")
+      expect(seen.env.filter((e) => e.startsWith("ELECTRON_"))).toEqual([])
+      expect(seen.env).toEqual(
+        expect.arrayContaining(["HOME", "CFFIXED_USER_HOME", "TMPDIR", "DISPLAY"]),
+      )
+      // The project's arguments come before Kiframe's switches, as given.
+      expect(seen.args.slice(0, 3)).toEqual([fixture, "hidden", `link=${other}`])
+    } finally {
+      delete process.env.KIFRAME_TEST_SECRET
+      delete process.env.NODE_OPTIONS
+      if (display === undefined) delete process.env.DISPLAY
+      else process.env.DISPLAY = display
+    }
+  })
+
+  it("is driven like a web page, at the scene's size, its window hidden", async () => {
+    const target = await launch()
+    await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1
+steps:
+  - { id: add, action: click, target: { by: role, role: button, name: Add note } }
+  - { id: one, action: expect, that: { text: "Notes: 1" } }
+  - { id: wide, action: expect, that: { text: "Width: 800" } }
+  - { id: open, action: click, target: { by: role, role: link, name: Settings } }
+  - { id: there, action: expect, that: { visible: { by: role, role: heading, name: Settings } } }
+`),
+      project,
+      {
+        electron: inTarget(target),
+        timeoutMs: 5000,
+      },
+    )
+  })
+
+  it("never lets a step leave the app: the user's files, a website", async () => {
+    for (const name of ["Hosts file", "A website"]) {
+      const target = await launch()
+      const error = await runScenario(
+        target.page,
+        parseScenarioYaml(`version: 1
+steps:
+  - { id: out, action: click, target: { by: role, role: link, name: ${name} } }
+`),
+        project,
+        {
+          electron: inTarget(target),
+          timeoutMs: 5000,
+        },
+      ).then(
+        () => undefined,
+        (e: unknown) => e,
+      )
+      expect(error, name).toBeInstanceOf(StepError)
+      expect((error as StepError).reason, name).toBe("off-app")
+    }
+  })
+
+  it("makes a window the app opens ready before the run follows it", async () => {
+    const target = await launch()
+    const order: string[] = []
+    await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1
+steps:
+  - { id: open, action: click, target: { by: role, role: button, name: Open settings window } }
+  - { id: there, action: expect, that: { text: "Settings width: 800" } }
+`),
+      project,
+      {
+        electron: {
+          app: "notes",
+          allows: target.allows,
+          stopped: target.stopped,
+          prepare: async (p) => {
+            order.push("prepare")
+            await target.prepare(p)
+          },
+        },
+        onPageSwitch: () => {
+          order.push("switch")
+          return Promise.resolve()
+        },
+        timeoutMs: 5000,
+      },
+    )
+    expect(order).toEqual(["prepare", "switch"])
+  })
+
+  it("follows a window the app opens, at the scene's size; runs a preset in it", async () => {
+    const target = await launch()
+    const withPreset = parseProjectYaml(`version: 2
+apps:
+  notes: { kind: electron, bundleId: com.kiframe.fixture, viewport: { width: 800, height: 600, deviceScaleFactor: 1 } }
+presets:
+  one: { steps: [{ action: click, target: { by: role, role: button, name: Add note } }] }
+defaults: { pacing: { settleMs: 0, cursor: instant, typing: instant } }
+`)
+    await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1
+setup: [{ preset: one }]
+steps:
+  - { id: one, action: expect, that: { text: "Notes: 1" } }
+  - { id: open, action: click, target: { by: role, role: button, name: Open settings window } }
+  - { id: there, action: expect, that: { text: "Settings width: 800" } }
+`),
+      withPreset,
+      {
+        electron: inTarget(target),
+        timeoutMs: 5000,
+      },
+    )
+  })
+
+  it("never runs a web scene in a desktop app's window", async () => {
+    const target = await launch()
+    const both = parseProjectYaml(`version: 2
+apps:
+  web: { kind: web, url: "https://app.test" }
+  notes: { kind: electron, bundleId: com.kiframe.fixture }
+`)
+    const error = await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1\nsteps: [{ id: a, action: pause, ms: 1 }]\n`),
+      both,
+      { electron: inTarget(target) },
+    ).then(
+      () => undefined,
+      (e: unknown) => e,
+    )
+    expect((error as StepError).message).toMatch(
+      /the scene starts in "web", not in the desktop app "notes" it was given/,
+    )
+  })
+
+  it("is filmed like a web page", async () => {
+    const target = await launch()
+    const out = join(mkdtempSync(join(tmpdir(), "kiframe-el-take-")), "take")
+    const take = await recordScenario(
+      target.page,
+      parseScenarioYaml(`version: 1
+steps:
+  - { id: add, action: click, target: { by: role, role: button, name: Add note } }
+  - { id: one, action: expect, that: { text: "Notes: 1" } }
+`),
+      project,
+      {
+        outDir: out,
+        sceneId: "notes",
+        electron: inTarget(target),
+      },
+    )
+    expect(take.meta.appUrl).toBe("electron:com.kiframe.fixture")
+    expect(existsSync(join(take.dir, "frames.webm"))).toBe(true)
+  })
+
+  it("ends whole: the app, a helper it detached, its sandbox", async () => {
+    const target = await launch()
+    const pidFile = join(target.sandbox, "profile", "helper.pid")
+    expect(await waitFor(() => existsSync(pidFile))).toBe(true)
+    const helper = Number(readFileSync(pidFile, "utf8"))
+    const groupedFile = join(target.sandbox, "profile", "grouped.pid")
+    expect(await waitFor(() => existsSync(groupedFile))).toBe(true)
+    const grouped = Number(readFileSync(groupedFile, "utf8"))
+    expect(alive(helper)).toBe(true)
+    expect(alive(grouped)).toBe(true)
+    await target.close()
+    open = []
+    // Detached (found by the sandbox it holds) and in the app's group (killed with it).
+    expect(await waitFor(() => !alive(helper))).toBe(true)
+    expect(await waitFor(() => !alive(grouped))).toBe(true)
+    expect(existsSync(target.sandbox)).toBe(false)
+  })
+
+  it("ends a group whose main process already died (its children never outlive it)", async () => {
+    const target = await launch()
+    const file = (name: string) => join(target.sandbox, "profile", name)
+    expect(
+      await waitFor(() => existsSync(file("main.pid")) && existsSync(file("grouped.pid"))),
+    ).toBe(true)
+    const main = Number(readFileSync(file("main.pid"), "utf8"))
+    const grouped = Number(readFileSync(file("grouped.pid"), "utf8"))
+    process.kill(main, "SIGKILL")
+    expect(await waitFor(() => !alive(main))).toBe(true)
+    expect(alive(grouped)).toBe(true)
+    await target.close()
+    open = []
+    expect(await waitFor(() => !alive(grouped))).toBe(true)
+  })
+
+  it("never leaves an app running when its launch can't be noted", async () => {
+    const before = readdirSync(tmpdir()).filter((d) => d.startsWith("kiframe-app-")).length
+    await expect(
+      launch([], { stateFile: join(tmpdir(), "no-such-folder-x", "launches.json") }),
+    ).rejects.toThrow()
+    expect(readdirSync(tmpdir()).filter((d) => d.startsWith("kiframe-app-")).length).toBe(before)
+  })
+
+  it("takes a bundle given through a link (its pages report either path)", async () => {
+    const link = join(mkdtempSync(join(tmpdir(), "kiframe-el-link-")), "Fixture.app")
+    symlinkSync(fixture, link)
+    const target = await launchElectron({
+      executable: electron,
+      bundle: link,
+      args: [link, "hidden"],
+      viewport,
+    })
+    open.push(target)
+    await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1
+steps:
+  - { id: open, action: click, target: { by: role, role: link, name: Settings } }
+  - { id: there, action: expect, that: { visible: { by: role, role: heading, name: Settings } } }
+`),
+      project,
+      {
+        electron: inTarget(target),
+        timeoutMs: 5000,
+      },
+    )
+  })
+
+  it("sweeps what a crash left (by the files they hold), at the next start", async () => {
+    const stateFile = join(mkdtempSync(join(tmpdir(), "kiframe-el-state-")), "launches.json")
+    const target = await launch([], { stateFile })
+    const pidFile = join(target.sandbox, "profile", "helper.pid")
+    await waitFor(() => existsSync(pidFile))
+    const helper = Number(readFileSync(pidFile, "utf8"))
+    expect(JSON.parse(readFileSync(stateFile, "utf8"))).toHaveLength(1)
+    // Kiframe "crashed": never closed. The next start sweeps it.
+    expect(await sweepElectronOrphans(stateFile)).toBe(1)
+    expect(await waitFor(() => !alive(helper))).toBe(true)
+    expect(existsSync(target.sandbox)).toBe(false)
+    expect(JSON.parse(readFileSync(stateFile, "utf8"))).toEqual([])
+  })
+
+  it("says an app that quits at once, and leaves nothing behind", async () => {
+    const before = readdirSync(tmpdir()).filter((d) => d.startsWith("kiframe-app-")).length
+    await expect(launch(["quit-at-once"])).rejects.toThrow(ElectronLaunchError)
+    await expect(launch(["quit-at-once"])).rejects.toThrow(/quit before Kiframe could attach/)
+    expect(readdirSync(tmpdir()).filter((d) => d.startsWith("kiframe-app-")).length).toBe(before)
+  })
+
+  it("learns its own scheme from a window it opens after a splash (never from a step)", async () => {
+    const target = await launch(["splash"])
+    expect(
+      await waitFor(() => target.context.pages().some((p) => p.url().startsWith("app:")), 8000),
+    ).toBe(true)
+    expect(target.allows("app://local/index.html")).toBe(true)
+    expect(target.allows("other://local/index.html")).toBe(false)
+    // Its main window (the splash closed or not, the last one opened) is the one driven.
+    expect(target.page.url()).toBe("app://local/index.html")
+    await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1
+steps:
+  - { id: add, action: click, target: { by: role, role: button, name: Add note } }
+  - { id: one, action: expect, that: { text: "Notes: 1" } }
+`),
+      project,
+      {
+        electron: inTarget(target),
+        timeoutMs: 5000,
+      },
+    )
+  })
+
+  it("guards every window and frame: a site's window closed, the user's file blanked, said", async () => {
+    const run = async (button: string) => {
+      const target = await launch()
+      const error = await runScenario(
+        target.page,
+        parseScenarioYaml(`version: 1
+steps:
+  - { id: out, action: click, target: { by: role, role: button, name: ${button} } }
+  - { id: beat, action: pause, ms: 1500 }
+`),
+        project,
+        {
+          electron: inTarget(target),
+          timeoutMs: 5000,
+        },
+      ).then(
+        () => undefined,
+        (e: unknown) => e as StepError,
+      )
+      return { target, error }
+    }
+    const site = await run("Open website window")
+    expect(site.error?.reason).toBe("off-app")
+    expect(site.error?.message).toMatch(/the app's window went to 127\.0\.0\.1:\d+/)
+    expect(site.target.context.pages().some((p) => p.url().startsWith(other))).toBe(false)
+    const file = await run("Embed hosts")
+    expect(file.error?.message).toMatch(/went to a file on this computer/)
+    // The frame is blank (never left showing the file to a read).
+    expect(file.target.page.frames().some((f) => f.url().startsWith("file:///etc"))).toBe(false)
+    // The app's own page in a frame is its own.
+    expect((await run("Embed settings")).error).toBeUndefined()
+  })
+
+  it("confines a desktop window while grounding too (the user's files never reach a read)", async () => {
+    const target = await launch()
+    const error = await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1
+steps:
+  - { id: out, action: click, target: { by: role, role: link, name: Hosts file } }
+`),
+      project,
+      {
+        electron: inTarget(target),
+        confineToApps: false,
+        timeoutMs: 5000,
+      },
+    ).then(
+      () => undefined,
+      (e: unknown) => e as StepError,
+    )
+    expect(error?.reason).toBe("off-app")
+  })
+
+  it("keeps no sign-in between runs yet, skips a web rule's goto, ends once", async () => {
+    const target = await launch()
+    const scene = parseScenarioYaml(`version: 1\nsteps: [{ id: a, action: pause, ms: 1 }]\n`)
+    await expect(
+      runScenario(target.page, scene, project, {
+        electron: inTarget(target),
+        skipSessionPresets: ["login"],
+      }),
+    ).rejects.toThrow(/a desktop app's sign-in isn't kept between runs yet/)
+    const withRule = parseProjectYaml(`version: 2
+apps:
+  notes: { kind: electron, bundleId: com.kiframe.fixture, viewport: { width: 800, height: 600, deviceScaleFactor: 1 } }
+  web: { kind: web, url: "https://app.test" }
+interrupts:
+  - { id: cookies, when: { by: role, role: button, name: Add note }, do: { action: goto, app: web, url: / } }
+defaults: { pacing: { settleMs: 0, cursor: instant, typing: instant } }
+`)
+    const warnings: string[] = []
+    await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1
+app: notes
+steps: [{ id: add, action: click, target: { by: role, role: button, name: Add note } }]
+`),
+      withRule,
+      {
+        electron: inTarget(target),
+        onEvent: (e) => e.kind === "warning" && warnings.push(e.message),
+      },
+    )
+    expect(warnings).toContain(
+      'interrupt rule "cookies" is skipped in the desktop app: it needs a web app\'s address',
+    )
+    // Once: a second call is the same ending (never a second signal to a group id).
+    const first = target.close()
+    expect(target.close()).toBe(first)
+    expect(await first).toEqual({ unread: false })
+    open = []
+  })
+
+  it("keeps what the app embeds as it opens, and takes its window back from a site", async () => {
+    // A frame of another (https) site shown at launch is the app as shipped: never a stop.
+    const embeds = await launchElectron({
+      executable: electron,
+      bundle: fixture,
+      args: [fixture, "hidden", `link=${secure}`, "embed-at-start", "trust-test-cert"],
+      viewport,
+    })
+    open.push(embeds)
+    await runScenario(
+      embeds.page,
+      parseScenarioYaml(`version: 1\nsteps: [{ id: a, action: pause, ms: 300 }]\n`),
+      project,
+      { electron: inTarget(embeds) },
+    )
+    expect(embeds.page.frames().some((f) => f.url() === secure)).toBe(true)
+    // A plain-http frame at launch is never the app's: stopped (and never blamed on a run).
+    const plain = await launch(["embed-at-start"])
+    await runScenario(
+      plain.page,
+      parseScenarioYaml(`version: 1\nsteps: [{ id: a, action: pause, ms: 300 }]\n`),
+      project,
+      { electron: inTarget(plain) },
+    )
+    expect(plain.page.frames().some((f) => f.url() === other)).toBe(false)
+    // The main window that went to a site comes back to the app (never left blank: no goto here).
+    const target = await launch()
+    const options = {
+      electron: inTarget(target),
+      timeoutMs: 5000,
+    }
+    await expect(
+      runScenario(
+        target.page,
+        parseScenarioYaml(`version: 1
+steps:
+  - { id: out, action: click, target: { by: role, role: link, name: A website } }
+  - { id: beat, action: pause, ms: 1000 }
+`),
+        project,
+        options,
+      ),
+    ).rejects.toThrow(/went to 127\.0\.0\.1/)
+    expect(
+      await waitFor(
+        () => target.page.url().endsWith("index.html") || target.page.url().includes("index.html?"),
+      ),
+    ).toBe(true)
+    await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1
+steps:
+  - { id: add, action: click, target: { by: role, role: button, name: Add note } }
+  - { id: one, action: expect, that: { text: "Notes: 1" } }
+`),
+      project,
+      options,
+    )
+  })
+
+  it("never blames a run for what was stopped before it; says a failed load as one", async () => {
+    const target = await launch()
+    const options = {
+      electron: inTarget(target),
+      timeoutMs: 5000,
+    }
+    // Stopped outside any run (an earlier failed step): the next run isn't blamed.
+    await target.page.getByRole("button", { name: "Embed hosts" }).click()
+    await new Promise((r) => setTimeout(r, 500))
+    await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1\nsteps: [{ id: a, action: pause, ms: 1 }]\n`),
+      project,
+      options,
+    )
+    const dead = await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1
+steps:
+  - { id: out, action: click, target: { by: role, role: link, name: A dead link } }
+  - { id: beat, action: pause, ms: 1000 }
+`),
+      project,
+      options,
+    ).then(
+      () => undefined,
+      (e: unknown) => e as StepError,
+    )
+    expect(dead?.message).toMatch(/the page failed to load/)
+  })
+
+  it("runs a batch's scene (its session hook never called), skips a URL-waiting rule", async () => {
+    const target = await launch()
+    const withRule = parseProjectYaml(`version: 2
+apps:
+  notes: { kind: electron, bundleId: com.kiframe.fixture, viewport: { width: 800, height: 600, deviceScaleFactor: 1 } }
+  web: { kind: web, url: "https://app.test" }
+presets:
+  login: { app: notes, session: true, steps: [{ action: click, target: { by: role, role: button, name: Add note } }] }
+interrupts:
+  - { id: home, when: { by: role, role: button, name: Add note }, do: { action: waitFor, until: { url: /home, app: web } } }
+defaults: { pacing: { settleMs: 0, cursor: instant, typing: instant } }
+`)
+    const warnings: string[] = []
+    let saved = 0
+    await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1
+app: notes
+setup: [{ preset: login }]
+steps: [{ id: add, action: click, target: { by: role, role: button, name: Add note } }]
+`),
+      withRule,
+      {
+        electron: inTarget(target),
+        onSessionReady: () => {
+          saved++
+          return Promise.resolve()
+        },
+        onEvent: (e) => e.kind === "warning" && warnings.push(e.message),
+      },
+    )
+    expect(saved).toBe(0)
+    expect(warnings).toContain(
+      'interrupt rule "home" is skipped in the desktop app: it needs a web app\'s address',
+    )
+  })
+
+  it("follows the windows its main process opens: a sign-in window replaced, Preferences", async () => {
+    const swap = await launch(["swap"])
+    await runScenario(
+      swap.page,
+      parseScenarioYaml(`version: 1
+steps:
+  - { id: wait, action: pause, ms: 4000 }
+  - { id: add, action: click, target: { by: role, role: button, name: Add note } }
+  - { id: one, action: expect, that: { text: "Notes: 1" } }
+`),
+      project,
+      { electron: inTarget(swap), timeoutMs: 5000 },
+    )
+    const prefs = await launch(["prefs"])
+    await runScenario(
+      prefs.page,
+      parseScenarioYaml(`version: 1
+steps:
+  - { id: wait, action: pause, ms: 3500 }
+  - { id: there, action: expect, that: { visible: { by: role, role: heading, name: Settings } } }
+  - { id: wide, action: expect, that: { text: "Settings width: 800" } }
+`),
+      project,
+      { electron: inTarget(prefs), timeoutMs: 5000 },
+    )
+  })
+
+  it("never counts the app's own DevTools as leaving it", async () => {
+    const target = await launch(["devtools"])
+    await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1
+steps:
+  - { id: wait, action: pause, ms: 1500 }
+  - { id: add, action: click, target: { by: role, role: button, name: Add note } }
+`),
+      project,
+      { electron: inTarget(target), timeoutMs: 5000 },
+    )
+  })
+
+  it("follows a window that opens blank and loads later; a frame of another window is said only", async () => {
+    const target = await launch()
+    const warnings: string[] = []
+    const options = {
+      electron: inTarget(target),
+      timeoutMs: 5000,
+      onEvent: (e: { kind: string; message?: string }) => {
+        if (e.kind === "warning" && e.message !== undefined) warnings.push(e.message)
+      },
+    }
+    await runScenario(
+      target.page,
+      parseScenarioYaml(`version: 1
+steps:
+  - { id: open, action: click, target: { by: role, role: button, name: Open window that loads later } }
+  - { id: there, action: expect, that: { visible: { by: role, role: heading, name: Settings } } }
+  - { id: other, action: pause, ms: 1 }
+`),
+      project,
+      {
+        ...options,
+        onPageSwitch: async () => {
+          // The run is on the new window: the main window (not driven) embeds the user's file.
+          await target.page.getByRole("button", { name: "Embed hosts" }).click()
+          await new Promise((r) => setTimeout(r, 500))
+        },
+      },
+    )
+    expect(warnings).toContain(
+      'a frame of another window of "notes" went to a file on this computer: Kiframe stopped it',
+    )
+  })
+
+  it("says a window left blank (nothing to go back to): relaunch", async () => {
+    const target = await launch()
+    const step = (yaml: string) =>
+      runScenario(target.page, parseScenarioYaml(`version: 1\nsteps:\n${yaml}`), project, {
+        electron: inTarget(target),
+        timeoutMs: 5000,
+      }).then(
+        () => "ran",
+        (e: unknown) => (e as Error).message,
+      )
+    expect(
+      await step(`  - { id: out, action: click, target: { by: role, role: button, name: Replace with website } }
+  - { id: beat, action: pause, ms: 1500 }`),
+    ).toMatch(/went to 127\.0\.0\.1/)
+    expect(await step("  - { id: a, action: pause, ms: 1 }")).toMatch(
+      /the app's window is blank .*: relaunch "notes"/,
+    )
+  })
+
+  it("refuses an app whose main window isn't its own at launch, said where it is", async () => {
+    await expect(launch(["elsewhere"])).rejects.toThrow(
+      "the app shows a data: page: if that's the app's own, list it in its origins",
+    )
+  })
+
+  it("says an app that isn't there any more, or can't start, never crashing the host", async () => {
+    await expect(
+      launchElectron({ executable: electron, bundle: "/Applications/Gone.app", viewport }),
+    ).rejects.toThrow("the app isn't at /Applications/Gone.app any more")
+    await expect(
+      launchElectron({ executable: "/no/such/executable", viewport, timeoutMs: 5000 }),
+    ).rejects.toThrow(/the app couldn't be launched/)
+  })
+
+  it("keeps a desktop scene in its app: no goto, URL condition or web preset there", async () => {
+    const target = await launch()
+    const both = parseProjectYaml(`version: 2
+apps:
+  notes: { kind: electron, bundleId: com.kiframe.fixture }
+  web: { kind: web, url: "https://app.test" }
+presets:
+  login: { app: web, steps: [{ action: goto, url: /login }] }
+`)
+    const failure = (yaml: string) =>
+      runScenario(target.page, parseScenarioYaml(`version: 1\n${yaml}`), both, {
+        electron: inTarget(target),
+        timeoutMs: 3000,
+      }).then(
+        () => "ran",
+        (e: unknown) => (e as Error).message,
+      )
+    expect(
+      await failure("setup: [{ preset: login }]\nsteps: [{ id: a, action: pause, ms: 1 }]"),
+    ).toMatch(/a scene in the desktop app "notes" stays in it/)
+    expect(await failure("steps: [{ id: a, action: goto, app: web, url: / }]")).toMatch(
+      /a goto can't run in a desktop app's scene/,
+    )
+    expect(
+      await failure("steps: [{ id: a, action: waitFor, until: { url: /, app: web } }]"),
+    ).toMatch(/a URL condition can't run in a desktop app's scene/)
+    expect(target.page.url()).toMatch(/^file:/)
+  })
+
+  it("stops when the run is stopped while it launches", async () => {
+    const stop = new AbortController()
+    const launching = launchElectron({
+      executable: electron,
+      bundle: fixture,
+      args: [fixture, "hidden"],
+      viewport,
+      signal: stop.signal,
+    })
+    stop.abort(new Error("stopped"))
+    await expect(launching).rejects.toThrow(/stopped/)
+  })
+})
+
+describe("a desktop app's own pages", () => {
+  const own = {
+    bundles: ["/Applications/Notes.app"],
+    sandbox: "/tmp/kiframe-app-x",
+    launched: new Set(["http://localhost:5173"]),
+    schemes: new Set(["app:", "vscode-file:"]),
+    origins: ["https://app.slack.com"],
+  }
+  it("are its bundle's and sandbox's files, its launch-time dev server and schemes, its sites", () => {
+    for (const url of [
+      "about:blank",
+      "file:///Applications/Notes.app/Contents/Resources/app/index.html",
+      "file:///tmp/kiframe-app-x/profile/page.html",
+      "http://localhost:5173/settings",
+      "https://app.slack.com/client/T1",
+      "app://notes/index.html",
+      "vscode-file://vscode-app/x.html",
+      "blob:https://app.slack.com/123",
+      // A file: page's blob (no path to check: made by the app's own pages).
+      "blob:file:///3f2a-41c1",
+      // Its site as one site (www.).
+      "https://www.app.slack.com/client",
+    ]) {
+      expect(allowedPage(url, own), url).toBe(true)
+    }
+  })
+  it("are never the user's files, another site or port, or a data: page", () => {
+    for (const url of [
+      "file:///etc/hosts",
+      "file:///Applications/Notes.app.evil/x.html",
+      "file:///Applications/Notes.app/../Mail.app/x.html",
+      "file:///Users/me/Documents/secret.pdf",
+      "http://localhost:8080/",
+      "https://example.com/",
+      "https://app.slack.com.evil.test/",
+      "data:text/html,<h1>x</h1>",
+      "chrome-error://chromewebdata/",
+      "blob:https://example.com/123",
+      // Another app's scheme, a site's sandboxed files, Chromium's pages, another host's file.
+      "other-app://x/index.html",
+      "filesystem:https://example.com/temporary/x.html",
+      "chrome-extension://abc/page.html",
+      "about:srcdoc",
+      "file://server/Applications/Notes.app/index.html",
+      // Decoding can make `..` the URL parser left alone.
+      "file:///Applications/Notes.app/..%2F..%2Fetc/hosts",
+      "blob:file://server/abc",
+      // Never plain http for an https site.
+      "http://app.slack.com/client",
+    ]) {
+      expect(allowedPage(url, own), url).toBe(false)
+    }
+  })
+})
+
+// The state file only names sandboxes Kiframe made: never a folder from a tampered file.
+describe("the launches' state file", () => {
+  it("keeps a launch noted while it sweeps (only what it swept is removed)", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "kiframe-el-state-"))
+    const left = mkdtempSync(join(tmpdir(), "kiframe-app-"))
+    const meanwhile = mkdtempSync(join(tmpdir(), "kiframe-app-"))
+    const stateFile = join(dir, "launches.json")
+    writeFileSync(stateFile, JSON.stringify([left]))
+    try {
+      const sweeping = sweepElectronOrphans(stateFile)
+      // A run starts during the sweep: its launch is noted.
+      writeFileSync(stateFile, JSON.stringify([left, meanwhile]))
+      expect(await sweeping).toBe(1)
+      expect(JSON.parse(readFileSync(stateFile, "utf8"))).toEqual([meanwhile])
+      expect(existsSync(meanwhile)).toBe(true)
+    } finally {
+      rmSync(left, { recursive: true, force: true })
+      rmSync(meanwhile, { recursive: true, force: true })
+    }
+  })
+
+  it("never sweeps a folder that isn't a sandbox (named like one, or anywhere else)", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "kiframe-el-state-"))
+    const keep = mkdtempSync(join(tmpdir(), "users-files-"))
+    // Named like a sandbox, but not one this module made (not directly in the temp folder).
+    const lookalike = mkdtempSync(join(dir, "kiframe-app-"))
+    const stateFile = join(dir, "launches.json")
+    writeFileSync(stateFile, JSON.stringify([keep, lookalike, `${lookalike}/../..`]))
+    expect(await sweepElectronOrphans(stateFile)).toBe(0)
+    expect(existsSync(keep)).toBe(true)
+    expect(existsSync(lookalike)).toBe(true)
+  })
+})
diff --git a/packages/runtime/test/fixtures/electron-app/index.html b/packages/runtime/test/fixtures/electron-app/index.html
new file mode 100644
index 0000000..60783bf
--- /dev/null
+++ b/packages/runtime/test/fixtures/electron-app/index.html
@@ -0,0 +1,51 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Fixture notes</title>
+  </head>
+  <body style="font-family: sans-serif">
+    <h1>Notes</h1>
+    <button
+      onclick="
+        document.getElementById('n').textContent = String(
+          Number(document.getElementById('n').textContent) + 1,
+        )
+      "
+    >
+      Add note
+    </button>
+    <p>Notes: <span id="n">0</span></p>
+    <p>Width: <span id="w"></span></p>
+    <a href="other.html">Settings</a>
+    <button onclick="window.open('other.html')">Open settings window</button>
+    <a href="file:///etc/hosts">Hosts file</a>
+    <a id="site" href="https://example.com/">A website</a>
+    <button onclick="window.open(link)">Open website window</button>
+    <a href="http://127.0.0.1:1/">A dead link</a>
+    <button onclick="location.replace(link)">Replace with website</button>
+    <button
+      onclick="
+        const w = window.open('')
+        setTimeout(() => (w.location = 'other.html'), 800)
+      "
+    >
+      Open window that loads later
+    </button>
+    <button onclick="embed('file:///etc/hosts')">Embed hosts</button>
+    <button onclick="embed('other.html')">Embed settings</button>
+    <script>
+      const w = () => (document.getElementById("w").textContent = String(innerWidth))
+      w()
+      addEventListener("resize", w)
+      const params = new URLSearchParams(location.search)
+      const link = params.get("link") ?? "https://example.com/"
+      document.getElementById("site").href = link
+      if (params.get("embed") === "1") embed(link)
+      function embed(src) {
+        const frame = document.createElement("iframe")
+        frame.src = src
+        document.body.append(frame)
+      }
+    </script>
+  </body>
+</html>
diff --git a/packages/runtime/test/fixtures/electron-app/main.cjs b/packages/runtime/test/fixtures/electron-app/main.cjs
new file mode 100644
index 0000000..3985634
--- /dev/null
+++ b/packages/runtime/test/fixtures/electron-app/main.cjs
@@ -0,0 +1,91 @@
+// A fixture desktop app for the Electron target's tests (never shipped): a window with a button,
+// links out, a popup; it writes its data, says what it sees of its environment, and starts a
+// detached helper (as a pty host or a daemon would) that only the sandbox sweep can find. It never
+// writes macOS preferences: those go to the user's real ~/Library/Preferences whatever the sandbox
+// (cfprefsd writes them for the app: a stated residual).
+const { app, BrowserWindow, net, protocol } = require("electron")
+const { pathToFileURL } = require("node:url")
+const { spawn } = require("node:child_process")
+const { writeFileSync } = require("node:fs")
+const { homedir } = require("node:os")
+const { join } = require("node:path")
+
+// "splash": a file: splash window first, the main window then on the app's own scheme (app:).
+const splash = process.argv.includes("splash")
+if (splash)
+  protocol.registerSchemesAsPrivileged([{ scheme: "app", privileges: { standard: true } }])
+
+// "trust-test-cert": a test's own https server (a throwaway certificate) is trusted.
+if (process.argv.includes("trust-test-cert"))
+  app.commandLine.appendSwitch("ignore-certificate-errors")
+
+if (process.argv.includes("quit-at-once")) {
+  app.quit()
+} else {
+  app.whenReady().then(() => {
+    const data = app.getPath("userData")
+    writeFileSync(
+      join(data, "seen.json"),
+      JSON.stringify({
+        env: Object.keys(process.env),
+        home: homedir(),
+        userData: data,
+        args: process.argv.slice(1),
+      }),
+    )
+    const helper = spawn("sleep", ["300"], { detached: true, stdio: "ignore", cwd: data })
+    helper.unref()
+    writeFileSync(join(data, "helper.pid"), String(helper.pid))
+    // A child in the app's own process group holding nothing in the sandbox (cwd /): only the
+    // group's kill ends it.
+    const grouped = spawn("sleep", ["300"], { stdio: "ignore", cwd: "/" })
+    writeFileSync(join(data, "grouped.pid"), String(grouped.pid))
+    writeFileSync(join(data, "main.pid"), String(process.pid))
+    const show = !process.argv.includes("hidden")
+    if (splash) {
+      protocol.handle("app", (request) =>
+        net.fetch(pathToFileURL(join(__dirname, new URL(request.url).pathname)).href),
+      )
+      const first = new BrowserWindow({ width: 300, height: 200, show })
+      first.loadFile(join(__dirname, "other.html"))
+      setTimeout(() => {
+        const main = new BrowserWindow({ width: 700, height: 500, show })
+        main.loadURL("app://local/index.html")
+      }, 800)
+      return
+    }
+    // "swap": a sign-in window first, replaced by the main window a moment later (no opener).
+    if (process.argv.includes("swap")) {
+      const signIn = new BrowserWindow({ width: 400, height: 300, show })
+      signIn.loadFile(join(__dirname, "other.html"))
+      setTimeout(() => {
+        const main = new BrowserWindow({ width: 700, height: 500, show })
+        main.loadFile(join(__dirname, "index.html"))
+        main.webContents.once("did-finish-load", () => signIn.close())
+      }, 2500)
+      return
+    }
+    const win = new BrowserWindow({ width: 700, height: 500, show })
+    // "prefs": its main process opens a Preferences window a moment later (no opener).
+    if (process.argv.includes("prefs")) {
+      setTimeout(() => {
+        const prefs = new BrowserWindow({ width: 500, height: 400, show })
+        prefs.loadFile(join(__dirname, "other.html"))
+      }, 2500)
+    }
+    // "devtools": it opens DevTools itself (a dev build).
+    if (process.argv.includes("devtools")) {
+      win.webContents.once("did-finish-load", () =>
+        win.webContents.openDevTools({ mode: "detach" }),
+      )
+    }
+    // "elsewhere": its window shows a page that's never an app's own (a data: page).
+    // "link=<url>": the other site its links and windows go to (a test's local server);
+    // "embed-at-start": it shows that site in a frame as it opens.
+    const link = process.argv.find((a) => a.startsWith("link="))?.slice(5) ?? "https://example.com/"
+    const query = { link, ...(process.argv.includes("embed-at-start") && { embed: "1" }) }
+    if (process.argv.includes("elsewhere")) win.loadURL("data:text/html,<h1>Elsewhere</h1>")
+    else win.loadFile(join(__dirname, "index.html"), { query })
+  })
+  app.on("window-all-closed", () => app.quit())
+}
diff --git a/packages/runtime/test/fixtures/electron-app/other.html b/packages/runtime/test/fixtures/electron-app/other.html
new file mode 100644
index 0000000..fb166d3
--- /dev/null
+++ b/packages/runtime/test/fixtures/electron-app/other.html
@@ -0,0 +1,15 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Settings</title>
+  </head>
+  <body>
+    <h1>Settings</h1>
+    <p>Settings width: <span id="w"></span></p>
+    <script>
+      const w = () => (document.getElementById("w").textContent = String(innerWidth))
+      w()
+      addEventListener("resize", w)
+    </script>
+  </body>
+</html>
diff --git a/packages/runtime/test/fixtures/electron-app/package.json b/packages/runtime/test/fixtures/electron-app/package.json
new file mode 100644
index 0000000..a3396eb
--- /dev/null
+++ b/packages/runtime/test/fixtures/electron-app/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "kiframe-fixture-electron",
+  "private": true,
+  "main": "main.cjs"
+}
diff --git a/packages/studio/test/snapshot-find.test.ts b/packages/studio/test/snapshot-find.test.ts
index 0edd411..6f54a8e 100644
--- a/packages/studio/test/snapshot-find.test.ts
+++ b/packages/studio/test/snapshot-find.test.ts
@@ -55,6 +55,7 @@ describe("finding in a snapshot", () => {
     expect(find(SNAP, "2026_FIFA")).toContain('link "2026 World Cup" [ref=e3]')
   })
 
+  // A ratio of times, never a budget: room for a CI machine busy with the Electron tests.
   it("stays linear on a huge snapshot with a common word", () => {
     // Time per size, not a wall-clock budget (CI and coverage are several times slower): four times
     // the snapshot takes about four times as long; a quadratic search takes about sixteen times.
@@ -73,7 +74,7 @@ describe("finding in a snapshot", () => {
     timed(10_000) // warm up
     const ratio = timed(100_000) / timed(25_000)
     expect(ratio).toBeLessThan(8)
-  })
+  }, 30_000)
 
   it("reads a sentence over a link, as written by a reader (dashes, quotes, case)", () => {
     // "He played in the 2026 World Cup and won." spans the paragraph's three children.

From 80338ba131b06673a06f5c335bba065d43d3fc87 Mon Sep 17 00:00:00 2001
From: Quang Lee <winlp4ever@gmail.com>
Date: Fri, 9 Oct 2026 09:55:36 +0200
Subject: [PATCH 03/10] fix(runtime): steady the desktop-app target in ci (#57)

* fix(runtime): wait for the guard's stops before reading a desktop app's window

* test(runtime): run the desktop-app suite alone, after every other suite

* perf(runtime): kill a desktop app outright and close its connection after

* fix(runtime): send a desktop app's window back on commit, with its own time
---
 packages/runtime/src/electron.ts       | 59 +++++++++++++++++---------
 packages/runtime/src/run/apps.ts       |  2 +
 packages/runtime/src/run/context.ts    |  2 +-
 packages/runtime/test/electron.test.ts | 23 +++++++---
 vitest.config.ts                       | 21 ++++++++-
 5 files changed, 80 insertions(+), 27 deletions(-)

diff --git a/packages/runtime/src/electron.ts b/packages/runtime/src/electron.ts
index daef1db..d961b57 100644
--- a/packages/runtime/src/electron.ts
+++ b/packages/runtime/src/electron.ts
@@ -46,8 +46,8 @@ const PASSED_ENV = [
 
 /** How long an app may take to open its debugging port and its first window. */
 const LAUNCH_MS = 20_000
-/** How long a terminated app may take to quit before it's killed. */
-const QUIT_MS = 2000
+/** How long the guard's "back" may take to commit (a busy machine: never a step's timeout). */
+const BACK_MS = 10_000
 /** How long closing the debugging connection may take (the group is killed after it anyway). */
 const CLOSE_MS = 2000
 /** How long an app that dropped the attach has to tell its exit. */
@@ -104,6 +104,11 @@ export interface ElectronLaunch {
   /** A file noting the launches still running: what a crash left is swept at the next start. */
   stateFile?: string
   signal?: AbortSignal
+  /**
+   * How long its windows must stay as they are before its main window is chosen (default 1.5 s: a
+   * splash closing, a sign-in window replaced). Tests of a plain app: shorter.
+   */
+  settleMs?: number
   /** Tests: how long to wait for the app, its port and its first window together (default 20 s). */
   timeoutMs?: number
 }
@@ -133,6 +138,8 @@ export interface ElectronTarget {
   stopped: () => GuardStop[]
   /** A window the run follows, at the scene's size first (its emulation applied). */
   prepare: (page: Page) => Promise<void>
+  /** Resolves once the guard's stops are done (a window sent back, a frame blanked). */
+  quiet: () => Promise<void>
   /**
    * Ends it (once: a second call does nothing): disconnects, kills the app's process group and
    * what still points at the sandbox, removes it. `unread`: what holds the sandbox couldn't be read.
@@ -205,14 +212,16 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
   const end = () =>
     (ended ??= (async () => {
       const alive = browser?.isConnected() === true
-      // Bounded: the group is killed right after (a close the app never answers never holds it).
+      // Killed first, the connection closed after (it drops with the app: never a close the app
+      // has to answer), bounded all the same.
+      const ended = await stop(child, sandbox.root, opts.stateFile, alive)
       const t0 = Date.now()
       await within(
         browser?.close().catch(() => undefined),
         CLOSE_MS,
       )
       timing("close", t0)
-      return stop(child, sandbox.root, opts.stateFile, alive)
+      return ended
     })())
   try {
     // Noted at once (a crash from here on is swept at the next start); a note that can't be
@@ -237,6 +246,7 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
       deadline,
       opts.signal,
       () => child.exitCode !== null || child.signalCode !== null || !connected.isConnected(),
+      opts.settleMs ?? SETTLE_MS,
     )
     // Sealed now, from the main window alone: its own scheme (app:) or dev server (loopback).
     const launched = new Set<string>()
@@ -270,6 +280,7 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
     // The guard: every frame of every window, every navigation, at once; one that isn't the app's
     // own is stopped (a popup closed, any other frame blanked) and said.
     const stops: GuardStop[] = []
+    const stopping = new Set<Promise<void>>()
     const frameAllowed = (frame: Frame): boolean => {
       const url = frame.url()
       if (url === "" || url === "about:blank") return true
@@ -287,15 +298,23 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
         if (frameAllowed(frame)) return
         stops.push({ page: p, window: frame === p.mainFrame(), place: placeOf(frame.url()) })
         // A popup closed; the main window back to the app's page (else nothing could bring it
-        // back: no goto in a desktop app); any other frame blanked.
-        if (frame !== p.mainFrame()) void frame.goto("about:blank").catch(() => undefined)
-        else if (p !== page) void p.close().catch(() => undefined)
-        else {
-          void p
-            .goBack()
-            .then((back) => (back === null ? frame.goto("about:blank") : back))
-            .catch(() => undefined)
-        }
+        // back: no goto in a desktop app); any other frame blanked. Kept until done: a read waits
+        // for it (`quiet`), never seeing a window mid-stop.
+        const action: Promise<unknown> =
+          frame !== p.mainFrame()
+            ? frame.goto("about:blank")
+            : p !== page
+              ? p.close()
+              : // Committed is enough (never the page's load, nor a step's short timeout).
+                p
+                  .goBack({ waitUntil: "commit", timeout: BACK_MS })
+                  .then((back) => (back === null ? frame.goto("about:blank") : back))
+        const done = action.then(
+          () => undefined,
+          () => undefined,
+        )
+        stopping.add(done)
+        void done.finally(() => stopping.delete(done))
       }
       p.on("framenavigated", check)
       for (const frame of p.frames()) check(frame)
@@ -334,6 +353,10 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
       allows,
       stopped: () => stops.splice(0),
       prepare: (p) => emulate(p),
+      quiet: async () => {
+        // A stop's own action may start another navigation (a goBack): until none is left.
+        while (stopping.size > 0) await Promise.all([...stopping])
+      },
       close: end,
     }
   } catch (error) {
@@ -435,6 +458,7 @@ async function mainWindow(
   deadline: number,
   signal: AbortSignal | undefined,
   gone: () => boolean,
+  settleMs: number,
 ): Promise<Page> {
   const windows = () => context.pages().filter((p) => !isDevtools(p.url()) && !p.isClosed())
   let seen = ""
@@ -451,7 +475,7 @@ async function mainWindow(
     }
     const last = now.at(-1)
     const loaded = last !== undefined && last.url() !== "" && last.url() !== "about:blank"
-    if (loaded && Date.now() - since >= SETTLE_MS) {
+    if (loaded && Date.now() - since >= settleMs) {
       await last
         .waitForLoadState("domcontentloaded", { timeout: Math.max(1, deadline - Date.now()) })
         .catch(() => undefined)
@@ -561,11 +585,8 @@ async function stop(
   const leader = child.exitCode === null && child.signalCode === null
   let t0 = Date.now()
   if (pid !== undefined && (leader || alive || (await orphanedGroup(pid)))) {
-    if (leader) {
-      const exited = new Promise((resolve) => child.once("exit", resolve))
-      signalGroup(pid, "SIGTERM")
-      await Promise.race([exited, new Promise((r) => setTimeout(r, QUIT_MS))])
-    }
+    // Killed outright, never asked to quit: its sandbox is thrown away (nothing to save), and a
+    // quit can run an updater's install-on-quit over the user's real app.
     signalGroup(pid, "SIGKILL")
   }
   timing("kill", t0)
diff --git a/packages/runtime/src/run/apps.ts b/packages/runtime/src/run/apps.ts
index 4cfbf58..9d45eca 100644
--- a/packages/runtime/src/run/apps.ts
+++ b/packages/runtime/src/run/apps.ts
@@ -81,6 +81,8 @@ export async function confine(ctx: Ctx, step: StepRef): Promise<void> {
   if (electron !== undefined) {
     // A stop counts against the step when it was the driven window's (or a frame in it), or a
     // window itself (one the step opened, sent back); a frame of another window is said only.
+    // The guard's stops done first: never a window read mid-stop.
+    await electron.quiet()
     const stops = electron.stopped()
     for (const s of stops) {
       if (s.page !== ctx.page && !s.window) {
diff --git a/packages/runtime/src/run/context.ts b/packages/runtime/src/run/context.ts
index 93f50fe..139212f 100644
--- a/packages/runtime/src/run/context.ts
+++ b/packages/runtime/src/run/context.ts
@@ -132,7 +132,7 @@ export interface RunOptions {
    * The desktop app this run's page belongs to (its target, `launchElectron`): a scene starting in
    * it runs only with it, and its pages (`allows`) are the app's own. None: no desktop app runs.
    */
-  electron?: { app: string } & Pick<ElectronTarget, "allows" | "stopped" | "prepare">
+  electron?: { app: string } & Pick<ElectronTarget, "allows" | "stopped" | "prepare" | "quiet">
   /** The org interrupt rules this run's config kept from the org (their approvals are the org's). */
   orgInterrupts?: { orgId: string; ruleIds: readonly string[] }
   /** Resolves an `upload` step's project asset (`<sha256>.<ext>`) to a file path. */
diff --git a/packages/runtime/test/electron.test.ts b/packages/runtime/test/electron.test.ts
index b4034fe..0269032 100644
--- a/packages/runtime/test/electron.test.ts
+++ b/packages/runtime/test/electron.test.ts
@@ -111,6 +111,7 @@ const inTarget = (target: ElectronTarget) => ({
   allows: target.allows,
   stopped: target.stopped,
   prepare: target.prepare,
+  quiet: target.quiet,
 })
 
 let open: ElectronTarget[] = []
@@ -119,6 +120,8 @@ const launch = async (extra: string[] = [], options: { stateFile?: string } = {}
     executable: electron,
     bundle: fixture,
     args: [fixture, "hidden", `link=${other}`, ...extra],
+    // A plain fixture settles at once; the window-shape tests keep the real wait.
+    ...(!extra.some((e) => ["splash", "swap", "embed-at-start"].includes(e)) && { settleMs: 300 }),
     viewport,
     ...options,
   })
@@ -233,6 +236,7 @@ steps:
           app: "notes",
           allows: target.allows,
           stopped: target.stopped,
+          quiet: target.quiet,
           prepare: async (p) => {
             order.push("prepare")
             await target.prepare(p)
@@ -565,11 +569,9 @@ steps:
         options,
       ),
     ).rejects.toThrow(/went to 127\.0\.0\.1/)
-    expect(
-      await waitFor(
-        () => target.page.url().endsWith("index.html") || target.page.url().includes("index.html?"),
-      ),
-    ).toBe(true)
+    await waitFor(() => target.page.url().includes("index.html"), 10_000)
+    // Its address said if not (a busy CI machine: what it was on).
+    expect(target.page.url()).toMatch(/index\.html/)
     await runScenario(
       target.page,
       parseScenarioYaml(`version: 1
@@ -724,6 +726,17 @@ steps:
     )
   })
 
+  it("is quiet only once its stops are done (a read never sees a window mid-stop)", async () => {
+    const target = await launch()
+    for (let i = 0; i < 3; i++) {
+      await target.page.getByRole("button", { name: "Embed hosts" }).click()
+      // Wait for the stop to be recorded (as a step's end would), then for the guard to be done.
+      await waitFor(() => target.context.pages()[0]?.frames().length !== 1)
+      await target.quiet()
+      expect(target.page.frames().some((f) => f.url().startsWith("file:///etc"))).toBe(false)
+    }
+  })
+
   it("says a window left blank (nothing to go back to): relaunch", async () => {
     const target = await launch()
     const step = (yaml: string) =>
diff --git a/vitest.config.ts b/vitest.config.ts
index efd0176..b2c4c7f 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,8 +1,11 @@
-import { defineConfig } from "vitest/config"
+import { configDefaults, defineConfig } from "vitest/config"
+
+// The desktop-app target's tests launch a real Electron app each: they run alone, after every other
+// suite (a CPU busy with them made timing-sensitive tests elsewhere flaky in CI).
+const ELECTRON = "packages/runtime/test/electron.test.ts"
 
 export default defineConfig({
   test: {
-    include: ["{packages,apps}/*/{src,test}/**/*.test.{ts,tsx}", "tests/**/*.test.{ts,tsx}"],
     coverage: {
       provider: "v8",
       // The shipped code (tests, fixtures and scripts aren't measured).
@@ -11,5 +14,19 @@ export default defineConfig({
       reporter: ["text-summary", "lcov"],
       reportsDirectory: "coverage",
     },
+    projects: [
+      {
+        extends: true,
+        test: {
+          name: "kiframe",
+          include: ["{packages,apps}/*/{src,test}/**/*.test.{ts,tsx}", "tests/**/*.test.{ts,tsx}"],
+          exclude: [...configDefaults.exclude, ELECTRON],
+        },
+      },
+      {
+        extends: true,
+        test: { name: "electron", include: [ELECTRON], sequence: { groupOrder: 1 } },
+      },
+    ],
   },
 })

From ed1c66ea4cc9c09447553d49554b98d00f0e6ce7 Mon Sep 17 00:00:00 2001
From: Quang Lee <winlp4ever@gmail.com>
Date: Fri, 9 Oct 2026 15:58:19 +0200
Subject: [PATCH 04/10] feat(runtime)!: confine every desktop-app launch under
 seatbelt (#58)

* feat(runtime)!: confine every desktop-app launch under seatbelt

Each launch runs under macOS Seatbelt: it writes only into its own sandbox,
never reads the user's folders, runs nothing it drops there, and reaches
neither preferences, the keychain, the clipboard nor other agents' sockets.
A canary checks the confinement before every launch (one read refused, one
allowed); without it, no launch.

A project's files/ is copied into each launch's sandbox (links, devices and
oversized trees refused); the app's arguments name paths in it. Sandboxes
live in ~/.kiframe/sandboxes, each named after the Kiframe that made it, so
a crash sweep removes only what no running Kiframe owns.

BREAKING CHANGE: a desktop app's args must be paths in the project's files/
(files/<name>); any other argument no longer parses.

* fix(runtime): steady a desktop-app launch's checks and copy

- each launch writes its own canary, and a canary that went missing
  proves nothing (refused): launches at once never spoil each other's
- the app's time to start begins once its files are copied
- a stop during the copy ends the launch before the app starts
- a folder in files/ swapped for a link while copied is refused
- the app's own temp folder holds its own pages again

* fix(runtime): finish a desktop-app launch's copy and canary checks

- a folder in files/ is checked again once its entries are copied: one
  swapped for a link at any point of the copy is refused
- each canary lies beside its sandbox, named after it: a crash's is swept
- a stop ends the canary check and the copy at once, said as the stop
- a canary that was read reads as a confinement that didn't hold
- the slow-copy tests are sized to the app's measured start, built once
  and removed
---
 docs/BACKLOG.md                               |   4 +
 docs/OBJECT-MODEL.md                          |   7 +-
 packages/runtime/src/electron-confine.ts      | 226 +++++++
 packages/runtime/src/electron-workarea.ts     | 271 ++++++++
 packages/runtime/src/electron.ts              | 314 +++++-----
 packages/runtime/src/index.ts                 |   3 +-
 packages/runtime/test/electron.test.ts        | 588 +++++++++++++++---
 .../runtime/test/fixtures/crash-launch.ts     |  22 +
 .../test/fixtures/electron-app/main.cjs       |  60 ++
 packages/schema/src/apps.test.ts              |  19 +-
 packages/schema/src/project.ts                |  20 +-
 11 files changed, 1295 insertions(+), 239 deletions(-)
 create mode 100644 packages/runtime/src/electron-confine.ts
 create mode 100644 packages/runtime/src/electron-workarea.ts
 create mode 100644 packages/runtime/test/fixtures/crash-launch.ts

diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md
index a73ca14..b1611b1 100644
--- a/docs/BACKLOG.md
+++ b/docs/BACKLOG.md
@@ -243,6 +243,10 @@ Non-severe review findings deferred on purpose (see the review-round rule: only
 
 ## Vault hardening (M1-7)
 - **Electron targets:** an app attached over CDP (F4) runs in its own persistent profile: no ephemeral context there. The app's own storage keeps whatever the scene typed; document it for Electron projects and prefer a throwaway app profile (`--user-data-dir` per run).
+- **Copy and paste in a desktop app's demo:** the confinement denies the pasteboard (the user's clipboard may hold a password), so an app's own copy and paste does nothing in a run. A demo that needs it: a run-only pasteboard (a private named pasteboard can't be forced on an app) or typing the pasted text.
+- **What a confined app opens through LaunchServices:** an app can't start without `launchservicesd`, and through it it can open a file or a URL that then runs unconfined (a script it wrote, the user's browser). Stated in §0.9 (accident, not a hostile app); an Endpoint Security watcher or a per-run user account would close it.
+- **Desktop-app sweeps read processes more than once:** the startup sweep runs one `ps` per leftover sandbox (one `ps -axo pid=,lstart=` table would answer every owner), and a run's close reads the process table twice (`orphanedGroup` and `sweepProcesses`). Startup and close time only (#58 review).
+- **Test hooks on the launch API (PR 4):** `appArgs`, `readable` and `allowUnconfined` are fields of `ElectronLaunch`, and `appArgs` skips the files/-only rule. Move them out of the public options when the desktop app first calls `launchElectron` (#58 review, agreed 2026-10-09).
 - **One launch helper:** browsers are launched by each entry point; nothing enforces an off-the-record context. A runtime-owned `launchBrowser()` / context factory would make it hard to bypass (the desktop app's main process).
 - **Secrets into contenteditable:** v0 writes secrets to inputs and textareas only (the value set on the approved element); a rich-text field is refused.
 - **Network exfiltration by the page itself:** a hostile page receives the typed password in its own field and can send it anywhere; that's the target app's own data. Out of scope for the vault (it only guarantees the value goes to the bound field on the allowed origins).
diff --git a/docs/OBJECT-MODEL.md b/docs/OBJECT-MODEL.md
index 99e661e..453dd36 100644
--- a/docs/OBJECT-MODEL.md
+++ b/docs/OBJECT-MODEL.md
@@ -226,10 +226,13 @@ One scene, three phases. The agent's own instructions say the same (`packages/st
 **Electron apps (designed 2026-10-08, design reviewed; moved into v0).** `{ kind: "electron", bundleId, args?, origins?, viewport }`:
 - **Named by bundle id, never a path or a program** (a project may come from someone else): the desktop app finds the bundle on each machine and keeps the user's approval in its own settings (bundle id, real path, signing team); only `.app` bundles holding `Electron Framework.framework`; App Store (sandboxed) apps refused. `args` are positional only (no switches). `origins`: the https sites a wrapper app (Slack, Notion) shows as its own.
 - **No address**: a goto or a URL condition on it is refused; a scene starting in it opens on its first window; it takes no secrets in v0 (the user signs in by hand: the handover).
-- **Each run launches it sandboxed** (its own HOME, `CFFIXED_USER_HOME`, XDG and temp folders, `--user-data-dir`; an allowlisted environment, never Kiframe's), attached with `--remote-debugging-port=0` + `connectOverCDP`; the viewport is emulated (a spike measured frames and clicks with the window covered, off-screen, minimized or hidden: a run never needs the user's screen; the window itself can't be moved over CDP). Isolation is verified when the app is added: after a trial launch its state must be inside the sandbox, else refused. Its process group killed after each run, leftovers swept.
+- **Each run launches it sandboxed** (its own HOME, `CFFIXED_USER_HOME`, XDG and temp folders, `--user-data-dir`; an allowlisted environment, never Kiframe's), attached with `--remote-debugging-port=0` + `connectOverCDP`; the viewport is emulated (a spike measured frames and clicks with the window covered, off-screen, minimized or hidden: a run never needs the user's screen; the window itself can't be moved over CDP). Isolation is enforced, never checked after the fact: every launch is confined (below). Its process group killed after each run, leftovers swept.
 - **Confinement: a guard, sealed at launch (PR 2, redesigned after three review rounds, design reviewed).** Once the app settles (its windows unchanged 1.5 s), its main window is the last opened still open; its own scheme or dev server is learned from that window alone, then sealed (nothing a run does adds to it). A main window that isn't the app's own (a wrapper's unlisted site) refuses the launch ("list it in its origins"). From then a **guard** checks every navigation of every frame of every window as it happens: a page that isn't the app's own is stopped at once (a popup closed, any other frame blanked: never left for a read or a frame) and recorded; the step fails `off-app`. The app's own: a local `file:` in its bundle or sandbox (decoded, normalized), its sealed scheme or dev server, a listed https site (`sameApp`, never plain http), a blob of those. Stated (as a web run): the guard acts as a page commits, so a page that isn't the app's own has loaded (its scripts ran, with the app's own rights) before it's stopped: following a link the app offers is what its user does too (blocking before the load needs request interception, which never sees `file:`); and the runner's own navigation events name it as they do for web runs (origin and path, known secret values scrubbed). What the main window embeds as it opens (a frame of another site) is the app as shipped: its origin is the app's own. A main window stopped goes back to the app's page (no goto there to bring it back); a failed load is said as one. **One app per run:** a desktop app's run never shows a site (no goto, URL condition or web preset; a web interrupt rule's goto skipped, said), is confined while grounding too, and keeps no sign-in between runs yet.
 - **Windows (PR 2, known limits, to settle on real apps in PR 3 and PR 5: decided by the user 2026-10-08):** the main window is the last opened still open once the app's windows were unchanged for 1.5 s (a splash that stays up longer is taken for the main window); windows the app's main process opens are followed as popups are (a hidden helper window opened during a step may be followed: CDP can't tell it's hidden); only the launch window is sent back when it goes off-app (another window is closed); a stop that lands after its step ended counts against the next step. A window that opens blank gets a moment to load (as a web page does); a frame of a window the run isn't driving is said, never the step's failure.
-- **Measured on a fixture app (PR 2, 2026-10-08):** HOME, XDG and `--user-data-dir` hold; macOS's own places don't move: Electron's `appData` (`~/Library/Application Support`) and the app's preferences (`NSUserDefaults`, written by `cfprefsd` into the user's real `~/Library/Preferences/<bundle id>.plist`) stay the user's whatever `HOME` or `CFFIXED_USER_HOME` say. The trial launch therefore checks both: the app's state inside the sandbox, and its preferences file unchanged; else the user is told.
+- **Every launch confined (PR 3a, 2026-10-09, design reviewed twice, measured):** on macOS each launch runs under Seatbelt (`sandbox-exec`, `electron-confine.ts`): writes only into its own sandbox; no reads of /Users, /Volumes, the temp folders, the user's home and the work area wherever they are (a home outside /Users) but its sandbox and its bundle; nothing run from its sandbox (the one place it writes: a program it drops there, a copied launcher), no `open`, `osascript`, `launchctl` nor Apple Events; no unix sockets (an agent's: ssh, Docker) but mDNSResponder; no preferences (cfprefsd), keychain (SecurityServer: a mock keychain instead, `--use-mock-keychain`) nor clipboard (the user's may hold a password just copied: an app's own copy and paste doesn't work in a run); network for runs (the app's backend), loopback only for a trial (no updater). Chromium's own sandbox can't nest in it (`--no-sandbox`): the guard and this profile replace it. A canary before every launch, before the files are copied (a read the profile refuses must fail, one of its sandbox succeed: a confinement that runs nothing never passes); no `sandbox-exec`, or a canary failed: no launch (never unconfined). Off macOS: desktop apps don't launch (CI's tests only, unconfined). Measured with a probe app: every escape above `EPERM` (a hard link or a symlink to an outside file too), the app driven as usual. This replaces the trial's after-the-fact isolation check, rejected by review (an app that leaks does its harm as it starts). **What it doesn't stop (stated):** an app can still ask macOS to open a file or a URL (LaunchServices: no app starts without reaching it, measured), and what opens runs outside the confinement; it reaches services on this machine (localhost: a dev build's own server needs it). The app's own pages are its bundle and what it writes in its sandbox's home, profile and temp folders (a page it builds there from remote content counts as its own, as its cache already does); never the files/ copy. The confinement keeps an app from the user's data by accident (the minmux incident), not an app built to escape (one the user runs unconfined every day anyway).
+- **The work area `~/.kiframe/`** (decided by the user 2026-10-09: deletable any time): `sandboxes/` (one per launch, 0700, never a link), each named after the Kiframe that made it (`kiframe-app-<pid>-<start>-…`: owned from the moment it exists, no shared state file to race on); a crash sweep at start removes only sandboxes no running Kiframe owns (the processes pointing at them killed first), never another build's launch, and nothing when `ps` can't be read. Kept out of Time Machine and Spotlight. Approvals stay in the app's settings, takes in app data.
+- **A project's `files/`** (decided by the user 2026-10-09): what a desktop app opens. Copied into the sandbox at each launch by Kiframe's own walk (folders and regular files only: a link, a FIFO, a device refused; 500 MB, 20,000 files, depth 32; cloned where the disk can, times kept); `args` name paths in it only (`files/vault`, given as the copy's path); the app's edits stay in the copy (thrown away: every run from the same files). The copy is the project's content, never the app's own pages for the guard. Filled by the user in v0: the agent's file tools never reach `files/` (it may hold what runs inside the app: an editor's tasks, a vault's plugins).
+- **Measured on a fixture app (PR 2, 2026-10-08):** HOME, XDG and `--user-data-dir` hold; macOS's own places don't move: Electron's `appData` (`~/Library/Application Support`) and the app's preferences (`NSUserDefaults`, written by `cfprefsd` into the user's real `~/Library/Preferences/<bundle id>.plist`) stay the user's whatever `HOME` or `CFFIXED_USER_HOME` say. Hence the confinement (PR 3a, below): the preferences daemon is denied and writes outside the sandbox refused, so neither can be reached (a check after launch, the earlier plan, came too late).
 - **Stated limits:** native dialogs and menus are unreachable; links open in the user's real browser; a sign-in through the browser with an app-scheme callback isn't supported in v0; the keychain and an app's macOS preferences are the user's (an app reading its own keychain item signs in as them); a window built from several views films one view.
 - **Built in steps** (epic `epic/electron-targets`): the format (2026-10-08), the launcher and target, the desktop approval and trial, the studio and batch on it, a real pass on a sandboxed minmux.
 
diff --git a/packages/runtime/src/electron-confine.ts b/packages/runtime/src/electron-confine.ts
new file mode 100644
index 0000000..c0e0efd
--- /dev/null
+++ b/packages/runtime/src/electron-confine.ts
@@ -0,0 +1,226 @@
+import { execFile } from "node:child_process"
+import { constants, existsSync, rmSync, writeFileSync } from "node:fs"
+import { copyFile, lstat, mkdir, readdir, utimes } from "node:fs/promises"
+import type { Stats } from "node:fs"
+import { join } from "node:path"
+import { filesPath } from "@kiframe/schema"
+
+// A desktop app's launch confined by macOS's Seatbelt (`sandbox-exec`; measured on a fixture app,
+// 2026-10-09: every escape below refused, the app driven as usual). Its own sandbox is the only
+// place it writes; it never reads the user's folders, never starts a program outside the
+// confinement (LaunchServices, AppleScript, launchd), never reaches the user's preferences or
+// keychain (a mock keychain instead), never connects to the user's agents' sockets. Chromium's own
+// sandbox can't nest in it (turned off: the guard and this profile replace it).
+
+/** Where the confinement lives (macOS); absent: desktop apps can't be launched (never unconfined). */
+export const SANDBOX_EXEC = "/usr/bin/sandbox-exec"
+
+/** Kiframe's own switches to an app run under the profile (after the project's arguments). */
+export const CONFINED_SWITCHES = ["--no-sandbox", "--use-mock-keychain"]
+
+export interface Confinement {
+  /** The launch's sandbox (real path): the only place written, read in full. */
+  sandbox: string
+  /** What the app reads besides: its bundle (real paths). */
+  readable: readonly string[]
+  /**
+   * The user's own folders, never read (real paths: the home and Kiframe's work area), wherever
+   * they are (a home outside /Users on a managed Mac).
+   */
+  private: readonly string[]
+  /** "all": the app's backend reachable (a run); "loopback": nothing beyond this machine (a trial). */
+  network: "all" | "loopback"
+}
+
+/** A string in the profile's language (quoted, its backslashes and quotes escaped). */
+const q = (s: string) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
+
+/** The Seatbelt profile of a launch. Later rules win over earlier ones. */
+export function seatbeltProfile(c: Confinement): string {
+  const readable = [c.sandbox, ...c.readable].map((p) => `(subpath ${q(p)})`).join(" ")
+  return `(version 1)
+(allow default)
+(deny file-write*)
+(allow file-write* (subpath ${q(c.sandbox)}) (literal "/dev/null") (literal "/dev/zero") (literal "/dev/dtracehelper") (regex #"^/dev/tty") (regex #"^/dev/fd/"))
+(deny file-read-data (subpath "/Users") (subpath "/Volumes") (subpath "/private/var/folders") (subpath "/private/tmp") (subpath "/var/folders") (subpath "/tmp")${c.private.map((p) => ` (subpath ${q(p)})`).join("")})
+(allow file-read-data ${readable})
+(deny network-outbound (remote unix-socket))
+(allow network-outbound (remote unix-socket (path-literal "/private/var/run/mDNSResponder")))
+(deny appleevent-send)
+(deny process-exec* (subpath ${q(c.sandbox)}) (literal "/usr/bin/open") (literal "/usr/bin/osascript") (literal "/bin/launchctl"))
+(deny mach-lookup (global-name "com.apple.cfprefsd.agent") (global-name "com.apple.SecurityServer") (global-name "com.apple.pasteboard.1"))
+${c.network === "loopback" ? '(deny network-outbound)\n(allow network-outbound (remote ip "localhost:*"))\n(allow network-outbound (remote unix-socket (path-literal "/private/var/run/mDNSResponder")))' : ""}
+`
+}
+
+/** A confinement that can't be used: said, and no desktop app is launched (never unconfined). */
+export class ConfinementError extends Error {}
+
+/** Whether a program confined by `c` reads `file` (its content, exactly). */
+function readsUnder(
+  c: Confinement,
+  file: string,
+  content: string,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    execFile(
+      SANDBOX_EXEC,
+      ["-p", seatbeltProfile(c), "/bin/cat", file],
+      { timeout: 5000, ...(signal !== undefined && { signal }) },
+      (error, stdout) => resolve(error === null && stdout === content),
+    )
+  })
+}
+
+/**
+ * Before each launch: the confinement still holds (a canary: a file the profile denies isn't
+ * read, while one in the sandbox is: a confinement that runs nothing never passes for one that
+ * refuses). Missing or broken (a macOS that removed or changed it): refused.
+ */
+export async function checkConfinement(
+  c: Confinement,
+  denied: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (!existsSync(SANDBOX_EXEC)) {
+    throw new ConfinementError(
+      "macOS's sandbox-exec is missing: Kiframe can't confine desktop apps",
+    )
+  }
+  const allowed = join(c.sandbox, "canary.txt")
+  let deniedRead: boolean
+  let allowedRead: boolean
+  let missing: boolean
+  try {
+    writeFileSync(denied, "canary")
+    writeFileSync(allowed, "canary")
+    ;[deniedRead, allowedRead] = await Promise.all([
+      readsUnder(c, denied, "canary", signal),
+      readsUnder(c, allowed, "canary", signal),
+    ])
+    missing = !existsSync(denied)
+  } catch (error) {
+    throw new ConfinementError(
+      `the confinement couldn't be checked (${(error as { code?: string }).code ?? "unwritable"})`,
+    )
+  } finally {
+    rmSync(allowed, { force: true })
+    rmSync(denied, { force: true })
+  }
+  signal?.throwIfAborted()
+  if (deniedRead) {
+    throw new ConfinementError(
+      "the confinement didn't hold (a canary was read): desktop apps are off",
+    )
+  }
+  // Unread because it was gone (removed meanwhile) says nothing of the confinement.
+  if (missing) {
+    throw new ConfinementError("the confinement couldn't be checked (its canary went missing)")
+  }
+  if (!allowedRead) {
+    throw new ConfinementError(
+      "the confinement doesn't run programs (its own sandbox unread): desktop apps are off",
+    )
+  }
+}
+
+/** A project's files/ too large to copy at each launch, or holding what can't be copied safely. */
+export class FilesError extends Error {}
+
+/** The copy's limits (it's made at every launch). */
+export const FILES_LIMITS = { bytes: 500 * 1024 * 1024, files: 20_000, depth: 32 }
+
+/** Still the entry that was checked (same kind, same inode: never a link put in its place). */
+const same = (now: Stats, checked: Stats, kind: "dir" | "file") =>
+  (kind === "dir" ? now.isDirectory() : now.isFile()) &&
+  now.ino === checked.ino &&
+  now.dev === checked.dev
+
+const changed = (rel: string) =>
+  new FilesError(`files${rel} changed while it was copied: try again`)
+
+/**
+ * A project's `files/` copied into a launch's sandbox (what the app opens: every run from the same
+ * files, its edits thrown away). Own walk, never a library copy: only folders and regular files
+ * (a link, a FIFO, a socket, a device refused: never followed, never opened), within the limits;
+ * cloned where the disk can (APFS: near instant), times kept (a run sees the files as they are).
+ */
+export async function copyFiles(from: string, to: string, signal?: AbortSignal): Promise<void> {
+  let bytes = 0
+  let entries = 0
+  const tooLarge = () =>
+    new FilesError("files/ is too large to copy at each launch (500 MB, 20,000 entries)")
+  const walk = async (
+    src: string,
+    dst: string,
+    depth: number,
+    rel: string,
+    checked: Stats,
+  ): Promise<void> => {
+    if (depth > FILES_LIMITS.depth) throw new FilesError(`files/${rel} is nested too deep`)
+    await mkdir(dst, { recursive: true })
+    const names = await readdir(src)
+    // readdir follows a link: a folder swapped for one meanwhile is refused (as a file is).
+    if (!same(await lstat(src), checked, "dir")) throw changed(rel === "" ? "" : `/${rel}`)
+    for (const name of names) {
+      signal?.throwIfAborted()
+      const s = join(src, name)
+      const d = join(dst, name)
+      const r = rel === "" ? name : `${rel}/${name}`
+      const stat = await lstat(s)
+      // Folders count too (a tree of empty ones is as slow to copy and remove).
+      entries += 1
+      if (entries > FILES_LIMITS.files) throw tooLarge()
+      if (stat.isDirectory()) {
+        await walk(s, d, depth + 1, r, stat)
+      } else if (stat.isFile()) {
+        bytes += stat.size
+        if (bytes > FILES_LIMITS.bytes) throw tooLarge()
+        await copyFile(s, d, constants.COPYFILE_FICLONE)
+        // copyFile follows a link: an entry swapped for one meanwhile is refused (still the file
+        // that was checked, never what a link points at).
+        if (!same(await lstat(s), stat, "file")) throw changed(`/${r}`)
+        await utimes(d, stat.atime, stat.mtime)
+      } else {
+        throw new FilesError(`files/${r} isn't a file or a folder (a link?): only those are copied`)
+      }
+    }
+    // And still that folder once its entries are copied (they're reached through its path: one
+    // swapped for a link meanwhile, its entries came from elsewhere; every folder above checks
+    // the same after its own loop).
+    if (!same(await lstat(src), checked, "dir")) throw changed(rel === "" ? "" : `/${rel}`)
+  }
+  try {
+    // files/ itself a real folder (a shared project's files/ linked to the user's documents: never
+    // followed).
+    const root = await lstat(from)
+    if (!root.isDirectory()) {
+      throw new FilesError(
+        "the project's files/ isn't a folder (a link?): only a real one is copied",
+      )
+    }
+    await walk(from, to, 0, "", root)
+  } catch (error) {
+    if (signal?.aborted === true) throw signal.reason
+    if (error instanceof FilesError) throw error
+    const code = (error as { code?: string }).code
+    throw new FilesError(
+      code === "ENOENT" && !existsSync(from)
+        ? "the project has no files/ folder (what its arguments name)"
+        : `files/ couldn't be copied (${code ?? String(error)})`,
+    )
+  }
+}
+
+/**
+ * A launch argument (the project's `files/<path>`) as the app gets it: the copy's absolute path in
+ * the sandbox. Anything else refused (the schema allows nothing else).
+ */
+export function argumentIn(arg: string, filesCopy: string): string {
+  const parts = filesPath(arg)
+  if (parts === undefined) {
+    throw new FilesError(`"${arg}": a desktop app opens only what's in the project's files/`)
+  }
+  return join(filesCopy, ...parts)
+}
diff --git a/packages/runtime/src/electron-workarea.ts b/packages/runtime/src/electron-workarea.ts
new file mode 100644
index 0000000..b8e4354
--- /dev/null
+++ b/packages/runtime/src/electron-workarea.ts
@@ -0,0 +1,271 @@
+import { execFile } from "node:child_process"
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs"
+import { readdir, readlink, rm } from "node:fs/promises"
+import { homedir } from "node:os"
+import { basename, dirname, join } from "node:path"
+
+// Kiframe's work area for desktop apps (decided by the user 2026-10-09): `~/.kiframe/`, safe to
+// delete at any time. Each launch's sandbox is a folder in `sandboxes/` whose name says which
+// Kiframe made it (`kiframe-app-<pid>-<started>-…`: owned from the moment it exists, no state file
+// to race on), so what a crash left is swept at the next start, never another running Kiframe's (a
+// dev and a release build share the folder).
+
+/** The default work area. */
+export function defaultWorkDir(): string {
+  return join(homedir(), ".kiframe")
+}
+
+/** A work area that can't be used (a link, another user's, not a folder): said as is. */
+export class WorkAreaError extends Error {}
+
+const prepared = new Set<string>()
+
+/**
+ * `work`/sandboxes made (or checked): real folders (never links), this user's, readable by them
+ * alone (0700); the work area kept out of backups and Spotlight (once per process). Returns the
+ * sandboxes folder's real path.
+ */
+export function sandboxesOf(work: string): string {
+  const sandboxes = join(work, "sandboxes")
+  for (const dir of [work, sandboxes]) {
+    let stat
+    try {
+      mkdirSync(dir, { recursive: true, mode: 0o700 })
+      stat = lstatSync(dir)
+    } catch (error) {
+      throw new WorkAreaError(
+        `${dir} can't be made (${(error as { code?: string }).code ?? String(error)})`,
+      )
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new WorkAreaError(`${dir} isn't a folder (a link?): Kiframe uses only a real one`)
+    }
+    if (process.getuid !== undefined && stat.uid !== process.getuid()) {
+      throw new WorkAreaError(`${dir} belongs to another user`)
+    }
+    if ((stat.mode & 0o777) !== 0o700) chmodSync(dir, 0o700)
+  }
+  if (!prepared.has(work)) {
+    prepared.add(work)
+    // Never indexed nor backed up (an app's throwaway data). Best effort: said by no one.
+    try {
+      writeFileSync(join(work, ".metadata_never_index"), "")
+    } catch {
+      // read-only? the launch says it next
+    }
+    if (process.platform === "darwin") {
+      execFile("tmutil", ["addexclusion", work], () => undefined)
+    }
+  }
+  return realpathSync(sandboxes)
+}
+
+/**
+ * A new sandbox folder, owned by this process from the moment it exists (its name says so). Its
+ * real path (a file: page's path is compared with it).
+ */
+export async function newSandbox(work: string): Promise<string> {
+  const sandboxes = sandboxesOf(work)
+  const owner = await self()
+  return realpathSync(mkdtempSync(join(sandboxes, `${PREFIX}${owner.pid}-${owner.started}-`)))
+}
+
+const PREFIX = "kiframe-app-"
+
+/** A sandbox folder this module makes: `kiframe-app-*` directly in the work area's sandboxes. */
+export function isSandbox(path: string, work: string): boolean {
+  try {
+    const real = realpathSync(path)
+    return (
+      dirname(real) === realpathSync(join(work, "sandboxes")) &&
+      basename(real).startsWith(PREFIX) &&
+      !lstatSync(path).isSymbolicLink()
+    )
+  } catch {
+    return false
+  }
+}
+
+/** Who started a launch: a Kiframe process, by its id and when it started (ids are reused). */
+interface Owner {
+  pid: number
+  started: number
+}
+
+/** A sandbox's owner, from its name (none: an older or foreign name, owned by no one). */
+function ownerOf(name: string): Owner | undefined {
+  const match = /^kiframe-app-(\d+)-(\d+)-/.exec(name)
+  return match === null ? undefined : { pid: Number(match[1]), started: Number(match[2]) }
+}
+
+/** A command's output (undefined when it fails; lsof's "nothing found" is an answer). */
+export function run(command: string, args: string[]): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    execFile(
+      command,
+      args,
+      // The C locale: what's parsed (a start time) reads the same in every language.
+      { timeout: 5000, maxBuffer: 16 * 1024 * 1024, env: { ...process.env, LC_ALL: "C" } },
+      (error, stdout) => {
+        resolve(error !== null && (error as { code?: unknown }).code !== 1 ? undefined : stdout)
+      },
+    )
+  })
+}
+
+/**
+ * When a process started, in seconds, from `ps`: undefined when it isn't running, null when `ps`
+ * can't be read (nothing can be said of any owner).
+ */
+async function startOf(pid: number): Promise<number | undefined | null> {
+  const out = await run("ps", ["-o", "lstart=", "-p", String(pid)])
+  if (out === undefined) return null
+  const at = Date.parse(out.trim())
+  return Number.isNaN(at) ? undefined : Math.round(at / 1000)
+}
+
+let me: Promise<Owner> | undefined
+/** This process as an owner. */
+function self(): Promise<Owner> {
+  me ??= startOf(process.pid).then((started) => ({
+    pid: process.pid,
+    started: started ?? Math.round(Date.now() / 1000 - process.uptime()),
+  }))
+  return me
+}
+
+/**
+ * Whether an owner still runs: its id alive and started when it was noted (never a reused id, this
+ * process's own included: a note from before a reboot can carry it). Null when `ps` can't say.
+ */
+async function alive(owner: Owner): Promise<boolean | null> {
+  const mine = await self()
+  if (owner.pid === mine.pid) return owner.started === mine.started
+  const started = await startOf(owner.pid)
+  if (started === null) return null
+  return started !== undefined && Math.abs(started - owner.started) <= 2
+}
+
+/**
+ * Every process's working folder: Linux's /proc (quick), else `lsof` (macOS: no /proc); undefined
+ * when it can't be read.
+ */
+async function workingDirs(): Promise<[number, string][] | undefined> {
+  if (process.platform === "linux") {
+    const out: [number, string][] = []
+    try {
+      for (const entry of await readdir("/proc")) {
+        if (!/^\d+$/.test(entry)) continue
+        try {
+          out.push([Number(entry), await readlink(`/proc/${entry}/cwd`)])
+        } catch {
+          // gone, or another user's
+        }
+      }
+      return out
+    } catch {
+      return undefined
+    }
+  }
+  const listed = await run("lsof", ["-a", "-d", "cwd", "-Fpn"])
+  if (listed === undefined) return undefined
+  const out: [number, string][] = []
+  let pid: number | undefined
+  for (const line of listed.split("\n")) {
+    if (line.startsWith("p")) pid = Number(line.slice(1))
+    else if (line.startsWith("n") && pid !== undefined) out.push([pid, line.slice(1)])
+  }
+  return out
+}
+
+/**
+ * Kills every process (never this one) that points at `under`: its command line names it (an
+ * app's helpers carry `--user-data-dir=<sandbox>/profile`), or it works in it (a helper detached
+ * with its cwd there); and the groups of the app's own processes (those with its profile: what
+ * stays in the group after a crash, pointing nowhere). Unread: said.
+ */
+export async function sweepProcesses(
+  unders: string | readonly string[],
+): Promise<{ swept: number; unread: boolean }> {
+  const all = typeof unders === "string" ? [unders] : unders
+  if (all.length === 0) return { swept: 0, unread: false }
+  const [ps, cwds] = await Promise.all([run("ps", ["-axo", "pid=,pgid=,command="]), workingDirs()])
+  const table: { pid: number; pgid: number; command: string }[] = []
+  for (const line of ps?.split("\n") ?? []) {
+    const match = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line)
+    if (match !== null) {
+      table.push({ pid: Number(match[1]), pgid: Number(match[2]), command: match[3] ?? "" })
+    }
+  }
+  const pids = new Set<number>()
+  const groups = new Set<number>()
+  const within = (path: string) =>
+    all.some((under) => path === under || path.startsWith(`${under}/`))
+  for (const p of table) {
+    if (!all.some((under) => p.command.includes(under))) continue
+    pids.add(p.pid)
+    if (all.some((under) => p.command.includes(`--user-data-dir=${under}/`))) groups.add(p.pgid)
+  }
+  for (const [pid, cwd] of cwds ?? []) if (within(cwd)) pids.add(pid)
+  // Never this process's own group.
+  const own = table.find((p) => p.pid === process.pid)?.pgid
+  if (own !== undefined) groups.delete(own)
+  for (const p of table) if (groups.has(p.pgid)) pids.add(p.pid)
+  pids.delete(process.pid)
+  for (const p of pids) {
+    try {
+      process.kill(p, "SIGKILL")
+    } catch {
+      // gone
+    }
+  }
+  return { swept: pids.size, unread: ps === undefined || cwds === undefined }
+}
+
+/**
+ * At the host's start: every sandbox in the work area that no running Kiframe owns (a crash left
+ * it) has the processes pointing at it killed and is removed. Another running Kiframe's launches
+ * are left alone; when `ps` can't be read nothing is swept (an owner can't be told dead). Only this
+ * module's sandboxes are ever touched.
+ */
+export async function sweepWorkArea(work: string): Promise<number> {
+  if (!existsSync(join(work, "sandboxes"))) return 0
+  const sandboxes = sandboxesOf(work)
+  if ((await startOf(process.pid)) === null) return 0
+  const dead: string[] = []
+  for (const name of readdirSync(sandboxes)) {
+    const path = join(sandboxes, name)
+    if (!isSandbox(path, work)) continue
+    const owner = ownerOf(name)
+    const live = owner === undefined ? false : await alive(owner)
+    // ps unreadable meanwhile: nothing said dead.
+    if (live === null) return 0
+    if (!live) dead.push(realpathOr(path))
+  }
+  // One read of the processes for all of them (lsof is slow).
+  await sweepProcesses(dead)
+  for (const path of dead) {
+    await rm(path, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }).catch(
+      () => undefined,
+    )
+  }
+  return dead.length
+}
+
+/** A path's real path, or the path itself when it can't be resolved (gone). */
+export function realpathOr(path: string): string {
+  try {
+    return realpathSync(path)
+  } catch {
+    return path
+  }
+}
diff --git a/packages/runtime/src/electron.ts b/packages/runtime/src/electron.ts
index d961b57..b28e6fa 100644
--- a/packages/runtime/src/electron.ts
+++ b/packages/runtime/src/electron.ts
@@ -1,17 +1,28 @@
-import { execFile, spawn, type ChildProcess } from "node:child_process"
+import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process"
 import { posix } from "node:path"
-import {
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  realpathSync,
-  writeFileSync,
-} from "node:fs"
-import { readdir, readlink, rm } from "node:fs/promises"
-import { tmpdir } from "node:os"
-import { basename, dirname, join, sep } from "node:path"
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs"
+import { rm } from "node:fs/promises"
+import { userInfo } from "node:os"
+import { join, sep } from "node:path"
 import { sameApp, type Viewport } from "@kiframe/schema"
+import {
+  ConfinementError,
+  CONFINED_SWITCHES,
+  argumentIn,
+  checkConfinement,
+  copyFiles,
+  FilesError,
+  SANDBOX_EXEC,
+  seatbeltProfile,
+} from "./electron-confine.ts"
+import {
+  defaultWorkDir,
+  newSandbox,
+  realpathOr,
+  run,
+  sweepProcesses,
+  WorkAreaError,
+} from "./electron-workarea.ts"
 import { untilStopped } from "./look.ts"
 import {
   chromium,
@@ -95,14 +106,30 @@ export interface ElectronLaunch {
   executable: string
   /** Its `.app` bundle: a `file:` page inside it is the app's own. */
   bundle?: string
-  /** What the app opens (positional: the project's `args`). */
+  /** What the app opens: paths in the project's files/ (`files/demo-vault`), given as the copy's. */
   args?: readonly string[]
+  /** The project's files/ folder: copied into the sandbox at each launch (what `args` name). */
+  files?: string
+  /** Kiframe's work area (default `~/.kiframe`): the launches' sandboxes. */
+  workDir?: string
+  /** The network: "all" (a run: the app's backend), "loopback" (a trial: nothing beyond). */
+  network?: "all" | "loopback"
+  /**
+   * Tests: arguments given as they are, before `args` (the fixture app's folder, its modes): never
+   * a project's (those name files/ only).
+   */
+  appArgs?: readonly string[]
+  /** Tests: more it may read (the repo's Electron). */
+  readable?: readonly string[]
+  /**
+   * Off macOS only (Linux CI): launched without the Seatbelt confinement (there's none). Never in
+   * the app: desktop apps are macOS-only.
+   */
+  allowUnconfined?: boolean
   /** The size its windows are shown at (emulated: the window itself is never moved). */
   viewport: Pick<Viewport, "width" | "height" | "deviceScaleFactor">
   /** The https sites a wrapper app shows as its own (the project's `origins`). */
   origins?: readonly string[]
-  /** A file noting the launches still running: what a crash left is swept at the next start. */
-  stateFile?: string
   signal?: AbortSignal
   /**
    * How long its windows must stay as they are before its main window is chosen (default 1.5 s: a
@@ -147,10 +174,35 @@ export interface ElectronTarget {
   close: () => Promise<{ unread: boolean }>
 }
 
-/** A fresh sandbox: the app's HOME (and macOS's), its XDG folders, its temp and its profile. */
-function makeSandbox(): { root: string; env: NodeJS.ProcessEnv; profile: string } {
-  // The real path: macOS's /var is a link (a file: page's path is compared with it).
-  const root = realpathSync(mkdtempSync(join(tmpdir(), "kiframe-app-")))
+/** Its own process group (killed whole), no terminal; its output read for the port only. */
+function spawnOptions(sandbox: { root: string; env: NodeJS.ProcessEnv }): SpawnOptions {
+  return {
+    detached: true,
+    env: sandbox.env,
+    stdio: ["ignore", "ignore", "pipe"],
+    cwd: sandbox.root,
+  }
+}
+
+/**
+ * A fresh sandbox in the work area: the app's HOME (and macOS's), XDG, temp, profile, files. One
+ * that can't be made is said (and nothing of it kept).
+ */
+async function makeSandbox(work: string): Promise<{
+  root: string
+  env: NodeJS.ProcessEnv
+  profile: string
+  home: string
+  tmp: string
+  files: string
+}> {
+  let root: string
+  try {
+    root = await newSandbox(work)
+  } catch (error) {
+    if (error instanceof WorkAreaError) throw new ElectronLaunchError(error.message)
+    throw new ElectronLaunchError(`Kiframe's work area can't be used (${String(error)})`)
+  }
   const dirs = {
     home: join(root, "home"),
     config: join(root, "home", ".config"),
@@ -160,7 +212,12 @@ function makeSandbox(): { root: string; env: NodeJS.ProcessEnv; profile: string
     tmp: join(root, "tmp"),
     profile: join(root, "profile"),
   }
-  for (const dir of Object.values(dirs)) mkdirSync(dir, { recursive: true })
+  try {
+    for (const dir of Object.values(dirs)) mkdirSync(dir, { recursive: true })
+  } catch (error) {
+    await rm(root, { recursive: true, force: true }).catch(() => undefined)
+    throw new ElectronLaunchError(`the app's sandbox can't be made (${String(error)})`)
+  }
   const env: NodeJS.ProcessEnv = {}
   for (const name of PASSED_ENV) if (process.env[name] !== undefined) env[name] = process.env[name]
   for (const [name, value] of Object.entries(process.env)) {
@@ -169,7 +226,7 @@ function makeSandbox(): { root: string; env: NodeJS.ProcessEnv; profile: string
   Object.assign(env, {
     HOME: dirs.home,
     // macOS: what reads NSHomeDirectory follows it (not appData, not the app's preferences: those
-    // stay the user's, checked by the trial launch).
+    // stay the user's, out of reach under the confinement).
     CFFIXED_USER_HOME: dirs.home,
     XDG_CONFIG_HOME: dirs.config,
     XDG_DATA_HOME: dirs.data,
@@ -177,7 +234,14 @@ function makeSandbox(): { root: string; env: NodeJS.ProcessEnv; profile: string
     XDG_STATE_HOME: dirs.state,
     TMPDIR: `${dirs.tmp}${sep}`,
   })
-  return { root, env, profile: dirs.profile }
+  return {
+    root,
+    env,
+    profile: dirs.profile,
+    home: dirs.home,
+    tmp: dirs.tmp,
+    files: join(root, "files"),
+  }
 }
 
 /** How long the app's windows must stay as they are before its main window is chosen. */
@@ -194,14 +258,71 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
   } catch {
     throw new ElectronLaunchError(`the app isn't at ${opts.bundle ?? ""} any more`)
   }
+  // The executable there and runnable (under Seatbelt the spawned program is sandbox-exec: a
+  // missing app would otherwise read as one that quit).
+  try {
+    accessSync(opts.executable, constants.X_OK)
+  } catch {
+    throw new ElectronLaunchError(`the app couldn't be launched (${opts.executable} isn't there)`)
+  }
+  // Never unconfined in the app: off macOS (no Seatbelt) only where asked (Linux CI).
+  const confined = process.platform === "darwin"
+  if (!confined && opts.allowUnconfined !== true) {
+    throw new ElectronLaunchError("desktop apps run only on macOS (they're confined there)")
+  }
+  const work = opts.workDir ?? defaultWorkDir()
+  const sandbox = await makeSandbox(work)
+  // Its files and its confinement ready before it starts (said, its sandbox removed, if not).
+  let args: string[]
+  let profile: string | undefined
+  try {
+    // The confinement first (cheap): a broken one never costs the files' copy.
+    if (confined) {
+      const confinement = {
+        sandbox: sandbox.root,
+        readable: [...bundles.map(realpathOr), ...(opts.readable ?? []).map(realpathOr)],
+        // The home and the work area wherever they are, and the one temp folder left (/var/tmp).
+        private: [realpathOr(userInfo().homedir), realpathOr(work), "/private/var/tmp"],
+        network: opts.network ?? "all",
+      }
+      // Its own canary, beside its sandbox (never inside: that's readable) and named after it:
+      // launches at once never touch each other's, and a crash's is swept with its sandbox.
+      await checkConfinement(confinement, `${sandbox.root}.canary`, opts.signal)
+      profile = seatbeltProfile(confinement)
+    }
+    if (opts.files !== undefined) await copyFiles(opts.files, sandbox.files, opts.signal)
+    args = (opts.args ?? []).map((a) => argumentIn(a, sandbox.files))
+    for (const arg of args) {
+      if (!existsSync(arg)) {
+        throw new ElectronLaunchError(`${arg.slice(sandbox.files.length + 1)} isn't in files/`)
+      }
+    }
+    // Stopped meanwhile: never started.
+    opts.signal?.throwIfAborted()
+  } catch (error) {
+    await rm(sandbox.root, { recursive: true, force: true }).catch(() => undefined)
+    if (error instanceof FilesError || error instanceof ConfinementError) {
+      throw new ElectronLaunchError(error.message)
+    }
+    throw error
+  }
+  // The app's own time to start (the copy and the canary never count against it).
   const deadline = Date.now() + (opts.timeoutMs ?? LAUNCH_MS)
-  const sandbox = makeSandbox()
-  const child = spawn(
-    opts.executable,
-    [...(opts.args ?? []), `--user-data-dir=${sandbox.profile}`, "--remote-debugging-port=0"],
-    // Its own process group (killed whole), no terminal; its output read for the port only.
-    { detached: true, env: sandbox.env, stdio: ["ignore", "ignore", "pipe"], cwd: sandbox.root },
-  )
+  const launchArgs = [
+    ...(opts.appArgs ?? []),
+    ...args,
+    `--user-data-dir=${sandbox.profile}`,
+    "--remote-debugging-port=0",
+  ]
+  const child =
+    profile === undefined
+      ? spawn(opts.executable, launchArgs, spawnOptions(sandbox))
+      : // Seatbelt runs the app itself (one process: its group, its pid), Kiframe's switches last.
+        spawn(
+          SANDBOX_EXEC,
+          ["-p", profile, opts.executable, ...launchArgs, ...CONFINED_SWITCHES],
+          spawnOptions(sandbox),
+        )
   // Its spawn failing is said by the launch (never an unhandled 'error' event).
   let spawnError: Error | undefined
   child.on("error", (error) => (spawnError = error))
@@ -214,7 +335,7 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
       const alive = browser?.isConnected() === true
       // Killed first, the connection closed after (it drops with the app: never a close the app
       // has to answer), bounded all the same.
-      const ended = await stop(child, sandbox.root, opts.stateFile, alive)
+      const ended = await stop(child, sandbox.root, alive)
       const t0 = Date.now()
       await within(
         browser?.close().catch(() => undefined),
@@ -224,9 +345,6 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
       return ended
     })())
   try {
-    // Noted at once (a crash from here on is swept at the next start); a note that can't be
-    // written ends the launch (never an app left running unnoted).
-    note(opts.stateFile, sandbox.root, true)
     const endpoint = await debuggingEndpoint(
       child,
       sandbox.profile,
@@ -266,7 +384,8 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
     }
     const own = {
       bundles,
-      sandbox: sandbox.root,
+      // Its home, profile and temp (its own data): never the files/ copy (a project's content).
+      trusted: [sandbox.home, sandbox.profile, sandbox.tmp],
       launched,
       schemes,
       origins: [...(opts.origins ?? []), ...embedded],
@@ -529,7 +648,8 @@ export function allowedPage(
   url: string,
   own: {
     bundles: readonly string[]
-    sandbox: string
+    /** The sandbox's folders that are the app's own data (its home, its profile). */
+    trusted: readonly string[]
     launched: ReadonlySet<string>
     schemes: ReadonlySet<string>
     origins: readonly string[]
@@ -558,7 +678,7 @@ export function allowedPage(
     path = posix.normalize(path)
     const inside = (dir: string) =>
       path === dir || path.startsWith(dir.endsWith("/") ? dir : `${dir}/`)
-    return own.bundles.some(inside) || inside(own.sandbox)
+    return own.bundles.some(inside) || own.trusted.some(inside)
   }
   if (parsed.protocol === "http:" || parsed.protocol === "https:") {
     return (
@@ -578,7 +698,6 @@ export function allowedPage(
 async function stop(
   child: ChildProcess,
   sandbox: string,
-  stateFile: string | undefined,
   alive: boolean,
 ): Promise<{ unread: boolean }> {
   const pid = child.pid
@@ -592,18 +711,13 @@ async function stop(
   timing("kill", t0)
   // Helpers that left the group (a daemon, a pty host) still point at the sandbox.
   t0 = Date.now()
-  const swept = await sweepSandbox(sandbox)
+  const swept = await sweepProcesses(sandbox)
   timing("sweep", t0)
   t0 = Date.now()
   await rm(sandbox, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }).catch(
     () => undefined,
   )
   timing("remove", t0)
-  try {
-    note(stateFile, sandbox, false)
-  } catch {
-    // kept: swept at the next start
-  }
   return { unread: swept.unread }
 }
 
@@ -630,117 +744,3 @@ function signalGroup(pid: number, signal: NodeJS.Signals) {
     // gone
   }
 }
-
-/** A command's output (empty when it fails: said by the caller's next check). */
-function run(command: string, args: string[]): Promise<string | undefined> {
-  return new Promise((resolve) => {
-    execFile(command, args, { timeout: 5000, maxBuffer: 16 * 1024 * 1024 }, (error, stdout) => {
-      // lsof exits 1 when nothing matches: its output (empty) is still the answer.
-      resolve(error !== null && (error as { code?: unknown }).code !== 1 ? undefined : stdout)
-    })
-  })
-}
-
-/**
- * Every process's working folder: Linux's /proc (quick), else `lsof` (macOS: no /proc); undefined
- * when it can't be read.
- */
-async function workingDirs(): Promise<[number, string][] | undefined> {
-  if (process.platform === "linux") {
-    const out: [number, string][] = []
-    try {
-      for (const entry of await readdir("/proc")) {
-        if (!/^\d+$/.test(entry)) continue
-        try {
-          out.push([Number(entry), await readlink(`/proc/${entry}/cwd`)])
-        } catch {
-          // gone, or another user's
-        }
-      }
-      return out
-    } catch {
-      return undefined
-    }
-  }
-  const listed = await run("lsof", ["-a", "-d", "cwd", "-Fpn"])
-  if (listed === undefined) return undefined
-  const out: [number, string][] = []
-  let pid: number | undefined
-  for (const line of listed.split("\n")) {
-    if (line.startsWith("p")) pid = Number(line.slice(1))
-    else if (line.startsWith("n") && pid !== undefined) out.push([pid, line.slice(1)])
-  }
-  return out
-}
-
-/**
- * Kills every process (never this one) that points at `sandbox`: its command line names it (the
- * app's helpers carry `--user-data-dir=<sandbox>/profile`), or it works in it (a helper detached
- * with its cwd there). Both are quick to read (never a walk of every file). Unread: said.
- */
-export async function sweepSandbox(sandbox: string): Promise<{ swept: number; unread: boolean }> {
-  if (!existsSync(sandbox)) return { swept: 0, unread: false }
-  const [ps, cwds] = await Promise.all([run("ps", ["-axo", "pid=,command="]), workingDirs()])
-  const pids = new Set<number>()
-  const within = (path: string) => path === sandbox || path.startsWith(`${sandbox}/`)
-  for (const line of ps?.split("\n") ?? []) {
-    const match = /^\s*(\d+)\s+(.*)$/.exec(line)
-    if (match !== null && match[2]?.includes(sandbox) === true) pids.add(Number(match[1]))
-  }
-  for (const [pid, cwd] of cwds ?? []) if (within(cwd)) pids.add(pid)
-  pids.delete(process.pid)
-  for (const p of pids) {
-    try {
-      process.kill(p, "SIGKILL")
-    } catch {
-      // gone
-    }
-  }
-  return { swept: pids.size, unread: ps === undefined || cwds === undefined }
-}
-
-/** Adds (or removes) a running launch's sandbox in the state file. */
-function note(stateFile: string | undefined, sandbox: string, running: boolean) {
-  if (stateFile === undefined) return
-  const all = readState(stateFile).filter((s) => s !== sandbox)
-  if (running) all.push(sandbox)
-  writeFileSync(stateFile, JSON.stringify(all))
-}
-
-/** A sandbox this module made: a `kiframe-app-*` folder directly in the temp folder, nothing else. */
-function isSandbox(path: string): boolean {
-  try {
-    const real = realpathSync(path)
-    return dirname(real) === realpathSync(tmpdir()) && basename(real).startsWith("kiframe-app-")
-  } catch {
-    return false
-  }
-}
-
-function readState(stateFile: string): string[] {
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(stateFile, "utf8"))
-    return Array.isArray(parsed) ? parsed.filter((s): s is string => typeof s === "string") : []
-  } catch {
-    return []
-  }
-}
-
-/**
- * What a crash left (launches still noted): every process pointing at their sandboxes killed (by
- * the sandbox, never a process id that may be another program's by now), the sandboxes removed.
- * Only folders this module makes are touched. Called at the host's start.
- */
-export async function sweepElectronOrphans(stateFile: string): Promise<number> {
-  const left = readState(stateFile).filter(isSandbox)
-  for (const sandbox of left) {
-    await sweepSandbox(sandbox)
-    await rm(sandbox, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }).catch(
-      () => undefined,
-    )
-  }
-  // Only what was swept: a launch noted meanwhile (a run started during the sweep) stays.
-  const now = readState(stateFile).filter((s) => !left.includes(s))
-  writeFileSync(stateFile, JSON.stringify(now))
-  return left.length
-}
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index 0c1a248..f762c97 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -14,8 +14,9 @@ export {
   ElectronLaunchError,
   type ElectronTarget,
   launchElectron,
-  sweepElectronOrphans,
 } from "./electron.ts"
+export { defaultWorkDir, sweepWorkArea, WorkAreaError } from "./electron-workarea.ts"
+export { ConfinementError, FILES_LIMITS, seatbeltProfile } from "./electron-confine.ts"
 export { LookRefusal, maskedScreenshot, type MaskedShot } from "./look.ts"
 export {
   fitImage,
diff --git a/packages/runtime/test/electron.test.ts b/packages/runtime/test/electron.test.ts
index 0269032..fe631d2 100644
--- a/packages/runtime/test/electron.test.ts
+++ b/packages/runtime/test/electron.test.ts
@@ -1,31 +1,43 @@
 import {
+  chmodSync,
   existsSync,
+  lstatSync,
+  mkdirSync,
   mkdtempSync,
   readdirSync,
+  renameSync,
   readFileSync,
+  realpathSync,
   rmSync,
+  statSync,
   symlinkSync,
   writeFileSync,
 } from "node:fs"
 import { createRequire } from "node:module"
-import { tmpdir } from "node:os"
-import { join } from "node:path"
+import { tmpdir, userInfo } from "node:os"
+import { dirname, join } from "node:path"
 import { parseProjectYaml, parseScenarioYaml } from "@kiframe/schema"
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest"
-import { execFileSync } from "node:child_process"
+import { execFileSync, spawn, spawnSync } from "node:child_process"
 import { createServer, type Server } from "node:http"
+import { createServer as createNetServer } from "node:net"
+import { pathToFileURL } from "node:url"
 import { createServer as createHttpsServer } from "node:https"
 import type { AddressInfo } from "node:net"
 import {
   allowedPage,
   ElectronLaunchError,
   type ElectronTarget,
+  FILES_LIMITS,
   launchElectron,
   recordScenario,
   runScenario,
   StepError,
-  sweepElectronOrphans,
+  seatbeltProfile,
+  sweepWorkArea,
 } from "../src/index.ts"
+import { checkConfinement, copyFiles } from "../src/electron-confine.ts"
+import { sandboxesOf } from "../src/electron-workarea.ts"
 
 // The Electron target (OBJECT-MODEL §0.9 "Electron apps"): a fixture desktop app launched in a
 // sandbox with the repo's own Electron, driven and filmed like a web page, ended whole.
@@ -35,6 +47,22 @@ const electron = createRequire(join(import.meta.dirname, "../../../apps/desktop/
 ) as string
 const fixture = join(import.meta.dirname, "fixtures/electron-app")
 const viewport = { width: 800, height: 600, deviceScaleFactor: 1 }
+/** The repo's Electron.app (the fixture runs on it): what the confined app may read besides. */
+const electronApp = electron.slice(0, electron.indexOf(".app/") + 4)
+/** How many sandboxes this file's work area holds (one left behind is a leak). */
+const sandboxCount = () =>
+  existsSync(join(work, "sandboxes")) ? readdirSync(join(work, "sandboxes")).length : 0
+/** This file's work area (never the user's ~/.kiframe). */
+const work = mkdtempSync(join(tmpdir(), "kiframe-el-work-"))
+/** How every launch here runs: the fixture on the repo's Electron, confined on macOS. */
+const base = {
+  executable: electron,
+  bundle: fixture,
+  readable: [electronApp],
+  workDir: work,
+  allowUnconfined: true,
+  viewport,
+}
 
 const project = parseProjectYaml(`version: 2
 apps:
@@ -115,14 +143,22 @@ const inTarget = (target: ElectronTarget) => ({
 })
 
 let open: ElectronTarget[] = []
-const launch = async (extra: string[] = [], options: { stateFile?: string } = {}) => {
+const launch = async (
+  extra: string[] = [],
+  options: {
+    workDir?: string
+    files?: string
+    args?: string[]
+    readable?: string[]
+    timeoutMs?: number
+    signal?: AbortSignal
+  } = {},
+) => {
   const target = await launchElectron({
-    executable: electron,
-    bundle: fixture,
-    args: [fixture, "hidden", `link=${other}`, ...extra],
+    ...base,
+    appArgs: [fixture, "hidden", `link=${other}`, ...extra],
     // A plain fixture settles at once; the window-shape tests keep the real wait.
     ...(!extra.some((e) => ["splash", "swap", "embed-at-start"].includes(e)) && { settleMs: 300 }),
-    viewport,
     ...options,
   })
   open.push(target)
@@ -354,23 +390,30 @@ steps:
     expect(await waitFor(() => !alive(grouped))).toBe(true)
   })
 
-  it("never leaves an app running when its launch can't be noted", async () => {
-    const before = readdirSync(tmpdir()).filter((d) => d.startsWith("kiframe-app-")).length
-    await expect(
-      launch([], { stateFile: join(tmpdir(), "no-such-folder-x", "launches.json") }),
-    ).rejects.toThrow()
-    expect(readdirSync(tmpdir()).filter((d) => d.startsWith("kiframe-app-")).length).toBe(before)
+  it("never sweeps a launch as it starts (owned from the moment its sandbox exists)", async () => {
+    const own = mkdtempSync(join(tmpdir(), "kiframe-el-work-"))
+    // Another Kiframe starting meanwhile sweeps the work area again and again.
+    let starting = true
+    const sweeps = (async () => {
+      while (starting) {
+        await sweepWorkArea(own)
+        await new Promise((resolve) => setTimeout(resolve, 5))
+      }
+    })()
+    try {
+      const target = await launch([], { workDir: own })
+      expect(existsSync(target.sandbox)).toBe(true)
+      expect(await target.page.title()).toBe("Fixture notes")
+    } finally {
+      starting = false
+      await sweeps
+    }
   })
 
   it("takes a bundle given through a link (its pages report either path)", async () => {
     const link = join(mkdtempSync(join(tmpdir(), "kiframe-el-link-")), "Fixture.app")
     symlinkSync(fixture, link)
-    const target = await launchElectron({
-      executable: electron,
-      bundle: link,
-      args: [link, "hidden"],
-      viewport,
-    })
+    const target = await launchElectron({ ...base, bundle: link, appArgs: [link, "hidden"] })
     open.push(target)
     await runScenario(
       target.page,
@@ -387,25 +430,59 @@ steps:
     )
   })
 
-  it("sweeps what a crash left (by the files they hold), at the next start", async () => {
-    const stateFile = join(mkdtempSync(join(tmpdir(), "kiframe-el-state-")), "launches.json")
-    const target = await launch([], { stateFile })
-    const pidFile = join(target.sandbox, "profile", "helper.pid")
-    await waitFor(() => existsSync(pidFile))
-    const helper = Number(readFileSync(pidFile, "utf8"))
-    expect(JSON.parse(readFileSync(stateFile, "utf8"))).toHaveLength(1)
-    // Kiframe "crashed": never closed. The next start sweeps it.
-    expect(await sweepElectronOrphans(stateFile)).toBe(1)
-    expect(await waitFor(() => !alive(helper))).toBe(true)
-    expect(existsSync(target.sandbox)).toBe(false)
-    expect(JSON.parse(readFileSync(stateFile, "utf8"))).toEqual([])
-  })
+  it("sweeps what a crash left at the next start (its owner gone)", async () => {
+    const own = mkdtempSync(join(tmpdir(), "kiframe-el-work-"))
+    // A Kiframe that launched the app, then crashed (killed outright: nothing of it ran after).
+    const kiframe = spawn(
+      process.execPath,
+      [
+        "--experimental-strip-types",
+        "--no-warnings",
+        join(import.meta.dirname, "fixtures/crash-launch.ts"),
+        own,
+        electron,
+        fixture,
+        electronApp,
+        fixture,
+      ],
+      { stdio: ["ignore", "pipe", "inherit"] },
+    )
+    let printed = ""
+    kiframe.stdout.on("data", (d: Buffer) => (printed += d.toString()))
+    const pids: number[] = []
+    try {
+      expect(await waitFor(() => printed.includes("\n"), 30_000)).toBe(true)
+      const sandbox = printed.trim()
+      const pid = (name: string) => Number(readFileSync(join(sandbox, "profile", name), "utf8"))
+      // main.pid is written last.
+      await waitFor(() => existsSync(join(sandbox, "profile", "main.pid")))
+      pids.push(pid("main.pid"))
+      const helper = pid("helper.pid")
+      // And one left in the app's group, pointing nowhere (its cwd /, no sandbox in its command).
+      const grouped = pid("grouped.pid")
+      pids.push(helper, grouped)
+      // While it runs, its launch is its own: never swept.
+      expect(await sweepWorkArea(own)).toBe(0)
+      kiframe.kill("SIGKILL")
+      expect(await waitFor(() => kiframe.exitCode !== null || kiframe.signalCode !== null)).toBe(
+        true,
+      )
+      expect(alive(helper) && alive(grouped)).toBe(true)
+      expect(await sweepWorkArea(own)).toBe(1)
+      expect(await waitFor(() => !alive(helper) && !alive(grouped))).toBe(true)
+      expect(existsSync(sandbox)).toBe(false)
+    } finally {
+      // Never left running when the test fails midway.
+      kiframe.kill("SIGKILL")
+      for (const pid of pids) if (alive(pid)) process.kill(pid, "SIGKILL")
+    }
+  }, 60_000)
 
   it("says an app that quits at once, and leaves nothing behind", async () => {
-    const before = readdirSync(tmpdir()).filter((d) => d.startsWith("kiframe-app-")).length
+    const before = sandboxCount()
     await expect(launch(["quit-at-once"])).rejects.toThrow(ElectronLaunchError)
     await expect(launch(["quit-at-once"])).rejects.toThrow(/quit before Kiframe could attach/)
-    expect(readdirSync(tmpdir()).filter((d) => d.startsWith("kiframe-app-")).length).toBe(before)
+    expect(sandboxCount()).toBe(before)
   })
 
   it("learns its own scheme from a window it opens after a splash (never from a step)", async () => {
@@ -529,10 +606,8 @@ steps: [{ id: add, action: click, target: { by: role, role: button, name: Add no
   it("keeps what the app embeds as it opens, and takes its window back from a site", async () => {
     // A frame of another (https) site shown at launch is the app as shipped: never a stop.
     const embeds = await launchElectron({
-      executable: electron,
-      bundle: fixture,
-      args: [fixture, "hidden", `link=${secure}`, "embed-at-start", "trust-test-cert"],
-      viewport,
+      ...base,
+      appArgs: [fixture, "hidden", `link=${secure}`, "embed-at-start", "trust-test-cert"],
     })
     open.push(embeds)
     await runScenario(
@@ -763,11 +838,11 @@ steps:
   })
 
   it("says an app that isn't there any more, or can't start, never crashing the host", async () => {
+    await expect(launchElectron({ ...base, bundle: "/Applications/Gone.app" })).rejects.toThrow(
+      "the app isn't at /Applications/Gone.app any more",
+    )
     await expect(
-      launchElectron({ executable: electron, bundle: "/Applications/Gone.app", viewport }),
-    ).rejects.toThrow("the app isn't at /Applications/Gone.app any more")
-    await expect(
-      launchElectron({ executable: "/no/such/executable", viewport, timeoutMs: 5000 }),
+      launchElectron({ ...base, executable: "/no/such/executable", timeoutMs: 5000 }),
     ).rejects.toThrow(/the app couldn't be launched/)
   })
 
@@ -803,10 +878,8 @@ presets:
   it("stops when the run is stopped while it launches", async () => {
     const stop = new AbortController()
     const launching = launchElectron({
-      executable: electron,
-      bundle: fixture,
-      args: [fixture, "hidden"],
-      viewport,
+      ...base,
+      appArgs: [fixture, "hidden"],
       signal: stop.signal,
     })
     stop.abort(new Error("stopped"))
@@ -817,7 +890,7 @@ presets:
 describe("a desktop app's own pages", () => {
   const own = {
     bundles: ["/Applications/Notes.app"],
-    sandbox: "/tmp/kiframe-app-x",
+    trusted: ["/tmp/kiframe-app-x/home", "/tmp/kiframe-app-x/profile"],
     launched: new Set(["http://localhost:5173"]),
     schemes: new Set(["app:", "vscode-file:"]),
     origins: ["https://app.slack.com"],
@@ -843,6 +916,9 @@ describe("a desktop app's own pages", () => {
   it("are never the user's files, another site or port, or a data: page", () => {
     for (const url of [
       "file:///etc/hosts",
+      // The sandbox's copy of the project's files/ (its content: never the app's own pages).
+      "file:///tmp/kiframe-app-x/files/demo/index.html",
+      "file:///tmp/kiframe-app-x/tmp/x.html",
       "file:///Applications/Notes.app.evil/x.html",
       "file:///Applications/Notes.app/../Mail.app/x.html",
       "file:///Users/me/Documents/secret.pdf",
@@ -869,36 +945,398 @@ describe("a desktop app's own pages", () => {
   })
 })
 
-// The state file only names sandboxes Kiframe made: never a folder from a tampered file.
-describe("the launches' state file", () => {
-  it("keeps a launch noted while it sweeps (only what it swept is removed)", async () => {
-    const dir = mkdtempSync(join(tmpdir(), "kiframe-el-state-"))
-    const left = mkdtempSync(join(tmpdir(), "kiframe-app-"))
-    const meanwhile = mkdtempSync(join(tmpdir(), "kiframe-app-"))
-    const stateFile = join(dir, "launches.json")
-    writeFileSync(stateFile, JSON.stringify([left]))
+// The confinement (macOS's Seatbelt, measured 2026-10-09): every escape refused, the app driven.
+describe.runIf(process.platform === "darwin")(
+  "a desktop app's confinement",
+  { timeout: 60_000 },
+  () => {
+    it("refuses every escape it tries: the user's folders, other launchers, sockets, the keychain", async () => {
+      const outside = join(mkdtempSync(join(tmpdir(), "kiframe-el-outside-")), "private.txt")
+      writeFileSync(outside, "the user's own file")
+      // An agent's socket outside the sandbox (as ssh-agent's, Docker's): it would accept.
+      const socket = `/private/tmp/kf-${process.pid}.sock`
+      const agent = createNetServer((c) => c.end())
+      await new Promise<void>((resolve) => agent.listen(socket, resolve))
+      const probes = [
+        join(userInfo().homedir, "Library", "KiframeProbe.txt"),
+        "/Users/Shared/KiframeProbe.txt",
+        "/private/tmp/KiframeProbe.txt",
+        "/Applications/KiframeProbe.txt",
+      ]
+      try {
+        const target = await launch(["probes", `outside=${outside}`, `socket=${socket}`])
+        const file = join(target.sandbox, "profile", "probes.json")
+        expect(await waitFor(() => existsSync(file), 10_000)).toBe(true)
+        const seen = JSON.parse(readFileSync(file, "utf8")) as Record<string, string>
+        for (const escape of [
+          "write-real-home",
+          "read-real-home",
+          "write-users-shared",
+          "write-private-tmp",
+          "write-applications",
+          "read-outside",
+          "hardlink-outside",
+          "exec-open",
+          "exec-osascript",
+          "exec-launchctl",
+          "exec-copied",
+          "socket-agent",
+        ]) {
+          // Refused by the confinement itself (never an error of another kind passing for one).
+          expect(seen[escape], escape).toBe("DENIED EPERM")
+        }
+        // Never the user's clipboard (measured: an unconfined read saw what the host had copied).
+        expect(seen["clipboard-read"]).toBe("0")
+        // A mock keychain (never the user's): encryption still works for the app.
+        expect(seen["keychain-encrypts"]).toBe("OK true")
+        // And the app is driven as usual.
+        await runScenario(
+          target.page,
+          parseScenarioYaml(`version: 1
+steps:
+  - { id: add, action: click, target: { by: role, role: button, name: Add note } }
+  - { id: one, action: expect, that: { text: "Notes: 1" } }
+`),
+          project,
+          { electron: inTarget(target), timeoutMs: 5000 },
+        )
+      } finally {
+        // A probe that got through would have left its file: never kept.
+        for (const probe of probes) rmSync(probe, { force: true })
+        agent.close()
+      }
+    })
+
+    it("never launches when the confinement doesn't hold (a canary is read)", async () => {
+      // A profile that lets the canary be read (its folder readable): refused, no app started.
+      const own = mkdtempSync(join(tmpdir(), "kiframe-el-work-"))
+      await expect(
+        launch([], { workDir: own, readable: [electronApp, realpathSync(own)] }),
+      ).rejects.toThrow(/the confinement didn't hold/)
+      expect(readdirSync(join(own, "sandboxes"))).toEqual([])
+    })
+
+    it("never lets launches at once spoil each other's canary", async () => {
+      // Broken launches (their canary readable) beside sound ones that end right after their
+      // canary (an argument missing): a shared canary removed by one is "unread" by another.
+      const own = mkdtempSync(join(tmpdir(), "kiframe-el-work-"))
+      const [broken, sound] = await Promise.all([
+        Promise.allSettled(
+          Array.from({ length: 8 }, () =>
+            launch([], { workDir: own, readable: [electronApp, realpathSync(own)] }),
+          ),
+        ),
+        Promise.allSettled(
+          Array.from({ length: 8 }, () => launch([], { workDir: own, args: ["files/missing"] })),
+        ),
+      ])
+      for (const b of broken) {
+        expect(b.status === "rejected" && String(b.reason)).toMatch(/didn't hold/)
+      }
+      // The sound ones fail only for what they lack (never their canary spoiled by another).
+      for (const s of sound) {
+        expect(s.status === "rejected" && String(s.reason)).toMatch(/isn't in files/)
+      }
+      // None left (each beside its sandbox, removed with it).
+      expect(readdirSync(join(own, "sandboxes")).filter((n) => n.endsWith(".canary"))).toEqual([])
+    })
+
+    it("never passes a canary that went missing for one that was refused", async () => {
+      // Every canary removed as soon as it's written (as another launch would): unread for that
+      // reason, the check proves nothing, and a broken confinement must still never pass.
+      const own = mkdtempSync(join(tmpdir(), "kiframe-el-work-"))
+      sandboxesOf(own)
+      // Polled on every turn of the loop: faster than a confined program starts.
+      let watching = true
+      const remove = () => {
+        for (const name of readdirSync(join(own, "sandboxes"))) {
+          if (name.endsWith(".canary")) rmSync(join(own, "sandboxes", name), { force: true })
+        }
+        if (watching) setImmediate(remove)
+      }
+      remove()
+      try {
+        await expect(
+          launch([], { workDir: own, readable: [electronApp, realpathSync(own)] }),
+        ).rejects.toThrow(ElectronLaunchError)
+      } finally {
+        watching = false
+      }
+    })
+
+    it("never passes a confinement that runs nothing for one that refuses", async () => {
+      // A sandbox named through a link (/var → /private/var): Seatbelt matches real paths, so the
+      // confined read of its own sandbox fails, as it would were sandbox-exec broken.
+      const real = mkdtempSync(join(realpathSync(tmpdir()), "kiframe-el-canary-"))
+      const linked = real.replace(/^\/private\/var\//, "/var/")
+      expect(linked).not.toBe(real)
+      await expect(
+        checkConfinement(
+          { sandbox: linked, readable: [], private: [], network: "all" },
+          join(mkdtempSync(join(tmpdir(), "kiframe-el-work-")), "canary.txt"),
+        ),
+      ).rejects.toThrow(/doesn't run programs/)
+    })
+
+    it("never reads the user's home wherever it is (a home outside /Users)", async () => {
+      // /var/tmp: outside every folder the profile denies by itself (as a /Network/Users home).
+      const home = mkdtempSync("/private/var/tmp/kiframe-el-home-")
+      const sandbox = mkdtempSync(join(realpathSync(tmpdir()), "kiframe-el-sb-"))
+      const confinement = { sandbox, readable: [], network: "all" } as const
+      try {
+        // Denied (the canary unread) only as one of the user's own folders.
+        await expect(
+          checkConfinement({ ...confinement, private: [home] }, join(home, "canary.txt")),
+        ).resolves.toBeUndefined()
+        await expect(
+          checkConfinement({ ...confinement, private: [] }, join(home, "canary.txt")),
+        ).rejects.toThrow(/didn't hold/)
+      } finally {
+        rmSync(home, { recursive: true, force: true })
+      }
+    })
+
+    it("keeps a trial off the network but this machine (no updater fetch)", () => {
+      const profile = seatbeltProfile({
+        sandbox: "/s",
+        readable: [],
+        private: [],
+        network: "loopback",
+      })
+      expect(profile).toContain("(deny network-outbound)")
+      expect(profile).toContain('(allow network-outbound (remote ip "localhost:*"))')
+      expect(
+        seatbeltProfile({ sandbox: "/s", readable: [], private: [], network: "all" }),
+      ).not.toContain("(deny network-outbound)\n")
+    })
+  },
+)
+
+// The project's files/ (decided 2026-10-09): copied into each launch, what its arguments name.
+describe("a desktop app's files", { timeout: 60_000 }, () => {
+  const filesWith = (entries: Record<string, string>) => {
+    const dir = join(mkdtempSync(join(tmpdir(), "kiframe-el-files-")), "files")
+    for (const [path, content] of Object.entries(entries)) {
+      mkdirSync(join(dir, path, ".."), { recursive: true })
+      writeFileSync(join(dir, path), content)
+    }
+    return dir
+  }
+
+  it("opens a copy of the project's files: its edits never reach the project", async () => {
+    const files = filesWith({ "vault/note.md": "the project's note", "vault/sub/deep.md": "deep" })
+    const target = await launch(["touch-arg"], { files, args: ["files/vault"] })
+    const seen = await seenBy(target)
+    const copy = join(target.sandbox, "files", "vault")
+    expect(seen.args).toContain(copy)
+    expect(readFileSync(join(copy, "sub", "deep.md"), "utf8")).toBe("deep")
+    expect(
+      await waitFor(() => readFileSync(join(copy, "note.md"), "utf8") === "edited by the app"),
+    ).toBe(true)
+    expect(readFileSync(join(files, "vault", "note.md"), "utf8")).toBe("the project's note")
+    // The copy is the project's content, never the app's own pages (a page there: off-app).
+    expect(target.allows(pathToFileURL(join(copy, "note.md")).href)).toBe(false)
+    expect(target.allows(pathToFileURL(join(target.sandbox, "profile", "x.html")).href)).toBe(true)
+    // Its temp too (a print preview it writes there is its own page).
+    expect(target.allows(pathToFileURL(join(target.sandbox, "tmp", "preview.html")).href)).toBe(
+      true,
+    )
+  })
+
+  // A files/ slower to copy than the app takes to start, by far (sized here, on this machine:
+  // its tests' timing holds wherever they run). Built once, removed after.
+  describe("slow to copy", { timeout: 300_000 }, () => {
+    let root: string
+    let files: string
+    let mirror: string
+    let copyMs = 0
+    let budget = 0
+    const limit = FILES_LIMITS.files
+    const copyTime = async () => {
+      const to = join(mkdtempSync(join(root, "copy-")), "files")
+      const t0 = Date.now()
+      await copyFiles(files, to)
+      const ms = Date.now() - t0
+      rmSync(dirname(to), { recursive: true, force: true })
+      return ms
+    }
+
+    beforeAll(async () => {
+      // The app's own time to start, measured: it's given twice that and a second.
+      const t0 = Date.now()
+      await (await launch()).close()
+      budget = 2 * (Date.now() - t0) + 1000
+      root = mkdtempSync(join(tmpdir(), "kiframe-el-slow-"))
+      files = join(root, "files")
+      FILES_LIMITS.files = 400_000
+      // Grown until its copy takes well over the app's time (all of it under files/vault).
+      for (let batch = 0; copyMs < budget + 1000 && batch < 60; batch++) {
+        for (let d = 0; d < 50; d++) {
+          const dir = join(files, "vault", `d${batch}-${d}`)
+          mkdirSync(dir, { recursive: true })
+          for (let f = 0; f < 100; f++) writeFileSync(join(dir, `f${f}`), "x")
+        }
+        copyMs = await copyTime()
+      }
+      expect(copyMs).toBeGreaterThan(budget + 1000)
+      // The same folders elsewhere (what a folder swapped for a link would show).
+      mirror = join(root, "mirror")
+      execFileSync("cp", [
+        process.platform === "darwin" ? "-cR" : "-R",
+        join(files, "vault"),
+        mirror,
+      ])
+    }, 300_000)
+
+    afterAll(() => {
+      FILES_LIMITS.files = limit
+      if (root !== undefined) rmSync(root, { recursive: true, force: true })
+    })
+
+    it("gives the app its whole time to start, however long its files take to copy", async () => {
+      // Were the copy counted, the app would have no time left.
+      const target = await launch([], { files, timeoutMs: budget })
+      expect(await target.page.title()).toBe("Fixture notes")
+    })
+
+    it("never starts the app when stopped while its files copy", async () => {
+      const before = sandboxCount()
+      const stopping = new AbortController()
+      const launching = launch([], { files, signal: stopping.signal })
+      setTimeout(() => stopping.abort(), 300)
+      const t0 = Date.now()
+      // The stop itself (never another error), said at once (never once the copy is done).
+      await expect(launching).rejects.toMatchObject({ name: "AbortError" })
+      expect(Date.now() - t0).toBeLessThan(copyMs / 2)
+      expect(sandboxCount()).toBe(before)
+    })
+
+    it("refuses a folder swapped for a link while its files copy", async () => {
+      const vault = join(files, "vault")
+      const launching = launch([], { files })
+      // Mid-copy, vault becomes a link to the same folders elsewhere: every entry still found.
+      setTimeout(() => {
+        renameSync(vault, join(root, "vault-moved"))
+        symlinkSync(mirror, vault)
+      }, 300)
+      try {
+        await expect(launching).rejects.toThrow(/files\/vault.* changed while it was copied/)
+      } finally {
+        rmSync(vault, { force: true })
+        renameSync(join(root, "vault-moved"), vault)
+      }
+    })
+  })
+
+  it("refuses what isn't a file or a folder in files/, and arguments outside it", async () => {
+    const linked = filesWith({ "vault/note.md": "x" })
+    symlinkSync("/etc/hosts", join(linked, "vault", "hosts"))
+    await expect(launch([], { files: linked, args: ["files/vault"] })).rejects.toThrow(
+      /files\/vault\/hosts isn't a file or a folder/,
+    )
+    const files = filesWith({ "vault/note.md": "x" })
+    for (const arg of ["files/../escape", "/etc", "vault", "files", "files/missing"]) {
+      await expect(launch([], { files, args: [arg] }), arg).rejects.toThrow(ElectronLaunchError)
+    }
+    // files/ itself a link (a shared project's, to the user's documents): never followed.
+    const elsewhere = filesWith({ "vault/secret.md": "the user's" })
+    const project = join(mkdtempSync(join(tmpdir(), "kiframe-el-files-")), "files")
+    symlinkSync(elsewhere, project)
+    await expect(launch([], { files: project, args: ["files/vault"] })).rejects.toThrow(
+      /files\/ isn't a folder \(a link\?\)/,
+    )
+    // Folders count toward the limit (a tree of empty ones is as slow to copy and remove).
+    const wide = filesWith({})
+    mkdirSync(wide, { recursive: true })
+    for (let i = 0; i < 6; i++) mkdirSync(join(wide, `d${i}`))
+    const limit = FILES_LIMITS.files
+    FILES_LIMITS.files = 5
+    try {
+      await expect(launch([], { files: wide })).rejects.toThrow(/too large to copy/)
+    } finally {
+      FILES_LIMITS.files = limit
+    }
+    // A project without its files/ folder: said as such (never a raw error).
+    await expect(
+      launch([], { files: join(dirname(files), "absent"), args: ["files/vault"] }),
+    ).rejects.toThrow(/the project has no files\/ folder/)
+    expect(sandboxCount()).toBe(0)
+  })
+})
+
+// The work area: only its own sandboxes swept, never another running Kiframe's, never a link.
+describe("the work area", () => {
+  // A work area with: a launch of another running Kiframe, one whose Kiframe ended, one carrying
+  // this process's id from before (a reboot reuses ids), an unowned one, a link to elsewhere.
+  const workArea = (other: number) => {
+    const own = mkdtempSync(join(tmpdir(), "kiframe-el-work-"))
+    const sandboxes = join(own, "sandboxes")
+    mkdirSync(sandboxes, { recursive: true, mode: 0o700 })
+    const startOf = (pid: number) =>
+      Math.round(
+        Date.parse(
+          execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+            encoding: "utf8",
+            env: { ...process.env, LC_ALL: "C" },
+          }).trim(),
+        ) / 1000,
+      )
+    const at = {
+      live: join(sandboxes, `kiframe-app-${other}-${startOf(other)}-a`),
+      ended: join(sandboxes, `kiframe-app-${spawnSync("true").pid}-${startOf(process.pid)}-b`),
+      reused: join(sandboxes, `kiframe-app-${process.pid}-${startOf(process.pid) - 3600}-c`),
+      unowned: join(sandboxes, "kiframe-app-d"),
+      link: join(sandboxes, "kiframe-app-link"),
+      elsewhere: mkdtempSync(join(tmpdir(), "users-files-")),
+    }
+    for (const dir of [at.live, at.ended, at.reused, at.unowned]) mkdirSync(dir)
+    // Canaries beside their sandboxes, as a crash mid-check leaves them.
+    for (const dir of [at.live, at.ended]) writeFileSync(`${dir}.canary`, "canary")
+    symlinkSync(at.elsewhere, at.link)
+    return { own, at }
+  }
+
+  it("sweeps what no running Kiframe owns, never another's launch, a link or what's elsewhere", async () => {
+    // Another Kiframe running (a dev build): its launch is left alone, in any language.
+    const other = spawn("sleep", ["30"], { stdio: "ignore" })
+    const locale = process.env["LC_ALL"]
+    try {
+      const { own, at } = workArea(other.pid!)
+      process.env["LC_ALL"] = "ko_KR.UTF-8"
+      expect(await sweepWorkArea(own)).toBe(4)
+      expect([at.ended, `${at.ended}.canary`, at.reused, at.unowned].filter(existsSync)).toEqual([])
+      expect(existsSync(at.live) && existsSync(`${at.live}.canary`)).toBe(true)
+      expect(existsSync(at.elsewhere)).toBe(true)
+      expect(lstatSync(at.link).isSymbolicLink()).toBe(true)
+    } finally {
+      if (locale === undefined) delete process.env["LC_ALL"]
+      else process.env["LC_ALL"] = locale
+      other.kill()
+    }
+  })
+
+  it("sweeps nothing when it can't tell who runs (ps unreadable)", async () => {
+    const other = spawn("sleep", ["30"], { stdio: "ignore" })
+    const path = process.env["PATH"]
     try {
-      const sweeping = sweepElectronOrphans(stateFile)
-      // A run starts during the sweep: its launch is noted.
-      writeFileSync(stateFile, JSON.stringify([left, meanwhile]))
-      expect(await sweeping).toBe(1)
-      expect(JSON.parse(readFileSync(stateFile, "utf8"))).toEqual([meanwhile])
-      expect(existsSync(meanwhile)).toBe(true)
+      const { own, at } = workArea(other.pid!)
+      process.env["PATH"] = mkdtempSync(join(tmpdir(), "kiframe-el-nops-"))
+      expect(await sweepWorkArea(own)).toBe(0)
+      expect([at.live, at.ended, at.reused].every(existsSync)).toBe(true)
     } finally {
-      rmSync(left, { recursive: true, force: true })
-      rmSync(meanwhile, { recursive: true, force: true })
+      process.env["PATH"] = path
+      other.kill()
     }
   })
 
-  it("never sweeps a folder that isn't a sandbox (named like one, or anywhere else)", async () => {
-    const dir = mkdtempSync(join(tmpdir(), "kiframe-el-state-"))
-    const keep = mkdtempSync(join(tmpdir(), "users-files-"))
-    // Named like a sandbox, but not one this module made (not directly in the temp folder).
-    const lookalike = mkdtempSync(join(dir, "kiframe-app-"))
-    const stateFile = join(dir, "launches.json")
-    writeFileSync(stateFile, JSON.stringify([keep, lookalike, `${lookalike}/../..`]))
-    expect(await sweepElectronOrphans(stateFile)).toBe(0)
-    expect(existsSync(keep)).toBe(true)
-    expect(existsSync(lookalike)).toBe(true)
+  it("is the user's alone (0700), never a link", () => {
+    const own = mkdtempSync(join(tmpdir(), "kiframe-el-work-"))
+    chmodSync(own, 0o755)
+    sandboxesOf(own)
+    expect(statSync(own).mode & 0o777).toBe(0o700)
+    expect(statSync(join(own, "sandboxes")).mode & 0o777).toBe(0o700)
+    const linked = join(mkdtempSync(join(tmpdir(), "kiframe-el-link-")), "work")
+    symlinkSync(own, linked)
+    expect(() => sandboxesOf(linked)).toThrow(/isn't a folder/)
   })
 })
diff --git a/packages/runtime/test/fixtures/crash-launch.ts b/packages/runtime/test/fixtures/crash-launch.ts
new file mode 100644
index 0000000..46cd301
--- /dev/null
+++ b/packages/runtime/test/fixtures/crash-launch.ts
@@ -0,0 +1,22 @@
+// A Kiframe that launches a desktop app and is then killed (the test's crash): it prints the
+// launch's sandbox and waits. Args: <workDir> <executable> <bundle> <readable> <fixture app>.
+import { launchElectron } from "../../src/electron.ts"
+
+const [workDir, executable, bundle, readable, app] = process.argv.slice(2) as [
+  string,
+  string,
+  string,
+  string,
+  string,
+]
+const target = await launchElectron({
+  executable,
+  bundle,
+  readable: [readable],
+  workDir,
+  allowUnconfined: true,
+  appArgs: [app, "hidden"],
+  viewport: { width: 800, height: 600, deviceScaleFactor: 1 },
+})
+process.stdout.write(`${target.sandbox}\n`)
+setInterval(() => undefined, 60_000)
diff --git a/packages/runtime/test/fixtures/electron-app/main.cjs b/packages/runtime/test/fixtures/electron-app/main.cjs
index 3985634..ce4eea1 100644
--- a/packages/runtime/test/fixtures/electron-app/main.cjs
+++ b/packages/runtime/test/fixtures/electron-app/main.cjs
@@ -89,3 +89,63 @@ if (process.argv.includes("quit-at-once")) {
   })
   app.on("window-all-closed", () => app.quit())
 }
+
+// "touch-arg": it edits what it was given to open (the files/ copy: never the project's own).
+const opened = process.argv.find((a) => a.includes("/files/"))
+if (process.argv.includes("touch-arg") && opened !== undefined) {
+  app.whenReady().then(() => writeFileSync(join(opened, "note.md"), "edited by the app"))
+}
+
+// "probes": each escape the confinement must refuse, tried and written down (never the user's
+// data: a write would only create a probe file the test removes; reads only list folders).
+if (process.argv.includes("probes")) {
+  app.whenReady().then(async () => {
+    const fs = require("node:fs")
+    const net = require("node:net")
+    const { execFileSync } = require("node:child_process")
+    const real = require("node:os").userInfo().homedir
+    const outside = process.argv.find((a) => a.startsWith("outside="))?.slice(8) ?? "/nonexistent"
+    const out = {}
+    const tryIt = (name, fn) => {
+      try {
+        out[name] = "OK " + String(fn()).slice(0, 40)
+      } catch (e) {
+        out[name] = "DENIED " + (e.code ?? String(e).slice(0, 40))
+      }
+    }
+    tryIt("write-real-home", () => fs.writeFileSync(join(real, "Library", "KiframeProbe.txt"), "x"))
+    tryIt("read-real-home", () => fs.readdirSync(join(real, "Library")).length)
+    tryIt("write-users-shared", () => fs.writeFileSync("/Users/Shared/KiframeProbe.txt", "x"))
+    tryIt("write-private-tmp", () => fs.writeFileSync("/private/tmp/KiframeProbe.txt", "x"))
+    tryIt("write-applications", () => fs.writeFileSync("/Applications/KiframeProbe.txt", "x"))
+    tryIt("read-outside", () => fs.readFileSync(outside, "utf8"))
+    tryIt("hardlink-outside", () => fs.linkSync(outside, join(app.getPath("userData"), "linked")))
+    tryIt("exec-open", () =>
+      execFileSync("/usr/bin/open", ["-h"], { stdio: "ignore", timeout: 3000 }),
+    )
+    tryIt("exec-osascript", () =>
+      execFileSync("/usr/bin/osascript", ["-e", "1"], { timeout: 3000 }),
+    )
+    tryIt("exec-launchctl", () => execFileSync("/bin/launchctl", ["version"], { timeout: 3000 }))
+    // A unix socket that would accept (the test's own server, outside the sandbox): an agent's.
+    const socket = process.argv.find((a) => a.startsWith("socket="))?.slice(7) ?? "/nonexistent"
+    out["socket-agent"] = await new Promise((resolve) => {
+      const s = net.connect(socket)
+      s.on("connect", () => (s.destroy(), resolve("OK connected")))
+      s.on("error", (e) => resolve("DENIED " + e.code))
+    })
+    // A program copied into its own sandbox, run from there (a copied launcher: an exact-path rule
+    // would miss it). `true`: it runs, or it's refused.
+    tryIt("exec-copied", () => {
+      const copy = join(app.getPath("userData"), "copied")
+      fs.copyFileSync("/usr/bin/true", copy)
+      fs.chmodSync(copy, 0o755)
+      return execFileSync(copy, [], { stdio: "ignore", timeout: 3000 })
+    })
+    // The user's clipboard (it may hold a password just copied): only how much is seen, never what.
+    const { safeStorage, clipboard } = require("electron")
+    out["clipboard-read"] = `${(await clipboard.readText()).length}`
+    tryIt("keychain-encrypts", () => safeStorage.isEncryptionAvailable())
+    fs.writeFileSync(join(app.getPath("userData"), "probes.json"), JSON.stringify(out))
+  })
+}
diff --git a/packages/schema/src/apps.test.ts b/packages/schema/src/apps.test.ts
index 60e30ab..bb9d056 100644
--- a/packages/schema/src/apps.test.ts
+++ b/packages/schema/src/apps.test.ts
@@ -274,13 +274,13 @@ describe("a desktop Electron app (design 2026-10-08)", () => {
   const parse = (apps: object) => Project.safeParse(v2(apps))
 
   it("is named by its bundle id, beside web apps (the viewport defaulted)", () => {
-    const parsed = parse({ web: app("https://a.dev"), notes: desk({ args: ["~/Demo"] }) })
+    const parsed = parse({ web: app("https://a.dev"), notes: desk({ args: ["files/demo"] }) })
     expect(parsed.success).toBe(true)
     const notes = parsed.data?.apps.notes
     expect(notes).toEqual({
       kind: "electron",
       bundleId: "com.example.notes",
-      args: ["~/Demo"],
+      args: ["files/demo"],
       viewport: { width: 1440, height: 900, deviceScaleFactor: 2 },
     })
     expect(appIdentity(notes!)).toBe("electron:com.example.notes")
@@ -311,7 +311,20 @@ describe("a desktop Electron app (design 2026-10-08)", () => {
         /positional arguments only/,
       )
     }
-    expect(issue({ x: desk({ args: ["~/My Demo"] }) })).toBe("parsed")
+    expect(issue({ x: desk({ args: ["files/My Demo"] }) })).toBe("parsed")
+    // Only the project's files/ (never the user's own folders, never out of it).
+    for (const outside of [
+      "~/Demo",
+      "/Users/me/Demo",
+      "files",
+      "files/../x",
+      "files//x",
+      "./files/x",
+    ]) {
+      expect(issue({ x: desk({ args: [outside] }) }), outside).toMatch(
+        /a path in the project's files/,
+      )
+    }
     expect(issue({ x: desk({ bundleId: "1.0" }) })).toMatch(/a bundle id/)
   })
 
diff --git a/packages/schema/src/project.ts b/packages/schema/src/project.ts
index 5294e03..f57e0dd 100644
--- a/packages/schema/src/project.ts
+++ b/packages/schema/src/project.ts
@@ -41,6 +41,17 @@ const HttpsOrigin = z
     return url !== null && url.protocol === "https:" && url.origin === s
   }, "an https origin (https://host, no path)")
 
+/**
+ * A desktop app's argument as a path in the project's files/ (`files/a/b` → ["a", "b"]); undefined
+ * for anything else (files/ itself, an empty, "." or ".." part: never outside it).
+ */
+export function filesPath(arg: string): string[] | undefined {
+  const parts = arg.split("/")
+  if (parts[0] !== "files" || parts.length < 2) return undefined
+  if (parts.some((p) => p === "" || p === "." || p === "..")) return undefined
+  return parts.slice(1)
+}
+
 /**
  * A desktop Electron app (OBJECT-MODEL §0.9, design 2026-10-08), named by its bundle id: never a
  * path or a program (a project may come from someone else: the app a bundle id means is found and
@@ -53,7 +64,10 @@ export const ElectronApp = z.strictObject({
     .string()
     .max(255)
     .regex(/^[A-Za-z][A-Za-z0-9-]*(\.[A-Za-z0-9-]+)+$/, "a bundle id (com.example.app)"),
-  /** What the app opens (a folder, a file): positional only, never a switch. */
+  /**
+   * What the app opens: paths in the project's files/ (`files/demo-vault`; a copy is what it gets,
+   * decided 2026-10-09), positional only, never a switch.
+   */
   args: z
     .array(
       z
@@ -68,6 +82,10 @@ export const ElectronApp = z.strictObject({
             !/^\s|\s$/.test(a) &&
             ![...a].some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127),
           "positional arguments only (no switches, no spaces at the ends)",
+        )
+        .refine(
+          (a) => filesPath(a) !== undefined,
+          "a path in the project's files/ (files/<name>): a desktop app opens only those",
         ),
     )
     .max(20)

From 98e3e9d5ec52b87b0a60235ed6f4d6bf90720de4 Mon Sep 17 00:00:00 2001
From: Quang Lee <winlp4ever@gmail.com>
Date: Fri, 9 Oct 2026 23:33:38 +0200
Subject: [PATCH 05/10] feat(runtime): inspect and try a desktop app before
 it's added (#59)

* feat(runtime): inspect and try a desktop app before it's added

- inspectDesktopApp: static checks of a picked .app (where it is, Info.plist
  via plutil, Electron's framework, its executable, App Sandbox, codesign);
  its signer kept: a developer's team, or a digest pinning an unsigned build
- trialDesktopApp: a confined launch without the network beyond this
  machine; read as ok, a wrapper's site (named even unreached), a quit
- apps allowing one copy (Slack, VS Code, Discord) launch confined: their
  lock's socket goes to the sandbox's temp (MAC_CHROMIUM_TMPDIR)
- launch errors say why structurally; the tests' launch hooks leave the
  package's launch options
- a macOS CI job runs the desktop-app suite

* fix(runtime): steady a desktop app's inspection and trial

- a pinned build's digest covers the whole bundle (helpers, frameworks)
- codesign that fails or times out refuses the app, never read as
  unsigned or unsandboxed; empty names fall back
- a trial runs with the network (an updater can't touch the real app):
  a wrapper's offline page no longer hides its site
- a main window that never loaded its own page is refused at launch, said
  as such (a dev server not running included); a hung attach is retried
- one command helper; the macOS CI job installs ffmpeg

* fix(runtime): close a pinned build's links and say a stalled attach

- a pinned build's digest covers the whole bundle and refuses a link that
  leads outside it; unreadable, too large or stopped: refused, said
- an attach that never answers is tried again, then said as the launch's
  own error (runs and trials alike); a trial throws Kiframe's own faults
- an error page whose address can't be read is said as an unloaded page
- the docs say what a trial reaches (the network, as a run)

* refactor(runtime): one launch failure rule and an unforgeable build digest

Redesign after three review rounds on the same two seams (reviewed):
- every failure ending a launch is an ElectronLaunchError with its why,
  by one rule (stop, not started, quit first, said, anything else in a
  fixed phrase, its detail on stderr only when asked); the trial maps
  only its why
- the pinned digest: the path resolved, each entry a JSON line under a
  version, links resolved inside the bundle step by step (a chain leaving
  it refused, one leading nowhere kept), sizes checked, sockets and
  devices refused, a stop honoured per chunk
- the unused loopback network mode and a duplicate branch removed

* fix(runtime): keep a launch's said reason and hold a trial to the picked build

- what a launch already said (a site, a page never loaded) stays said if
  the app then quits; the attach hands its timeout to the one rule
- a pinned build is held by its digest (signatureHolds compares it); a
  trial runs only the build that was picked
- an inspection stops when asked (codesign and plutil killed)
- bundle ids with underscores accepted (schema and inspection)
- one quoting helper; the digest's link steps no longer block

* fix(runtime): say a quit over a generic failure and an unread build as such

- only what the app showed (a site, a page never loaded) beats a quit
- a build that can't be checked (codesign timed out, unreadable) is said
  as unread, never as changed; buildHolds says which
- the stop honoured in the middle of one large file
- one bundle id rule, shared with the schema; one quoting helper, named
  for the two languages it serves

* fix(runtime): keep a frame still loading as a desktop app opens

What the main window embeds as it opens is read by a loading frame's src
too: its first navigation uncommitted when the launch seals what's the
app's own, it was stopped once it loaded (the macOS runner's flake). The
single-instance test runs where its fix applies (macOS).

* fix(runtime): never stop a desktop app's own devtools opened mid-run

A dev build that opens DevTools after Kiframe attached showed them in a
window that appears blank first (never filtered as DevTools), and the
guard stopped it, failing the step (the macOS runner's failure, then
reproduced every time with DevTools opened late). The guard leaves
devtools: pages alone, as the window list and emulation already did.

* test(runtime): read the app under its devtools, never click it on the runner

On the macOS runner a click under DevTools opened mid-run waits for stability until its timeout (a covered window's animation frames throttled); the test's property is DevTools never counted as leaving the app. Clicking with DevTools open is checked on a real app (BACKLOG, PR 5).

* fix(runtime): stop a desktop app's off-site frame at launch, blank a failed back

- a frame still loading toward what isn't the app's when the launch seals
  is stopped then (never landing as a stop in a run's first step)
- a main window whose back failed is blanked (never left showing the site;
  the run says to relaunch, as with no history), the failure's detail logged
- CI logs desktop-app failures' detail (KIFRAME_ELECTRON_DEBUG)
---
 .github/workflows/ci.yml                      |  22 +-
 docs/BACKLOG.md                               |   2 +-
 docs/OBJECT-MODEL.md                          |   3 +-
 packages/runtime/src/electron-confine.ts      |  18 +-
 packages/runtime/src/electron-inspect.ts      | 335 +++++++++++++++
 packages/runtime/src/electron-trial.ts        |  58 +++
 packages/runtime/src/electron-workarea.ts     |  31 +-
 packages/runtime/src/electron.ts              | 236 +++++++++--
 packages/runtime/src/index.ts                 |  10 +
 .../runtime/test/electron-inspect.test.ts     | 397 ++++++++++++++++++
 packages/runtime/test/electron.test.ts        | 267 ++++++++++--
 .../runtime/test/fixtures/crash-launch.ts     |  20 +-
 .../test/fixtures/electron-app/main.cjs       |  24 +-
 packages/schema/src/apps.test.ts              |   2 +
 packages/schema/src/project.ts                |   8 +-
 vitest.config.ts                              |   2 +-
 16 files changed, 1324 insertions(+), 111 deletions(-)
 create mode 100644 packages/runtime/src/electron-inspect.ts
 create mode 100644 packages/runtime/src/electron-trial.ts
 create mode 100644 packages/runtime/test/electron-inspect.test.ts

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e72c221..1a22e25 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -37,8 +37,10 @@ jobs:
       - run: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
       - run: xvfb-run -a pnpm test:coverage
         env:
-          # Slow shutdown phases of a desktop app's launch, said (the Electron target's evidence).
+          # Slow shutdown phases of a desktop app's launch, and its failures' detail, said (the
+          # Electron target's evidence).
           KIFRAME_ELECTRON_TIMING: "1"
+          KIFRAME_ELECTRON_DEBUG: "1"
       # The desktop app, built and launched under a virtual display.
       - name: Desktop end-to-end
         run: xvfb-run -a pnpm --filter @kiframe/desktop e2e
@@ -49,3 +51,21 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./coverage/lcov.info
           fail_ci_if_error: false
+
+  # Desktop apps run on macOS only (Seatbelt, codesign, plutil): their suite, where it holds.
+  electron-macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      # A desktop app's takes are encoded with ffmpeg (as on Linux).
+      - run: brew install ffmpeg
+      - run: pnpm exec vitest run --project electron
+        env:
+          KIFRAME_ELECTRON_TIMING: "1"
+          KIFRAME_ELECTRON_DEBUG: "1"
diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md
index b1611b1..50ff9f0 100644
--- a/docs/BACKLOG.md
+++ b/docs/BACKLOG.md
@@ -246,7 +246,7 @@ Non-severe review findings deferred on purpose (see the review-round rule: only
 - **Copy and paste in a desktop app's demo:** the confinement denies the pasteboard (the user's clipboard may hold a password), so an app's own copy and paste does nothing in a run. A demo that needs it: a run-only pasteboard (a private named pasteboard can't be forced on an app) or typing the pasted text.
 - **What a confined app opens through LaunchServices:** an app can't start without `launchservicesd`, and through it it can open a file or a URL that then runs unconfined (a script it wrote, the user's browser). Stated in §0.9 (accident, not a hostile app); an Endpoint Security watcher or a per-run user account would close it.
 - **Desktop-app sweeps read processes more than once:** the startup sweep runs one `ps` per leftover sandbox (one `ps -axo pid=,lstart=` table would answer every owner), and a run's close reads the process table twice (`orphanedGroup` and `sweepProcesses`). Startup and close time only (#58 review).
-- **Test hooks on the launch API (PR 4):** `appArgs`, `readable` and `allowUnconfined` are fields of `ElectronLaunch`, and `appArgs` skips the files/-only rule. Move them out of the public options when the desktop app first calls `launchElectron` (#58 review, agreed 2026-10-09).
+- **Clicks in a desktop app under its own DevTools (macOS runner):** with DevTools opened mid-run over a hidden test window, a click waited for the button to be stable until its timeout on GitHub's macOS runner (animation frames throttled: the window covered); locally it clicks. The DevTools test reads instead of clicking; check clicks with DevTools open on a real app in PR 5.
 - **One launch helper:** browsers are launched by each entry point; nothing enforces an off-the-record context. A runtime-owned `launchBrowser()` / context factory would make it hard to bypass (the desktop app's main process).
 - **Secrets into contenteditable:** v0 writes secrets to inputs and textareas only (the value set on the approved element); a rich-text field is refused.
 - **Network exfiltration by the page itself:** a hostile page receives the typed password in its own field and can send it anywhere; that's the target app's own data. Out of scope for the vault (it only guarantees the value goes to the bound field on the allowed origins).
diff --git a/docs/OBJECT-MODEL.md b/docs/OBJECT-MODEL.md
index 453dd36..08b6b0e 100644
--- a/docs/OBJECT-MODEL.md
+++ b/docs/OBJECT-MODEL.md
@@ -229,7 +229,8 @@ One scene, three phases. The agent's own instructions say the same (`packages/st
 - **Each run launches it sandboxed** (its own HOME, `CFFIXED_USER_HOME`, XDG and temp folders, `--user-data-dir`; an allowlisted environment, never Kiframe's), attached with `--remote-debugging-port=0` + `connectOverCDP`; the viewport is emulated (a spike measured frames and clicks with the window covered, off-screen, minimized or hidden: a run never needs the user's screen; the window itself can't be moved over CDP). Isolation is enforced, never checked after the fact: every launch is confined (below). Its process group killed after each run, leftovers swept.
 - **Confinement: a guard, sealed at launch (PR 2, redesigned after three review rounds, design reviewed).** Once the app settles (its windows unchanged 1.5 s), its main window is the last opened still open; its own scheme or dev server is learned from that window alone, then sealed (nothing a run does adds to it). A main window that isn't the app's own (a wrapper's unlisted site) refuses the launch ("list it in its origins"). From then a **guard** checks every navigation of every frame of every window as it happens: a page that isn't the app's own is stopped at once (a popup closed, any other frame blanked: never left for a read or a frame) and recorded; the step fails `off-app`. The app's own: a local `file:` in its bundle or sandbox (decoded, normalized), its sealed scheme or dev server, a listed https site (`sameApp`, never plain http), a blob of those. Stated (as a web run): the guard acts as a page commits, so a page that isn't the app's own has loaded (its scripts ran, with the app's own rights) before it's stopped: following a link the app offers is what its user does too (blocking before the load needs request interception, which never sees `file:`); and the runner's own navigation events name it as they do for web runs (origin and path, known secret values scrubbed). What the main window embeds as it opens (a frame of another site) is the app as shipped: its origin is the app's own. A main window stopped goes back to the app's page (no goto there to bring it back); a failed load is said as one. **One app per run:** a desktop app's run never shows a site (no goto, URL condition or web preset; a web interrupt rule's goto skipped, said), is confined while grounding too, and keeps no sign-in between runs yet.
 - **Windows (PR 2, known limits, to settle on real apps in PR 3 and PR 5: decided by the user 2026-10-08):** the main window is the last opened still open once the app's windows were unchanged for 1.5 s (a splash that stays up longer is taken for the main window); windows the app's main process opens are followed as popups are (a hidden helper window opened during a step may be followed: CDP can't tell it's hidden); only the launch window is sent back when it goes off-app (another window is closed); a stop that lands after its step ended counts against the next step. A window that opens blank gets a moment to load (as a web page does); a frame of a window the run isn't driving is said, never the step's failure.
-- **Every launch confined (PR 3a, 2026-10-09, design reviewed twice, measured):** on macOS each launch runs under Seatbelt (`sandbox-exec`, `electron-confine.ts`): writes only into its own sandbox; no reads of /Users, /Volumes, the temp folders, the user's home and the work area wherever they are (a home outside /Users) but its sandbox and its bundle; nothing run from its sandbox (the one place it writes: a program it drops there, a copied launcher), no `open`, `osascript`, `launchctl` nor Apple Events; no unix sockets (an agent's: ssh, Docker) but mDNSResponder; no preferences (cfprefsd), keychain (SecurityServer: a mock keychain instead, `--use-mock-keychain`) nor clipboard (the user's may hold a password just copied: an app's own copy and paste doesn't work in a run); network for runs (the app's backend), loopback only for a trial (no updater). Chromium's own sandbox can't nest in it (`--no-sandbox`): the guard and this profile replace it. A canary before every launch, before the files are copied (a read the profile refuses must fail, one of its sandbox succeed: a confinement that runs nothing never passes); no `sandbox-exec`, or a canary failed: no launch (never unconfined). Off macOS: desktop apps don't launch (CI's tests only, unconfined). Measured with a probe app: every escape above `EPERM` (a hard link or a symlink to an outside file too), the app driven as usual. This replaces the trial's after-the-fact isolation check, rejected by review (an app that leaks does its harm as it starts). **What it doesn't stop (stated):** an app can still ask macOS to open a file or a URL (LaunchServices: no app starts without reaching it, measured), and what opens runs outside the confinement; it reaches services on this machine (localhost: a dev build's own server needs it). The app's own pages are its bundle and what it writes in its sandbox's home, profile and temp folders (a page it builds there from remote content counts as its own, as its cache already does); never the files/ copy. The confinement keeps an app from the user's data by accident (the minmux incident), not an app built to escape (one the user runs unconfined every day anyway).
+- **Every launch confined (PR 3a, 2026-10-09, design reviewed twice, measured):** on macOS each launch runs under Seatbelt (`sandbox-exec`, `electron-confine.ts`): writes only into its own sandbox; no reads of /Users, /Volumes, the temp folders, the user's home and the work area wherever they are (a home outside /Users) but its sandbox and its bundle; nothing run from its sandbox (the one place it writes: a program it drops there, a copied launcher), no `open`, `osascript`, `launchctl` nor Apple Events; no unix sockets (an agent's: ssh, Docker) but mDNSResponder; no preferences (cfprefsd), keychain (SecurityServer: a mock keychain instead, `--use-mock-keychain`) nor clipboard (the user's may hold a password just copied: an app's own copy and paste doesn't work in a run); the network on, for runs and trials alike (the app's backend, a wrapper's site: an updater can't touch the real app, nothing outside the sandbox being written; what an app could send is only what it can read here: its bundle, the system's files, its own sandbox). Chromium's own sandbox can't nest in it (`--no-sandbox`): the guard and this profile replace it. A canary before every launch, before the files are copied (a read the profile refuses must fail, one of its sandbox succeed: a confinement that runs nothing never passes); no `sandbox-exec`, or a canary failed: no launch (never unconfined). Off macOS: desktop apps don't launch (CI's tests only, unconfined). Measured with a probe app: every escape above `EPERM` (a hard link or a symlink to an outside file too), the app driven as usual. This replaces the trial's after-the-fact isolation check, rejected by review (an app that leaks does its harm as it starts). **What it doesn't stop (stated):** an app can still ask macOS to open a file or a URL (LaunchServices: no app starts without reaching it, measured), and what opens runs outside the confinement; it reaches services on this machine (localhost: a dev build's own server needs it). The app's own pages are its bundle and what it writes in its sandbox's home, profile and temp folders (a page it builds there from remote content counts as its own, as its cache already does); never the files/ copy. The confinement keeps an app from the user's data by accident (the minmux incident), not an app built to escape (one the user runs unconfined every day anyway).
+- **Adding a desktop app (PR 3b, design reviewed 2026-10-09):** inspected first, statically (`electron-inspect.ts`: only `plutil` and `codesign` run): refused outside where an app can stay (a disk image, a temporary translocated copy, the Trash, inside another app), not Electron (its framework; no version gate: Figma reports 13.6.1), an executable that isn't its own file, a Mac App Store build (App Sandbox), a developer signature that doesn't hold (`codesign --verify --strict` against its team and signed identifier). Kept: its id, name, Electron's version, and its signer: a developer (team id) or, ad hoc and unsigned (the user's own builds), pinned to a digest of the whole bundle (a link leading outside it refused; at most 4 GB and 200,000 entries). Then **tried confined** (`electron-trial.ts`): launched with the network as in a run (an updater can't touch the real app: nothing outside the sandbox is written; a wrapper's offline page can't hide its site), its main window attached, closed; a wrapper's site is named (even unreached: the error page's unreachable URL, over CDP) and allowed by the user in a second trial. A main window that never loaded its own page (offline, a dev server not running) is refused at launch, said as such: never a window driven on Chromium's error page. An attach that hangs as the first page fails (measured 1 in 5; cause not found) is tried again within the launch's time (stated). A trial runs only the build that was picked (its developer's signature, or its pinned digest, checked first; a change between that check and the launch is the user's own build tool's: holding every launch to its approval is PR 4's, with runs). codesign that fails or times out refuses the app (never read as unsigned or unsandboxed). Apps that allow one copy (Slack, VS Code, Discord) need Chromium's temp folder in the sandbox (`MAC_CHROMIUM_TMPDIR`): its lock's socket otherwise goes to the user's /var/folders, denied, and the app quits.
 - **The work area `~/.kiframe/`** (decided by the user 2026-10-09: deletable any time): `sandboxes/` (one per launch, 0700, never a link), each named after the Kiframe that made it (`kiframe-app-<pid>-<start>-…`: owned from the moment it exists, no shared state file to race on); a crash sweep at start removes only sandboxes no running Kiframe owns (the processes pointing at them killed first), never another build's launch, and nothing when `ps` can't be read. Kept out of Time Machine and Spotlight. Approvals stay in the app's settings, takes in app data.
 - **A project's `files/`** (decided by the user 2026-10-09): what a desktop app opens. Copied into the sandbox at each launch by Kiframe's own walk (folders and regular files only: a link, a FIFO, a device refused; 500 MB, 20,000 files, depth 32; cloned where the disk can, times kept); `args` name paths in it only (`files/vault`, given as the copy's path); the app's edits stay in the copy (thrown away: every run from the same files). The copy is the project's content, never the app's own pages for the guard. Filled by the user in v0: the agent's file tools never reach `files/` (it may hold what runs inside the app: an editor's tasks, a vault's plugins).
 - **Measured on a fixture app (PR 2, 2026-10-08):** HOME, XDG and `--user-data-dir` hold; macOS's own places don't move: Electron's `appData` (`~/Library/Application Support`) and the app's preferences (`NSUserDefaults`, written by `cfprefsd` into the user's real `~/Library/Preferences/<bundle id>.plist`) stay the user's whatever `HOME` or `CFFIXED_USER_HOME` say. Hence the confinement (PR 3a, below): the preferences daemon is denied and writes outside the sandbox refused, so neither can be reached (a check after launch, the earlier plan, came too late).
diff --git a/packages/runtime/src/electron-confine.ts b/packages/runtime/src/electron-confine.ts
index c0e0efd..7b529f8 100644
--- a/packages/runtime/src/electron-confine.ts
+++ b/packages/runtime/src/electron-confine.ts
@@ -28,28 +28,28 @@ export interface Confinement {
    * they are (a home outside /Users on a managed Mac).
    */
   private: readonly string[]
-  /** "all": the app's backend reachable (a run); "loopback": nothing beyond this machine (a trial). */
-  network: "all" | "loopback"
 }
 
-/** A string in the profile's language (quoted, its backslashes and quotes escaped). */
-const q = (s: string) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
+/**
+ * A double-quoted string, its backslashes and quotes escaped: what Seatbelt's profile language and
+ * codesign's requirement language both read (a change here must hold for both).
+ */
+export const quoted = (s: string) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
 
 /** The Seatbelt profile of a launch. Later rules win over earlier ones. */
 export function seatbeltProfile(c: Confinement): string {
-  const readable = [c.sandbox, ...c.readable].map((p) => `(subpath ${q(p)})`).join(" ")
+  const readable = [c.sandbox, ...c.readable].map((p) => `(subpath ${quoted(p)})`).join(" ")
   return `(version 1)
 (allow default)
 (deny file-write*)
-(allow file-write* (subpath ${q(c.sandbox)}) (literal "/dev/null") (literal "/dev/zero") (literal "/dev/dtracehelper") (regex #"^/dev/tty") (regex #"^/dev/fd/"))
-(deny file-read-data (subpath "/Users") (subpath "/Volumes") (subpath "/private/var/folders") (subpath "/private/tmp") (subpath "/var/folders") (subpath "/tmp")${c.private.map((p) => ` (subpath ${q(p)})`).join("")})
+(allow file-write* (subpath ${quoted(c.sandbox)}) (literal "/dev/null") (literal "/dev/zero") (literal "/dev/dtracehelper") (regex #"^/dev/tty") (regex #"^/dev/fd/"))
+(deny file-read-data (subpath "/Users") (subpath "/Volumes") (subpath "/private/var/folders") (subpath "/private/tmp") (subpath "/var/folders") (subpath "/tmp")${c.private.map((p) => ` (subpath ${quoted(p)})`).join("")})
 (allow file-read-data ${readable})
 (deny network-outbound (remote unix-socket))
 (allow network-outbound (remote unix-socket (path-literal "/private/var/run/mDNSResponder")))
 (deny appleevent-send)
-(deny process-exec* (subpath ${q(c.sandbox)}) (literal "/usr/bin/open") (literal "/usr/bin/osascript") (literal "/bin/launchctl"))
+(deny process-exec* (subpath ${quoted(c.sandbox)}) (literal "/usr/bin/open") (literal "/usr/bin/osascript") (literal "/bin/launchctl"))
 (deny mach-lookup (global-name "com.apple.cfprefsd.agent") (global-name "com.apple.SecurityServer") (global-name "com.apple.pasteboard.1"))
-${c.network === "loopback" ? '(deny network-outbound)\n(allow network-outbound (remote ip "localhost:*"))\n(allow network-outbound (remote unix-socket (path-literal "/private/var/run/mDNSResponder")))' : ""}
 `
 }
 
diff --git a/packages/runtime/src/electron-inspect.ts b/packages/runtime/src/electron-inspect.ts
new file mode 100644
index 0000000..082c369
--- /dev/null
+++ b/packages/runtime/src/electron-inspect.ts
@@ -0,0 +1,335 @@
+import { createHash } from "node:crypto"
+import { constants, createReadStream } from "node:fs"
+import { access, lstat, readdir, readlink, realpath } from "node:fs/promises"
+import { basename, isAbsolute, join } from "node:path"
+import { BUNDLE_ID } from "@kiframe/schema"
+import { quoted } from "./electron-confine.ts"
+import { command as run } from "./electron-workarea.ts"
+
+// A desktop app the user picks, inspected before Kiframe ever runs it (PR 3b, design reviewed
+// 2026-10-09): only plutil and codesign run, nothing of the app. What's refused is said as is;
+// what's kept is what an approval pins (its developer, or the exact build of an unsigned one).
+
+/**
+ * Who stands behind the app: a developer (Apple team id; `identifier` the signing identifier, kept
+ * for the signature check) or no one (ad hoc or unsigned: pinned to a digest of its code).
+ */
+export type Signer =
+  { kind: "team"; team: string; identifier: string } | { kind: "pinned"; digest: string }
+
+export interface DesktopApp {
+  /** The bundle's real path. */
+  path: string
+  bundleId: string
+  /** Its name as shown (Finder's). */
+  name: string
+  version: string | undefined
+  /** Electron's version in it (shown, never a condition: the confined trial decides). */
+  electron: string
+  /** The executable's real path, inside the bundle. */
+  executable: string
+  signer: Signer
+}
+
+/** An app Kiframe won't add: said to the user as is. */
+export class InspectError extends Error {}
+
+/** codesign on a large bundle (a verify reads it all) can take a while: never forever. */
+const TIMEOUT = 60_000
+
+/** Why an app can't be used from where it is (its real path), or undefined. */
+export function placeRefusal(real: string): string | undefined {
+  if (!real.endsWith(".app")) return "that isn't an app (a .app)"
+  if (real.slice(0, -4).includes(".app/"))
+    return "that app is inside another app: pick the app itself"
+  if (real.startsWith("/Volumes/")) {
+    return "that app is on a disk image or another disk: copy it to Applications first"
+  }
+  if (real.includes("/AppTranslocation/")) {
+    return "macOS runs that app from a temporary copy: move it to Applications, open it once, then add it"
+  }
+  if (real.includes("/.Trash/")) return "that app is in the Trash"
+  return undefined
+}
+
+/** A value of an Info.plist (undefined when it has none), read by plutil. */
+async function plistValue(
+  plist: string,
+  key: string,
+  signal?: AbortSignal,
+): Promise<string | undefined> {
+  const out = await run(
+    "/usr/bin/plutil",
+    ["-extract", key, "raw", "-o", "-", plist],
+    TIMEOUT,
+    signal,
+  )
+  signal?.throwIfAborted()
+  // An empty value is no value (a build with an empty name: its fallback instead).
+  const value = out.code === 0 ? out.stdout.trim() : ""
+  return value === "" ? undefined : value
+}
+
+/**
+ * What `codesign -dv` says of a signature: unsigned (it says so), ad hoc, a developer's, or unread
+ * (it failed otherwise, timed out: never taken for "unsigned").
+ */
+export function parseSigning(
+  code: number,
+  stderr: string,
+):
+  | { kind: "unsigned" }
+  | { kind: "adhoc" }
+  | { kind: "team"; team: string; identifier: string }
+  | { kind: "unread" } {
+  if (code !== 0)
+    return /not signed at all/.test(stderr) ? { kind: "unsigned" } : { kind: "unread" }
+  const field = (name: string) => new RegExp(`^${name}=(.*)$`, "m").exec(stderr)?.[1]?.trim()
+  const team = field("TeamIdentifier")
+  const identifier = field("Identifier")
+  if (field("Signature") === "adhoc" || team === undefined || team === "not set") {
+    return { kind: "adhoc" }
+  }
+  return { kind: "team", team, identifier: identifier ?? "" }
+}
+
+/** The requirement a developer's signature must meet: their team, the signed identifier. */
+export function teamRequirement(team: string, identifier: string): string {
+  return `anchor apple generic and identifier ${quoted(identifier)} and certificate leaf[subject.OU] = ${quoted(team)}`
+}
+
+/**
+ * Whether the app at `path` is still the one approved: a developer's, its signature whole and
+ * theirs (`codesign --verify --strict`); a pinned build, the same digest. "unread" when that can't
+ * be told (codesign timed out or couldn't run; the bundle unreadable): never taken for a change.
+ */
+export async function buildHolds(
+  path: string,
+  signer: Signer,
+  signal?: AbortSignal,
+): Promise<"holds" | "changed" | "unread"> {
+  if (signer.kind === "pinned") {
+    try {
+      return (await codeDigest(path, signal)) === signer.digest ? "holds" : "changed"
+    } catch (error) {
+      if (error instanceof InspectError) return "unread"
+      throw error
+    }
+  }
+  const out = await run(
+    "/usr/bin/codesign",
+    ["--verify", "--strict", `-R=${teamRequirement(signer.team, signer.identifier)}`, path],
+    TIMEOUT,
+    signal,
+  )
+  signal?.throwIfAborted()
+  return out.code === 0 ? "holds" : out.code === -1 ? "unread" : "changed"
+}
+
+/** A pinned build's limits (it's read whole when picked). */
+export const DIGEST_LIMITS = { bytes: 4 * 1024 * 1024 * 1024, entries: 200_000 }
+
+/** The digest's own version (a cache keyed by it, a future encoding: never confused). */
+const DIGEST_VERSION = "kiframe-code-v1"
+
+/**
+ * Where a link leads, resolved inside the bundle one step at a time (inner links followed, so a
+ * chain like `d -> .` then `e -> d/../x` is seen leaving): its parts under the root, `"outside"`
+ * (absolute, or above the root at any step), or `"dangling"` (a step that isn't there: it leads
+ * nowhere, so nowhere outside).
+ */
+async function resolveIn(
+  root: string,
+  base: readonly string[],
+  target: string,
+  depth: number,
+): Promise<string[] | "outside" | "dangling"> {
+  if (depth > 40 || isAbsolute(target)) return "outside"
+  const parts = [...base]
+  for (const step of target.split("/")) {
+    if (step === "" || step === ".") continue
+    if (step === "..") {
+      if (parts.length === 0) return "outside"
+      parts.pop()
+      continue
+    }
+    parts.push(step)
+    let stat
+    try {
+      stat = await lstat(join(root, ...parts))
+    } catch {
+      return "dangling"
+    }
+    if (stat.isSymbolicLink()) {
+      const inner = await resolveIn(
+        root,
+        parts.slice(0, -1),
+        await readlink(join(root, ...parts)),
+        depth + 1,
+      )
+      if (typeof inner === "string") return inner
+      parts.splice(0, parts.length, ...inner)
+    }
+  }
+  return parts
+}
+
+/**
+ * The code an unsigned app runs, hashed: the whole bundle, what pins the exact build (any change: a
+ * new digest). Each entry a JSON line (no name can pass for another entry); a link kept as a link
+ * when it leads inside the bundle (or nowhere), refused when it leads outside (code the pin
+ * couldn't cover); a socket or a device refused. Unreadable, changed while read, too large or
+ * stopped: refused, said.
+ */
+export async function codeDigest(picked: string, signal?: AbortSignal): Promise<string> {
+  const hash = createHash("sha256")
+  const line = (entry: readonly unknown[]) => hash.update(`${JSON.stringify(entry)}\n`)
+  line([DIGEST_VERSION])
+  let bytes = 0
+  let entries = 0
+  const tooLarge = () => new InspectError("that app is too large to pin")
+  const walk = async (root: string, rel: readonly string[]) => {
+    signal?.throwIfAborted()
+    const full = join(root, ...rel)
+    const name = rel.join("/")
+    const stat = await lstat(full)
+    entries += 1
+    if (entries > DIGEST_LIMITS.entries) throw tooLarge()
+    if (stat.isSymbolicLink()) {
+      const target = await readlink(full)
+      if ((await resolveIn(root, rel.slice(0, -1), target, 0)) === "outside") {
+        throw new InspectError(`that app links outside itself (${name}): Kiframe can't pin it`)
+      }
+      line(["link", name, target])
+    } else if (stat.isDirectory()) {
+      line(["dir", name])
+      for (const entry of (await readdir(full)).sort()) await walk(root, [...rel, entry])
+    } else if (stat.isFile()) {
+      bytes += stat.size
+      if (bytes > DIGEST_LIMITS.bytes) throw tooLarge()
+      line(["file", name, stat.size, (stat.mode & 0o111) !== 0])
+      let read = 0
+      for await (const chunk of createReadStream(full)) {
+        signal?.throwIfAborted()
+        read += (chunk as Buffer).length
+        hash.update(chunk as Buffer)
+      }
+      if (read !== stat.size)
+        throw new InspectError("that app changed while it was read: try again")
+    } else {
+      throw new InspectError(`that app holds what isn't a file (${name}): Kiframe can't pin it`)
+    }
+  }
+  try {
+    await walk(await realpath(picked), [])
+  } catch (error) {
+    if (signal?.aborted === true) throw signal.reason
+    if (error instanceof InspectError) throw error
+    throw new InspectError(
+      `that app can't be read whole (${(error as { code?: string }).code ?? "unreadable"})`,
+    )
+  }
+  return hash.digest("hex")
+}
+
+/**
+ * The signer of an app at `path`, and whether it's signed at all (an unsigned one has no
+ * entitlements to read). Unread: refused (never taken for unsigned).
+ */
+export async function signerOf(
+  path: string,
+  signal?: AbortSignal,
+): Promise<Signer & { signed: boolean }> {
+  const signing = await run("/usr/bin/codesign", ["-dv", path], TIMEOUT, signal)
+  signal?.throwIfAborted()
+  const parsed = parseSigning(signing.code, signing.stderr)
+  if (parsed.kind === "unread") throw new InspectError("that app's signature couldn't be read")
+  if (parsed.kind === "team") return { ...parsed, signed: true }
+  return {
+    kind: "pinned",
+    digest: await codeDigest(path, signal),
+    signed: parsed.kind === "adhoc",
+  }
+}
+
+/**
+ * The app at `picked`, inspected (static: nothing of it runs). Refused, said: not an app, where it
+ * can't stay, not Electron, an executable that isn't its own file, a Mac App Store build (its own
+ * sandbox), a developer signature that doesn't hold.
+ */
+export async function inspectDesktopApp(picked: string, signal?: AbortSignal): Promise<DesktopApp> {
+  let path: string
+  try {
+    path = await realpath(picked)
+    if (!(await lstat(path)).isDirectory()) throw new Error()
+  } catch {
+    throw new InspectError("that app can't be read (moved or removed?)")
+  }
+  const place = placeRefusal(path)
+  if (place !== undefined) throw new InspectError(place)
+  const plist = join(path, "Contents", "Info.plist")
+  const bundleId = await plistValue(plist, "CFBundleIdentifier", signal)
+  if (bundleId === undefined || !BUNDLE_ID.test(bundleId)) {
+    throw new InspectError("that app has no bundle id Kiframe can use")
+  }
+  const framework = join(path, "Contents/Frameworks/Electron Framework.framework")
+  const electron = await plistValue(
+    join(framework, "Resources/Info.plist"),
+    "CFBundleVersion",
+    signal,
+  )
+  if (electron === undefined) {
+    throw new InspectError("that isn't an Electron app: Kiframe drives Electron apps only")
+  }
+  const exe = await plistValue(plist, "CFBundleExecutable", signal)
+  if (exe === undefined || exe === "." || exe === ".." || exe.includes("/")) {
+    throw new InspectError("that app names no executable Kiframe can run")
+  }
+  const executable = join(path, "Contents", "MacOS", exe)
+  try {
+    const stat = await lstat(executable)
+    if (!stat.isFile()) throw new Error()
+    if (!(await realpath(executable)).startsWith(`${path}/`)) throw new Error()
+    await access(executable, constants.X_OK)
+  } catch {
+    throw new InspectError("that app's executable isn't its own runnable file")
+  }
+  const { signed, ...signer } = await signerOf(path, signal)
+  // A signed app's entitlements, read (unread: refused, never taken for "not sandboxed"); an
+  // unsigned one has none.
+  if (signed) {
+    const entitlements = await run(
+      "/usr/bin/codesign",
+      ["-d", "--entitlements", "-", "--xml", path],
+      TIMEOUT,
+      signal,
+    )
+    signal?.throwIfAborted()
+    if (entitlements.code !== 0) {
+      throw new InspectError("that app's entitlements couldn't be read")
+    }
+    if (/<key>com\.apple\.security\.app-sandbox<\/key>\s*<true\s*\/>/.test(entitlements.stdout)) {
+      throw new InspectError(
+        "that's a Mac App Store build (it has its own sandbox, which can't run in Kiframe's)",
+      )
+    }
+  }
+  if (signer.kind === "team" && (await buildHolds(path, signer, signal)) !== "holds") {
+    throw new InspectError("that app's signature is broken: reinstall it")
+  }
+  const [display, short, version] = await Promise.all(
+    ["CFBundleDisplayName", "CFBundleName", "CFBundleShortVersionString"].map((key) =>
+      plistValue(plist, key, signal),
+    ),
+  )
+  const name = display ?? short ?? basename(path, ".app")
+  return {
+    path,
+    bundleId,
+    name,
+    version,
+    electron,
+    executable,
+    signer,
+  }
+}
diff --git a/packages/runtime/src/electron-trial.ts b/packages/runtime/src/electron-trial.ts
new file mode 100644
index 0000000..58926dd
--- /dev/null
+++ b/packages/runtime/src/electron-trial.ts
@@ -0,0 +1,58 @@
+import type { Viewport } from "@kiframe/schema"
+import { ElectronLaunchError, launchElectron } from "./electron.ts"
+import { buildHolds, type DesktopApp } from "./electron-inspect.ts"
+
+/**
+ * A trial's outcome, read structurally: it runs confined and is driven (`ok`); its window is a site
+ * (`site`: a wrapper's, to allow as its own); it quit at once; or it failed (`failed`: said as is).
+ */
+export type TrialOutcome = { ok: true } | { site: string } | { quit: true } | { failed: string }
+
+export interface TrialOptions {
+  /** Sites it shows as its own (a second trial, after the first named one). */
+  origins?: readonly string[]
+  workDir?: string
+  signal?: AbortSignal
+  viewport?: Pick<Viewport, "width" | "height" | "deviceScaleFactor">
+  timeoutMs?: number
+}
+
+/**
+ * An app tried before it's added (PR 3b): launched confined, its main window attached, then
+ * closed. A stop is thrown as the stop.
+ */
+export async function trialDesktopApp(
+  app: Pick<DesktopApp, "path" | "executable" | "signer">,
+  opts: TrialOptions = {},
+): Promise<TrialOutcome> {
+  const origins = opts.origins ?? []
+  // The build that was picked, nothing else (a dev build rebuilt meanwhile: said). Checked before
+  // the launch only: a change in between is the user's own build tool's (stated).
+  const holds = await buildHolds(app.path, app.signer, opts.signal)
+  if (holds === "changed") return { failed: "the app changed since it was picked: pick it again" }
+  if (holds === "unread")
+    return { failed: "the app couldn't be checked (busy or unreadable): try again" }
+  let target
+  try {
+    target = await launchElectron({
+      executable: app.executable,
+      bundle: app.path,
+      // The network as in a run (its site shown even behind its own offline page): an updater
+      // can't touch the real app all the same (nothing outside the sandbox is written).
+      origins,
+      viewport: opts.viewport ?? { width: 1440, height: 900, deviceScaleFactor: 1 },
+      ...(opts.workDir !== undefined && { workDir: opts.workDir }),
+      ...(opts.signal !== undefined && { signal: opts.signal }),
+      ...(opts.timeoutMs !== undefined && { timeoutMs: opts.timeoutMs }),
+    })
+  } catch (error) {
+    // The launch says every failure as an ElectronLaunchError (but a stop: thrown as is).
+    if (!(error instanceof ElectronLaunchError)) throw error
+    if (error.why === "site" && error.site !== undefined) return { site: error.site }
+    if (error.why === "quit") return { quit: true }
+    return { failed: error.message }
+  }
+  // Its close is bounded and never fails a trial that worked.
+  await target.close().catch(() => undefined)
+  return { ok: true }
+}
diff --git a/packages/runtime/src/electron-workarea.ts b/packages/runtime/src/electron-workarea.ts
index b8e4354..806e858 100644
--- a/packages/runtime/src/electron-workarea.ts
+++ b/packages/runtime/src/electron-workarea.ts
@@ -108,15 +108,34 @@ function ownerOf(name: string): Owner | undefined {
 }
 
 /** A command's output (undefined when it fails; lsof's "nothing found" is an answer). */
-export function run(command: string, args: string[]): Promise<string | undefined> {
+export async function run(cmd: string, args: string[]): Promise<string | undefined> {
+  const out = await command(cmd, args, 5000)
+  return out.code === 0 || out.code === 1 ? out.stdout : undefined
+}
+
+/**
+ * A command's exit code (-1: it couldn't run, or timed out) and output, in the C locale: what's
+ * parsed (a start time, codesign's fields) reads the same in every language.
+ */
+export function command(
+  cmd: string,
+  args: string[],
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<{ code: number; stdout: string; stderr: string }> {
   return new Promise((resolve) => {
     execFile(
-      command,
+      cmd,
       args,
-      // The C locale: what's parsed (a start time) reads the same in every language.
-      { timeout: 5000, maxBuffer: 16 * 1024 * 1024, env: { ...process.env, LC_ALL: "C" } },
-      (error, stdout) => {
-        resolve(error !== null && (error as { code?: unknown }).code !== 1 ? undefined : stdout)
+      {
+        timeout: timeoutMs,
+        maxBuffer: 16 * 1024 * 1024,
+        env: { ...process.env, LC_ALL: "C" },
+        ...(signal !== undefined && { signal }),
+      },
+      (error, stdout, stderr) => {
+        const code = error === null ? 0 : typeof error.code === "number" ? error.code : -1
+        resolve({ code: error?.killed === true ? -1 : code, stdout, stderr })
       },
     )
   })
diff --git a/packages/runtime/src/electron.ts b/packages/runtime/src/electron.ts
index b28e6fa..abf46ae 100644
--- a/packages/runtime/src/electron.ts
+++ b/packages/runtime/src/electron.ts
@@ -26,6 +26,7 @@ import {
 import { untilStopped } from "./look.ts"
 import {
   chromium,
+  errors,
   type Browser,
   type BrowserContext,
   type CDPSession,
@@ -87,6 +88,45 @@ async function exitedSoon(child: ChildProcess, ms: number): Promise<boolean> {
   })
 }
 
+/**
+ * What a launch that failed says, the one rule (every failure an ElectronLaunchError with its
+ * `why`, but a stop): stopped → the stop; not started → said; what the app showed (a site, a
+ * page never loaded) → as is; the app quit → quit (whatever else was said); already said → as is;
+ * anything else (Playwright, CDP) → a fixed phrase (never
+ * its message: it can carry the debugging endpoint or a page's address), its detail on stderr for
+ * Kiframe's own debugging only (KIFRAME_ELECTRON_DEBUG).
+ */
+export function launchFailure(
+  error: unknown,
+  state: { stopped: unknown; spawnError: Error | undefined; quit: boolean },
+): unknown {
+  if (state.stopped !== undefined) return state.stopped
+  if (state.spawnError !== undefined) {
+    return new ElectronLaunchError(`the app couldn't be launched (${state.spawnError.message})`)
+  }
+  // What the app showed (a site, a page it never loaded): kept, whatever the app did next.
+  if (error instanceof ElectronLaunchError && (error.why === "site" || error.why === "unloaded")) {
+    return error
+  }
+  if (state.quit) return new ElectronLaunchError(QUIT_EARLY, { why: "quit" })
+  if (error instanceof ElectronLaunchError) return error
+  debug("launch", error)
+  return new ElectronLaunchError(
+    error instanceof errors.TimeoutError
+      ? "the app didn't answer in time (it may refuse automation)"
+      : "the app couldn't be driven (its debugging connection failed)",
+  )
+}
+
+/** A failure's detail, for Kiframe's own debugging: stderr, only when asked (never a tool's). */
+function debug(phase: string, error: unknown) {
+  if (process.env.KIFRAME_ELECTRON_DEBUG !== undefined) {
+    process.stderr.write(
+      `[electron] ${phase}: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`,
+    )
+  }
+}
+
 /** Shutdown phases that took long, said on stderr (KIFRAME_ELECTRON_TIMING): CI's evidence. */
 function timing(phase: string, since: number) {
   const took = Date.now() - since
@@ -98,8 +138,25 @@ function timing(phase: string, since: number) {
 const QUIT_EARLY =
   "the app quit before Kiframe could attach (it may allow only one instance: quit it and try again; be a launcher for another program; or refuse automation)"
 
-/** An app that couldn't be launched or attached: said to the user as is. */
-export class ElectronLaunchError extends Error {}
+/**
+ * An app that couldn't be launched or attached: said to the user as is. `why` read structurally (a
+ * trial's outcome): it quit at once, its main window showed a site (`site`: the https origin it
+ * showed or failed to load: a wrapper's own, to allow), or anything else.
+ */
+export class ElectronLaunchError extends Error {
+  readonly why: "quit" | "site" | "unloaded" | "other"
+  readonly site: string | undefined
+  constructor(
+    message: string,
+    detail: { why: "quit" | "unloaded" | "other" } | { why: "site"; site: string } = {
+      why: "other",
+    },
+  ) {
+    super(message)
+    this.why = detail.why
+    this.site = detail.why === "site" ? detail.site : undefined
+  }
+}
 
 export interface ElectronLaunch {
   /** The app's executable (`X.app/Contents/MacOS/X`), resolved and approved by the host. */
@@ -112,20 +169,6 @@ export interface ElectronLaunch {
   files?: string
   /** Kiframe's work area (default `~/.kiframe`): the launches' sandboxes. */
   workDir?: string
-  /** The network: "all" (a run: the app's backend), "loopback" (a trial: nothing beyond). */
-  network?: "all" | "loopback"
-  /**
-   * Tests: arguments given as they are, before `args` (the fixture app's folder, its modes): never
-   * a project's (those name files/ only).
-   */
-  appArgs?: readonly string[]
-  /** Tests: more it may read (the repo's Electron). */
-  readable?: readonly string[]
-  /**
-   * Off macOS only (Linux CI): launched without the Seatbelt confinement (there's none). Never in
-   * the app: desktop apps are macOS-only.
-   */
-  allowUnconfined?: boolean
   /** The size its windows are shown at (emulated: the window itself is never moved). */
   viewport: Pick<Viewport, "width" | "height" | "deviceScaleFactor">
   /** The https sites a wrapper app shows as its own (the project's `origins`). */
@@ -140,6 +183,60 @@ export interface ElectronLaunch {
   timeoutMs?: number
 }
 
+/** Tests only (never the package's: its launches take none of these). */
+export interface LaunchHooks {
+  /**
+   * Arguments given as they are, before `args` (the fixture app's folder, its modes): never a
+   * project's (those name files/ only).
+   */
+  appArgs?: readonly string[]
+  /** More it may read (the repo's Electron). */
+  readable?: readonly string[]
+  /** Off macOS only (Linux CI): launched without the Seatbelt confinement (there's none). */
+  allowUnconfined?: boolean
+}
+
+/** How long one attach may take before it's tried again. */
+const ATTACH_TRY_MS = 5000
+
+/**
+ * Attached over CDP, tried again while time is left: an attach as the app's first page turns into
+ * Chromium's error page (a dev server not started) can hang (measured: 1 in 5), a second never did.
+ */
+export async function attach(
+  endpoint: string,
+  deadline: number,
+  signal?: AbortSignal,
+): Promise<Browser> {
+  for (;;) {
+    const left = deadline - Date.now()
+    try {
+      return await untilStopped(
+        chromium.connectOverCDP(endpoint, { timeout: Math.max(1, Math.min(left, ATTACH_TRY_MS)) }),
+        signal,
+      )
+    } catch (error) {
+      // Out of time (or another failure): the launch's one rule words it.
+      if (!(error instanceof errors.TimeoutError) || left <= ATTACH_TRY_MS) throw error
+    }
+  }
+}
+
+/** Where a page that failed to load was going (Chromium's error page keeps it, over CDP). */
+async function unreachableUrl(page: Page): Promise<string | undefined> {
+  try {
+    const cdp = await page.context().newCDPSession(page)
+    try {
+      const { frameTree } = await cdp.send("Page.getFrameTree")
+      return frameTree.frame.unreachableUrl
+    } finally {
+      await cdp.detach().catch(() => undefined)
+    }
+  } catch {
+    return undefined
+  }
+}
+
 /** A page the guard stopped: in which window, whether it was the window itself, and where. */
 export interface GuardStop {
   page: Page
@@ -233,6 +330,9 @@ async function makeSandbox(work: string): Promise<{
     XDG_CACHE_HOME: dirs.cache,
     XDG_STATE_HOME: dirs.state,
     TMPDIR: `${dirs.tmp}${sep}`,
+    // Chromium on macOS: its temp folder (the single-instance lock's socket) in the sandbox too,
+    // never the user's /var/folders (denied by the confinement: such an app would quit).
+    MAC_CHROMIUM_TMPDIR: dirs.tmp,
   })
   return {
     root,
@@ -247,8 +347,16 @@ async function makeSandbox(work: string): Promise<{
 /** How long the app's windows must stay as they are before its main window is chosen. */
 const SETTLE_MS = 1500
 
-/** Launches `opts.executable` in a fresh sandbox and attaches to its main window. */
-export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarget> {
+/** Launches `opts.executable` in a fresh sandbox, confined, and attaches to its main window. */
+export function launchElectron(opts: ElectronLaunch): Promise<ElectronTarget> {
+  return launchElectronWith(opts, {})
+}
+
+/** `launchElectron` with the tests' hooks (not exported by the package). */
+export async function launchElectronWith(
+  opts: ElectronLaunch,
+  hooks: LaunchHooks,
+): Promise<ElectronTarget> {
   opts.signal?.throwIfAborted()
   // Before anything runs: an app moved since it was approved is said, never half-launched.
   let bundles: string[]
@@ -267,7 +375,7 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
   }
   // Never unconfined in the app: off macOS (no Seatbelt) only where asked (Linux CI).
   const confined = process.platform === "darwin"
-  if (!confined && opts.allowUnconfined !== true) {
+  if (!confined && hooks.allowUnconfined !== true) {
     throw new ElectronLaunchError("desktop apps run only on macOS (they're confined there)")
   }
   const work = opts.workDir ?? defaultWorkDir()
@@ -280,10 +388,9 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
     if (confined) {
       const confinement = {
         sandbox: sandbox.root,
-        readable: [...bundles.map(realpathOr), ...(opts.readable ?? []).map(realpathOr)],
+        readable: [...bundles.map(realpathOr), ...(hooks.readable ?? []).map(realpathOr)],
         // The home and the work area wherever they are, and the one temp folder left (/var/tmp).
         private: [realpathOr(userInfo().homedir), realpathOr(work), "/private/var/tmp"],
-        network: opts.network ?? "all",
       }
       // Its own canary, beside its sandbox (never inside: that's readable) and named after it:
       // launches at once never touch each other's, and a crash's is swept with its sandbox.
@@ -301,15 +408,18 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
     opts.signal?.throwIfAborted()
   } catch (error) {
     await rm(sandbox.root, { recursive: true, force: true }).catch(() => undefined)
+    if (opts.signal?.aborted === true) throw opts.signal.reason as Error
     if (error instanceof FilesError || error instanceof ConfinementError) {
       throw new ElectronLaunchError(error.message)
     }
-    throw error
+    if (error instanceof ElectronLaunchError) throw error
+    debug("prepare", error)
+    throw new ElectronLaunchError("the app's sandbox couldn't be prepared")
   }
   // The app's own time to start (the copy and the canary never count against it).
   const deadline = Date.now() + (opts.timeoutMs ?? LAUNCH_MS)
   const launchArgs = [
-    ...(opts.appArgs ?? []),
+    ...(hooks.appArgs ?? []),
     ...args,
     `--user-data-dir=${sandbox.profile}`,
     "--remote-debugging-port=0",
@@ -352,10 +462,7 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
       opts.signal,
       () => spawnError,
     )
-    browser = await untilStopped(
-      chromium.connectOverCDP(endpoint, { timeout: Math.max(1, deadline - Date.now()) }),
-      opts.signal,
-    )
+    browser = await attach(endpoint, deadline, opts.signal)
     const context = browser.contexts()[0]
     if (context === undefined) throw new ElectronLaunchError("the app opened no window")
     const connected = browser
@@ -366,21 +473,39 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
       () => child.exitCode !== null || child.signalCode !== null || !connected.isConnected(),
       opts.settleMs ?? SETTLE_MS,
     )
+    // Where the main window is, or went: a load that failed (offline, a dev server not started)
+    // still names it (CDP's unreachable URL), judged and said by that.
+    const failed = page.url().startsWith("chrome-error:")
+    const shown = failed ? ((await unreachableUrl(page)) ?? page.url()) : page.url()
     // Sealed now, from the main window alone: its own scheme (app:) or dev server (loopback).
     const launched = new Set<string>()
     const schemes = new Set<string>()
     const embedded = new Set<string>()
-    const origin = loopbackOrigin(page.url())
+    const origin = loopbackOrigin(shown)
     if (origin !== undefined) launched.add(origin)
-    const scheme = ownScheme(page.url())
+    const scheme = ownScheme(shown)
     if (scheme !== undefined) schemes.add(scheme)
     // What the main window embeds as it opens (a video, a widget) is part of the app as shipped.
+    // A frame still loading (its first navigation not committed: its url empty or about:blank) is
+    // read by its element's src, resolved against the page (else it'd be stopped once it loads).
+    const loading: { frame: Frame; url: string }[] = []
     for (const frame of page.frames()) {
-      const url = URL.parse(frame.url())
-      // https only (a listed site's rule: never plain http in the app's name).
-      if (frame !== page.mainFrame() && url !== null && url.protocol === "https:") {
-        embedded.add(url.origin)
+      if (frame === page.mainFrame()) continue
+      let shownIn = frame.url()
+      if (shownIn === "" || shownIn === "about:blank") {
+        const src = await frame
+          .frameElement()
+          .then((element) => element.getAttribute("src"))
+          .catch(() => null)
+        const resolved = src === null ? undefined : URL.parse(src, page.url())?.href
+        if (resolved !== undefined) {
+          shownIn = resolved
+          loading.push({ frame, url: resolved })
+        }
       }
+      const url = URL.parse(shownIn)
+      // https only (a listed site's rule: never plain http in the app's name).
+      if (url !== null && url.protocol === "https:") embedded.add(url.origin)
     }
     const own = {
       bundles,
@@ -391,9 +516,24 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
       origins: [...(opts.origins ?? []), ...embedded],
     }
     const allows = (url: string) => allowedPage(url, own)
-    if (!allows(page.url())) {
+    // A frame still loading toward what isn't the app's: stopped now, at the launch (never as it
+    // lands in a run's first step).
+    for (const { frame, url } of loading) {
+      if (!allows(url)) await frame.goto("about:blank", { timeout: BACK_MS }).catch(() => undefined)
+    }
+    if (!shown.startsWith("chrome-error:") && !allows(shown)) {
+      const url = URL.parse(shown)
+      throw new ElectronLaunchError(
+        `the app shows ${placeOf(shown)}: if that's the app's own, list it in its origins`,
+        url?.protocol === "https:" ? { why: "site", site: url.origin } : { why: "other" },
+      )
+    }
+    // Its own page, never loaded: said (never a window driven on Chromium's error page).
+    if (failed) {
+      const where = shown.startsWith("chrome-error:") ? "its page" : placeOf(shown)
       throw new ElectronLaunchError(
-        `the app shows ${placeOf(page.url())}: if that's the app's own, list it in its origins`,
+        `the app couldn't load ${where} (offline? its server not running?)`,
+        { why: "unloaded" },
       )
     }
     // The guard: every frame of every window, every navigation, at once; one that isn't the app's
@@ -410,6 +550,9 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
       }
       // A load that failed (Chromium's error page): said as such by the step, never a place.
       if (url.startsWith("chrome-error:")) return true
+      // The app's own DevTools (a dev build opens them, at once or later: a window that appears
+      // blank, then shows them): never a page a run drives or films (no web page can show them).
+      if (isDevtools(url)) return true
       return allows(url)
     }
     const watch = (p: Page) => {
@@ -424,10 +567,16 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
             ? frame.goto("about:blank")
             : p !== page
               ? p.close()
-              : // Committed is enough (never the page's load, nor a step's short timeout).
+              : // Committed is enough (never the page's load, nor a step's short timeout). No
+                // history, or a back that failed: blank (never left showing the site; the run
+                // then says to relaunch).
                 p
                   .goBack({ waitUntil: "commit", timeout: BACK_MS })
                   .then((back) => (back === null ? frame.goto("about:blank") : back))
+                  .catch((error: unknown) => {
+                    debug("back", error)
+                    return frame.goto("about:blank")
+                  })
         const done = action.then(
           () => undefined,
           () => undefined,
@@ -483,12 +632,11 @@ export async function launchElectron(opts: ElectronLaunch): Promise<ElectronTarg
     // A moment for its exit to be told (it may quit as the attach drops: the drop comes first).
     const quit = await exitedSoon(child, EXIT_TELL_MS)
     await end()
-    if (opts.signal?.aborted === true) throw opts.signal.reason as Error
-    if (spawnError !== undefined) {
-      throw new ElectronLaunchError(`the app couldn't be launched (${spawnError.message})`)
-    }
-    if (quit && !(error instanceof ElectronLaunchError)) throw new ElectronLaunchError(QUIT_EARLY)
-    throw error
+    throw launchFailure(error, {
+      stopped: opts.signal?.aborted === true ? (opts.signal.reason as unknown) : undefined,
+      spawnError,
+      quit,
+    })
   }
 }
 
@@ -550,7 +698,7 @@ function debuggingEndpoint(
         // not yet
       }
     }, 100)
-    const exited = () => finish(new ElectronLaunchError(QUIT_EARLY))
+    const exited = () => finish(new ElectronLaunchError(QUIT_EARLY, { why: "quit" }))
     const aborted = () => finish(signal?.reason as Error)
     child.once("exit", exited)
     signal?.addEventListener("abort", aborted, { once: true })
@@ -585,7 +733,7 @@ async function mainWindow(
   for (;;) {
     signal?.throwIfAborted()
     // Quit (or dropped its port) before showing a window: said at once, never a wait to the end.
-    if (gone()) throw new ElectronLaunchError(QUIT_EARLY)
+    if (gone()) throw new ElectronLaunchError(QUIT_EARLY, { why: "quit" })
     const now = windows()
     const key = now.map((p) => p.url()).join("\n")
     if (key !== seen) {
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index f762c97..c141306 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -16,6 +16,16 @@ export {
   launchElectron,
 } from "./electron.ts"
 export { defaultWorkDir, sweepWorkArea, WorkAreaError } from "./electron-workarea.ts"
+export {
+  buildHolds,
+  codeDigest,
+  type DesktopApp,
+  inspectDesktopApp,
+  InspectError,
+  type Signer,
+  signerOf,
+} from "./electron-inspect.ts"
+export { trialDesktopApp, type TrialOptions, type TrialOutcome } from "./electron-trial.ts"
 export { ConfinementError, FILES_LIMITS, seatbeltProfile } from "./electron-confine.ts"
 export { LookRefusal, maskedScreenshot, type MaskedShot } from "./look.ts"
 export {
diff --git a/packages/runtime/test/electron-inspect.test.ts b/packages/runtime/test/electron-inspect.test.ts
new file mode 100644
index 0000000..5d20c9f
--- /dev/null
+++ b/packages/runtime/test/electron-inspect.test.ts
@@ -0,0 +1,397 @@
+import { execFileSync } from "node:child_process"
+import {
+  chmodSync,
+  cpSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  symlinkSync,
+  truncateSync,
+  writeFileSync,
+} from "node:fs"
+import { createRequire } from "node:module"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterAll, beforeAll, describe, expect, it } from "vitest"
+import {
+  buildHolds,
+  codeDigest,
+  DIGEST_LIMITS,
+  inspectDesktopApp,
+  parseSigning,
+  placeRefusal,
+  teamRequirement,
+} from "../src/electron-inspect.ts"
+import { trialDesktopApp } from "../src/electron-trial.ts"
+
+// Inspecting a desktop app the user picks (PR 3b): real bundles built from the repo's Electron (a
+// clone, the fixture as its app, re-signed ad hoc: no hook in them), refused shapes beside.
+
+const electron = createRequire(join(import.meta.dirname, "../../../apps/desktop/package.json"))(
+  "electron",
+) as string
+const electronApp = electron.slice(0, electron.indexOf(".app/") + 4)
+const fixture = join(import.meta.dirname, "fixtures/electron-app")
+
+describe("where an app can't stay", () => {
+  it("refuses what isn't an app, an app inside another, disk images, translocation, the Trash", () => {
+    expect(placeRefusal("/Applications/Slack.app")).toBeUndefined()
+    expect(placeRefusal("/Users/me/Apps/Tool.app")).toBeUndefined()
+    expect(placeRefusal("/Applications/Slack")).toMatch(/isn't an app/)
+    expect(placeRefusal("/Applications/Outer.app/Contents/Inner.app")).toMatch(/inside another/)
+    expect(placeRefusal("/Volumes/Slack/Slack.app")).toMatch(/disk image/)
+    expect(placeRefusal("/private/var/folders/x/y/T/AppTranslocation/ABC/d/Slack.app")).toMatch(
+      /temporary copy/,
+    )
+    expect(placeRefusal("/Users/me/.Trash/Slack.app")).toMatch(/Trash/)
+  })
+})
+
+describe("a signature", () => {
+  it("reads unsigned, ad hoc and a developer's from codesign", () => {
+    expect(parseSigning(1, "code object is not signed at all")).toEqual({ kind: "unsigned" })
+    // Any other failure (a timeout, a codesign that can't read it): unread, never "unsigned".
+    expect(parseSigning(-1, "")).toEqual({ kind: "unread" })
+    expect(parseSigning(1, "invalid signature (code or signature have been modified)")).toEqual({
+      kind: "unread",
+    })
+    expect(
+      parseSigning(0, "Identifier=Electron\nSignature=adhoc\nTeamIdentifier=not set\n"),
+    ).toEqual({
+      kind: "adhoc",
+    })
+    expect(
+      parseSigning(0, "Identifier=com.tinyspeck.slackmacgap\nTeamIdentifier=BQR82RBBHL\n"),
+    ).toEqual({ kind: "team", team: "BQR82RBBHL", identifier: "com.tinyspeck.slackmacgap" })
+  })
+
+  it("requires the developer's team and the signed identifier, quoted", () => {
+    expect(teamRequirement("BQR82RBBHL", 'a"b')).toBe(
+      'anchor apple generic and identifier "a\\"b" and certificate leaf[subject.OU] = "BQR82RBBHL"',
+    )
+  })
+})
+
+// A pinned build's digest (any platform: plain folders).
+describe("a pinned build's digest", () => {
+  const tree = (entries: Record<string, string>, links: Record<string, string> = {}) => {
+    const root = mkdtempSync(join(tmpdir(), "kiframe-el-digest-"))
+    for (const [rel, content] of Object.entries(entries)) {
+      mkdirSync(join(root, rel, ".."), { recursive: true })
+      writeFileSync(join(root, rel), content)
+    }
+    for (const [rel, target] of Object.entries(links)) {
+      mkdirSync(join(root, rel, ".."), { recursive: true })
+      symlinkSync(target, join(root, rel))
+    }
+    return root
+  }
+
+  it("keeps links inside the bundle, and one leading nowhere", async () => {
+    const root = tree(
+      { "Versions/A/code": "x" },
+      { "Versions/Current": "A", code: "Versions/Current/code", "bin/gone": "../pruned/cli.js" },
+    )
+    expect(await codeDigest(root)).toMatch(/^[0-9a-f]{64}$/)
+  })
+
+  it("refuses a link leading outside, however it gets there", async () => {
+    for (const links of [
+      { "lib.js": "/etc/hosts" },
+      { "a/lib.js": "../../outside.js" },
+      // Through an inner link: d is the root itself, so d/../x is above it.
+      { d: ".", e: "d/../x" },
+    ]) {
+      await expect(
+        codeDigest(tree({ "a/code": "x" }, links)),
+        JSON.stringify(links),
+      ).rejects.toThrow(/links outside itself/)
+    }
+  })
+
+  it("never lets one tree pass for another (names can't forge entries)", async () => {
+    const two = tree({ A: "X", B: "Y" })
+    // One file whose name spells A's entry, A's byte and B's entry (in a plain "file name size
+    // exec" encoding the two trees would read the same).
+    const one = tree({ ["A 1 false\nXfile B"]: "Y" })
+    expect(await codeDigest(two)).not.toBe(await codeDigest(one))
+  })
+
+  it("is the same through a link to the bundle, and changes with the code", async () => {
+    const root = tree({ "a/code": "x" })
+    const linked = join(mkdtempSync(join(tmpdir(), "kiframe-el-digest-link-")), "App.app")
+    symlinkSync(root, linked)
+    const digest = await codeDigest(root)
+    expect(await codeDigest(linked)).toBe(digest)
+    writeFileSync(join(root, "a/code"), "y")
+    expect(await codeDigest(root)).not.toBe(digest)
+  })
+
+  it("refuses what isn't a file, what's too large, and stops when asked", async () => {
+    const fifo = tree({ "a/code": "x" })
+    execFileSync("mkfifo", [join(fifo, "a/pipe")])
+    await expect(codeDigest(fifo)).rejects.toThrow(/isn't a file/)
+    const limit = DIGEST_LIMITS.entries
+    DIGEST_LIMITS.entries = 2
+    try {
+      await expect(codeDigest(tree({ "a/b": "1", "a/c": "2" }))).rejects.toThrow(/too large/)
+    } finally {
+      DIGEST_LIMITS.entries = limit
+    }
+    const stopping = new AbortController()
+    stopping.abort()
+    await expect(codeDigest(tree({ a: "1" }), stopping.signal)).rejects.toMatchObject({
+      name: "AbortError",
+    })
+    // In the middle of one large file (400 MB, sparse): ended at once, never at its end.
+    const large = tree({})
+    const file = join(large, "framework")
+    writeFileSync(file, "")
+    truncateSync(file, 400 * 1024 * 1024)
+    try {
+      const t0 = Date.now()
+      await codeDigest(large)
+      const full = Date.now() - t0
+      const midway = new AbortController()
+      setTimeout(() => midway.abort(), full / 4)
+      const t1 = Date.now()
+      await expect(codeDigest(large, midway.signal)).rejects.toMatchObject({ name: "AbortError" })
+      expect(Date.now() - t1).toBeLessThan(full / 2 + 50)
+    } finally {
+      rmSync(large, { recursive: true, force: true })
+    }
+  }, 60_000)
+})
+
+describe.runIf(process.platform === "darwin")("an app's inspection", { timeout: 60_000 }, () => {
+  let root: string
+  let base: string
+  // A real bundle: Electron cloned, the fixture as its app, its id and name its own, re-signed.
+  const bundle = (name: string, change?: (app: string) => void, sign: string[] = []) => {
+    const app = join(mkdtempSync(join(root, "app-")), `${name}.app`)
+    execFileSync("cp", ["-cR", base, app])
+    change?.(app)
+    execFileSync("codesign", ["-s", "-", "-f", "--deep", ...sign, app], { stdio: "ignore" })
+    return app
+  }
+
+  beforeAll(() => {
+    root = mkdtempSync(join(tmpdir(), "kiframe-el-inspect-"))
+    base = join(root, "Base.app")
+    execFileSync("cp", ["-cR", electronApp, base])
+    cpSync(fixture, join(base, "Contents/Resources/app"), { recursive: true })
+    const plist = join(base, "Contents/Info.plist")
+    execFileSync("plutil", [
+      "-replace",
+      "CFBundleIdentifier",
+      "-string",
+      "com.kiframe.fixture",
+      plist,
+    ])
+    for (const key of ["CFBundleName", "CFBundleDisplayName"]) {
+      execFileSync("plutil", ["-replace", key, "-string", "Kiframe Fixture", plist])
+    }
+  }, 120_000)
+
+  afterAll(() => {
+    if (root !== undefined) rmSync(root, { recursive: true, force: true })
+  })
+
+  it("keeps an Electron app's id, name, versions and executable, pinned to its build", async () => {
+    const app = bundle("Fixture")
+    const seen = await inspectDesktopApp(app)
+    expect(seen).toMatchObject({
+      bundleId: "com.kiframe.fixture",
+      name: "Kiframe Fixture",
+      electron: "44.4.5",
+      executable: join(seen.path, "Contents/MacOS/Electron"),
+      signer: { kind: "pinned" },
+    })
+    // Any change to the code it runs: another build (its app, its framework).
+    const edited = bundle("Edited", (a) =>
+      writeFileSync(join(a, "Contents/Resources/app/index.html"), "<h1>changed</h1>"),
+    )
+    const digest = (await inspectDesktopApp(edited)).signer
+    expect(digest).not.toEqual(seen.signer)
+    // A helper app (where its pages and GPU run) changed: another build too.
+    const helper = bundle("Helper", (a) => {
+      const resources = join(
+        a,
+        "Contents/Frameworks/Electron Helper (Renderer).app/Contents/Resources",
+      )
+      mkdirSync(resources, { recursive: true })
+      writeFileSync(join(resources, "added.js"), "changed")
+    })
+    expect((await inspectDesktopApp(helper)).signer).not.toEqual(seen.signer)
+    expect(await codeDigest(seen.path)).toBe(
+      seen.signer.kind === "pinned" ? seen.signer.digest : "",
+    )
+  })
+
+  it("refuses an app that isn't Electron, a Mac App Store build, an executable that's a link", async () => {
+    const notElectron = bundle("Plain", (a) =>
+      rmSync(join(a, "Contents/Frameworks/Electron Framework.framework"), {
+        recursive: true,
+        force: true,
+      }),
+    )
+    await expect(inspectDesktopApp(notElectron)).rejects.toThrow(/Electron apps only/)
+    const entitlements = join(root, "sandbox.plist")
+    writeFileSync(
+      entitlements,
+      '<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict><key>com.apple.security.app-sandbox</key><true/></dict></plist>',
+    )
+    // Inspected only, never launched (its own sandbox would crash it).
+    const store = bundle("Store", undefined, ["--entitlements", entitlements])
+    await expect(inspectDesktopApp(store)).rejects.toThrow(/Mac App Store build/)
+    // Swapped after signing (codesign won't sign it so).
+    const linked = bundle("Linked")
+    const exe = join(linked, "Contents/MacOS/Electron")
+    rmSync(exe)
+    symlinkSync("/bin/sh", exe)
+    await expect(inspectDesktopApp(linked)).rejects.toThrow(/executable isn't its own/)
+  })
+
+  it("names an app with an empty display name by its bundle name", async () => {
+    const app = bundle("Unnamed", (a) =>
+      execFileSync("plutil", [
+        "-replace",
+        "CFBundleDisplayName",
+        "-string",
+        "",
+        join(a, "Contents/Info.plist"),
+      ]),
+    )
+    expect((await inspectDesktopApp(app)).name).toBe("Kiframe Fixture")
+  })
+
+  it("refuses a pinned app that links outside itself, or can't be read whole", async () => {
+    // After signing (code a link leads to outside the bundle: what the pin couldn't cover).
+    const outside = bundle("Outside")
+    symlinkSync("/etc/hosts", join(outside, "Contents/Resources/shared.js"))
+    await expect(inspectDesktopApp(outside)).rejects.toThrow(/links outside itself/)
+    const unreadable = bundle("Unreadable")
+    const locked = join(unreadable, "Contents/Resources/app/index.html")
+    chmodSync(locked, 0o000)
+    try {
+      await expect(inspectDesktopApp(unreadable)).rejects.toThrow(/can't be read whole \(EACCES\)/)
+    } finally {
+      chmodSync(locked, 0o644)
+    }
+  })
+
+  it("refuses an app inside another app", async () => {
+    const outer = join(mkdtempSync(join(root, "outer-")), "Outer.app")
+    mkdirSync(join(outer, "Contents"), { recursive: true })
+    const inner = join(outer, "Contents", "Inner.app")
+    execFileSync("cp", ["-cR", bundle("Inner"), inner])
+    await expect(inspectDesktopApp(inner)).rejects.toThrow(/inside another app/)
+    await expect(inspectDesktopApp(join(root, "Gone.app"))).rejects.toThrow(/can't be read/)
+  })
+
+  // A bundle whose app runs the fixture in a mode (a shim as its main: no argument from Kiframe).
+  const withMode = (name: string, mode: string) =>
+    bundle(name, (a) => {
+      const dir = join(a, "Contents/Resources/app")
+      writeFileSync(
+        join(dir, "mode.cjs"),
+        `process.argv.push(${JSON.stringify(mode)}, "hidden")\nrequire("./main.cjs")\n`,
+      )
+      writeFileSync(
+        join(dir, "package.json"),
+        JSON.stringify({ name: "kiframe-fixture-electron", main: "mode.cjs" }),
+      )
+    })
+
+  it("tries an app confined: driven, a wrapper's site named, one that quits said", async () => {
+    const work = mkdtempSync(join(tmpdir(), "kiframe-el-work-"))
+    const app = await inspectDesktopApp(withMode("Notes", "plain"))
+    expect(await trialDesktopApp(app, { workDir: work })).toEqual({ ok: true })
+    const wrapper = await inspectDesktopApp(withMode("Wrapper", "wrapper"))
+    // Its site named, even unreached (where its window failed to go).
+    expect(await trialDesktopApp(wrapper, { workDir: work })).toEqual({
+      site: "https://kiframe-wrapper.invalid",
+    })
+    // Listed, unreachable: said as a failed load (a real one loads, in electron.test.ts).
+    expect(
+      await trialDesktopApp(wrapper, {
+        workDir: work,
+        origins: ["https://kiframe-wrapper.invalid"],
+      }),
+    ).toMatchObject({ failed: expect.stringMatching(/couldn't load/) as string })
+    const quits = await inspectDesktopApp(withMode("Quits", "quit-at-once"))
+    expect(await trialDesktopApp(quits, { workDir: work })).toEqual({ quit: true })
+    // Nothing left of any trial.
+    expect(readdirSync(join(work, "sandboxes"))).toEqual([])
+  })
+
+  it("holds an app to the build that was picked (a pinned one rebuilt: changed)", async () => {
+    const path = withMode("Rebuilt", "plain")
+    const app = await inspectDesktopApp(path)
+    expect(await buildHolds(app.path, app.signer)).toBe("holds")
+    writeFileSync(join(path, "Contents/Resources/app/index.html"), "<h1>rebuilt</h1>")
+    expect(await buildHolds(app.path, app.signer)).toBe("changed")
+    // Never tried as the build that was picked.
+    expect(
+      await trialDesktopApp(app, { workDir: mkdtempSync(join(tmpdir(), "kiframe-el-work-")) }),
+    ).toEqual({ failed: "the app changed since it was picked: pick it again" })
+  })
+
+  it("stops an inspection when asked, even in the middle of reading it", async () => {
+    const stopping = new AbortController()
+    stopping.abort()
+    await expect(inspectDesktopApp(bundle("Stop"), stopping.signal)).rejects.toMatchObject({
+      name: "AbortError",
+    })
+    // Mid-read (the whole build hashed: hundreds of MB): ended at once.
+    const path = bundle("Midway")
+    const t0 = Date.now()
+    const full = await codeDigest(path).then(() => Date.now() - t0)
+    const midway = new AbortController()
+    setTimeout(() => midway.abort(), full / 4)
+    const t1 = Date.now()
+    await expect(codeDigest(path, midway.signal)).rejects.toMatchObject({ name: "AbortError" })
+    expect(Date.now() - t1).toBeLessThan(full / 2 + 100)
+  })
+
+  it("says a build it can't read as unread, never as changed", async () => {
+    const path = withMode("Locked", "plain")
+    const app = await inspectDesktopApp(path)
+    const locked = join(path, "Contents/Resources/app/index.html")
+    chmodSync(locked, 0o000)
+    try {
+      expect(await buildHolds(app.path, app.signer)).toBe("unread")
+      expect(
+        await trialDesktopApp(app, { workDir: mkdtempSync(join(tmpdir(), "kiframe-el-work-")) }),
+      ).toEqual({ failed: "the app couldn't be checked (busy or unreadable): try again" })
+    } finally {
+      chmodSync(locked, 0o644)
+    }
+  })
+
+  it("takes a bundle id with underscores (electron-builder's own)", async () => {
+    const app = bundle("Underscore", (a) =>
+      execFileSync("plutil", [
+        "-replace",
+        "CFBundleIdentifier",
+        "-string",
+        "com.electron.my_app",
+        join(a, "Contents/Info.plist"),
+      ]),
+    )
+    expect((await inspectDesktopApp(app)).bundleId).toBe("com.electron.my_app")
+  })
+
+  it("throws a stop as the stop", async () => {
+    const app = await inspectDesktopApp(withMode("Stopped", "plain"))
+    const stopping = new AbortController()
+    stopping.abort()
+    await expect(
+      trialDesktopApp(app, {
+        workDir: mkdtempSync(join(tmpdir(), "kiframe-el-work-")),
+        signal: stopping.signal,
+      }),
+    ).rejects.toMatchObject({ name: "AbortError" })
+  })
+})
diff --git a/packages/runtime/test/electron.test.ts b/packages/runtime/test/electron.test.ts
index fe631d2..638a083 100644
--- a/packages/runtime/test/electron.test.ts
+++ b/packages/runtime/test/electron.test.ts
@@ -17,6 +17,7 @@ import { createRequire } from "node:module"
 import { tmpdir, userInfo } from "node:os"
 import { dirname, join } from "node:path"
 import { parseProjectYaml, parseScenarioYaml } from "@kiframe/schema"
+import { errors } from "playwright"
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest"
 import { execFileSync, spawn, spawnSync } from "node:child_process"
 import { createServer, type Server } from "node:http"
@@ -29,7 +30,6 @@ import {
   ElectronLaunchError,
   type ElectronTarget,
   FILES_LIMITS,
-  launchElectron,
   recordScenario,
   runScenario,
   StepError,
@@ -37,6 +37,13 @@ import {
   sweepWorkArea,
 } from "../src/index.ts"
 import { checkConfinement, copyFiles } from "../src/electron-confine.ts"
+import {
+  attach,
+  type ElectronLaunch,
+  launchFailure,
+  launchElectronWith,
+  type LaunchHooks,
+} from "../src/electron.ts"
 import { sandboxesOf } from "../src/electron-workarea.ts"
 
 // The Electron target (OBJECT-MODEL §0.9 "Electron apps"): a fixture desktop app launched in a
@@ -55,6 +62,10 @@ const sandboxCount = () =>
 /** This file's work area (never the user's ~/.kiframe). */
 const work = mkdtempSync(join(tmpdir(), "kiframe-el-work-"))
 /** How every launch here runs: the fixture on the repo's Electron, confined on macOS. */
+// The tests' launches: the hooks (the fixture's folder and modes, the repo's Electron readable,
+// unconfined on Linux CI) beside a launch's own options.
+const launchElectron = (opts: ElectronLaunch & LaunchHooks) => launchElectronWith(opts, opts)
+
 const base = {
   executable: electron,
   bundle: fixture,
@@ -114,16 +125,26 @@ beforeAll(async () => {
   )
   secureServer = createHttpsServer(
     { key: readFileSync(join(certs, "key.pem")), cert: readFileSync(join(certs, "cert.pem")) },
-    (_req, res) => {
-      res.writeHead(200, { "content-type": "text/html" })
-      res.end("<h1>A widget</h1>")
+    (req, res) => {
+      // "/slow": answered after a while (a widget still loading as the app opens).
+      const answer = () => {
+        res.writeHead(200, { "content-type": "text/html" })
+        res.end("<h1>A widget</h1>")
+      }
+      if (req.url === "/slow") setTimeout(answer, 3000)
+      else answer()
     },
   )
   await new Promise<void>((resolve) => secureServer.listen(0, "127.0.0.1", resolve))
   secure = `https://127.0.0.1:${(secureServer.address() as AddressInfo).port}/`
-  server = createServer((_req, res) => {
-    res.writeHead(200, { "content-type": "text/html" })
-    res.end("<h1>Another site</h1>")
+  server = createServer((req, res) => {
+    // "/slow": answered after a while (a frame still loading as the app opens).
+    const answer = () => {
+      res.writeHead(200, { "content-type": "text/html" })
+      res.end("<h1>Another site</h1>")
+    }
+    if (req.url === "/slow") setTimeout(answer, 3000)
+    else answer()
   })
   await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve))
   other = `http://127.0.0.1:${(server.address() as AddressInfo).port}/`
@@ -152,6 +173,7 @@ const launch = async (
     readable?: string[]
     timeoutMs?: number
     signal?: AbortSignal
+    origins?: string[]
   } = {},
 ) => {
   const target = await launchElectron({
@@ -478,10 +500,162 @@ steps:
     }
   }, 60_000)
 
+  // macOS's fix (Linux runs unconfined, its lock's socket path under its own length limit).
+  it.runIf(process.platform === "darwin")(
+    "launches an app that allows one copy only (its lock in the sandbox, never /var/folders)",
+    async () => {
+      const target = await launch(["single"])
+      expect(await target.page.title()).toBe("Fixture notes")
+    },
+  )
+
+  it("names the site a wrapper app shows, even when it can't load it", async () => {
+    const error = await launch(["wrapper"]).then(
+      () => undefined,
+      (e: unknown) => e as ElectronLaunchError,
+    )
+    expect(error).toBeInstanceOf(ElectronLaunchError)
+    expect(error?.why).toBe("site")
+    expect(error?.site).toBe("https://kiframe-wrapper.invalid")
+    // Listed as its own but never loaded: said (never a window driven on an error page).
+    await expect(
+      launch(["wrapper"], { origins: ["https://kiframe-wrapper.invalid"] }),
+    ).rejects.toThrow(/couldn't load kiframe-wrapper\.invalid/)
+    // Listed and loaded: driven.
+    const site = new URL(secure).origin
+    const target = await launch([`wrapper=${secure}`, "trust-test-cert"], { origins: [site] })
+    expect(target.page.url()).toBe(secure)
+  })
+
+  // A fake app: announces a debugging endpoint (a test's server) and, asked, quits after a while.
+  const fakeApp = () => {
+    const dir = mkdtempSync(join(tmpdir(), "kiframe-el-fake-"))
+    const script = join(dir, "fake-app")
+    writeFileSync(
+      script,
+      `#!${process.execPath}
+const [port, quitAfter] = process.argv.slice(2)
+process.stderr.write("DevTools listening on ws://127.0.0.1:" + port + "/devtools/browser/0f0e0d0c-0000-4000-8000-000000000000\\n")
+if (quitAfter !== "never") setTimeout(() => process.exit(0), Number(quitAfter))
+else setInterval(() => undefined, 60_000)
+`,
+      { mode: 0o755 },
+    )
+    return { script, readable: [realpathSync(dir), realpathSync(dirname(process.execPath))] }
+  }
+  const fakeLaunch = (port: number, quitAfter: string, timeoutMs: number) => {
+    const fake = fakeApp()
+    return launchElectron({
+      executable: fake.script,
+      appArgs: [String(port), quitAfter],
+      readable: fake.readable,
+      workDir: work,
+      allowUnconfined: true,
+      viewport,
+      timeoutMs,
+    }).then(
+      () => undefined,
+      (e: unknown) => e,
+    )
+  }
+
+  it("says a broken debugging connection in its own words (never Playwright's, its endpoint)", async () => {
+    // An endpoint that refuses the WebSocket (a CDP it can't speak).
+    const refusing = createServer((_req, res) => res.writeHead(404).end())
+    await new Promise<void>((resolve) => refusing.listen(0, "127.0.0.1", resolve))
+    try {
+      const error = await fakeLaunch((refusing.address() as AddressInfo).port, "never", 8000)
+      expect(error).toBeInstanceOf(ElectronLaunchError)
+      expect(String(error)).toMatch(/couldn't be driven \(its debugging connection failed\)/)
+      expect(String(error)).not.toMatch(/ws:\/\/|127\.0\.0\.1/)
+    } finally {
+      refusing.close()
+    }
+  }, 30_000)
+
+  it("says an app that quits while its attach stalls as quit (never 'didn't answer')", async () => {
+    const silent = createNetServer(() => undefined)
+    await new Promise<void>((resolve) => silent.listen(0, "127.0.0.1", resolve))
+    try {
+      // It quits just after the launch's time: the attach times out, its exit lands after.
+      const error = await fakeLaunch((silent.address() as AddressInfo).port, "3300", 3000)
+      expect(error).toBeInstanceOf(ElectronLaunchError)
+      expect((error as ElectronLaunchError).why).toBe("quit")
+    } finally {
+      silent.close()
+    }
+  }, 30_000)
+
+  it("words every failure by one rule: a stop, not started, quit, said, anything else", () => {
+    const stop = new DOMException("stopped", "AbortError")
+    const said = new ElectronLaunchError("said")
+    const raw = new Error("connect ECONNREFUSED ws://127.0.0.1:9/devtools/browser/x")
+    const none = { stopped: undefined, spawnError: undefined, quit: false }
+    expect(launchFailure(raw, { ...none, stopped: stop, quit: true })).toBe(stop)
+    expect(
+      String(launchFailure(raw, { ...none, spawnError: new Error("ENOENT"), quit: true })),
+    ).toMatch(/couldn't be launched \(ENOENT\)/)
+    // Already said (a site to allow, a page never loaded) stays said, even if the app then quit.
+    const site = new ElectronLaunchError("site", { why: "site", site: "https://a.example" })
+    expect(launchFailure(site, { ...none, quit: true })).toBe(site)
+    expect(launchFailure(said, none)).toBe(said)
+    // Anything else said (no window in time) or unworded (an attach that stalled), the app gone:
+    // it quit (the one-copy advice kept).
+    expect(launchFailure(said, { ...none, quit: true })).toMatchObject({ why: "quit" })
+    const unloaded = new ElectronLaunchError("unloaded", { why: "unloaded" })
+    expect(launchFailure(unloaded, { ...none, quit: true })).toBe(unloaded)
+    expect(launchFailure(raw, { ...none, quit: true })).toMatchObject({ why: "quit" })
+    const worded = launchFailure(raw, none)
+    expect(worded).toBeInstanceOf(ElectronLaunchError)
+    expect(String(worded)).not.toMatch(/ws:\/\//)
+  })
+
+  it("tries a stalled attach again, then says it as the launch's own (never Playwright's)", async () => {
+    // A debugging endpoint that accepts and never answers.
+    let connections = 0
+    const silent = createNetServer(() => (connections += 1))
+    await new Promise<void>((resolve) => silent.listen(0, "127.0.0.1", resolve))
+    const port = (silent.address() as AddressInfo).port
+    try {
+      const error = await attach(
+        `ws://127.0.0.1:${port}/devtools/browser/x`,
+        Date.now() + 7000,
+      ).then(
+        () => undefined,
+        (e: unknown) => e,
+      )
+      // Tried twice, then the timeout handed to the launch's one rule, which words it.
+      expect(connections).toBe(2)
+      expect(error).toBeInstanceOf(errors.TimeoutError)
+      const worded = launchFailure(error, {
+        stopped: undefined,
+        spawnError: undefined,
+        quit: false,
+      })
+      expect(worded).toBeInstanceOf(ElectronLaunchError)
+      expect(String(worded)).toMatch(/didn't answer in time/)
+    } finally {
+      silent.close()
+    }
+  }, 30_000)
+
+  it("says a dev build whose server isn't running, as such (never an off-app site)", async () => {
+    const closed = createNetServer()
+    await new Promise<void>((resolve) => closed.listen(0, "127.0.0.1", resolve))
+    const port = (closed.address() as AddressInfo).port
+    await new Promise((resolve) => closed.close(resolve))
+    await expect(launch([`dev-down=http://127.0.0.1:${port}/`])).rejects.toThrow(
+      new RegExp(
+        `couldn't load 127\\.0\\.0\\.1:${port} \\(offline\\? its server not running\\?\\)`,
+      ),
+    )
+  })
+
   it("says an app that quits at once, and leaves nothing behind", async () => {
     const before = sandboxCount()
     await expect(launch(["quit-at-once"])).rejects.toThrow(ElectronLaunchError)
     await expect(launch(["quit-at-once"])).rejects.toThrow(/quit before Kiframe could attach/)
+    await expect(launch(["quit-at-once"])).rejects.toMatchObject({ why: "quit" })
     expect(sandboxCount()).toBe(before)
   })
 
@@ -603,6 +777,43 @@ steps: [{ id: add, action: click, target: { by: role, role: button, name: Add no
     open = []
   })
 
+  it("keeps a frame the app embeds that's still loading as it opens", async () => {
+    // Its first navigation uncommitted when the launch seals what's its own: read by its src.
+    const slow = `${secure}slow`
+    const embeds = await launchElectron({
+      ...base,
+      appArgs: [fixture, "hidden", `link=${slow}`, "embed-at-start", "trust-test-cert"],
+      settleMs: 300,
+    })
+    open.push(embeds)
+    expect(await waitFor(() => embeds.page.frames().some((f) => f.url() === slow), 8000)).toBe(true)
+    await runScenario(
+      embeds.page,
+      parseScenarioYaml(`version: 1\nsteps: [{ id: a, action: pause, ms: 300 }]\n`),
+      project,
+      { electron: inTarget(embeds) },
+    )
+    expect(embeds.page.frames().some((f) => f.url() === slow)).toBe(true)
+  })
+
+  it("stops a frame loading toward another site as the app opens, never in the run", async () => {
+    // Its first navigation uncommitted when the launch seals: stopped then, at the launch.
+    const slow = `${other}slow`
+    const plain = await launchElectron({
+      ...base,
+      appArgs: [fixture, "hidden", `link=${slow}`, "embed-at-start"],
+      settleMs: 300,
+    })
+    open.push(plain)
+    await runScenario(
+      plain.page,
+      parseScenarioYaml(`version: 1\nsteps: [{ id: a, action: pause, ms: 4000 }]\n`),
+      project,
+      { electron: inTarget(plain) },
+    )
+    expect(plain.page.frames().some((f) => f.url() === slow)).toBe(false)
+  })
+
   it("keeps what the app embeds as it opens, and takes its window back from a site", async () => {
     // A frame of another (https) site shown at launch is the app as shipped: never a stop.
     const embeds = await launchElectron({
@@ -754,18 +965,20 @@ steps:
     )
   })
 
-  it("never counts the app's own DevTools as leaving it", async () => {
-    const target = await launch(["devtools"])
-    await runScenario(
-      target.page,
-      parseScenarioYaml(`version: 1
+  it("never counts the app's own DevTools as leaving it, opened at once or later", async () => {
+    for (const mode of ["devtools", "devtools-late"]) {
+      const target = await launch([mode])
+      await runScenario(
+        target.page,
+        parseScenarioYaml(`version: 1
 steps:
-  - { id: wait, action: pause, ms: 1500 }
-  - { id: add, action: click, target: { by: role, role: button, name: Add note } }
+  - { id: wait, action: pause, ms: 3500 }
+  - { id: still, action: expect, that: { visible: { by: role, role: button, name: Add note } } }
 `),
-      project,
-      { electron: inTarget(target), timeoutMs: 5000 },
-    )
+        project,
+        { electron: inTarget(target), timeoutMs: 5000 },
+      )
+    }
   })
 
   it("follows a window that opens blank and loads later; a frame of another window is said only", async () => {
@@ -1072,7 +1285,7 @@ steps:
       expect(linked).not.toBe(real)
       await expect(
         checkConfinement(
-          { sandbox: linked, readable: [], private: [], network: "all" },
+          { sandbox: linked, readable: [], private: [] },
           join(mkdtempSync(join(tmpdir(), "kiframe-el-work-")), "canary.txt"),
         ),
       ).rejects.toThrow(/doesn't run programs/)
@@ -1082,7 +1295,7 @@ steps:
       // /var/tmp: outside every folder the profile denies by itself (as a /Network/Users home).
       const home = mkdtempSync("/private/var/tmp/kiframe-el-home-")
       const sandbox = mkdtempSync(join(realpathSync(tmpdir()), "kiframe-el-sb-"))
-      const confinement = { sandbox, readable: [], network: "all" } as const
+      const confinement = { sandbox, readable: [] } as const
       try {
         // Denied (the canary unread) only as one of the user's own folders.
         await expect(
@@ -1096,18 +1309,10 @@ steps:
       }
     })
 
-    it("keeps a trial off the network but this machine (no updater fetch)", () => {
-      const profile = seatbeltProfile({
-        sandbox: "/s",
-        readable: [],
-        private: [],
-        network: "loopback",
-      })
-      expect(profile).toContain("(deny network-outbound)")
-      expect(profile).toContain('(allow network-outbound (remote ip "localhost:*"))')
-      expect(
-        seatbeltProfile({ sandbox: "/s", readable: [], private: [], network: "all" }),
-      ).not.toContain("(deny network-outbound)\n")
+    it("leaves the network to the app (its backend), never other programs' sockets", () => {
+      const profile = seatbeltProfile({ sandbox: "/s", readable: [], private: [] })
+      expect(profile).not.toContain("(deny network-outbound)\n")
+      expect(profile).toContain("(deny network-outbound (remote unix-socket))")
     })
   },
 )
diff --git a/packages/runtime/test/fixtures/crash-launch.ts b/packages/runtime/test/fixtures/crash-launch.ts
index 46cd301..c0f2fd6 100644
--- a/packages/runtime/test/fixtures/crash-launch.ts
+++ b/packages/runtime/test/fixtures/crash-launch.ts
@@ -1,6 +1,6 @@
 // A Kiframe that launches a desktop app and is then killed (the test's crash): it prints the
 // launch's sandbox and waits. Args: <workDir> <executable> <bundle> <readable> <fixture app>.
-import { launchElectron } from "../../src/electron.ts"
+import { launchElectronWith } from "../../src/electron.ts"
 
 const [workDir, executable, bundle, readable, app] = process.argv.slice(2) as [
   string,
@@ -9,14 +9,14 @@ const [workDir, executable, bundle, readable, app] = process.argv.slice(2) as [
   string,
   string,
 ]
-const target = await launchElectron({
-  executable,
-  bundle,
-  readable: [readable],
-  workDir,
-  allowUnconfined: true,
-  appArgs: [app, "hidden"],
-  viewport: { width: 800, height: 600, deviceScaleFactor: 1 },
-})
+const target = await launchElectronWith(
+  {
+    executable,
+    bundle,
+    workDir,
+    viewport: { width: 800, height: 600, deviceScaleFactor: 1 },
+  },
+  { readable: [readable], allowUnconfined: true, appArgs: [app, "hidden"] },
+)
 process.stdout.write(`${target.sandbox}\n`)
 setInterval(() => undefined, 60_000)
diff --git a/packages/runtime/test/fixtures/electron-app/main.cjs b/packages/runtime/test/fixtures/electron-app/main.cjs
index ce4eea1..a663db1 100644
--- a/packages/runtime/test/fixtures/electron-app/main.cjs
+++ b/packages/runtime/test/fixtures/electron-app/main.cjs
@@ -19,7 +19,12 @@ if (splash)
 if (process.argv.includes("trust-test-cert"))
   app.commandLine.appendSwitch("ignore-certificate-errors")
 
-if (process.argv.includes("quit-at-once")) {
+// "single": it allows one copy only (as Slack, VS Code, Discord): Chromium's lock, a unix socket
+// in its temp folder.
+if (
+  process.argv.includes("quit-at-once") ||
+  (process.argv.includes("single") && !app.requestSingleInstanceLock())
+) {
   app.quit()
 } else {
   app.whenReady().then(() => {
@@ -73,18 +78,31 @@ if (process.argv.includes("quit-at-once")) {
         prefs.loadFile(join(__dirname, "other.html"))
       }, 2500)
     }
-    // "devtools": it opens DevTools itself (a dev build).
+    // "devtools": it opens DevTools itself (a dev build); "devtools-late": a while after it opens
+    // (once Kiframe is attached: a window that appears, then shows DevTools).
     if (process.argv.includes("devtools")) {
       win.webContents.once("did-finish-load", () =>
         win.webContents.openDevTools({ mode: "detach" }),
       )
     }
+    if (process.argv.includes("devtools-late")) {
+      setTimeout(() => win.webContents.openDevTools({ mode: "detach" }), 2500)
+    }
     // "elsewhere": its window shows a page that's never an app's own (a data: page).
     // "link=<url>": the other site its links and windows go to (a test's local server);
     // "embed-at-start": it shows that site in a frame as it opens.
     const link = process.argv.find((a) => a.startsWith("link="))?.slice(5) ?? "https://example.com/"
     const query = { link, ...(process.argv.includes("embed-at-start") && { embed: "1" }) }
-    if (process.argv.includes("elsewhere")) win.loadURL("data:text/html,<h1>Elsewhere</h1>")
+    // "wrapper[=<url>]": its window is a site (as Slack's app.slack.com); by default one that never
+    // loads (.invalid). "dev-down=<url>": its dev server, not running.
+    const wrapper = process.argv.find((a) => a === "wrapper" || a.startsWith("wrapper="))
+    const devDown = process.argv.find((a) => a.startsWith("dev-down="))?.slice(9)
+    if (wrapper !== undefined) {
+      win.loadURL(
+        wrapper === "wrapper" ? "https://kiframe-wrapper.invalid/client" : wrapper.slice(8),
+      )
+    } else if (devDown !== undefined) win.loadURL(devDown)
+    else if (process.argv.includes("elsewhere")) win.loadURL("data:text/html,<h1>Elsewhere</h1>")
     else win.loadFile(join(__dirname, "index.html"), { query })
   })
   app.on("window-all-closed", () => app.quit())
diff --git a/packages/schema/src/apps.test.ts b/packages/schema/src/apps.test.ts
index bb9d056..13dc0fa 100644
--- a/packages/schema/src/apps.test.ts
+++ b/packages/schema/src/apps.test.ts
@@ -298,6 +298,8 @@ describe("a desktop Electron app (design 2026-10-08)", () => {
     expect(issue({ x: desk({ args: ["--inspect=9229"] }) })).toMatch(/positional arguments only/)
     expect(issue({ x: desk({ args: ["-e"] }) })).toMatch(/positional arguments only/)
     expect(issue({ x: desk({ bundleId: "/Applications/Notes.app" }) })).toMatch(/a bundle id/)
+    // An underscore is a bundle id's (electron-builder's com.electron.my_app).
+    expect(issue({ x: desk({ bundleId: "com.electron.my_app" }) })).toBe("parsed")
     expect(issue({ x: desk({ bundleId: "notes" }) })).toMatch(/a bundle id/)
     expect(issue({ x: desk({ url: "https://a.dev" }) })).not.toBe("parsed")
     // Chromium trims an argument before telling a switch: spaces and control characters too.
diff --git a/packages/schema/src/project.ts b/packages/schema/src/project.ts
index f57e0dd..ca4c997 100644
--- a/packages/schema/src/project.ts
+++ b/packages/schema/src/project.ts
@@ -41,6 +41,9 @@ const HttpsOrigin = z
     return url !== null && url.protocol === "https:" && url.origin === s
   }, "an https origin (https://host, no path)")
 
+/** A macOS bundle id's form (underscores too: macOS runs electron-builder's com.electron.my_app). */
+export const BUNDLE_ID = /^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)+$/
+
 /**
  * A desktop app's argument as a path in the project's files/ (`files/a/b` → ["a", "b"]); undefined
  * for anything else (files/ itself, an empty, "." or ".." part: never outside it).
@@ -60,10 +63,7 @@ export function filesPath(arg: string): string[] | undefined {
 export const ElectronApp = z.strictObject({
   kind: z.literal("electron"),
   /** The macOS bundle id (`com.example.app`). */
-  bundleId: z
-    .string()
-    .max(255)
-    .regex(/^[A-Za-z][A-Za-z0-9-]*(\.[A-Za-z0-9-]+)+$/, "a bundle id (com.example.app)"),
+  bundleId: z.string().max(255).regex(BUNDLE_ID, "a bundle id (com.example.app)"),
   /**
    * What the app opens: paths in the project's files/ (`files/demo-vault`; a copy is what it gets,
    * decided 2026-10-09), positional only, never a switch.
diff --git a/vitest.config.ts b/vitest.config.ts
index b2c4c7f..e623c69 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -2,7 +2,7 @@ import { configDefaults, defineConfig } from "vitest/config"
 
 // The desktop-app target's tests launch a real Electron app each: they run alone, after every other
 // suite (a CPU busy with them made timing-sensitive tests elsewhere flaky in CI).
-const ELECTRON = "packages/runtime/test/electron.test.ts"
+const ELECTRON = "packages/runtime/test/electron*.test.ts"
 
 export default defineConfig({
   test: {

From 6b8ddd72a9702d4fdfbeb469f0d0373dc79567da Mon Sep 17 00:00:00 2001
From: Quang Lee <winlp4ever@gmail.com>
Date: Sat, 10 Oct 2026 09:08:25 +0200
Subject: [PATCH 06/10] feat(desktop): add a desktop app to a project from the
 apps panel (#60)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(desktop): add a desktop app to a project from the apps panel

On macOS, "Add desktop app…": main shows the picker and inspects what was
picked (the window holds a token, never a path or a site to allow), the
card tries it confined, then it's added to project.json and approved.

Approvals (desktop-apps.json in app data, written whole, one that doesn't
read set aside) are per Mac and per project, and cover the app (its
developer, or the exact build of an unsigned one) and what the project
opens with it. Each desktop app's status shows in the panel, checked
statically (nothing launches). Picking an app the project already names
allows it here. Removing it drops this project's approval; a trial ends
with its add, the project or a quit; leftovers are swept at the start.

* fix(desktop): show what a named desktop app opens, and steady its add

- an app a project already names: its card shows what the project opens
  with it (sites, arguments: the check runs with the sites), and an add
  after the project changed what it opens is refused; a site allowed in
  its check is written to the project and approved
- one pick and one add at a time; a check of a card given up never shows
  on another; the add dropped with the window or a new project, a check
  refused once its project closed
- statuses read together; the set-aside note said once; a status that
  can't be read said

* fix(desktop): tie a desktop app's add to its project, checked after each wait

- an add lives only while its project is the open one, checked at every
  step and after every wait (a project changed by any path ends it): an
  add given up while its app was looked at is never written
- a finished add tells the open project's agent only; a site allowed in a
  check is kept as such (never guessed), one the project refuses is said
- one app picker at a time (main); the panel never says an add given up,
  and picks nothing while one runs
- the approvals' set-aside note given once by the store itself

* refactor(desktop): own a desktop app's add whole, behind one gate

Redesign after three review rounds on its lifetime and guards (reviewed):
DesktopAdds runs the whole add (main's dialog included) through a host
(the open project, its session, Kif's state, the picker, the approval),
with one gate before every change and after every wait: a pick cancelled
or a project changed while the user picked or the app was looked at, Kif
started meanwhile, an add during a check: refused, nothing written.

- the workspace tells listeners as it switches project (every add ends,
  its trial too); a window reloading drops its add
- an add is done once written (an approval failing then: said, never
  added twice); only the project's rules are reworded (a file changed on
  disk says to reopen it)

* fix(desktop): keep each copy of a desktop app apart and approve the build tried

- approvals per copy of an app (its place): a release and a dev build of
  one bundle id never take each other's approval; a project uses one
- the build that was tried is approved (one updated since: "updated")
- a status says what needs no look at the app before looking (another
  project's, opens changed); a pick given up stops looking at its app
- an approval is written to disk before it's kept; one check at a time in
  the panel; one rule for the same app, one "apps changed" in main

* fix(desktop): keep each project's tried build and approvals that read back

- the build a project tried is kept per project (another's approval of an
  update never changes its "updated" or "ready")
- approvals validated before they're written, names cut and copies capped
  (the oldest let go): never a file set aside at the next start
- an add given up stops its look at the app; the switch wiring tested as
  main has it; a check per card in the panel; neutral "not allowed in
  this project yet" wording

* fix(desktop): compare a desktop app's version as kept, and free a cancelled add

- a version compares as it's kept (a long one never "updated" forever)
- an approval refused for its details is said in words; a long signing
  identifier kept; copies of one path merged
- an add's look at the app keeps its own failure unless it was given up
- a cancelled add frees the panel at once (per card, as a check)
- the copy cap in one place; the unused copy version removed
---
 apps/desktop/e2e/desktop-app.e2e.ts           | 104 +++
 apps/desktop/src/main/desktop-apps.ts         | 578 ++++++++++++++++
 apps/desktop/src/main/index.ts                | 125 +++-
 apps/desktop/src/main/workspace.ts            |  19 +
 .../renderer/src/components/apps-panel.tsx    | 226 ++++++-
 apps/desktop/src/renderer/src/styles.css      |  12 +
 apps/desktop/src/renderer/test/apps.test.tsx  | 215 ++++++
 apps/desktop/src/shared/channels.ts           |   5 +
 apps/desktop/src/shared/ipc.ts                |  59 ++
 apps/desktop/test/desktop-apps.test.ts        | 617 ++++++++++++++++++
 apps/desktop/test/workspace.test.ts           |  20 +
 docs/BACKLOG.md                               |   1 +
 docs/OBJECT-MODEL.md                          |   1 +
 13 files changed, 1971 insertions(+), 11 deletions(-)
 create mode 100644 apps/desktop/e2e/desktop-app.e2e.ts
 create mode 100644 apps/desktop/src/main/desktop-apps.ts
 create mode 100644 apps/desktop/test/desktop-apps.test.ts

diff --git a/apps/desktop/e2e/desktop-app.e2e.ts b/apps/desktop/e2e/desktop-app.e2e.ts
new file mode 100644
index 0000000..9b6c919
--- /dev/null
+++ b/apps/desktop/e2e/desktop-app.e2e.ts
@@ -0,0 +1,104 @@
+// "Add desktop app…" end to end (macOS: Seatbelt, codesign): the built app adds a real bundle (the
+// repo's Electron, the runtime's fixture as its app, re-signed ad hoc) picked through main's
+// dialog (stubbed), inspected, tried confined, written to the project and approved. Its work area
+// is a test's own (never ~/.kiframe).
+import { execFileSync } from "node:child_process"
+import { cpSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs"
+import { createRequire } from "node:module"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { createProject } from "@kiframe/project"
+import { _electron as electron, type ElectronApplication, type Page } from "playwright"
+import { afterAll, beforeAll, describe, expect, it } from "vitest"
+
+const appDir = join(import.meta.dirname, "..")
+const mac = process.platform === "darwin"
+let app: ElectronApplication | undefined
+let page: Page
+let root: string
+let bundle: string
+let work: string
+
+beforeAll(async () => {
+  if (!mac) return
+  root = mkdtempSync(join(tmpdir(), "kiframe-e2e-desktop-"))
+  // A real bundle with no hook in it: Electron cloned, the fixture as its app, re-signed.
+  const electronExe = createRequire(join(appDir, "package.json"))("electron") as string
+  bundle = join(root, "Notes.app")
+  execFileSync("cp", ["-cR", electronExe.slice(0, electronExe.indexOf(".app/") + 4), bundle])
+  cpSync(
+    join(appDir, "../../packages/runtime/test/fixtures/electron-app"),
+    join(bundle, "Contents/Resources/app"),
+    { recursive: true },
+  )
+  const plist = join(bundle, "Contents/Info.plist")
+  execFileSync("plutil", [
+    "-replace",
+    "CFBundleIdentifier",
+    "-string",
+    "com.kiframe.e2e-notes",
+    plist,
+  ])
+  for (const key of ["CFBundleName", "CFBundleDisplayName"]) {
+    execFileSync("plutil", ["-replace", key, "-string", "Notes", plist])
+  }
+  execFileSync("codesign", ["-s", "-", "-f", "--deep", bundle], { stdio: "ignore" })
+  work = join(root, "work")
+  const profile = join(root, "profile")
+  const env = Object.fromEntries(
+    Object.entries(process.env).filter(
+      (e): e is [string, string] =>
+        e[1] !== undefined && e[0] !== "ELECTRON_RENDERER_URL" && e[0] !== "ELECTRON_RUN_AS_NODE",
+    ),
+  )
+  env.KIFRAME_TEST_KEYCHAIN = "memory"
+  env.KIFRAME_WORK_DIR = work
+  app = await electron.launch({ args: [appDir, `--user-data-dir=${profile}`], cwd: appDir, env })
+  page = await app.firstWindow()
+  await page.getByLabel("OpenRouter API key").fill("sk-or-test-not-a-real-key")
+  await page.getByRole("button", { name: "Save key" }).click()
+}, 120_000)
+
+afterAll(async () => {
+  await app?.close()
+  if (root !== undefined) rmSync(root, { recursive: true, force: true })
+})
+
+describe.runIf(mac)("adding a desktop app", () => {
+  it("picks it, tries it confined, adds it to the project and approves it on this Mac", async () => {
+    const dir = join(root, "demo.kiframe")
+    createProject(dir, { id: "p1", name: "Desktop demo", url: "https://app.example" })
+    await app!.evaluate(({ dialog }, picked) => {
+      dialog.showOpenDialog = () => Promise.resolve({ canceled: false, filePaths: [picked] })
+    }, dir)
+    await page.getByRole("button", { name: "Open a project…" }).click()
+    await page.getByRole("button", { name: /app\.example/ }).click()
+    const panel = page.getByRole("dialog", { name: "Apps" })
+    // The app picker answers with the bundle (main's dialog, stubbed).
+    await app!.evaluate(({ dialog }, picked) => {
+      dialog.showOpenDialog = () => Promise.resolve({ canceled: false, filePaths: [picked] })
+    }, bundle)
+    await panel.getByRole("button", { name: "Add desktop app…" }).click()
+    const adding = panel.getByRole("region", { name: "Adding Notes" })
+    await expect.poll(() => adding.textContent()).toMatch(/not signed by a developer: pinned/)
+    await adding.getByRole("button", { name: "Check" }).click()
+    await expect
+      .poll(() => adding.getByRole("status").textContent(), { timeout: 40_000 })
+      .toMatch(/runs confined/)
+    await adding.getByRole("button", { name: "Add Notes" }).click()
+    await expect
+      .poll(() => panel.getByRole("list", { name: "The project's apps" }).textContent(), {
+        timeout: 10_000,
+      })
+      .toMatch(/notes.*com\.kiframe\.e2e-notes.*Ready on this Mac/s)
+    const written = JSON.parse(readFileSync(join(dir, "project.json"), "utf8")) as {
+      apps: Record<string, unknown>
+    }
+    expect(written.apps["notes"]).toMatchObject({
+      kind: "electron",
+      bundleId: "com.kiframe.e2e-notes",
+    })
+    // The trial's sandbox gone; nothing of it in the user's own work area.
+    expect(readdirSync(join(work, "sandboxes")).filter((n) => !n.endsWith(".canary"))).toEqual([])
+  }, 120_000)
+})
diff --git a/apps/desktop/src/main/desktop-apps.ts b/apps/desktop/src/main/desktop-apps.ts
new file mode 100644
index 0000000..d8a9765
--- /dev/null
+++ b/apps/desktop/src/main/desktop-apps.ts
@@ -0,0 +1,578 @@
+// Desktop apps a user added (PR 3b, design reviewed 2026-10-09): approved on this Mac and per
+// project, kept in app data (never the project: a project from someone else names an app by its
+// bundle id only). An approval covers the app (its developer, or the exact build of an unsigned one)
+// AND what the project opens with it (its arguments and sites): a project that changed either asks
+// again. Adding one: picked by the user, inspected (nothing runs), tried confined, then added.
+import { createHash, randomBytes, randomUUID } from "node:crypto"
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { type OpenedProject, saveProject } from "@kiframe/project"
+import type { DesktopApp, Signer, TrialOptions, TrialOutcome } from "@kiframe/runtime"
+import { BUNDLE_ID, type ElectronApp } from "@kiframe/schema"
+import { z } from "zod"
+
+const SignerSchema = z.union([
+  z.strictObject({
+    kind: z.literal("team"),
+    team: z.string().max(64),
+    identifier: z.string().max(1024),
+  }),
+  z.strictObject({ kind: z.literal("pinned"), digest: z.string().regex(/^[0-9a-f]{64}$/) }),
+])
+
+/** One copy of an app approved on this Mac (where it was picked, who stands behind it). */
+const Approval = z.strictObject({
+  /** Where the app was picked (its real path). */
+  path: z.string().max(4096),
+  name: z.string().max(200),
+  signer: SignerSchema,
+  approvedAt: z.string(),
+  /**
+   * Per project folder (the registry's scope): what it opens with the app, approved, and the build
+   * it tried (each project's own: another's update never changes its status).
+   */
+  scopes: z.record(
+    z.string(),
+    z.strictObject({
+      opens: z.string().regex(/^[0-9a-f]{64}$/),
+      version: z.string().max(100).optional(),
+    }),
+  ),
+})
+type Approval = z.infer<typeof Approval>
+
+/** At most this many copies of one app kept (the oldest let go): the file always reads back. */
+const MAX_COPIES = 20
+
+/** A version as kept (cut: compared the same way). */
+const versionOf = (app: Pick<DesktopApp, "version">) => app.version?.slice(0, 100)
+
+/**
+ * Each bundle id's copies (a release in Applications, a dev build elsewhere: one id, several
+ * apps): a project uses one of them.
+ */
+const File = z.strictObject({
+  version: z.literal(1),
+  apps: z.record(z.string().regex(BUNDLE_ID), z.array(Approval).max(MAX_COPIES)),
+})
+type File = z.infer<typeof File>
+
+/** What a project opens with an app (its arguments and sites), as one digest. */
+export function opensOf(app: Pick<ElectronApp, "args" | "origins">): string {
+  return createHash("sha256")
+    .update(JSON.stringify({ args: app.args ?? [], origins: app.origins ?? [] }))
+    .digest("hex")
+}
+
+/** The store's key: bundle ids compare without case (as the schema's project does). */
+const keyOf = (bundleId: string) => bundleId.toLowerCase()
+
+/**
+ * The approvals file (`desktop-apps.json` in app data, 0600, written whole: on disk first, then
+ * kept). One that doesn't read is set aside (renamed, said once), never overwritten.
+ */
+export class DesktopApprovals {
+  readonly #path: string
+  #file: File
+  #problem: string | null = null
+
+  /** Why the file was set aside: given once (the panel says it), then null. */
+  takeProblem(): string | null {
+    const problem = this.#problem
+    this.#problem = null
+    return problem
+  }
+
+  constructor(dir: string) {
+    this.#path = join(dir, "desktop-apps.json")
+    this.#file = { version: 1, apps: {} }
+    if (!existsSync(this.#path)) return
+    try {
+      this.#file = File.parse(JSON.parse(readFileSync(this.#path, "utf8")))
+    } catch {
+      const aside = `${this.#path}.bad-${Date.now()}`
+      renameSync(this.#path, aside)
+      this.#problem = `the desktop apps' approvals didn't read: set aside as ${aside}; add them again`
+    }
+  }
+
+  /** The app's copies approved on this Mac. */
+  copies(bundleId: string): readonly Approval[] {
+    const key = keyOf(bundleId)
+    return Object.hasOwn(this.#file.apps, key) ? (this.#file.apps[key] ?? []) : []
+  }
+
+  /** The copy this project folder uses (one at most). */
+  copyFor(bundleId: string, scope: string): Approval | undefined {
+    return this.copies(bundleId).find((copy) => Object.hasOwn(copy.scopes, scope))
+  }
+
+  /**
+   * The app (the build that was tried) approved for this project folder and what it opens: its
+   * copy (by place) kept with its other projects when it's the same build or developer, started
+   * afresh when another is there now; the project's other copy of that id let go.
+   */
+  approve(app: DesktopApp, scope: string, opens: string): void {
+    const atPlace = (copy: Approval) => copy.path === app.path
+    const here = this.copies(app.bundleId).find(atPlace)
+    const others = this.copies(app.bundleId)
+      .filter((copy) => !atPlace(copy))
+      .map((copy) => ({ ...copy, scopes: without(copy.scopes, scope) }))
+      .filter((copy) => Object.keys(copy.scopes).length > 0)
+    const kept = here !== undefined && sameSigner(here.signer, app.signer) ? here.scopes : {}
+    const version = versionOf(app)
+    const copy: Approval = {
+      path: app.path,
+      name: app.name.slice(0, 200),
+      signer: app.signer,
+      approvedAt: new Date().toISOString(),
+      scopes: { ...kept, [scope]: { opens, ...(version !== undefined && { version }) } },
+    }
+    try {
+      this.#write({
+        ...this.#file.apps,
+        [keyOf(app.bundleId)]: [...others, copy].slice(-MAX_COPIES),
+      })
+    } catch (error) {
+      if ((error as Error).name !== "ZodError") throw error
+      throw new Error("this app's details can't be kept (too long?)", { cause: error })
+    }
+  }
+
+  /** This project folder's approval of the app taken back (the app removed from the project). */
+  drop(bundleId: string, scope: string): void {
+    if (this.copyFor(bundleId, scope) === undefined) return
+    const copies = this.copies(bundleId)
+      .map((copy) => ({ ...copy, scopes: without(copy.scopes, scope) }))
+      .filter((copy) => Object.keys(copy.scopes).length > 0)
+    this.#write({ ...this.#file.apps, [keyOf(bundleId)]: copies })
+  }
+
+  /** Written whole, then kept (a write that fails changes nothing here either). */
+  #write(apps: File["apps"]): void {
+    // What reads back (never a file that would be set aside at the next start).
+    const next: File = File.parse({ version: 1, apps })
+    mkdirSync(dirname(this.#path), { recursive: true })
+    const tmp = `${this.#path}.${randomBytes(6).toString("hex")}.tmp`
+    writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 })
+    renameSync(tmp, this.#path)
+    this.#file = next
+  }
+}
+
+function without<T>(record: Readonly<Record<string, T>>, key: string): Record<string, T> {
+  return Object.fromEntries(Object.entries(record).filter(([k]) => k !== key))
+}
+
+/** The same app: its developer (a team app updated is still theirs), or the same pinned build. */
+function sameSigner(a: Signer, b: Signer): boolean {
+  return a.kind === "team"
+    ? b.kind === "team" && a.team === b.team && a.identifier === b.identifier
+    : b.kind === "pinned" && a.digest === b.digest
+}
+
+/**
+ * A desktop app of the project, as this Mac has it: `ready`; `updated` (same developer, a new build:
+ * tried before its next run); `allow` (approved for another project, or never on this Mac: pick it
+ * to approve it here); `opens-changed` (the project changed what it opens with it); `changed` (another
+ * developer, or another build of an unsigned one); `not-found` (no longer where it was picked).
+ */
+export type DesktopStatus =
+  | { status: "ready" | "updated" }
+  | { status: "allow" | "opens-changed" | "changed" | "not-found"; why: string }
+
+/** The functions that look at an app (the runtime's; fakes in tests). */
+export interface Looks {
+  inspect: (path: string, signal?: AbortSignal) => Promise<DesktopApp>
+  trial: (app: DesktopApp, opts: TrialOptions) => Promise<TrialOutcome>
+}
+
+/**
+ * The project's desktop app's status, static only (opening the panel never launches anything): its
+ * approval here first (what needs no look at the app), then the copy it uses, inspected, compared.
+ */
+export async function desktopStatus(
+  entry: ElectronApp,
+  scope: string,
+  approvals: DesktopApprovals,
+  looks: Pick<Looks, "inspect">,
+): Promise<DesktopStatus> {
+  const copy = approvals.copyFor(entry.bundleId, scope)
+  if (copy === undefined) {
+    return approvals.copies(entry.bundleId).length === 0
+      ? { status: "allow", why: "not added on this Mac: add it from Applications to use it here" }
+      : { status: "allow", why: "not allowed in this project yet: pick it to allow it here" }
+  }
+  if (copy.scopes[scope]?.opens !== opensOf(entry)) {
+    return {
+      status: "opens-changed",
+      why: "the project changed what it opens with it: allow it again",
+    }
+  }
+  let now: DesktopApp
+  try {
+    now = await looks.inspect(copy.path)
+  } catch (error) {
+    if (!existsSync(copy.path)) {
+      return { status: "not-found", why: `not at ${copy.path} any more: add it again` }
+    }
+    return { status: "changed", why: (error as Error).message }
+  }
+  if (keyOf(now.bundleId) !== keyOf(entry.bundleId) || !sameSigner(copy.signer, now.signer)) {
+    return { status: "changed", why: "another app is there now (or another build): add it again" }
+  }
+  return versionOf(now) !== copy.scopes[scope]?.version && now.signer.kind === "team"
+    ? { status: "updated" }
+    : { status: "ready" }
+}
+
+/** An app's name in the project: its own, in the app-name form, made unique. */
+export function appNameFor(name: string, taken: readonly string[]): string {
+  const base =
+    name
+      .normalize("NFKD")
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^[^a-z]+/, "")
+      .replace(/-+$/, "")
+      .slice(0, 32)
+      .replace(/-+$/, "") || "app"
+  if (!taken.includes(base)) return base
+  for (let i = 2; ; i++) if (!taken.includes(`${base}-${i}`)) return `${base}-${i}`
+}
+
+/** The app written to the project as `name` (refused by the project's own rules: said in words). */
+function save(opened: OpenedProject, name: string, entry: ElectronApp): void {
+  try {
+    saveProject(opened, { ...opened.project, apps: { ...opened.project.apps, [name]: entry } })
+  } catch (error) {
+    // Only the project's rules reworded (a file changed on disk, a write failed: said as is).
+    if ((error as Error).name !== "ZodError") throw error
+    const issue = (error as { issues?: { message: string }[] }).issues?.[0]?.message
+    throw new Error(`the project can't take it so${issue === undefined ? "" : ` (${issue})`}`, {
+      cause: error,
+    })
+  }
+}
+
+/** What the window shows of a picked app (never its path). */
+export interface DesktopCard {
+  token: string
+  name: string
+  bundleId: string
+  version: string | undefined
+  electron: string
+  /** Who stands behind it: a developer's team id, or none (pinned to this build). */
+  signer: { kind: "team"; team: string } | { kind: "pinned" }
+  /** The project already names it (a project from someone else): adding approves it here. */
+  existing: string | undefined
+  /**
+   * What that project opens with it, shown before it's allowed: its arguments (paths in files/,
+   * not passed to the check) and the sites it shows as its own (the check runs with them).
+   */
+  opens: { args: string[]; origins: string[] } | undefined
+}
+
+/**
+ * What the add flow needs of the app around it (main's; a fake in tests): read fresh at each step,
+ * never a snapshot.
+ */
+export interface AddHost {
+  /** The open project's session (none when no project is open). */
+  session(): string | undefined
+  opened(): OpenedProject | null
+  /** Why nothing may change now (Kif working), or undefined. */
+  busy(): string | undefined
+  /** The app the user picks (main's dialog): undefined when cancelled. */
+  pickApp(): Promise<string | undefined>
+  /** The app approved for this project with what it opens. */
+  approve(app: DesktopApp, opened: OpenedProject, opens: string): void
+  /** The project's apps changed (its agent and the window told, if it's still the open one). */
+  changed(opened: OpenedProject): void
+}
+
+interface Pending {
+  owner: number
+  session: string
+  app: DesktopApp
+  existing: string | undefined
+  /** What the project opened the app with when picked (an add after a change: refused). */
+  opensAtPick: string | undefined
+  /** The site the last trial named (kept here: the window never names one). */
+  site: string | undefined
+  /** The sites it runs with (the project's, and any the user allowed after a trial named one). */
+  origins: string[]
+  /** Sites the user allowed in its checks (written to the project with it). */
+  allowed: string[]
+  /** A trial worked with the sites it runs with now (they changed since: not tried). */
+  tried: boolean
+  trial: AbortController | undefined
+  adding: boolean
+  /** Ends what's under way for it (its add's look at the app) when it's dropped. */
+  stopping: AbortController
+}
+
+/** Refused: said to the user as is. */
+const refused = (why: string) => new Error(why)
+const GONE = "that app isn't being added any more: pick it again"
+
+/**
+ * The add flow, owned whole (PR 3b-2, redesigned after three review rounds): the app picked (main's
+ * dialog; its path stays here: the window has a token), inspected, tried confined, added. One
+ * gate before every change and after every wait: the add still under way, its window's, its
+ * project the open one, Kif not working. A project switch ends every add at once (main's hook);
+ * the gate is the guarantee whatever path changed it.
+ */
+export class DesktopAdds {
+  readonly #pending = new Map<string, Pending>()
+  /** Each window's pick in progress (a cancel ends it: its answer dropped). */
+  readonly #picks = new Map<number, { generation: number; stopping: AbortController }>()
+  #generation = 0
+  readonly #looks: Looks
+  readonly #host: AddHost
+  readonly #workDir: string | undefined
+
+  constructor(looks: Looks, host: AddHost, workDir?: string) {
+    this.#looks = looks
+    this.#host = host
+    this.#workDir = workDir
+  }
+
+  /**
+   * The user picks an app (one pick per window at a time), inspected: its card, null when the
+   * dialog was cancelled or the pick given up meanwhile; refused: thrown, said.
+   */
+  async pick(owner: number, session: string): Promise<DesktopCard | null> {
+    if (this.#picks.has(owner)) throw refused("an app is being picked already")
+    this.#current(session)
+    this.dropFor(owner)
+    const generation = ++this.#generation
+    const stopping = new AbortController()
+    this.#picks.set(owner, { generation, stopping })
+    const still = () =>
+      this.#picks.get(owner)?.generation === generation && this.#isCurrent(session)
+    try {
+      const path = await this.#host.pickApp()
+      if (path === undefined || !still()) return null
+      let app: DesktopApp
+      try {
+        app = await this.#looks.inspect(path, stopping.signal)
+      } catch (error) {
+        if (stopping.signal.aborted) return null
+        throw error
+      }
+      if (!still()) return null
+      this.#current(session)
+      const opened = this.#host.opened()
+      if (opened === null) return null
+      const named = Object.entries(opened.project.apps).find(
+        ([, a]) => a.kind === "electron" && keyOf(a.bundleId) === keyOf(app.bundleId),
+      )
+      const existing = named?.[0]
+      // Named already: tried with the sites the project lists for it (what it'll run with), shown.
+      const entry = named?.[1].kind === "electron" ? named[1] : undefined
+      const listed = [...(entry?.origins ?? [])]
+      const token = randomUUID()
+      this.#pending.set(token, {
+        owner,
+        session,
+        app,
+        existing,
+        opensAtPick: entry === undefined ? undefined : opensOf(entry),
+        site: undefined,
+        origins: listed,
+        allowed: [],
+        tried: false,
+        trial: undefined,
+        adding: false,
+        stopping: new AbortController(),
+      })
+      return {
+        token,
+        name: app.name,
+        bundleId: app.bundleId,
+        version: app.version,
+        electron: app.electron,
+        signer:
+          app.signer.kind === "team" ? { kind: "team", team: app.signer.team } : { kind: "pinned" },
+        existing,
+        opens: entry === undefined ? undefined : { args: [...(entry.args ?? [])], origins: listed },
+      }
+    } finally {
+      if (this.#picks.get(owner)?.generation === generation) this.#picks.delete(owner)
+    }
+  }
+
+  /**
+   * The picked app tried, confined. `allowSite`: with the site the last trial named (kept here),
+   * as the app's own: tried again before it can be added.
+   */
+  async check(
+    owner: number,
+    session: string,
+    token: string,
+    allowSite: boolean,
+  ): Promise<TrialOutcome> {
+    const pending = this.#own(owner, session, token)
+    if (pending.trial !== undefined) throw refused("it's being checked already")
+    if (pending.adding) throw refused("it's being added already")
+    if (allowSite) {
+      if (pending.site === undefined) throw refused("no site to allow: check it first")
+      pending.origins = [...new Set([...pending.origins, pending.site])]
+      pending.allowed = [...new Set([...pending.allowed, pending.site])]
+    }
+    // What it runs with now is untried until this trial says so.
+    pending.tried = false
+    const stopping = new AbortController()
+    pending.trial = stopping
+    try {
+      const outcome = await this.#looks.trial(pending.app, {
+        origins: pending.origins,
+        signal: stopping.signal,
+        ...(this.#workDir !== undefined && { workDir: this.#workDir }),
+      })
+      this.#own(owner, session, token)
+      pending.tried = "ok" in outcome
+      pending.site = "site" in outcome ? outcome.site : undefined
+      return outcome
+    } finally {
+      pending.trial = undefined
+    }
+  }
+
+  /**
+   * The tried app added to the project (or, named already, allowed here): its build checked again
+   * (the one tried), the project written (its changed-on-disk refusal), then approved. Once the
+   * project is written the add is done (an approval that fails then: said, allowed again later).
+   */
+  async add(owner: number, session: string, token: string): Promise<string> {
+    const pending = this.#own(owner, session, token)
+    if (pending.trial !== undefined) throw refused("it's being checked: wait for it")
+    if (!pending.tried) throw refused("check it first: it's added once it ran here")
+    if (pending.adding) throw refused("it's being added already")
+    pending.adding = true
+    try {
+      const now = await this.#looks
+        .inspect(pending.app.path, pending.stopping.signal)
+        .catch((error: unknown) => {
+          // Given up meanwhile: said as such (the gate's words); else its own reason.
+          if (pending.stopping.signal.aborted) this.#own(owner, session, token)
+          throw error
+        })
+      this.#own(owner, session, token)
+      if (!sameSigner(now.signer, pending.app.signer)) {
+        throw refused("the app changed since it was checked: pick it again")
+      }
+      const opened = this.#host.opened()
+      if (opened === null) throw refused(GONE)
+      let name = pending.existing
+      let entry: ElectronApp
+      if (name !== undefined) {
+        const named = opened.project.apps[name]
+        // What the user saw at the pick, still (a project changed meanwhile: never approved untried).
+        if (named?.kind !== "electron" || opensOf(named) !== pending.opensAtPick) {
+          throw refused("the project changed meanwhile: pick it again")
+        }
+        entry = named
+        // A site allowed in a check: the project's too (its runs need it).
+        if (pending.allowed.length > 0) {
+          entry = {
+            ...named,
+            origins: [...new Set([...(named.origins ?? []), ...pending.allowed])],
+          }
+          save(opened, name, entry)
+        }
+      } else {
+        name = appNameFor(now.name, Object.keys(opened.project.apps))
+        entry = {
+          kind: "electron",
+          bundleId: now.bundleId,
+          ...(pending.origins.length > 0 && { origins: pending.origins }),
+          viewport: { width: 1440, height: 900, deviceScaleFactor: 1 },
+        }
+        save(opened, name, entry)
+      }
+      // Written: done, whatever follows.
+      this.#pending.delete(token)
+      this.#host.changed(opened)
+      try {
+        // The build that was tried (a newer one since, same developer: "updated", tried at its run).
+        this.#host.approve(pending.app, opened, opensOf(entry))
+      } catch (error) {
+        throw refused(
+          `added as ${name}, but not approved on this Mac (${(error as Error).message}): pick it again to allow it`,
+        )
+      }
+      return name
+    } finally {
+      pending.adding = false
+    }
+  }
+
+  /** A window's pick and add given up (cancelled, the window closed or reloaded). */
+  dropFor(owner: number): void {
+    this.#picks.get(owner)?.stopping.abort()
+    this.#picks.delete(owner)
+    for (const [token, pending] of this.#pending) {
+      if (pending.owner !== owner) continue
+      pending.trial?.abort()
+      pending.stopping.abort()
+      this.#pending.delete(token)
+    }
+  }
+
+  /** Every pick and add given up, their trials ended (a project switch, a quit). */
+  dropAll(): void {
+    for (const pick of this.#picks.values()) pick.stopping.abort()
+    this.#picks.clear()
+    for (const pending of this.#pending.values()) {
+      pending.trial?.abort()
+      pending.stopping.abort()
+    }
+    this.#pending.clear()
+  }
+
+  #isCurrent(session: string): boolean {
+    return this.#host.session() === session
+  }
+
+  /** The session the window acts in is the open project's, and nothing may stop a change now. */
+  #current(session: string): void {
+    if (!this.#isCurrent(session)) throw refused("the project changed: pick the app again")
+    const busy = this.#host.busy()
+    if (busy !== undefined) throw refused(busy)
+  }
+
+  /** The gate: this window's add, still under way, its project the open one, Kif not working. */
+  #own(owner: number, session: string, token: string): Pending {
+    const pending = this.#pending.get(token)
+    if (pending !== undefined && !this.#isCurrent(pending.session)) {
+      pending.trial?.abort()
+      pending.stopping.abort()
+      this.#pending.delete(token)
+    }
+    const still = this.#pending.get(token)
+    if (still === undefined || still.owner !== owner || still.session !== session)
+      throw refused(GONE)
+    const busy = this.#host.busy()
+    if (busy !== undefined) throw refused(busy)
+    return still
+  }
+}
+
+/** The add flow's host from the workspace (main's, and tests' with a real one). */
+export function addHostOf(
+  workspace: {
+    readonly session: string | undefined
+    readonly opened: OpenedProject | null
+    readonly agent: { readonly running: boolean } | undefined
+  },
+  deps: Pick<AddHost, "pickApp" | "approve" | "changed">,
+): AddHost {
+  return {
+    session: () => workspace.session,
+    opened: () => workspace.opened,
+    busy: () => (workspace.agent?.running === true ? "Kif is working: stop it first" : undefined),
+    ...deps,
+  }
+}
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index b8522e2..be4f9c7 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -3,12 +3,20 @@ import { join } from "node:path"
 import { fileURLToPath } from "node:url"
 import { type LlmClient, OpenAiCompatibleClient } from "@kiframe/agent"
 import { type OpenedProject, TakeStore } from "@kiframe/project"
+import { defaultWorkDir, inspectDesktopApp, sweepWorkArea, trialDesktopApp } from "@kiframe/runtime"
 import { keychainBackend, memoryBackend } from "@kiframe/vault"
 import { app, type BrowserWindow, dialog, shell } from "electron"
 import { type Browser, chromium } from "playwright"
 import type { AppStatus } from "../shared/ipc.ts"
 import { errorMessage } from "../shared/util.ts"
 import { AgentHost } from "./agent.ts"
+import {
+  addHostOf,
+  DesktopAdds,
+  DesktopApprovals,
+  desktopStatus,
+  type Looks,
+} from "./desktop-apps.ts"
 import { FileVersions } from "./file-versions.ts"
 import { resolveAppAddress } from "./app-address.ts"
 import { emit, registerHandlers } from "./ipc.ts"
@@ -261,6 +269,51 @@ function start(): void {
     return status()
   }
 
+  // Desktop apps (macOS): inspected and tried by the runtime; approvals in app data.
+  const looks: Looks = { inspect: inspectDesktopApp, trial: trialDesktopApp }
+  // Kiframe's work area (~/.kiframe); a test's own (never the user's) when it names one.
+  const workDir = process.env.KIFRAME_WORK_DIR ?? defaultWorkDir()
+  const adds: DesktopAdds = new DesktopAdds(
+    looks,
+    addHostOf(workspace, {
+      pickApp: async () => {
+        const picked = await dialog.showOpenDialog(parent(), {
+          title: "Add a desktop app",
+          buttonLabel: "Choose",
+          defaultPath: "/Applications",
+          properties: ["openFile"],
+          filters: [{ name: "Applications", extensions: ["app"] }],
+        })
+        return picked.canceled ? undefined : picked.filePaths[0]
+      },
+      approve: (picked, opened, opens) =>
+        desktopApprovals().approve(picked, ids().scope(opened.dir), opens),
+      changed: (opened) => appsChanged(opened),
+    }),
+    workDir,
+  )
+  // Every add ends, its trial too, as the project switches.
+  // Every add ends, its trial too, as the project switches.
+  workspace.onSwitch(() => adds.dropAll())
+  let approvals: DesktopApprovals | undefined
+  const desktopApprovals = (): DesktopApprovals =>
+    (approvals ??= new DesktopApprovals(app.getPath("userData")))
+  /** The open project, if it's this session's (else why not). */
+  const sessionProject = (session: string): OpenedProject | string => {
+    const opened = workspace.opened
+    if (opened === null || workspace.session !== session) return "the project changed"
+    return opened
+  }
+  /** The project's apps changed: its agent and the window told (never another project's). */
+  const appsChanged = (opened: OpenedProject): void => {
+    if (workspace.opened !== opened) return
+    workspace.agent?.appsChanged(opened.project.apps)
+    void status().then((now) => {
+      if (workspace.opened === opened) emit(window, "status", now)
+    })
+  }
+  const owner = () => window?.webContents.id ?? 0
+
   /** The window a dialog belongs to (modal to it: never opened behind it). */
   const parent = (): BrowserWindow => {
     if (window === null) throw new Error("no window to show the dialog in")
@@ -270,7 +323,14 @@ function start(): void {
   const showWindow = () => {
     if (window === null) {
       window = createWindow(join(here, "../preload"), icon, devServer)
+      const closing = window.webContents.id
+      // A reload keeps the id: its add given up all the same (the window starts afresh).
+      window.webContents.on("did-start-navigation", (event) => {
+        if (event.isMainFrame && !event.isSameDocument) adds.dropFor(closing)
+      })
       window.on("closed", () => {
+        // Its add dropped, its trial ended (macOS keeps the app open without a window).
+        adds.dropFor(closing)
         window = null
       })
       return
@@ -295,6 +355,8 @@ function start(): void {
     event.preventDefault()
     if (cleanup === "running") return
     cleanup = "running"
+    // Every desktop app's trial ended (its confined app killed with it).
+    adds.dropAll()
     const work = (async () => {
       // The browser let go within the close, as for project:close (an open in flight never comes
       // between); a close refused still lets it go: the app is quitting.
@@ -477,12 +539,61 @@ function start(): void {
           } catch (e) {
             return message(e)
           }
-          workspace.agent?.appsChanged(opened.project.apps)
-          void status().then((now) => {
-            if (workspace.opened === opened) emit(window, "status", now)
-          })
+          // A desktop app's approval in this project goes with it (its other projects' stay).
+          if (removed?.kind === "electron") {
+            try {
+              desktopApprovals().drop(removed.bundleId, ids().scope(opened.dir))
+            } catch (e) {
+              say(`its approval on this Mac couldn't be removed: ${message(e)}`)
+            }
+          }
+          appsChanged(opened)
           return null
         },
+        "apps:desktop-pick": async ({ session }) => {
+          if (process.platform !== "darwin") {
+            return { refused: "desktop apps run on macOS only (they're confined there)" }
+          }
+          try {
+            const card = await adds.pick(owner(), session)
+            return card === null ? null : { card }
+          } catch (e) {
+            return { refused: message(e) }
+          }
+        },
+        "apps:desktop-check": async ({ session, token, allowSite }) => {
+          try {
+            return await adds.check(owner(), session, token, allowSite)
+          } catch (e) {
+            return { failed: message(e) }
+          }
+        },
+        "apps:desktop-add": async ({ session, token }) => {
+          try {
+            await adds.add(owner(), session, token)
+            return null
+          } catch (e) {
+            return message(e)
+          }
+        },
+        "apps:desktop-cancel": () => adds.dropFor(owner()),
+        "apps:desktop-status": async ({ session }) => {
+          const opened = sessionProject(session)
+          const apps: Record<string, Awaited<ReturnType<typeof desktopStatus>>> = {}
+          if (typeof opened === "string") return { apps, problem: null }
+          const store = desktopApprovals()
+          const scope = ids().scope(opened.dir)
+          await Promise.all(
+            Object.entries(opened.project.apps).map(async ([name, entry]) => {
+              if (entry.kind !== "electron") return
+              apps[name] =
+                process.platform === "darwin"
+                  ? await desktopStatus(entry, scope, store, looks)
+                  : { status: "not-found", why: "desktop apps run on macOS only" }
+            }),
+          )
+          return { apps, problem: store.takeProblem() }
+        },
         "preview:open": (sceneId) => {
           const opened = workspace.opened
           if (opened === null) return { ok: false, why: "No project is open." }
@@ -506,6 +617,12 @@ function start(): void {
           // After the window's first read: pushed to it (not an action's result).
           say(`couldn't clean up old recordings: ${message(e)}`)
         }
+        // What a crash left of desktop apps' launches (never another running Kiframe's).
+        if (process.platform === "darwin") {
+          sweepWorkArea(workDir).catch((e: unknown) =>
+            say(`couldn't clean up desktop apps' leftovers: ${message(e)}`),
+          )
+        }
         // Sealed, then scratch beyond the budget (said if it fails).
         void sealTakes().then(() =>
           keeper?.evict().catch((e: unknown) => say(`couldn't tidy old recordings: ${message(e)}`)),
diff --git a/apps/desktop/src/main/workspace.ts b/apps/desktop/src/main/workspace.ts
index e0f1ce8..ba89ba2 100644
--- a/apps/desktop/src/main/workspace.ts
+++ b/apps/desktop/src/main/workspace.ts
@@ -18,6 +18,7 @@ export class Workspace<A extends Agent> {
   #session = ""
   #agent: A | undefined
   #switching: Promise<unknown> = Promise.resolve()
+  readonly #onSwitch: (() => void)[] = []
 
   readonly #ready: () => void
 
@@ -39,6 +40,16 @@ export class Workspace<A extends Agent> {
     return this.#opened
   }
 
+  /** This opening's session; none when no project is open. */
+  get session(): string | undefined {
+    return this.#opened === null ? undefined : this.#session
+  }
+
+  /** Told as a project is opened, created or closed (what belonged to the last one ends). */
+  onSwitch(listener: () => void): void {
+    this.#onSwitch.push(listener)
+  }
+
   /** The open project's apps and this opening's session, without building its whole view. */
   apps(): Pick<ProjectView, "session" | "apps"> | undefined {
     if (this.#opened === null) return undefined
@@ -86,6 +97,14 @@ export class Workspace<A extends Agent> {
       this.#opened = opened
       this.#agent = agent
       this.#session = randomBytes(6).toString("hex")
+      // A listener that fails never keeps the old agent from closing.
+      for (const listener of this.#onSwitch) {
+        try {
+          listener()
+        } catch {
+          // said by the listener itself, if anywhere
+        }
+      }
       try {
         await old?.close()
       } finally {
diff --git a/apps/desktop/src/renderer/src/components/apps-panel.tsx b/apps/desktop/src/renderer/src/components/apps-panel.tsx
index 658e77f..dfabcbd 100644
--- a/apps/desktop/src/renderer/src/components/apps-panel.tsx
+++ b/apps/desktop/src/renderer/src/components/apps-panel.tsx
@@ -1,11 +1,29 @@
-// The project's apps: each with its exact origin (main's), and a way to remove one (never the
-// first: where scenes start). Main asks before removing, naming the scenes that use it.
-import { Globe, WarningCircle, X } from "@phosphor-icons/react"
-import { useEffect, useRef, useState } from "react"
-import { appViewIdentity, type ProjectView } from "../../../shared/ipc.ts"
+// The project's apps: each with its exact origin (main's) or its bundle id, and a way to remove one
+// (never the first: where scenes start). Main asks before removing, naming the scenes that use it.
+// On macOS, a desktop app is added here: main shows the picker and inspects it, the card tries it
+// confined, then adds it (the window holds a token, never the app's path or a site to allow).
+import { AppWindow, Globe, WarningCircle, X } from "@phosphor-icons/react"
+import { useCallback, useEffect, useRef, useState } from "react"
+import {
+  appViewIdentity,
+  type DesktopCheck,
+  type DesktopPick,
+  type DesktopStatusView,
+  type ProjectView,
+} from "../../../shared/ipc.ts"
 import { api } from "../api.ts"
 import { useChat } from "../chat-store.ts"
 
+type Card = Extract<DesktopPick, { card: unknown }>["card"]
+
+/** A desktop app's status on this Mac, in words. */
+function statusText(entry: DesktopStatusView["apps"][string] | undefined): string {
+  if (entry === undefined) return ""
+  if (entry.status === "ready") return "Ready on this Mac"
+  if (entry.status === "updated") return "Updated: tried confined before its next run"
+  return entry.why ?? ""
+}
+
 export function AppsPanel({
   project,
   onClose,
@@ -14,8 +32,18 @@ export function AppsPanel({
   onClose: () => void
 }) {
   const running = useChat((s) => s.running)
+  const mac = api().platform === "darwin"
   const [error, setError] = useState<string | null>(null)
   const [busy, setBusy] = useState(false)
+  const [statuses, setStatuses] = useState<DesktopStatusView["apps"]>({})
+  const [card, setCard] = useState<Card | null>(null)
+  const [outcome, setOutcome] = useState<DesktopCheck | null>(null)
+  const [checking, setChecking] = useState(false)
+  const [picking, setPicking] = useState(false)
+  const [adding, setAdding] = useState(false)
+  // The card a check's answer belongs to (an answer for a card given up: dropped).
+  const current = useRef<string | null>(null)
+  current.current = card?.token ?? null
   const close = useRef(onClose)
   close.current = onClose
   useEffect(() => {
@@ -26,6 +54,32 @@ export function AppsPanel({
     return () => document.removeEventListener("keydown", onKey)
   }, [])
 
+  const hasDesktop = project.apps.some((a) => a.kind === "electron")
+  const refresh = useCallback(async () => {
+    if (!hasDesktop) return
+    const view = await api()
+      .invoke("apps:desktop-status", { session: project.session })
+      .catch((e: unknown) => {
+        setError(`the desktop apps' status couldn't be read: ${String(e)}`)
+        return null
+      })
+    if (view === null) return
+    setStatuses(view.apps)
+    if (view.problem !== null) setError(view.problem)
+  }, [hasDesktop, project.session])
+  useEffect(() => {
+    void refresh()
+  }, [refresh])
+
+  // An add given up when the panel closes (its trial ended in main).
+  useEffect(
+    () => () =>
+      void api()
+        .invoke("apps:desktop-cancel")
+        .catch(() => undefined),
+    [],
+  )
+
   const remove = async (name: string, identity: string) => {
     if (busy) return
     setBusy(true)
@@ -36,6 +90,83 @@ export function AppsPanel({
     setError(refused)
   }
 
+  // Busy flags read at once (a double click within one frame sees the first).
+  const pickingNow = useRef(false)
+  // The card an add is under way for (a card given up frees the panel at once).
+  const addingNow = useRef<string | null>(null)
+  // The card a check is under way for (another card's Check is its own).
+  const checkingNow = useRef<string | null>(null)
+  const pick = async () => {
+    if (pickingNow.current || (addingNow.current !== null && addingNow.current === current.current))
+      return
+    pickingNow.current = true
+    setError(null)
+    setOutcome(null)
+    setPicking(true)
+    const picked = await api()
+      .invoke("apps:desktop-pick", { session: project.session })
+      .catch((e: unknown) => ({ refused: String(e) }))
+    pickingNow.current = false
+    setPicking(false)
+    if (picked === null) return
+    if ("refused" in picked) {
+      setCard(null)
+      setError(picked.refused)
+      return
+    }
+    setCard(picked.card)
+  }
+
+  const check = async (allowSite: boolean) => {
+    if (card === null || checkingNow.current === card.token) return
+    const token = card.token
+    checkingNow.current = token
+    setChecking(true)
+    setOutcome(null)
+    const result = await api()
+      .invoke("apps:desktop-check", { session: project.session, token, allowSite })
+      .catch((e: unknown) => ({ failed: String(e) }))
+    if (checkingNow.current === token) checkingNow.current = null
+    // Given up meanwhile (cancelled, another app picked): never shown on another card.
+    if (current.current !== token) return
+    setChecking(false)
+    setOutcome(result)
+  }
+
+  const add = async () => {
+    if (card === null || addingNow.current === card.token) return
+    const token = card.token
+    addingNow.current = token
+    setAdding(true)
+    const refused = await api()
+      .invoke("apps:desktop-add", { session: project.session, token })
+      .catch((e: unknown) => String(e))
+    if (addingNow.current === token) addingNow.current = null
+    setAdding(false)
+    // Given up meanwhile (cancelled, another app picked): never said on another card.
+    if (current.current !== token) {
+      if (refused === null) await refresh()
+      return
+    }
+    if (refused !== null) {
+      setError(refused)
+      return
+    }
+    setCard(null)
+    setOutcome(null)
+    await refresh()
+  }
+
+  const cancel = () => {
+    setCard(null)
+    setOutcome(null)
+    setChecking(false)
+    setAdding(false)
+    void api()
+      .invoke("apps:desktop-cancel")
+      .catch(() => undefined)
+  }
+
   return (
     <div className="dialog-backdrop">
       <div className="dialog" role="dialog" aria-modal="true" aria-labelledby="apps-title">
@@ -47,14 +178,18 @@ export function AppsPanel({
           </button>
         </div>
         <p className="dialog-text">
-          The sites this project’s scenes may open. Kif asks before adding one.
+          The sites and desktop apps this project’s scenes may open. Kif asks before adding a site;
+          you add desktop apps.
         </p>
         <ul className="app-list" aria-label="The project's apps">
           {project.apps.map((app, i) => (
             <li key={app.name}>
-              <Globe size={15} />
+              {app.kind === "electron" ? <AppWindow size={15} /> : <Globe size={15} />}
               <span className="mono">{app.name}</span>
               <span className="mono app-origin">{appViewIdentity(app)}</span>
+              {app.kind === "electron" && (
+                <span className="app-first">{statusText(statuses[app.name])}</span>
+              )}
               <div className="spacer" />
               {i === 0 ? (
                 <span className="app-first">Where scenes start</span>
@@ -72,6 +207,73 @@ export function AppsPanel({
             </li>
           ))}
         </ul>
+        {mac && card === null && (
+          <button
+            type="button"
+            className="btn"
+            disabled={running || picking || adding}
+            title={running ? "Kif is working: stop it first" : undefined}
+            onClick={() => void pick()}
+          >
+            {picking ? "Looking at the app…" : "Add desktop app…"}
+          </button>
+        )}
+        {card !== null && (
+          <section className="app-card" aria-label={`Adding ${card.name}`}>
+            <p>
+              <strong>{card.name}</strong> {card.version ?? ""} · Electron {card.electron} ·{" "}
+              {card.signer.kind === "team"
+                ? `signed by developer ${card.signer.team}`
+                : "not signed by a developer: pinned to this build"}
+            </p>
+            {card.existing !== undefined && (
+              <p className="app-card-why">
+                This project names it already (as {card.existing}): checking it allows it here, with
+                what the project opens with it:{" "}
+                {card.opens === undefined ||
+                (card.opens.args.length === 0 && card.opens.origins.length === 0)
+                  ? "nothing more."
+                  : [
+                      ...card.opens.origins.map((o) => `the site ${o} as its own`),
+                      ...card.opens.args.map((a) => `${a} (not opened by the check)`),
+                    ].join(", ")}
+              </p>
+            )}
+            <p className="app-card-why">
+              Kiframe opens {card.name} confined (it can’t read or change your files, your own{" "}
+              {card.name}’s data or its preferences) for a few seconds, to check it works there.
+            </p>
+            {outcome !== null && <p role="status">{outcomeText(outcome, card.name)}</p>}
+            <div className="row">
+              {outcome !== null && "ok" in outcome ? (
+                <button type="button" className="btn" disabled={adding} onClick={() => void add()}>
+                  {card.existing === undefined ? `Add ${card.name}` : `Allow ${card.name} here`}
+                </button>
+              ) : outcome !== null && "site" in outcome ? (
+                <button
+                  type="button"
+                  className="btn"
+                  disabled={checking}
+                  onClick={() => void check(true)}
+                >
+                  Allow {outcome.site} and check again
+                </button>
+              ) : (
+                <button
+                  type="button"
+                  className="btn"
+                  disabled={checking || running}
+                  onClick={() => void check(false)}
+                >
+                  {checking ? "Checking…" : "Check"}
+                </button>
+              )}
+              <button type="button" className="btn btn-ghost" onClick={cancel}>
+                Cancel
+              </button>
+            </div>
+          </section>
+        )}
         {error !== null && (
           <div className="error" role="alert">
             <WarningCircle size={16} weight="fill" />
@@ -82,3 +284,13 @@ export function AppsPanel({
     </div>
   )
 }
+
+/** A trial's outcome, in words. */
+function outcomeText(outcome: DesktopCheck, name: string): string {
+  if ("ok" in outcome) return `${name} runs confined: Kiframe can drive it.`
+  if ("site" in outcome) {
+    return `${name}’s window is the site ${outcome.site}: if that’s ${name}’s own, allow it.`
+  }
+  if ("quit" in outcome) return `${name} quit at once: it may refuse automation.`
+  return outcome.failed
+}
diff --git a/apps/desktop/src/renderer/src/styles.css b/apps/desktop/src/renderer/src/styles.css
index 9e945c4..af703e7 100644
--- a/apps/desktop/src/renderer/src/styles.css
+++ b/apps/desktop/src/renderer/src/styles.css
@@ -1708,6 +1708,18 @@ ul.strip-cards > li {
   color: var(--muted);
 }
 
+/* A desktop app being added: what it is, its check's outcome, the next step. */
+.app-card {
+  margin-top: 8px;
+  padding: 10px 12px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+}
+
+.app-card p {
+  margin: 0 0 8px;
+}
+
 /* The app chip opens the apps panel; "+2" when there are more. */
 .chip-button {
   cursor: pointer;
diff --git a/apps/desktop/src/renderer/test/apps.test.tsx b/apps/desktop/src/renderer/test/apps.test.tsx
index ccca81e..ec3b981 100644
--- a/apps/desktop/src/renderer/test/apps.test.tsx
+++ b/apps/desktop/src/renderer/test/apps.test.tsx
@@ -95,3 +95,218 @@ describe("the project's apps", () => {
     )
   })
 })
+
+// PR 3b: a desktop app added from the panel (main picks, inspects, tries; the window holds a token).
+describe("adding a desktop app", () => {
+  const withDesktop: ProjectView = {
+    ...project,
+    apps: [...project.apps, { name: "notes", kind: "electron", bundleId: "com.example.Notes" }],
+  }
+  const card = {
+    token: "6a1c6c1e-0f0b-4d5e-9a3b-2c1d0e9f8a7b",
+    name: "Slack",
+    bundleId: "com.tinyspeck.slackmacgap",
+    version: "4.41",
+    electron: "44.4.5",
+    signer: { kind: "team" as const, team: "BQR82RBBHL" },
+    existing: undefined,
+    opens: undefined,
+  }
+
+  it("shows each desktop app's status on this Mac (nothing launched to know it)", async () => {
+    const { invoke } = stubApi({
+      "app:status": () => status({ hasKey: true, project: withDesktop }),
+      "apps:desktop-status": () => ({
+        apps: {
+          notes: { status: "allow", why: "approved for another project: allow it in this one" },
+        },
+        problem: null,
+      }),
+      "apps:desktop-cancel": () => undefined,
+    })
+    render(<App />)
+    fireEvent.click(await screen.findByRole("button", { name: /app\.test/ }))
+    const panel = screen.getByRole("dialog", { name: "Apps" })
+    expect(await within(panel).findByText(/approved for another project/)).toBeTruthy()
+    expect(invoke).toHaveBeenCalledWith("apps:desktop-status", { session: "s1" })
+  })
+
+  it("picks, checks, allows a wrapper's site, then adds: never sending a path or a site", async () => {
+    let checks = 0
+    const { invoke } = stubApi({
+      "app:status": () => status({ hasKey: true, project }),
+      "apps:desktop-pick": () => ({ card }),
+      "apps:desktop-check": () =>
+        checks++ === 0 ? { site: "https://app.slack.com" } : { ok: true },
+      "apps:desktop-add": () => null,
+      "apps:desktop-cancel": () => undefined,
+    })
+    render(<App />)
+    fireEvent.click(await screen.findByRole("button", { name: /app\.test/ }))
+    const panel = screen.getByRole("dialog", { name: "Apps" })
+    fireEvent.click(within(panel).getByRole("button", { name: "Add desktop app…" }))
+    const adding = await within(panel).findByRole("region", { name: "Adding Slack" })
+    expect(adding.textContent).toContain("signed by developer BQR82RBBHL")
+    expect(within(adding).queryByRole("button", { name: "Add Slack" })).toBeNull()
+    fireEvent.click(within(adding).getByRole("button", { name: "Check" }))
+    fireEvent.click(
+      await within(adding).findByRole("button", {
+        name: "Allow https://app.slack.com and check again",
+      }),
+    )
+    fireEvent.click(await within(adding).findByRole("button", { name: "Add Slack" }))
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(invoke).toHaveBeenCalledWith("apps:desktop-check", {
+      session: "s1",
+      token: card.token,
+      allowSite: false,
+    })
+    expect(invoke).toHaveBeenCalledWith("apps:desktop-check", {
+      session: "s1",
+      token: card.token,
+      allowSite: true,
+    })
+    expect(invoke).toHaveBeenCalledWith("apps:desktop-add", { session: "s1", token: card.token })
+    // The window named no path and no site: only its session, the token and a yes.
+    expect(JSON.stringify(invoke.mock.calls)).not.toMatch(/Applications|slack\.com"/)
+  })
+
+  it("says why an app can't be added, and offers nothing off macOS", async () => {
+    stubApi({
+      "app:status": () => status({ hasKey: true, project }),
+      "apps:desktop-pick": () => ({
+        refused: "that isn't an Electron app: Kiframe drives Electron apps only",
+      }),
+      "apps:desktop-cancel": () => undefined,
+    })
+    render(<App />)
+    fireEvent.click(await screen.findByRole("button", { name: /app\.test/ }))
+    const panel = screen.getByRole("dialog", { name: "Apps" })
+    fireEvent.click(within(panel).getByRole("button", { name: "Add desktop app…" }))
+    expect((await within(panel).findByRole("alert")).textContent).toMatch(/Electron apps only/)
+    cleanup()
+    window.kiframe = { ...window.kiframe, platform: "linux" }
+    render(<App />)
+    fireEvent.click(await screen.findByRole("button", { name: /app\.test/ }))
+    expect(screen.queryByRole("button", { name: "Add desktop app…" })).toBeNull()
+  })
+
+  it("shows what a project that names the app opens with it, before it's allowed", async () => {
+    stubApi({
+      "app:status": () => status({ hasKey: true, project }),
+      "apps:desktop-pick": () => ({
+        card: {
+          ...card,
+          existing: "slack",
+          opens: { args: ["files/vault"], origins: ["https://evil.example"] },
+        },
+      }),
+      "apps:desktop-cancel": () => undefined,
+    })
+    render(<App />)
+    fireEvent.click(await screen.findByRole("button", { name: /app\.test/ }))
+    const panel = screen.getByRole("dialog", { name: "Apps" })
+    fireEvent.click(within(panel).getByRole("button", { name: "Add desktop app…" }))
+    const adding = await within(panel).findByRole("region", { name: "Adding Slack" })
+    expect(adding.textContent).toContain("the site https://evil.example as its own")
+    expect(adding.textContent).toContain("files/vault (not opened by the check)")
+  })
+
+  it("never shows a check's answer on a card picked after it was given up", async () => {
+    let answer: (v: unknown) => void = () => undefined
+    let picks = 0
+    stubApi({
+      "app:status": () => status({ hasKey: true, project }),
+      "apps:desktop-pick": () => ({
+        card:
+          picks++ === 0
+            ? card
+            : { ...card, token: "7b2d6d2f-1a1c-4e6f-8b4c-3d2e1f0a9b8c", name: "Notion" },
+      }),
+      "apps:desktop-check": () => new Promise((resolve) => (answer = resolve)) as never,
+      "apps:desktop-cancel": () => undefined,
+    })
+    render(<App />)
+    fireEvent.click(await screen.findByRole("button", { name: /app\.test/ }))
+    const panel = screen.getByRole("dialog", { name: "Apps" })
+    fireEvent.click(within(panel).getByRole("button", { name: "Add desktop app…" }))
+    const slack = await within(panel).findByRole("region", { name: "Adding Slack" })
+    fireEvent.click(within(slack).getByRole("button", { name: "Check" }))
+    fireEvent.click(within(slack).getByRole("button", { name: "Cancel" }))
+    fireEvent.click(within(panel).getByRole("button", { name: "Add desktop app…" }))
+    const notion = await within(panel).findByRole("region", { name: "Adding Notion" })
+    await act(async () => {
+      answer({ ok: true })
+      await Promise.resolve()
+    })
+    expect(within(notion).queryByRole("status")).toBeNull()
+    expect(within(notion).queryByRole("button", { name: "Add Notion" })).toBeNull()
+  })
+
+  it("never says an add given up on the card picked after it", async () => {
+    let answer: (v: unknown) => void = () => undefined
+    let picks = 0
+    stubApi({
+      "app:status": () => status({ hasKey: true, project }),
+      "apps:desktop-pick": () => ({
+        card:
+          picks++ === 0
+            ? card
+            : { ...card, token: "7b2d6d2f-1a1c-4e6f-8b4c-3d2e1f0a9b8c", name: "Notion" },
+      }),
+      "apps:desktop-check": () => ({ ok: true }),
+      "apps:desktop-add": () => new Promise((resolve) => (answer = resolve)) as never,
+      "apps:desktop-cancel": () => undefined,
+    })
+    render(<App />)
+    fireEvent.click(await screen.findByRole("button", { name: /app\.test/ }))
+    const panel = screen.getByRole("dialog", { name: "Apps" })
+    fireEvent.click(within(panel).getByRole("button", { name: "Add desktop app…" }))
+    const slack = await within(panel).findByRole("region", { name: "Adding Slack" })
+    fireEvent.click(within(slack).getByRole("button", { name: "Check" }))
+    fireEvent.click(await within(slack).findByRole("button", { name: "Add Slack" }))
+    fireEvent.click(within(slack).getByRole("button", { name: "Cancel" }))
+    // Given up: the panel's free at once (main refuses that add's write).
+    expect(
+      within(panel).getByRole("button", { name: "Add desktop app…" }).hasAttribute("disabled"),
+    ).toBe(false)
+    await act(async () => {
+      answer("the project can't take it so")
+      await Promise.resolve()
+    })
+    // The add given up: its answer said nowhere.
+    expect(within(panel).queryByRole("alert")).toBeNull()
+    fireEvent.click(within(panel).getByRole("button", { name: "Add desktop app…" }))
+    await within(panel).findByRole("region", { name: "Adding Notion" })
+  })
+
+  it("checks the next card at once, whatever a given-up card's check is still doing", async () => {
+    let checks = 0
+    let picks = 0
+    stubApi({
+      "app:status": () => status({ hasKey: true, project }),
+      "apps:desktop-pick": () => ({
+        card:
+          picks++ === 0
+            ? card
+            : { ...card, token: "7b2d6d2f-1a1c-4e6f-8b4c-3d2e1f0a9b8c", name: "Notion" },
+      }),
+      "apps:desktop-check": () =>
+        (checks++ === 0 ? new Promise(() => undefined) : { ok: true }) as never,
+      "apps:desktop-cancel": () => undefined,
+    })
+    render(<App />)
+    fireEvent.click(await screen.findByRole("button", { name: /app\.test/ }))
+    const panel = screen.getByRole("dialog", { name: "Apps" })
+    fireEvent.click(within(panel).getByRole("button", { name: "Add desktop app…" }))
+    const slack = await within(panel).findByRole("region", { name: "Adding Slack" })
+    fireEvent.click(within(slack).getByRole("button", { name: "Check" }))
+    fireEvent.click(within(slack).getByRole("button", { name: "Cancel" }))
+    fireEvent.click(within(panel).getByRole("button", { name: "Add desktop app…" }))
+    const notion = await within(panel).findByRole("region", { name: "Adding Notion" })
+    fireEvent.click(within(notion).getByRole("button", { name: "Check" }))
+    expect(await within(notion).findByRole("button", { name: "Add Notion" })).toBeTruthy()
+  })
+})
diff --git a/apps/desktop/src/shared/channels.ts b/apps/desktop/src/shared/channels.ts
index 7235d04..5e0ac4a 100644
--- a/apps/desktop/src/shared/channels.ts
+++ b/apps/desktop/src/shared/channels.ts
@@ -18,6 +18,11 @@ export const INVOKE_CHANNELS = [
   "secrets:add",
   "secrets:remove",
   "apps:remove",
+  "apps:desktop-pick",
+  "apps:desktop-check",
+  "apps:desktop-add",
+  "apps:desktop-cancel",
+  "apps:desktop-status",
   "preview:open",
 ] as const
 
diff --git a/apps/desktop/src/shared/ipc.ts b/apps/desktop/src/shared/ipc.ts
index 83180a7..9f4d45a 100644
--- a/apps/desktop/src/shared/ipc.ts
+++ b/apps/desktop/src/shared/ipc.ts
@@ -300,6 +300,41 @@ export const LiveInput = z.discriminatedUnion("kind", [
 ])
 export type LiveInput = z.infer<typeof LiveInput>
 
+/** A desktop app picked: its card (never its path), or why it can't be added (null: cancelled). */
+export type DesktopPick =
+  | {
+      card: {
+        token: string
+        name: string
+        bundleId: string
+        version: string | undefined
+        electron: string
+        signer: { kind: "team"; team: string } | { kind: "pinned" }
+        /** The project names it already (a project from someone else): adding approves it here. */
+        existing: string | undefined
+        /** What that project opens with it (shown before it's allowed). */
+        opens: { args: string[]; origins: string[] } | undefined
+      }
+    }
+  | { refused: string }
+  | null
+
+/** A trial's outcome, as the card shows it (or why it couldn't run). */
+export type DesktopCheck = { ok: true } | { site: string } | { quit: true } | { failed: string }
+
+/** Each desktop app of the open project (by its name): its status on this Mac, and why. */
+export interface DesktopStatusView {
+  apps: Record<
+    string,
+    {
+      status: "ready" | "updated" | "allow" | "opens-changed" | "changed" | "not-found"
+      why?: string
+    }
+  >
+  /** The approvals file didn't read and was set aside (said once). */
+  problem: string | null
+}
+
 /** What the window needs to know to show the right screen. */
 export interface AppStatus {
   /** An OpenRouter key is in the keychain (its value never leaves main). */
@@ -395,6 +430,24 @@ export const invokeArgs = {
   "apps:remove": z.tuple([
     z.strictObject({ session: z.string().max(64), name: AppName, identity: z.string().max(2048) }),
   ]),
+  /**
+   * Adding a desktop app: main shows the picker (Applications) and inspects what was picked; the
+   * window gets a card and a token (never the app's path).
+   */
+  "apps:desktop-pick": z.tuple([z.strictObject({ session: z.string().max(64) })]),
+  /**
+   * The picked app tried, confined. `allowSite`: with the site its last trial named as its own
+   * (main kept it: the window never names a site).
+   */
+  "apps:desktop-check": z.tuple([
+    z.strictObject({ session: z.string().max(64), token: z.uuid(), allowSite: z.boolean() }),
+  ]),
+  /** The tried app added to the open project (or, named already, approved here). */
+  "apps:desktop-add": z.tuple([z.strictObject({ session: z.string().max(64), token: z.uuid() })]),
+  /** The add given up (its trial ended). */
+  "apps:desktop-cancel": z.tuple([]),
+  /** The open project's desktop apps as this Mac has them (static: nothing launches). */
+  "apps:desktop-status": z.tuple([z.strictObject({ session: z.string().max(64) })]),
   /** A scene of the open project, to play (its id, checked against the project in main). */
   "preview:open": z.tuple([z.string().min(1).max(200)]),
 } satisfies Record<(typeof INVOKE_CHANNELS)[number], z.ZodTuple>
@@ -423,6 +476,12 @@ export interface InvokeResults {
   "secrets:remove": string | null
   /** null when removed or cancelled; else why not, in words. */
   "apps:remove": string | null
+  "apps:desktop-pick": DesktopPick
+  "apps:desktop-check": DesktopCheck
+  /** null when added; else why not, in words. */
+  "apps:desktop-add": string | null
+  "apps:desktop-cancel": void
+  "apps:desktop-status": DesktopStatusView
   "preview:open": Preview
 }
 
diff --git a/apps/desktop/test/desktop-apps.test.ts b/apps/desktop/test/desktop-apps.test.ts
new file mode 100644
index 0000000..c209d1d
--- /dev/null
+++ b/apps/desktop/test/desktop-apps.test.ts
@@ -0,0 +1,617 @@
+import { chmodSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { createProject, openProject, saveProject } from "@kiframe/project"
+import type { DesktopApp, TrialOptions, TrialOutcome } from "@kiframe/runtime"
+import type { ElectronApp } from "@kiframe/schema"
+import { describe, expect, it } from "vitest"
+import { Workspace } from "../src/main/workspace.ts"
+import {
+  addHostOf,
+  type AddHost,
+  appNameFor,
+  DesktopAdds,
+  DesktopApprovals,
+  desktopStatus,
+  opensOf,
+} from "../src/main/desktop-apps.ts"
+
+// Desktop apps added and approved (PR 3b): main's store, status and add flow, with the runtime's
+// inspection and trial as fakes (nothing launches here; the runtime's own tests launch for real).
+
+const dir = () => mkdtempSync(join(tmpdir(), "kiframe-desktop-apps-"))
+const project = () =>
+  createProject(join(dir(), "demo.kiframe"), { id: "p1", name: "Demo", url: "https://app.test" })
+
+const notes = (over: Partial<DesktopApp> = {}): DesktopApp => ({
+  path: "/Applications/Notes.app",
+  bundleId: "com.example.Notes",
+  name: "Notes",
+  version: "1.0",
+  electron: "44.4.5",
+  executable: "/Applications/Notes.app/Contents/MacOS/Notes",
+  signer: { kind: "team", team: "TEAM123456", identifier: "com.example.Notes" },
+  ...over,
+})
+
+/** Fakes of the runtime's looks: what's at each path, what a trial says (recorded). */
+const looks = (
+  apps: Record<string, DesktopApp>,
+  outcome: (o: TrialOptions) => TrialOutcome = () => ({ ok: true }),
+) => {
+  const trials: TrialOptions[] = []
+  return {
+    trials,
+    looks: {
+      inspect: (path: string, _signal?: AbortSignal) => {
+        const app = apps[path]
+        return app === undefined
+          ? Promise.reject(new Error("that app can't be read (moved or removed?)"))
+          : Promise.resolve(app)
+      },
+      trial: (_app: DesktopApp, o: TrialOptions) => {
+        trials.push(o)
+        return Promise.resolve(outcome(o))
+      },
+    },
+  }
+}
+
+const entry = (over: Partial<ElectronApp> = {}): ElectronApp => ({
+  kind: "electron",
+  bundleId: "com.example.Notes",
+  viewport: { width: 1440, height: 900, deviceScaleFactor: 1 },
+  ...over,
+})
+
+describe("a desktop app's approvals", () => {
+  it("are kept per Mac and per project, with what the project opens", () => {
+    const data = dir()
+    const approvals = new DesktopApprovals(data)
+    approvals.approve(notes(), "folder-a", opensOf(entry()))
+    const again = new DesktopApprovals(data)
+    // With the build this project tried.
+    expect(again.copyFor("COM.EXAMPLE.NOTES", "folder-a")?.scopes).toEqual({
+      "folder-a": { opens: opensOf(entry()), version: "1.0" },
+    })
+    expect(readFileSync(join(data, "desktop-apps.json")).length).toBeGreaterThan(0)
+    again.drop("com.example.Notes", "folder-a")
+    expect(new DesktopApprovals(data).copies("com.example.Notes")).toEqual([])
+  })
+
+  it("keep other projects' approvals for the same app, drop them for another build there", () => {
+    const approvals = new DesktopApprovals(dir())
+    const scopes = () => approvals.copies("com.example.Notes").map((c) => Object.keys(c.scopes))
+    approvals.approve(notes(), "folder-a", "a".repeat(64))
+    // An update of the same developer's app: still theirs.
+    approvals.approve(notes({ version: "1.1" }), "folder-b", "b".repeat(64))
+    expect(scopes()).toEqual([["folder-a", "folder-b"]])
+    // Another developer at that place now: the others approved that one, not this.
+    approvals.approve(
+      notes({ signer: { kind: "team", team: "OTHER00000", identifier: "x" } }),
+      "folder-b",
+      "b".repeat(64),
+    )
+    expect(scopes()).toEqual([["folder-b"]])
+  })
+
+  it("keep each copy of an app apart (a release and a dev build of one id)", () => {
+    const approvals = new DesktopApprovals(dir())
+    const release = notes()
+    const dev = notes({
+      path: "/Users/me/dev/Notes.app",
+      signer: { kind: "pinned", digest: "c".repeat(64) },
+    })
+    approvals.approve(release, "folder-a", "a".repeat(64))
+    approvals.approve(dev, "folder-b", "b".repeat(64))
+    // Each project keeps its own copy (never taken from the other).
+    expect(approvals.copyFor("com.example.Notes", "folder-a")?.path).toBe(release.path)
+    expect(approvals.copyFor("com.example.Notes", "folder-b")?.path).toBe(dev.path)
+    // A project switching copies lets the other go.
+    approvals.approve(dev, "folder-a", "a".repeat(64))
+    expect(approvals.copies("com.example.Notes").map((c) => c.path)).toEqual([dev.path])
+  })
+
+  it("always read back (copies capped, long names cut): never set aside for what they wrote", () => {
+    const data = dir()
+    const approvals = new DesktopApprovals(data)
+    for (let i = 0; i < 25; i++) {
+      approvals.approve(
+        notes({
+          path: `/Users/me/dev/w${i}/Notes.app`,
+          name: "N".repeat(300),
+          version: "9".repeat(150),
+        }),
+        `folder-${i}`,
+        opensOf(entry()),
+      )
+    }
+    const again = new DesktopApprovals(data)
+    expect(again.takeProblem()).toBeNull()
+    expect(again.copies("com.example.Notes")).toHaveLength(20)
+    expect(again.copyFor("com.example.Notes", "folder-24")?.name).toHaveLength(200)
+    // A long version compares as it was kept (never "updated" for being long).
+    const team = notes({ path: "/Users/me/dev/w24/Notes.app", version: "9".repeat(150) })
+    return desktopStatus(entry(), "folder-24", again, looks({ [team.path]: team }).looks).then(
+      (status) => expect(status).toEqual({ status: "ready" }),
+    )
+  })
+
+  it("change nothing when a write fails (memory as on disk)", () => {
+    const data = dir()
+    const approvals = new DesktopApprovals(data)
+    approvals.approve(notes(), "folder-a", "a".repeat(64))
+    chmodSync(data, 0o500)
+    try {
+      expect(() => approvals.approve(notes(), "folder-b", "b".repeat(64))).toThrow()
+      expect(approvals.copyFor("com.example.Notes", "folder-b")).toBeUndefined()
+    } finally {
+      chmodSync(data, 0o700)
+    }
+  })
+
+  it("set a file that doesn't read aside, never overwrite it", () => {
+    const data = dir()
+    writeFileSync(join(data, "desktop-apps.json"), "{ not json")
+    const approvals = new DesktopApprovals(data)
+    expect(approvals.takeProblem()).toMatch(/set aside as .*desktop-apps\.json\.bad-\d+/)
+    expect(readdirSync(data).some((n) => n.startsWith("desktop-apps.json.bad-"))).toBe(true)
+    approvals.approve(notes(), "folder-a", "a".repeat(64))
+    const aside = readdirSync(data).find((n) => n.startsWith("desktop-apps.json.bad-"))
+    expect(readFileSync(join(data, aside ?? ""), "utf8")).toBe("{ not json")
+  })
+})
+
+describe("a desktop app's status (static: nothing launches)", () => {
+  const status = async (
+    at: Record<string, DesktopApp>,
+    approve: ((a: DesktopApprovals) => void) | undefined,
+    app = entry(),
+  ) => {
+    const approvals = new DesktopApprovals(dir())
+    approve?.(approvals)
+    return desktopStatus(app, "folder-a", approvals, looks(at).looks)
+  }
+  const approved = (a: DesktopApprovals) => a.approve(notes(), "folder-a", opensOf(entry()))
+
+  it("is ready when approved here for what it opens, updated when its developer shipped a new build", async () => {
+    expect(await status({ "/Applications/Notes.app": notes() }, approved)).toEqual({
+      status: "ready",
+    })
+    expect(
+      await status({ "/Applications/Notes.app": notes({ version: "2.0" }) }, approved),
+    ).toEqual({
+      status: "updated",
+    })
+  })
+
+  it("asks again: never added here, another project's, what it opens changed", async () => {
+    const at = { "/Applications/Notes.app": notes() }
+    expect((await status(at, undefined)).status).toBe("allow")
+    expect((await status(at, (a) => a.approve(notes(), "folder-b", opensOf(entry())))).status).toBe(
+      "allow",
+    )
+    // A pull added a site the project shows as the app's own (or an argument): asked again.
+    const opens = entry({ origins: ["https://evil.example"] })
+    expect((await status(at, approved, opens)).status).toBe("opens-changed")
+  })
+
+  it("keeps each project's tried build: another's approval of an update changes nothing here", async () => {
+    const approvals = new DesktopApprovals(dir())
+    approvals.approve(notes(), "folder-b", opensOf(entry()))
+    const updated = { "/Applications/Notes.app": notes({ version: "1.1" }) }
+    expect(await desktopStatus(entry(), "folder-b", approvals, looks(updated).looks)).toEqual({
+      status: "updated",
+    })
+    // Project A tries and approves 1.1: B still hasn't tried it.
+    approvals.approve(notes({ version: "1.1" }), "folder-a", opensOf(entry()))
+    expect(await desktopStatus(entry(), "folder-b", approvals, looks(updated).looks)).toEqual({
+      status: "updated",
+    })
+    expect(await desktopStatus(entry(), "folder-a", approvals, looks(updated).looks)).toEqual({
+      status: "ready",
+    })
+  })
+
+  it("never looks at the app to say what needs no look (another project's, opens changed)", async () => {
+    const approvals = new DesktopApprovals(dir())
+    approvals.approve(notes(), "folder-b", opensOf(entry()))
+    const never = {
+      inspect: () => Promise.reject(new Error("looked at the app")),
+    }
+    expect((await desktopStatus(entry(), "folder-a", approvals, never)).status).toBe("allow")
+    approvals.approve(notes(), "folder-a", opensOf(entry()))
+    const opens = entry({ origins: ["https://evil.example"] })
+    expect((await desktopStatus(opens, "folder-a", approvals, never)).status).toBe("opens-changed")
+  })
+
+  it("is changed for another developer or another unsigned build, not found when gone", async () => {
+    const other = notes({
+      signer: { kind: "team", team: "OTHER00000", identifier: "com.example.Notes" },
+    })
+    expect((await status({ "/Applications/Notes.app": other }, approved)).status).toBe("changed")
+    const pinned = notes({ signer: { kind: "pinned", digest: "a".repeat(64) } })
+    const rebuilt = notes({ signer: { kind: "pinned", digest: "b".repeat(64) } })
+    const approvePinned = (a: DesktopApprovals) => a.approve(pinned, "folder-a", opensOf(entry()))
+    expect((await status({ "/Applications/Notes.app": pinned }, approvePinned)).status).toBe(
+      "ready",
+    )
+    expect((await status({ "/Applications/Notes.app": rebuilt }, approvePinned)).status).toBe(
+      "changed",
+    )
+    expect((await status({}, approved)).status).toBe("not-found")
+  })
+})
+
+/** A deferred answer (a wait the test lets go of when it wants). */
+function deferred<T>() {
+  let resolve: (value: T) => void = () => undefined
+  const promise = new Promise<T>((r) => (resolve = r))
+  return { promise, resolve }
+}
+
+/**
+ * The add flow with a fake host: the open project, its session, Kif's state and the picker driven
+ * by the test; what's approved and told recorded.
+ */
+function harness(
+  opened = project(),
+  at: Record<string, DesktopApp> = { "/Applications/Notes.app": notes() },
+  outcome: (o: TrialOptions) => TrialOutcome = () => ({ ok: true }),
+) {
+  const state = {
+    session: "s1" as string | undefined,
+    opened: opened as ReturnType<typeof project> | null,
+    busy: undefined as string | undefined,
+    picked: "/Applications/Notes.app" as string | undefined,
+    approved: [] as string[],
+    changed: 0,
+  }
+  const fake = looks(at, outcome)
+  const approvals = new DesktopApprovals(dir())
+  const host: AddHost = {
+    session: () => state.session,
+    opened: () => state.opened,
+    busy: () => state.busy,
+    pickApp: () => Promise.resolve(state.picked),
+    approve: (app, o, opens) => {
+      approvals.approve(app, "folder-a", opens)
+      state.approved.push(app.bundleId)
+      void o
+    },
+    changed: () => (state.changed += 1),
+  }
+  const adds = new DesktopAdds(fake.looks, host)
+  const pick = async () => {
+    const card = await adds.pick(1, "s1")
+    if (card === null) throw new Error("no card")
+    return card
+  }
+  return { adds, state, host, fake, approvals, opened, pick }
+}
+
+describe("adding a desktop app", () => {
+  it("adds it once it ran confined: named, written to the project, approved here", async () => {
+    const h = harness()
+    const card = await h.pick()
+    expect(card).toMatchObject({
+      name: "Notes",
+      bundleId: "com.example.Notes",
+      signer: { kind: "team", team: "TEAM123456" },
+    })
+    expect(JSON.stringify(card)).not.toContain("/Applications")
+    await expect(h.adds.add(1, "s1", card.token)).rejects.toThrow(/check it first/)
+    expect(await h.adds.check(1, "s1", card.token, false)).toEqual({ ok: true })
+    expect(await h.adds.add(1, "s1", card.token)).toBe("notes")
+    expect(openProject(h.opened.dir).project.apps["notes"]).toMatchObject({
+      kind: "electron",
+      bundleId: "com.example.Notes",
+    })
+    expect(h.state.changed).toBe(1)
+    expect(
+      await desktopStatus(
+        h.opened.project.apps["notes"] as ElectronApp,
+        "folder-a",
+        h.approvals,
+        h.fake.looks,
+      ),
+    ).toEqual({ status: "ready" })
+  })
+
+  it("allows a wrapper's site only as the trial named it, tried before it's added", async () => {
+    const h = harness(project(), undefined, (o) =>
+      (o.origins ?? []).length > 0 ? { ok: true } : { site: "https://app.slack.com" },
+    )
+    const card = await h.pick()
+    await expect(h.adds.check(1, "s1", card.token, true)).rejects.toThrow(/no site to allow/)
+    expect(await h.adds.check(1, "s1", card.token, false)).toEqual({
+      site: "https://app.slack.com",
+    })
+    expect(await h.adds.check(1, "s1", card.token, true)).toEqual({ ok: true })
+    expect(h.fake.trials.at(-1)?.origins).toEqual(["https://app.slack.com"])
+    await h.adds.add(1, "s1", card.token)
+    expect(openProject(h.opened.dir).project.apps["notes"]).toMatchObject({
+      origins: ["https://app.slack.com"],
+    })
+  })
+
+  it("never adds while a check runs (a site allowed but not tried yet)", async () => {
+    const trial = deferred<TrialOutcome>()
+    let first = true
+    const h = harness()
+    h.fake.looks.trial = (_app, o) => {
+      h.fake.trials.push(o)
+      if (first) {
+        first = false
+        return Promise.resolve({ site: "https://app.slack.com" })
+      }
+      return trial.promise
+    }
+    const card = await h.pick()
+    await h.adds.check(1, "s1", card.token, false)
+    const checking = h.adds.check(1, "s1", card.token, true)
+    await expect(h.adds.add(1, "s1", card.token)).rejects.toThrow(/being checked/)
+    trial.resolve({ ok: true })
+    await checking
+    expect(await h.adds.add(1, "s1", card.token)).toBe("notes")
+  })
+
+  it("refuses a token of another window or project, and a build changed since its trial", async () => {
+    const h = harness()
+    const card = await h.pick()
+    await expect(h.adds.check(2, "s1", card.token, false)).rejects.toThrow(
+      /isn't being added any more/,
+    )
+    await expect(h.adds.check(1, "s2", card.token, false)).rejects.toThrow(
+      /isn't being added any more/,
+    )
+    await h.adds.check(1, "s1", card.token, false)
+    h.fake.looks.inspect = () =>
+      Promise.resolve(notes({ signer: { kind: "team", team: "OTHER00000", identifier: "x" } }))
+    await expect(h.adds.add(1, "s1", card.token)).rejects.toThrow(/changed since it was checked/)
+  })
+
+  it("says a file changed on disk as itself, and a site the project can't take in words", async () => {
+    const h = harness()
+    const card = await h.pick()
+    await h.adds.check(1, "s1", card.token, false)
+    writeFileSync(
+      join(h.opened.dir, "project.json"),
+      readFileSync(join(h.opened.dir, "project.json"), "utf8") + " ",
+    )
+    await expect(h.adds.add(1, "s1", card.token)).rejects.toThrow(/changed on disk.*reopen it/)
+    // The site is a web app's of the project already (one app per site).
+    const opened = project()
+    saveProject(opened, { ...opened.project, apps: { ...opened.project.apps, desk: entry() } })
+    const g = harness(opened, undefined, (o) =>
+      (o.origins ?? []).length > 0 ? { ok: true } : { site: "https://app.test" },
+    )
+    const named = await g.pick()
+    await g.adds.check(1, "s1", named.token, false)
+    await g.adds.check(1, "s1", named.token, true)
+    const error = await g.adds.add(1, "s1", named.token).then(
+      () => "",
+      (e: unknown) => (e as Error).message,
+    )
+    expect(error).toMatch(/^the project can't take it so/)
+    expect(error).not.toMatch(/"code"|\[\{/)
+  })
+
+  it("approves the build that was tried (one updated since: updated, never ready)", async () => {
+    const h = harness()
+    const card = await h.pick()
+    await h.adds.check(1, "s1", card.token, false)
+    // The developer's update lands between the check and the add.
+    h.fake.looks.inspect = () => Promise.resolve(notes({ version: "2.0" }))
+    await h.adds.add(1, "s1", card.token)
+    const desk = openProject(h.opened.dir).project.apps["notes"] as ElectronApp
+    expect(await desktopStatus(desk, "folder-a", h.approvals, h.fake.looks)).toEqual({
+      status: "updated",
+    })
+  })
+
+  it("stops looking at an app picked then given up", async () => {
+    const h = harness()
+    let signal: AbortSignal | undefined
+    h.fake.looks.inspect = (_path, s) => {
+      signal = s
+      return new Promise<DesktopApp>((_, reject) =>
+        s?.addEventListener("abort", () => reject(s.reason as Error)),
+      )
+    }
+    const picking = h.adds.pick(1, "s1")
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    h.adds.dropFor(1)
+    expect(await picking).toBeNull()
+    expect(signal?.aborted).toBe(true)
+  })
+
+  it("stops looking at the app again when its add is given up", async () => {
+    const h = harness()
+    const card = await h.pick()
+    await h.adds.check(1, "s1", card.token, false)
+    let signal: AbortSignal | undefined
+    h.fake.looks.inspect = (_path, s) => {
+      signal = s
+      return new Promise<DesktopApp>((_, reject) =>
+        s?.addEventListener("abort", () => reject(s.reason as Error)),
+      )
+    }
+    const adding = h.adds.add(1, "s1", card.token)
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    h.adds.dropFor(1)
+    await expect(adding).rejects.toThrow(/isn't being added any more/)
+    expect(signal?.aborted).toBe(true)
+  })
+
+  it("is done once written: an approval that fails then is said, never added twice", async () => {
+    const h = harness()
+    h.host.approve = () => {
+      throw new Error("EACCES")
+    }
+    const card = await h.pick()
+    await h.adds.check(1, "s1", card.token, false)
+    await expect(h.adds.add(1, "s1", card.token)).rejects.toThrow(
+      /added as notes, but not approved on this Mac/,
+    )
+    await expect(h.adds.add(1, "s1", card.token)).rejects.toThrow(/isn't being added any more/)
+    expect(Object.keys(openProject(h.opened.dir).project.apps)).toEqual(["app", "notes"])
+  })
+})
+
+describe("an app's name in the project", () => {
+  it("is its own name in the app-name form, made unique; nothing left: app", () => {
+    expect(appNameFor("Visual Studio Code", [])).toBe("visual-studio-code")
+    expect(appNameFor("Slack", ["slack"])).toBe("slack-2")
+    expect(appNameFor("微信", [])).toBe("app")
+    expect(appNameFor("1Password", [])).toBe("password")
+  })
+})
+
+describe("adding an app a project already names", () => {
+  const named = () => {
+    const opened = project()
+    saveProject(opened, {
+      ...opened.project,
+      apps: {
+        ...opened.project.apps,
+        desk: entry({ args: ["files/vault"], origins: ["https://a.example"] }),
+      },
+    })
+    return opened
+  }
+
+  it("shows what it opens, tries it with its sites, and approves it without adding it twice", async () => {
+    const h = harness(named())
+    const card = await h.pick()
+    expect(card.existing).toBe("desk")
+    expect(card.opens).toEqual({ args: ["files/vault"], origins: ["https://a.example"] })
+    await h.adds.check(1, "s1", card.token, false)
+    expect(h.fake.trials[0]?.origins).toEqual(["https://a.example"])
+    expect(await h.adds.add(1, "s1", card.token)).toBe("desk")
+    expect(Object.keys(openProject(h.opened.dir).project.apps)).toEqual(["app", "desk"])
+    expect(h.approvals.copyFor("com.example.Notes", "folder-a")?.scopes["folder-a"]?.opens).toBe(
+      opensOf(entry({ args: ["files/vault"], origins: ["https://a.example"] })),
+    )
+  })
+
+  it("never approves a project changed since the pick", async () => {
+    const h = harness(named())
+    const card = await h.pick()
+    await h.adds.check(1, "s1", card.token, false)
+    const desk = h.opened.project.apps["desk"] as ElectronApp
+    saveProject(h.opened, {
+      ...h.opened.project,
+      apps: {
+        ...h.opened.project.apps,
+        desk: { ...desk, origins: ["https://a.example", "https://evil.example"] },
+      },
+    })
+    await expect(h.adds.add(1, "s1", card.token)).rejects.toThrow(/the project changed meanwhile/)
+  })
+
+  it("writes a site allowed in its check to the project, and approves that", async () => {
+    const opened = project()
+    saveProject(opened, { ...opened.project, apps: { ...opened.project.apps, desk: entry() } })
+    const h = harness(opened, undefined, (o) =>
+      (o.origins ?? []).length > 0 ? { ok: true } : { site: "https://app.slack.com" },
+    )
+    const card = await h.pick()
+    await h.adds.check(1, "s1", card.token, false)
+    await h.adds.check(1, "s1", card.token, true)
+    expect(await h.adds.add(1, "s1", card.token)).toBe("desk")
+    const desk = openProject(opened.dir).project.apps["desk"] as ElectronApp
+    expect(desk.origins).toEqual(["https://app.slack.com"])
+    expect(await desktopStatus(desk, "folder-a", h.approvals, h.fake.looks)).toEqual({
+      status: "ready",
+    })
+  })
+})
+
+describe("an add's lifetime: its project's, checked after every wait", () => {
+  it("drops a pick whose project changed or that was cancelled while the user picked", async () => {
+    const h = harness()
+    const dialog = deferred<string | undefined>()
+    h.host.pickApp = () => dialog.promise
+    const picking = h.adds.pick(1, "s1")
+    await expect(h.adds.pick(1, "s1")).rejects.toThrow(/being picked already/)
+    h.adds.dropFor(1)
+    dialog.resolve("/Applications/Notes.app")
+    expect(await picking).toBeNull()
+    // And the next pick works (nothing left stuck).
+    h.host.pickApp = () => Promise.resolve("/Applications/Notes.app")
+    expect(await h.adds.pick(1, "s1")).not.toBeNull()
+    // A project switch while the app is looked at: no card.
+    const inspecting = deferred<DesktopApp>()
+    h.fake.looks.inspect = () => inspecting.promise
+    const later = h.adds.pick(1, "s1")
+    h.state.session = "s2"
+    inspecting.resolve(notes())
+    expect(await later).toBeNull()
+  })
+
+  it("never writes an add given up, or Kif started, while the app was looked at again", async () => {
+    for (const giveUp of ["switch", "cancel", "busy"] as const) {
+      const h = harness()
+      const card = await h.pick()
+      await h.adds.check(1, "s1", card.token, false)
+      const inspecting = deferred<DesktopApp>()
+      h.fake.looks.inspect = () => inspecting.promise
+      const adding = h.adds.add(1, "s1", card.token)
+      if (giveUp === "switch") h.state.session = "s2"
+      if (giveUp === "cancel") h.adds.dropFor(1)
+      if (giveUp === "busy") h.state.busy = "Kif is working: stop it first"
+      inspecting.resolve(notes())
+      await expect(adding, giveUp).rejects.toThrow(
+        giveUp === "busy" ? /Kif is working/ : /isn't being added any more/,
+      )
+      expect(openProject(h.opened.dir).project.apps["notes"], giveUp).toBeUndefined()
+      expect(h.state.approved, giveUp).toEqual([])
+    }
+  })
+
+  it("reads the project after the pick (an app removed meanwhile is no longer 'named')", async () => {
+    const opened = project()
+    saveProject(opened, { ...opened.project, apps: { ...opened.project.apps, desk: entry() } })
+    const h = harness(opened)
+    const dialog = deferred<string | undefined>()
+    h.host.pickApp = () => dialog.promise
+    const picking = h.adds.pick(1, "s1")
+    const { desk: _desk, ...rest } = opened.project.apps
+    void _desk
+    saveProject(opened, { ...opened.project, apps: rest })
+    dialog.resolve("/Applications/Notes.app")
+    expect((await picking)?.existing).toBeUndefined()
+  })
+
+  it("ends every add and its trial as the workspace switches project", async () => {
+    const workspace = new Workspace(() => ({ close: () => Promise.resolve(), running: false }))
+    await workspace.open(project().dir)
+    let signal: AbortSignal | undefined
+    const host = addHostOf(workspace, {
+      pickApp: () => Promise.resolve("/Applications/Notes.app"),
+      approve: () => undefined,
+      changed: () => undefined,
+    })
+    const adds: DesktopAdds = new DesktopAdds(
+      {
+        inspect: () => Promise.resolve(notes()),
+        trial: (_app, o) => {
+          signal = o.signal
+          return new Promise<TrialOutcome>((_, reject) =>
+            o.signal?.addEventListener("abort", () => reject(o.signal?.reason as Error)),
+          )
+        },
+      },
+      host,
+    )
+    workspace.onSwitch(() => adds.dropAll())
+    const session = workspace.session ?? ""
+    const card = await adds.pick(1, session)
+    const checking = adds.check(1, session, card?.token ?? "", false)
+    await workspace.close()
+    await expect(checking).rejects.toMatchObject({ name: "AbortError" })
+    expect(signal?.aborted).toBe(true)
+    expect(workspace.session).toBeUndefined()
+  })
+})
diff --git a/apps/desktop/test/workspace.test.ts b/apps/desktop/test/workspace.test.ts
index 97536d8..e370357 100644
--- a/apps/desktop/test/workspace.test.ts
+++ b/apps/desktop/test/workspace.test.ts
@@ -179,3 +179,23 @@ describe("the open project and its agent", () => {
     expect(ws.agent).toBe(made[2])
   })
 })
+
+describe("a project switch", () => {
+  it("tells its listeners on open, create and close (one that throws stops nothing)", async () => {
+    const workspace = new Workspace(() => ({ close: () => Promise.resolve() }))
+    let told = 0
+    workspace.onSwitch(() => {
+      throw new Error("a listener that fails")
+    })
+    workspace.onSwitch(() => (told += 1))
+    const dir = folder()
+    createProject(dir, { id: "p1", name: "Demo", url: "https://app.test" })
+    await workspace.open(dir)
+    expect(workspace.session).toMatch(/^[0-9a-f]{12}$/)
+    await workspace.create(folder(), { name: "New", url: "https://new.test" })
+    await workspace.close()
+    expect(told).toBe(3)
+    // No project: no session.
+    expect(workspace.session).toBeUndefined()
+  })
+})
diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md
index 50ff9f0..6766caa 100644
--- a/docs/BACKLOG.md
+++ b/docs/BACKLOG.md
@@ -247,6 +247,7 @@ Non-severe review findings deferred on purpose (see the review-round rule: only
 - **What a confined app opens through LaunchServices:** an app can't start without `launchservicesd`, and through it it can open a file or a URL that then runs unconfined (a script it wrote, the user's browser). Stated in §0.9 (accident, not a hostile app); an Endpoint Security watcher or a per-run user account would close it.
 - **Desktop-app sweeps read processes more than once:** the startup sweep runs one `ps` per leftover sandbox (one `ps -axo pid=,lstart=` table would answer every owner), and a run's close reads the process table twice (`orphanedGroup` and `sweepProcesses`). Startup and close time only (#58 review).
 - **Clicks in a desktop app under its own DevTools (macOS runner):** with DevTools opened mid-run over a hidden test window, a click waited for the button to be stable until its timeout on GitHub's macOS runner (animation frames throttled: the window covered); locally it clicks. The DevTools test reads instead of clicking; check clicks with DevTools open on a real app in PR 5.
+- **A desktop app's check while Kif starts:** the Apps panel refuses a check while Kif works, but Kif starting during a check (10–40 s) doesn't end it: the confined app runs beside Kif's run, its result refused after. End the check when a run starts (the agent's start hook).
 - **One launch helper:** browsers are launched by each entry point; nothing enforces an off-the-record context. A runtime-owned `launchBrowser()` / context factory would make it hard to bypass (the desktop app's main process).
 - **Secrets into contenteditable:** v0 writes secrets to inputs and textareas only (the value set on the approved element); a rich-text field is refused.
 - **Network exfiltration by the page itself:** a hostile page receives the typed password in its own field and can send it anywhere; that's the target app's own data. Out of scope for the vault (it only guarantees the value goes to the bound field on the allowed origins).
diff --git a/docs/OBJECT-MODEL.md b/docs/OBJECT-MODEL.md
index 08b6b0e..b6e91c9 100644
--- a/docs/OBJECT-MODEL.md
+++ b/docs/OBJECT-MODEL.md
@@ -231,6 +231,7 @@ One scene, three phases. The agent's own instructions say the same (`packages/st
 - **Windows (PR 2, known limits, to settle on real apps in PR 3 and PR 5: decided by the user 2026-10-08):** the main window is the last opened still open once the app's windows were unchanged for 1.5 s (a splash that stays up longer is taken for the main window); windows the app's main process opens are followed as popups are (a hidden helper window opened during a step may be followed: CDP can't tell it's hidden); only the launch window is sent back when it goes off-app (another window is closed); a stop that lands after its step ended counts against the next step. A window that opens blank gets a moment to load (as a web page does); a frame of a window the run isn't driving is said, never the step's failure.
 - **Every launch confined (PR 3a, 2026-10-09, design reviewed twice, measured):** on macOS each launch runs under Seatbelt (`sandbox-exec`, `electron-confine.ts`): writes only into its own sandbox; no reads of /Users, /Volumes, the temp folders, the user's home and the work area wherever they are (a home outside /Users) but its sandbox and its bundle; nothing run from its sandbox (the one place it writes: a program it drops there, a copied launcher), no `open`, `osascript`, `launchctl` nor Apple Events; no unix sockets (an agent's: ssh, Docker) but mDNSResponder; no preferences (cfprefsd), keychain (SecurityServer: a mock keychain instead, `--use-mock-keychain`) nor clipboard (the user's may hold a password just copied: an app's own copy and paste doesn't work in a run); the network on, for runs and trials alike (the app's backend, a wrapper's site: an updater can't touch the real app, nothing outside the sandbox being written; what an app could send is only what it can read here: its bundle, the system's files, its own sandbox). Chromium's own sandbox can't nest in it (`--no-sandbox`): the guard and this profile replace it. A canary before every launch, before the files are copied (a read the profile refuses must fail, one of its sandbox succeed: a confinement that runs nothing never passes); no `sandbox-exec`, or a canary failed: no launch (never unconfined). Off macOS: desktop apps don't launch (CI's tests only, unconfined). Measured with a probe app: every escape above `EPERM` (a hard link or a symlink to an outside file too), the app driven as usual. This replaces the trial's after-the-fact isolation check, rejected by review (an app that leaks does its harm as it starts). **What it doesn't stop (stated):** an app can still ask macOS to open a file or a URL (LaunchServices: no app starts without reaching it, measured), and what opens runs outside the confinement; it reaches services on this machine (localhost: a dev build's own server needs it). The app's own pages are its bundle and what it writes in its sandbox's home, profile and temp folders (a page it builds there from remote content counts as its own, as its cache already does); never the files/ copy. The confinement keeps an app from the user's data by accident (the minmux incident), not an app built to escape (one the user runs unconfined every day anyway).
 - **Adding a desktop app (PR 3b, design reviewed 2026-10-09):** inspected first, statically (`electron-inspect.ts`: only `plutil` and `codesign` run): refused outside where an app can stay (a disk image, a temporary translocated copy, the Trash, inside another app), not Electron (its framework; no version gate: Figma reports 13.6.1), an executable that isn't its own file, a Mac App Store build (App Sandbox), a developer signature that doesn't hold (`codesign --verify --strict` against its team and signed identifier). Kept: its id, name, Electron's version, and its signer: a developer (team id) or, ad hoc and unsigned (the user's own builds), pinned to a digest of the whole bundle (a link leading outside it refused; at most 4 GB and 200,000 entries). Then **tried confined** (`electron-trial.ts`): launched with the network as in a run (an updater can't touch the real app: nothing outside the sandbox is written; a wrapper's offline page can't hide its site), its main window attached, closed; a wrapper's site is named (even unreached: the error page's unreachable URL, over CDP) and allowed by the user in a second trial. A main window that never loaded its own page (offline, a dev server not running) is refused at launch, said as such: never a window driven on Chromium's error page. An attach that hangs as the first page fails (measured 1 in 5; cause not found) is tried again within the launch's time (stated). A trial runs only the build that was picked (its developer's signature, or its pinned digest, checked first; a change between that check and the launch is the user's own build tool's: holding every launch to its approval is PR 4's, with runs). codesign that fails or times out refuses the app (never read as unsigned or unsandboxed). Apps that allow one copy (Slack, VS Code, Discord) need Chromium's temp folder in the sandbox (`MAC_CHROMIUM_TMPDIR`): its lock's socket otherwise goes to the user's /var/folders, denied, and the app quits.
+- **Approvals (PR 3b-2, user decisions 2026-10-09):** added from the Apps panel ("Add desktop app…", macOS): main shows the picker (Applications) and inspects what was picked; the window gets a card and a token, never the app's path, and never names a site to allow (the trial's, kept in main). Tried confined, then added (the build that was tried is approved: one updated since says "updated"; `project.json`, its changed-on-disk refusal) and approved in app data (`desktop-apps.json`, 0600, written whole; one that doesn't read is set aside and said, never overwritten). An approval is per copy of the app on this Mac (where it was picked: a release and a dev build of one bundle id kept apart, a project using one of them; at most 20 copies of one app kept, the oldest let go) and per project folder (the registry's scope) and covers the app (its developer's team, or the exact build of an unsigned one) **and what the project opens with it** (its `args` and `origins`, as a digest): a pull that changes either asks again. Statuses (static, opening the panel launches nothing): ready; updated (same developer, a build this project hasn't tried: tried confined before its next run, PR 4, which records it); allow (approved for another project, or never on this Mac: pick it to allow it here, without adding it twice); opens-changed; changed (another developer, another unsigned build); not found. Removing the app drops this project's approval. Off macOS: nothing offered. A trial in progress ends with its add (another pick, the project closed, a quit); what a crash left is swept at the start.
 - **The work area `~/.kiframe/`** (decided by the user 2026-10-09: deletable any time): `sandboxes/` (one per launch, 0700, never a link), each named after the Kiframe that made it (`kiframe-app-<pid>-<start>-…`: owned from the moment it exists, no shared state file to race on); a crash sweep at start removes only sandboxes no running Kiframe owns (the processes pointing at them killed first), never another build's launch, and nothing when `ps` can't be read. Kept out of Time Machine and Spotlight. Approvals stay in the app's settings, takes in app data.
 - **A project's `files/`** (decided by the user 2026-10-09): what a desktop app opens. Copied into the sandbox at each launch by Kiframe's own walk (folders and regular files only: a link, a FIFO, a device refused; 500 MB, 20,000 files, depth 32; cloned where the disk can, times kept); `args` name paths in it only (`files/vault`, given as the copy's path); the app's edits stay in the copy (thrown away: every run from the same files). The copy is the project's content, never the app's own pages for the guard. Filled by the user in v0: the agent's file tools never reach `files/` (it may hold what runs inside the app: an editor's tasks, a vault's plugins).
 - **Measured on a fixture app (PR 2, 2026-10-08):** HOME, XDG and `--user-data-dir` hold; macOS's own places don't move: Electron's `appData` (`~/Library/Application Support`) and the app's preferences (`NSUserDefaults`, written by `cfprefsd` into the user's real `~/Library/Preferences/<bundle id>.plist`) stay the user's whatever `HOME` or `CFFIXED_USER_HOME` say. Hence the confinement (PR 3a, below): the preferences daemon is denied and writes outside the sandbox refused, so neither can be reached (a check after launch, the earlier plan, came too late).

From 0dcb640b04439b67f6ae9ecc1ad405542ee78410 Mon Sep 17 00:00:00 2001
From: Quang Lee <winlp4ever@gmail.com>
Date: Sat, 10 Oct 2026 14:35:12 +0200
Subject: [PATCH 07/10] feat(desktop): launch a project's desktop app only from
 its approval (#61)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(desktop): launch a project's desktop app only from its approval

The launch main gives the agent (PR 4a, design reviewed): the app's copy
approved for this project and what it opens, inspected once by its status.
An update by the same developer is tried confined first, quietly (one
trial per app and project), and that build approved compare-and-set (the
same copy, developer and opens, the project still open). Anything else is
refused for the user to settle in the Apps panel, never for the agent to
retry.

- a take of a desktop app keeps its build and what it opened (appBuild:
  shown, never in its key, never a reason to record again)
- Kif starting ends an "Add desktop app…" check in progress
- BACKLOG: #60's CI flakes; what an approval doesn't cover (files/)

* fix(desktop): launch only the build that was tried, and only while approved

- a launch re-reads the approval and the project after looking at the app:
  one removed or switched meanwhile is never launched
- one quiet trial per build: an update landing during a trial is never
  launched untried; a stopped launch stops only its own wait
- a quiet trial that didn't work says why (a site, a quit, a failure); an
  approval that can't be written is refused for the user
- Kif starting ends checks in progress only (picked cards kept); a
  launch's stop reaches its look at the app; the take's build shape from
  its schema; status tests assert the app they return

* fix(desktop): one quiet trial per app, ended with the launcher, status asked again

- one quiet trial per app and project (launches meanwhile wait); after it
  a launch asks the app's status again and must find the build just
  approved (an update, a move, a replacement meanwhile: refused)
- the quiet trial ends with the launcher (stopAll: a project switch, a
  quit), never with one launch's stop; a launch already stopped starts none
- the trial approves against the launch's own project; a launch checks the
  approved build is the one it starts
- an add's check ended by Kif starting or a switch is said in words

* refactor(desktop): each launch tries its own update, stopped with it

Simplified after a third review round on the shared quiet trial: each
launch of an updated app tries it itself (stopped by its own stop, or by
the launcher's as it was when the launch began: a project switch, a quit
refused in words), then approves compare-and-set (two launches that both
tried it approve the same build). No trial shared, kept, or joined.

- an add's check ended (Kif started, given up) always said in words
- a folder in files/ gone mid-copy said as a change; the slow-copy tests
  budget the app's start on the slower of two

* test(runtime): accept an interrupt handled before the first step that met it

On a busy CI runner the page loads slower than the late dialog's 300 ms,
so the dialog is up as the steps begin and is handled before "wait"
instead of "go" (seen twice). Handled once, off camera, before the click
it would block, either way: the click works.

* test(runtime): close the interrupt test again

The previous commit's edit dropped the test's closing brace (lint and format failed in CI).

* test: run the desktop-app suite's files one after another

Since #59 the electron project holds two files and they ran in parallel:
Electron launched while the other file cloned and re-signed it (spawn
ETXTBSY on Linux for the first tests, a splash slower than its wait on
macOS, both in #61's CI). The suite was meant to run alone: its files now
do too.
---
 apps/desktop/src/main/desktop-apps.ts    |  36 ++-
 apps/desktop/src/main/desktop-launch.ts  | 182 ++++++++++++
 apps/desktop/src/main/index.ts           |  15 +-
 apps/desktop/test/desktop-apps.test.ts   |  77 +++--
 apps/desktop/test/desktop-launch.test.ts | 347 +++++++++++++++++++++++
 docs/BACKLOG.md                          |   3 +-
 docs/OBJECT-MODEL.md                     |   1 +
 packages/runtime/src/electron-confine.ts |   7 +-
 packages/runtime/src/recorder.ts         |   3 +
 packages/runtime/test/electron.test.ts   |  24 +-
 packages/runtime/test/runner.test.ts     |   8 +-
 packages/schema/src/take.ts              |  11 +
 vitest.config.ts                         |   9 +-
 13 files changed, 681 insertions(+), 42 deletions(-)
 create mode 100644 apps/desktop/src/main/desktop-launch.ts
 create mode 100644 apps/desktop/test/desktop-launch.test.ts

diff --git a/apps/desktop/src/main/desktop-apps.ts b/apps/desktop/src/main/desktop-apps.ts
index d8a9765..1fdae5b 100644
--- a/apps/desktop/src/main/desktop-apps.ts
+++ b/apps/desktop/src/main/desktop-apps.ts
@@ -45,7 +45,7 @@ type Approval = z.infer<typeof Approval>
 const MAX_COPIES = 20
 
 /** A version as kept (cut: compared the same way). */
-const versionOf = (app: Pick<DesktopApp, "version">) => app.version?.slice(0, 100)
+export const versionOf = (app: Pick<DesktopApp, "version">) => app.version?.slice(0, 100)
 
 /**
  * Each bundle id's copies (a release in Applications, a dev build elsewhere: one id, several
@@ -165,7 +165,7 @@ function without<T>(record: Readonly<Record<string, T>>, key: string): Record<st
 }
 
 /** The same app: its developer (a team app updated is still theirs), or the same pinned build. */
-function sameSigner(a: Signer, b: Signer): boolean {
+export function sameSigner(a: Signer, b: Signer): boolean {
   return a.kind === "team"
     ? b.kind === "team" && a.team === b.team && a.identifier === b.identifier
     : b.kind === "pinned" && a.digest === b.digest
@@ -178,7 +178,7 @@ function sameSigner(a: Signer, b: Signer): boolean {
  * developer, or another build of an unsigned one); `not-found` (no longer where it was picked).
  */
 export type DesktopStatus =
-  | { status: "ready" | "updated" }
+  | { status: "ready" | "updated"; app: DesktopApp }
   | { status: "allow" | "opens-changed" | "changed" | "not-found"; why: string }
 
 /** The functions that look at an app (the runtime's; fakes in tests). */
@@ -196,6 +196,7 @@ export async function desktopStatus(
   scope: string,
   approvals: DesktopApprovals,
   looks: Pick<Looks, "inspect">,
+  signal?: AbortSignal,
 ): Promise<DesktopStatus> {
   const copy = approvals.copyFor(entry.bundleId, scope)
   if (copy === undefined) {
@@ -211,8 +212,9 @@ export async function desktopStatus(
   }
   let now: DesktopApp
   try {
-    now = await looks.inspect(copy.path)
+    now = await looks.inspect(copy.path, signal)
   } catch (error) {
+    if (signal?.aborted === true) throw error
     if (!existsSync(copy.path)) {
       return { status: "not-found", why: `not at ${copy.path} any more: add it again` }
     }
@@ -222,8 +224,8 @@ export async function desktopStatus(
     return { status: "changed", why: "another app is there now (or another build): add it again" }
   }
   return versionOf(now) !== copy.scopes[scope]?.version && now.signer.kind === "team"
-    ? { status: "updated" }
-    : { status: "ready" }
+    ? { status: "updated", app: now }
+    : { status: "ready", app: now }
 }
 
 /** An app's name in the project: its own, in the app-name form, made unique. */
@@ -426,11 +428,18 @@ export class DesktopAdds {
     const stopping = new AbortController()
     pending.trial = stopping
     try {
-      const outcome = await this.#looks.trial(pending.app, {
-        origins: pending.origins,
-        signal: stopping.signal,
-        ...(this.#workDir !== undefined && { workDir: this.#workDir }),
-      })
+      const outcome = await this.#looks
+        .trial(pending.app, {
+          origins: pending.origins,
+          signal: stopping.signal,
+          ...(this.#workDir !== undefined && { workDir: this.#workDir }),
+        })
+        .catch((error: unknown) => {
+          // Ended (Kif started, given up): said in words, never a raw stop.
+          if (!stopping.signal.aborted) throw error
+          this.#own(owner, session, token)
+          throw refused("the check was ended (Kif started?): check it again")
+        })
       this.#own(owner, session, token)
       pending.tried = "ok" in outcome
       pending.site = "site" in outcome ? outcome.site : undefined
@@ -521,6 +530,11 @@ export class DesktopAdds {
     }
   }
 
+  /** Every check in progress ended (Kif starting): picks and cards kept, checked again later. */
+  endChecks(): void {
+    for (const pending of this.#pending.values()) pending.trial?.abort()
+  }
+
   /** Every pick and add given up, their trials ended (a project switch, a quit). */
   dropAll(): void {
     for (const pick of this.#picks.values()) pick.stopping.abort()
diff --git a/apps/desktop/src/main/desktop-launch.ts b/apps/desktop/src/main/desktop-launch.ts
new file mode 100644
index 0000000..f4e5fb0
--- /dev/null
+++ b/apps/desktop/src/main/desktop-launch.ts
@@ -0,0 +1,182 @@
+// A desktop app launched for the agent (PR 4, design reviewed 2026-10-10): only an app approved
+// on this Mac for this project and what it opens, from the copy that was approved. One the same
+// developer updated is tried confined first, quietly (the user's decision, 2026-10-09), and that
+// build approved for the project only if nothing changed meanwhile. Anything else is refused for
+// the user to settle in the Apps panel (never something the agent can fix).
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import type { OpenedProject } from "@kiframe/project"
+import type { DesktopApp, ElectronLaunch, ElectronTarget, TrialOutcome } from "@kiframe/runtime"
+import type { ElectronApp, TakeMeta } from "@kiframe/schema"
+import {
+  type DesktopApprovals,
+  desktopStatus,
+  type Looks,
+  opensOf,
+  sameSigner,
+  versionOf,
+} from "./desktop-apps.ts"
+
+/** What a take keeps of the app it filmed: its build and what it opened (the take's own shape). */
+export type AppBuild = NonNullable<TakeMeta["appBuild"]>
+
+/** A launch refused: the user settles it (the Apps panel), the agent says so and never retries. */
+export class DesktopRefused extends Error {
+  readonly needsUser = true
+}
+
+export interface LauncherDeps {
+  approvals: () => DesktopApprovals
+  looks: Looks
+  launch: (opts: ElectronLaunch) => Promise<ElectronTarget>
+  /** The open project, read at each step (a switch meanwhile: refused). */
+  opened: () => OpenedProject | null
+  scope: (dir: string) => string
+  workDir?: string
+}
+
+/**
+ * Launches the project's desktop apps, each from its approval (an updated build tried quietly by
+ * the launch itself first).
+ */
+export class DesktopLauncher {
+  readonly #deps: LauncherDeps
+  #lifetime = new AbortController()
+
+  constructor(deps: LauncherDeps) {
+    this.#deps = deps
+  }
+
+  /** Every launch's quiet trial ended (a project switch, a quit): their confined apps killed. */
+  stopAll(): void {
+    this.#lifetime.abort()
+    this.#lifetime = new AbortController()
+  }
+
+  /** The app `name` of the open project, launched confined; refused: `DesktopRefused`. */
+  async launch(
+    name: string,
+    signal?: AbortSignal,
+  ): Promise<{ target: ElectronTarget; build: AppBuild }> {
+    const opened = this.#deps.opened()
+    const entry = opened?.project.apps[name]
+    if (opened === null || entry?.kind !== "electron") {
+      throw new DesktopRefused(`"${name}" isn't a desktop app of the open project`)
+    }
+    const scope = this.#deps.scope(opened.dir)
+    // The launcher's stop as it was when this launch began (a switch meanwhile ends it too).
+    const lifetime = this.#lifetime.signal
+    let status = await desktopStatus(entry, scope, this.#deps.approvals(), this.#deps.looks, signal)
+    if (status.status === "updated") {
+      signal?.throwIfAborted()
+      const stops = signal === undefined ? lifetime : AbortSignal.any([signal, lifetime])
+      await this.#quietTrial(name, entry, opened, scope, status.app, stops, signal)
+      // Asked again: what's there now must be the build just approved (an update landing during
+      // the trial, an app moved or replaced: refused for the user, never launched untried).
+      status = await desktopStatus(entry, scope, this.#deps.approvals(), this.#deps.looks, signal)
+      if (status.status === "updated") {
+        throw new DesktopRefused(`${name} updated again while it was checked: start again`)
+      }
+    }
+    if ("why" in status) throw new DesktopRefused(`${name}: ${status.why} (in the Apps panel)`)
+    signal?.throwIfAborted()
+    // Still approved here, the project still open and naming it the same (removed or switched
+    // while it was looked at: never launched).
+    this.#still(name, entry, opened, scope, status.app)
+    const app = status.app
+    const files = join(opened.dir, "files")
+    const target = await this.#deps.launch({
+      executable: app.executable,
+      bundle: app.path,
+      ...(existsSync(files) && { files }),
+      ...(entry.args !== undefined && { args: entry.args }),
+      ...(entry.origins !== undefined && { origins: entry.origins }),
+      viewport: entry.viewport,
+      ...(signal !== undefined && { signal }),
+      ...(this.#deps.workDir !== undefined && { workDir: this.#deps.workDir }),
+    })
+    const version = versionOf(app)
+    return { target, build: { ...(version !== undefined && { version }), opens: opensOf(entry) } }
+  }
+
+  /** The approval and the project as they were looked at, still (else refused, nothing written). */
+  #still(
+    name: string,
+    entry: ElectronApp,
+    opened: OpenedProject,
+    scope: string,
+    app: DesktopApp,
+    approvedBuild = true,
+  ): void {
+    const copy = this.#deps.approvals().copyFor(entry.bundleId, scope)
+    const now = this.#deps.opened()
+    const named = now?.project.apps[name]
+    const same =
+      copy !== undefined &&
+      copy.path === app.path &&
+      sameSigner(copy.signer, app.signer) &&
+      copy.scopes[scope]?.opens === opensOf(entry) &&
+      (!approvedBuild ||
+        app.signer.kind !== "team" ||
+        copy.scopes[scope]?.version === versionOf(app)) &&
+      now === opened &&
+      named?.kind === "electron" &&
+      opensOf(named) === opensOf(entry)
+    if (!same) {
+      throw new DesktopRefused(`${name} changed meanwhile: allow it again (in the Apps panel)`)
+    }
+  }
+
+  /**
+   * An updated build tried confined by this launch, then approved for its project compare-and-set
+   * (the same copy, developer and opens, the project still the one it looked at: two launches that
+   * both tried it approve the same thing; anything changed: refused). Its stop: the launch's own
+   * (thrown as it is), or the launcher's (refused: the project closed).
+   */
+  async #quietTrial(
+    name: string,
+    entry: ElectronApp,
+    opened: OpenedProject,
+    scope: string,
+    app: DesktopApp,
+    stops: AbortSignal,
+    own: AbortSignal | undefined,
+  ): Promise<void> {
+    let outcome: TrialOutcome
+    try {
+      outcome = await this.#deps.looks.trial(app, {
+        origins: entry.origins ?? [],
+        signal: stops,
+        ...(this.#deps.workDir !== undefined && { workDir: this.#deps.workDir }),
+      })
+    } catch (error) {
+      if (own?.aborted === true) throw error
+      if (stops.aborted)
+        throw new DesktopRefused(`${name}: the project closed while it was checked`)
+      throw error
+    }
+    if (stops.aborted && own?.aborted !== true) {
+      throw new DesktopRefused(`${name}: the project closed while it was checked`)
+    }
+    own?.throwIfAborted()
+    if (!("ok" in outcome)) throw new DesktopRefused(`${name} updated: ${refusalOf(outcome)}`)
+    this.#still(name, entry, opened, scope, app, false)
+    try {
+      this.#deps.approvals().approve(app, scope, opensOf(entry))
+    } catch (error) {
+      throw new DesktopRefused(
+        `${name} ran confined but couldn't be approved here (${(error as Error).message})`,
+      )
+    }
+  }
+}
+
+/** What a quiet trial that didn't work says (in words the user acts on). */
+function refusalOf(outcome: Exclude<TrialOutcome, { ok: true }>): string {
+  if ("site" in outcome) {
+    return `its window is now the site ${outcome.site}: allow it again (in the Apps panel)`
+  }
+  if ("quit" in outcome)
+    return "it quit at once when tried confined: check it again (in the Apps panel)"
+  return `it couldn't be tried confined (${outcome.failed}): check it again (in the Apps panel)`
+}
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index be4f9c7..f93613c 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -7,7 +7,7 @@ import { defaultWorkDir, inspectDesktopApp, sweepWorkArea, trialDesktopApp } fro
 import { keychainBackend, memoryBackend } from "@kiframe/vault"
 import { app, type BrowserWindow, dialog, shell } from "electron"
 import { type Browser, chromium } from "playwright"
-import type { AppStatus } from "../shared/ipc.ts"
+import type { AppStatus, DesktopStatusView } from "../shared/ipc.ts"
 import { errorMessage } from "../shared/util.ts"
 import { AgentHost } from "./agent.ts"
 import {
@@ -245,7 +245,11 @@ function start(): void {
         // The files the agent replaces or deletes, kept first (by the host's scope for the folder).
         versions: new FileVersions(join(app.getPath("userData"), "versions", scope)),
         item: (item) => current() && emit(window, "chat:item", item),
-        running: (running) => current() && emit(window, "chat:running", running),
+        running: (running) => {
+          // Kif starting ends an "Add desktop app…" check in progress (never beside its run).
+          if (running && current()) adds.endChecks()
+          return current() && emit(window, "chat:running", running)
+        },
         frame: (frame) => current() && emit(window, "live:frame", frame),
         projectChanged: () => {
           // Checked again once read: a switch meanwhile makes this one stale.
@@ -298,6 +302,9 @@ function start(): void {
   let approvals: DesktopApprovals | undefined
   const desktopApprovals = (): DesktopApprovals =>
     (approvals ??= new DesktopApprovals(app.getPath("userData")))
+  /** A status as the window has it (never the app's path or details). */
+  const view = (s: Awaited<ReturnType<typeof desktopStatus>>) =>
+    "why" in s ? { status: s.status, why: s.why } : { status: s.status }
   /** The open project, if it's this session's (else why not). */
   const sessionProject = (session: string): OpenedProject | string => {
     const opened = workspace.opened
@@ -579,7 +586,7 @@ function start(): void {
         "apps:desktop-cancel": () => adds.dropFor(owner()),
         "apps:desktop-status": async ({ session }) => {
           const opened = sessionProject(session)
-          const apps: Record<string, Awaited<ReturnType<typeof desktopStatus>>> = {}
+          const apps: DesktopStatusView["apps"] = {}
           if (typeof opened === "string") return { apps, problem: null }
           const store = desktopApprovals()
           const scope = ids().scope(opened.dir)
@@ -588,7 +595,7 @@ function start(): void {
               if (entry.kind !== "electron") return
               apps[name] =
                 process.platform === "darwin"
-                  ? await desktopStatus(entry, scope, store, looks)
+                  ? view(await desktopStatus(entry, scope, store, looks))
                   : { status: "not-found", why: "desktop apps run on macOS only" }
             }),
           )
diff --git a/apps/desktop/test/desktop-apps.test.ts b/apps/desktop/test/desktop-apps.test.ts
index c209d1d..2e5ba20 100644
--- a/apps/desktop/test/desktop-apps.test.ts
+++ b/apps/desktop/test/desktop-apps.test.ts
@@ -133,7 +133,7 @@ describe("a desktop app's approvals", () => {
     // A long version compares as it was kept (never "updated" for being long).
     const team = notes({ path: "/Users/me/dev/w24/Notes.app", version: "9".repeat(150) })
     return desktopStatus(entry(), "folder-24", again, looks({ [team.path]: team }).looks).then(
-      (status) => expect(status).toEqual({ status: "ready" }),
+      (status) => expect(status).toMatchObject({ status: "ready" }),
     )
   })
 
@@ -175,14 +175,14 @@ describe("a desktop app's status (static: nothing launches)", () => {
   const approved = (a: DesktopApprovals) => a.approve(notes(), "folder-a", opensOf(entry()))
 
   it("is ready when approved here for what it opens, updated when its developer shipped a new build", async () => {
+    // With the app as inspected now, at the approved copy's place (what a launch starts).
     expect(await status({ "/Applications/Notes.app": notes() }, approved)).toEqual({
       status: "ready",
+      app: notes(),
     })
     expect(
       await status({ "/Applications/Notes.app": notes({ version: "2.0" }) }, approved),
-    ).toEqual({
-      status: "updated",
-    })
+    ).toEqual({ status: "updated", app: notes({ version: "2.0" }) })
   })
 
   it("asks again: never added here, another project's, what it opens changed", async () => {
@@ -200,17 +200,17 @@ describe("a desktop app's status (static: nothing launches)", () => {
     const approvals = new DesktopApprovals(dir())
     approvals.approve(notes(), "folder-b", opensOf(entry()))
     const updated = { "/Applications/Notes.app": notes({ version: "1.1" }) }
-    expect(await desktopStatus(entry(), "folder-b", approvals, looks(updated).looks)).toEqual({
-      status: "updated",
-    })
+    expect(await desktopStatus(entry(), "folder-b", approvals, looks(updated).looks)).toMatchObject(
+      { status: "updated" },
+    )
     // Project A tries and approves 1.1: B still hasn't tried it.
     approvals.approve(notes({ version: "1.1" }), "folder-a", opensOf(entry()))
-    expect(await desktopStatus(entry(), "folder-b", approvals, looks(updated).looks)).toEqual({
-      status: "updated",
-    })
-    expect(await desktopStatus(entry(), "folder-a", approvals, looks(updated).looks)).toEqual({
-      status: "ready",
-    })
+    expect(await desktopStatus(entry(), "folder-b", approvals, looks(updated).looks)).toMatchObject(
+      { status: "updated" },
+    )
+    expect(await desktopStatus(entry(), "folder-a", approvals, looks(updated).looks)).toMatchObject(
+      { status: "ready" },
+    )
   })
 
   it("never looks at the app to say what needs no look (another project's, opens changed)", async () => {
@@ -315,7 +315,7 @@ describe("adding a desktop app", () => {
         h.approvals,
         h.fake.looks,
       ),
-    ).toEqual({ status: "ready" })
+    ).toMatchObject({ status: "ready" })
   })
 
   it("allows a wrapper's site only as the trial named it, tried before it's added", async () => {
@@ -405,7 +405,7 @@ describe("adding a desktop app", () => {
     h.fake.looks.inspect = () => Promise.resolve(notes({ version: "2.0" }))
     await h.adds.add(1, "s1", card.token)
     const desk = openProject(h.opened.dir).project.apps["notes"] as ElectronApp
-    expect(await desktopStatus(desk, "folder-a", h.approvals, h.fake.looks)).toEqual({
+    expect(await desktopStatus(desk, "folder-a", h.approvals, h.fake.looks)).toMatchObject({
       status: "updated",
     })
   })
@@ -522,7 +522,7 @@ describe("adding an app a project already names", () => {
     expect(await h.adds.add(1, "s1", card.token)).toBe("desk")
     const desk = openProject(opened.dir).project.apps["desk"] as ElectronApp
     expect(desk.origins).toEqual(["https://app.slack.com"])
-    expect(await desktopStatus(desk, "folder-a", h.approvals, h.fake.looks)).toEqual({
+    expect(await desktopStatus(desk, "folder-a", h.approvals, h.fake.looks)).toMatchObject({
       status: "ready",
     })
   })
@@ -610,8 +610,51 @@ describe("an add's lifetime: its project's, checked after every wait", () => {
     const card = await adds.pick(1, session)
     const checking = adds.check(1, session, card?.token ?? "", false)
     await workspace.close()
-    await expect(checking).rejects.toMatchObject({ name: "AbortError" })
+    // Said in words (never a raw stop).
+    await expect(checking).rejects.toThrow(/isn't being added any more/)
     expect(signal?.aborted).toBe(true)
     expect(workspace.session).toBeUndefined()
   })
 })
+
+describe("Kif starting during an add", () => {
+  it("ends a check in progress, keeping the card to check again", async () => {
+    const h = harness()
+    const trial = deferred<TrialOutcome>()
+    h.fake.looks.trial = (_app, o) => {
+      o.signal?.addEventListener("abort", () => trial.resolve({ failed: "stopped" }))
+      return trial.promise
+    }
+    const card = await h.pick()
+    const checking = h.adds.check(1, "s1", card.token, false)
+    h.adds.endChecks()
+    expect(await checking).toEqual({ failed: "stopped" })
+    h.fake.looks.trial = () => Promise.resolve({ ok: true })
+    expect(await h.adds.check(1, "s1", card.token, false)).toEqual({ ok: true })
+  })
+
+  it("says a check it ended as Kif working, never a raw stop", async () => {
+    const h = harness()
+    h.fake.looks.trial = (_app, o) =>
+      new Promise<TrialOutcome>((_, reject) =>
+        o.signal?.addEventListener("abort", () => reject(o.signal?.reason as Error)),
+      )
+    const card = await h.pick()
+    const checking = h.adds.check(1, "s1", card.token, false)
+    h.state.busy = "Kif is working: stop it first"
+    h.adds.endChecks()
+    await expect(checking).rejects.toThrow(/Kif is working/)
+  })
+
+  it("says a check ended after Kif already stopped in words too", async () => {
+    const h = harness()
+    h.fake.looks.trial = (_app, o) =>
+      new Promise<TrialOutcome>((_, reject) =>
+        o.signal?.addEventListener("abort", () => reject(o.signal?.reason as Error)),
+      )
+    const card = await h.pick()
+    const checking = h.adds.check(1, "s1", card.token, false)
+    h.adds.endChecks()
+    await expect(checking).rejects.toThrow(/the check was ended/)
+  })
+})
diff --git a/apps/desktop/test/desktop-launch.test.ts b/apps/desktop/test/desktop-launch.test.ts
new file mode 100644
index 0000000..09077cb
--- /dev/null
+++ b/apps/desktop/test/desktop-launch.test.ts
@@ -0,0 +1,347 @@
+import { mkdirSync, mkdtempSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { createProject, type OpenedProject, saveProject } from "@kiframe/project"
+import type { DesktopApp, ElectronLaunch, ElectronTarget, TrialOutcome } from "@kiframe/runtime"
+import type { ElectronApp } from "@kiframe/schema"
+import { describe, expect, it } from "vitest"
+import { DesktopApprovals, opensOf } from "../src/main/desktop-apps.ts"
+import { DesktopLauncher, DesktopRefused } from "../src/main/desktop-launch.ts"
+
+// A desktop app launched for the agent (PR 4): from its approval only, an updated build tried
+// quietly first and approved compare-and-set. Fakes for the runtime's looks and launch.
+
+const dir = () => mkdtempSync(join(tmpdir(), "kiframe-desktop-launch-"))
+const notes = (over: Partial<DesktopApp> = {}): DesktopApp => ({
+  path: "/Applications/Notes.app",
+  bundleId: "com.example.Notes",
+  name: "Notes",
+  version: "1.0",
+  electron: "44.4.5",
+  executable: "/Applications/Notes.app/Contents/MacOS/Notes",
+  signer: { kind: "team", team: "TEAM123456", identifier: "com.example.Notes" },
+  ...over,
+})
+const entry = (over: Partial<ElectronApp> = {}): ElectronApp => ({
+  kind: "electron",
+  bundleId: "com.example.Notes",
+  args: ["files/vault"],
+  origins: ["https://notes.example"],
+  viewport: { width: 1280, height: 800, deviceScaleFactor: 1 },
+  ...over,
+})
+
+function deferred<T>() {
+  let resolve: (value: T) => void = () => undefined
+  const promise = new Promise<T>((r) => (resolve = r))
+  return { promise, resolve }
+}
+
+/** A project naming the app, approved (or not) for its folder, and a launcher over fakes. */
+function setup(installed: DesktopApp = notes(), approve = true) {
+  const opened = createProject(join(dir(), "demo.kiframe"), {
+    id: "p1",
+    name: "Demo",
+    url: "https://app.test",
+  })
+  saveProject(opened, { ...opened.project, apps: { ...opened.project.apps, notes: entry() } })
+  const approvals = new DesktopApprovals(dir())
+  if (approve) approvals.approve(notes(), "folder-a", opensOf(entry()))
+  const state = {
+    opened: opened as OpenedProject | null,
+    installed,
+    trials: 0,
+    trial: (): Promise<TrialOutcome> => Promise.resolve({ ok: true }),
+    launches: [] as ElectronLaunch[],
+  }
+  const launcher = new DesktopLauncher({
+    approvals: () => approvals,
+    looks: {
+      inspect: () => Promise.resolve(state.installed),
+      trial: () => {
+        state.trials += 1
+        return state.trial()
+      },
+    },
+    launch: (opts) => {
+      state.launches.push(opts)
+      return Promise.resolve({ close: () => Promise.resolve() } as unknown as ElectronTarget)
+    },
+    opened: () => state.opened,
+    scope: () => "folder-a",
+  })
+  return { launcher, state, approvals, opened }
+}
+
+describe("a desktop app launched for the agent", () => {
+  it("launches the approved copy with what the project opens, its build said", async () => {
+    const { launcher, state, opened } = setup()
+    const { build } = await launcher.launch("notes")
+    expect(state.trials).toBe(0)
+    expect(state.launches[0]).toMatchObject({
+      executable: "/Applications/Notes.app/Contents/MacOS/Notes",
+      bundle: "/Applications/Notes.app",
+      args: ["files/vault"],
+      origins: ["https://notes.example"],
+      viewport: { width: 1280, height: 800, deviceScaleFactor: 1 },
+    })
+    // No files/ folder in the project: none given.
+    expect(state.launches[0]?.files).toBeUndefined()
+    expect(build).toEqual({ version: "1.0", opens: opensOf(entry()) })
+    mkdirSync(join(opened.dir, "files"))
+    await launcher.launch("notes")
+    expect(state.launches[1]?.files).toBe(join(opened.dir, "files"))
+  })
+
+  it("refuses for the user what isn't approved here, never launching it", async () => {
+    for (const [why, make] of [
+      ["not added on this Mac", () => setup(notes(), false)],
+      [
+        "another app is there now",
+        () => setup(notes({ signer: { kind: "team", team: "OTHER00000", identifier: "x" } })),
+      ],
+    ] as const) {
+      const { launcher, state } = make()
+      const error = await launcher.launch("notes").catch((e: unknown) => e)
+      expect(error, why).toBeInstanceOf(DesktopRefused)
+      expect((error as DesktopRefused).needsUser).toBe(true)
+      expect(String(error)).toContain(why)
+      expect(String(error)).toContain("in the Apps panel")
+      expect(state.launches).toEqual([])
+    }
+    // What the project opens with it changed (a pull): asked again.
+    const { launcher, state, opened } = setup()
+    saveProject(opened, {
+      ...opened.project,
+      apps: { ...opened.project.apps, notes: entry({ origins: ["https://evil.example"] }) },
+    })
+    await expect(launcher.launch("notes")).rejects.toThrow(/changed what it opens/)
+    expect(state.launches).toEqual([])
+  })
+
+  it("tries an update quietly, then approves that build for the project and launches it", async () => {
+    const { launcher, state, approvals } = setup(notes({ version: "1.1" }))
+    await launcher.launch("notes")
+    expect(state.trials).toBe(1)
+    expect(approvals.copyFor("com.example.Notes", "folder-a")?.scopes["folder-a"]?.version).toBe(
+      "1.1",
+    )
+    expect(state.launches).toHaveLength(1)
+    // Approved now: no second trial.
+    await launcher.launch("notes")
+    expect(state.trials).toBe(1)
+  })
+
+  it("refuses an update that no longer runs confined", async () => {
+    const { launcher, state, approvals } = setup(notes({ version: "1.1" }))
+    state.trial = () => Promise.resolve({ quit: true })
+    await expect(launcher.launch("notes")).rejects.toThrow(/updated: it quit at once/)
+    expect(approvals.copyFor("com.example.Notes", "folder-a")?.scopes["folder-a"]?.version).toBe(
+      "1.0",
+    )
+    expect(state.launches).toEqual([])
+  })
+
+  it("never approves what changed while the update was tried (removed, project switched)", async () => {
+    for (const change of ["removed", "switched"] as const) {
+      const { launcher, state, approvals } = setup(notes({ version: "1.1" }))
+      const trial = deferred<TrialOutcome>()
+      state.trial = () => trial.promise
+      const launching = launcher.launch("notes")
+      await new Promise((resolve) => setTimeout(resolve, 0))
+      if (change === "removed") approvals.drop("com.example.Notes", "folder-a")
+      else state.opened = null
+      trial.resolve({ ok: true })
+      await expect(launching, change).rejects.toThrow(/changed meanwhile/)
+      expect(state.launches, change).toEqual([])
+      expect(
+        approvals.copyFor("com.example.Notes", "folder-a")?.scopes["folder-a"]?.version,
+        change,
+      ).not.toBe("1.1")
+    }
+  })
+
+  it("lets two launches of an update at once each try it, both approving the same build", async () => {
+    const { launcher, state, approvals } = setup(notes({ version: "1.1" }))
+    await Promise.all([launcher.launch("notes"), launcher.launch("notes")])
+    expect(state.trials).toBe(2)
+    expect(state.launches).toHaveLength(2)
+    expect(approvals.copyFor("com.example.Notes", "folder-a")?.scopes["folder-a"]?.version).toBe(
+      "1.1",
+    )
+  })
+
+  it("never launches an app removed or a project switched while it was looked at", async () => {
+    for (const change of ["removed", "closed", "another"] as const) {
+      const { state, approvals } = setup()
+      const looking = deferred<DesktopApp>()
+      const launcher = new DesktopLauncher({
+        approvals: () => approvals,
+        looks: { inspect: () => looking.promise, trial: () => Promise.resolve({ ok: true }) },
+        launch: (opts) => {
+          state.launches.push(opts)
+          return Promise.resolve({ close: () => Promise.resolve() } as unknown as ElectronTarget)
+        },
+        opened: () => state.opened,
+        scope: () => "folder-a",
+      })
+      const launching = launcher.launch("notes")
+      if (change === "removed") approvals.drop("com.example.Notes", "folder-a")
+      if (change === "closed") state.opened = null
+      // Another project naming the app the same, opened meanwhile (same scope: never its approval).
+      if (change === "another") state.opened = setup().opened
+      looking.resolve(notes())
+      await expect(launching, change).rejects.toThrow(/changed meanwhile/)
+      expect(state.launches, change).toEqual([])
+    }
+  })
+
+  it("ends a quiet trial with the launcher (a project switch, a quit), and never starts one stopped", async () => {
+    const { launcher, state } = setup(notes({ version: "1.1" }))
+    let signal: AbortSignal | undefined
+    const trialing = new DesktopLauncher({
+      approvals: () => setup().approvals,
+      looks: {
+        inspect: () => Promise.resolve(notes({ version: "1.1" })),
+        trial: (_app, o) => {
+          signal = o.signal
+          // As the runtime's: a stop thrown as the stop.
+          return new Promise<TrialOutcome>((_, reject) =>
+            o.signal?.addEventListener("abort", () => reject(o.signal?.reason as Error)),
+          )
+        },
+      },
+      launch: () => Promise.reject(new Error("never")),
+      opened: () => state.opened,
+      scope: () => "folder-a",
+    })
+    const launching = trialing.launch("notes")
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    trialing.stopAll()
+    // Refused for the user (never a raw stop the agent takes for its own).
+    const error = await launching.catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(DesktopRefused)
+    expect(String(error)).toMatch(/the project closed while it was checked/)
+    expect(signal?.aborted).toBe(true)
+    // A launch already stopped: no trial at all.
+    const stopped = new AbortController()
+    stopped.abort()
+    const before = state.trials
+    await expect(launcher.launch("notes", stopped.signal)).rejects.toMatchObject({
+      name: "AbortError",
+    })
+    expect(state.trials).toBe(before)
+  })
+
+  it("never launches a build other than the one tried (an update landing during its trial)", async () => {
+    const { launcher, state } = setup(notes({ version: "1.1" }))
+    const trial = deferred<TrialOutcome>()
+    state.trial = () => trial.promise
+    const launching = launcher.launch("notes")
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    state.installed = notes({ version: "1.2" })
+    trial.resolve({ ok: true })
+    await expect(launching).rejects.toThrow(/updated again while it was checked/)
+    expect(state.launches).toEqual([])
+  })
+
+  it("stops only the launch that was stopped (its own trial), never another's", async () => {
+    const { state, approvals } = setup(notes({ version: "1.1" }))
+    const launcher = new DesktopLauncher({
+      approvals: () => approvals,
+      looks: {
+        inspect: () => Promise.resolve(state.installed),
+        trial: (_app, o) =>
+          new Promise<TrialOutcome>((resolve, reject) => {
+            o.signal?.addEventListener("abort", () => reject(o.signal?.reason as Error))
+            setTimeout(() => resolve({ ok: true }), 20)
+          }),
+      },
+      launch: (opts) => {
+        state.launches.push(opts)
+        return Promise.resolve({ close: () => Promise.resolve() } as unknown as ElectronTarget)
+      },
+      opened: () => state.opened,
+      scope: () => "folder-a",
+    })
+    const stopping = new AbortController()
+    const stopped = launcher.launch("notes", stopping.signal)
+    const going = launcher.launch("notes")
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    stopping.abort()
+    await expect(stopped).rejects.toMatchObject({ name: "AbortError" })
+    await going
+    expect(state.launches).toHaveLength(1)
+  })
+
+  it("says why an update's quiet trial didn't work, and a failed approval, for the user", async () => {
+    for (const [outcome, said] of [
+      [{ site: "https://login.example" }, /its window is now the site https:\/\/login\.example/],
+      [{ quit: true }, /quit at once/],
+      [{ failed: "busy" }, /couldn't be tried confined \(busy\)/],
+    ] as const) {
+      const { launcher, state } = setup(notes({ version: "1.1" }))
+      state.trial = () => Promise.resolve(outcome as TrialOutcome)
+      const error = await launcher.launch("notes").catch((e: unknown) => e)
+      expect(error).toBeInstanceOf(DesktopRefused)
+      expect(String(error)).toMatch(said)
+    }
+    const { state, approvals } = setup(notes({ version: "1.1" }))
+    const failing = new DesktopLauncher({
+      approvals: () =>
+        Object.assign(Object.create(approvals) as DesktopApprovals, {
+          copyFor: approvals.copyFor.bind(approvals),
+          approve: () => {
+            throw new Error("EACCES")
+          },
+        }),
+      looks: {
+        inspect: () => Promise.resolve(state.installed),
+        trial: () => Promise.resolve({ ok: true }),
+      },
+      launch: () => Promise.reject(new Error("never")),
+      opened: () => state.opened,
+      scope: () => "folder-a",
+    })
+    const error = await failing.launch("notes").catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(DesktopRefused)
+    expect(String(error)).toMatch(/couldn't be approved here \(EACCES\)/)
+  })
+
+  it("never approves an update for another project opened while it was tried", async () => {
+    const { launcher, state, approvals } = setup(notes({ version: "1.1" }))
+    const trial = deferred<TrialOutcome>()
+    state.trial = () => trial.promise
+    const launching = launcher.launch("notes")
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    // Another project naming the app the same (same scope), opened during the trial.
+    state.opened = setup().opened
+    trial.resolve({ ok: true })
+    await expect(launching).rejects.toThrow(/changed meanwhile/)
+    expect(approvals.copyFor("com.example.Notes", "folder-a")?.scopes["folder-a"]?.version).toBe(
+      "1.0",
+    )
+    expect(state.launches).toEqual([])
+  })
+
+  it("launches only the build approved now (another launch's approval meanwhile: refused)", async () => {
+    const { state, approvals } = setup()
+    const looking = deferred<DesktopApp>()
+    const launcher = new DesktopLauncher({
+      approvals: () => approvals,
+      looks: { inspect: () => looking.promise, trial: () => Promise.resolve({ ok: true }) },
+      launch: (opts) => {
+        state.launches.push(opts)
+        return Promise.resolve({ close: () => Promise.resolve() } as unknown as ElectronTarget)
+      },
+      opened: () => state.opened,
+      scope: () => "folder-a",
+    })
+    const launching = launcher.launch("notes")
+    // Another launch approved 1.1 meanwhile: this one's 1.0 is no longer the approved build.
+    approvals.approve(notes({ version: "1.1" }), "folder-a", opensOf(entry()))
+    looking.resolve(notes())
+    await expect(launching).rejects.toThrow(/changed meanwhile/)
+    expect(state.launches).toEqual([])
+  })
+})
diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md
index 6766caa..7dc5b32 100644
--- a/docs/BACKLOG.md
+++ b/docs/BACKLOG.md
@@ -247,7 +247,8 @@ Non-severe review findings deferred on purpose (see the review-round rule: only
 - **What a confined app opens through LaunchServices:** an app can't start without `launchservicesd`, and through it it can open a file or a URL that then runs unconfined (a script it wrote, the user's browser). Stated in §0.9 (accident, not a hostile app); an Endpoint Security watcher or a per-run user account would close it.
 - **Desktop-app sweeps read processes more than once:** the startup sweep runs one `ps` per leftover sandbox (one `ps -axo pid=,lstart=` table would answer every owner), and a run's close reads the process table twice (`orphanedGroup` and `sweepProcesses`). Startup and close time only (#58 review).
 - **Clicks in a desktop app under its own DevTools (macOS runner):** with DevTools opened mid-run over a hidden test window, a click waited for the button to be stable until its timeout on GitHub's macOS runner (animation frames throttled: the window covered); locally it clicks. The DevTools test reads instead of clicking; check clicks with DevTools open on a real app in PR 5.
-- **A desktop app's check while Kif starts:** the Apps panel refuses a check while Kif works, but Kif starting during a check (10–40 s) doesn't end it: the confined app runs beside Kif's run, its result refused after. End the check when a run starts (the agent's start hook).
+- **CI flakes seen on #60 (passed on rerun):** `recorder.test.ts` "keeps a storyboard shot for a first step that starts before any frame" (a `frameSize` mismatch, Linux), and `electron.test.ts` "runs in its own sandbox" (the fixture quit before Kiframe attached, macOS runner). Neither repeated locally (3/3); watch for a second occurrence, then look into it.
+- **A desktop app's files/ under its approval:** an approval covers the app and what the project opens with it (its `args`, `origins`), not what's in `files/`: a teammate's pull can change `files/demo-vault` (an Obsidian plugin that runs code) without asking again. Only the confinement holds then. The quiet trial of an update doesn't open `files/` either (as the add's trial). A check or a recording launches a second copy beside the live one: an app that binds a fixed port fails there (said as its launch's failure).
 - **One launch helper:** browsers are launched by each entry point; nothing enforces an off-the-record context. A runtime-owned `launchBrowser()` / context factory would make it hard to bypass (the desktop app's main process).
 - **Secrets into contenteditable:** v0 writes secrets to inputs and textareas only (the value set on the approved element); a rich-text field is refused.
 - **Network exfiltration by the page itself:** a hostile page receives the typed password in its own field and can send it anywhere; that's the target app's own data. Out of scope for the vault (it only guarantees the value goes to the bound field on the allowed origins).
diff --git a/docs/OBJECT-MODEL.md b/docs/OBJECT-MODEL.md
index b6e91c9..da63968 100644
--- a/docs/OBJECT-MODEL.md
+++ b/docs/OBJECT-MODEL.md
@@ -232,6 +232,7 @@ One scene, three phases. The agent's own instructions say the same (`packages/st
 - **Every launch confined (PR 3a, 2026-10-09, design reviewed twice, measured):** on macOS each launch runs under Seatbelt (`sandbox-exec`, `electron-confine.ts`): writes only into its own sandbox; no reads of /Users, /Volumes, the temp folders, the user's home and the work area wherever they are (a home outside /Users) but its sandbox and its bundle; nothing run from its sandbox (the one place it writes: a program it drops there, a copied launcher), no `open`, `osascript`, `launchctl` nor Apple Events; no unix sockets (an agent's: ssh, Docker) but mDNSResponder; no preferences (cfprefsd), keychain (SecurityServer: a mock keychain instead, `--use-mock-keychain`) nor clipboard (the user's may hold a password just copied: an app's own copy and paste doesn't work in a run); the network on, for runs and trials alike (the app's backend, a wrapper's site: an updater can't touch the real app, nothing outside the sandbox being written; what an app could send is only what it can read here: its bundle, the system's files, its own sandbox). Chromium's own sandbox can't nest in it (`--no-sandbox`): the guard and this profile replace it. A canary before every launch, before the files are copied (a read the profile refuses must fail, one of its sandbox succeed: a confinement that runs nothing never passes); no `sandbox-exec`, or a canary failed: no launch (never unconfined). Off macOS: desktop apps don't launch (CI's tests only, unconfined). Measured with a probe app: every escape above `EPERM` (a hard link or a symlink to an outside file too), the app driven as usual. This replaces the trial's after-the-fact isolation check, rejected by review (an app that leaks does its harm as it starts). **What it doesn't stop (stated):** an app can still ask macOS to open a file or a URL (LaunchServices: no app starts without reaching it, measured), and what opens runs outside the confinement; it reaches services on this machine (localhost: a dev build's own server needs it). The app's own pages are its bundle and what it writes in its sandbox's home, profile and temp folders (a page it builds there from remote content counts as its own, as its cache already does); never the files/ copy. The confinement keeps an app from the user's data by accident (the minmux incident), not an app built to escape (one the user runs unconfined every day anyway).
 - **Adding a desktop app (PR 3b, design reviewed 2026-10-09):** inspected first, statically (`electron-inspect.ts`: only `plutil` and `codesign` run): refused outside where an app can stay (a disk image, a temporary translocated copy, the Trash, inside another app), not Electron (its framework; no version gate: Figma reports 13.6.1), an executable that isn't its own file, a Mac App Store build (App Sandbox), a developer signature that doesn't hold (`codesign --verify --strict` against its team and signed identifier). Kept: its id, name, Electron's version, and its signer: a developer (team id) or, ad hoc and unsigned (the user's own builds), pinned to a digest of the whole bundle (a link leading outside it refused; at most 4 GB and 200,000 entries). Then **tried confined** (`electron-trial.ts`): launched with the network as in a run (an updater can't touch the real app: nothing outside the sandbox is written; a wrapper's offline page can't hide its site), its main window attached, closed; a wrapper's site is named (even unreached: the error page's unreachable URL, over CDP) and allowed by the user in a second trial. A main window that never loaded its own page (offline, a dev server not running) is refused at launch, said as such: never a window driven on Chromium's error page. An attach that hangs as the first page fails (measured 1 in 5; cause not found) is tried again within the launch's time (stated). A trial runs only the build that was picked (its developer's signature, or its pinned digest, checked first; a change between that check and the launch is the user's own build tool's: holding every launch to its approval is PR 4's, with runs). codesign that fails or times out refuses the app (never read as unsigned or unsandboxed). Apps that allow one copy (Slack, VS Code, Discord) need Chromium's temp folder in the sandbox (`MAC_CHROMIUM_TMPDIR`): its lock's socket otherwise goes to the user's /var/folders, denied, and the app quits.
 - **Approvals (PR 3b-2, user decisions 2026-10-09):** added from the Apps panel ("Add desktop app…", macOS): main shows the picker (Applications) and inspects what was picked; the window gets a card and a token, never the app's path, and never names a site to allow (the trial's, kept in main). Tried confined, then added (the build that was tried is approved: one updated since says "updated"; `project.json`, its changed-on-disk refusal) and approved in app data (`desktop-apps.json`, 0600, written whole; one that doesn't read is set aside and said, never overwritten). An approval is per copy of the app on this Mac (where it was picked: a release and a dev build of one bundle id kept apart, a project using one of them; at most 20 copies of one app kept, the oldest let go) and per project folder (the registry's scope) and covers the app (its developer's team, or the exact build of an unsigned one) **and what the project opens with it** (its `args` and `origins`, as a digest): a pull that changes either asks again. Statuses (static, opening the panel launches nothing): ready; updated (same developer, a build this project hasn't tried: tried confined before its next run, PR 4, which records it); allow (approved for another project, or never on this Mac: pick it to allow it here, without adding it twice); opens-changed; changed (another developer, another unsigned build); not found. Removing the app drops this project's approval. Off macOS: nothing offered. A trial in progress ends with its add (another pick, the project closed, a quit); what a crash left is swept at the start.
+- **Launching an approved app (PR 4, design reviewed 2026-10-10):** main launches a project's desktop app only from its approval for this project folder and what it opens (`desktop-launch.ts`): the copy approved, inspected once (its status); `ready` launches it (the copy's executable and bundle; the project's `files/` when it has one, its `args`, `origins`, viewport); `updated` (the same developer's new build) is tried confined first, quietly (one trial per app and project at a time), then that build approved for the project compare-and-set (the same copy, developer and opens, the project still the open one: else refused); anything else is refused for the user to settle in the Apps panel (`needsUser`: the agent says so, never retries). A take of a desktop app keeps its build (`appBuild`: its version and what it opened; never in the take's key, never a reason to record again: user decision 2026-10-10; an older Kiframe can't read such a take: its meta is strict). Kif starting ends an add's check in progress.
 - **The work area `~/.kiframe/`** (decided by the user 2026-10-09: deletable any time): `sandboxes/` (one per launch, 0700, never a link), each named after the Kiframe that made it (`kiframe-app-<pid>-<start>-…`: owned from the moment it exists, no shared state file to race on); a crash sweep at start removes only sandboxes no running Kiframe owns (the processes pointing at them killed first), never another build's launch, and nothing when `ps` can't be read. Kept out of Time Machine and Spotlight. Approvals stay in the app's settings, takes in app data.
 - **A project's `files/`** (decided by the user 2026-10-09): what a desktop app opens. Copied into the sandbox at each launch by Kiframe's own walk (folders and regular files only: a link, a FIFO, a device refused; 500 MB, 20,000 files, depth 32; cloned where the disk can, times kept); `args` name paths in it only (`files/vault`, given as the copy's path); the app's edits stay in the copy (thrown away: every run from the same files). The copy is the project's content, never the app's own pages for the guard. Filled by the user in v0: the agent's file tools never reach `files/` (it may hold what runs inside the app: an editor's tasks, a vault's plugins).
 - **Measured on a fixture app (PR 2, 2026-10-08):** HOME, XDG and `--user-data-dir` hold; macOS's own places don't move: Electron's `appData` (`~/Library/Application Support`) and the app's preferences (`NSUserDefaults`, written by `cfprefsd` into the user's real `~/Library/Preferences/<bundle id>.plist`) stay the user's whatever `HOME` or `CFFIXED_USER_HOME` say. Hence the confinement (PR 3a, below): the preferences daemon is denied and writes outside the sandbox refused, so neither can be reached (a check after launch, the earlier plan, came too late).
diff --git a/packages/runtime/src/electron-confine.ts b/packages/runtime/src/electron-confine.ts
index 7b529f8..4ff35fc 100644
--- a/packages/runtime/src/electron-confine.ts
+++ b/packages/runtime/src/electron-confine.ts
@@ -206,8 +206,11 @@ export async function copyFiles(from: string, to: string, signal?: AbortSignal):
     if (error instanceof FilesError) throw error
     const code = (error as { code?: string }).code
     throw new FilesError(
-      code === "ENOENT" && !existsSync(from)
-        ? "the project has no files/ folder (what its arguments name)"
+      code === "ENOENT"
+        ? existsSync(from)
+          ? // Something in it gone while it was copied (moved, swapped): said as such.
+            "files/ changed while it was copied: try again"
+          : "the project has no files/ folder (what its arguments name)"
         : `files/ couldn't be copied (${code ?? String(error)})`,
     )
   }
diff --git a/packages/runtime/src/recorder.ts b/packages/runtime/src/recorder.ts
index d806d79..e2930bd 100644
--- a/packages/runtime/src/recorder.ts
+++ b/packages/runtime/src/recorder.ts
@@ -53,6 +53,8 @@ export interface RecordOptions extends RunOptions {
   encodeFailed?: boolean
   /** Version string written into meta.json. */
   kiframeVersion?: string
+  /** A desktop app's build and what it opened (its take keeps them: shown, never a key). */
+  appBuild?: TakeMeta["appBuild"]
 }
 
 export interface Take {
@@ -471,6 +473,7 @@ export async function recordScenario(
         recordedAt: recordedAt.toISOString(),
         appUrl: appIdentity(start.app),
         app: start.name,
+        ...(options.appBuild !== undefined && { appBuild: options.appBuild }),
         // The capture scale actually obtained (Phase 0 finding F1: screencast frames are at CSS size).
         viewport: {
           width: viewport.width,
diff --git a/packages/runtime/test/electron.test.ts b/packages/runtime/test/electron.test.ts
index 638a083..1937f86 100644
--- a/packages/runtime/test/electron.test.ts
+++ b/packages/runtime/test/electron.test.ts
@@ -372,9 +372,16 @@ steps:
         outDir: out,
         sceneId: "notes",
         electron: inTarget(target),
+        appBuild: { version: "44.4.5", opens: "a".repeat(64) },
       },
     )
     expect(take.meta.appUrl).toBe("electron:com.kiframe.fixture")
+    // The build it filmed and what it opened, kept (read back through the schema).
+    expect(take.meta.appBuild).toEqual({ version: "44.4.5", opens: "a".repeat(64) })
+    expect(
+      (JSON.parse(readFileSync(join(take.dir, "meta.json"), "utf8")) as { appBuild?: unknown })
+        .appBuild,
+    ).toEqual({ version: "44.4.5", opens: "a".repeat(64) })
     expect(existsSync(join(take.dir, "frames.webm"))).toBe(true)
   })
 
@@ -1367,10 +1374,15 @@ describe("a desktop app's files", { timeout: 60_000 }, () => {
     }
 
     beforeAll(async () => {
-      // The app's own time to start, measured: it's given twice that and a second.
-      const t0 = Date.now()
-      await (await launch()).close()
-      budget = 2 * (Date.now() - t0) + 1000
+      // The app's own time to start, measured twice (one slow start: never the budget's undoing):
+      // it's given three times the slower and two seconds.
+      let slowest = 0
+      for (let i = 0; i < 2; i++) {
+        const t0 = Date.now()
+        await (await launch()).close()
+        slowest = Math.max(slowest, Date.now() - t0)
+      }
+      budget = 3 * slowest + 2000
       root = mkdtempSync(join(tmpdir(), "kiframe-el-slow-"))
       files = join(root, "files")
       FILES_LIMITS.files = 400_000
@@ -1425,7 +1437,9 @@ describe("a desktop app's files", { timeout: 60_000 }, () => {
         symlinkSync(mirror, vault)
       }, 300)
       try {
-        await expect(launching).rejects.toThrow(/files\/vault.* changed while it was copied/)
+        // Refused as a change, whichever moment of the swap the copy met (a link in its place, or the
+        // folder gone between the rename and the link).
+        await expect(launching).rejects.toThrow(/files.* changed while it was copied/)
       } finally {
         rmSync(vault, { force: true })
         renameSync(join(root, "vault-moved"), vault)
diff --git a/packages/runtime/test/runner.test.ts b/packages/runtime/test/runner.test.ts
index b6df8ca..904a131 100644
--- a/packages/runtime/test/runner.test.ts
+++ b/packages/runtime/test/runner.test.ts
@@ -1827,7 +1827,13 @@ steps:
         ? [`${e.kind}:${e.rule}:${e.step.stepId}`]
         : [],
     )
-    expect(kinds).toEqual(["interrupt_start:cookies:go", "interrupt_end:cookies:go"])
+    // Handled once, off camera, before the click it would block: before "go" when it shows during
+    // the pause, before "wait" when the page loaded slower than its 300 ms (a busy CI machine:
+    // already up as the steps begin). Either way the click it would have blocked works.
+    expect([
+      ["interrupt_start:cookies:go", "interrupt_end:cookies:go"],
+      ["interrupt_start:cookies:wait", "interrupt_end:cookies:wait"],
+    ]).toContainEqual(kinds)
   })
 
   it("doesn't re-run a rule on a dialog that is still fading out", async () => {
diff --git a/packages/schema/src/take.ts b/packages/schema/src/take.ts
index 5e7a5c7..60563c8 100644
--- a/packages/schema/src/take.ts
+++ b/packages/schema/src/take.ts
@@ -127,6 +127,17 @@ const TakeMetaBase = z.strictObject({
   appUrl: withoutCredentials(z.string()),
   /** The app the take starts in, by its name in the project (takes from before named apps: none). */
   app: AppName.optional(),
+  /**
+   * A desktop app's take: the build it filmed (its version, untrusted: bounded) and what the
+   * project opened it with (a digest of its arguments and sites). Shown, never a reason to record
+   * again (an app's update keeps its scenes: user decision 2026-10-10).
+   */
+  appBuild: z
+    .strictObject({
+      version: z.string().max(100).optional(),
+      opens: z.string().regex(/^[0-9a-f]{64}$/),
+    })
+    .optional(),
   /** The environment the take was recorded on (APPROACHES §10c), when known. */
   environment: RuleName.optional(),
   /** The page's CSS viewport, and the capture scale actually obtained (frame pixels per CSS pixel). */
diff --git a/vitest.config.ts b/vitest.config.ts
index e623c69..125b805 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -25,7 +25,14 @@ export default defineConfig({
       },
       {
         extends: true,
-        test: { name: "electron", include: [ELECTRON], sequence: { groupOrder: 1 } },
+        // Its files one after another too (launching Electron while another file clones and
+        // re-signs it: a binary busy on Linux, slow starts on macOS, seen in CI on #61).
+        test: {
+          name: "electron",
+          include: [ELECTRON],
+          sequence: { groupOrder: 1 },
+          fileParallelism: false,
+        },
       },
     ],
   },

From ad41fa904f30457722ad52601d6a43213e04c4c7 Mon Sep 17 00:00:00 2001
From: Quang Lee <winlp4ever@gmail.com>
Date: Sat, 10 Oct 2026 18:07:41 +0200
Subject: [PATCH 08/10] feat(studio): ground, check and record scenes in a
 desktop app (#62)

* feat(studio): ground, check and record scenes in a desktop app

The studio works in a desktop app as in a web app (PR 4b, design
reviewed), through the host's launcher (from the app's approval, confined):

- grounding keeps one live launch of the scene's app (another app's scene
  closes it first; one that quit is launched again, said); a check and a
  recording each run in a fresh launch, closed whole after; a take keeps
  the app's build
- the app's pages are said by its guard (its own page or not), never its
  file path; looking at a ref and an approval's screenshot read the
  window's size from the page
- a refusal the user settles is said for the agent to tell them, never to
  retry; no handover in a desktop app yet (a scene with one isn't saved)
- main gives the agent its launcher, its quiet trials ended as the project
  switches or the app quits; the prompt says how desktop apps are worked

* fix(studio): keep local paths and retries out of a desktop app's refusals

- every launch failure is a refusal for the user, its local paths taken out
  (the app's place, the work area, the project, the home: whole, then any
  other); a tool error the user settles never invites a retry
- the scene's app live before a step's refs are resolved (another app's
  page: a new snapshot asked); the live page kept between web apps' scenes
  (a sign-in by hand kept), closed only for a desktop app's
- a launch stopped with the tool that asked for it; an app removed from
  the project closed; a relaunch said on a failing step too
- no handover in a desktop app live either, nor through a preset; window
  sizes read with a bound

* fix(studio): open the app asked for, and stop only its own caller

- the live page being opened is that app's: a caller asking for another
  waits, then asks again (closed first if need be); a desktop launch is
  the studio's (ended as it closes), each caller stopped by its own stop
- an app removed while it launched is never kept; a relaunch said only
  once it worked; a handover refused before anything launches; the
  handover check reads each step
- local paths taken out by one runtime helper (known ones whole, file:
  URLs, a path up to where it plainly ends); only an approval's refusal
  is the user's to settle (a launch that timed out may be tried again)

* refactor(studio): own each desktop launch, say no paths at the source

Round 3 still found normal-use bugs in the shared live launch and the
path regex, so both are redesigned:

- a desktop launch is owned by the tool call that started it: its stop
  or the studio's close ends it (trial and spawn), it is never joined (a
  call while it goes on is refused, one after a stop waits it out), and
  an app removed or changed while it opened is never kept
- launch errors name no local path by construction (OS errors by their
  code); the launcher passes only those and its own refusals, and
  replaces whole a message naming a folder it knows
- every launch failure is the user's to settle: the agent tells them and
  never retries

* fix(studio): keep a refusal for the user, one copy of a desktop app at a time

- a refusal the user settles keeps its flag through the tool wrapper and
  the agent loop: the model is told to tell them, never to retry
- a check or recording closes the live copy of a desktop app first, and
  a stop during its launch ends the call as a stop
- a recording closes its launched app when its take folder can't be made
- the live app is closed when the project lists another app under its
  name; concurrent closes share one close
- a step is checked before any app is launched or closed for it
- a desktop app's snapshot says its links by the guard (never a file path)
- a copy error with no code is said without its message

* fix(studio): check a step before any launch, close only the app being checked

- a step's shape is checked before any app opens or closes for it (its
  refs stood in for by a plain locator)
- a check or recording closes only its own app's live copy; another
  desktop app stays live
- whether a launch in flight is a desktop one is kept when it starts (an
  app removed meanwhile is still waited out); one rule for a launch in
  flight
- look says an app that quit and was launched again
- a refusal is said in its own words (no "Error:", no doubled prefix);
  one needsUser helper; the live page's app and identity required

* feat(studio): never guess which of several apps to open

With several apps and none open, snapshot, look and a handover say to open the scene's app with a step first (a pause step does nothing else) instead of opening the first app. A project with one app still opens it. look's hidden failure reason goes to stderr under KIFRAME_ELECTRON_DEBUG.

* ci(desktop): install chromium for the macos electron tests

* test(studio): show the desktop fixture's window on linux

A hidden window never paints under xvfb, so a look's screenshot timed out on Linux CI. Also backlogs the launch's splash race (seen on macOS CI).
---
 .github/workflows/ci.yml                     |   2 +
 apps/desktop/e2e/desktop-app.e2e.ts          |  47 +-
 apps/desktop/src/main/agent.ts               |   6 +
 apps/desktop/src/main/desktop-apps.ts        |  16 +-
 apps/desktop/src/main/desktop-launch.ts      |  58 +-
 apps/desktop/src/main/index.ts               |  27 +-
 apps/desktop/test/desktop-launch.test.ts     |  46 +-
 docs/BACKLOG.md                              |   1 +
 docs/OBJECT-MODEL.md                         |   1 +
 packages/agent/src/agent-loop.ts             |  11 +-
 packages/agent/src/tool-result.ts            |  22 +-
 packages/agent/test/agent-loop.test.ts       |  19 +
 packages/agent/test/tool-result.test.ts      |  12 +
 packages/runtime/src/electron-confine.ts     |   8 +-
 packages/runtime/src/electron-workarea.ts    |   9 +-
 packages/runtime/src/electron.ts             |  23 +-
 packages/runtime/src/index.ts                |   2 +
 packages/runtime/src/run/secrets.ts          |   5 +-
 packages/runtime/test/electron.test.ts       |  30 +-
 packages/studio/src/prompt.ts                |  11 +-
 packages/studio/src/studio.ts                | 589 ++++++++++++++++---
 packages/studio/src/tools.ts                 |   7 +-
 packages/studio/test/desktop-app.test.ts     | 464 ++++++++++++++-
 packages/studio/test/electron-studio.test.ts | 320 ++++++++++
 packages/studio/test/studio.test.ts          |  25 +-
 vitest.config.ts                             |   2 +-
 26 files changed, 1600 insertions(+), 163 deletions(-)
 create mode 100644 packages/studio/test/electron-studio.test.ts

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1a22e25..dfe5206 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -65,6 +65,8 @@ jobs:
       - run: pnpm install --frozen-lockfile
       # A desktop app's takes are encoded with ffmpeg (as on Linux).
       - run: brew install ffmpeg
+      # The studio's desktop tests drive a web page beside the app too.
+      - run: pnpm --filter @kiframe/runtime exec playwright install chromium
       - run: pnpm exec vitest run --project electron
         env:
           KIFRAME_ELECTRON_TIMING: "1"
diff --git a/apps/desktop/e2e/desktop-app.e2e.ts b/apps/desktop/e2e/desktop-app.e2e.ts
index 9b6c919..6915b99 100644
--- a/apps/desktop/e2e/desktop-app.e2e.ts
+++ b/apps/desktop/e2e/desktop-app.e2e.ts
@@ -3,7 +3,7 @@
 // dialog (stubbed), inspected, tried confined, written to the project and approved. Its work area
 // is a test's own (never ~/.kiframe).
 import { execFileSync } from "node:child_process"
-import { cpSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs"
+import { cpSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
 import { createRequire } from "node:module"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
@@ -53,6 +53,33 @@ beforeAll(async () => {
   )
   env.KIFRAME_TEST_KEYCHAIN = "memory"
   env.KIFRAME_WORK_DIR = work
+  // Kif, scripted: a step in the desktop app once it's added (launched from its approval).
+  const model = join(root, "model.json")
+  writeFileSync(
+    model,
+    JSON.stringify([
+      {
+        kind: "tool_calls",
+        calls: [
+          {
+            id: "d1",
+            name: "run_step",
+            arguments: JSON.stringify({
+              scene: "tour",
+              start_app: "notes",
+              step: {
+                id: "add",
+                action: "click",
+                target: { by: "role", role: "button", name: "Add note" },
+              },
+            }),
+          },
+        ],
+      },
+      { kind: "text", text: "Added a note in Notes." },
+    ]),
+  )
+  env.KIFRAME_TEST_MODEL = model
   app = await electron.launch({ args: [appDir, `--user-data-dir=${profile}`], cwd: appDir, env })
   page = await app.firstWindow()
   await page.getByLabel("OpenRouter API key").fill("sk-or-test-not-a-real-key")
@@ -101,4 +128,22 @@ describe.runIf(mac)("adding a desktop app", () => {
     // The trial's sandbox gone; nothing of it in the user's own work area.
     expect(readdirSync(join(work, "sandboxes")).filter((n) => !n.endsWith(".canary"))).toEqual([])
   }, 120_000)
+
+  it("lets Kif work in it: launched from its approval, confined, closed with the project", async () => {
+    // The Apps panel closed (the chat beside it).
+    await page.keyboard.press("Escape")
+    const box = page.getByLabel("Message Kif")
+    await box.fill("Add a note in Notes")
+    await box.press("Enter")
+    await expect
+      .poll(() => page.getByText("Added a note in Notes.").count(), { timeout: 60_000 })
+      .toBeGreaterThan(0)
+    // Its live app: one confined launch in the test's work area.
+    const live = () => readdirSync(join(work, "sandboxes")).filter((n) => !n.endsWith(".canary"))
+    expect(live()).toHaveLength(1)
+    // The project closed: Kif's app ends with it.
+    await page.getByRole("button", { name: /Desktop demo/ }).click()
+    await page.getByRole("menuitem", { name: "Close project" }).click()
+    await expect.poll(() => live().length, { timeout: 20_000 }).toBe(0)
+  }, 120_000)
 })
diff --git a/apps/desktop/src/main/agent.ts b/apps/desktop/src/main/agent.ts
index ca681ef..73a919d 100644
--- a/apps/desktop/src/main/agent.ts
+++ b/apps/desktop/src/main/agent.ts
@@ -12,6 +12,7 @@ import {
   notesBlock,
   runNotes,
   Studio,
+  type StudioOptions,
   studioTools,
   systemPrompt,
 } from "@kiframe/studio"
@@ -99,6 +100,8 @@ export interface AgentHostOptions {
   projectChanged: () => void
   /** Where the files the agent replaces or deletes are kept first (none: not kept). */
   versions?: FileVersions
+  /** Launches the project's desktop apps (main's launcher, from their approvals). None: none. */
+  launchDesktop?: StudioOptions["launchDesktop"]
 }
 
 /** A message as sent: its text as the user wrote it, as the history keeps it, its files. */
@@ -515,6 +518,9 @@ export class AgentHost {
       takes,
       browser,
       ...(this.#options.afterRecord !== undefined && { afterRecord: this.#options.afterRecord }),
+      ...(this.#options.launchDesktop !== undefined && {
+        launchDesktop: this.#options.launchDesktop,
+      }),
       requestUser: (request, signal) => this.#ask(request, signal),
       // What the agent read of the project's files: this host's (outlives a studio remade).
       fileReads: this.#fileReads,
diff --git a/apps/desktop/src/main/desktop-apps.ts b/apps/desktop/src/main/desktop-apps.ts
index 1fdae5b..f08319b 100644
--- a/apps/desktop/src/main/desktop-apps.ts
+++ b/apps/desktop/src/main/desktop-apps.ts
@@ -7,7 +7,13 @@ import { createHash, randomBytes, randomUUID } from "node:crypto"
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
 import { dirname, join } from "node:path"
 import { type OpenedProject, saveProject } from "@kiframe/project"
-import type { DesktopApp, Signer, TrialOptions, TrialOutcome } from "@kiframe/runtime"
+import {
+  type DesktopApp,
+  InspectError,
+  type Signer,
+  type TrialOptions,
+  type TrialOutcome,
+} from "@kiframe/runtime"
 import { BUNDLE_ID, type ElectronApp } from "@kiframe/schema"
 import { z } from "zod"
 
@@ -216,9 +222,13 @@ export async function desktopStatus(
   } catch (error) {
     if (signal?.aborted === true) throw error
     if (!existsSync(copy.path)) {
-      return { status: "not-found", why: `not at ${copy.path} any more: add it again` }
+      return { status: "not-found", why: "not where it was picked any more: add it again" }
+    }
+    // An inspection's own refusal (worded, path-free), else just that it changed.
+    return {
+      status: "changed",
+      why: error instanceof InspectError ? error.message : "it can't be looked at any more",
     }
-    return { status: "changed", why: (error as Error).message }
   }
   if (keyOf(now.bundleId) !== keyOf(entry.bundleId) || !sameSigner(copy.signer, now.signer)) {
     return { status: "changed", why: "another app is there now (or another build): add it again" }
diff --git a/apps/desktop/src/main/desktop-launch.ts b/apps/desktop/src/main/desktop-launch.ts
index f4e5fb0..8bb4d7c 100644
--- a/apps/desktop/src/main/desktop-launch.ts
+++ b/apps/desktop/src/main/desktop-launch.ts
@@ -4,9 +4,16 @@
 // build approved for the project only if nothing changed meanwhile. Anything else is refused for
 // the user to settle in the Apps panel (never something the agent can fix).
 import { existsSync } from "node:fs"
+import { homedir } from "node:os"
 import { join } from "node:path"
 import type { OpenedProject } from "@kiframe/project"
-import type { DesktopApp, ElectronLaunch, ElectronTarget, TrialOutcome } from "@kiframe/runtime"
+import {
+  type DesktopApp,
+  type ElectronLaunch,
+  ElectronLaunchError,
+  type ElectronTarget,
+  type TrialOutcome,
+} from "@kiframe/runtime"
 import type { ElectronApp, TakeMeta } from "@kiframe/schema"
 import {
   type DesktopApprovals,
@@ -53,10 +60,49 @@ export class DesktopLauncher {
     this.#lifetime = new AbortController()
   }
 
-  /** The app `name` of the open project, launched confined; refused: `DesktopRefused`. */
+  /**
+   * The app `name` of the open project, launched confined. Refused by its approval:
+   * `DesktopRefused` (the user's to settle); any other failure an Error; either said without a
+   * local path (the agent reads it); a stop thrown as the stop.
+   */
   async launch(
     name: string,
     signal?: AbortSignal,
+  ): Promise<{ target: ElectronTarget; build: AppBuild }> {
+    try {
+      return await this.#launch(name, signal)
+    } catch (error) {
+      if (signal?.aborted === true) throw error
+      throw new DesktopRefused(this.#said(name, error), { cause: error })
+    }
+  }
+
+  /**
+   * A launch's failure as the agent reads it: its own worded refusals and the runtime's launch
+   * errors (none names a local path, by construction) as they are; anything else by its code
+   * only. A message naming a path Kiframe knows anyway (never meant to): replaced whole.
+   */
+  #said(name: string, error: unknown): string {
+    const said =
+      error instanceof DesktopRefused
+        ? error.message
+        : error instanceof ElectronLaunchError
+          ? `${name}: ${error.message}`
+          : `${name} couldn't be launched (${(error as { code?: string }).code ?? "an error"})`
+    const opened = this.#deps.opened()
+    const known = [
+      homedir(),
+      ...(this.#deps.workDir !== undefined ? [this.#deps.workDir] : []),
+      ...(opened !== null ? [opened.dir] : []),
+    ]
+    return known.some((path) => path.length > 1 && said.includes(path))
+      ? `${name} couldn't be launched (details kept out: they name a local folder)`
+      : said
+  }
+
+  async #launch(
+    name: string,
+    signal?: AbortSignal,
   ): Promise<{ target: ElectronTarget; build: AppBuild }> {
     const opened = this.#deps.opened()
     const entry = opened?.project.apps[name]
@@ -75,7 +121,9 @@ export class DesktopLauncher {
       // the trial, an app moved or replaced: refused for the user, never launched untried).
       status = await desktopStatus(entry, scope, this.#deps.approvals(), this.#deps.looks, signal)
       if (status.status === "updated") {
-        throw new DesktopRefused(`${name} updated again while it was checked: start again`)
+        throw new DesktopRefused(
+          `${name} updated again while it was checked: ask again in a moment`,
+        )
       }
     }
     if ("why" in status) throw new DesktopRefused(`${name}: ${status.why} (in the Apps panel)`)
@@ -164,8 +212,10 @@ export class DesktopLauncher {
     try {
       this.#deps.approvals().approve(app, scope, opensOf(entry))
     } catch (error) {
+      // Its code only (a write error names the approvals file's path).
       throw new DesktopRefused(
-        `${name} ran confined but couldn't be approved here (${(error as Error).message})`,
+        `${name} ran confined but couldn't be approved here (${(error as { code?: string }).code ?? "not saved"})`,
+        { cause: error },
       )
     }
   }
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index f93613c..3d28f8f 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -3,13 +3,20 @@ import { join } from "node:path"
 import { fileURLToPath } from "node:url"
 import { type LlmClient, OpenAiCompatibleClient } from "@kiframe/agent"
 import { type OpenedProject, TakeStore } from "@kiframe/project"
-import { defaultWorkDir, inspectDesktopApp, sweepWorkArea, trialDesktopApp } from "@kiframe/runtime"
+import {
+  defaultWorkDir,
+  inspectDesktopApp,
+  launchElectron,
+  sweepWorkArea,
+  trialDesktopApp,
+} from "@kiframe/runtime"
 import { keychainBackend, memoryBackend } from "@kiframe/vault"
 import { app, type BrowserWindow, dialog, shell } from "electron"
 import { type Browser, chromium } from "playwright"
 import type { AppStatus, DesktopStatusView } from "../shared/ipc.ts"
 import { errorMessage } from "../shared/util.ts"
 import { AgentHost } from "./agent.ts"
+import { DesktopLauncher } from "./desktop-launch.ts"
 import {
   addHostOf,
   DesktopAdds,
@@ -238,6 +245,10 @@ function start(): void {
         sceneKey: (sceneId) => registry.sceneKey(opened.dir, sceneId),
         takes,
         browser: launch,
+        // Desktop apps (macOS): launched from their approval for this project, confined.
+        ...(process.platform === "darwin" && {
+          launchDesktop: (name: string, signal: AbortSignal) => launcher.launch(name, signal),
+        }),
         llm: model,
         model: DEFAULT_MODEL,
         seesImages,
@@ -297,11 +308,22 @@ function start(): void {
     workDir,
   )
   // Every add ends, its trial too, as the project switches.
-  // Every add ends, its trial too, as the project switches.
+  // Every add ends, its trial too, as the project switches; every launch's quiet trial too.
   workspace.onSwitch(() => adds.dropAll())
   let approvals: DesktopApprovals | undefined
   const desktopApprovals = (): DesktopApprovals =>
     (approvals ??= new DesktopApprovals(app.getPath("userData")))
+  // Launches a project's desktop app for the agent, from its approval (every launch's quiet
+  // trial of an update ends as the project switches).
+  const launcher = new DesktopLauncher({
+    approvals: desktopApprovals,
+    looks,
+    launch: launchElectron,
+    opened: () => workspace.opened,
+    scope: (dir) => ids().scope(dir),
+    workDir,
+  })
+  workspace.onSwitch(() => launcher.stopAll())
   /** A status as the window has it (never the app's path or details). */
   const view = (s: Awaited<ReturnType<typeof desktopStatus>>) =>
     "why" in s ? { status: s.status, why: s.why } : { status: s.status }
@@ -364,6 +386,7 @@ function start(): void {
     cleanup = "running"
     // Every desktop app's trial ended (its confined app killed with it).
     adds.dropAll()
+    launcher.stopAll()
     const work = (async () => {
       // The browser let go within the close, as for project:close (an open in flight never comes
       // between); a close refused still lets it go: the app is quitting.
diff --git a/apps/desktop/test/desktop-launch.test.ts b/apps/desktop/test/desktop-launch.test.ts
index 09077cb..c60f458 100644
--- a/apps/desktop/test/desktop-launch.test.ts
+++ b/apps/desktop/test/desktop-launch.test.ts
@@ -6,6 +6,8 @@ import type { DesktopApp, ElectronLaunch, ElectronTarget, TrialOutcome } from "@
 import type { ElectronApp } from "@kiframe/schema"
 import { describe, expect, it } from "vitest"
 import { DesktopApprovals, opensOf } from "../src/main/desktop-apps.ts"
+import { ElectronLaunchError } from "@kiframe/runtime"
+import { homedir } from "node:os"
 import { DesktopLauncher, DesktopRefused } from "../src/main/desktop-launch.ts"
 
 // A desktop app launched for the agent (PR 4): from its approval only, an updated build tried
@@ -292,7 +294,10 @@ describe("a desktop app launched for the agent", () => {
         Object.assign(Object.create(approvals) as DesktopApprovals, {
           copyFor: approvals.copyFor.bind(approvals),
           approve: () => {
-            throw new Error("EACCES")
+            // As a write fails: its message names the approvals file.
+            throw Object.assign(new Error("EACCES: permission denied, open '/Users/a/x.json'"), {
+              code: "EACCES",
+            })
           },
         }),
       looks: {
@@ -306,6 +311,7 @@ describe("a desktop app launched for the agent", () => {
     const error = await failing.launch("notes").catch((e: unknown) => e)
     expect(error).toBeInstanceOf(DesktopRefused)
     expect(String(error)).toMatch(/couldn't be approved here \(EACCES\)/)
+    expect(String(error)).not.toContain("/Users")
   })
 
   it("never approves an update for another project opened while it was tried", async () => {
@@ -344,4 +350,42 @@ describe("a desktop app launched for the agent", () => {
     await expect(launching).rejects.toThrow(/changed meanwhile/)
     expect(state.launches).toEqual([])
   })
+
+  it("says every launch failure for the user, never a local path", async () => {
+    const failing = (error: Error) => {
+      const { state, approvals } = setup()
+      return new DesktopLauncher({
+        approvals: () => approvals,
+        looks: {
+          inspect: () => Promise.resolve(state.installed),
+          trial: () => Promise.resolve({ ok: true }),
+        },
+        launch: () => Promise.reject(error),
+        opened: () => state.opened,
+        scope: () => "folder-a",
+      })
+    }
+    // An OS error (its message names a path): said by its code only.
+    const os = Object.assign(new Error("spawn /Users/alice/Apps/My App.app/x ENOENT"), {
+      code: "ENOENT",
+    })
+    const fromOs = await failing(os)
+      .launch("notes")
+      .catch((e: unknown) => e)
+    expect(fromOs).toBeInstanceOf(DesktopRefused)
+    expect(String(fromOs)).toContain("notes couldn't be launched (ENOENT)")
+    expect(String(fromOs)).not.toContain("/Users")
+    // The runtime's own launch errors (worded, path-free): as they are.
+    const said = await failing(new ElectronLaunchError("the app quit before Kiframe could attach"))
+      .launch("notes")
+      .catch((e: unknown) => e)
+    expect(String(said)).toContain("notes: the app quit before")
+    expect((said as DesktopRefused).needsUser).toBe(true)
+    // A message naming a folder Kiframe knows (never meant to): replaced whole.
+    const leaked = await failing(new ElectronLaunchError(`odd: ${homedir()}/x`))
+      .launch("notes")
+      .catch((e: unknown) => e)
+    expect(String(leaked)).not.toContain(homedir())
+    expect(String(leaked)).toContain("details kept out")
+  })
 })
diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md
index 7dc5b32..9428843 100644
--- a/docs/BACKLOG.md
+++ b/docs/BACKLOG.md
@@ -350,3 +350,4 @@ Non-severe review findings deferred on purpose (see the review-round rule: only
 - **Handover:** a scene's `handover` step (replay and recording pause for the user; recordings reuse the agent's signed-in session, in memory: decided 2026-10-07) — next PR; a handover between on-camera steps cut from the video (TakeEvent, ClipReason, clips/camera/captions around the cut); native dialogs and file pickers during a handover (shown in the card; `filechooser` through the OS picker); input coalescing (moves merged) if the queue proves slow.
 - **Handover in a check or a recording:** the live view shows a recording's page at the recording's frame size (device pixels: larger frames over IPC during the handover). Sign-in reuse: sessionStorage carried with the state (an init script per app origin); seeding it from the live app (a fresh live context for a `{ preset }` run); revoking a deleted preset's secret approvals (presets have no host key). A check or a recording falling back to a fresh sign-in by itself after `session-expired` (today: failed, the agent runs it again); fewer full snapshots on reuse (an app with a large IndexedDB is serialised each check).
 - **A `delete_scene` tool:** the agent can't remove a scene it saved (a throwaway probe stays in the project: seen on Excalidraw, 2026-10-08); with the user's approval, as a file delete.
+- **A desktop app's splash longer than the launch's settle** (seen 2026-10-10: `learns its own scheme … after a splash` failed on macOS CI and once locally under load): the launch seals the app's own addresses from the main window once the window list has been still for 1.5 s; a main window that shows later than that (a slow machine, a long splash) leaves the splash sealed as main, so the app's own scheme (`app:`) is never learned. Scheme learning is security-relevant (what counts as the app's own): measure real splashes in PR 5's real-app pass, then a reviewed design (e.g. learning from the first window that replaces a closed splash), never a longer fixed wait alone.
diff --git a/docs/OBJECT-MODEL.md b/docs/OBJECT-MODEL.md
index da63968..3dc6e05 100644
--- a/docs/OBJECT-MODEL.md
+++ b/docs/OBJECT-MODEL.md
@@ -233,6 +233,7 @@ One scene, three phases. The agent's own instructions say the same (`packages/st
 - **Adding a desktop app (PR 3b, design reviewed 2026-10-09):** inspected first, statically (`electron-inspect.ts`: only `plutil` and `codesign` run): refused outside where an app can stay (a disk image, a temporary translocated copy, the Trash, inside another app), not Electron (its framework; no version gate: Figma reports 13.6.1), an executable that isn't its own file, a Mac App Store build (App Sandbox), a developer signature that doesn't hold (`codesign --verify --strict` against its team and signed identifier). Kept: its id, name, Electron's version, and its signer: a developer (team id) or, ad hoc and unsigned (the user's own builds), pinned to a digest of the whole bundle (a link leading outside it refused; at most 4 GB and 200,000 entries). Then **tried confined** (`electron-trial.ts`): launched with the network as in a run (an updater can't touch the real app: nothing outside the sandbox is written; a wrapper's offline page can't hide its site), its main window attached, closed; a wrapper's site is named (even unreached: the error page's unreachable URL, over CDP) and allowed by the user in a second trial. A main window that never loaded its own page (offline, a dev server not running) is refused at launch, said as such: never a window driven on Chromium's error page. An attach that hangs as the first page fails (measured 1 in 5; cause not found) is tried again within the launch's time (stated). A trial runs only the build that was picked (its developer's signature, or its pinned digest, checked first; a change between that check and the launch is the user's own build tool's: holding every launch to its approval is PR 4's, with runs). codesign that fails or times out refuses the app (never read as unsigned or unsandboxed). Apps that allow one copy (Slack, VS Code, Discord) need Chromium's temp folder in the sandbox (`MAC_CHROMIUM_TMPDIR`): its lock's socket otherwise goes to the user's /var/folders, denied, and the app quits.
 - **Approvals (PR 3b-2, user decisions 2026-10-09):** added from the Apps panel ("Add desktop app…", macOS): main shows the picker (Applications) and inspects what was picked; the window gets a card and a token, never the app's path, and never names a site to allow (the trial's, kept in main). Tried confined, then added (the build that was tried is approved: one updated since says "updated"; `project.json`, its changed-on-disk refusal) and approved in app data (`desktop-apps.json`, 0600, written whole; one that doesn't read is set aside and said, never overwritten). An approval is per copy of the app on this Mac (where it was picked: a release and a dev build of one bundle id kept apart, a project using one of them; at most 20 copies of one app kept, the oldest let go) and per project folder (the registry's scope) and covers the app (its developer's team, or the exact build of an unsigned one) **and what the project opens with it** (its `args` and `origins`, as a digest): a pull that changes either asks again. Statuses (static, opening the panel launches nothing): ready; updated (same developer, a build this project hasn't tried: tried confined before its next run, PR 4, which records it); allow (approved for another project, or never on this Mac: pick it to allow it here, without adding it twice); opens-changed; changed (another developer, another unsigned build); not found. Removing the app drops this project's approval. Off macOS: nothing offered. A trial in progress ends with its add (another pick, the project closed, a quit); what a crash left is swept at the start.
 - **Launching an approved app (PR 4, design reviewed 2026-10-10):** main launches a project's desktop app only from its approval for this project folder and what it opens (`desktop-launch.ts`): the copy approved, inspected once (its status); `ready` launches it (the copy's executable and bundle; the project's `files/` when it has one, its `args`, `origins`, viewport); `updated` (the same developer's new build) is tried confined first, quietly (one trial per app and project at a time), then that build approved for the project compare-and-set (the same copy, developer and opens, the project still the open one: else refused); anything else is refused for the user to settle in the Apps panel (`needsUser`: the agent says so, never retries). A take of a desktop app keeps its build (`appBuild`: its version and what it opened; never in the take's key, never a reason to record again: user decision 2026-10-10; an older Kiframe can't read such a take: its meta is strict). Kif starting ends an add's check in progress.
+- **Kif in a desktop app (PR 4b, design reviewed 2026-10-10):** the studio grounds, checks and records a scene in a desktop app as in a web app, through the host's launcher (`launchDesktop`: from the approval, confined). Grounding keeps one live launch of the scene's app (one desktop app live at a time: another app's scene closes it first, a web app's live context stays between web apps; an app that quits while grounded is launched again and said: "what earlier steps did is gone"). A desktop launch is owned by the tool call that started it (redesigned after three review rounds): its stop or the studio's close ends it (its quiet trial, its spawn: nothing comes live after a stop), it's never joined (a call while it goes on is refused; one after a stop waits it out); an app removed or changed while it opened is never kept; a check or recording of a desktop scene closes that app's live copy first (one copy at a time: an app may allow only one; said with the next step; another app's live launch stays); a step's shape is checked before any app opens or closes for it. With several apps and none open, snapshot, look and a handover never guess which to open: the agent opens the scene's app with a step first (one app: it opens); a check and a recording each run in a fresh launch (its own sandbox: the same files and state every time), closed whole after. Its pages, and a snapshot's link addresses, are said by its guard (its own page or not, `placeOf`): never its file path. A launch's errors name no local path by construction (the runtime's say "the app isn't where it was approved any more", an OS error by its code); the launcher passes only those and its own refusals, anything else by its code, and replaces whole a message naming a folder it knows. Every launch failure is the user's to settle (`needsUser`: the agent tells them, never retries; an approval's refusal names the Apps panel). No handover in a desktop app yet (decided 2026-10-10: measured in PR 5): a scene with one isn't saved, a run's request for one is declined. A take keeps the app's build (`appBuild`). Every launch's quiet trial ends as the project switches or the app quits.
 - **The work area `~/.kiframe/`** (decided by the user 2026-10-09: deletable any time): `sandboxes/` (one per launch, 0700, never a link), each named after the Kiframe that made it (`kiframe-app-<pid>-<start>-…`: owned from the moment it exists, no shared state file to race on); a crash sweep at start removes only sandboxes no running Kiframe owns (the processes pointing at them killed first), never another build's launch, and nothing when `ps` can't be read. Kept out of Time Machine and Spotlight. Approvals stay in the app's settings, takes in app data.
 - **A project's `files/`** (decided by the user 2026-10-09): what a desktop app opens. Copied into the sandbox at each launch by Kiframe's own walk (folders and regular files only: a link, a FIFO, a device refused; 500 MB, 20,000 files, depth 32; cloned where the disk can, times kept); `args` name paths in it only (`files/vault`, given as the copy's path); the app's edits stay in the copy (thrown away: every run from the same files). The copy is the project's content, never the app's own pages for the guard. Filled by the user in v0: the agent's file tools never reach `files/` (it may hold what runs inside the app: an editor's tasks, a vault's plugins).
 - **Measured on a fixture app (PR 2, 2026-10-08):** HOME, XDG and `--user-data-dir` hold; macOS's own places don't move: Electron's `appData` (`~/Library/Application Support`) and the app's preferences (`NSUserDefaults`, written by `cfprefsd` into the user's real `~/Library/Preferences/<bundle id>.plist`) stay the user's whatever `HOME` or `CFFIXED_USER_HOME` say. Hence the confinement (PR 3a, below): the preferences daemon is denied and writes outside the sandbox refused, so neither can be reached (a check after launch, the earlier plan, came too late).
diff --git a/packages/agent/src/agent-loop.ts b/packages/agent/src/agent-loop.ts
index d5eb0cf..cf60348 100644
--- a/packages/agent/src/agent-loop.ts
+++ b/packages/agent/src/agent-loop.ts
@@ -3,6 +3,7 @@ import {
   CUT_SHORT,
   isToolFailure,
   isToolSoftError,
+  needsUser,
   toolAborted,
   toolNotRun,
   toolRejected,
@@ -67,9 +68,7 @@ export async function executeToolCall<C>(
     const result = await tool.run(args, ctx, signal)
     return isToolSoftError(result) ? toolRejected(tool.name, result.error) : result
   } catch (err) {
-    return signal.aborted
-      ? toolAborted(tool.name)
-      : toolThrew(tool.name, new Error(errorMessage(err)))
+    return signal.aborted ? toolAborted(tool.name) : toolThrew(tool.name, readable(err))
   }
 }
 
@@ -349,6 +348,12 @@ async function* modelTurn(
   return final
 }
 
+/** What a tool threw, readable (its text, and whether the user settles it): never throws itself. */
+function readable(err: unknown): Error {
+  const said = new Error(errorMessage(err))
+  return needsUser(err) ? Object.assign(said, { needsUser: true }) : said
+}
+
 /** An error's text, whatever was thrown (never throws itself). */
 function errorMessage(error: unknown): string {
   try {
diff --git a/packages/agent/src/tool-result.ts b/packages/agent/src/tool-result.ts
index 882a711..0950340 100644
--- a/packages/agent/src/tool-result.ts
+++ b/packages/agent/src/tool-result.ts
@@ -79,15 +79,31 @@ export const unknownTool = (tool: string): ToolFailure => ({
     `Pick a valid tool for this step, or answer directly if none applies.`,
 })
 
+/** How a failure the user settles (an app they must allow) ends, for the model: never retried. */
+export const USER_SETTLES = "The user settles this: tell them, and don't retry."
+
+/** Whether a thrown failure is one the user settles (never throws: a throwing getter is no). */
+export function needsUser(err: unknown): boolean {
+  try {
+    return (err as { needsUser?: unknown } | null | undefined)?.needsUser === true
+  } catch {
+    return false
+  }
+}
+
 /** A tool threw while running (e.g. a managed service 500 or a network error). */
 export const toolThrew = (tool: string, err: unknown): ToolFailure => ({
   ok: false,
   error: "tool_error",
   tool,
   message:
-    `The "${tool}" tool failed with an error: ${err instanceof Error ? err.message : String(err)}. ` +
-    `You may retry once if this looks transient; otherwise continue without it and ` +
-    `tell the user what could not be completed.`,
+    // Something the user settles (an app they must allow): never retried.
+    needsUser(err)
+      ? `The "${tool}" tool can't go on: ${err instanceof Error ? err.message : String(err)}. ` +
+        USER_SETTLES
+      : `The "${tool}" tool failed with an error: ${err instanceof Error ? err.message : String(err)}. ` +
+        `You may retry once if this looks transient; otherwise continue without it and ` +
+        `tell the user what could not be completed.`,
 })
 
 /** The user stopped the run before or while this call ran: not a failure of the tool. */
diff --git a/packages/agent/test/agent-loop.test.ts b/packages/agent/test/agent-loop.test.ts
index 8fae268..b260c8c 100644
--- a/packages/agent/test/agent-loop.test.ts
+++ b/packages/agent/test/agent-loop.test.ts
@@ -899,3 +899,22 @@ describe("untilStopped", () => {
     await expect(untilStopped(failing, stopped.signal)).rejects.toThrow()
   })
 })
+
+describe("runAgent: a failure the user settles", () => {
+  it("tells the model to tell the user, never to retry (the tool's flag kept through the loop)", async () => {
+    const refused = defineTool<Ctx, z.ZodObject<Record<string, never>>>({
+      name: "snapshot",
+      description: "Refused",
+      parameters: z.object({}),
+      run: () =>
+        Promise.reject(Object.assign(new Error("notes isn't allowed here"), { needsUser: true })),
+    })
+    const { llm } = scripted([{ kind: "tool_calls", calls: [call("c1", "snapshot", {})] }])
+    const events = await collect(
+      runAgent({ userMessage: "go", tools: [refused], llm, context: { log: [] } }),
+    )
+    const [result] = events.flatMap((e) => (e.type === "tool_result" ? [e.result] : []))
+    expect(JSON.stringify(result)).toContain("The user settles this: tell them, and don't retry")
+    expect(JSON.stringify(result)).not.toContain("retry once")
+  })
+})
diff --git a/packages/agent/test/tool-result.test.ts b/packages/agent/test/tool-result.test.ts
index 322d04a..3b1f473 100644
--- a/packages/agent/test/tool-result.test.ts
+++ b/packages/agent/test/tool-result.test.ts
@@ -68,3 +68,15 @@ describe("tool-result contract", () => {
     expect(isToolFailure(r)).toBe(true) // one uniform "did it fail?" check across all origins
   })
 })
+
+describe("a tool that threw something the user settles", () => {
+  it("never invites a retry (the user settles it: the agent tells them)", () => {
+    const settles = Object.assign(new Error("notes: not allowed in this project yet"), {
+      needsUser: true,
+    })
+    const said = toolThrew("snapshot", settles).message
+    expect(said).toContain("The user settles this: tell them, and don't retry.")
+    expect(said).not.toContain("retry once")
+    expect(toolThrew("snapshot", new Error("boom")).message).toContain("retry once")
+  })
+})
diff --git a/packages/runtime/src/electron-confine.ts b/packages/runtime/src/electron-confine.ts
index 4ff35fc..b17070a 100644
--- a/packages/runtime/src/electron-confine.ts
+++ b/packages/runtime/src/electron-confine.ts
@@ -138,7 +138,7 @@ const same = (now: Stats, checked: Stats, kind: "dir" | "file") =>
   now.dev === checked.dev
 
 const changed = (rel: string) =>
-  new FilesError(`files${rel} changed while it was copied: try again`)
+  new FilesError(`files${rel} changed while it was copied: ask again in a moment`)
 
 /**
  * A project's `files/` copied into a launch's sandbox (what the app opens: every run from the same
@@ -209,9 +209,9 @@ export async function copyFiles(from: string, to: string, signal?: AbortSignal):
       code === "ENOENT"
         ? existsSync(from)
           ? // Something in it gone while it was copied (moved, swapped): said as such.
-            "files/ changed while it was copied: try again"
+            "files/ changed while it was copied: ask again in a moment"
           : "the project has no files/ folder (what its arguments name)"
-        : `files/ couldn't be copied (${code ?? String(error)})`,
+        : `files/ couldn't be copied (${code ?? "an error"})`,
     )
   }
 }
@@ -223,7 +223,7 @@ export async function copyFiles(from: string, to: string, signal?: AbortSignal):
 export function argumentIn(arg: string, filesCopy: string): string {
   const parts = filesPath(arg)
   if (parts === undefined) {
-    throw new FilesError(`"${arg}": a desktop app opens only what's in the project's files/`)
+    throw new FilesError("a desktop app opens only what's in the project's files/ (files/<name>)")
   }
   return join(filesCopy, ...parts)
 }
diff --git a/packages/runtime/src/electron-workarea.ts b/packages/runtime/src/electron-workarea.ts
index 806e858..64df601 100644
--- a/packages/runtime/src/electron-workarea.ts
+++ b/packages/runtime/src/electron-workarea.ts
@@ -42,15 +42,18 @@ export function sandboxesOf(work: string): string {
       mkdirSync(dir, { recursive: true, mode: 0o700 })
       stat = lstatSync(dir)
     } catch (error) {
+      // Never its path (said to the agent): the work area by name, the failure by its code.
       throw new WorkAreaError(
-        `${dir} can't be made (${(error as { code?: string }).code ?? String(error)})`,
+        `Kiframe's work area can't be made (${(error as { code?: string }).code ?? "unwritable"})`,
       )
     }
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
-      throw new WorkAreaError(`${dir} isn't a folder (a link?): Kiframe uses only a real one`)
+      throw new WorkAreaError(
+        "Kiframe's work area isn't a real folder (a link?): Kiframe uses only a real one",
+      )
     }
     if (process.getuid !== undefined && stat.uid !== process.getuid()) {
-      throw new WorkAreaError(`${dir} belongs to another user`)
+      throw new WorkAreaError("Kiframe's work area belongs to another user")
     }
     if ((stat.mode & 0o777) !== 0o700) chmodSync(dir, 0o700)
   }
diff --git a/packages/runtime/src/electron.ts b/packages/runtime/src/electron.ts
index abf46ae..c2d85c2 100644
--- a/packages/runtime/src/electron.ts
+++ b/packages/runtime/src/electron.ts
@@ -102,7 +102,10 @@ export function launchFailure(
 ): unknown {
   if (state.stopped !== undefined) return state.stopped
   if (state.spawnError !== undefined) {
-    return new ElectronLaunchError(`the app couldn't be launched (${state.spawnError.message})`)
+    // Its code only (an OS message names the executable's path: never said to the agent).
+    return new ElectronLaunchError(
+      `the app couldn't be launched (${(state.spawnError as { code?: string }).code ?? "it couldn't run"})`,
+    )
   }
   // What the app showed (a site, a page it never loaded): kept, whatever the app did next.
   if (error instanceof ElectronLaunchError && (error.why === "site" || error.why === "unloaded")) {
@@ -298,7 +301,9 @@ async function makeSandbox(work: string): Promise<{
     root = await newSandbox(work)
   } catch (error) {
     if (error instanceof WorkAreaError) throw new ElectronLaunchError(error.message)
-    throw new ElectronLaunchError(`Kiframe's work area can't be used (${String(error)})`)
+    throw new ElectronLaunchError(
+      `Kiframe's work area can't be used (${(error as { code?: string }).code ?? "unusable"})`,
+    )
   }
   const dirs = {
     home: join(root, "home"),
@@ -313,7 +318,9 @@ async function makeSandbox(work: string): Promise<{
     for (const dir of Object.values(dirs)) mkdirSync(dir, { recursive: true })
   } catch (error) {
     await rm(root, { recursive: true, force: true }).catch(() => undefined)
-    throw new ElectronLaunchError(`the app's sandbox can't be made (${String(error)})`)
+    throw new ElectronLaunchError(
+      `the app's sandbox can't be made (${(error as { code?: string }).code ?? "unwritable"})`,
+    )
   }
   const env: NodeJS.ProcessEnv = {}
   for (const name of PASSED_ENV) if (process.env[name] !== undefined) env[name] = process.env[name]
@@ -364,14 +371,14 @@ export async function launchElectronWith(
     // As given and as it really is: an app may build its pages' paths either way.
     bundles = opts.bundle === undefined ? [] : [opts.bundle, realpathSync(opts.bundle)]
   } catch {
-    throw new ElectronLaunchError(`the app isn't at ${opts.bundle ?? ""} any more`)
+    throw new ElectronLaunchError("the app isn't where it was approved any more")
   }
   // The executable there and runnable (under Seatbelt the spawned program is sandbox-exec: a
   // missing app would otherwise read as one that quit).
   try {
     accessSync(opts.executable, constants.X_OK)
   } catch {
-    throw new ElectronLaunchError(`the app couldn't be launched (${opts.executable} isn't there)`)
+    throw new ElectronLaunchError("the app couldn't be launched (its executable isn't there)")
   }
   // Never unconfined in the app: off macOS (no Seatbelt) only where asked (Linux CI).
   const confined = process.platform === "darwin"
@@ -681,7 +688,11 @@ function debuggingEndpoint(
     const poll = setInterval(() => {
       const failed = spawnError()
       if (failed !== undefined) {
-        finish(new ElectronLaunchError(`the app couldn't be launched (${failed.message})`))
+        finish(
+          new ElectronLaunchError(
+            `the app couldn't be launched (${(failed as { code?: string }).code ?? "it couldn't run"})`,
+          ),
+        )
         return
       }
       try {
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index c141306..d8bd3e9 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -14,6 +14,7 @@ export {
   ElectronLaunchError,
   type ElectronTarget,
   launchElectron,
+  placeOf,
 } from "./electron.ts"
 export { defaultWorkDir, sweepWorkArea, WorkAreaError } from "./electron-workarea.ts"
 export {
@@ -42,3 +43,4 @@ export { normalizeText } from "./text-match.ts"
 export { viewOf, type PageView } from "./scroller.ts"
 export { addKnownValues, isSafeSelector, knownValuesOf } from "./secret-state.ts"
 export * from "./batch.ts"
+export { viewportWithin } from "./run/secrets.ts"
diff --git a/packages/runtime/src/run/secrets.ts b/packages/runtime/src/run/secrets.ts
index adfb430..df2f0d4 100644
--- a/packages/runtime/src/run/secrets.ts
+++ b/packages/runtime/src/run/secrets.ts
@@ -449,8 +449,9 @@ async function resolveSecret(
  * screen, shown to them only (APPROACHES §0: never masked; it never reaches the agent or a take).
  */
 async function pageShot(page: Page): Promise<ApprovalRequest["shot"]> {
-  const size = page.viewportSize()
-  if (size === null) return undefined
+  // Read from the page when the context sets none (a desktop app's: never shown without a shot).
+  const size = await viewportWithin(page, 3000)
+  if (size === undefined) return undefined
   const jpeg = await page
     .screenshot({ type: "jpeg", quality: 75, timeout: 3000, caret: "initial", animations: "allow" })
     .catch(() => undefined)
diff --git a/packages/runtime/test/electron.test.ts b/packages/runtime/test/electron.test.ts
index 1937f86..fba3ffe 100644
--- a/packages/runtime/test/electron.test.ts
+++ b/packages/runtime/test/electron.test.ts
@@ -599,9 +599,16 @@ else setInterval(() => undefined, 60_000)
     const raw = new Error("connect ECONNREFUSED ws://127.0.0.1:9/devtools/browser/x")
     const none = { stopped: undefined, spawnError: undefined, quit: false }
     expect(launchFailure(raw, { ...none, stopped: stop, quit: true })).toBe(stop)
+    // A spawn error is said by its code: its message names the executable's local path.
+    const spawnError = Object.assign(new Error("spawn /Users/me/Notes.app/x ENOENT"), {
+      code: "ENOENT",
+    })
+    const spawned = String(launchFailure(raw, { ...none, spawnError, quit: true }))
+    expect(spawned).toMatch(/couldn't be launched \(ENOENT\)/)
+    expect(spawned).not.toContain("/Users")
     expect(
-      String(launchFailure(raw, { ...none, spawnError: new Error("ENOENT"), quit: true })),
-    ).toMatch(/couldn't be launched \(ENOENT\)/)
+      String(launchFailure(raw, { ...none, spawnError: new Error("/Users/me/x"), quit: true })),
+    ).toBe("Error: the app couldn't be launched (it couldn't run)")
     // Already said (a site to allow, a page never loaded) stays said, even if the app then quit.
     const site = new ElectronLaunchError("site", { why: "site", site: "https://a.example" })
     expect(launchFailure(site, { ...none, quit: true })).toBe(site)
@@ -1058,12 +1065,19 @@ steps:
   })
 
   it("says an app that isn't there any more, or can't start, never crashing the host", async () => {
-    await expect(launchElectron({ ...base, bundle: "/Applications/Gone.app" })).rejects.toThrow(
-      "the app isn't at /Applications/Gone.app any more",
+    // Said without a path (the agent reads a launch's error: never the user's folders).
+    const gone = await launchElectron({ ...base, bundle: "/Applications/Gone.app" }).catch(
+      (e: unknown) => String(e),
     )
-    await expect(
-      launchElectron({ ...base, executable: "/no/such/executable", timeoutMs: 5000 }),
-    ).rejects.toThrow(/the app couldn't be launched/)
+    expect(gone).toContain("the app isn't where it was approved any more")
+    expect(gone).not.toContain("/Applications")
+    const missing = await launchElectron({
+      ...base,
+      executable: "/no/such/executable",
+      timeoutMs: 5000,
+    }).catch((e: unknown) => String(e))
+    expect(missing).toMatch(/the app couldn't be launched/)
+    expect(missing).not.toContain("/no/such")
   })
 
   it("keeps a desktop scene in its app: no goto, URL condition or web preset there", async () => {
@@ -1556,6 +1570,6 @@ describe("the work area", () => {
     expect(statSync(join(own, "sandboxes")).mode & 0o777).toBe(0o700)
     const linked = join(mkdtempSync(join(tmpdir(), "kiframe-el-link-")), "work")
     symlinkSync(own, linked)
-    expect(() => sandboxesOf(linked)).toThrow(/isn't a folder/)
+    expect(() => sandboxesOf(linked)).toThrow(/isn't a real folder/)
   })
 })
diff --git a/packages/studio/src/prompt.ts b/packages/studio/src/prompt.ts
index 533d06d..c1d875d 100644
--- a/packages/studio/src/prompt.ts
+++ b/packages/studio/src/prompt.ts
@@ -143,8 +143,13 @@ function appsPart(studio: Studio): string {
     .join("\n")
   return `Apps of the project (a scene may use several; never any other site):
 ${list}
-- A desktop app (one listed as "the desktop app …") can't be grounded or run yet: give every scene
-  and preset a web app (\`app: <name>\` when the first app is a desktop one).
+- A desktop app (one listed as "the desktop app …") is grounded and filmed like a web app (snapshot,
+  run_step, save_scene, record_scene), in its own window: its scene starts in it (\`app: <name>\`
+  and \`start_app\`); it shows its own pages, so no goto, URL condition or web preset there; one app
+  per scene (switching a scene to another app starts that app afresh: what earlier steps did there
+  is gone). Nothing in a desktop app is handed to the user yet (no handover step: sign-in by hand
+  comes next). A desktop app that won't open says why: the user settles it (the Apps panel); tell
+  them, never retry.
 - A scene starts in the first app unless it says another at the top level, next to version:
   \`app: <name>\`. Pass the same as \`start_app\` to run_step and run_steps while you ground it.
 - A step without an app means the scene's start app, NEVER the app the page went to (a link, a
@@ -152,5 +157,7 @@ ${list}
   condition \`{ action: waitFor, until: { url: /path, app: <name> } }\` (same in expect's \`that\`).
   Only goto and URL conditions take an app (never a click).
 - Where a step leaves the page says its app: \`url: docs: /install\`.
+- snapshot and look show the app that's open: with none open yet, open the scene's app first (a
+  run_step with its start_app; a pause step does nothing else).
 ${adding}`
 }
diff --git a/packages/studio/src/studio.ts b/packages/studio/src/studio.ts
index b912fc8..e0d6c27 100644
--- a/packages/studio/src/studio.ts
+++ b/packages/studio/src/studio.ts
@@ -1,3 +1,4 @@
+import { needsUser, USER_SETTLES } from "@kiframe/agent"
 import { generate } from "@kiframe/generators"
 import {
   type OpenedProject,
@@ -37,6 +38,10 @@ import {
   fitImage,
   type FittedImage,
   ImageRefusal,
+  viewportWithin,
+  type ElectronTarget,
+  placeOf,
+  type RunOptions,
 } from "@kiframe/runtime"
 import {
   ACTION_REFERENCE,
@@ -63,6 +68,8 @@ import {
   webAppsOf,
   firstApp,
   startAppOf,
+  type TakeMeta,
+  appIdentity,
 } from "@kiframe/schema"
 import type { Browser, BrowserContext, ElementHandle, Page } from "playwright"
 import { parse as parseYaml } from "yaml"
@@ -232,6 +239,15 @@ export interface StudioOptions {
    * None: nothing is ever evicted (tests, a CLI that knows one project only).
    */
   afterRecord?: () => void
+  /**
+   * Launches the project's desktop app `app` (the host's: from its approval, confined), with the
+   * build a take keeps. A refusal the user settles (in the Apps panel) has `needsUser`. None:
+   * desktop apps can't be grounded or recorded (a CLI, tests of web apps).
+   */
+  launchDesktop?: (
+    app: string,
+    signal: AbortSignal,
+  ) => Promise<{ target: ElectronTarget; build: NonNullable<TakeMeta["appBuild"]> }>
 }
 
 /** How long a step may take on a real app (Cal.com's login hydrates in more than 6 s). */
@@ -241,7 +257,15 @@ export const SNAPSHOT_MAX = 20_000
 
 export class Studio {
   readonly options: StudioOptions
-  #live: { context: BrowserContext; page: Page } | undefined
+  /**
+   * The live page: its context and page, the app it's at, and (a desktop app) its launched target,
+   * closed whole with it.
+   */
+  #live: Live | undefined
+  /** Said with the next tool's result once (a desktop app that quit, launched again). */
+  #notice: string | undefined
+  /** The live page's close under way (one close, however many ask). */
+  #closing: { live: Live; done: Promise<void> } | undefined
   /**
    * The saved sign-in (memory only, gone with the studio: it holds a session's cookies): one
    * browser state, and the session presets it holds (each its key: its steps and the apps as they
@@ -270,12 +294,9 @@ export class Studio {
   #checked: Map<string, SnapshotNode> | undefined
   /** Aborted when the studio closes: every tool and dialog stops (the tools' signal includes it). */
   readonly #lifetime = new AbortController()
-  /**
-   * Where the live page opens: the first web app, as the project's apps are now (a desktop app has
-   * its own driver, next).
-   */
+  /** The project's first web app, as its apps are now (where a web-only default opens). */
   get #start(): WebApp | undefined {
-    return Object.values(this.options.config.apps).find((a): a is WebApp => a.kind === "web")
+    return Object.values(webAppsOf(this.options.config.apps))[0]
   }
   #files: ProjectFiles | undefined
   #fileReads: Map<string, FileNote> | undefined
@@ -391,6 +412,9 @@ export class Studio {
    */
   setApps(apps: ProjectConfig["apps"]): void {
     this.options.config = { ...this.options.config, apps }
+    // A live app the project no longer lists, or lists as another app (removed: its approval
+    // dropped): closed (a tool meanwhile never gets its page: `livePage` checks it too).
+    if (this.#live !== undefined && !this.#listed(this.#live)) void this.#closeLive()
     // The page may be on the removed site: its refs are never used (the agent looks again).
     this.#snapshot = undefined
     this.#checked = undefined
@@ -410,8 +434,8 @@ export class Studio {
     return result
   }
 
-  /** The live page being opened (one at a time: a second caller waits for it). */
-  #opening: Promise<Page> | undefined
+  /** The live page being opened: for which app, and the call that owns it (its stop ends it). */
+  #opening: { app: string; desktop: boolean; page: Promise<Page>; owner: AbortSignal } | undefined
 
   constructor(options: StudioOptions) {
     this.options = options
@@ -610,7 +634,8 @@ export class Studio {
     ref?: string,
     signal?: AbortSignal,
   ): Promise<{ text: string; image: string } | { error: string }> {
-    const page = await this.livePage()
+    if (this.#appFor(undefined) === undefined) return { error: NO_APP_OPEN }
+    const page = await this.livePage(undefined, signal ?? this.#lifetime.signal)
     // A ref's box, measured in both scans around the capture (it must not move); the image is its
     // part on screen (an `at` fraction maps onto the image only when it's whole). Never scrolled
     // to: a look changes nothing on the page (a replay would never see that scroll).
@@ -632,7 +657,8 @@ export class Studio {
       }
       measure = async () => {
         const box = await target.boundingBox({ timeout: 2000 }).catch(() => null)
-        const view = page.viewportSize()
+        // Read from the page when the context sets none (a desktop app's window).
+        const view = (await viewportWithin(page, 3000)) ?? null
         if (box === null || view === null) return null
         whole = box
         const x1 = Math.max(0, box.x)
@@ -653,7 +679,10 @@ export class Studio {
         const box = whole
         const range = (from: number, size: number, total: number) =>
           `${(Math.max(0, -from) / size).toFixed(2)}–${(Math.min(size, total - from) / size).toFixed(2)}`
-        const view = page.viewportSize() ?? { width: shot.width, height: shot.height }
+        const view = (await viewportWithin(page, 3000)) ?? {
+          width: shot.width,
+          height: shot.height,
+        }
         const all = shot.width >= Math.floor(box.width) && shot.height >= Math.floor(box.height)
         what = all
           ? `ref ${ref}, ${Math.round(box.width)}×${Math.round(box.height)}: an \`at\` fraction on it is a position in this image`
@@ -661,7 +690,7 @@ export class Studio {
       }
       const masked = shot.masked > 0.5 ? " Most of it is masked (it shows secrets)." : ""
       return {
-        text: `The live page (url: ${this.#where(page.url())}), ${what}.${masked}`,
+        text: `The live page (url: ${this.#where(page.url())}), ${what}.${masked}${this.#told()}`,
         image: `data:image/png;base64,${shot.png.toString("base64")}`,
       }
     } catch (error) {
@@ -670,6 +699,12 @@ export class Studio {
       // Said when it's how the look was asked (it won't change); else never why (a retry's reason
       // could tell what changed on the page).
       if (error instanceof LookRefusal) return { error: `couldn't look: ${error.message}` }
+      // Why, for Kiframe's own debugging only (stderr, when asked): never the agent's.
+      if (process.env.KIFRAME_ELECTRON_DEBUG !== undefined) {
+        process.stderr.write(
+          `[look] ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`,
+        )
+      }
       return { error: "couldn't look at the page now: try again in a moment" }
     }
   }
@@ -690,7 +725,16 @@ export class Studio {
     | { outcome: "done" | "declined"; note?: string; url: string; title: string; took_s: number }
     | { error: string }
   > {
-    await this.livePage()
+    // A desktop app's (live, or the one that would open): refused before anything launches.
+    const opens = this.#appFor(undefined)
+    if (opens === undefined) return { error: NO_APP_OPEN }
+    if (
+      this.#live?.target !== undefined ||
+      (this.#live === undefined && appOf(this.options.config, opens)?.kind === "electron")
+    ) {
+      return { error: NO_DESKTOP_HANDOVER }
+    }
+    await this.livePage(undefined, signal)
     const live = this.#live
     if (live === undefined) return { error: "there's no live page to hand over" }
     const started = Date.now()
@@ -858,37 +902,150 @@ export class Studio {
     return this.#live !== undefined && !this.#live.page.isClosed() ? this.#live.page : undefined
   }
 
-  /** The page the agent explores and grounds on (opened at the app on first use). */
-  async livePage(): Promise<Page> {
+  /**
+   * The app a live page is for: the one asked, else what's live, else the only app that can open
+   * here (a desktop app only with a launcher). Several and none asked: undefined, never a guess
+   * (the agent opens the scene's app with a step first). Decided once, before anything opens.
+   */
+  #appFor(app: string | undefined): string | undefined {
+    if (app !== undefined) return app
+    if (this.#live !== undefined) return this.#live.app
+    const { apps } = this.options.config
+    const openable = Object.keys(this.options.launchDesktop === undefined ? webAppsOf(apps) : apps)
+    if (openable.length === 1) return openable[0]
+    // None openable here (a desktop-only project, no launcher): its first, said as such on opening.
+    return openable.length === 0 ? firstApp(this.options.config).name : undefined
+  }
+
+  /**
+   * The page the agent explores and grounds on, at `app` (see `#appFor`). A desktop app's live
+   * launch is closed for another app (one app per window); a web app's context stays between web
+   * apps (its sign-in kept). A desktop launch is owned by the call that started it (stopped with it
+   * or the studio, never joined): one whose caller stopped is waited out (it never becomes live);
+   * a web page opening is shared (one page for callers at once).
+   */
+  async livePage(app: string | undefined, signal: AbortSignal): Promise<Page> {
+    const wanted = this.#appFor(app)
+    if (wanted === undefined) throw new NoAppOpen()
+    const opening = this.#opening
+    // A web page opening (at once, never stopped midway): one page for callers at once.
+    if (opening !== undefined && !opening.desktop && opening.app === wanted) return opening.page
+    // Never yields when none is (callers at once see each other's opening).
+    if (opening !== undefined) await this.#launchSettled(true)
+    const desktop = appOf(this.options.config, wanted)?.kind === "electron"
+    if (
+      this.#live !== undefined &&
+      (!this.#listed(this.#live) ||
+        (this.#live.app !== wanted && (this.#live.target !== undefined || desktop)))
+    ) {
+      await this.#closeLive()
+    }
     if (this.#live !== undefined && !this.#live.page.isClosed()) return this.#live.page
     // The page the runner followed may have closed (a popup): back on another page still open.
     const back = this.#backPage()
     if (back !== undefined) return back
-    this.#opening ??= this.#open().finally(() => {
-      this.#opening = undefined
-    })
-    return this.#opening
+    // A desktop app with no window left: it quit (launched again; said once it is).
+    const quit = this.#live?.target !== undefined ? (this.#live.app ?? "the app") : undefined
+    const page = this.#open(wanted, AbortSignal.any([signal, this.#lifetime.signal])).then(
+      (opened) => {
+        if (quit !== undefined) {
+          this.#notice = `${quit} quit: launched again fresh (what earlier steps did is gone)`
+        }
+        return opened
+      },
+    )
+    this.#opening = { app: wanted, desktop, page, owner: signal }
+    void page
+      .finally(() => {
+        if (this.#opening?.page === page) this.#opening = undefined
+      })
+      .catch(() => undefined)
+    return page
   }
 
-  async #open(): Promise<Page> {
+  /** Whether the project still lists the live page's app, the same one it opened. */
+  #listed(live: { app: string; identity: string }): boolean {
+    const now = appOf(this.options.config, live.app)
+    return now !== undefined && appIdentity(now) === live.identity
+  }
+
+  /**
+   * A desktop launch still going ended first: one whose caller stopped waited out, one still owned
+   * refused (never two launches at once).
+   */
+  async #launchSettled(anyOpening = false): Promise<void> {
+    const opening = this.#opening
+    if (opening === undefined || (!opening.desktop && !anyOpening)) return
+    // The agent's calls come one at a time: one still going is one whose caller stopped.
+    if (!opening.owner.aborted) {
+      throw new Error(`"${opening.app}" is still opening: try again in a moment`)
+    }
+    await opening.page.catch(() => undefined)
+  }
+
+  /** The live page closed whole (a desktop app's target: its process and sandbox too). */
+  async #closeLive(): Promise<void> {
+    const live = this.#live
+    if (live === undefined) return
+    // Closed once (the user's removal and a tool's call at once): every caller waits for it.
+    if (this.#closing?.live !== live) {
+      const done = this.#closeOf(live)
+      this.#closing = { live, done }
+      void done.finally(() => {
+        if (this.#closing?.done === done) this.#closing = undefined
+      })
+    }
+    await this.#closing.done
+  }
+
+  async #closeOf(live: Live): Promise<void> {
     // A handover on it still reading its fields: done first (what the user typed made known).
-    if (this.#live !== undefined) await this.#settled()
-    await this.#live?.context.close().catch(() => undefined)
-    this.#live = undefined
-    // A desktop app has its own driver (the Electron target, next): never a page here.
-    const start = this.#start
-    if (start === undefined) {
-      throw new Error("desktop apps can't be grounded yet: the Electron target comes next")
+    await this.#settled()
+    if (this.#live === live) {
+      this.#live = undefined
+      // Its refs went with it (a step's on another app's page: never resolved there).
+      this.#snapshot = undefined
+      this.#checked = undefined
+    }
+    await (live.target !== undefined ? live.target.close() : live.context.close()).catch(
+      () => undefined,
+    )
+  }
+
+  /**
+   * Opens `name`'s live page: a desktop app launched (stopped by `stops`: a stop or the studio's
+   * close ends it, never kept), a web app's page at its address. Kept only if the project still
+   * lists that app, the same (removed or changed meanwhile: closed).
+   */
+  async #open(name: string, stops: AbortSignal): Promise<Page> {
+    await this.#closeLive()
+    const start = appOf(this.options.config, name)
+    if (start === undefined) throw new Error(`"${name}" isn't one of the project's apps`)
+    const identity = appIdentity(start)
+    const stillListed = () => this.#listed({ app: name, identity })
+    if (start.kind === "electron") {
+      const launch = this.options.launchDesktop
+      if (launch === undefined) {
+        throw new Error(`"${name}" is a desktop app: none can be opened here`)
+      }
+      const { target } = await launch(name, stops)
+      if (stops.aborted || !stillListed()) {
+        await target.close().catch(() => undefined)
+        throw stops.aborted ? (stops.reason as Error) : new Error(`"${name}" was removed`)
+      }
+      this.#live = { context: target.context, page: target.page, app: name, identity, target }
+      return target.page
     }
     const { width, height } = start.viewport
     const context = await this.options.browser.newContext({ viewport: { width, height } })
     try {
       const page = await context.newPage()
       await page.goto(start.url)
-      // Closed meanwhile: never kept (nothing would close it).
+      // Closed meanwhile, or the app removed meanwhile: never kept (nothing would close it).
       if (this.#lifetime.signal.aborted) throw new Error("the studio was closed")
+      if (!stillListed()) throw new Error(`"${name}" was removed`)
       // Kept only once it's at the app (a failed first visit is tried again next time).
-      this.#live = { context, page }
+      this.#live = { context, page, app: name, identity }
       return page
     } catch (error) {
       await context.close().catch(() => undefined)
@@ -907,13 +1064,56 @@ export class Studio {
   }
 
   #where(url: string, site?: Site): string {
+    // A desktop app's page: its own or not, by its guard (never its file path: the user's).
+    const target = this.#live?.target
+    if (target !== undefined) {
+      return target.allows(url)
+        ? `${this.#live?.app ?? "the app"}'s own page`
+        : `${placeOf(url)} (not the app's own)`
+    }
     // Named whenever the project has several apps (a desktop one too: the prompt lists them all).
     const { apps } = this.options.config
     return whereOf(url, webAppsOf(apps), site, Object.keys(apps).length > 1)
   }
 
+  /**
+   * A snapshot's link addresses: a desktop app's said by its guard as its page is (a `file:` link
+   * names the user's folders: never to the agent); a web app's as they are.
+   */
+  #linksSaid(text: string, base: string): string {
+    if (this.#live?.target === undefined) return text
+    return text.replace(/^(\s*- \/url: )(.*)$/gm, (_line, lead: string, raw: string) => {
+      // As written in the page (a relative one too): read against the page's own address.
+      const href = raw.replace(/^(["'])(.*)\1$/, "$2")
+      const url = URL.parse(href, base)?.href ?? href
+      return `${lead}${JSON.stringify(this.#where(url))}`
+    })
+  }
+
+  /** A note once (a desktop app launched again), then nothing. */
+  #told(): string {
+    const notice = this.#notice
+    this.#notice = undefined
+    return notice === undefined ? "" : `\nnote: ${notice}`
+  }
+
   /** A step done, and where its page is: a page that failed to load makes it a failure. */
   #landed(url: string, said: string): StepResult {
+    if (this.#live?.target !== undefined) {
+      if (url.startsWith("chrome-error:")) {
+        return {
+          ok: false,
+          text: "failed (page-not-loaded): the page failed to load: try again",
+          site: "unloaded",
+        }
+      }
+      const own = this.#live.target.allows(url)
+      return {
+        ok: true,
+        text: `${said}. url: ${this.#where(url)}${this.#told()}`,
+        site: own ? "app" : "other",
+      }
+    }
     const site = siteOf(url, webAppsOf(this.options.config.apps))
     if (site === "unloaded") {
       return {
@@ -929,11 +1129,12 @@ export class Studio {
    * The live page's accessibility snapshot (or one region's), with its URL; with `find`, only the
    * parts that mention it (a long page's content past the cut).
    */
-  async snapshot(within?: unknown, find?: string): Promise<StepResult> {
+  async snapshot(within?: unknown, find?: string, signal?: AbortSignal): Promise<StepResult> {
     // Its refs are gone whatever this one gives (as Playwright's are).
     this.#snapshot = undefined
     this.#checked = undefined
-    const page = await this.livePage()
+    if (this.#appFor(undefined) === undefined) return failed(NO_APP_OPEN)
+    const page = await this.livePage(undefined, signal ?? this.#lifetime.signal)
     let root = page.locator("body")
     if (within !== undefined) {
       const parsed = Locator.safeParse(asObject(within))
@@ -980,7 +1181,7 @@ export class Studio {
     }
     // Scrubbed whole, then searched and cut: a value the cut splits would pass the scrubber in
     // part, and a search before scrubbing would tell a guess of a value from a miss.
-    const scrubbed = this.scrub(text)
+    const scrubbed = this.#linksSaid(this.scrub(text), page.url())
     const found = find === undefined ? undefined : findInSnapshot(scrubbed, find)
     const shown = found === undefined ? scrubbed : found.text
     const where = within === undefined ? "page" : "region"
@@ -1005,7 +1206,7 @@ export class Studio {
         : `\n(${unusable}: its refs can't be used; snapshot again to point at them, or write locators)`
     return {
       ok: true,
-      text: `url: ${this.#where(page.url())}${within === undefined ? await this.#view(page) : ""}${note}${nearly}\n${cut}`,
+      text: `url: ${this.#where(page.url())}${within === undefined ? await this.#view(page) : ""}${note}${nearly}${this.#told()}\n${cut}`,
     }
   }
 
@@ -1034,7 +1235,7 @@ export class Studio {
     const refs = refsAt(items)
     const now = this.#refusedNow(refs)
     if (now !== undefined || refs.length === 0) return now
-    const fresh = await this.#fresh(await this.livePage(), refs, signal)
+    const fresh = await this.#fresh(await this.livePage(undefined, signal), refs, signal)
     if ("error" in fresh) return fresh.error
     for (const { ref } of refs) {
       const why = this.#refused(ref, fresh.nodes)
@@ -1155,16 +1356,31 @@ export class Studio {
         `start_app: "${app}" isn't one of the project's apps (${Object.keys(this.options.config.apps).join(", ")})`,
       )
     }
-    if (starts.kind !== "web") {
-      return failed(
-        `start_app: "${app}" is a desktop app: desktop apps can't be grounded yet (the Electron target comes next)`,
-      )
+    if (starts.kind !== "web" && this.options.launchDesktop === undefined) {
+      return failed(`start_app: "${app}" is a desktop app: none can be grounded here`)
     }
+    // Checked before any launch (a step that never runs never closes or opens an app).
     const raw = asObject(input)
     if (isCyclic(raw))
       return failed("invalid step: a YAML alias refers to itself (or it nests too deep)")
     // Before any of its refs is looked at: it never runs anyway.
     if (typeof raw === "object" && raw !== null && "ensure" in raw) return failed(NO_CLEANUP)
+    // Its shape too, each ref as a plain locator (what it becomes is checked once it's written).
+    const shaped = refsAt(raw).reduce<unknown>(
+      (item, at) => withAt(item, at.path, { by: "role", role: "button" }),
+      raw,
+    )
+    const invalid = invalidItem(shaped, part)
+    if (invalid !== undefined) return invalid
+    // The scene's app live first: its refs are that page's (another app's: a new snapshot asked).
+    if (starts.kind === "electron" || this.#live?.target !== undefined) {
+      try {
+        await this.livePage(app, signal)
+      } catch (error) {
+        if (isStopped(error) || signal.aborted) throw error
+        return failed(refusal(error))
+      }
+    }
     const refs = refsAt(raw)
     if (refs.length === 0) {
       this.#checked = undefined
@@ -1198,7 +1414,7 @@ export class Studio {
     part: ScenarioPart,
     signal: AbortSignal,
   ): Promise<{ value: unknown } | { error: string }> {
-    const page = await this.livePage()
+    const page = await this.livePage(undefined, signal)
     // The page as it is right now (the steps before changed it): each ref checked in a fresh
     // snapshot, and resolved against it (no other snapshot in between: it'd replace Playwright's refs).
     const checked = this.#checked
@@ -1244,40 +1460,16 @@ export class Studio {
     part: ScenarioPart,
     app: string,
   ): Promise<StepResult> {
-    if (typeof raw !== "object" || raw === null) {
-      return failed(
-        "invalid step: expected an object like {id: open-new, action: click, target: {...}}",
-      )
+    const invalid = invalidItem(raw, part)
+    if (invalid !== undefined || typeof raw !== "object" || raw === null) {
+      return invalid ?? failed("invalid step")
     }
     // Run in the part it's for: its approvals are keyed there, as the replay's will be (A1).
     const step = part === "steps" ? Step.safeParse(raw) : { success: false as const }
-    // In the steps, only a preset runs as the setup (it's setup-only).
     const setupItem =
       step.success || (part === "steps" && !("preset" in raw))
         ? undefined
         : SetupItem.safeParse(raw)
-    if (!step.success && setupItem?.success !== true) {
-      const r = raw as Record<string, unknown>
-      // An off-camera-only kind (a handover) on camera: said as such (an id would never do).
-      if (part === "steps" && typeof r.action === "string" && isOffCameraOnly(r.action)) {
-        return failed(`invalid step: ${OFF_CAMERA_MESSAGE}: give its part (setup)`)
-      }
-      if (part === "steps" && !("id" in r) && Action.safeParse(raw).success) {
-        return failed("invalid step: an on-camera step needs an id (a setup action: give its part)")
-      }
-      // Parsed against the shape the agent meant (a union's error only says "Invalid input").
-      const [what, schema] =
-        "preset" in r
-          ? (["preset", PresetRef] as const)
-          : "id" in r && part === "steps"
-            ? (["step", Step] as const)
-            : (["setup action", Action] as const)
-      const result = schema.safeParse(raw)
-      // The issue, then the forms of the action it meant (never a guess at the field names).
-      return failed(
-        `invalid ${what}: ${result.success ? "?" : formatIssue(result.error.issues[0])}${shapeOf(raw)}`,
-      )
-    }
     // As in the scene: started in its start app (its steps without an app mean that one).
     const scenario: Scenario = {
       ...(step.success || setupItem?.data === undefined
@@ -1285,10 +1477,17 @@ export class Studio {
         : { version: 1, setup: [setupItem.data], steps: [] }),
       app,
     }
-    const page = await this.livePage()
+    let page: Page
+    try {
+      page = await this.livePage(app, signal)
+    } catch (error) {
+      if (isStopped(error) || signal.aborted) throw error
+      return failed(refusal(error))
+    }
     try {
       await runScenario(page, scenario, this.#quick, {
         ...this.#run(scene, signal),
+        ...this.#guarded(app),
         // Live: a step may go anywhere (it says where: the moment to add a site, `add_app`).
         confineToApps: false,
         // The live page follows the tab or popup the runner switched to (the next step acts there).
@@ -1317,7 +1516,7 @@ export class Studio {
               `failed (page-closed): ${(error as StepError).message}; the rest of it didn't run (back on the page that opened it, url: ${this.#where(back.url())}): run its remaining steps one by one`,
             )
       }
-      return failed(failure(error))
+      return failed(`${failure(error)}${this.#told()}`)
     }
   }
 
@@ -1343,6 +1542,19 @@ export class Studio {
     }
     const issues = checkScenarioAgainstProject(scenario, this.options.config)
     if (issues.length > 0) return { error: `invalid scenario: ${issues.join("; ")}` }
+    // A desktop app's scene: nothing handed to the user yet (it could never be checked or filmed).
+    if (
+      startAppOf(scenario, this.options.config).app.kind === "electron" &&
+      [
+        ...(scenario.setup ?? []),
+        // The presets its setup runs (a sign-in preset with a handover).
+        ...(scenario.setup ?? []).flatMap((item) =>
+          "preset" in item ? (this.options.config.presets[item.preset]?.steps ?? []) : [],
+        ),
+      ].some((item) => "action" in item && isOffCameraOnly(item.action))
+    ) {
+      return { error: `invalid scenario: ${NO_DESKTOP_HANDOVER}` }
+    }
     if (scenario.steps.length < SCENE_STEPS.min || scenario.steps.length > SCENE_STEPS.max) {
       return {
         error: `a scene has ${SCENE_STEPS.min}-${SCENE_STEPS.max} on-camera steps (this one has ${scenario.steps.length})`,
@@ -1364,11 +1576,14 @@ export class Studio {
     } catch (error) {
       return `replay failed: ${failure(error)}`
     }
-    const reuse = this.#reuse(scenario)
-    const context = await this.options.browser.newContext({
-      ...filmed,
-      ...(reuse.storageState !== undefined && { storageState: reuse.storageState }),
-    })
+    let fresh: Fresh
+    try {
+      fresh = await this.#freshPage(scenario, filmed, signal)
+    } catch (error) {
+      // A stop during a desktop launch comes as the signal's own reason: a stop all the same.
+      if (isStopped(error) || signal.aborted) throw error
+      return `replay failed: ${refusal(error)}`
+    }
     try {
       // The pointer at once, also over the scene's own pacing (its typing and settling stay).
       const paced: Scenario = {
@@ -1378,12 +1593,10 @@ export class Studio {
           pacing: { ...scenario.overrides?.pacing, cursor: "instant" },
         },
       }
-      await runScenario(await context.newPage(), paced, this.options.config, {
-        ...this.#run(scene, signal, "check"),
+      await runScenario(fresh.page, paced, this.options.config, {
+        ...this.#run(scene, signal, "check", fresh.desktop),
         fresh: true,
-        skipSessionPresets: reuse.skipSessionPresets,
-        sessionLandings: reuse.sessionLandings,
-        onSessionReady: this.#sessionHooks(),
+        ...fresh.run,
       })
       return "ok"
     } catch (error) {
@@ -1392,7 +1605,7 @@ export class Studio {
       return `replay failed: ${failure(error)}`
     } finally {
       await this.#settled()
-      await context.close().catch(() => undefined)
+      await fresh.close().catch(() => undefined)
     }
   }
 
@@ -1417,22 +1630,31 @@ export class Studio {
     } catch (error) {
       return failed(`can't record "${sceneId}": ${failure(error)}`)
     }
-    const dir = takes.newTakeDir(this.project.project.id, sceneId)
-    const reuse = this.#reuse(scenario)
-    const context = await this.options.browser.newContext({
-      ...filmed,
-      ...(reuse.storageState !== undefined && { storageState: reuse.storageState }),
-    })
+    let fresh: Fresh
+    try {
+      fresh = await this.#freshPage(scenario, filmed, signal)
+    } catch (error) {
+      // A stop during a desktop launch comes as the signal's own reason: a stop all the same.
+      if (isStopped(error) || signal.aborted) throw error
+      return failed(`can't record "${sceneId}": ${refusal(error)}`)
+    }
+    let dir: string
+    try {
+      dir = takes.newTakeDir(this.project.project.id, sceneId)
+    } catch (error) {
+      // Never left running (a desktop app's process and sandbox).
+      await fresh.close().catch(() => undefined)
+      return failed(`can't record "${sceneId}": ${failure(error)}`)
+    }
     let recorded: Awaited<ReturnType<typeof recordScenario>> | undefined
     let why: string | undefined
     let stopped: StepError | undefined
     try {
-      recorded = await recordScenario(await context.newPage(), scenario, config, {
-        ...this.#run(sceneId, signal, "record"),
+      recorded = await recordScenario(fresh.page, scenario, config, {
+        ...this.#run(sceneId, signal, "record", fresh.desktop),
         fresh: true,
-        skipSessionPresets: reuse.skipSessionPresets,
-        sessionLandings: reuse.sessionLandings,
-        onSessionReady: this.#sessionHooks(),
+        ...fresh.run,
+        ...(fresh.build !== undefined && { appBuild: fresh.build }),
         outDir: dir,
         // A failed take's video is dropped as it settles: never encoded.
         encodeFailed: false,
@@ -1443,7 +1665,7 @@ export class Studio {
       why = failure(error)
     } finally {
       await this.#settled()
-      await context.close().catch(() => undefined)
+      await fresh.close().catch(() => undefined)
     }
     let take: Awaited<ReturnType<TakeStore["settle"]>>
     try {
@@ -1486,14 +1708,87 @@ export class Studio {
     }
   }
 
+  /**
+   * A fresh page for a check or a recording, in the scene's start app: a web app's in a new context
+   * (its saved sign-in reused when it holds); a desktop app's in a fresh launch (its own sandbox:
+   * the same files and state every time; no saved sign-in), closed whole after.
+   */
+  async #freshPage(scenario: Scenario, filmed: Filmed, signal: AbortSignal): Promise<Fresh> {
+    const start = startAppOf(scenario, this.options.config)
+    if (start.app.kind === "electron") {
+      const launch = this.options.launchDesktop
+      if (launch === undefined) {
+        throw new Error(`"${start.name}" is a desktop app: none can be run here`)
+      }
+      // One copy of a desktop app at a time (an app may allow only one): its live one closed
+      // first, said with the next step (what earlier steps did there is gone).
+      const live =
+        this.#live?.target !== undefined && this.#live.app === start.name
+          ? this.#live.app
+          : undefined
+      await this.#launchSettled()
+      if (live !== undefined) {
+        await this.#closeLive()
+        this.#notice = `${live} was closed for the check or recording: launched again fresh (what earlier steps did is gone)`
+      }
+      const { target, build } = await launch(
+        start.name,
+        AbortSignal.any([signal, this.#lifetime.signal]),
+      )
+      // Removed or changed while it launched: never run (its approval may be gone).
+      if (!this.#listed({ app: start.name, identity: appIdentity(start.app) })) {
+        await target.close().catch(() => undefined)
+        throw new Error(`"${start.name}" was removed`)
+      }
+      return {
+        page: target.page,
+        run: { electron: electronHook(start.name, target) },
+        build,
+        desktop: true,
+        close: () => target.close().then(() => undefined),
+      }
+    }
+    const reuse = this.#reuse(scenario)
+    const context = await this.options.browser.newContext({
+      ...filmed,
+      ...(reuse.storageState !== undefined && { storageState: reuse.storageState }),
+    })
+    try {
+      return {
+        page: await context.newPage(),
+        run: {
+          skipSessionPresets: reuse.skipSessionPresets,
+          sessionLandings: reuse.sessionLandings,
+          onSessionReady: this.#sessionHooks(),
+        },
+        desktop: false,
+        close: () => context.close(),
+      }
+    } catch (error) {
+      await context.close().catch(() => undefined)
+      throw error
+    }
+  }
+
   /** Closes the live page (the browser is the host's); every tool and dialog still running stops. */
   async close(): Promise<void> {
     this.#lifetime.abort()
-    await this.#live?.context.close().catch(() => undefined)
-    this.#live = undefined
+    await this.#closeLive()
+  }
+
+  /** A desktop app's guard for a run in it (its live target's), when the live page is one. */
+  #guarded(app: string): Pick<RunOptions, "electron"> {
+    const target = this.#live?.target
+    if (target === undefined || this.#live?.app !== app) return {}
+    return { electron: electronHook(app, target) }
   }
 
-  #run(sceneId: string, signal: AbortSignal, where: "live" | "check" | "record" = "live") {
+  #run(
+    sceneId: string,
+    signal: AbortSignal,
+    where: "live" | "check" | "record" = "live",
+    desktop = this.#live?.target !== undefined,
+  ) {
     const { resolveSecret, requestUser, requestApproval, scope, sceneKey, knownValues } =
       this.options
     const key = sceneKey(sceneId)
@@ -1511,6 +1806,8 @@ export class Studio {
       // A handover step: the user does a part themselves, on this run's page (the live view
       // follows it), never filmed.
       requestHandover: async (request: HandoverRequest) => {
+        // A desktop app's window isn't handed to the user yet (measured first: PR 5).
+        if (desktop) return { outcome: "declined" as const, note: NO_DESKTOP_HANDOVER }
         const context = request.page.context()
         this.#handoverPage = request.page
         const answer = await ask(signal, () =>
@@ -1559,10 +1856,13 @@ export class Studio {
 
 /** A context's latest page still open (the one a closed popup's opener most likely is). */
 function latestOpen(context: BrowserContext): Page | undefined {
-  return context
-    .pages()
-    .filter((p) => !p.isClosed())
-    .at(-1)
+  return (
+    context
+      .pages()
+      // A desktop app's DevTools: never a page the agent works on.
+      .filter((p) => !p.isClosed() && !p.url().startsWith("devtools://"))
+      .at(-1)
+  )
 }
 
 /**
@@ -1574,6 +1874,99 @@ async function ask<T>(signal: AbortSignal, open: () => T | Promise<T>): Promise<
   return open()
 }
 
+/** Why a desktop app's scene hands nothing to the user (decided 2026-10-10: measured in PR 5). */
+const NO_DESKTOP_HANDOVER =
+  "a desktop app's window isn't handed to the user yet (signing in by hand comes next): a desktop scene has no handover step"
+
+/** A fresh page for a check or a recording, and how its run goes and ends. */
+interface Fresh {
+  page: Page
+  run: Partial<RunOptions>
+  build?: NonNullable<TakeMeta["appBuild"]>
+  desktop: boolean
+  close: () => Promise<void>
+}
+
+/** Why an item can't run in its part (its shape: never its page), or undefined when it can. */
+function invalidItem(raw: unknown, part: ScenarioPart): StepResult | undefined {
+  if (typeof raw !== "object" || raw === null) {
+    return failed(
+      "invalid step: expected an object like {id: open-new, action: click, target: {...}}",
+    )
+  }
+  // Run in the part it's for: its approvals are keyed there, as the replay's will be (A1).
+  const step = part === "steps" ? Step.safeParse(raw) : { success: false as const }
+  // In the steps, only a preset runs as the setup (it's setup-only).
+  const setupItem =
+    step.success || (part === "steps" && !("preset" in raw)) ? undefined : SetupItem.safeParse(raw)
+  if (!step.success && setupItem?.success !== true) {
+    const r = raw as Record<string, unknown>
+    // An off-camera-only kind (a handover) on camera: said as such (an id would never do).
+    if (part === "steps" && typeof r.action === "string" && isOffCameraOnly(r.action)) {
+      return failed(`invalid step: ${OFF_CAMERA_MESSAGE}: give its part (setup)`)
+    }
+    if (part === "steps" && !("id" in r) && Action.safeParse(raw).success) {
+      return failed("invalid step: an on-camera step needs an id (a setup action: give its part)")
+    }
+    // Parsed against the shape the agent meant (a union's error only says "Invalid input").
+    const [what, schema] =
+      "preset" in r
+        ? (["preset", PresetRef] as const)
+        : "id" in r && part === "steps"
+          ? (["step", Step] as const)
+          : (["setup action", Action] as const)
+    const result = schema.safeParse(raw)
+    // The issue, then the forms of the action it meant (never a guess at the field names).
+    return failed(
+      `invalid ${what}: ${result.success ? "?" : formatIssue(result.error.issues[0])}${shapeOf(raw)}`,
+    )
+  }
+  return undefined
+}
+
+/** The live page: its context and page, the app it's at, and a desktop app's launched target. */
+type Live = {
+  context: BrowserContext
+  page: Page
+  app: string
+  /** The app as it was opened (`appIdentity`): another under its name is another app. */
+  identity: string
+  target?: ElectronTarget
+}
+
+/** A desktop app's run hook from its launched target (its guard, its windows). */
+function electronHook(app: string, target: ElectronTarget): NonNullable<RunOptions["electron"]> {
+  return {
+    app,
+    allows: target.allows,
+    stopped: target.stopped,
+    prepare: target.prepare,
+    quiet: target.quiet,
+  }
+}
+
+/**
+ * Why something couldn't start, for the agent: a refusal the user settles (a desktop app's
+ * approval) says so, for the agent to tell them and never retry.
+ */
+function refusal(error: unknown): string {
+  // A launch's error names no local path (said so at its source, and by the launcher).
+  if (!needsUser(error)) return failure(error)
+  // Its own words (a refusal is no crash: no "Error:").
+  return `${error instanceof Error ? error.message : String(error)}. ${USER_SETTLES}`
+}
+
+/** Said when a tool needs the live page, none is open, and the project has several apps. */
+const NO_APP_OPEN =
+  "no app is open yet (the project has several): open the scene's app with a run_step first, its start_app named (a pause step opens it and does nothing else)"
+
+/** Thrown by `livePage` rather than guessing which of several apps to open. */
+class NoAppOpen extends Error {
+  constructor() {
+    super(NO_APP_OPEN)
+  }
+}
+
 /** Why a scene never has a teardown or an `ensure` (OBJECT-MODEL §0.4). */
 const NO_CLEANUP =
   "no teardown and no ensure: Kiframe doesn't clean up after a scene (what it creates stays in the app, the user is told); remove them"
diff --git a/packages/studio/src/tools.ts b/packages/studio/src/tools.ts
index e885b48..5e23e46 100644
--- a/packages/studio/src/tools.ts
+++ b/packages/studio/src/tools.ts
@@ -1,4 +1,4 @@
-import { defineTool, isWithImages, type Tool, withImages } from "@kiframe/agent"
+import { defineTool, isWithImages, needsUser, type Tool, withImages } from "@kiframe/agent"
 import { saveScene } from "@kiframe/project"
 import { AppName, firstApp, RuleName, SceneId, webAppsOf } from "@kiframe/schema"
 import { parse as parseYaml } from "yaml"
@@ -58,7 +58,8 @@ const snapshot = defineTool({
         "Text to look for: only the elements that mention it, with where they are and their refs (as a reader: case, dashes and quotes don't matter; a phrase may run over a paragraph's links; with no exact match, the blocks holding all its words). For content further down a long page, past the snapshot's cut",
       ),
   }),
-  run: async ({ within, find }, studio: Studio) => said(await studio.snapshot(within, find)),
+  run: async ({ within, find }, studio: Studio, signal) =>
+    said(await studio.snapshot(within, find, signal)),
 })
 
 const look = defineTool({
@@ -370,6 +371,8 @@ function scrubbed(tool: Tool<Studio>): Tool<Studio> {
         const scrub = studio.scrubber()
         const scrubbed = new Error(scrub(error instanceof Error ? error.message : String(error)))
         if (error instanceof Error) scrubbed.name = error.name
+        // Whether the user settles it (an app to allow): the agent tells them, never retries.
+        if (needsUser(error)) Object.assign(scrubbed, { needsUser: true })
         throw scrubbed
       }
       // A tool's images are made safe where they're made (a screenshot masked; a project's image
diff --git a/packages/studio/test/desktop-app.test.ts b/packages/studio/test/desktop-app.test.ts
index bbc18d7..b57da09 100644
--- a/packages/studio/test/desktop-app.test.ts
+++ b/packages/studio/test/desktop-app.test.ts
@@ -1,7 +1,7 @@
 import { mkdtempSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
-import { createProject, TakeStore } from "@kiframe/project"
+import { createProject, saveScene, TakeStore } from "@kiframe/project"
 import { parseProjectYaml } from "@kiframe/schema"
 import type { Browser } from "playwright"
 import { describe, expect, it } from "vitest"
@@ -15,8 +15,10 @@ function studioWith(appsYaml: string) {
   const project = createProject(dir, { id: "p1", name: "Demo", url: "https://app.test" })
   const secretsAsked: string[] = []
   const opened: string[] = []
+  const contexts: number[] = []
   const browser = {
-    newContext: () =>
+    newContext: () => (
+      contexts.push(1),
       Promise.resolve({
         newPage: () =>
           Promise.resolve({
@@ -24,9 +26,11 @@ function studioWith(appsYaml: string) {
               opened.push(url)
               return Promise.resolve(null)
             },
+            isClosed: () => false,
           }),
         close: () => Promise.resolve(),
-      }),
+      })
+    ),
   } as unknown as Browser
   const studio = new Studio({
     project,
@@ -42,7 +46,7 @@ function studioWith(appsYaml: string) {
     },
     stopRun: () => undefined,
   })
-  return { studio, secretsAsked, opened }
+  return { studio, secretsAsked, opened, contexts }
 }
 
 describe("a desktop app in the studio", () => {
@@ -64,15 +68,17 @@ describe("a desktop app in the studio", () => {
     expect(secretsAsked).toEqual(["https://app.test"])
   })
 
-  it("is never grounded as a web page (its driver comes next): said, never a page opened", async () => {
+  it("is never grounded as a web page without a desktop launcher: said, never a page opened", async () => {
     const alone = studioWith("  notes: { kind: electron, bundleId: com.example.notes }\n")
-    await expect(alone.studio.livePage()).rejects.toThrow(/desktop apps can't be grounded yet/)
+    await expect(alone.studio.livePage(undefined, new AbortController().signal)).rejects.toThrow(
+      /"notes" is a desktop app: none can be opened here/,
+    )
     expect(alone.opened).toEqual([])
     // Listed first, beside a web app: the live page opens on the web app.
     const both = studioWith(
       '  notes: { kind: electron, bundleId: com.example.notes }\n  app: { kind: web, url: "https://app.test" }\n',
     )
-    await both.studio.livePage()
+    await both.studio.livePage(undefined, new AbortController().signal)
     expect(both.opened).toEqual(["https://app.test"])
     // A step grounded in the desktop app: refused, said why.
     const tool = studioTools.find((t) => t.name === "run_step")!
@@ -83,8 +89,7 @@ describe("a desktop app in the studio", () => {
         new AbortController().signal,
       ),
     ).toEqual({
-      error:
-        'start_app: "notes" is a desktop app: desktop apps can\'t be grounded yet (the Electron target comes next)',
+      error: 'start_app: "notes" is a desktop app: none can be grounded here',
     })
   })
 
@@ -93,4 +98,445 @@ describe("a desktop app in the studio", () => {
     expect(whereOf("https://app.test/dash", apps, "app", true)).toBe("app: /dash")
     expect(whereOf("https://app.test/dash", apps, "app")).toBe("/dash")
   })
+
+  it("keeps the live page between web apps' scenes (a sign-in by hand kept)", async () => {
+    const two = studioWith(
+      '  app: { kind: web, url: "https://app.test" }\n  docs: { kind: web, url: "https://docs.test" }\n',
+    )
+    await two.studio.livePage("app", new AbortController().signal)
+    await two.studio.livePage("docs", new AbortController().signal)
+    expect(two.contexts).toHaveLength(1)
+  })
+
+  it("never saves a desktop scene that hands something over, in a preset too", () => {
+    const { studio } = studioWith(`  notes: { kind: electron, bundleId: com.example.notes }
+presets:
+  sign-in:
+    app: notes
+    steps:
+      - { action: handover, task: Sign in }
+`)
+    const saved = studio.check(`version: 1
+app: notes
+setup:
+  - { preset: sign-in }
+steps:
+  - { id: a, action: pause, ms: 1 }
+  - { id: b, action: pause, ms: 1 }
+  - { id: c, action: pause, ms: 1 }
+  - { id: d, action: pause, ms: 1 }
+  - { id: e, action: pause, ms: 1 }
+`)
+    expect(saved).toMatchObject({ error: expect.stringMatching(/no handover step/) as string })
+  })
+
+  describe("its live launch (a fake launcher)", () => {
+    /** A launcher whose launches the test lets go of; each one's page and its close counted. */
+    const launcher = () => {
+      const pending: {
+        app: string
+        go: () => void
+        fail: (e: Error) => void
+        signal: AbortSignal
+      }[] = []
+      const closed: string[] = []
+      const launch = (app: string, signal: AbortSignal) =>
+        new Promise<never>((resolve, reject) => {
+          const page = { isClosed: () => false, url: () => `app://${app}/`, context: () => context }
+          const context = { pages: () => [page] }
+          const target = {
+            page,
+            context,
+            allows: () => true,
+            stopped: () => [],
+            prepare: () => Promise.resolve(),
+            quiet: () => Promise.resolve(),
+            close: () => (closed.push(app), Promise.resolve({ unread: false })),
+          }
+          pending.push({
+            app,
+            signal,
+            go: () => resolve({ target, build: { opens: "a".repeat(64) } } as never),
+            fail: reject,
+          })
+        })
+      return { pending, closed, launch }
+    }
+    const desktopStudio = (fake: ReturnType<typeof launcher>, appsYaml: string) => {
+      const made = studioWith(appsYaml)
+      ;(made.studio as unknown as { options: { launchDesktop: unknown } }).options.launchDesktop =
+        fake.launch
+      return made.studio
+    }
+    const two =
+      "  notes: { kind: electron, bundleId: com.example.notes }\n  other: { kind: electron, bundleId: com.example.other }\n"
+    // One app: nothing to guess (a bare snapshot or handover opens it).
+    const one = "  notes: { kind: electron, bundleId: com.example.notes }\n"
+
+    it("refuses a call while another call's launch goes on (never joined)", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      const notes = studio.livePage("notes", new AbortController().signal)
+      await expect.poll(() => fake.pending.length).toBe(1)
+      await expect(studio.livePage("other", new AbortController().signal)).rejects.toThrow(
+        /"notes" is still opening/,
+      )
+      await expect(studio.livePage("notes", new AbortController().signal)).rejects.toThrow(
+        /still opening/,
+      )
+      fake.pending[0]?.go()
+      expect((await notes).url()).toBe("app://notes/")
+    })
+
+    it("keeps a refusal the user settles through the tool (the agent tells them, never retries)", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, one)
+      const snapshot = studioTools.find((t) => t.name === "snapshot")!
+      const seen = snapshot.run({}, studio, new AbortController().signal)
+      await expect.poll(() => fake.pending.length).toBe(1)
+      fake.pending[0]?.fail(
+        Object.assign(new Error("notes: approved for another project"), { needsUser: true }),
+      )
+      await expect(seen).rejects.toMatchObject({
+        message: expect.stringMatching(/approved for another project/) as string,
+        needsUser: true,
+      })
+    })
+
+    it("ends a launch its caller stopped (never live), and the next call goes on", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      const stopping = new AbortController()
+      const stopped = studio.livePage("notes", stopping.signal)
+      await expect.poll(() => fake.pending.length).toBe(1)
+      stopping.abort()
+      // The launch sees the stop (its trial and spawn end).
+      expect(fake.pending[0]?.signal.aborted).toBe(true)
+      // The next call (the user's next message) comes while it's still winding down: waited
+      // out, never refused.
+      const next = studio.livePage("other", new AbortController().signal)
+      await new Promise((resolve) => setTimeout(resolve, 0))
+      expect(fake.pending).toHaveLength(1)
+      fake.pending[0]?.fail(stopping.signal.reason as Error)
+      await expect(stopped).rejects.toMatchObject({ name: "AbortError" })
+      await expect.poll(() => fake.pending.length).toBe(2)
+      fake.pending[1]?.go()
+      expect((await next).url()).toBe("app://other/")
+      expect(studio.currentPage?.url()).toBe("app://other/")
+    })
+
+    it("closes a launch that finished after its caller stopped (never kept)", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      const stopping = new AbortController()
+      const stopped = studio.livePage("notes", stopping.signal)
+      await expect.poll(() => fake.pending.length).toBe(1)
+      stopping.abort()
+      // It finishes anyway (a launch that ignored the stop): closed, never live.
+      fake.pending[0]?.go()
+      await expect(stopped).rejects.toMatchObject({ name: "AbortError" })
+      expect(fake.closed).toEqual(["notes"])
+      expect(studio.currentPage).toBeUndefined()
+    })
+
+    it("keeps no app removed while it launched", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      const opening = studio.livePage("notes", new AbortController().signal)
+      // Removed once the launch is under way.
+      await expect.poll(() => fake.pending.length).toBe(1)
+      studio.setApps(
+        parseProjectYaml(
+          "version: 2\napps:\n  other: { kind: electron, bundleId: com.example.other }\n",
+        ).apps,
+      )
+      await Promise.resolve()
+      fake.pending[0]?.go()
+      await expect(opening).rejects.toThrow(/was removed/)
+      expect(fake.closed).toEqual(["notes"])
+    })
+
+    it("stops a snapshot's launch with the snapshot (the agent's first call)", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, one)
+      const stopping = new AbortController()
+      const shot = studioTools.find((t) => t.name === "snapshot")!.run({}, studio, stopping.signal)
+      await expect.poll(() => fake.pending.length).toBe(1)
+      stopping.abort()
+      expect(fake.pending[0]?.signal.aborted).toBe(true)
+      fake.pending[0]?.fail(stopping.signal.reason as Error)
+      await expect(shot).rejects.toMatchObject({ name: "AbortError" })
+    })
+
+    it("never checks a scene in an app removed while it launched", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      const checked = studio.check(`version: 1
+app: notes
+steps:
+  - { id: a, action: pause, ms: 1 }
+  - { id: b, action: pause, ms: 1 }
+  - { id: c, action: pause, ms: 1 }
+  - { id: d, action: pause, ms: 1 }
+  - { id: e, action: pause, ms: 1 }
+`)
+      if ("error" in checked) throw new Error(checked.error)
+      const replay = studio.replay(checked.scenario, "s", new AbortController().signal)
+      await expect.poll(() => fake.pending.length).toBe(1)
+      studio.setApps(
+        parseProjectYaml(
+          "version: 2\napps:\n  other: { kind: electron, bundleId: com.example.other }\n",
+        ).apps,
+      )
+      fake.pending[0]?.go()
+      expect(await replay).toMatch(/was removed/)
+      expect(fake.closed).toEqual(["notes"])
+    })
+
+    const fiveSteps = `version: 1
+app: notes
+steps:
+  - { id: a, action: pause, ms: 1 }
+  - { id: b, action: pause, ms: 1 }
+  - { id: c, action: pause, ms: 1 }
+  - { id: d, action: pause, ms: 1 }
+  - { id: e, action: pause, ms: 1 }
+`
+
+    it("ends a check stopped while its app launched as a stop, never as a failed check", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      const checked = studio.check(fiveSteps)
+      if ("error" in checked) throw new Error(checked.error)
+      const stopping = new AbortController()
+      const replay = studio.replay(checked.scenario, "s", stopping.signal)
+      await expect.poll(() => fake.pending.length).toBe(1)
+      stopping.abort()
+      fake.pending[0]?.fail(stopping.signal.reason as Error)
+      await expect(replay).rejects.toMatchObject({ name: "AbortError" })
+    })
+
+    it("closes the live copy of the app before a check launches another (one at a time)", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      const live = studio.livePage("notes", new AbortController().signal)
+      await expect.poll(() => fake.pending.length).toBe(1)
+      fake.pending[0]?.go()
+      await live
+      const checked = studio.check(fiveSteps)
+      if ("error" in checked) throw new Error(checked.error)
+      const replay = studio.replay(checked.scenario, "s", new AbortController().signal)
+      await expect.poll(() => fake.pending.length).toBe(2)
+      // The live one closed before the check's launch began.
+      expect(fake.closed).toEqual(["notes"])
+      expect(studio.currentPage).toBeUndefined()
+      fake.pending[1]?.fail(new Error("done"))
+      await replay
+    })
+
+    it("leaves no app running when a recording's take folder can't be made", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      const checked = studio.check(fiveSteps)
+      if ("error" in checked) throw new Error(checked.error)
+      saveScene(
+        studio.project,
+        {
+          version: 1,
+          id: "s",
+          title: "S",
+          source: { kind: "recording" },
+          duration: { mode: "auto" },
+        },
+        { scenario: checked.scenario },
+      )
+      studio.options.takes.newTakeDir = () => {
+        throw Object.assign(new Error("no space"), { code: "ENOSPC" })
+      }
+      const recording = studio.record("s", new AbortController().signal)
+      await expect.poll(() => fake.pending.length).toBe(1)
+      fake.pending[0]?.go()
+      expect(await recording).toMatchObject({ ok: false })
+      expect(fake.closed).toEqual(["notes"])
+    })
+
+    it("closes a live app the project now lists as another app under its name", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      const live = studio.livePage("notes", new AbortController().signal)
+      await expect.poll(() => fake.pending.length).toBe(1)
+      fake.pending[0]?.go()
+      await live
+      studio.setApps(
+        parseProjectYaml(
+          "version: 2\napps:\n  notes: { kind: electron, bundleId: com.example.another }\n",
+        ).apps,
+      )
+      // A call meanwhile never gets the old one's page: a new launch, of the app now listed.
+      const next = studio.livePage("notes", new AbortController().signal)
+      await expect.poll(() => fake.closed).toEqual(["notes"])
+      await expect.poll(() => fake.pending.length).toBe(2)
+      fake.pending[1]?.go()
+      await next
+      expect(fake.closed).toEqual(["notes"])
+    })
+
+    it("checks a step before launching anything for it", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      const step = await studio.runStep(
+        { ensure: [{ action: "pause", ms: 1 }] },
+        "s",
+        new AbortController().signal,
+        "steps",
+        "notes",
+      )
+      expect(step.ok).toBe(false)
+      expect(fake.pending).toEqual([])
+    })
+
+    it("checks a step's shape before launching anything for it (its refs as locators)", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      // No id: an on-camera step needs one (said before any app opens or closes).
+      const step = await studio.runStep(
+        { action: "click", target: { ref: "e3" } },
+        "s",
+        new AbortController().signal,
+        "steps",
+        "notes",
+      )
+      expect(step).toMatchObject({
+        ok: false,
+        text: expect.stringMatching(/needs an id/) as string,
+      })
+      expect(fake.pending).toEqual([])
+    })
+
+    it("keeps another desktop app live while a scene's check launches its own", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      const live = studio.livePage("notes", new AbortController().signal)
+      await expect.poll(() => fake.pending.length).toBe(1)
+      fake.pending[0]?.go()
+      await live
+      const checked = studio.check(`version: 1
+app: other
+steps:
+  - { id: a, action: pause, ms: 1 }
+  - { id: b, action: pause, ms: 1 }
+  - { id: c, action: pause, ms: 1 }
+  - { id: d, action: pause, ms: 1 }
+  - { id: e, action: pause, ms: 1 }
+`)
+      if ("error" in checked) throw new Error(checked.error)
+      const replay = studio.replay(checked.scenario, "s", new AbortController().signal)
+      await expect.poll(() => fake.pending.length).toBe(2)
+      expect(fake.closed).toEqual([])
+      expect(studio.currentPage?.url()).toBe("app://notes/")
+      fake.pending[1]?.fail(new Error("done"))
+      await replay
+    })
+
+    it("waits out a stopped launch of an app removed meanwhile before a check launches", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      const stopping = new AbortController()
+      const stopped = studio.livePage("notes", stopping.signal)
+      await expect.poll(() => fake.pending.length).toBe(1)
+      stopping.abort()
+      studio.setApps(
+        parseProjectYaml(
+          "version: 2\napps:\n  other: { kind: electron, bundleId: com.example.other }\n",
+        ).apps,
+      )
+      const checked = studio.check(`version: 1
+app: other
+steps:
+  - { id: a, action: pause, ms: 1 }
+  - { id: b, action: pause, ms: 1 }
+  - { id: c, action: pause, ms: 1 }
+  - { id: d, action: pause, ms: 1 }
+  - { id: e, action: pause, ms: 1 }
+`)
+      if ("error" in checked) throw new Error(checked.error)
+      const replay = studio.replay(checked.scenario, "s", new AbortController().signal)
+      await new Promise((resolve) => setTimeout(resolve, 10))
+      // Still a desktop launch, though its app is gone from the project: never two at once.
+      expect(fake.pending).toHaveLength(1)
+      fake.pending[0]?.fail(stopping.signal.reason as Error)
+      await expect(stopped).rejects.toMatchObject({ name: "AbortError" })
+      await expect.poll(() => fake.pending.length).toBe(2)
+      fake.pending[1]?.fail(new Error("done"))
+      await replay
+    })
+
+    it("never guesses which of several apps to open: says to open one with a step", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, two)
+      const signal = new AbortController().signal
+      const asked = /no app is open yet .*start_app/
+      expect(await studio.snapshot(undefined, undefined, signal)).toMatchObject({
+        ok: false,
+        text: expect.stringMatching(asked) as string,
+      })
+      expect(await studio.look(undefined, signal)).toMatchObject({
+        error: expect.stringMatching(asked) as string,
+      })
+      expect(await studio.handOver("Sign in", undefined, signal)).toMatchObject({
+        error: expect.stringMatching(asked) as string,
+      })
+      expect(fake.pending).toEqual([])
+      // Once a step opened one, a bare snapshot is of it.
+      const opened = studio.runStep(
+        { id: "a", action: "pause", ms: 1 },
+        "s",
+        signal,
+        "steps",
+        "other",
+      )
+      await expect.poll(() => fake.pending.length).toBe(1)
+      expect(fake.pending[0]?.app).toBe("other")
+      fake.pending[0]?.fail(new Error("done"))
+      await opened
+    })
+
+    it("refuses a handover before launching anything", async () => {
+      const fake = launcher()
+      const studio = desktopStudio(fake, one)
+      expect(
+        await studio.handOver("Sign in", undefined, new AbortController().signal),
+      ).toMatchObject({
+        error: expect.stringMatching(/isn't handed to the user yet/) as string,
+      })
+      expect(fake.pending).toEqual([])
+    })
+  })
+
+  it("never keeps a web app's page removed while it loaded", async () => {
+    let loaded: () => void = () => undefined
+    const made = studioWith(
+      '  app: { kind: web, url: "https://app.test" }\n  docs: { kind: web, url: "https://docs.test" }\n',
+    )
+    const browser = {
+      newContext: () =>
+        Promise.resolve({
+          newPage: () =>
+            Promise.resolve({
+              goto: () => new Promise((resolve) => (loaded = () => resolve(null))),
+              isClosed: () => false,
+            }),
+          close: () => Promise.resolve(),
+        }),
+    }
+    ;(made.studio as unknown as { options: { browser: unknown } }).options.browser = browser
+    const opening = made.studio.livePage("docs", new AbortController().signal)
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    made.studio.setApps(
+      parseProjectYaml('version: 2\napps:\n  app: { kind: web, url: "https://app.test" }\n').apps,
+    )
+    loaded()
+    await expect(opening).rejects.toThrow(/was removed/)
+    expect(made.studio.currentPage).toBeUndefined()
+  })
 })
diff --git a/packages/studio/test/electron-studio.test.ts b/packages/studio/test/electron-studio.test.ts
new file mode 100644
index 0000000..7cf3cb2
--- /dev/null
+++ b/packages/studio/test/electron-studio.test.ts
@@ -0,0 +1,320 @@
+import { existsSync, mkdtempSync, readdirSync, readFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { USER_SETTLES } from "@kiframe/agent"
+import { createProject, saveScene, TakeStore } from "@kiframe/project"
+import { parseProjectYaml } from "@kiframe/schema"
+import { chromium, type Browser } from "playwright"
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest"
+import { launchElectronWith } from "../../runtime/src/electron.ts"
+import { Studio, studioTools } from "../src/index.ts"
+
+// Kif in a desktop app (PR 4b): the studio grounds, checks and records a scene in the runtime's
+// fixture app, launched for real (the host's launcher replaced by the test's: confined on macOS,
+// unconfined on Linux CI), and leaves nothing running.
+
+const electron = createRequire(join(import.meta.dirname, "../../../apps/desktop/package.json"))(
+  "electron",
+) as string
+const fixture = join(import.meta.dirname, "../../runtime/test/fixtures/electron-app")
+const electronApp = electron.slice(0, electron.indexOf(".app/") + 4)
+const viewport = { width: 800, height: 600, deviceScaleFactor: 1 }
+
+let browser: Browser
+beforeAll(async () => {
+  browser = await chromium.launch()
+})
+afterAll(async () => {
+  await browser.close()
+})
+
+const closing: (() => Promise<void>)[] = []
+afterEach(async () => {
+  for (const close of closing.splice(0)) await close().catch(() => undefined)
+})
+
+/** A studio over a project whose app is the fixture desktop app, launched by the test. */
+function studioWith(
+  launch?: (app: string, signal: AbortSignal) => Promise<never>,
+  appsYaml = "  notes: { kind: electron, bundleId: com.kiframe.fixture, viewport: { width: 800, height: 600, deviceScaleFactor: 1 } }\n",
+) {
+  const dir = join(mkdtempSync(join(tmpdir(), "kiframe-el-studio-")), "demo.kiframe")
+  const project = createProject(dir, { id: "p1", name: "Demo", url: "https://app.test" })
+  const work = mkdtempSync(join(tmpdir(), "kiframe-el-studio-work-"))
+  const data = mkdtempSync(join(tmpdir(), "kiframe-el-studio-data-"))
+  const takes = new TakeStore(data)
+  const launches: string[] = []
+  const studio = new Studio({
+    project,
+    scope: "folder-1",
+    sceneKey: (id) => `host-${id}`,
+    config: parseProjectYaml(`version: 2
+apps:
+${appsYaml}defaults: { pacing: { settleMs: 0, cursor: instant, typing: instant } }
+`),
+    takes,
+    browser,
+    requestUser: () => Promise.resolve(false),
+    stopRun: () => undefined,
+    launchDesktop:
+      launch ??
+      (async (app, signal) => {
+        launches.push(app)
+        const target = await launchElectronWith(
+          { executable: electron, bundle: fixture, workDir: work, viewport, signal, settleMs: 300 },
+          // Hidden where it still paints (macOS); shown on Linux (xvfb): a hidden window there never
+          // paints, so a look's screenshot would wait forever.
+          {
+            appArgs: process.platform === "linux" ? [fixture] : [fixture, "hidden"],
+            readable: [electronApp],
+            allowUnconfined: true,
+          },
+        )
+        closing.push(() => target.close().then(() => undefined))
+        return { target, build: { version: "44.4.5", opens: "a".repeat(64) } }
+      }),
+  })
+  closing.push(() => studio.close())
+  return { studio, project, data, work, launches }
+}
+
+const tool = (name: string) => studioTools.find((t) => t.name === name)!
+const run = (studio: Studio, name: string, input: object) =>
+  tool(name).run(input, studio, new AbortController().signal)
+const sandboxes = (work: string) =>
+  existsSync(join(work, "sandboxes"))
+    ? readdirSync(join(work, "sandboxes")).filter((n) => !n.endsWith(".canary"))
+    : []
+
+describe("Kif in a desktop app", { timeout: 120_000 }, () => {
+  it("grounds a scene in its window: its own pages said as such, never a file path", async () => {
+    const { studio, launches } = studioWith()
+    const seen = (await run(studio, "snapshot", {})) as { result?: string; error?: string }
+    const text = JSON.stringify(seen)
+    expect(text).toContain("notes's own page")
+    // The app's own file path (the user's machine) never reaches the agent (its page's own
+    // content, a link to a file, is the page's).
+    expect(text).not.toContain(fixture)
+    expect(text).not.toContain("index.html")
+    // Its links too: said by the guard, never their address on this computer.
+    expect(text).not.toContain("file:")
+    expect(text).not.toContain("/etc/hosts")
+    expect(text).toContain(String.raw`/url: \"notes's own page\"`)
+    expect(text).toContain(String.raw`/url: \"a file on this computer (not the app's own)\"`)
+    const step = (await run(studio, "run_step", {
+      scene: "s",
+      start_app: "notes",
+      step: {
+        id: "add",
+        action: "click",
+        target: { by: "role", role: "button", name: "Add note" },
+      },
+    })) as object
+    expect(JSON.stringify(step)).toContain("notes's own page")
+    const checked = (await run(studio, "run_step", {
+      scene: "s",
+      start_app: "notes",
+      step: { id: "one", action: "expect", that: { text: "Notes: 1" } },
+    })) as object
+    expect(JSON.stringify(checked)).not.toContain("error")
+    // One launch for the live session (never one per step).
+    expect(launches).toEqual(["notes"])
+  })
+
+  it("fails a step whose page never loaded (never ok on Chromium's error page)", async () => {
+    const { studio } = studioWith()
+    const step = (await run(studio, "run_step", {
+      scene: "s",
+      start_app: "notes",
+      step: {
+        id: "dead",
+        action: "click",
+        target: { by: "role", role: "link", name: "A dead link" },
+      },
+    })) as object
+    expect(step).toMatchObject({
+      error: expect.stringMatching(/the page failed to load/) as string,
+    })
+  })
+
+  it("looks at a ref in its window (its size read from the page)", async () => {
+    const { studio } = studioWith()
+    const shot = JSON.stringify(await run(studio, "snapshot", {}))
+    const ref = /\[ref=(e\d+)\]/.exec(shot)?.[1]
+    expect(ref).toBeDefined()
+    const looked = JSON.stringify(await run(studio, "look", { ref }))
+    expect(looked).not.toContain("error")
+  })
+
+  it("says an app that quit while grounded, launched again fresh", async () => {
+    const { studio, launches } = studioWith()
+    await studio.livePage("notes", new AbortController().signal)
+    // The app's only window closed: the fixture quits.
+    await studio.currentPage?.close()
+    const step = JSON.stringify(
+      await run(studio, "run_step", {
+        scene: "s",
+        start_app: "notes",
+        step: { id: "a", action: "pause", ms: 1 },
+      }),
+    )
+    expect(step).toContain("notes quit: launched again fresh")
+    expect(launches).toEqual(["notes", "notes"])
+    // Said with a look too (the image is of a fresh window).
+    await studio.currentPage?.close()
+    const looked = JSON.stringify(await run(studio, "look", {}))
+    expect(looked).toContain("notes quit: launched again fresh")
+  })
+
+  it("checks and records a scene in a fresh launch each, its take keeping the build", async () => {
+    const { studio, project, data, work, launches } = studioWith()
+    const yaml = `version: 1
+app: notes
+steps:
+  - { id: add, action: click, target: { by: role, role: button, name: Add note } }
+  - { id: one, action: expect, that: { text: "Notes: 1" } }
+  - { id: two, action: click, target: { by: role, role: button, name: Add note } }
+  - { id: three, action: expect, that: { text: "Notes: 2" } }
+  - { id: rest, action: pause, ms: 100 }
+`
+    const checked = studio.check(yaml)
+    if ("error" in checked) throw new Error(checked.error)
+    expect(await studio.replay(checked.scenario, "s", new AbortController().signal)).toBe("ok")
+    saveScene(
+      project,
+      {
+        version: 1,
+        id: "s",
+        title: "S",
+        source: { kind: "recording" },
+        duration: { mode: "auto" },
+      },
+      { scenario: checked.scenario },
+    )
+    const recorded = await studio.record("s", new AbortController().signal)
+    expect(recorded).toMatchObject({ ok: true })
+    // A launch each (the check's, the recording's), each closed: no sandbox left.
+    expect(launches).toEqual(["notes", "notes"])
+    expect(sandboxes(work)).toEqual([])
+    // The take's meta, wherever the store keeps it.
+    const metas = readdirSync(data, { recursive: true, encoding: "utf8" }).filter((p) =>
+      p.endsWith("meta.json"),
+    )
+    expect(metas).toHaveLength(1)
+    const meta = JSON.parse(readFileSync(join(data, metas[0] ?? ""), "utf8")) as {
+      appBuild?: unknown
+      appUrl: string
+    }
+    expect(meta.appUrl).toBe("electron:com.kiframe.fixture")
+    expect(meta.appBuild).toEqual({ version: "44.4.5", opens: "a".repeat(64) })
+  })
+
+  it("says a refusal the user settles for them, and never saves a handover in a desktop scene", async () => {
+    const refused = Object.assign(new Error("notes: approved for another project"), {
+      needsUser: true,
+    })
+    const { studio } = studioWith(() => Promise.reject(refused))
+    const step = JSON.stringify(
+      await run(studio, "run_step", {
+        scene: "s",
+        start_app: "notes",
+        step: { id: "a", action: "pause", ms: 1 },
+      }),
+    )
+    expect(step).toContain(USER_SETTLES)
+    // Said in its own words (a refusal, no crash).
+    expect(step).not.toContain("Error:")
+    const saved = studio.check(`version: 1
+app: notes
+setup:
+  - { action: handover, task: Sign in, done_when: You see your notes }
+steps:
+  - { id: a, action: pause, ms: 1 }
+  - { id: b, action: pause, ms: 1 }
+  - { id: c, action: pause, ms: 1 }
+  - { id: d, action: pause, ms: 1 }
+  - { id: e, action: pause, ms: 1 }
+`)
+    expect(saved).toMatchObject({ error: expect.stringMatching(/no handover step/) as string })
+  })
+
+  it("closes its desktop app with the studio (nothing left running)", async () => {
+    const { studio, work } = studioWith()
+    await studio.livePage("notes", new AbortController().signal)
+    expect(sandboxes(work)).toHaveLength(1)
+    await studio.close()
+    expect(sandboxes(work)).toEqual([])
+  })
+
+  it("hands nothing over live, closes an app removed from the project, says a relaunch on failure", async () => {
+    const { studio, work } = studioWith()
+    await studio.livePage("notes", new AbortController().signal)
+    expect(await studio.handOver("Sign in", undefined, new AbortController().signal)).toMatchObject(
+      {
+        error: expect.stringMatching(/isn't handed to the user yet/) as string,
+      },
+    )
+    // The app quit; the next step fails: the relaunch is said all the same.
+    await studio.currentPage?.close()
+    const failing = JSON.stringify(
+      await run(studio, "run_step", {
+        scene: "s",
+        start_app: "notes",
+        step: { id: "nine", action: "expect", that: { text: "Notes: 9" }, timeout: 500 },
+      }),
+    )
+    expect(failing).toContain("notes quit: launched again fresh")
+    // Removed from the project (its approval dropped): its live launch closed.
+    studio.setApps({})
+    await expect.poll(() => sandboxes(work).length, { timeout: 10_000 }).toBe(0)
+  })
+
+  it("never resolves a ref on another app's page (a new snapshot asked)", async () => {
+    const twice =
+      "  notes: { kind: electron, bundleId: com.kiframe.fixture, viewport: { width: 800, height: 600, deviceScaleFactor: 1 } }\n" +
+      "  other: { kind: electron, bundleId: com.kiframe.other, viewport: { width: 800, height: 600, deviceScaleFactor: 1 } }\n"
+    const { studio } = studioWith(undefined, twice)
+    // Opened by a step first (with several apps, a bare snapshot never guesses).
+    await run(studio, "run_step", {
+      scene: "s",
+      start_app: "notes",
+      step: { id: "a", action: "pause", ms: 1 },
+    })
+    const shot = JSON.stringify(await run(studio, "snapshot", {}))
+    // The snapshot as the agent gets it (JSON: its quotes escaped).
+    const ref = /button \\?"Add note\\?" \[ref=(e\d+)\]/.exec(shot)?.[1]
+    expect(ref).toBeDefined()
+    const step = JSON.stringify(
+      await run(studio, "run_step", {
+        scene: "s",
+        start_app: "other",
+        step: { id: "add", action: "click", target: { ref } },
+      }),
+    )
+    expect(step).toMatch(/snapshot/)
+    expect(step).not.toContain("Notes: 1")
+  })
+
+  it("stops a launch with the call that started it (never live after a stop)", async () => {
+    let seen: AbortSignal | undefined
+    const { studio } = studioWith((_app, signal) => {
+      seen = signal
+      return new Promise<never>((_, reject) =>
+        signal.addEventListener("abort", () => reject(signal.reason as Error)),
+      )
+    })
+    const stopping = new AbortController()
+    const step = tool("run_step").run(
+      { scene: "s", start_app: "notes", step: { id: "a", action: "pause", ms: 1 } },
+      studio,
+      stopping.signal,
+    )
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    stopping.abort()
+    await expect(step).rejects.toMatchObject({ name: "AbortError" })
+    // The launch itself ended (its trial, its spawn): nothing comes live after the stop.
+    expect(seen?.aborted).toBe(true)
+    expect(studio.currentPage).toBeUndefined()
+  })
+})
diff --git a/packages/studio/test/studio.test.ts b/packages/studio/test/studio.test.ts
index 6a2ed5b..66e96ff 100644
--- a/packages/studio/test/studio.test.ts
+++ b/packages/studio/test/studio.test.ts
@@ -411,7 +411,7 @@ describe("studio tools", () => {
   it("scrubs a snapshot before cutting it (a value the cut splits never shows in part)", async () => {
     const value = "sk-live-4242424242"
     const { studio } = makeStudio(undefined, { knownValues: () => new Set([value]) })
-    const page = await studio.livePage()
+    const page = await studio.livePage(undefined, new AbortController().signal)
     // The value placed across the cut: SNAPSHOT_MAX falls in its middle.
     const fill = async (n: number) => {
       await page.setContent(`<p>${"x".repeat(n)} ${value} ${"y".repeat(1000)}</p>`)
@@ -458,7 +458,7 @@ steps:
     const value = "sk-live-4242424242"
     const { studio } = makeStudio(undefined, { knownValues: () => new Set([value]) })
     const step = (s: object) => tool("run_step").run({ scene: "long", step: s }, studio, never)
-    const page = await studio.livePage()
+    const page = await studio.livePage(undefined, new AbortController().signal)
     const rows = Array.from({ length: 600 }, (_, i) => `<p>Season ${i}: matches and goals</p>`)
     await page.setContent(
       `<main>${rows.join("")}<h2>World Cup 2026</h2><p>Key: ${value}</p><p>The final.</p></main>`,
@@ -629,7 +629,10 @@ ${["a", "b", "c", "d", "e"].map((id) => `  - { id: ${id}, action: pause, ms: 150
 
   it("opens one live page for callers at once", async () => {
     const { studio } = makeStudio()
-    const [a, b] = await Promise.all([studio.livePage(), studio.livePage()])
+    const [a, b] = await Promise.all([
+      studio.livePage(undefined, new AbortController().signal),
+      studio.livePage(undefined, new AbortController().signal),
+    ])
     expect(a).toBe(b)
     expect(browser.contexts().filter((c) => c.pages().includes(a))).toHaveLength(1)
     const before = browser.contexts().length
@@ -667,7 +670,7 @@ ${["a", "b", "c", "d", "e"].map((id) => `  - { id: ${id}, action: pause, ms: 150
 
   it("says when the page is on another site than the app's", async () => {
     const { studio } = makeStudio()
-    const page = await studio.livePage()
+    const page = await studio.livePage(undefined, new AbortController().signal)
     // The same server under another host name: another site.
     await page.goto(`${server.url.replace("127.0.0.1", "localhost")}/projects?token=abc`)
     const snap = (await tool("snapshot").run({}, studio, never)) as string
@@ -1007,7 +1010,7 @@ steps: [{ id: a, action: pause, ms: 1 }]
     )) as string
     expect(asText.split("\n")).toEqual(["1 step ok", expect.stringMatching(/^1\. ok/) as unknown])
     // A step that leaves the app's site stops the rest.
-    const page = await studio.livePage()
+    const page = await studio.livePage(undefined, new AbortController().signal)
     await page.goto(`${server.url.replace("127.0.0.1", "localhost")}/`)
     const offSite = (await tool("run_steps").run(
       {
@@ -1460,7 +1463,7 @@ describe("look: the live page as an image", () => {
   it("shows the page with a secret painted over, one element alone, and its image intact through the boundary", async () => {
     const known = new Set<string>(["bob@acme.com"])
     const { studio } = makeStudio(undefined, { knownValues: () => known })
-    const page = await studio.livePage()
+    const page = await studio.livePage(undefined, new AbortController().signal)
     await page.setContent(
       `<p style="font-size:40px">Logged in as bob@acme.com</p><canvas id="c" role="img" aria-label="Drawing canvas" style="width:300px;height:120px;background:#eee"></canvas>`,
     )
@@ -1553,7 +1556,7 @@ describe("hand_over: the user takes the live browser", () => {
       asked = request
       return Promise.resolve({ outcome: "done", note: "", hide: true } as never)
     })
-    const page = await studio.livePage()
+    const page = await studio.livePage(undefined, new AbortController().signal)
     await page.goto("about:blank")
     await studio.handOver("Look", undefined, new AbortController().signal)
     expect(asked).toMatchObject({ kind: "handover", origin: "" })
@@ -1572,7 +1575,7 @@ describe("hand_over: the user takes the live browser", () => {
       await studio.currentPage!.close()
       return { outcome: "done", note: "", hide: true } as never
     })
-    await studio.livePage()
+    await studio.livePage(undefined, new AbortController().signal)
     const result = await studio.handOver("Sign in", undefined, new AbortController().signal)
     expect(result).toMatchObject({ outcome: "done", url: "" })
     expect(studio.scrub("x closing-typed-1")).toBe("x [secret]")
@@ -1588,7 +1591,7 @@ describe("hand_over: the user takes the live browser", () => {
       await new Promise((r) => setTimeout(r, 300))
       return { outcome: "declined", note: "no phone at hand", hide: true } as never
     })
-    const page = await studio.livePage()
+    const page = await studio.livePage(undefined, new AbortController().signal)
     await page.setContent(`<button>Go</button>`)
     const snap = await studio.snapshot()
     expect(snap.ok).toBe(true)
@@ -1627,7 +1630,7 @@ steps:
       studio.knowTyped(["typed-in-check-1"])
       return Promise.resolve({ outcome: "done", note: "", hide: true } as never)
     })
-    const live = await studio.livePage()
+    const live = await studio.livePage(undefined, new AbortController().signal)
     expect(await studio.replay(scenario(), "demo", new AbortController().signal)).toBe("ok")
     expect(asked).toMatchObject({
       kind: "handover",
@@ -1642,7 +1645,7 @@ steps:
     // Its context closed: the value stays known for the studio's life (a new live context too).
     expect(studio.scrub("x typed-in-check-1")).toBe("x [secret]")
     await live.context().close()
-    await studio.livePage()
+    await studio.livePage(undefined, new AbortController().signal)
     expect(studio.scrub("x typed-in-check-1")).toBe("x [secret]")
   }, 60_000)
 
diff --git a/vitest.config.ts b/vitest.config.ts
index 125b805..adee8ba 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -2,7 +2,7 @@ import { configDefaults, defineConfig } from "vitest/config"
 
 // The desktop-app target's tests launch a real Electron app each: they run alone, after every other
 // suite (a CPU busy with them made timing-sensitive tests elsewhere flaky in CI).
-const ELECTRON = "packages/runtime/test/electron*.test.ts"
+const ELECTRON = "packages/{runtime,studio}/test/electron*.test.ts"
 
 export default defineConfig({
   test: {

From bdcb7826ad491f7f526511ccc01a53e5d3a08712 Mon Sep 17 00:00:00 2001
From: Quang Lee <winlp4ever@gmail.com>
Date: Sun, 11 Oct 2026 21:32:41 +0200
Subject: [PATCH 09/10] feat(runtime): let a project's desktop app open
 terminals of its own (#63)

* feat(runtime): let a project's desktop app open terminals of its own

A confined app could make no pty (terminal apps failed with posix_spawnp),
and could print into every terminal the user had open. Now no app reaches a
terminal unless its project says terminals: true, ticked on its add card with
a warning and covered by its approval. Such a launch denies the user's ptys
open at launch every way (read, write, stat, chmod, ioctl, revoke), allows
new ones, and gives its shells a neutral prompt. A terminal the user opens
while it runs stays exposed (stated in BACKLOG).

* feat(scripts): add a desktop app to real-app runs

--desktop name=/path/App.app adds it through the Apps panel (picked, checked
confined, allowed), with --desktop-arg, --files and --desktop-terminals.
---
 apps/desktop/src/main/desktop-apps.ts         |  37 +++-
 apps/desktop/src/main/desktop-launch.ts       |   1 +
 apps/desktop/src/main/index.ts                |   4 +-
 .../renderer/src/components/apps-panel.tsx    |  35 +++-
 apps/desktop/src/renderer/src/styles.css      |   8 +
 apps/desktop/src/renderer/test/apps.test.tsx  |  70 ++++++-
 apps/desktop/src/shared/ipc.ts                |   6 +-
 apps/desktop/test/desktop-apps.test.ts        |  69 ++++++-
 apps/desktop/test/desktop-launch.test.ts      |  25 +++
 docs/BACKLOG.md                               |   1 +
 docs/FAILURE-CATALOGUE.md                     |   1 +
 docs/OBJECT-MODEL.md                          |   3 +-
 packages/runtime/src/electron-confine.ts      |  79 +++++++-
 packages/runtime/src/electron.ts              |  58 +++++-
 packages/runtime/test/electron.test.ts        | 172 +++++++++++++++++-
 .../test/fixtures/electron-app/main.cjs       |  59 ++++++
 packages/schema/src/project.ts                |   6 +
 scripts/real-apps/drive.ts                    | 104 +++++++++++
 18 files changed, 715 insertions(+), 23 deletions(-)

diff --git a/apps/desktop/src/main/desktop-apps.ts b/apps/desktop/src/main/desktop-apps.ts
index f08319b..c8b2b6f 100644
--- a/apps/desktop/src/main/desktop-apps.ts
+++ b/apps/desktop/src/main/desktop-apps.ts
@@ -63,10 +63,19 @@ const File = z.strictObject({
 })
 type File = z.infer<typeof File>
 
-/** What a project opens with an app (its arguments and sites), as one digest. */
-export function opensOf(app: Pick<ElectronApp, "args" | "origins">): string {
+/**
+ * What a project opens with an app (its arguments, sites, terminals), as one digest: what its
+ * approval covers. Terminals only when on (an approval from before them keeps its digest).
+ */
+export function opensOf(app: Pick<ElectronApp, "args" | "origins" | "terminals">): string {
   return createHash("sha256")
-    .update(JSON.stringify({ args: app.args ?? [], origins: app.origins ?? [] }))
+    .update(
+      JSON.stringify({
+        args: app.args ?? [],
+        origins: app.origins ?? [],
+        ...(app.terminals === true && { terminals: true }),
+      }),
+    )
     .digest("hex")
 }
 
@@ -280,9 +289,10 @@ export interface DesktopCard {
   existing: string | undefined
   /**
    * What that project opens with it, shown before it's allowed: its arguments (paths in files/,
-   * not passed to the check) and the sites it shows as its own (the check runs with them).
+   * not passed to the check), the sites it shows as its own (the check runs with them), and
+   * whether it opens terminals (never in the check: a few seconds need no shell).
    */
-  opens: { args: string[]; origins: string[] } | undefined
+  opens: { args: string[]; origins: string[]; terminals: boolean } | undefined
 }
 
 /**
@@ -408,7 +418,14 @@ export class DesktopAdds {
         signer:
           app.signer.kind === "team" ? { kind: "team", team: app.signer.team } : { kind: "pinned" },
         existing,
-        opens: entry === undefined ? undefined : { args: [...(entry.args ?? [])], origins: listed },
+        opens:
+          entry === undefined
+            ? undefined
+            : {
+                args: [...(entry.args ?? [])],
+                origins: listed,
+                terminals: entry.terminals === true,
+              },
       }
     } finally {
       if (this.#picks.get(owner)?.generation === generation) this.#picks.delete(owner)
@@ -463,9 +480,14 @@ export class DesktopAdds {
    * The tried app added to the project (or, named already, allowed here): its build checked again
    * (the one tried), the project written (its changed-on-disk refusal), then approved. Once the
    * project is written the add is done (an approval that fails then: said, allowed again later).
+   * `terminals`: a new app's, as the user chose on its card (an app the project names keeps the
+   * project's: shown on its card, never changed here).
    */
-  async add(owner: number, session: string, token: string): Promise<string> {
+  async add(owner: number, session: string, token: string, terminals = false): Promise<string> {
     const pending = this.#own(owner, session, token)
+    if (terminals && pending.existing !== undefined) {
+      throw refused("the project says whether it opens terminals: remove it to change that")
+    }
     if (pending.trial !== undefined) throw refused("it's being checked: wait for it")
     if (!pending.tried) throw refused("check it first: it's added once it ran here")
     if (pending.adding) throw refused("it's being added already")
@@ -507,6 +529,7 @@ export class DesktopAdds {
           kind: "electron",
           bundleId: now.bundleId,
           ...(pending.origins.length > 0 && { origins: pending.origins }),
+          ...(terminals && { terminals: true }),
           viewport: { width: 1440, height: 900, deviceScaleFactor: 1 },
         }
         save(opened, name, entry)
diff --git a/apps/desktop/src/main/desktop-launch.ts b/apps/desktop/src/main/desktop-launch.ts
index 8bb4d7c..821c3e4 100644
--- a/apps/desktop/src/main/desktop-launch.ts
+++ b/apps/desktop/src/main/desktop-launch.ts
@@ -139,6 +139,7 @@ export class DesktopLauncher {
       ...(existsSync(files) && { files }),
       ...(entry.args !== undefined && { args: entry.args }),
       ...(entry.origins !== undefined && { origins: entry.origins }),
+      ...(entry.terminals === true && { terminals: true }),
       viewport: entry.viewport,
       ...(signal !== undefined && { signal }),
       ...(this.#deps.workDir !== undefined && { workDir: this.#deps.workDir }),
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index 3d28f8f..226e3ac 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -598,9 +598,9 @@ function start(): void {
             return { failed: message(e) }
           }
         },
-        "apps:desktop-add": async ({ session, token }) => {
+        "apps:desktop-add": async ({ session, token, terminals }) => {
           try {
-            await adds.add(owner(), session, token)
+            await adds.add(owner(), session, token, terminals)
             return null
           } catch (e) {
             return message(e)
diff --git a/apps/desktop/src/renderer/src/components/apps-panel.tsx b/apps/desktop/src/renderer/src/components/apps-panel.tsx
index dfabcbd..6c05162 100644
--- a/apps/desktop/src/renderer/src/components/apps-panel.tsx
+++ b/apps/desktop/src/renderer/src/components/apps-panel.tsx
@@ -16,6 +16,11 @@ import { useChat } from "../chat-store.ts"
 
 type Card = Extract<DesktopPick, { card: unknown }>["card"]
 
+/** What an app allowed its own terminals is open to (said on its card before it's added). */
+const TERMINALS_WARNING =
+  "Its terminals work. While Kiframe runs it, a terminal you open (in any app) can be read and " +
+  "typed into by it: only for apps you trust, and review what Kif does with it."
+
 /** A desktop app's status on this Mac, in words. */
 function statusText(entry: DesktopStatusView["apps"][string] | undefined): string {
   if (entry === undefined) return ""
@@ -41,6 +46,8 @@ export function AppsPanel({
   const [checking, setChecking] = useState(false)
   const [picking, setPicking] = useState(false)
   const [adding, setAdding] = useState(false)
+  // A new app's terminals (off unless the user ticks it for this card).
+  const [terminals, setTerminals] = useState(false)
   // The card a check's answer belongs to (an answer for a card given up: dropped).
   const current = useRef<string | null>(null)
   current.current = card?.token ?? null
@@ -114,6 +121,7 @@ export function AppsPanel({
       setError(picked.refused)
       return
     }
+    setTerminals(false)
     setCard(picked.card)
   }
 
@@ -139,7 +147,11 @@ export function AppsPanel({
     addingNow.current = token
     setAdding(true)
     const refused = await api()
-      .invoke("apps:desktop-add", { session: project.session, token })
+      .invoke("apps:desktop-add", {
+        session: project.session,
+        token,
+        terminals: card.existing === undefined && terminals,
+      })
       .catch((e: unknown) => String(e))
     if (addingNow.current === token) addingNow.current = null
     setAdding(false)
@@ -231,14 +243,33 @@ export function AppsPanel({
                 This project names it already (as {card.existing}): checking it allows it here, with
                 what the project opens with it:{" "}
                 {card.opens === undefined ||
-                (card.opens.args.length === 0 && card.opens.origins.length === 0)
+                (card.opens.args.length === 0 &&
+                  card.opens.origins.length === 0 &&
+                  !card.opens.terminals)
                   ? "nothing more."
                   : [
                       ...card.opens.origins.map((o) => `the site ${o} as its own`),
                       ...card.opens.args.map((a) => `${a} (not opened by the check)`),
+                      ...(card.opens.terminals ? ["terminals of its own"] : []),
                     ].join(", ")}
               </p>
             )}
+            {card.existing === undefined && (
+              <label className="app-card-option">
+                <input
+                  type="checkbox"
+                  checked={terminals}
+                  disabled={adding}
+                  onChange={(e) => setTerminals(e.target.checked)}
+                />
+                It opens terminals (a terminal app, an editor’s terminal)
+              </label>
+            )}
+            {(card.existing === undefined ? terminals : card.opens?.terminals === true) && (
+              <p className="app-card-why app-card-warn" role="note">
+                {TERMINALS_WARNING}
+              </p>
+            )}
             <p className="app-card-why">
               Kiframe opens {card.name} confined (it can’t read or change your files, your own{" "}
               {card.name}’s data or its preferences) for a few seconds, to check it works there.
diff --git a/apps/desktop/src/renderer/src/styles.css b/apps/desktop/src/renderer/src/styles.css
index af703e7..bf6e78c 100644
--- a/apps/desktop/src/renderer/src/styles.css
+++ b/apps/desktop/src/renderer/src/styles.css
@@ -1679,6 +1679,14 @@ ul.strip-cards > li {
   color: var(--muted);
 }
 
+.app-card-option {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin: 4px 0 8px;
+  font-size: 13px;
+}
+
 .app-card-label {
   font-style: italic;
 }
diff --git a/apps/desktop/src/renderer/test/apps.test.tsx b/apps/desktop/src/renderer/test/apps.test.tsx
index ec3b981..65fc337 100644
--- a/apps/desktop/src/renderer/test/apps.test.tsx
+++ b/apps/desktop/src/renderer/test/apps.test.tsx
@@ -168,7 +168,11 @@ describe("adding a desktop app", () => {
       token: card.token,
       allowSite: true,
     })
-    expect(invoke).toHaveBeenCalledWith("apps:desktop-add", { session: "s1", token: card.token })
+    expect(invoke).toHaveBeenCalledWith("apps:desktop-add", {
+      session: "s1",
+      token: card.token,
+      terminals: false,
+    })
     // The window named no path and no site: only its session, the token and a yes.
     expect(JSON.stringify(invoke.mock.calls)).not.toMatch(/Applications|slack\.com"/)
   })
@@ -200,7 +204,7 @@ describe("adding a desktop app", () => {
         card: {
           ...card,
           existing: "slack",
-          opens: { args: ["files/vault"], origins: ["https://evil.example"] },
+          opens: { args: ["files/vault"], origins: ["https://evil.example"], terminals: false },
         },
       }),
       "apps:desktop-cancel": () => undefined,
@@ -212,6 +216,68 @@ describe("adding a desktop app", () => {
     const adding = await within(panel).findByRole("region", { name: "Adding Slack" })
     expect(adding.textContent).toContain("the site https://evil.example as its own")
     expect(adding.textContent).toContain("files/vault (not opened by the check)")
+    expect(within(adding).queryByRole("note")).toBeNull()
+  })
+
+  it("warns before allowing an app the project lets open terminals (never a choice made here)", async () => {
+    const { invoke } = stubApi({
+      "app:status": () => status({ hasKey: true, project }),
+      "apps:desktop-pick": () => ({
+        card: { ...card, existing: "minmux", opens: { args: [], origins: [], terminals: true } },
+      }),
+      "apps:desktop-check": () => ({ ok: true }),
+      "apps:desktop-add": () => null,
+      "apps:desktop-cancel": () => undefined,
+    })
+    render(<App />)
+    fireEvent.click(await screen.findByRole("button", { name: /app\.test/ }))
+    const panel = screen.getByRole("dialog", { name: "Apps" })
+    fireEvent.click(within(panel).getByRole("button", { name: "Add desktop app…" }))
+    const adding = await within(panel).findByRole("region", { name: "Adding Slack" })
+    expect(adding.textContent).toContain("terminals of its own")
+    expect(within(adding).getByRole("note").textContent).toMatch(/can be read and typed into/)
+    // The project's say, shown: no box to change it here.
+    expect(within(adding).queryByRole("checkbox")).toBeNull()
+    fireEvent.click(within(adding).getByRole("button", { name: "Check" }))
+    fireEvent.click(await within(adding).findByRole("button", { name: "Allow Slack here" }))
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(invoke).toHaveBeenCalledWith("apps:desktop-add", {
+      session: "s1",
+      token: card.token,
+      terminals: false,
+    })
+  })
+
+  it("lets a new app open terminals only when ticked, warned of what that exposes", async () => {
+    const { invoke } = stubApi({
+      "app:status": () => status({ hasKey: true, project }),
+      "apps:desktop-pick": () => ({ card }),
+      "apps:desktop-check": () => ({ ok: true }),
+      "apps:desktop-add": () => null,
+      "apps:desktop-cancel": () => undefined,
+    })
+    render(<App />)
+    fireEvent.click(await screen.findByRole("button", { name: /app\.test/ }))
+    const panel = screen.getByRole("dialog", { name: "Apps" })
+    fireEvent.click(within(panel).getByRole("button", { name: "Add desktop app…" }))
+    const adding = await within(panel).findByRole("region", { name: "Adding Slack" })
+    const box = within(adding).getByRole("checkbox", { name: /It opens terminals/ })
+    expect((box as HTMLInputElement).checked).toBe(false)
+    expect(within(adding).queryByRole("note")).toBeNull()
+    fireEvent.click(box)
+    expect(within(adding).getByRole("note").textContent).toMatch(/can be read and typed into/)
+    fireEvent.click(within(adding).getByRole("button", { name: "Check" }))
+    fireEvent.click(await within(adding).findByRole("button", { name: "Add Slack" }))
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(invoke).toHaveBeenCalledWith("apps:desktop-add", {
+      session: "s1",
+      token: card.token,
+      terminals: true,
+    })
   })
 
   it("never shows a check's answer on a card picked after it was given up", async () => {
diff --git a/apps/desktop/src/shared/ipc.ts b/apps/desktop/src/shared/ipc.ts
index 9f4d45a..524ee02 100644
--- a/apps/desktop/src/shared/ipc.ts
+++ b/apps/desktop/src/shared/ipc.ts
@@ -313,7 +313,7 @@ export type DesktopPick =
         /** The project names it already (a project from someone else): adding approves it here. */
         existing: string | undefined
         /** What that project opens with it (shown before it's allowed). */
-        opens: { args: string[]; origins: string[] } | undefined
+        opens: { args: string[]; origins: string[]; terminals: boolean } | undefined
       }
     }
   | { refused: string }
@@ -443,7 +443,9 @@ export const invokeArgs = {
     z.strictObject({ session: z.string().max(64), token: z.uuid(), allowSite: z.boolean() }),
   ]),
   /** The tried app added to the open project (or, named already, approved here). */
-  "apps:desktop-add": z.tuple([z.strictObject({ session: z.string().max(64), token: z.uuid() })]),
+  "apps:desktop-add": z.tuple([
+    z.strictObject({ session: z.string().max(64), token: z.uuid(), terminals: z.boolean() }),
+  ]),
   /** The add given up (its trial ended). */
   "apps:desktop-cancel": z.tuple([]),
   /** The open project's desktop apps as this Mac has them (static: nothing launches). */
diff --git a/apps/desktop/test/desktop-apps.test.ts b/apps/desktop/test/desktop-apps.test.ts
index 2e5ba20..f1278d3 100644
--- a/apps/desktop/test/desktop-apps.test.ts
+++ b/apps/desktop/test/desktop-apps.test.ts
@@ -196,6 +196,16 @@ describe("a desktop app's status (static: nothing launches)", () => {
     expect((await status(at, approved, opens)).status).toBe("opens-changed")
   })
 
+  it("asks again for an app the project now lets open terminals; off is as never said", async () => {
+    const at = { "/Applications/Notes.app": notes() }
+    expect((await status(at, approved, entry({ terminals: true }))).status).toBe("opens-changed")
+    expect((await status(at, approved, entry({ terminals: false }))).status).toBe("ready")
+    // Approvals from before terminals keep their digest (never all asked again by an update).
+    expect(opensOf(entry())).toBe(
+      "be954a12116b1369a8f5d36bdb9f9c4482b0bc8cb3465685b11bbf6106b7584b",
+    )
+  })
+
   it("keeps each project's tried build: another's approval of an update changes nothing here", async () => {
     const approvals = new DesktopApprovals(dir())
     approvals.approve(notes(), "folder-b", opensOf(entry()))
@@ -318,6 +328,23 @@ describe("adding a desktop app", () => {
     ).toMatchObject({ status: "ready" })
   })
 
+  it("lets it open terminals only as its card was ticked, approved with them", async () => {
+    for (const terminals of [false, true]) {
+      const h = harness()
+      const card = await h.pick()
+      await h.adds.check(1, "s1", card.token, false)
+      // Its check never opens terminals (a few seconds need no shell).
+      expect(h.fake.trials[0]).not.toHaveProperty("terminals")
+      expect(await h.adds.add(1, "s1", card.token, terminals)).toBe("notes")
+      const written = openProject(h.opened.dir).project.apps["notes"] as ElectronApp
+      // Written only when on (never `terminals: false`).
+      expect("terminals" in written, `terminals: ${terminals}`).toBe(terminals)
+      expect(await desktopStatus(written, "folder-a", h.approvals, h.fake.looks)).toMatchObject({
+        status: "ready",
+      })
+    }
+  })
+
   it("allows a wrapper's site only as the trial named it, tried before it's added", async () => {
     const h = harness(project(), undefined, (o) =>
       (o.origins ?? []).length > 0 ? { ok: true } : { site: "https://app.slack.com" },
@@ -485,7 +512,11 @@ describe("adding an app a project already names", () => {
     const h = harness(named())
     const card = await h.pick()
     expect(card.existing).toBe("desk")
-    expect(card.opens).toEqual({ args: ["files/vault"], origins: ["https://a.example"] })
+    expect(card.opens).toEqual({
+      args: ["files/vault"],
+      origins: ["https://a.example"],
+      terminals: false,
+    })
     await h.adds.check(1, "s1", card.token, false)
     expect(h.fake.trials[0]?.origins).toEqual(["https://a.example"])
     expect(await h.adds.add(1, "s1", card.token)).toBe("desk")
@@ -510,6 +541,42 @@ describe("adding an app a project already names", () => {
     await expect(h.adds.add(1, "s1", card.token)).rejects.toThrow(/the project changed meanwhile/)
   })
 
+  it("shows its terminals before it's allowed, and never turns them on from the card", async () => {
+    const opened = project()
+    saveProject(opened, {
+      ...opened.project,
+      apps: { ...opened.project.apps, desk: entry({ terminals: true }) },
+    })
+    const h = harness(opened)
+    const card = await h.pick()
+    expect(card.opens?.terminals).toBe(true)
+    await h.adds.check(1, "s1", card.token, false)
+    expect(await h.adds.add(1, "s1", card.token)).toBe("desk")
+    expect(h.approvals.copyFor("com.example.Notes", "folder-a")?.scopes["folder-a"]?.opens).toBe(
+      opensOf(entry({ terminals: true })),
+    )
+    // One it names without them: the card's say never adds them.
+    const plain = harness(named())
+    const off = await plain.pick()
+    await plain.adds.check(1, "s1", off.token, false)
+    await expect(plain.adds.add(1, "s1", off.token, true)).rejects.toThrow(/remove it to change/)
+    expect(openProject(plain.opened.dir).project.apps["desk"]).not.toHaveProperty("terminals")
+    expect(plain.approvals.copyFor("com.example.Notes", "folder-a")).toBeUndefined()
+  })
+
+  it("never approves terminals turned on since the pick", async () => {
+    const h = harness(named())
+    const card = await h.pick()
+    await h.adds.check(1, "s1", card.token, false)
+    const desk = h.opened.project.apps["desk"] as ElectronApp
+    saveProject(h.opened, {
+      ...h.opened.project,
+      apps: { ...h.opened.project.apps, desk: { ...desk, terminals: true } },
+    })
+    await expect(h.adds.add(1, "s1", card.token)).rejects.toThrow(/the project changed meanwhile/)
+    expect(h.approvals.copyFor("com.example.Notes", "folder-a")).toBeUndefined()
+  })
+
   it("writes a site allowed in its check to the project, and approves that", async () => {
     const opened = project()
     saveProject(opened, { ...opened.project, apps: { ...opened.project.apps, desk: entry() } })
diff --git a/apps/desktop/test/desktop-launch.test.ts b/apps/desktop/test/desktop-launch.test.ts
index c60f458..4212199 100644
--- a/apps/desktop/test/desktop-launch.test.ts
+++ b/apps/desktop/test/desktop-launch.test.ts
@@ -121,6 +121,31 @@ describe("a desktop app launched for the agent", () => {
     expect(state.launches).toEqual([])
   })
 
+  it("opens terminals only as approved here: a project that turned them on is asked again", async () => {
+    // Never when the project doesn't say so.
+    const plain = setup()
+    await plain.launcher.launch("notes")
+    expect(plain.state.launches[0]?.terminals).toBeUndefined()
+    // Turned on (a teammate's push, a hand edit), an update waiting too: refused, never tried.
+    for (const installed of [notes(), notes({ version: "1.1" })]) {
+      const { launcher, state, approvals, opened } = setup(installed)
+      saveProject(opened, {
+        ...opened.project,
+        apps: { ...opened.project.apps, notes: entry({ terminals: true }) },
+      })
+      await expect(launcher.launch("notes")).rejects.toThrow(/changed what it opens/)
+      expect(state.launches).toEqual([])
+      expect(state.trials).toBe(0)
+      expect(approvals.copyFor("com.example.Notes", "folder-a")?.scopes["folder-a"]?.opens).toBe(
+        opensOf(entry()),
+      )
+      // Allowed again here (the card said it): launched with them.
+      approvals.approve(installed, "folder-a", opensOf(entry({ terminals: true })))
+      await launcher.launch("notes")
+      expect(state.launches[0]?.terminals).toBe(true)
+    }
+  })
+
   it("tries an update quietly, then approves that build for the project and launches it", async () => {
     const { launcher, state, approvals } = setup(notes({ version: "1.1" }))
     await launcher.launch("notes")
diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md
index 9428843..c32f267 100644
--- a/docs/BACKLOG.md
+++ b/docs/BACKLOG.md
@@ -243,6 +243,7 @@ Non-severe review findings deferred on purpose (see the review-round rule: only
 
 ## Vault hardening (M1-7)
 - **Electron targets:** an app attached over CDP (F4) runs in its own persistent profile: no ephemeral context there. The app's own storage keeps whatever the scene typed; document it for Electron projects and prefer a throwaway app profile (`--user-data-dir` per run).
+- **Terminals in a desktop app's demo (decided 2026-10-11):** an app its project lets open terminals (`terminals: true`, chosen when it's added, warned, approved with it) gets new ptys; the user's terminals open at launch are never reached (read, written, chmod, revoked). Stated gaps: a terminal the user opens while a launch lives (any app's) can be read (keystrokes, passwords), written and revoked by it, since Seatbelt can't tell its ptys from the user's: a pty broker (Kiframe opens them, the app gets descriptors) would close it. Closing a terminal that was open at launch can make the app's next pty fail (its number is reused, still denied). Helpers some apps run through a pty without terminals (askpass, some language servers) fail. An app the project already names keeps its project's setting: remove and add it again to change it. Its checks (adding it, a quiet trial of an update) run without terminals: an app that quits without a pty at start can't be added yet.
 - **Copy and paste in a desktop app's demo:** the confinement denies the pasteboard (the user's clipboard may hold a password), so an app's own copy and paste does nothing in a run. A demo that needs it: a run-only pasteboard (a private named pasteboard can't be forced on an app) or typing the pasted text.
 - **What a confined app opens through LaunchServices:** an app can't start without `launchservicesd`, and through it it can open a file or a URL that then runs unconfined (a script it wrote, the user's browser). Stated in §0.9 (accident, not a hostile app); an Endpoint Security watcher or a per-run user account would close it.
 - **Desktop-app sweeps read processes more than once:** the startup sweep runs one `ps` per leftover sandbox (one `ps -axo pid=,lstart=` table would answer every owner), and a run's close reads the process table twice (`orphanedGroup` and `sweepProcesses`). Startup and close time only (#58 review).
diff --git a/docs/FAILURE-CATALOGUE.md b/docs/FAILURE-CATALOGUE.md
index ba09b0d..b3b69e4 100644
--- a/docs/FAILURE-CATALOGUE.md
+++ b/docs/FAILURE-CATALOGUE.md
@@ -29,3 +29,4 @@
 | 21 | Every snapshot ref refused | Cal.com (desktop app, 2026-10-03, acting by ref) | Right after a snapshot, `run_steps` said "ref e23: it isn't on the page anymore" twice; the agent went back to writing locators. Playwright's `elementHandle()` on an `aria-ref` waits about 1.6 s on Cal.com's login page (count is 1 at once), past the 1 s the studio gave it | — | Done: a ref's element is looked up with `elementHandles()` (no wait: a fresh snapshot just saw it), right before its step |
 | 22 | Content past the snapshot's cut | Wikipedia (desktop app, 2026-10-05) | "Search Messi, then go to his WC26 campaign": the article's snapshot is 1.14 M characters, the agent reads the first 20 k. It never saw the 2026 part: ~35 snapshots (25 failed `within` guesses: Wikipedia's sections have no names), the search page, the API, the printable page, until the 12 min ran out ($0.11). The user saw it as "scroll not working". With `find` (rerun, traced) it scrolled to the 2026 part in 3 min, then took a snapshot "to check where the page is now": a snapshot starts at the page's top whatever the scroll, and it thought 283 s about why nothing moved. Model time 704 s of 730 (tools 26 s) | — | Done: `snapshot` takes `find` (the elements that mention a text, with their ancestors and refs, searched in the scrubbed snapshot); the cut says to use it; every snapshot says where the view is (how far down, the section) and that it covers the whole page. The thinking itself: capped next (its own PR) |
 | 23 | The recording fails where the replay passed | Wikipedia (desktop app, 2026-10-05/06) | "Search Messi": `save_scene`'s replay passed, `record_scene` failed with "locator.press: Timeout 15000ms exceeded" on the search step, every run (the agent worked around it, minutes each time). Typed at a person's pace, Wikipedia swaps its search box for a combobox mid-typing: the text still goes to the focused new field, but `submit` pressed Enter on the target's locator (a "Search Wikipedia" searchbox, gone). The replay typed at once, before the swap | — | Done: when the focused text field holds the typed text and the target is gone (or doesn't hold it: a modal took the keys), Enter goes where the text is; otherwise the target, as before. `save_scene` replays with the recording's typing and settling (pointer at once) and pixel ratio, so what a person's typing changes fails before the recording |
+| 24 | A terminal app's shell refused by the confinement | minmux (desktop app, confined, 2026-10-11) | Every terminal pane said "posix_spawnp failed": Seatbelt denied /dev/ptmx, so no pty could be made; Kif spent the run on diagnostics. Measuring it found the old rule let any confined app print into every terminal the user had open (input injection refused by macOS) | Per app, opt-in (user decision): `terminals: true` allows new ptys and denies the user's terminals open at launch (every way: read, write, chmod, ioctl, revoke); every other app gets no terminal at all | Done (stated gap: terminals opened while it runs, BACKLOG) |
diff --git a/docs/OBJECT-MODEL.md b/docs/OBJECT-MODEL.md
index 3dc6e05..e2ddbeb 100644
--- a/docs/OBJECT-MODEL.md
+++ b/docs/OBJECT-MODEL.md
@@ -223,13 +223,14 @@ One scene, three phases. The agent's own instructions say the same (`packages/st
 
 **Desktop apps.** The same `apps` entry with `kind: electron` (launched and attached over its debugging port: `--remote-debugging-port` + `connectOverCDP`, measured working on a hardened packaged app in Phase 0, F4) or `kind: tauri` (WebKit on macOS: no CDP, partial support, APPROACHES §6b). The format is ready for them; driving them is v0.1 work.
 
-**Electron apps (designed 2026-10-08, design reviewed; moved into v0).** `{ kind: "electron", bundleId, args?, origins?, viewport }`:
+**Electron apps (designed 2026-10-08, design reviewed; moved into v0).** `{ kind: "electron", bundleId, args?, origins?, terminals?, viewport }`:
 - **Named by bundle id, never a path or a program** (a project may come from someone else): the desktop app finds the bundle on each machine and keeps the user's approval in its own settings (bundle id, real path, signing team); only `.app` bundles holding `Electron Framework.framework`; App Store (sandboxed) apps refused. `args` are positional only (no switches). `origins`: the https sites a wrapper app (Slack, Notion) shows as its own.
 - **No address**: a goto or a URL condition on it is refused; a scene starting in it opens on its first window; it takes no secrets in v0 (the user signs in by hand: the handover).
 - **Each run launches it sandboxed** (its own HOME, `CFFIXED_USER_HOME`, XDG and temp folders, `--user-data-dir`; an allowlisted environment, never Kiframe's), attached with `--remote-debugging-port=0` + `connectOverCDP`; the viewport is emulated (a spike measured frames and clicks with the window covered, off-screen, minimized or hidden: a run never needs the user's screen; the window itself can't be moved over CDP). Isolation is enforced, never checked after the fact: every launch is confined (below). Its process group killed after each run, leftovers swept.
 - **Confinement: a guard, sealed at launch (PR 2, redesigned after three review rounds, design reviewed).** Once the app settles (its windows unchanged 1.5 s), its main window is the last opened still open; its own scheme or dev server is learned from that window alone, then sealed (nothing a run does adds to it). A main window that isn't the app's own (a wrapper's unlisted site) refuses the launch ("list it in its origins"). From then a **guard** checks every navigation of every frame of every window as it happens: a page that isn't the app's own is stopped at once (a popup closed, any other frame blanked: never left for a read or a frame) and recorded; the step fails `off-app`. The app's own: a local `file:` in its bundle or sandbox (decoded, normalized), its sealed scheme or dev server, a listed https site (`sameApp`, never plain http), a blob of those. Stated (as a web run): the guard acts as a page commits, so a page that isn't the app's own has loaded (its scripts ran, with the app's own rights) before it's stopped: following a link the app offers is what its user does too (blocking before the load needs request interception, which never sees `file:`); and the runner's own navigation events name it as they do for web runs (origin and path, known secret values scrubbed). What the main window embeds as it opens (a frame of another site) is the app as shipped: its origin is the app's own. A main window stopped goes back to the app's page (no goto there to bring it back); a failed load is said as one. **One app per run:** a desktop app's run never shows a site (no goto, URL condition or web preset; a web interrupt rule's goto skipped, said), is confined while grounding too, and keeps no sign-in between runs yet.
 - **Windows (PR 2, known limits, to settle on real apps in PR 3 and PR 5: decided by the user 2026-10-08):** the main window is the last opened still open once the app's windows were unchanged for 1.5 s (a splash that stays up longer is taken for the main window); windows the app's main process opens are followed as popups are (a hidden helper window opened during a step may be followed: CDP can't tell it's hidden); only the launch window is sent back when it goes off-app (another window is closed); a stop that lands after its step ended counts against the next step. A window that opens blank gets a moment to load (as a web page does); a frame of a window the run isn't driving is said, never the step's failure.
 - **Every launch confined (PR 3a, 2026-10-09, design reviewed twice, measured):** on macOS each launch runs under Seatbelt (`sandbox-exec`, `electron-confine.ts`): writes only into its own sandbox; no reads of /Users, /Volumes, the temp folders, the user's home and the work area wherever they are (a home outside /Users) but its sandbox and its bundle; nothing run from its sandbox (the one place it writes: a program it drops there, a copied launcher), no `open`, `osascript`, `launchctl` nor Apple Events; no unix sockets (an agent's: ssh, Docker) but mDNSResponder; no preferences (cfprefsd), keychain (SecurityServer: a mock keychain instead, `--use-mock-keychain`) nor clipboard (the user's may hold a password just copied: an app's own copy and paste doesn't work in a run); the network on, for runs and trials alike (the app's backend, a wrapper's site: an updater can't touch the real app, nothing outside the sandbox being written; what an app could send is only what it can read here: its bundle, the system's files, its own sandbox). Chromium's own sandbox can't nest in it (`--no-sandbox`): the guard and this profile replace it. A canary before every launch, before the files are copied (a read the profile refuses must fail, one of its sandbox succeed: a confinement that runs nothing never passes); no `sandbox-exec`, or a canary failed: no launch (never unconfined). Off macOS: desktop apps don't launch (CI's tests only, unconfined). Measured with a probe app: every escape above `EPERM` (a hard link or a symlink to an outside file too), the app driven as usual. This replaces the trial's after-the-fact isolation check, rejected by review (an app that leaks does its harm as it starts). **What it doesn't stop (stated):** an app can still ask macOS to open a file or a URL (LaunchServices: no app starts without reaching it, measured), and what opens runs outside the confinement; it reaches services on this machine (localhost: a dev build's own server needs it). The app's own pages are its bundle and what it writes in its sandbox's home, profile and temp folders (a page it builds there from remote content counts as its own, as its cache already does); never the files/ copy. The confinement keeps an app from the user's data by accident (the minmux incident), not an app built to escape (one the user runs unconfined every day anyway).
+- **Terminals, per app (2026-10-11, design reviewed twice, measured):** no app reaches a terminal (no pty, none of the user's ttys read or written) unless its project says `terminals: true` (a terminal app, an editor's terminal): ticked on its add card, which says what it exposes; part of what its approval covers (in the opens digest only when on: approvals from before keep theirs), so a project that turns it on is asked again, and an app the project names already shows it before it's allowed (never changed from the card). Such an app's launch lists the user's terminals open just before it starts (ptys a user owns: a free pty's leftover node is root's, left for the app's own next pty; one in use by root is closed to it by its mode) and denies each every way (read, write, chmod, ioctl, revoke), allowing new ptys; that profile is checked to load before the app starts. Stated: a terminal the user opens while it runs is exposed to it (BACKLOG). Its checks run without terminals. Its shells' prompt shows the folder only (user decision 2026-10-11: a `.zshrc`, `.bashrc`, `.bash_profile` and fish config in its fresh home; never the user's login or Mac's name on camera).
 - **Adding a desktop app (PR 3b, design reviewed 2026-10-09):** inspected first, statically (`electron-inspect.ts`: only `plutil` and `codesign` run): refused outside where an app can stay (a disk image, a temporary translocated copy, the Trash, inside another app), not Electron (its framework; no version gate: Figma reports 13.6.1), an executable that isn't its own file, a Mac App Store build (App Sandbox), a developer signature that doesn't hold (`codesign --verify --strict` against its team and signed identifier). Kept: its id, name, Electron's version, and its signer: a developer (team id) or, ad hoc and unsigned (the user's own builds), pinned to a digest of the whole bundle (a link leading outside it refused; at most 4 GB and 200,000 entries). Then **tried confined** (`electron-trial.ts`): launched with the network as in a run (an updater can't touch the real app: nothing outside the sandbox is written; a wrapper's offline page can't hide its site), its main window attached, closed; a wrapper's site is named (even unreached: the error page's unreachable URL, over CDP) and allowed by the user in a second trial. A main window that never loaded its own page (offline, a dev server not running) is refused at launch, said as such: never a window driven on Chromium's error page. An attach that hangs as the first page fails (measured 1 in 5; cause not found) is tried again within the launch's time (stated). A trial runs only the build that was picked (its developer's signature, or its pinned digest, checked first; a change between that check and the launch is the user's own build tool's: holding every launch to its approval is PR 4's, with runs). codesign that fails or times out refuses the app (never read as unsigned or unsandboxed). Apps that allow one copy (Slack, VS Code, Discord) need Chromium's temp folder in the sandbox (`MAC_CHROMIUM_TMPDIR`): its lock's socket otherwise goes to the user's /var/folders, denied, and the app quits.
 - **Approvals (PR 3b-2, user decisions 2026-10-09):** added from the Apps panel ("Add desktop app…", macOS): main shows the picker (Applications) and inspects what was picked; the window gets a card and a token, never the app's path, and never names a site to allow (the trial's, kept in main). Tried confined, then added (the build that was tried is approved: one updated since says "updated"; `project.json`, its changed-on-disk refusal) and approved in app data (`desktop-apps.json`, 0600, written whole; one that doesn't read is set aside and said, never overwritten). An approval is per copy of the app on this Mac (where it was picked: a release and a dev build of one bundle id kept apart, a project using one of them; at most 20 copies of one app kept, the oldest let go) and per project folder (the registry's scope) and covers the app (its developer's team, or the exact build of an unsigned one) **and what the project opens with it** (its `args` and `origins`, as a digest): a pull that changes either asks again. Statuses (static, opening the panel launches nothing): ready; updated (same developer, a build this project hasn't tried: tried confined before its next run, PR 4, which records it); allow (approved for another project, or never on this Mac: pick it to allow it here, without adding it twice); opens-changed; changed (another developer, another unsigned build); not found. Removing the app drops this project's approval. Off macOS: nothing offered. A trial in progress ends with its add (another pick, the project closed, a quit); what a crash left is swept at the start.
 - **Launching an approved app (PR 4, design reviewed 2026-10-10):** main launches a project's desktop app only from its approval for this project folder and what it opens (`desktop-launch.ts`): the copy approved, inspected once (its status); `ready` launches it (the copy's executable and bundle; the project's `files/` when it has one, its `args`, `origins`, viewport); `updated` (the same developer's new build) is tried confined first, quietly (one trial per app and project at a time), then that build approved for the project compare-and-set (the same copy, developer and opens, the project still the open one: else refused); anything else is refused for the user to settle in the Apps panel (`needsUser`: the agent says so, never retries). A take of a desktop app keeps its build (`appBuild`: its version and what it opened; never in the take's key, never a reason to record again: user decision 2026-10-10; an older Kiframe can't read such a take: its meta is strict). Kif starting ends an add's check in progress.
diff --git a/packages/runtime/src/electron-confine.ts b/packages/runtime/src/electron-confine.ts
index b17070a..97e59d1 100644
--- a/packages/runtime/src/electron-confine.ts
+++ b/packages/runtime/src/electron-confine.ts
@@ -28,6 +28,11 @@ export interface Confinement {
    * they are (a home outside /Users on a managed Mac).
    */
   private: readonly string[]
+  /**
+   * Its own terminals allowed (the project's app opens them, approved as such): the user's open at
+   * launch (`openTerminals`) never reached. Absent: no terminal at all.
+   */
+  terminals?: { existing: readonly string[] }
 }
 
 /**
@@ -36,13 +41,84 @@ export interface Confinement {
  */
 export const quoted = (s: string) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
 
+/** What `openTerminals` reads of /dev (the tests' own). */
+export interface DevView {
+  list: () => Promise<string[]>
+  /** A node's owner; undefined when it's gone (closed meanwhile). */
+  owner: (path: string) => Promise<number | undefined>
+}
+
+const DEV: DevView = {
+  list: () => readdir("/dev"),
+  owner: async (path) => {
+    try {
+      return (await lstat(path)).uid
+    } catch (error) {
+      if ((error as { code?: string }).code === "ENOENT") return undefined
+      throw error
+    }
+  },
+}
+
+/**
+ * The user's terminals there now (ptys owned by a user: a pty in use belongs to whoever opened
+ * it), never reached by an app allowed its own. A free pty's node stays, owned by root (measured
+ * 2026-10-11): never listed, the app's own next pty may take its number; one in use by root is
+ * closed to the app by its mode already. Seatbelt can't tell a pty the app opens later from one
+ * the user opens: those stay exposed (stated in BACKLOG). Unreadable: refused (never unlisted).
+ */
+export async function openTerminals(dev: DevView = DEV): Promise<string[]> {
+  try {
+    const paths = (await dev.list()).filter((n) => /^ttys[0-9]+$/.test(n)).map((n) => `/dev/${n}`)
+    const owners = await Promise.all(paths.map((path) => dev.owner(path)))
+    return paths.filter((_, i) => owners[i] !== undefined && owners[i] !== 0)
+  } catch {
+    throw new ConfinementError("the open terminals couldn't be listed: the app isn't launched")
+  }
+}
+
+/**
+ * The profile with an app's terminals parses (it isn't the one the canary ran): a macOS that
+ * refused it would otherwise read as an app that quit at once.
+ */
+export function checkProfile(profile: string, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    execFile(
+      SANDBOX_EXEC,
+      ["-p", profile, "/usr/bin/true"],
+      { timeout: 5000, ...(signal !== undefined && { signal }) },
+      (error) =>
+        error === null
+          ? resolve()
+          : reject(new ConfinementError("the confinement for its terminals didn't load")),
+    )
+  })
+}
+
+/**
+ * Every way to reach a terminal: read, written, its mode changed, its ioctls, revoked (killed),
+ * its times watched (when the user types).
+ */
+const TERMINAL_OPS = "file-read-data file-read-metadata file-write* file-ioctl file-revoke"
+
 /** The Seatbelt profile of a launch. Later rules win over earlier ones. */
 export function seatbeltProfile(c: Confinement): string {
   const readable = [c.sandbox, ...c.readable].map((p) => `(subpath ${quoted(p)})`).join(" ")
+  // Its own ptys (new ones), or none; never the user's (open at launch), serial lines, BSD ptys.
+  const ptys =
+    c.terminals === undefined ? "" : ' (literal "/dev/ptmx") (regex #"^/dev/ttys[0-9]+$")'
+  // Every tty but its own new ptys (ttysNNN) and /dev/tty; the user's ptys, each.
+  const terminals =
+    c.terminals === undefined
+      ? '(regex #"^/dev/tty.") (literal "/dev/ptmx")'
+      : [
+          '(regex #"^/dev/tty[^s]")',
+          ...c.terminals.existing.map((t) => `(literal ${quoted(t)})`),
+        ].join(" ")
   return `(version 1)
 (allow default)
 (deny file-write*)
-(allow file-write* (subpath ${quoted(c.sandbox)}) (literal "/dev/null") (literal "/dev/zero") (literal "/dev/dtracehelper") (regex #"^/dev/tty") (regex #"^/dev/fd/"))
+(allow file-write* (subpath ${quoted(c.sandbox)}) (literal "/dev/null") (literal "/dev/zero") (literal "/dev/dtracehelper") (literal "/dev/tty")${ptys} (regex #"^/dev/fd/"))
 (deny file-read-data (subpath "/Users") (subpath "/Volumes") (subpath "/private/var/folders") (subpath "/private/tmp") (subpath "/var/folders") (subpath "/tmp")${c.private.map((p) => ` (subpath ${quoted(p)})`).join("")})
 (allow file-read-data ${readable})
 (deny network-outbound (remote unix-socket))
@@ -50,6 +126,7 @@ export function seatbeltProfile(c: Confinement): string {
 (deny appleevent-send)
 (deny process-exec* (subpath ${quoted(c.sandbox)}) (literal "/usr/bin/open") (literal "/usr/bin/osascript") (literal "/bin/launchctl"))
 (deny mach-lookup (global-name "com.apple.cfprefsd.agent") (global-name "com.apple.SecurityServer") (global-name "com.apple.pasteboard.1"))
+(deny ${TERMINAL_OPS} (regex #"^/dev/cu\\.") (regex #"^/dev/pty") ${terminals})
 `
 }
 
diff --git a/packages/runtime/src/electron.ts b/packages/runtime/src/electron.ts
index c2d85c2..ab16449 100644
--- a/packages/runtime/src/electron.ts
+++ b/packages/runtime/src/electron.ts
@@ -1,6 +1,14 @@
 import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process"
 import { posix } from "node:path"
-import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs"
+import {
+  accessSync,
+  constants,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs"
 import { rm } from "node:fs/promises"
 import { userInfo } from "node:os"
 import { join, sep } from "node:path"
@@ -10,8 +18,11 @@ import {
   CONFINED_SWITCHES,
   argumentIn,
   checkConfinement,
+  checkProfile,
+  type Confinement,
   copyFiles,
   FilesError,
+  openTerminals,
   SANDBOX_EXEC,
   seatbeltProfile,
 } from "./electron-confine.ts"
@@ -176,6 +187,11 @@ export interface ElectronLaunch {
   viewport: Pick<Viewport, "width" | "height" | "deviceScaleFactor">
   /** The https sites a wrapper app shows as its own (the project's `origins`). */
   origins?: readonly string[]
+  /**
+   * It opens terminals of its own (the project's, approved): new ptys allowed, the user's open at
+   * launch never reached. Off: no terminal at all.
+   */
+  terminals?: boolean
   signal?: AbortSignal
   /**
    * How long its windows must stay as they are before its main window is chosen (default 1.5 s: a
@@ -351,6 +367,24 @@ async function makeSandbox(work: string): Promise<{
   }
 }
 
+/**
+ * Its shells' setup (user decision 2026-10-11): a prompt with no login or machine name (a demo
+ * shows it), the folder only. Its home is fresh at each launch: these are all it holds.
+ */
+function neutralShell(home: string, env: NodeJS.ProcessEnv): void {
+  writeFileSync(join(home, ".zshrc"), "PROMPT='%1~ %# '\n")
+  for (const file of [".bashrc", ".bash_profile"]) {
+    writeFileSync(join(home, file), "PS1='\\W \\$ '\n")
+  }
+  mkdirSync(join(home, ".config", "fish"), { recursive: true })
+  writeFileSync(
+    join(home, ".config", "fish", "config.fish"),
+    "function fish_prompt; echo -n (prompt_pwd)' > '; end\n",
+  )
+  // macOS's bash says zsh is the default at every start: never on camera.
+  env.BASH_SILENCE_DEPRECATION_WARNING = "1"
+}
+
 /** How long the app's windows must stay as they are before its main window is chosen. */
 const SETTLE_MS = 1500
 
@@ -390,10 +424,11 @@ export async function launchElectronWith(
   // Its files and its confinement ready before it starts (said, its sandbox removed, if not).
   let args: string[]
   let profile: string | undefined
+  let confinement: Confinement | undefined
   try {
     // The confinement first (cheap): a broken one never costs the files' copy.
     if (confined) {
-      const confinement = {
+      confinement = {
         sandbox: sandbox.root,
         readable: [...bundles.map(realpathOr), ...(hooks.readable ?? []).map(realpathOr)],
         // The home and the work area wherever they are, and the one temp folder left (/var/tmp).
@@ -402,7 +437,6 @@ export async function launchElectronWith(
       // Its own canary, beside its sandbox (never inside: that's readable) and named after it:
       // launches at once never touch each other's, and a crash's is swept with its sandbox.
       await checkConfinement(confinement, `${sandbox.root}.canary`, opts.signal)
-      profile = seatbeltProfile(confinement)
     }
     if (opts.files !== undefined) await copyFiles(opts.files, sandbox.files, opts.signal)
     args = (opts.args ?? []).map((a) => argumentIn(a, sandbox.files))
@@ -411,6 +445,24 @@ export async function launchElectronWith(
         throw new ElectronLaunchError(`${arg.slice(sandbox.files.length + 1)} isn't in files/`)
       }
     }
+    if (opts.terminals === true) {
+      // Its profile's shape loads (checked first: the listing below stays the last step).
+      if (confinement !== undefined) {
+        await checkProfile(
+          seatbeltProfile({ ...confinement, terminals: { existing: [] } }),
+          opts.signal,
+        )
+      }
+      neutralShell(sandbox.home, sandbox.env)
+    }
+    // Last before it starts: the user's terminals listed as late as they can be.
+    if (confinement !== undefined) {
+      const existing = opts.terminals === true ? await openTerminals() : undefined
+      profile = seatbeltProfile({
+        ...confinement,
+        ...(existing !== undefined && { terminals: { existing } }),
+      })
+    }
     // Stopped meanwhile: never started.
     opts.signal?.throwIfAborted()
   } catch (error) {
diff --git a/packages/runtime/test/electron.test.ts b/packages/runtime/test/electron.test.ts
index fba3ffe..1af4a98 100644
--- a/packages/runtime/test/electron.test.ts
+++ b/packages/runtime/test/electron.test.ts
@@ -14,7 +14,7 @@ import {
   writeFileSync,
 } from "node:fs"
 import { createRequire } from "node:module"
-import { tmpdir, userInfo } from "node:os"
+import { hostname, tmpdir, userInfo } from "node:os"
 import { dirname, join } from "node:path"
 import { parseProjectYaml, parseScenarioYaml } from "@kiframe/schema"
 import { errors } from "playwright"
@@ -36,7 +36,13 @@ import {
   seatbeltProfile,
   sweepWorkArea,
 } from "../src/index.ts"
-import { checkConfinement, copyFiles } from "../src/electron-confine.ts"
+import {
+  checkConfinement,
+  checkProfile,
+  ConfinementError,
+  copyFiles,
+  openTerminals,
+} from "../src/electron-confine.ts"
 import {
   attach,
   type ElectronLaunch,
@@ -174,6 +180,7 @@ const launch = async (
     timeoutMs?: number
     signal?: AbortSignal
     origins?: string[]
+    terminals?: boolean
   } = {},
 ) => {
   const target = await launchElectron({
@@ -1241,6 +1248,167 @@ steps:
       }
     })
 
+    /** A terminal of the user's (a pty the test opens, a shell in it): what's printed into it, seen. */
+    const userTerminal = async () => {
+      const shell = spawn(
+        "/usr/bin/script",
+        ["-q", "/dev/null", "/bin/sh", "-c", "tty; exec sleep 120"],
+        {
+          stdio: ["ignore", "pipe", "ignore"],
+        },
+      )
+      let seen = ""
+      shell.stdout.on("data", (d: Buffer) => (seen += d.toString()))
+      expect(await waitFor(() => /\/dev\/ttys[0-9]+/.test(seen), 10_000)).toBe(true)
+      const path = /\/dev\/ttys[0-9]+/.exec(seen)![0]
+      return { path, seen: () => seen, mode: () => statSync(path).mode, close: () => shell.kill() }
+    }
+    const terminalsSeen = async (target: ElectronTarget, name = "terminals.json") => {
+      const file = join(target.sandbox, "profile", name)
+      expect(await waitFor(() => existsSync(file), 15_000)).toBe(true)
+      return JSON.parse(readFileSync(file, "utf8")) as Record<string, string>
+    }
+
+    it("never reaches the user's terminals; opens its own only when its project allows it", async () => {
+      const user = await userTerminal()
+      const mode = user.mode()
+      try {
+        for (const terminals of [false, true]) {
+          const target = await launch(["terminals", `tty=${user.path}`], { terminals })
+          const seen = await terminalsSeen(target)
+          // Never the user's: not printed into, not read (keystrokes), its mode kept.
+          for (const escape of [
+            "tty-write-outside",
+            "tty-read-outside",
+            "tty-chmod-outside",
+            "tty-stat-outside",
+          ]) {
+            expect(seen[escape], `${escape} (terminals: ${terminals})`).toBe("DENIED EPERM")
+          }
+          // Its own pty (a terminal app's shell): only when allowed.
+          expect(seen["pty-shell"], `terminals: ${terminals}`).toMatch(
+            terminals ? /^OK true/ : /^DENIED/,
+          )
+          // Its shells' prompts: the folder only, never the user's login or Mac's name.
+          if (terminals) {
+            expect(seen["zsh-prompt"]).toMatch(/^OK \S+ %$/)
+            expect(seen["bash-prompt"]).toBe("OK \\W \\$")
+            for (const prompt of [seen["zsh-prompt"], seen["bash-prompt"]]) {
+              expect(prompt).not.toContain(userInfo().username)
+              expect(prompt).not.toContain(hostname().split(".")[0])
+            }
+          }
+          await target.close()
+        }
+        expect(user.seen()).not.toContain("INJECTED")
+        expect(user.mode()).toBe(mode)
+      } finally {
+        user.close()
+      }
+    })
+
+    it("can read a terminal opened while it runs, when allowed its own (the stated gap)", async () => {
+      // Seatbelt can't tell a pty the app opens from one the user opens after the launch: pinned
+      // here, so a fix (a pty broker) flips it knowingly. Without terminals: never.
+      for (const terminals of [true, false]) {
+        const target = await launch(["terminals"], { terminals })
+        await terminalsSeen(target)
+        const user = await userTerminal()
+        try {
+          writeFileSync(join(target.sandbox, "profile", "later.txt"), user.path)
+          const later = await terminalsSeen(target, "later.json")
+          expect(later["tty-read-later"], `terminals: ${terminals}`).toBe(
+            terminals ? "OK" : "DENIED EPERM",
+          )
+        } finally {
+          user.close()
+          await target.close()
+        }
+      }
+    })
+
+    it("lists the user's terminals last, every way to reach one denied; none for an app without", () => {
+      const base = { sandbox: "/s", readable: [], private: [] }
+      const without = seatbeltProfile(base)
+      const last = (p: string) => p.trim().split("\n").at(-1)!
+      expect(last(without)).toMatch(
+        /^\(deny file-read-data file-read-metadata file-write\* file-ioctl file-revoke /,
+      )
+      expect(last(without)).toContain('(regex #"^/dev/tty.") (literal "/dev/ptmx")')
+      expect(without).not.toContain('(regex #"^/dev/ttys[0-9]+$")')
+      const withOwn = seatbeltProfile({
+        ...base,
+        terminals: { existing: ["/dev/ttys001", "/dev/ttys004"] },
+      })
+      expect(withOwn).toContain('(literal "/dev/ptmx") (regex #"^/dev/ttys[0-9]+$")')
+      expect(last(withOwn)).toMatch(
+        /^\(deny file-read-data file-read-metadata file-write\* file-ioctl file-revoke /,
+      )
+      // Every other tty (serial lines, old BSD ptys), then the user's ptys, each.
+      expect(last(withOwn)).toContain(
+        '(regex #"^/dev/tty[^s]") (literal "/dev/ttys001") (literal "/dev/ttys004")',
+      )
+      // Never every terminal writable (the rule that let an app print into the user's).
+      for (const p of [without, withOwn]) expect(p).not.toContain('(regex #"^/dev/tty")')
+    })
+
+    it("lists the user's ptys only: a free one's node (root's) is the app's to take", async () => {
+      const nodes: Record<string, number | undefined> = {
+        "/dev/ttys001": 501,
+        // Free (closed since boot): its node stays, root's; the app's next pty may take it.
+        "/dev/ttys003": 0,
+        // Closed while listed.
+        "/dev/ttys005": undefined,
+        "/dev/tty.usb": 501,
+        "/dev/cu.serial": 0,
+      }
+      const view = {
+        list: () => Promise.resolve([...Object.keys(nodes), "tty", "null"].map((p) => p.slice(5))),
+        owner: (p: string) => Promise.resolve(nodes[p]),
+      }
+      expect(await openTerminals(view)).toEqual(["/dev/ttys001"])
+      // Unreadable: refused (never a launch with them unlisted).
+      const eacces = () => Promise.reject(Object.assign(new Error("EACCES"), { code: "EACCES" }))
+      for (const broken of [
+        { ...view, list: eacces },
+        { ...view, owner: eacces },
+      ]) {
+        await expect(openTerminals(broken)).rejects.toThrow(ConfinementError)
+      }
+      // On this Mac: the test's own terminal is listed (its user's), a root-owned node never (one
+      // closed since: gone, nothing to say of it).
+      const user = await userTerminal()
+      try {
+        const listed = await openTerminals()
+        expect(listed).toContain(user.path)
+        for (const path of listed) {
+          const owner = (() => {
+            try {
+              return statSync(path).uid
+            } catch {
+              return undefined
+            }
+          })()
+          if (owner !== undefined) expect(owner).not.toBe(0)
+        }
+      } finally {
+        user.close()
+      }
+    })
+
+    it("refuses a terminals profile macOS won't load (never read as an app that quit)", async () => {
+      const profile = seatbeltProfile({
+        sandbox: realpathSync(tmpdir()),
+        readable: [],
+        private: [],
+        terminals: { existing: [] },
+      })
+      await expect(checkProfile(profile)).resolves.toBeUndefined()
+      await expect(checkProfile(profile + "(deny no-such-operation)\n")).rejects.toThrow(
+        /the confinement for its terminals didn't load/,
+      )
+    })
+
     it("never launches when the confinement doesn't hold (a canary is read)", async () => {
       // A profile that lets the canary be read (its folder readable): refused, no app started.
       const own = mkdtempSync(join(tmpdir(), "kiframe-el-work-"))
diff --git a/packages/runtime/test/fixtures/electron-app/main.cjs b/packages/runtime/test/fixtures/electron-app/main.cjs
index a663db1..d4c15bd 100644
--- a/packages/runtime/test/fixtures/electron-app/main.cjs
+++ b/packages/runtime/test/fixtures/electron-app/main.cjs
@@ -114,6 +114,65 @@ if (process.argv.includes("touch-arg") && opened !== undefined) {
   app.whenReady().then(() => writeFileSync(join(opened, "note.md"), "edited by the app"))
 }
 
+// "terminals": the user's terminal (`tty=`, opened before the launch: never reached) and a pty of
+// its own (a shell run through /usr/bin/script: what a terminal app does), tried and written down.
+// Then the terminal the test opens after the launch (`later.txt` in its data folder), if given.
+if (process.argv.includes("terminals")) {
+  app.whenReady().then(async () => {
+    const fs = require("node:fs")
+    const { execFileSync } = require("node:child_process")
+    const tty = process.argv.find((a) => a.startsWith("tty="))?.slice(4) ?? "/nonexistent"
+    const out = {}
+    const tryIt = (name, fn) => {
+      try {
+        out[name] = "OK " + String(fn()).slice(0, 40)
+      } catch (e) {
+        out[name] = "DENIED " + (e.code ?? String(e).slice(0, 40))
+      }
+    }
+    const openRead = (path) =>
+      fs.closeSync(fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK))
+    tryIt("tty-write-outside", () => fs.writeFileSync(tty, "INJECTED"))
+    tryIt("tty-read-outside", () => openRead(tty))
+    tryIt("tty-chmod-outside", () => fs.chmodSync(tty, 0o666))
+    // Its times (they change as the user types): never watched.
+    tryIt("tty-stat-outside", () => fs.statSync(tty).mtimeMs)
+    tryIt("pty-shell", () =>
+      execFileSync("/usr/bin/script", ["-q", "/dev/null", "/bin/echo", "pty-ok"], {
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 5000,
+      })
+        .toString()
+        .includes("pty-ok"),
+    )
+    // What its shells' prompts show (a demo films them).
+    const shell = (program, script) =>
+      execFileSync(program, ["-i", "-c", script], {
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5000,
+      })
+        .toString()
+        .trim()
+    tryIt("zsh-prompt", () => shell("/bin/zsh", 'print -rP -- "$PS1"'))
+    tryIt("bash-prompt", () => shell("/bin/bash", 'echo "$PS1"'))
+    const data = app.getPath("userData")
+    fs.writeFileSync(join(data, "terminals.json"), JSON.stringify(out))
+    const asked = join(data, "later.txt")
+    for (let i = 0; i < 200 && !fs.existsSync(asked); i++)
+      await new Promise((r) => setTimeout(r, 50))
+    if (!fs.existsSync(asked)) return
+    const later = {}
+    const path = fs.readFileSync(asked, "utf8")
+    try {
+      openRead(path)
+      later["tty-read-later"] = "OK"
+    } catch (e) {
+      later["tty-read-later"] = "DENIED " + e.code
+    }
+    fs.writeFileSync(join(data, "later.json"), JSON.stringify(later))
+  })
+}
+
 // "probes": each escape the confinement must refuse, tried and written down (never the user's
 // data: a write would only create a probe file the test removes; reads only list folders).
 if (process.argv.includes("probes")) {
diff --git a/packages/schema/src/project.ts b/packages/schema/src/project.ts
index ca4c997..f39ae0b 100644
--- a/packages/schema/src/project.ts
+++ b/packages/schema/src/project.ts
@@ -92,6 +92,12 @@ export const ElectronApp = z.strictObject({
     .optional(),
   /** The sites a wrapper app shows as its own (Slack's app.slack.com): its pages, never another's. */
   origins: z.array(HttpsOrigin).max(10).optional(),
+  /**
+   * It opens terminals of its own (a terminal app, an editor's terminal; decided 2026-10-11): its
+   * new ptys allowed, the user's open at launch never reached; a terminal the user opens while it
+   * runs is exposed to it (Seatbelt can't tell them apart). Approved on each Mac with the app.
+   */
+  terminals: z.boolean().optional(),
   /** The size its takes are recorded at (emulated: the window itself is never moved). */
   viewport: Viewport.prefault({ width: 1440, height: 900 }),
 })
diff --git a/scripts/real-apps/drive.ts b/scripts/real-apps/drive.ts
index c5b3af7..a489b51 100644
--- a/scripts/real-apps/drive.ts
+++ b/scripts/real-apps/drive.ts
@@ -10,7 +10,9 @@
 // Build the app first (pnpm --filter @kiframe/desktop build). Keys and secrets come from the root
 // `.env` (never printed). Risky steps are approved: throwaway accounts only.
 import {
+  appendFileSync,
   copyFileSync,
+  cpSync,
   existsSync,
   mkdirSync,
   mkdtempSync,
@@ -92,6 +94,15 @@ const { values } = parseArgs({
     input: { type: "string", multiple: true },
     // A file attached to the brief in the composer (its picker, as the user would).
     attach: { type: "string", multiple: true },
+    // A desktop app of the project, `name=/Applications/App.app`: written to project.json (with
+    // --desktop-arg), then added through the Apps panel (picked, checked confined, approved).
+    desktop: { type: "string" },
+    // What the desktop app opens: a path in the project's files/ (`files/demo`).
+    "desktop-arg": { type: "string", multiple: true },
+    // A folder copied into the project's files/ (what a desktop app opens).
+    files: { type: "string" },
+    // The desktop app opens terminals of its own (its card's warning shown before it's allowed).
+    "desktop-terminals": { type: "boolean" },
   },
 })
 function usage(why: string): never {
@@ -100,6 +111,13 @@ function usage(why: string): never {
   )
   process.exit(2)
 }
+// The desktop app's options only with it (never silently ignored).
+if (
+  values.desktop === undefined &&
+  (values["desktop-arg"] !== undefined || values["desktop-terminals"] === true)
+) {
+  usage("--desktop-arg and --desktop-terminals need --desktop")
+}
 // Any other app: its address and the request to send, both; never with --app (which one would run).
 let custom: AppRun | undefined
 if (values.url !== undefined) {
@@ -213,6 +231,78 @@ async function exportVideo(status: unknown, file: string): Promise<void> {
   log(done.status === 0 ? `exported: ${resolve(file)}` : `export failed (${done.status ?? "?"})`)
 }
 
+/**
+ * A desktop app added as the user would: its entry (what it opens) in the project's file, the
+ * project opened again, then the Apps panel: picked (main's dialog answered with the bundle),
+ * checked confined, approved. Each stage logged, its time too.
+ */
+async function addDesktop(spec: string, dir: string): Promise<void> {
+  const [name, bundle] = spec.split(/=(.*)/s)
+  if (name === undefined || bundle === undefined) throw new Error("--desktop name=/path/App.app")
+  // As the add card reads it (its name, its bundle id): what the panel shows.
+  const { inspectDesktopApp } = await import("@kiframe/runtime")
+  const { bundleId, name: shown } = await inspectDesktopApp(bundle)
+  const literal = shown.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  // Closed from the project's menu, as the user would.
+  await page.getByRole("button", { name: run.name }).first().click()
+  await page.getByRole("menuitem", { name: "Close project" }).click()
+  await page.getByRole("button", { name: "Open a project…" }).waitFor({ timeout: 30_000 })
+  const file = join(dir, "project.json")
+  const project = JSON.parse(readFileSync(file, "utf8")) as { apps: Record<string, unknown> }
+  if (name in project.apps)
+    throw new Error(`--desktop ${name}: the project names an app ${name} already`)
+  project.apps[name] = {
+    kind: "electron",
+    bundleId,
+    ...(values["desktop-arg"] !== undefined && { args: values["desktop-arg"] }),
+    ...(values["desktop-terminals"] === true && { terminals: true }),
+  }
+  writeFileSync(file, JSON.stringify(project, null, 2) + "\n")
+  await app.evaluate(({ dialog }, picked) => {
+    dialog.showOpenDialog = () => Promise.resolve({ canceled: false, filePaths: [picked] })
+  }, dir)
+  // Opened again from the menu, as the user would (the window's view of it made fresh).
+  await page.getByRole("button", { name: "Open a project…" }).click()
+  await page.getByRole("region", { name: "Scenes" }).waitFor({ timeout: 30_000 })
+  // The title bar's chip: the first app's host (the Apps panel).
+  await page.locator("header button.chip-button").click()
+  const panel = page.getByRole("dialog", { name: "Apps" })
+  await app.evaluate(({ dialog }, picked) => {
+    dialog.showOpenDialog = () => Promise.resolve({ canceled: false, filePaths: [picked] })
+  }, bundle)
+  await panel.getByRole("button", { name: "Add desktop app…" }).click()
+  const adding = panel.getByRole("region", { name: `Adding ${shown}` })
+  await adding.waitFor({ timeout: 30_000 })
+  log(`adding ${shown}: ${(await adding.textContent()) ?? ""}`)
+  if (values["desktop-terminals"] === true) {
+    const note = adding.getByRole("note")
+    log(`terminals warning: ${(await note.count()) > 0 ? await note.textContent() : "(none!)"}`)
+  }
+  const t0 = Date.now()
+  await adding.getByRole("button", { name: "Check" }).click()
+  const status = adding.getByRole("status")
+  await page.waitForFunction(
+    (el) => /runs confined|couldn|can't|isn't|refused|failed/i.test(el?.textContent ?? ""),
+    await status.elementHandle(),
+    { timeout: 120_000 },
+  )
+  const took = Math.round((Date.now() - t0) / 100) / 10
+  log(`checked in ${took} s: ${(await status.textContent()) ?? ""}`)
+  await shot("desktop-checked")
+  // Added, or allowed here when the project names it already (as here).
+  await adding
+    .getByRole("button", { name: new RegExp(`^(Add ${literal}|Allow ${literal} here)$`) })
+    .click()
+  const list = panel.getByRole("list", { name: "The project's apps" })
+  await page.waitForFunction(
+    (el) => /Ready on this Mac/.test(el?.textContent ?? ""),
+    await list.elementHandle(),
+    { timeout: 30_000 },
+  )
+  log(`app ${name} added: ${(await list.textContent()) ?? ""}`)
+  await page.keyboard.press("Escape")
+}
+
 /** The complete takes the app's take store holds (its own reading: leftovers and bad ones skipped). */
 function completeTakes(data: string): number {
   const store = new TakeStore(data)
@@ -251,6 +341,11 @@ const env = Object.fromEntries(
 env.KIFRAME_TEST_KEYCHAIN = "memory"
 // The agent's every event, timed, next to the report (what it called, with what, how long).
 env.KIFRAME_TRACE = join(out, "trace.jsonl")
+// A desktop app's sandboxes in the run's own work area (never the user's ~/.kiframe); its launch's
+// timings and failures' details on main's stderr, kept next to the report.
+env.KIFRAME_WORK_DIR = join(out, "work")
+env.KIFRAME_ELECTRON_TIMING = "1"
+env.KIFRAME_ELECTRON_DEBUG = "1"
 const profile = mkdtempSync(join(tmpdir(), "kiframe-real-"))
 const usageBefore = await credits()
 const started = Date.now()
@@ -259,6 +354,7 @@ const app = await electron.launch({
   cwd: join(root, "apps", "desktop"),
   env,
 })
+app.process().stderr?.on("data", (chunk: Buffer) => appendFileSync(join(out, "main.log"), chunk))
 const page = await app.firstWindow()
 await page.setViewportSize({ width: 1440, height: 900 }).catch(() => undefined)
 const shot = (name: string) =>
@@ -300,6 +396,14 @@ try {
     log(`app ${name} added`)
   }
 
+  // A desktop app: in the project's file first (what it opens), as a shared project has it; then
+  // added through the Apps panel as the user would (its picker answered with the bundle).
+  if (values.files !== undefined) {
+    cpSync(values.files, join(dir, "files", basename(values.files)), { recursive: true })
+    log(`files/${basename(values.files)} added`)
+  }
+  if (values.desktop !== undefined) await addDesktop(values.desktop, dir)
+
   for (const secret of run.secrets) {
     const value = process.env[secret.env]
     if (value === undefined || value === "") throw new Error(`${secret.env} isn't set (root .env)`)

From babbff7469c4a6d1d90d3f507abe2e6f32533096 Mon Sep 17 00:00:00 2001
From: Quang Lee <winlp4ever@gmail.com>
Date: Sun, 11 Oct 2026 23:15:09 +0200
Subject: [PATCH 10/10] fix(runtime): give a desktop app's shells a temp folder
 of their own (#64) (#65)

* fix(runtime): give a desktop app's shells a temp folder of their own

zsh writes here-docs under /tmp/zsh, which the confinement denies: VS Code's
shell (read at its start, and its terminal's integration) said "can't create
temp file" on camera. TMPPREFIX now points into the sandbox's temp for every
desktop app. With KIFRAME_ELECTRON_DEBUG, the app's own output and exit code
are written to Kiframe's stderr (how VS Code's silent quit was found).

* fix(scripts): give real-app runs a short work folder

An app's socket in its sandbox must fit macOS's 104 characters: VS Code quit
at once under the run's own output folder. Runs use /tmp/kf-*, removed at exit;
the Check outcomes "quit" and "the site" end the wait too.

* docs(backlog): record the VS Code pass and its open items

Socket path length (stated limit), shell temp files (fixed), grounding in an
editor, and two items left for a reviewed design: a desktop take refused when
the window is smaller than its viewport, and the guard's way back from a site.
---
 docs/BACKLOG.md                               |  3 +++
 docs/FAILURE-CATALOGUE.md                     |  4 ++++
 packages/runtime/src/electron.ts              | 21 +++++++++++++++----
 packages/runtime/test/electron.test.ts        |  2 ++
 .../test/fixtures/electron-app/main.cjs       |  2 ++
 scripts/real-apps/drive.ts                    | 14 +++++++++----
 6 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md
index c32f267..bbcc4fc 100644
--- a/docs/BACKLOG.md
+++ b/docs/BACKLOG.md
@@ -244,6 +244,9 @@ Non-severe review findings deferred on purpose (see the review-round rule: only
 ## Vault hardening (M1-7)
 - **Electron targets:** an app attached over CDP (F4) runs in its own persistent profile: no ephemeral context there. The app's own storage keeps whatever the scene typed; document it for Electron projects and prefer a throwaway app profile (`--user-data-dir` per run).
 - **Terminals in a desktop app's demo (decided 2026-10-11):** an app its project lets open terminals (`terminals: true`, chosen when it's added, warned, approved with it) gets new ptys; the user's terminals open at launch are never reached (read, written, chmod, revoked). Stated gaps: a terminal the user opens while a launch lives (any app's) can be read (keystrokes, passwords), written and revoked by it, since Seatbelt can't tell its ptys from the user's: a pty broker (Kiframe opens them, the app gets descriptors) would close it. Closing a terminal that was open at launch can make the app's next pty fail (its number is reused, still denied). Helpers some apps run through a pty without terminals (askpass, some language servers) fail. An app the project already names keeps its project's setting: remove and add it again to change it. Its checks (adding it, a quiet trial of an update) run without terminals: an app that quits without a pty at start can't be added yet.
+- **Socket paths in a desktop app's sandbox:** an app's socket in its data folder (VS Code's instance socket) must fit macOS's 104 characters; in `~/.kiframe` the path is 88 + the user's name long (VS Code 1.140). A long user name quits such an app at once ("quit at once": FAILURE-CATALOGUE #25). Shorter sandbox names (and the sweep reading both forms) would add room; a work area set by the user (KIFRAME_WORK_DIR) must stay short.
+- **A desktop window smaller than its viewport: its take refused (design first, PR 5 2026-10-11):** VS Code's window (1200×800) is smaller than its viewport (1440×900): some screencast frames are of the window as it is (2700×1800), the take takes the first frame's size, TakeMeta refuses it ("frameSize must equal viewport × deviceScaleFactor"); going full screen worked around it. A frame gate (keep only the viewport at the scale asked) went through a redesign and six review rounds without settling: a larger window of the same shape is scaled into the asked size and passes; a take's size vs its first window; a popup's unread size; a display change mid-take. Next: a reviewed design, maybe at the root (the window sized to the viewport, which moves the user's window: decided against 2026-10-08, to weigh again). Its work: scratchpad patch `vscode-fixes-full.patch` (not in the repo).
+- **The guard's way back from a site (design first, PR 5 2026-10-11):** a main window that went to a site goes back once; on CI the back failed ("Page.getNavigationHistory: Not attached to an active page", the page moving process) and the window was blanked (the embed test's flake). A retry loop driven by the window's address went through the same review rounds without settling: it stops on Chromium's error page or an about:blank entry (both "allowed"), a same-URL pushState reads as no history, a cut-off back may land late. Next: a reviewed design with the app's own check (`allows`) as its goal, never `frameAllowed`.
 - **Copy and paste in a desktop app's demo:** the confinement denies the pasteboard (the user's clipboard may hold a password), so an app's own copy and paste does nothing in a run. A demo that needs it: a run-only pasteboard (a private named pasteboard can't be forced on an app) or typing the pasted text.
 - **What a confined app opens through LaunchServices:** an app can't start without `launchservicesd`, and through it it can open a file or a URL that then runs unconfined (a script it wrote, the user's browser). Stated in §0.9 (accident, not a hostile app); an Endpoint Security watcher or a per-run user account would close it.
 - **Desktop-app sweeps read processes more than once:** the startup sweep runs one `ps` per leftover sandbox (one `ps -axo pid=,lstart=` table would answer every owner), and a run's close reads the process table twice (`orphanedGroup` and `sweepProcesses`). Startup and close time only (#58 review).
diff --git a/docs/FAILURE-CATALOGUE.md b/docs/FAILURE-CATALOGUE.md
index b3b69e4..8e31090 100644
--- a/docs/FAILURE-CATALOGUE.md
+++ b/docs/FAILURE-CATALOGUE.md
@@ -30,3 +30,7 @@
 | 22 | Content past the snapshot's cut | Wikipedia (desktop app, 2026-10-05) | "Search Messi, then go to his WC26 campaign": the article's snapshot is 1.14 M characters, the agent reads the first 20 k. It never saw the 2026 part: ~35 snapshots (25 failed `within` guesses: Wikipedia's sections have no names), the search page, the API, the printable page, until the 12 min ran out ($0.11). The user saw it as "scroll not working". With `find` (rerun, traced) it scrolled to the 2026 part in 3 min, then took a snapshot "to check where the page is now": a snapshot starts at the page's top whatever the scroll, and it thought 283 s about why nothing moved. Model time 704 s of 730 (tools 26 s) | — | Done: `snapshot` takes `find` (the elements that mention a text, with their ancestors and refs, searched in the scrubbed snapshot); the cut says to use it; every snapshot says where the view is (how far down, the section) and that it covers the whole page. The thinking itself: capped next (its own PR) |
 | 23 | The recording fails where the replay passed | Wikipedia (desktop app, 2026-10-05/06) | "Search Messi": `save_scene`'s replay passed, `record_scene` failed with "locator.press: Timeout 15000ms exceeded" on the search step, every run (the agent worked around it, minutes each time). Typed at a person's pace, Wikipedia swaps its search box for a combobox mid-typing: the text still goes to the focused new field, but `submit` pressed Enter on the target's locator (a "Search Wikipedia" searchbox, gone). The replay typed at once, before the swap | — | Done: when the focused text field holds the typed text and the target is gone (or doesn't hold it: a modal took the keys), Enter goes where the text is; otherwise the target, as before. `save_scene` replays with the recording's typing and settling (pointer at once) and pixel ratio, so what a person's typing changes fails before the recording |
 | 24 | A terminal app's shell refused by the confinement | minmux (desktop app, confined, 2026-10-11) | Every terminal pane said "posix_spawnp failed": Seatbelt denied /dev/ptmx, so no pty could be made; Kif spent the run on diagnostics. Measuring it found the old rule let any confined app print into every terminal the user had open (input injection refused by macOS) | Per app, opt-in (user decision): `terminals: true` allows new ptys and denies the user's terminals open at launch (every way: read, write, chmod, ioctl, revoke); every other app gets no terminal at all | Done (stated gap: terminals opened while it runs, BACKLOG) |
+| 25 | An app quits at once, silently, confined | VS Code (desktop app, confined, 2026-10-11) | "Code quit at once": exit 1, nothing said (its `--verbose`: `Lifecycle#kill()` right after start). Its instance socket lives in its data folder, inside the sandbox; under the driver's work folder that path was ~170 characters, past macOS's 104 for a socket. Found with the launcher's debug output (KIFRAME_ELECTRON_DEBUG: the app's own output and exit code) and VS Code's `--verbose` | The driver uses a short work folder (`/tmp/kf-…`); in `~/.kiframe` the path is 88 + the user's name long (95 here) | Stated limit (BACKLOG): a user name over ~16 characters, or an app with a longer socket name, quits the same way |
+| 26 | A desktop app's take refused: its frames of two shapes | VS Code (desktop app, confined, 2026-10-11) | Every `record_scene`: "frameSize must equal viewport × deviceScaleFactor". Its window (1200×800) is smaller than the viewport it's shown at (1440×900): some screencast frames are of the window as it is (2700×1800), and the take took the first one's size. Kif got a take only by going full screen (frames still changed mid-take) | Going full screen (Kif found it) | Open: design first (BACKLOG) |
+| 27 | A shell's temp files refused | VS Code's terminal (confined, 2026-10-11) | Its zsh integration said `.zshrc:158: can't create temp file` on camera (zsh writes here-docs under /tmp/zsh: denied), in a path naming the user's login | Every desktop app's `TMPPREFIX` in its sandbox temp (VS Code reads its shell at start, terminals or not) | Done |
+| 28 | Grounding slow in an editor | VS Code (desktop app, 2026-10-11) | 15.5 min and $0.18 for one scene: Ctrl+` didn't open the terminal, the command palette's input timed out on focus (in the replay too), a first-run dialog and the folder's trust dialog each took steps; the scene opens the terminal from the panel toggle | — | Open: prompt hints for editors (dismiss first-run dialogs in setup; prefer visible toggles to shortcuts) |
diff --git a/packages/runtime/src/electron.ts b/packages/runtime/src/electron.ts
index ab16449..453cd2b 100644
--- a/packages/runtime/src/electron.ts
+++ b/packages/runtime/src/electron.ts
@@ -295,7 +295,8 @@ function spawnOptions(sandbox: { root: string; env: NodeJS.ProcessEnv }): SpawnO
   return {
     detached: true,
     env: sandbox.env,
-    stdio: ["ignore", "ignore", "pipe"],
+    // Its standard output read only for Kiframe's own debugging.
+    stdio: ["ignore", process.env.KIFRAME_ELECTRON_DEBUG === undefined ? "ignore" : "pipe", "pipe"],
     cwd: sandbox.root,
   }
 }
@@ -356,6 +357,9 @@ async function makeSandbox(work: string): Promise<{
     // Chromium on macOS: its temp folder (the single-instance lock's socket) in the sandbox too,
     // never the user's /var/folders (denied by the confinement: such an app would quit).
     MAC_CHROMIUM_TMPDIR: dirs.tmp,
+    // zsh's temp files (here-docs: VS Code's shell, its environment read at start) in its own
+    // temp, never /tmp (denied).
+    TMPPREFIX: join(dirs.tmp, "zsh"),
   })
   return {
     root,
@@ -495,6 +499,14 @@ export async function launchElectronWith(
   // Its spawn failing is said by the launch (never an unhandled 'error' event).
   let spawnError: Error | undefined
   child.on("error", (error) => (spawnError = error))
+  // What it says and how it ends: Kiframe's own debugging only (its output may name paths).
+  if (process.env.KIFRAME_ELECTRON_DEBUG !== undefined) {
+    child.stderr?.on("data", (chunk: Buffer) => process.stderr.write(`[app] ${chunk.toString()}`))
+    child.stdout?.on("data", (chunk: Buffer) =>
+      process.stderr.write(`[app out] ${chunk.toString()}`),
+    )
+    child.on("exit", (code, signalName) => debug("exit", `${code ?? signalName}`))
+  }
   let browser: Browser | undefined
   let ended: Promise<{ unread: boolean }> | undefined
   // Once: the app's group is signalled only while it's known alive (its leader running, or its
@@ -720,13 +732,13 @@ function debuggingEndpoint(
     const finish = (error?: Error, endpoint?: string) => {
       clearTimeout(timer)
       clearInterval(poll)
-      child.stderr?.removeAllListeners("data")
+      child.stderr?.removeListener("data", onData)
       child.removeListener("exit", exited)
       signal?.removeEventListener("abort", aborted)
       if (error !== undefined) reject(error)
       else resolve(endpoint as string)
     }
-    child.stderr?.on("data", (chunk: Buffer) => {
+    const onData = (chunk: Buffer) => {
       output = (output + chunk.toString("utf8")).slice(-8192)
       // A whole line only (a chunk may end mid-address), on this machine only.
       const found =
@@ -734,7 +746,8 @@ function debuggingEndpoint(
           output,
         )?.[1]
       if (found !== undefined) finish(undefined, found)
-    })
+    }
+    child.stderr?.on("data", onData)
     // The profile's own file, inside the sandbox (never one elsewhere: an app that ignores
     // --user-data-dir would write it where Kiframe never reads), read whole.
     const poll = setInterval(() => {
diff --git a/packages/runtime/test/electron.test.ts b/packages/runtime/test/electron.test.ts
index 1af4a98..e1b6ad6 100644
--- a/packages/runtime/test/electron.test.ts
+++ b/packages/runtime/test/electron.test.ts
@@ -1289,6 +1289,8 @@ steps:
           expect(seen["pty-shell"], `terminals: ${terminals}`).toMatch(
             terminals ? /^OK true/ : /^DENIED/,
           )
+          // A shell's temp files in its own temp (every app's: VS Code reads its shell at start).
+          expect(seen["zsh-temp"], `terminals: ${terminals}`).toBe("OK here-ok")
           // Its shells' prompts: the folder only, never the user's login or Mac's name.
           if (terminals) {
             expect(seen["zsh-prompt"]).toMatch(/^OK \S+ %$/)
diff --git a/packages/runtime/test/fixtures/electron-app/main.cjs b/packages/runtime/test/fixtures/electron-app/main.cjs
index d4c15bd..325da17 100644
--- a/packages/runtime/test/fixtures/electron-app/main.cjs
+++ b/packages/runtime/test/fixtures/electron-app/main.cjs
@@ -155,6 +155,8 @@ if (process.argv.includes("terminals")) {
         .trim()
     tryIt("zsh-prompt", () => shell("/bin/zsh", 'print -rP -- "$PS1"'))
     tryIt("bash-prompt", () => shell("/bin/bash", 'echo "$PS1"'))
+    // A here-string (a temp file of zsh's: what VS Code's shell integration writes).
+    tryIt("zsh-temp", () => shell("/bin/zsh", "cat <<< here-ok"))
     const data = app.getPath("userData")
     fs.writeFileSync(join(data, "terminals.json"), JSON.stringify(out))
     const asked = join(data, "later.txt")
diff --git a/scripts/real-apps/drive.ts b/scripts/real-apps/drive.ts
index a489b51..51a34b3 100644
--- a/scripts/real-apps/drive.ts
+++ b/scripts/real-apps/drive.ts
@@ -18,6 +18,7 @@ import {
   mkdtempSync,
   readdirSync,
   readFileSync,
+  rmSync,
   writeFileSync,
 } from "node:fs"
 import { tmpdir } from "node:os"
@@ -282,7 +283,8 @@ async function addDesktop(spec: string, dir: string): Promise<void> {
   await adding.getByRole("button", { name: "Check" }).click()
   const status = adding.getByRole("status")
   await page.waitForFunction(
-    (el) => /runs confined|couldn|can't|isn't|refused|failed/i.test(el?.textContent ?? ""),
+    (el) =>
+      /runs confined|couldn|can.t|isn.t|refused|failed|quit|the site/i.test(el?.textContent ?? ""),
     await status.elementHandle(),
     { timeout: 120_000 },
   )
@@ -341,9 +343,13 @@ const env = Object.fromEntries(
 env.KIFRAME_TEST_KEYCHAIN = "memory"
 // The agent's every event, timed, next to the report (what it called, with what, how long).
 env.KIFRAME_TRACE = join(out, "trace.jsonl")
-// A desktop app's sandboxes in the run's own work area (never the user's ~/.kiframe); its launch's
-// timings and failures' details on main's stderr, kept next to the report.
-env.KIFRAME_WORK_DIR = join(out, "work")
+// A short path (never the user's ~/.kiframe): an app's socket in its sandbox must fit macOS's 104
+// characters (VS Code's quit at once under the run's own folder).
+const work = mkdtempSync("/tmp/kf-")
+env.KIFRAME_WORK_DIR = work
+process.on("exit", () => rmSync(work, { recursive: true, force: true }))
+// A desktop app's launch timings and failures' details (its own output too) on main's stderr
+// (main.log, next to the report).
 env.KIFRAME_ELECTRON_TIMING = "1"
 env.KIFRAME_ELECTRON_DEBUG = "1"
 const profile = mkdtempSync(join(tmpdir(), "kiframe-real-"))