@notis_ai/cli 0.2.0-beta.145.1 → 0.2.0-beta.151.1

package/dist/base-skills/notis-apps/SKILL.md

@@ -102,11 +102,11 @@ App code never accesses the runtime directly -- it uses SDK hooks (`useTool`, `u
 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, scoped under the authenticated environment. Never pass a runtime app whose manifest has `is_dev: true` to `notis apps link`.
 18. **Automatic mounts are multi-instance and least-authority** -- Prod, Beta, and source-development Desktop instances may mount the same source simultaneously with independent authenticated runtimes. Automatic mounting never grants capabilities: reuse existing grants and leave restricted capabilities denied until approved. Consumer leases expire after crashes so the shared host exits after the last live instance. There are no offline rows or manual start/stop controls.
 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.
+20. **Bump `notisAppVersion` before linked development and every Store update** -- `package.json` must contain a semver `notisAppVersion`. A linked local source substitutes its installed Workspace app only when the local version is strictly greater than the installed manifest's `release_version`; equal, lower, missing, or invalid versions keep serving the online bundle. `apps pull` retrieves the online version, so increment `notisAppVersion` before `apps dev` when continuing development. For an existing Store app, also 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.
 22. **Database rows are private unless explicitly seeded** -- A string declaration such as `databases: ['notes']` publishes schema only and never includes the developer's rows. Use `{ slug: 'templates', seedDocuments: true }` only for small, intentional starter content that every installer should receive. Never enable it for user-created notes, history, leads, or other personal data.
 23. **Public submissions are complete, reviewable packages** -- The registry PR must contain the full editable source tree, Store assets, exact source-declared database schemas, and only explicitly seeded starter rows. Registry CI validates those boundaries before merge; do not hand-edit `notis-listing.json` or strip source files to make a check pass. Fix the app locally, redeploy, and resubmit.
-24. **New projects land in `~/.notis/apps/<slug>`, and `[dir]` overrides it** -- `apps init` and `apps pull` default to that root, the same well-known home the desktop uses for synced skills (`~/.notis/skills`), so a project nobody deliberately placed is always findable and never depends on where the shell happened to be sitting. Pass `[dir]` whenever the app belongs somewhere specific -- a git repo the user tracks, an existing monorepo's `apps/<name>/`, or a path the user named -- and tell the user which location you used. Never place a project inside the Notis source repo or a Conductor worktree: every later CLI call from that directory resolves the worktree's local dev runtime (`.context/notis-runtime.json`) instead of the user's real profile.
+24. **New projects default to `~/.notis/apps/<slug>`, and `[dir]` overrides it** -- `apps init` and `apps pull` use this stable, predictable home unless the app belongs in a specific repository, monorepo, or user-chosen location. In those cases, pass `[dir]` and report the resulting path. Do not nest an app inside a directory whose local workspace metadata selects an unrelated Notis runtime or profile: later CLI calls inherit that routing and may target the wrong environment.
 
 ## Anti-patterns -- NEVER do these
 
@@ -130,10 +130,10 @@ These are the most common mistakes agents make. Each one wastes time and produce
 **Default to the Store scaffold catalog, not a blank project.** Every published Store app is a scaffold: `notis apps scaffolds list` reads the catalog from the public registry, and `notis apps init --from <slug>` downloads that app's source. Most user requests overlap with a published app, and starting from one is faster than a bare app.
 
 1. **Find a starting point.** Run `npx --package @notis_ai/cli@latest -- notis apps scaffolds list` (add `--search <term>` to filter) to list the published Store apps. If something close matches, run `npx --package @notis_ai/cli@latest -- notis apps init "My App" --from <slug>` to download that app's source from the registry. Only run plain `notis apps init "My App"` when no published app fits. Either way the project lands in `~/.notis/apps/<slug>`; add a `[dir]` argument when the user wants it somewhere else (a tracked git repo, an existing monorepo), and report the path you used.
-2. **Pull your own apps; fork Store apps with `--from`.** `apps pull` is for apps the user already has installed or deployed: run `npx --package @notis_ai/cli@latest -- notis apps list`, then `npx --package @notis_ai/cli@latest -- notis apps pull <app-id>` (lands in `~/.notis/apps/<app-slug>`; pass a `[dir]` argument to place it elsewhere). To fork a published Store app, use `apps init --from <slug>` instead -- it downloads the source from the registry and does not require installing the app first.
+2. **Pull your own apps; fork Store apps with `--from`.** `apps pull` is for apps the user already has installed or deployed: run `npx --package @notis_ai/cli@latest -- notis apps list`, preserve any local edits in the target directory, then run `npx --package @notis_ai/cli@latest -- notis apps pull <app-id>` (lands in `~/.notis/apps/<app-slug>`; pass a `[dir]` argument to place it elsewhere). A pull reproduces the installed release, so increment `package.json` `notisAppVersion` above that release before `apps dev`; until then the online bundle remains active. To fork a published Store app, use `apps init --from <slug>` instead -- it downloads the source from the registry and does not require installing the app 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 [folder]` once. It permanently registers the root; `~/.notis/apps` is already implicit. Running Desktop instances discover the root itself, direct app children, and `apps/*`, then mount each successful build automatically in Workspace. Source edits hot-reload only that app in every instance. Add `--scratch` for isolated empty resources when the work needs fixtures or destructive experiments.
+5. **Iterate live.** Before developing a linked installed app, increment `package.json` `notisAppVersion` above the installed release. Then run `npx --package @notis_ai/cli@latest -- notis apps dev [folder]` once. It permanently registers the root; `~/.notis/apps` is already implicit. Running Desktop instances discover the root itself, direct app children, and `apps/*`, then mount each successful build automatically in Workspace. A linked build substitutes the online bundle only while its version is strictly greater; equal or stale builds remain served online. Source edits hot-reload only that app in every instance. Add `--scratch` for isolated empty resources when the work needs fixtures or destructive experiments.
 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. A `scenario` names an entry in `metadata/screenshot-fixtures.json`; besides `actions` it may carry its own `tools` and `requests`, shallow-merged per key over the file-level ones for that capture, which is how the same route is shown both populated and in its first-run empty state.
 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. Incomplete listing media is only a `Store readiness:` warning there; run `notis apps verify --listing` before publish to make it a failure.
 8. **Local-development-first handoff — STOP HERE.** Hand off after the user can see and test the app in its DEV-badged Workspace row. Building a new app to this point, without deploying, is a **complete and expected** result. Do NOT proceed to `apps create` / `apps deploy` yet. **Before handing off, complete all three acceptance checks:**
@@ -191,6 +191,7 @@ npx --package @notis_ai/cli@latest -- notis apps list
 npx --package @notis_ai/cli@latest -- notis apps pull <installed-app-id>
 cd ~/.notis/apps/my-app
 npm install
+# Increment package.json notisAppVersion above the pulled online release.
 npx --package @notis_ai/cli@latest -- notis apps dev
 npx --package @notis_ai/cli@latest -- notis apps build
 npx --package @notis_ai/cli@latest -- notis apps verify
@@ -234,6 +235,8 @@ routes: [
 
 Use the same page template for the root Notes route and collection/sub-collection detail states. The portal sidebar injects live collection items under the static route row when `collection.sidebar.mode === 'tree'`.
 
+For arbitrary app-owned resources that are not Notis collection rows, set `resourceDeepLinks: true` on the route. Read the decoded `?resource=` identifier from `useNotis().resourceId`, and link between routes with `toRoute('/inbox', { resourceId })`. Keep collection links on `?item=`. Publish external preview/source links as the resource `url`; the host separately supplies the exact Notis review link as `active_resource.view_url` for opted-in routes. Handle missing or deleted identifiers with a safe view-level fallback.
+
 ### Step 2: Build pages
 
 Standard React pages in `app/`. Use generic SDK tool hooks for data and build on top of the scaffolded shadcn components and portal shell classes (`notis-app-shell`, `notis-app-surface`):
@@ -444,10 +447,10 @@ already installs `ShortcutProvider`; app code should not add a second provider.
 
 | API | Signature | Description |
 |-----|-----------|-------------|
-| `useNotis()` | `() => { app, route, context, ready }` | App metadata, current route, generic portal context, ready state |
+| `useNotis()` | `() => { app, route, databases, collectionItem, resourceId, ready }` | App metadata, current route, selected collection item, decoded exact-resource id, ready state |
 | `useTool<TArgs, TResult>(name)` | `(name: string) => { call, loading, error }` | Call a declared tool with app-defined argument/result types. Identical idempotent reads may use `call(args, { dedupe: true })`; never dedupe writes |
 | `useTools()` | `() => { tools, loading }` | List available tools |
-| `useNotisNavigation()` | `() => { toRoute, toDocument, toApp }` | Navigate between routes, documents, or the app root |
+| `useNotisNavigation()` | `() => { toRoute, toDocument, toApp }` | Navigate between routes (including `toRoute(path, { resourceId })`), documents, or the app root |
 | `useTopBarSearch(opts)` | `({ value, onChange, placeholder?, onSubmit? }) => { setLoading }` | Bind the current view to the Portal-owned top-bar search input |
 | `useBackend()` | `() => { request }` | Raw backend request proxy with JWT auth |
 | `useDatabaseSubscription(slug, opts?)` | `(slug: string, opts?) => { rows, documents, loading, error, refetch, live }` | Query a database and refetch it when its rows change. `live` is false on hosts without a change feed (dev harness, vite preview) -- keep a manual refresh for those |
@@ -509,13 +512,13 @@ const result = await queryTasks.call({ database_id: 'tasks-db-id', query: { page
 npx --package @notis_ai/cli@latest -- notis apps dev
 ```
 
-Runs the real desktop-local development workflow. The CLI should discover all apps in the target workspace, serve their bundles from loopback, and surface them in the Electron Portal's Workspace group — each substituted for its installed entry, or appended while unpublished — through the local desktop session registry.
+Runs the real desktop-local development workflow. The CLI should discover all apps in the target workspace and serve their bundles from loopback. Unpublished apps appear in the Electron Portal's Workspace group; linked apps substitute their installed entry only when the local `notisAppVersion` is strictly greater than the installed `release_version`.
 
 ## Testing
 
 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**: Run `notis apps dev [folder]` once to register the root, then verify each signed-in Desktop instance independently: one DEV-badged Workspace row, the default route rendering real app content, and live edits appearing without restarting the CLI or Desktop. Use `notis apps roots list` as the persistence proof. Loopback bundle health alone does not prove that an authenticated instance mounted or rendered the app.
+3. **Local development acceptance**: Run `notis apps dev [folder]` once to register the root, then verify each signed-in Desktop instance independently. For an unpublished app, expect one DEV-badged Workspace row. For a linked app, first confirm local `notisAppVersion` is strictly greater than installed `release_version`, then expect one substituted DEV-badged row; equal or lower must keep the online row and bundle. Verify the default route renders and live edits appear without restarting the CLI or Desktop. Use `notis apps roots list` as the persistence proof. Loopback bundle health alone does not prove that an authenticated instance mounted or rendered the app.
 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
@@ -544,6 +547,6 @@ Run `npx --package @notis_ai/cli@latest -- notis apps verify` after `npx --packa
   authenticated API available. Do not bypass DEV-app promotion or installed-app
   identity with a direct database/storage write.
 - **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 the sidebar**: Run `apps roots list`, confirm the app is at the root, one direct child, or `apps/*`, and confirm its first build succeeds. Restarting Desktop reattaches the same persistent roots; no terminal process or manual sidebar action is required.
+- **App is missing from the sidebar**: Run `apps roots list`, confirm the app is at the root, one direct child, or `apps/*`, and confirm its first build succeeds. For a linked app, compare `package.json` `notisAppVersion` with the installed manifest's `release_version`: equal, lower, missing, or invalid intentionally keeps the online app without a DEV badge. If source is stale, preserve any local edits, run `apps pull <app-id> <dir> --force` to refresh it, then increment `notisAppVersion` before continuing development. Restarting Desktop reattaches the same persistent roots; no terminal process or manual sidebar action is required.
 - **`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/package.json

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

package/skills/notis-apps/cli.md

@@ -118,7 +118,7 @@ Examples:
 
 Register a development root and connect its apps to the shared local development host.
 
-When to use: Run this once for any folder that should be watched permanently. The folder itself, direct child apps, and apps/* are discovered automatically by every signed-in Notis Desktop instance.
+When to use: Run this once for any folder that should be watched permanently. The folder itself, direct child apps, and apps/* are discovered automatically by every signed-in Notis Desktop instance. A linked app substitutes its online bundle only when local notisAppVersion is strictly greater than the installed release.
 
 Options:
 - `--port <number>` — Local bundle server port (default: 5173).
@@ -218,7 +218,7 @@ Examples:
 
 Download a Notis app source snapshot into a local project folder.
 
-When to use: Edit an installed app locally. Pulls the persisted source, links the directory to the app/version, then continue with npm install, notis apps dev, notis apps build, and notis apps deploy.
+When to use: Edit an installed app locally. Preserve any local edits, pull and link the latest persisted source, then increment package.json notisAppVersion above that release before notis apps dev; continue with build and deploy.
 
 Options:
 - `--force` — Overwrite a non-empty target directory.

package/src/command-specs/apps.js

@@ -8,7 +8,7 @@
  */
 
 import { randomUUID } from 'node:crypto';
-import { mkdirSync, mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
 
@@ -36,6 +36,7 @@ import {
   normalizeAppCapabilities,
   normalizeAppToolBindings,
   normalizeAppSkillManifestPath,
+  appRowFieldsFromManifest,
   directDeploy,
   pullAppSource,
 } from '../runtime/app-platform.js';
@@ -45,6 +46,7 @@ import {
   scaffoldRegistryLabel,
 } from '../runtime/app-registry-scaffolds.js';
 import { startAppDevServer } from '../runtime/app-dev-server.js';
+import { captureDesktopHostOwnership } from '../runtime/app-dev-process-identity.js';
 import {
   discoverRegisteredAppProjects,
   readAppDevRoots,
@@ -87,6 +89,8 @@ import {
   toolConflictToError,
 } from './helpers.js';
 
+export { appRowFieldsFromManifest } from '../runtime/app-platform.js';
+
 const DEFAULT_DEV_PORT = 5173;
 const DEV_HEARTBEAT_INTERVAL_MS = 10_000;
 const DEV_CONSUMER_HEARTBEAT_INTERVAL_MS = 3_000;
@@ -98,6 +102,72 @@ function projectIsWithinRoot(projectDir, rootDir) {
   return nested === '' || (nested !== '..' && !nested.startsWith(`..${sep}`) && !isAbsolute(nested));
 }
 
+function parseNotisAppVersion(value) {
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(
+    String(value || '').trim(),
+  );
+  if (!match) return null;
+  const prerelease = match[4] ? match[4].split('.') : [];
+  if (prerelease.some((identifier) => /^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith('0'))) {
+    return null;
+  }
+  return {
+    major: match[1],
+    minor: match[2],
+    patch: match[3],
+    prerelease,
+  };
+}
+
+function compareNumericSemverIdentifiers(left, right) {
+  if (left.length !== right.length) return left.length > right.length ? 1 : -1;
+  return left === right ? 0 : left > right ? 1 : -1;
+}
+
+function compareNotisPrerelease(left, right) {
+  if (left.length === 0 || right.length === 0) {
+    return left.length === right.length ? 0 : left.length === 0 ? 1 : -1;
+  }
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftIdentifier = left[index];
+    const rightIdentifier = right[index];
+    if (leftIdentifier === undefined || rightIdentifier === undefined) {
+      return leftIdentifier === rightIdentifier ? 0 : leftIdentifier === undefined ? -1 : 1;
+    }
+    if (leftIdentifier === rightIdentifier) continue;
+    const leftNumeric = /^\d+$/.test(leftIdentifier);
+    const rightNumeric = /^\d+$/.test(rightIdentifier);
+    if (leftNumeric && rightNumeric) {
+      return compareNumericSemverIdentifiers(leftIdentifier, rightIdentifier);
+    }
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+    return leftIdentifier > rightIdentifier ? 1 : -1;
+  }
+  return 0;
+}
+
+export function compareNotisAppVersions(leftValue, rightValue) {
+  const left = parseNotisAppVersion(leftValue);
+  const right = parseNotisAppVersion(rightValue);
+  if (!left || !right) return null;
+  for (const key of ['major', 'minor', 'patch']) {
+    const comparison = compareNumericSemverIdentifiers(left[key], right[key]);
+    if (comparison !== 0) return comparison;
+  }
+  return compareNotisPrerelease(left.prerelease, right.prerelease);
+}
+
+function readLocalNotisAppVersion(projectDir) {
+  try {
+    const packageJson = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8'));
+    const version = String(packageJson.notisAppVersion || '').trim();
+    return parseNotisAppVersion(version) ? version : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * A CLI launch may add one root, but the shared host always serves the complete
  * machine registry. Desktop sets skipRootRegistration because it is reconciling
@@ -410,13 +480,6 @@ export function screenshotIndexByRouteSlug(manifest) {
   return new Map(routes.map((route, index) => [route.slug, index + 1]));
 }
 
-export function appRowFieldsFromManifest(manifest) {
-  const app = manifest?.app && typeof manifest.app === 'object' ? manifest.app : {};
-  return {
-    accent: app.accent ?? null,
-  };
-}
-
 export function screenshotExitCode(failedCount) {
   return failedCount === 0 ? EXIT_CODES.ok : EXIT_CODES.unexpected;
 }
@@ -570,7 +633,7 @@ function renderVerifyReport({ summary, results, noBrowser }) {
   return lines.join('\n');
 }
 
-function buildManifestForDev(appConfig) {
+function buildManifestForDev(appConfig, projectDir) {
   const routes = Array.isArray(appConfig.routes) ? appConfig.routes : [];
   return {
     version: 1,
@@ -579,6 +642,7 @@ function buildManifestForDev(appConfig) {
       name: appConfig.name,
       description: appConfig.description || null,
       icon: appConfig.icon || null,
+      release_version: readLocalNotisAppVersion(projectDir),
     },
     routes: routes.map((route) => ({
       path: route.path,
@@ -587,6 +651,7 @@ function buildManifestForDev(appConfig) {
       icon: route.icon || null,
       parentSlug: route.parentSlug || null,
       default: route.default || false,
+      resourceDeepLinks: route.resourceDeepLinks === true,
       export_name: route.exportName || route.export_name,
       collection: route.collection || null,
     })),
@@ -726,7 +791,7 @@ export async function ensureDevInstall({
     throw usageError(`notis.config.ts devSlug or name in ${projectDir} must slugify to a non-empty value.`);
   }
 
-  const manifest = buildManifestForDev(appConfig);
+  const manifest = buildManifestForDev(appConfig, projectDir);
   const skills = resolveConfiguredAppSkills(appConfig, projectDir);
   const profileKey = linkedStateProfileKey(ctx.runtime);
   let linkedState = readLinkedState(projectDir, profileKey);
@@ -801,6 +866,10 @@ export async function ensureDevInstall({
         ].includes(key)),
       )
     : linkedState;
+  const localReleaseVersion = manifest.app.release_version || null;
+  const installedReleaseVersion = linkedApp?.manifest?.app?.release_version || '0.0.0';
+  const mountEligible = !linkedApp
+    || compareNotisAppVersions(localReleaseVersion, installedReleaseVersion) === 1;
   const ensureArguments = buildEnsureDevInstallArguments({
     appConfig,
     manifest,
@@ -866,6 +935,9 @@ export async function ensureDevInstall({
     linkedAppId: runtimeLinkedState?.app_id || null,
     targetAppId: runtimeLinkedState?.app_id || null,
     targetAppSlug: linkedApp?.slug || null,
+    localReleaseVersion,
+    installedReleaseVersion: linkedApp ? installedReleaseVersion : null,
+    mountEligible,
     databaseMaterialization: ensureResult.payload.database_materialization || { created: [], unresolved: [] },
     liveData: ensureResult.payload.live_data || null,
   };
@@ -892,6 +964,16 @@ function liveDataWarnings(apps) {
     .map((app) => `${app.name}: ${app.liveData.warning}`);
 }
 
+function versionPrecedenceWarnings(apps) {
+  return apps
+    .filter((app) => app.targetAppId && app.mountEligible === false)
+    .map((app) => {
+      const localVersion = app.localReleaseVersion || 'missing or invalid';
+      const pullCommand = `npx --package @notis_ai/cli@latest -- notis apps pull ${app.targetAppId} ${JSON.stringify(app.projectDir)} --force`;
+      return `${app.name}: local version ${localVersion} is not strictly newer than installed version ${app.installedReleaseVersion}; Workspace keeps serving the online bundle. Preserve any local edits, pull latest with \`${pullCommand}\`, then bump package.json notisAppVersion before development.`;
+    });
+}
+
 async function getAccessibleApp(runtime, appId, runTool = runToolCommand) {
   const result = await runTool({
     runtime,
@@ -1305,6 +1387,7 @@ async function appsDevHandler(ctx) {
         isBundleReady: () => true,
         updateApp: () => {},
         waitForBundle: async () => {},
+        getWatcherOwnership: () => null,
       }
     : await startAppDevServer({
         apps: canonicalCandidates.map((app) => ({
@@ -1320,6 +1403,10 @@ async function appsDevHandler(ctx) {
         port,
         sessionsFilePath,
       });
+  const desktopHostOwnership = captureDesktopHostOwnership({
+    desktopOwnerId: process.env.NOTIS_APPS_DEV_DESKTOP_OWNER_ID,
+    desktopOwnerScope: process.env.NOTIS_APPS_DEV_DESKTOP_OWNER_SCOPE,
+  });
 
   let heartbeatTimer = setInterval(() => {
     try {
@@ -1379,6 +1466,8 @@ async function appsDevHandler(ctx) {
         sessionId,
         hostPid: process.pid,
         sourceHost: !sharedBundleBaseUrls,
+        ...(desktopHostOwnership || {}),
+        ...(devServer.getWatcherOwnership(app.devSlug) || {}),
         bundleReady: devServer.isBundleReady(app.devSlug),
         ...(!sharedBundleBaseUrls ? {
           discoveredProjects: discoveredAppDirs,
@@ -1456,6 +1545,7 @@ async function appsDevHandler(ctx) {
     ...registrationWarnings,
     ...databaseMaterializationWarnings(apps),
     ...liveDataWarnings(apps),
+    ...versionPrecedenceWarnings(apps),
   ];
 
   let consumerTimer = null;
@@ -1481,6 +1571,9 @@ async function appsDevHandler(ctx) {
         linked_app_id: app.linkedAppId,
         database_materialization: app.databaseMaterialization,
         live_data: app.liveData,
+        local_release_version: app.localReleaseVersion,
+        installed_release_version: app.installedReleaseVersion,
+        mount_eligible: app.mountEligible,
       })),
     },
     warnings,
@@ -1492,11 +1585,15 @@ async function appsDevHandler(ctx) {
         ? [`Databases: ${apps.filter((app) => app.liveData?.enabled).length}/${apps.length} app(s) reading the installed app's live rows`]
         : []),
       '',
-      ...apps.map((app) => `  ${app.name.padEnd(24)} ${app.bundleBaseUrl} -> ${app.appHref}`),
+      ...apps.map((app) => (
+        app.mountEligible
+          ? `  ${app.name.padEnd(24)} ${app.bundleBaseUrl} -> ${app.appHref}`
+          : `  ${app.name.padEnd(24)} online v${app.installedReleaseVersion} (local ${app.localReleaseVersion || 'version missing'})`
+      )),
       '',
       sharedBundleBaseUrls
-        ? `Mounted ${apps.length} shared source app${apps.length === 1 ? '' : 's'} for this authenticated environment.`
-        : `Serving one shared loopback host for ${apps.length} app${apps.length === 1 ? '' : 's'}.`,
+        ? `Attached to the shared source host: ${apps.filter((app) => app.mountEligible).length}/${apps.length} app${apps.length === 1 ? '' : 's'} eligible to substitute.`
+        : `Serving one shared loopback host for ${apps.length} app${apps.length === 1 ? '' : 's'}; ${apps.filter((app) => app.mountEligible).length} eligible to substitute.`,
       '',
       'Press Ctrl-C to stop.',
     ].join('\n'),
@@ -1527,12 +1624,15 @@ async function appsDevHandler(ctx) {
       }
     }
     try {
-      removeAppDevSession(sessionId, sessionsFilePath);
+      await devServer.close();
     } catch {
       // ignore cleanup failures during shutdown
     }
+    // Keep ownership records until every watcher group has stopped. If the
+    // Desktop must force this host down, the next launch can still recover a
+    // verified orphan instead of losing its only ownership proof.
     try {
-      await devServer.close();
+      removeAppDevSession(sessionId, sessionsFilePath);
     } catch {
       // ignore cleanup failures during shutdown
     }
@@ -2148,7 +2248,7 @@ async function appsPullHandler(ctx) {
       project_dir: pulled.projectDir,
       version: pulled.version,
     },
-    humanSummary: `Pulled ${versionLabel} to ${pulled.projectDir}. Run \`cd ${pulled.projectDir} && npm install && notis apps dev\` to start editing.`,
+    humanSummary: `Pulled ${versionLabel} to ${pulled.projectDir}. Increment package.json notisAppVersion above the pulled release, then run \`cd ${pulled.projectDir} && npm install && notis apps dev\` to substitute the online bundle.`,
   });
 }
 
@@ -2599,7 +2699,7 @@ export const appsCommandSpecs = [
     command_path: ['apps', 'dev'],
     summary: 'Register a development root and connect its apps to the shared local development host.',
     when_to_use:
-      'Run this once for any folder that should be watched permanently. The folder itself, direct child apps, and apps/* are discovered automatically by every signed-in Notis Desktop instance.',
+      'Run this once for any folder that should be watched permanently. The folder itself, direct child apps, and apps/* are discovered automatically by every signed-in Notis Desktop instance. A linked app substitutes its online bundle only when local notisAppVersion is strictly greater than the installed release.',
     args_schema: {
       arguments: [
         { token: '[dir]', key: 'dir', description: 'Project directory or monorepo root (default: current dir).' },
@@ -2775,7 +2875,7 @@ export const appsCommandSpecs = [
     command_path: ['apps', 'pull'],
     summary: 'Download a Notis app source snapshot into a local project folder.',
     when_to_use:
-      'Edit an installed app locally. Pulls the persisted source, links the directory to the app/version, then continue with npm install, notis apps dev, notis apps build, and notis apps deploy.',
+      'Edit an installed app locally. Preserve any local edits, pull and link the latest persisted source, then increment package.json notisAppVersion above that release before notis apps dev; continue with build and deploy.',
     args_schema: {
       arguments: [
         { token: '<app-id>', description: 'Remote app ID to pull.' },

package/src/runtime/app-dev-process-identity.js

@@ -0,0 +1,111 @@
+import { execFileSync } from 'node:child_process';
+import { readlinkSync, realpathSync } from 'node:fs';
+
+export const NOTIS_APP_BUILD_COMMAND_FINGERPRINT = 'npm:run-build:watch:v1';
+export const NOTIS_APPS_DEV_HOST_COMMAND_FINGERPRINT = 'notis:apps-dev:v1';
+
+function normalizePath(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  try {
+    return realpathSync(value.trim());
+  } catch {
+    return null;
+  }
+}
+
+export function isExpectedNotisBuildCommand(command) {
+  if (typeof command !== 'string') return false;
+  return /(?:^|[/\s])npm(?:\s|$)/.test(command)
+    && /\brun\s+build\b/.test(command)
+    && /(?:^|\s)--watch(?:\s|$)/.test(command);
+}
+
+export function isExpectedNotisAppsDevHostCommand(command) {
+  return typeof command === 'string'
+    && /(?:notis(?:\.js)?|@notis_ai[/\\]cli)/.test(command)
+    && /\bapps\s+dev\b/.test(command);
+}
+
+function readDarwinProcessCwd(pid, execute) {
+  const output = execute('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  const line = output.split('\n').find((entry) => entry.startsWith('n'));
+  return line ? line.slice(1) : null;
+}
+
+export function inspectAppDevWatcherProcess(pid, {
+  platform = process.platform,
+  execute = execFileSync,
+  readLink = readlinkSync,
+} = {}) {
+  if (!Number.isSafeInteger(pid) || pid <= 0 || platform === 'win32') return null;
+  try {
+    const ps = (field) => execute('ps', ['-o', `${field}=`, '-p', String(pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    const processGroupPid = Number.parseInt(ps('pgid'), 10);
+    const startIdentity = ps('lstart').replace(/\s+/g, ' ').trim();
+    const command = ps('command');
+    const cwd = platform === 'linux'
+      ? readLink(`/proc/${pid}/cwd`)
+      : readDarwinProcessCwd(pid, execute);
+    const projectDir = normalizePath(cwd);
+    if (!Number.isSafeInteger(processGroupPid) || processGroupPid <= 0) return null;
+    if (!startIdentity || !command || !projectDir) return null;
+    return { pid, processGroupPid, startIdentity, command, projectDir };
+  } catch {
+    return null;
+  }
+}
+
+export function captureDesktopWatcherOwnership({
+  pid,
+  projectDir,
+  desktopOwnerId,
+  desktopOwnerScope,
+  inspect = inspectAppDevWatcherProcess,
+} = {}) {
+  const owner = typeof desktopOwnerId === 'string' ? desktopOwnerId.trim() : '';
+  const ownerScope = typeof desktopOwnerScope === 'string' ? desktopOwnerScope.trim() : '';
+  const expectedProjectDir = normalizePath(projectDir);
+  if (!owner || !ownerScope || !expectedProjectDir) return null;
+  const identity = inspect(pid);
+  if (
+    !identity
+    || identity.processGroupPid !== pid
+    || identity.projectDir !== expectedProjectDir
+    || !isExpectedNotisBuildCommand(identity.command)
+  ) {
+    return null;
+  }
+  return {
+    desktopOwnerId: owner,
+    desktopOwnerScope: ownerScope,
+    watcherProcessGroupPid: identity.processGroupPid,
+    watcherStartIdentity: identity.startIdentity,
+    watcherProjectDir: identity.projectDir,
+    watcherCommandFingerprint: NOTIS_APP_BUILD_COMMAND_FINGERPRINT,
+  };
+}
+
+export function captureDesktopHostOwnership({
+  pid = process.pid,
+  desktopOwnerId,
+  desktopOwnerScope,
+  inspect = inspectAppDevWatcherProcess,
+} = {}) {
+  const owner = typeof desktopOwnerId === 'string' ? desktopOwnerId.trim() : '';
+  const ownerScope = typeof desktopOwnerScope === 'string' ? desktopOwnerScope.trim() : '';
+  if (!owner || !ownerScope) return null;
+  const identity = inspect(pid);
+  if (!identity || !isExpectedNotisAppsDevHostCommand(identity.command)) return null;
+  return {
+    desktopOwnerId: owner,
+    desktopOwnerScope: ownerScope,
+    desktopHostStartIdentity: identity.startIdentity,
+    desktopHostCommandFingerprint: NOTIS_APPS_DEV_HOST_COMMAND_FINGERPRINT,
+  };
+}