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

package/src/command-specs/onboarding.js

@@ -0,0 +1,216 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { CliError, EXIT_CODES } from '../runtime/errors.js';
+import { getDesktopAuthRecovery, waitForDesktopAuth } from '../runtime/desktop-auth.js';
+import { getJwt, isJwtExpired, loadConfig } from '../runtime/profiles.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_BRIEF_PATH = join(HERE, '..', '..', 'skills', 'notis-onboarding', 'BRIEF.md');
+
+/**
+ * The brief is served rather than bundled so it tracks the deployed server. The
+ * bundled copy is a fallback for an offline or unreachable API, and the payload
+ * says which one the caller got so a stale brief is diagnosable.
+ */
+async function fetchBrief(apiBase, timeoutMs) {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.min(timeoutMs || 30_000, 30_000));
+    try {
+      const response = await fetch(`${apiBase.replace(/\/$/, '')}/signup/onboarding-brief`, {
+        signal: controller.signal,
+      });
+      if (response.ok) {
+        const payload = await response.json();
+        if (payload?.markdown) {
+          return { markdown: payload.markdown, source: 'server' };
+        }
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    // fall through to the bundled copy
+  }
+
+  try {
+    return { markdown: readFileSync(BUNDLED_BRIEF_PATH, 'utf-8'), source: 'bundled' };
+  } catch {
+    return { markdown: null, source: null };
+  }
+}
+
+async function requestSignupLink(apiBase, { email, useCases }) {
+  const response = await fetch(`${apiBase.replace(/\/$/, '')}/signup/agent`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      email,
+      ...(useCases && useCases.length ? { preferred_use_cases: useCases } : {}),
+    }),
+  });
+  const payload = await response.json().catch(() => null);
+
+  if (response.status === 429) {
+    // Requesting another link invalidates the previous one, so retrying is
+    // actively harmful. Surface the cooldown and stop.
+    throw new CliError({
+      code: 'signup_throttled',
+      message: payload?.message || 'A sign-in link was just sent to this address.',
+      exitCode: EXIT_CODES.usage,
+      details: payload || {},
+      hints: [
+        {
+          command: 'Open the newest Notis email on this machine',
+          reason: 'Requesting another link makes earlier links stop working',
+        },
+      ],
+    });
+  }
+
+  if (!response.ok) {
+    throw new CliError({
+      code: 'signup_failed',
+      message: payload?.message || `Signup failed with status ${response.status}`,
+      exitCode: EXIT_CODES.backend,
+      details: payload || {},
+    });
+  }
+
+  return payload || {};
+}
+
+async function startHandler(ctx) {
+  const { runtime, options, output } = ctx;
+  const apiBase = runtime.apiBase;
+  const authenticated = Boolean(runtime.jwt) && !isJwtExpired(runtime.jwt);
+
+  // Safe to re-run: an already-authenticated machine skips straight to the brief.
+  // Agents retry commands, and a second signup would invalidate the first email.
+  if (authenticated || options.briefOnly) {
+    if (!authenticated) {
+      const recovery = getDesktopAuthRecovery(runtime, { mode: 'missing' });
+      throw new CliError({
+        code: 'auth_missing',
+        message: 'This machine is not signed in to Notis yet.',
+        exitCode: EXIT_CODES.auth,
+        hints: recovery.hints,
+      });
+    }
+    const brief = await fetchBrief(apiBase, runtime.timeoutMs);
+    return output.emitSuccess({
+      command: 'start',
+      data: { authenticated: true, brief: brief.markdown, brief_source: brief.source },
+      humanSummary: 'Notis CLI is authenticated on this machine.',
+      renderHuman: () => brief.markdown || 'Notis CLI is authenticated.',
+    });
+  }
+
+  if (!options.email) {
+    // The one point in the flow that has to stop and talk to the human.
+    throw new CliError({
+      code: 'signup_email_required',
+      message: 'An email address is required to create or access a Notis account.',
+      exitCode: EXIT_CODES.usage,
+      hints: [
+        {
+          command: 'Ask the user for their email address, then rerun with --email <address>',
+          reason: 'Notis sends a sign-in link there to prove they own the address',
+        },
+      ],
+    });
+  }
+
+  const signup = await requestSignupLink(apiBase, {
+    email: options.email,
+    useCases: options.useCase,
+  });
+
+  // Commander stores the negatable `--no-wait` flag as `options.wait === false`
+  // and never sets `options.noWait` — the same footgun already fixed for
+  // `--no-open` in apps.js. Reading `noWait` made the flag a no-op, so an agent
+  // that asked not to wait blocked for the full timeout instead.
+  if (options.wait === false) {
+    return output.emitSuccess({
+      command: 'start',
+      data: { authenticated: false, next_action: 'open_email_link', ...signup },
+      humanSummary: `A sign-in link is on its way to ${options.email}.`,
+    });
+  }
+
+  const timeoutMs = Number(options.waitTimeoutMs) > 0 ? Number(options.waitTimeoutMs) : 300_000;
+  const jwt = await waitForDesktopAuth({
+    loadConfig,
+    getJwt,
+    isJwtExpired,
+    profileName: runtime.profileName,
+    timeoutMs,
+    onTick: (remaining) => {
+      if (runtime.outputMode !== 'json' && remaining % 15_000 < 2_000) {
+        output.note?.(`Waiting for Notis Desktop to sign in (${Math.round(remaining / 1000)}s left)...`);
+      }
+    },
+  });
+
+  if (!jwt) {
+    throw new CliError({
+      code: 'auth_timeout',
+      message: 'Timed out waiting for Notis Desktop to authenticate the CLI.',
+      exitCode: EXIT_CODES.auth,
+      details: { desktop_download_url: signup.desktop_download_url || null },
+      hints: [
+        {
+          command: `Install Notis Desktop: ${signup.desktop_download_url || 'https://notis.ai/channels/desktop-app'}`,
+          reason: 'The desktop app is what writes the CLI credential',
+        },
+        { command: 'notis start --brief-only', reason: 'Resume once the desktop app is signed in' },
+        { command: 'notis doctor', reason: 'Re-check config, auth, and API reachability' },
+      ],
+    });
+  }
+
+  const brief = await fetchBrief(apiBase, runtime.timeoutMs);
+  return output.emitSuccess({
+    command: 'start',
+    data: { authenticated: true, brief: brief.markdown, brief_source: brief.source },
+    humanSummary: 'Notis CLI is authenticated. Follow the onboarding brief below.',
+    renderHuman: () => brief.markdown || 'Notis CLI is authenticated.',
+  });
+}
+
+export const onboardingCommandSpecs = [
+  {
+    command_path: ['start'],
+    summary: 'Create or access a Notis account and wait for the desktop app to sign the CLI in.',
+    when_to_use:
+      'Run this first on a new machine, before anything that needs auth. Safe to re-run: an already-signed-in machine just reprints the onboarding brief.',
+    args_schema: {
+      arguments: [],
+      options: [
+        { flags: '--email <email>', description: 'Email to create or sign in the Notis account with.' },
+        { flags: '--use-case <slug>', description: 'Primary use case (repeatable).', collect: true },
+        {
+          flags: '--wait-timeout-ms <n>',
+          description: 'How long to wait for the desktop sign-in (default 300000).',
+        },
+        { flags: '--no-wait', description: 'Send the link and exit without waiting.' },
+        { flags: '--brief-only', description: 'Print the onboarding brief for an already-signed-in profile.' },
+      ],
+    },
+    examples: [
+      'notis start --email you@example.com',
+      'notis start --brief-only',
+      'notis start --email you@example.com --json',
+    ],
+    output_schema:
+      'Returns {authenticated, brief, brief_source} once signed in, or {next_action, cooldown_seconds, desktop_download_url} while waiting.',
+    mutates: true,
+    idempotent: true,
+    require_auth: false,
+    related_commands: ['notis doctor', 'notis tools link'],
+    backend_call: { type: 'http', name: 'POST /signup/agent' },
+    handler: startHandler,
+  },
+];

