@notis_ai/cli 0.2.0-beta.114.1 → 0.2.0-beta.116.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notis_ai/cli",
-  "version": "0.2.0-beta.114.1",
+  "version": "0.2.0-beta.116.1",
   "description": "Agent-first Notis CLI for apps and generic tool execution",
   "type": "module",
   "bin": {

package/skills/notis-apps/SKILL.md

@@ -9,8 +9,6 @@ Use this skill when the user wants a packaged Notis app -- task manager, CRM, da
 
 Run the Notis CLI through NPX, for example `npx --package @notis_ai/cli@latest -- notis apps list`. Notis Desktop keeps the CLI auth profile current. This `notis-apps` skill is delivered through normal Notis skill sync for the signed-in user, alongside other curated skills.
 
-For the platform model, architecture, and local development workflow, read [docs/notis-apps-platform.md](../../../docs/notis-apps-platform.md) first. This skill is the execution guide for using that platform correctly.
-
 ## How Apps Are Built
 
 All Notis apps are built using the Notis CLI, either locally in a repo workspace or inside a Vercel Sandbox. The platform contract is the same in both cases:
@@ -94,7 +92,7 @@ App code never accesses the runtime directly -- it uses SDK hooks (`useTool`, `u
 15. **Local development first; deploy is user-gated** -- Iterate with `apps dev` and let the **user** test the app in the desktop **Local development** sidebar group. Do NOT run `apps create` or `apps deploy` on your own initiative, even after a clean build and verify. `deploy` installs the app onto the user's account and is a one-directional, outward-facing action — treat it like publishing: only run it when the user has tested the local build and **explicitly asks you to deploy**. Building a new app end-to-end without deploying is the expected, complete outcome. (See the **Local-development-first handoff** in the Workflow.)
 16. **Installed app links are explicit** -- A mounted dev session updates an installed workspace app only when the local checkout is linked by app id in `.notis/state.json` and the dev-session registry mirrors that id. Name or slug matches may be suggestions, never update targets. After first install, keep that link so Portal and CLI show/update the same app instead of creating duplicates.
 17. **Development identities stay separate** -- `.notis/state.json` uses `dev_app_id` for the hidden development-runtime row and `app_id` only for an accessible installed workspace app. The Electron registry mirrors the installed id as `targetAppId`. Never pass a runtime app whose manifest has `is_dev: true` to `notis apps link`; it is not an install/update target. Current CLIs reject that link and repair stale hidden, deleted, or inaccessible targets on the next `apps dev` without erasing valid state on transport or authentication failures.
-18. **Mounted means Portal-acknowledged** -- A running process, registry row, or HTTP 200 proves only that the app is serving. Before telling the user an app is mounted, require the current `apps dev` process to report `Mounted in Notis`. That status comes from an exact session/app/slug/nonce acknowledgment written by Electron only after the app enters the Portal's final **Local development** sidebar model. Do not require a manual Electron route/render check merely to prove the mount; route rendering is a separate behavior or visual verification task.
+18. **Mounted means Portal-acknowledged** -- A running process or HTTP 200 proves only that the app is serving. Before telling the user an app is mounted, require the current `apps dev` process to report `Mounted in <target desktop>`. The CLI selects the target from the active Notis profile: normal CLI runs target the signed-in Notis or Notis Beta desktop, while a CLI running inside an active Notis source workspace targets that workspace's matching desktop instance. The exact session/app/slug/nonce acknowledgment is accepted only from the visible target window after the app enters its final **Local development** sidebar model. Route rendering is a separate proof: when UI verification is required, also open the app and require `Rendered in <target desktop>`.
 19. **Store submission is user-gated** -- Run `apps publish --confirm-ready` only after the user explicitly confirms the current App Details page and Store listing are ready. Deploy the exact approved local state first. The command must reject missing confirmation, incomplete listing media, a local/deployed version mismatch, private visibility, or an existing pending review.
 20. **Bump `notisAppVersion` for every Store update** -- `package.json` must contain a semver `notisAppVersion`. For an existing Store app, increment it beyond the currently published registry version before deploy and submission; registry CI rejects equal or lower versions.
 21. **`CHANGELOG.md` owns release history** -- Keep the complete release history in one root `CHANGELOG.md`, newest entry first. Do not add new `versionNotes` values to `notis.config.ts`. Use `## [Release title] - YYYY-MM-DD`, or `{PR_MERGE_DATE}` for an unpublished entry. App Details reads **What’s New** and **Version History** from the deployed package manifest, while the Store reads them from the latest published snapshot; unpublished workspace edits must never change the Store page. The manifest also exposes `package.json` `notisAppVersion` as the package version shown in App Details.
@@ -126,13 +124,13 @@ These are the most common mistakes agents make. Each one wastes time and produce
 2. **Pull only installed apps.** If the user explicitly wants to fork an app they already installed, run `npx --package @notis_ai/cli@latest -- notis apps list`, then `npx --package @notis_ai/cli@latest -- notis apps pull <app-id> ./<dir>`. To fork a Store app that is not installed, tell the user to install it from `/store` first.
 3. **Edit the listing source.** Update `name` (slug), `title`, description, icon, accent, author, categories, tagline, databases, routes, and tools in `notis.config.ts`. Declare a database as a string for schema-only Store packaging; use `{ slug: 'templates', seedDocuments: true }` only when its rows are deliberate starter content for every installer. Keep the complete Store release history in the root `CHANGELOG.md`, newest entry first, using `## [Release title] - YYYY-MM-DD` (or `{PR_MERGE_DATE}` before publication). The first entry powers **What’s New** and the same file powers **Version History**. `icon` is a `phosphor:<name>` value or `metadata/icon.png`; when unset the app shows its **two-letter initials** everywhere (store, sidebar, app details). `accent` optionally pins the avatar color to one of `blue|violet|emerald|amber|rose|sky|fuchsia|teal` (default derived from the app id). Icon/accent flow through deploy onto the app row + listing and can also be set later via the `update_app` tool.
 4. **Build pages in `app/`.** Reuse scaffold code wherever it fits.
-5. **Iterate live.** Run `npx --package @notis_ai/cli@latest -- notis apps dev` so the desktop sidebar's Local development group discovers the app and the Electron Portal renders the local bundle. In the Notis monorepo's supervised `dev.sh` stack, keep app projects under `apps/<slug>/`; the root supervisor discovers that directory, owns the long-running process, and restarts it. A root-level app folder is not supervised and can disappear as soon as an agent-owned terminal exits.
+5. **Iterate live.** Run `npx --package @notis_ai/cli@latest -- notis apps dev` so the target desktop's **Local development** sidebar group discovers the app and renders the local bundle. Keep this command running for as long as the user is testing; stopping it removes the temporary Local development entry. Read the command's `Target desktop` line instead of guessing between Notis, Notis Beta, or a source-workspace desktop.
 6. **Capture listing screenshots.** Declare 3–6 screenshots in `notis.config.ts`, each with a stable `path`, descriptive `alt`, and optional `route`/`scenario`/`focus`/`theme`, then run `npx --package @notis_ai/cli@latest -- notis apps screenshot`. Use `focus` to frame a real app root without empty browser canvas; use `theme: 'light'` or `theme: 'dark'` to match both the Portal render and Store backdrop, and pair both modes when that best represents the app. It renders the configured states in a headless harness and writes exact 2000x1250 PNGs under `metadata/`, using the deterministic Store presentation by default (`--raw` is diagnostic only). Apps are icon-led like Raycast — the icon set in `notis.config.ts` represents the app, so there is no cover image, only these screenshots. Never hand-author the PNGs; regenerate them when routes or UI change.
 7. **Verify locally.** Run `npm install`, then `npx --package @notis_ai/cli@latest -- notis apps build` and `npx --package @notis_ai/cli@latest -- notis apps verify`. Surface the verify report and fix failures.
-8. **Local-development-first handoff — STOP HERE.** Keep `apps dev` running and hand off to the user: tell them the app is live in the desktop **Local development** sidebar group (green `DEV` badge) and ask them to test it there. Building a new app to this point, without deploying, is a **complete and expected** result. Do NOT proceed to `apps create` / `apps deploy` yet — wait for the user to test and explicitly ask to deploy. (`apps dev` is what puts the app in Local development; without a running session the app never appears there.) **Before handing off, complete all three acceptance checks:**
-   1. Registry: `cat "$CONDUCTOR_WORKSPACE_PATH/.context/app-dev-sessions.json"` lists the app's `devSlug` with a fresh `lastHeartbeatAt`. If it is absent (the session landed in global `~/.notis` instead), restart with `NOTIS_APP_DEV_SESSIONS_FILE="$CONDUCTOR_WORKSPACE_PATH/.context/app-dev-sessions.json"`.
-   2. Bundle: the session's loopback `/snapshot` URL responds successfully and contains the expected manifest/routes.
-   3. Mount acknowledgment: capture the current `apps dev` status `Mounted in Notis: <app name>`. This is the deterministic proof that the nonce-backed session reached the Portal's final Local development sidebar model. If the CLI says only `Serving locally`, do not claim the app is mounted. Manual Electron rendering is optional here; use it when the task specifically requires UI/behavior verification, not as the mount handshake.
+8. **Local-development-first handoff — STOP HERE.** Keep `apps dev` running and hand off to the user: tell them the app is live in the target desktop's **Local development** sidebar group (green `DEV` badge) and ask them to test it there. Building a new app to this point, without deploying, is a **complete and expected** result. Do NOT proceed to `apps create` / `apps deploy` yet — wait for the user to test and explicitly ask to deploy. (`apps dev` is what puts the app in Local development; without a running session the app never appears there.) **Before handing off, complete all three acceptance checks:**
+   1. Target: capture the CLI's `Target desktop: <name>` line and make sure that exact desktop app is running and signed in.
+   2. Bundle: the reported loopback `/snapshot` URL responds successfully and contains the expected manifest/routes.
+   3. Mount and render: require `Mounted in <target desktop>: <app name>`. If the task includes UI or runtime behavior, open the default route and also require `Rendered in <target desktop>: <app name>`. If the CLI says only `Serving locally`, do not claim the app is mounted.
    See Troubleshooting → *App is missing from Local development* if any check fails.
 9. **Deploy only when the user asks.** Once the user has tested locally and explicitly requests a deploy, run `npx --package @notis_ai/cli@latest -- notis apps create "<name>" .` (first time) then `npx --package @notis_ai/cli@latest -- notis apps deploy --direct`, or link first with `npx --package @notis_ai/cli@latest -- notis apps link <id> .` / pass `--app-id <id>` for an existing app. Deploy installs or updates the app on the user's account (it appears under **Workspace**, not Local development). After first install, `.notis/state.json` must point at the installed app id so future local-dev actions become **Update**, not another **Install**.
 10. **Submit only after confirmation.** When the user explicitly confirms the current App Details page is ready, ensure the approved state is deployed, then run `npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready`. The command submits Team apps immediately or opens the Public Store registry review PR. Without that confirmation, stop after deploy.
@@ -484,7 +482,7 @@ This uploads the bundle and editable source snapshot directly to Supabase storag
 
 1. **Build validation**: `npx --package @notis_ai/cli@latest -- notis apps build` must succeed without errors. Vite surfaces TypeScript and bundling errors during this step.
 2. **Headless render verification** (recommended after every build): run `npx --package @notis_ai/cli@latest -- notis apps verify`. It builds unless `--skip-build` is passed, spins up a loopback harness, drives `agent-browser` against every route, and reports per-route pass/fail with captured render errors and runtime calls.
-3. **Local development acceptance**: Require the running CLI to report `Mounted in Notis`, which proves the exact nonce-backed session entered the current Electron Portal's final `Local development` sidebar model. Registry presence and bundle HTTP health alone prove only `Serving locally`. Opening the default route, asserting shadow-root content, and exercising hot reload remain the right checks when the task includes UI, runtime behavior, or visual acceptance, but they are not required merely to prove mounting.
+3. **Local development acceptance**: Require the running CLI to name the intended desktop and report `Mounted in <target desktop>`, which proves the exact nonce-backed session entered that visible desktop's final `Local development` sidebar model. Bundle HTTP health alone proves only `Serving locally`. When the task includes UI, runtime behavior, or visual acceptance, open the default route and also require `Rendered in <target desktop>` before claiming the app works.
 4. **Post-deploy**: Verify the deployed bundle via `/portal_views/get` -> `runtime_descriptor.bundle.js_url`, then verify the app renders in the portal. The portal renders app bundles directly as React components, so the fastest verification is navigating to the app page in the portal.
 
 ### Headless harness verification
@@ -511,15 +509,6 @@ Run `npx --package @notis_ai/cli@latest -- notis apps verify` after `npx --packa
 
 - **Deploy fails with network error**: Backend server not running. Use `npx --package @notis_ai/cli@latest -- notis apps deploy --direct` or start the server.
 - **App shows old code after deploy**: Bundle cache is stale. Hard refresh (Cmd+Shift+R) or clear site data in DevTools.
-- **App is missing from Local development**: First confirm the app lives in the directory owned by the long-running supervisor (`apps/<slug>/` in the Notis monorepo), the current worktree's Electron app is running, and `npx --package @notis_ai/cli@latest -- notis apps dev` is bound to loopback. Then check the **dev-session registry**: `apps dev` records its session in a JSON registry the desktop polls, and the desktop reads a **per-workspace** file at `<workspace>/.context/app-dev-sessions.json` (it sets `NOTIS_APP_DEV_SESSIONS_FILE` on its own runs). An agent-launched `apps dev` that does not resolve that file writes to the global `~/.notis/app-dev-sessions.json` instead — the bundle serves fine but the app never shows in that workspace's sidebar. Verify your session is in the workspace file:
-  ```bash
-  cat "$CONDUCTOR_WORKSPACE_PATH/.context/app-dev-sessions.json"   # your devSlug must be present with a fresh lastHeartbeatAt
-  ```
-  If it is missing, restart `apps dev` pointed at that file:
-  ```bash
-  NOTIS_APP_DEV_SESSIONS_FILE="$CONDUCTOR_WORKSPACE_PATH/.context/app-dev-sessions.json" \
-    npx --package @notis_ai/cli@latest -- notis apps dev --no-open
-  ```
-  Current CLI auto-resolves the nearest `.context` registry, so the explicit env is only a fallback for older CLIs. Startup and heartbeat preserve other sessions, so this coexists with the desktop's own dev sessions. If the registry row has a `targetAppId`, that id must resolve to an installed app whose manifest is not `is_dev: true`; never repair this by linking to another development-runtime id. Restart the current CLI and let it clear stale hidden/deleted targets automatically. Then wait for `Mounted in Notis`; Electron writes the matching nonce acknowledgment beside the registry only after the app reaches the final Local development sidebar model. A corrected registry row or HTTP 200 is not mount proof by itself. Open and render the route separately only when validating UI or runtime behavior.
+- **App is missing from Local development**: Read the `Target desktop` line from `apps dev`, then bring that exact Notis app forward and confirm it is signed into the same account reported by `npx --package @notis_ai/cli@latest -- notis whoami`. Keep `apps dev` running. If it still says only `Serving locally`, run `npx --package @notis_ai/cli@latest -- notis doctor`, restart the target desktop, and retry `apps dev`. Do not redirect internal registry files manually: the CLI selects the normal Notis/Notis Beta target from the active profile and selects a source-workspace desktop only when an active workspace runtime identifies it. Wait for `Mounted in <target desktop>` before claiming success; when validating UI or runtime behavior, open the route and wait for `Rendered in <target desktop>` too.
 - **`LOCAL_NOTIS_DATABASE_QUERY` returns empty documents**: Check that the database ID passed to the tool matches the intended database. Use `npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_LIST_DATABASES --arguments '{}'` to verify the ID; use the database slug only as a fallback.
 - **Properties are `undefined`**: Keep app-local result types for `useTool<TArgs, TResult>` and guard optional nested properties when reading live data.

package/src/command-specs/apps.js

@@ -44,10 +44,12 @@ import {
   runHarnessRoute,
 } from '../runtime/agent-browser.js';
 import {
+  getAppDevSessionsFile,
   heartbeatAppDevSession,
   removeAppDevSession,
   upsertAppDevSessions,
   waitForAppDevSessionMountAcknowledgements,
+  waitForAppDevSessionRenderAcknowledgements,
 } from '../runtime/app-dev-sessions.js';
 import { getAvailablePort } from '../runtime/ports.js';
 import { getCliMode } from '../runtime/cli-mode.js';
@@ -140,13 +142,24 @@ function decodeJwtSub(jwt) {
   }
 }
 
-function openInBrowser(url) {
-  const platform = process.platform;
+export function developmentDesktopOpenCommand(
+  url,
+  {
+    platform = process.platform,
+    appName = null,
+    bundleId = null,
+    scheme = 'notis',
+  } = {},
+) {
   let command;
   let args;
   if (platform === 'darwin') {
     command = 'open';
-    args = [url];
+    args = bundleId && scheme === 'notis'
+      ? ['-b', bundleId, url]
+      : appName && scheme === 'notis'
+        ? ['-a', appName, url]
+        : [url];
   } else if (platform === 'win32') {
     command = 'cmd';
     args = ['/c', 'start', '', url];
@@ -154,10 +167,14 @@ function openInBrowser(url) {
     command = 'xdg-open';
     args = [url];
   }
+  return { command, args };
+}
+
+function openInBrowser(url, options = {}) {
+  const { command, args } = developmentDesktopOpenCommand(url, options);
   try {
-    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    const child = spawn(command, args, { stdio: 'ignore' });
     child.on('error', () => {});
-    child.unref();
   } catch {
     // Non-fatal. The URL is printed in the CLI output.
   }
@@ -207,21 +224,55 @@ function pickDefaultRouteSlug(manifest) {
 
 const DESKTOP_DEEP_LINK_SCHEME_PATTERN = /^[a-z][a-z0-9-]*$/;
 
-export function resolveDevelopmentDesktopScheme(env = process.env) {
+export function resolveDevelopmentDesktopScheme(env = process.env, worktreeRuntime = null) {
   // Mirror the desktop app's own scheme resolution (electron main + forge config):
   // local dev launches register `notis-dev`, while installed prod/beta builds claim
   // `notis`. Hardcoding `notis` here is what made `apps dev` open the installed
   // prod/beta app instead of the local dev app.
-  const scheme = (env.NOTIS_DESKTOP_DEEP_LINK_SCHEME || '').trim();
+  const scheme = (
+    worktreeRuntime?.desktop_deep_link_scheme
+    || env.NOTIS_DESKTOP_DEEP_LINK_SCHEME
+    || ''
+  ).trim();
   return DESKTOP_DEEP_LINK_SCHEME_PATTERN.test(scheme) ? scheme : 'notis';
 }
 
+export function resolveDevelopmentDesktopAppName(runtime = {}) {
+  const explicit = String(
+    runtime.desktopAppName
+    || runtime.worktreeRuntime?.desktop_app_name
+    || '',
+  ).trim();
+  if (explicit) {
+    return explicit;
+  }
+  try {
+    return new URL(runtime.apiBase).hostname === 'api-beta.notis.ai'
+      ? 'Notis Beta'
+      : 'Notis';
+  } catch {
+    return 'Notis';
+  }
+}
+
+export function resolveDevelopmentDesktopBundleId(runtime = {}) {
+  return resolveDevelopmentDesktopAppName(runtime) === 'Notis Beta'
+    ? 'ai.notis.desktop.beta'
+    : 'ai.notis.desktop';
+}
+
 export function buildDevelopmentDesktopUrl(appHref = null, scheme = 'notis') {
   const route = String(appHref || '/store').replace(/^\/+/, '');
   const normalizedScheme = DESKTOP_DEEP_LINK_SCHEME_PATTERN.test(scheme) ? scheme : 'notis';
   return `${normalizedScheme}://${route || 'store'}`;
 }
 
+export function buildMountedDevelopmentDesktopUrl(appHref, scheme, sessionId) {
+  const url = new URL(buildDevelopmentDesktopUrl(appHref, scheme));
+  url.searchParams.set('notis_dev_session', sessionId);
+  return url.toString();
+}
+
 export function shouldOpenDevelopmentTab(options = {}) {
   // Commander stores the negatable `--no-open` flag as `options.open === false`;
   // it never sets `options.noOpen`. Reading the non-existent `noOpen` key meant
@@ -230,8 +281,17 @@ export function shouldOpenDevelopmentTab(options = {}) {
   return options.open !== false;
 }
 
-function buildAppHref({ appSlug, appId, manifest }) {
-  const originlessBase = `/apps/${appSlug}-${appId}`;
+export function buildDevelopmentAppHref({
+  appSlug,
+  appId,
+  devSlug,
+  targetAppId = null,
+  targetAppSlug = null,
+  manifest,
+}) {
+  const routeAppId = `${targetAppId || appId}__local_dev__${devSlug}`;
+  const routeAppSlug = targetAppSlug || devSlug || appSlug;
+  const originlessBase = `/apps/${routeAppSlug}-${routeAppId}`;
   const routeSlug = pickDefaultRouteSlug(manifest);
   return routeSlug ? `${originlessBase}/${routeSlug}` : originlessBase;
 }
@@ -499,8 +559,9 @@ export async function ensureDevInstall({
   const manifest = buildManifestForDev(appConfig);
   const skills = resolveConfiguredAppSkills(appConfig, projectDir);
   let linkedState = readLinkedState(projectDir);
+  let linkedApp = null;
   if (linkedState?.app_id) {
-    const linkedApp = await getAccessibleApp(ctx.runtime, linkedState.app_id, runTool);
+    linkedApp = await getAccessibleApp(ctx.runtime, linkedState.app_id, runTool);
     if (linkedApp?.manifest?.is_dev === true) {
       const { app_id: legacyDevAppId, linked_at: _linkedAt, deployed_at: _deployedAt, version: _version, ...rest } = linkedState;
       const devAppId = linkedState.dev_app_id || legacyDevAppId;
@@ -512,6 +573,7 @@ export async function ensureDevInstall({
         } : {}),
       };
       writeLinkedState(projectDir, linkedState);
+      linkedApp = null;
     }
   }
   const ensureArguments = buildEnsureDevInstallArguments({ appConfig, manifest, linkedState, skills });
@@ -544,6 +606,7 @@ export async function ensureDevInstall({
     created: ensureResult.payload.created || false,
     linkedAppId: linkedState?.app_id || null,
     targetAppId: linkedState?.app_id || null,
+    targetAppSlug: linkedApp?.slug || null,
     databaseMaterialization: ensureResult.payload.database_materialization || { created: [], unresolved: [] },
   };
 }
@@ -725,6 +788,15 @@ async function appsDevHandler(ctx) {
     throw usageError('Could not determine the current user from the CLI auth token. Open the Notis desktop app, sign in, and retry.');
   }
   const apiBase = String(ctx.runtime.apiBase || '').replace(/\/$/, '');
+  const sessionsFilePath = getAppDevSessionsFile(
+    ctx.runtime.worktreeRuntime?.app_dev_sessions_file,
+  );
+  const desktopScheme = resolveDevelopmentDesktopScheme(
+    process.env,
+    ctx.runtime.worktreeRuntime,
+  );
+  const desktopAppName = resolveDevelopmentDesktopAppName(ctx.runtime);
+  const desktopBundleId = resolveDevelopmentDesktopBundleId(ctx.runtime);
   const sessionId = randomUUID();
 
   const candidates = [];
@@ -780,16 +852,25 @@ async function appsDevHandler(ctx) {
       ...app,
       bundleBaseUrl,
       mountNonce: randomUUID(),
-      appHref: buildAppHref({
+      appHref: buildDevelopmentAppHref({
         appSlug: app.slug,
         appId: app.appId,
+        devSlug: app.devSlug,
+        targetAppId: app.targetAppId,
+        targetAppSlug: app.targetAppSlug,
         manifest: app.manifest,
       }),
     };
   });
   const developmentTabUrl = buildDevelopmentDesktopUrl(
     apps[0]?.appHref,
-    resolveDevelopmentDesktopScheme(),
+    desktopScheme,
+  );
+  const desktopWakeUrl = buildDevelopmentDesktopUrl('/manage', desktopScheme);
+  const mountedDevelopmentTabUrl = buildMountedDevelopmentDesktopUrl(
+    apps[0]?.appHref,
+    desktopScheme,
+    sessionId,
   );
   const warnings = databaseMaterializationWarnings(apps);
 
@@ -802,6 +883,7 @@ async function appsDevHandler(ctx) {
       userId: identity,
     })),
     port,
+    sessionsFilePath,
   });
 
   try {
@@ -818,7 +900,8 @@ async function appsDevHandler(ctx) {
       projectDir: app.projectDir,
       startedAt: now,
       lastHeartbeatAt: now,
-    })));
+      desktopAppName,
+    })), sessionsFilePath);
   } catch (error) {
     try {
       await devServer.close();
@@ -830,7 +913,7 @@ async function appsDevHandler(ctx) {
 
   let heartbeatTimer = setInterval(() => {
     try {
-      heartbeatAppDevSession(sessionId, new Date().toISOString());
+      heartbeatAppDevSession(sessionId, new Date().toISOString(), sessionsFilePath);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       process.stderr.write(`[notis apps dev] heartbeat failed: ${message}\n`);
@@ -852,6 +935,8 @@ async function appsDevHandler(ctx) {
       development_url: developmentTabUrl,
       session_id: sessionId,
       mount_status: 'serving',
+      render_status: 'waiting_for_route',
+      desktop_target: desktopAppName,
       identity,
       apps: apps.map((app) => ({
         slug: app.devSlug,
@@ -869,36 +954,67 @@ async function appsDevHandler(ctx) {
     warnings,
     humanSummary: [
       `Running apps dev against ${apiBase} as ${identity} (mode: ${mode})`,
+      `Target desktop: ${desktopAppName}`,
       '',
       `Open in desktop: ${developmentTabUrl}`,
       '',
       ...apps.map((app) => `  ${app.name.padEnd(24)} ${app.bundleBaseUrl} -> ${app.appHref}`),
       '',
-      `Serving locally; waiting for Notis to mount ${apps.length === 1 ? 'the app' : `${apps.length} apps`}.`,
+      `Serving locally; waiting for ${desktopAppName} to mount ${apps.length === 1 ? 'the app' : `${apps.length} apps`}.`,
       '',
       'Press Ctrl-C to stop.',
     ].join('\n'),
   });
 
   if (shouldOpenDevelopmentTab(ctx.options)) {
-    openInBrowser(developmentTabUrl);
+    openInBrowser(desktopWakeUrl, {
+      appName: desktopAppName,
+      bundleId: desktopBundleId,
+      scheme: desktopScheme,
+    });
   }
 
   void (async () => {
-    let result = await waitForAppDevSessionMountAcknowledgements(expectedMountAcknowledgements);
+    let result = await waitForAppDevSessionMountAcknowledgements(expectedMountAcknowledgements, {
+      sessionsFilePath,
+    });
     if (!result.mounted) {
       process.stderr.write(
-        `[notis apps dev] Serving locally, but Notis has not acknowledged ${result.missing.length === 1 ? 'the app' : `${result.missing.length} apps`} in its Local development sidebar yet. Keep this command running and open Notis.\n`,
+        `[notis apps dev] Serving locally, but ${desktopAppName} has not acknowledged ${result.missing.length === 1 ? 'the app' : `${result.missing.length} apps`} in its Local development sidebar yet. Keep this command running and open ${desktopAppName}.\n`,
       );
     }
     while (!result.mounted) {
       result = await waitForAppDevSessionMountAcknowledgements(expectedMountAcknowledgements, {
+        sessionsFilePath,
+        timeoutMs: 60_000,
+        pollIntervalMs: 250,
+      });
+    }
+    process.stderr.write(
+      `[notis apps dev] Mounted in ${desktopAppName}: ${apps.map((app) => app.name).join(', ')}.\n`,
+    );
+    if (shouldOpenDevelopmentTab(ctx.options)) {
+      openInBrowser(mountedDevelopmentTabUrl, {
+        appName: desktopAppName,
+        bundleId: desktopBundleId,
+        scheme: desktopScheme,
+      });
+    }
+
+    const firstAppRender = expectedMountAcknowledgements.slice(0, 1);
+    let renderResult = await waitForAppDevSessionRenderAcknowledgements(firstAppRender, {
+      sessionsFilePath,
+      timeoutMs: 0,
+    });
+    while (!renderResult.mounted) {
+      renderResult = await waitForAppDevSessionRenderAcknowledgements(firstAppRender, {
+        sessionsFilePath,
         timeoutMs: 60_000,
         pollIntervalMs: 250,
       });
     }
     process.stderr.write(
-      `[notis apps dev] Mounted in Notis: ${apps.map((app) => app.name).join(', ')}.\n`,
+      `[notis apps dev] Rendered in ${desktopAppName}: ${apps[0].name}.\n`,
     );
   })().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
@@ -915,7 +1031,7 @@ async function appsDevHandler(ctx) {
       heartbeatTimer = null;
     }
     try {
-      removeAppDevSession(sessionId);
+      removeAppDevSession(sessionId, sessionsFilePath);
     } catch {
       // ignore cleanup failures during shutdown
     }

package/src/runtime/app-dev-server.js

@@ -288,12 +288,13 @@ function renderHarnessHtml({ state, manifest, appConfig, route, harnessOptions,
 /**
  * Start the dev server for one or more apps.
  *
- * @param {{apps: Array<{slug: string, projectDir: string, appId?: string, targetAppId?: string, userId?: string}>, port: number, watch?: boolean, harness?: { mode?: string, apiBase?: string, jwt?: string }, log?: (m: string) => void, logError?: (m: string) => void}} options
+ * @param {{apps: Array<{slug: string, projectDir: string, appId?: string, targetAppId?: string, userId?: string}>, port: number, watch?: boolean, sessionsFilePath?: string, harness?: { mode?: string, apiBase?: string, jwt?: string }, log?: (m: string) => void, logError?: (m: string) => void}} options
  */
 export async function startAppDevServer({
   apps,
   port,
   watch = true,
+  sessionsFilePath,
   harness = {},
   log = (msg) => process.stdout.write(`${msg}\n`),
   logError = (msg) => process.stderr.write(`${msg}\n`),
@@ -466,7 +467,7 @@ export async function startAppDevServer({
                 devSlug: state.slug,
                 targetAppId: appId,
                 lastHeartbeatAt: now,
-              });
+              }, sessionsFilePath);
               const response = {
                 ok: true,
                 app_id: appId,

package/src/runtime/app-dev-sessions.js

@@ -1,6 +1,5 @@
 import { randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join, parse as parsePath } from 'node:path';
 import { CONFIG_DIR } from './profiles.js';
 
@@ -9,37 +8,6 @@ export const APP_DEV_SESSIONS_FILE = DEFAULT_APP_DEV_SESSIONS_FILE;
 export const APP_DEV_SESSIONS_VERSION = 1;
 export const APP_DEV_SESSION_MOUNT_ACKS_VERSION = 1;
 
-/**
- * Walk up from `startDir` looking for a workspace-scoped dev-sessions registry.
- *
- * The Notis desktop (and Conductor) reads a PER-WORKSPACE registry at
- * `<workspace>/.context/app-dev-sessions.json` (it points its own `apps dev`
- * at it via `NOTIS_APP_DEV_SESSIONS_FILE`). When a coding agent runs
- * `apps dev` manually it does not inherit that env var, so its session would
- * otherwise land in the global `~/.notis` registry and never appear in the
- * desktop's Local development sidebar. Resolving the nearest `.context`
- * registry keeps agent-run and desktop-run sessions in the same file.
- *
- * Returns the registry path if a `.context/` directory is found in `startDir`
- * or an ancestor (stopping at the home directory / filesystem root), else null.
- */
-export function findWorkspaceAppDevSessionsFile(startDir = process.cwd()) {
-  let dir = startDir;
-  const home = homedir();
-  const { root } = parsePath(dir);
-  // Bounded walk; `.context` lives at the workspace root, never above $HOME.
-  for (let depth = 0; depth < 64; depth += 1) {
-    if (existsSync(join(dir, '.context'))) {
-      return join(dir, '.context', 'app-dev-sessions.json');
-    }
-    if (dir === home || dir === root) break;
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
-}
-
 export function getAppDevSessionsFile(filePath) {
   if (filePath) {
     return filePath;
@@ -48,10 +16,6 @@ export function getAppDevSessionsFile(filePath) {
   if (typeof envPath === 'string' && envPath.trim()) {
     return envPath.trim();
   }
-  const workspaceFile = findWorkspaceAppDevSessionsFile();
-  if (workspaceFile) {
-    return workspaceFile;
-  }
   return DEFAULT_APP_DEV_SESSIONS_FILE;
 }
 
@@ -173,7 +137,7 @@ function normalizeMountAcknowledgements(raw) {
     typeof acknowledgement.devSlug === 'string' &&
     typeof acknowledgement.mountNonce === 'string' &&
     typeof acknowledgement.acknowledgedAt === 'string' &&
-    acknowledgement.stage === 'listed',
+    ['listed', 'rendered'].includes(acknowledgement.stage),
   );
 }
 
@@ -218,12 +182,13 @@ export function removeAppDevSessionMountAcknowledgements(sessionId, sessionsFile
   return writeAppDevSessionMountAcknowledgements(registry, sessionsFilePath);
 }
 
-function mountAcknowledgementKey(value) {
-  return `${value.sessionId}:${value.appId}:${value.devSlug}:${value.mountNonce}`;
+function mountAcknowledgementKey(value, fallbackStage = 'listed') {
+  return `${value.sessionId}:${value.appId}:${value.devSlug}:${value.mountNonce}:${value.stage || fallbackStage}`;
 }
 
 export async function waitForAppDevSessionMountAcknowledgements(expectedSessions, options = {}) {
   const expected = Array.isArray(expectedSessions) ? expectedSessions : [expectedSessions];
+  const stage = options.stage === 'rendered' ? 'rendered' : 'listed';
   const timeoutMs = Number.isFinite(options.timeoutMs) ? Math.max(0, options.timeoutMs) : 15_000;
   const pollIntervalMs = Number.isFinite(options.pollIntervalMs)
     ? Math.max(1, options.pollIntervalMs)
@@ -237,7 +202,9 @@ export async function waitForAppDevSessionMountAcknowledgements(expectedSessions
   while (true) {
     const registry = readAppDevSessionMountAcknowledgements(options.sessionsFilePath);
     const acknowledgedKeys = new Set(registry.acknowledgements.map(mountAcknowledgementKey));
-    const missing = expected.filter((session) => !acknowledgedKeys.has(mountAcknowledgementKey(session)));
+    const missing = expected.filter(
+      (session) => !acknowledgedKeys.has(mountAcknowledgementKey(session, stage)),
+    );
     if (missing.length === 0) {
       return { mounted: true, missing: [], acknowledgements: registry.acknowledgements };
     }
@@ -249,3 +216,10 @@ export async function waitForAppDevSessionMountAcknowledgements(expectedSessions
     await sleep(Math.min(pollIntervalMs, timeoutMs - elapsedMs));
   }
 }
+
+export function waitForAppDevSessionRenderAcknowledgements(expectedSessions, options = {}) {
+  return waitForAppDevSessionMountAcknowledgements(expectedSessions, {
+    ...options,
+    stage: 'rendered',
+  });
+}

package/src/runtime/profiles.js

@@ -143,6 +143,14 @@ export function resolveWorktreeRuntime(startDir = process.cwd()) {
   const runtime = readJsonFile(runtimePath);
   const apiBase = typeof runtime?.api_base === 'string' ? runtime.api_base.replace(/\/+$/, '') : '';
   const configFile = typeof runtime?.config_file === 'string' ? runtime.config_file : '';
+  const appDevSessionsFile =
+    typeof runtime?.app_dev_sessions_file === 'string' && runtime.app_dev_sessions_file.trim()
+      ? runtime.app_dev_sessions_file.trim()
+      : join(dirname(runtimePath), 'app-dev-sessions.json');
+  const desktopDeepLinkScheme =
+    typeof runtime?.desktop_deep_link_scheme === 'string'
+      ? runtime.desktop_deep_link_scheme.trim()
+      : '';
   const pid = Number(runtime?.dev_pid);
   if (
     runtime?.mode !== 'local-only' ||
@@ -165,6 +173,8 @@ export function resolveWorktreeRuntime(startDir = process.cwd()) {
     ...runtime,
     api_base: apiBase,
     config_file: resolve(dirname(runtimePath), configFile),
+    app_dev_sessions_file: resolve(dirname(runtimePath), appDevSessionsFile),
+    desktop_deep_link_scheme: desktopDeepLinkScheme || undefined,
     runtime_path: runtimePath,
     routing_path: routingPath,
   };