package/src/command-specs/tools.js

@@ -453,8 +453,12 @@ async function toolsExecHandler(ctx) {
     arguments_: {
       tools: [{ tool_slug: requestedToolName, arguments: args }],
     },
-    mutating: targetMutating !== false,
-    idempotencyKey: targetMutating === false ? null : idempotencyKey,
+    // The server is authoritative about provider/MCP effects. A tool name that
+    // looks like a read is not proof of read-only behavior, so generic
+    // executions always carry a key and use mutation-safe transport retries.
+    // Proven reads are still executed in the read lane by hosted MCP.
+    mutating: true,
+    idempotencyKey,
     fileBindings,
   });
   ctx.output.emitProgress({
@@ -470,8 +474,8 @@ async function toolsExecHandler(ctx) {
     requestId: result.requestId,
     meta: {
       mutating: targetMutating,
-      mutation_classification: targetMutating === null ? 'unknown' : 'inferred',
-      idempotency_key: targetMutating === false ? null : idempotencyKey,
+      mutation_classification: targetMutating === null ? 'unknown' : 'name_hint_only',
+      idempotency_key: idempotencyKey,
     },
     renderHuman: () => JSON.stringify(result.payload, null, 2),
   });

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/app-platform.js

@@ -231,7 +231,13 @@ export function detectProjectWarnings(projectDir, appConfig = null) {
     warnings.push('Missing Tailwind config.');
   }
 
-  if (appConfig && (!Array.isArray(appConfig.databases) || appConfig.databases.length === 0)) {
+  const readsWorkspaceDatabases =
+    appConfig?.capabilities?.workspaceDatabases === 'read';
+  if (
+    appConfig
+    && !readsWorkspaceDatabases
+    && (!Array.isArray(appConfig.databases) || appConfig.databases.length === 0)
+  ) {
     warnings.push('No database references declared in notis.config.ts.');
   }
 
@@ -490,13 +496,24 @@ export async function runProjectScript({ projectDir, scriptName, env = {}, stdio
       stdio,
       env: { ...process.env, ...env },
     });
+    let capturedOutput = '';
+    for (const stream of [child.stdout, child.stderr]) {
+      stream?.on('data', (chunk) => {
+        capturedOutput += chunk.toString();
+      });
+    }
     child.on('error', rejectPromise);
     child.on('exit', (code) => {
       if (code === 0) {
         resolvePromise();
         return;
       }
-      rejectPromise(new Error(`npm run ${scriptName} failed with exit code ${code}`));
+      const detail = capturedOutput.trim();
+      rejectPromise(
+        new Error(
+          `npm run ${scriptName} failed with exit code ${code}${detail ? `:\n${detail}` : ''}`,
+        ),
+      );
     });
   });
 }
@@ -707,7 +724,14 @@ export function generateManifest(appConfig, projectDir) {
     return entry;
   });
 
-  const databases = appConfig.databases || [];
+  // Database entries may be a bare slug (structure only) or an object opting
+  // into shipping rows to installers. Normalize to the manifest's snake_case.
+  const databases = (appConfig.databases || []).map((entry) => {
+    if (typeof entry === 'string') return entry;
+    if (!entry || typeof entry !== 'object' || !entry.slug) return entry;
+    const seedDocuments = entry.seedDocuments ?? entry.seed_documents;
+    return seedDocuments === true ? { slug: entry.slug, seed_documents: true } : entry.slug;
+  });
   const categories = normalizeCategories(appConfig.categories || []);
   const metadata = { screenshots: resolveListingScreenshots(projectDir, appConfig) };
   const appSlug = safeKebab(appConfig.name);
@@ -786,12 +810,29 @@ export function generateManifest(appConfig, projectDir) {
       css: 'bundle/app.css',
     },
     databases,
+    capabilities: normalizeAppCapabilities(appConfig.capabilities),
     tools: appConfig.tools || [],
     skills,
     onboarding: appConfig.onboarding || null,
   };
 }
 
+/**
+ * Keeps only capabilities the platform actually understands, at the exact
+ * values it accepts. An unknown key or value is dropped rather than passed
+ * through, so a typo can never reach the server as a permission grant.
+ */
+export function normalizeAppCapabilities(capabilities) {
+  if (!capabilities || typeof capabilities !== 'object') {
+    return {};
+  }
+  const normalized = {};
+  if (capabilities.workspaceDatabases === 'read') {
+    normalized.workspaceDatabases = 'read';
+  }
+  return normalized;
+}
+
 export function resolveConfiguredAppSkills(appConfig, projectDir) {
   const configured = Array.isArray(appConfig.skills) ? appConfig.skills : [];
   const projectRoot = resolve(projectDir);
@@ -831,13 +872,14 @@ export function resolveConfiguredAppSkills(appConfig, projectDir) {
 /**
  * Build the app bundle: generate entry file, run `vite build`, package into .notis/output/.
  */
-export async function buildArtifact(projectDir) {
+export async function buildArtifact(projectDir, { stdio = 'inherit' } = {}) {
   await prepareArtifactBuild(projectDir);
 
   // Run Vite build
   await runProjectScript({
     projectDir,
     scriptName: 'build',
+    stdio,
   });
 
   // Verify the canonical `.notis/output/bundle` packaging contract.
@@ -948,8 +990,13 @@ export function scaffoldProject({ projectDir, appName, fromSlug = null }) {
   if (existsSync(pkgPath)) {
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
     pkg.name = appName.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-');
+    // A scaffold creates a new app identity, even when its source comes from a
+    // versioned Store example. New apps must therefore start their own release
+    // history instead of inheriting the example app's registry version.
+    pkg.notisAppVersion = '0.1.0';
     ensureScaffoldLocalSdk(projectDir, pkg);
     writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    normalizeScaffoldLockfile(projectDir, pkg);
   }
 
   // Update notis.config.ts with the app name
@@ -983,6 +1030,20 @@ export function scaffoldProject({ projectDir, appName, fromSlug = null }) {
   return { projectDir };
 }
 
+function normalizeScaffoldLockfile(projectDir, pkg) {
+  const lockPath = join(projectDir, 'package-lock.json');
+  if (!existsSync(lockPath)) {
+    return;
+  }
+
+  const lockfile = JSON.parse(readFileSync(lockPath, 'utf-8'));
+  lockfile.name = pkg.name;
+  if (lockfile.packages?.['']) {
+    lockfile.packages[''].name = pkg.name;
+  }
+  writeFileSync(lockPath, JSON.stringify(lockfile, null, 2) + '\n');
+}
+
 function ensureScaffoldLocalSdk(projectDir, pkg) {
   let shouldInstallLocalSdk = false;
   for (const dependencyGroup of ['dependencies', 'devDependencies']) {

package/src/runtime/desktop-auth.js

@@ -24,7 +24,15 @@ function defaultDesktopAppName(apiBase) {
   }
 }
 
-export function getDesktopAuthRecovery(runtime) {
+/**
+ * Recovery hints for an unusable desktop-managed credential.
+ *
+ * `mode` distinguishes the two cases an agent has to act on differently:
+ * "expired" means a session existed and the desktop app can renew it, while
+ * "missing" means this machine was never signed in — telling that caller to
+ * renew something is misleading.
+ */
+export function getDesktopAuthRecovery(runtime, { mode = 'expired' } = {}) {
   const desktopRunning = isPidRunning(runtime.desktopPid);
   const appName = runtime.desktopAppName || defaultDesktopAppName(runtime.apiBase);
   let command = 'Start the Notis desktop app';
@@ -32,22 +40,63 @@ export function getDesktopAuthRecovery(runtime) {
     command = `open -a ${quoteShellArgument(appName)}`;
   }
 
-  return {
-    desktopRunning,
-    appName,
-    hints: [
-      {
-        command,
-        reason: desktopRunning
-          ? `Bring ${appName} forward so it can renew CLI authentication, then retry`
-          : `Start ${appName} to renew expired CLI authentication, then retry`,
-      },
-      {
-        command: 'notis doctor',
-        reason: 'Retry the auth and API checks after the desktop app is ready',
-      },
-    ],
-  };
+  let reason;
+  if (mode === 'missing') {
+    reason = desktopRunning
+      ? `Sign in to ${appName} to authenticate the CLI on this machine, then retry`
+      : `Install and sign in to ${appName} to authenticate the CLI on this machine, then retry`;
+  } else {
+    reason = desktopRunning
+      ? `Bring ${appName} forward so it can renew CLI authentication, then retry`
+      : `Start ${appName} to renew expired CLI authentication, then retry`;
+  }
+
+  const hints = [{ command, reason }];
+  if (mode === 'missing') {
+    // Leads the list: a machine that was never signed in may not even have an
+    // account yet, and `notis start` covers both cases.
+    hints.unshift({
+      command: 'notis start --email <address>',
+      reason: 'Create or access a Notis account and sign this machine in',
+    });
+  }
+  hints.push({
+    command: 'notis doctor',
+    reason: 'Retry the auth and API checks after the desktop app is ready',
+  });
+
+  return { desktopRunning, appName, hints };
+}
+
+/**
+ * Block until the desktop app writes an unexpired JWT into the CLI profile.
+ *
+ * Polls the local config file only — never the server. The desktop app is what
+ * mints the credential, and `transport.js` re-reads the profile before every
+ * request, so this loop exists purely so the caller's process can wait rather
+ * than fail and make the user re-run the command.
+ */
+export async function waitForDesktopAuth({
+  loadConfig,
+  getJwt,
+  isJwtExpired,
+  profileName = 'default',
+  timeoutMs = 300_000,
+  intervalMs = 2_000,
+  onTick,
+} = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const jwt = getJwt(loadConfig(), profileName);
+    if (jwt && !isJwtExpired(jwt)) {
+      return jwt;
+    }
+    if (Date.now() >= deadline) {
+      return null;
+    }
+    if (onTick) onTick(Math.max(0, deadline - Date.now()));
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
 }
 
 export function createExpiredAuthError(runtime) {

package/src/runtime/errors.js

@@ -6,6 +6,7 @@ export const EXIT_CODES = {
   conflict: 5,
   backend: 6,
   unexpected: 7,
+  payment: 8,
 };
 
 export class CliError extends Error {

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,
   };
@@ -187,7 +197,15 @@ export function loadConfig(runtime = null) {
     return normalizeConfig({});
   }
 
-  return normalizeConfig(JSON.parse(readFileSync(configFile, 'utf-8')));
+  // The desktop app rewrites this file while the CLI may be reading it, so a
+  // torn or corrupt read is expected rather than exceptional. Degrade to
+  // "unauthenticated", which surfaces the actionable auth_missing error instead
+  // of a raw SyntaxError from deep inside the runtime.
+  try {
+    return normalizeConfig(JSON.parse(readFileSync(configFile, 'utf-8')));
+  } catch {
+    return normalizeConfig({});
+  }
 }
 
 export function saveConfig(config, runtime = null) {
@@ -361,11 +379,14 @@ export function resolveRuntimeProfile(
     : null;
 
   if (requireAuth && !jwt) {
-    const recovery = getDesktopAuthRecovery({
-      apiBase,
-      desktopAppName: profile.desktop_app_name,
-      desktopPid: profile.desktop_pid,
-    });
+    const recovery = getDesktopAuthRecovery(
+      {
+        apiBase,
+        desktopAppName: profile.desktop_app_name,
+        desktopPid: profile.desktop_pid,
+      },
+      { mode: 'missing' },
+    );
     throw new CliError({
       code: 'auth_missing',
       message: `No JWT configured for profile ${profileName}`,