@notis_ai/cli 0.2.0-beta.76.1 → 0.2.0-beta.95.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notis_ai/cli",
-  "version": "0.2.0-beta.76.1",
+  "version": "0.2.0-beta.95.1",
   "description": "Agent-first Notis CLI for apps and generic tool execution",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
     "prepack": "npm run build",
     "release:prepare": "npm run build && node ./scripts/prepare-publish.js --apply",
     "cli:set-mode": "node ./scripts/set-cli-mode.js",
+    "smoke": "node ./scripts/smoke-package.js",
     "test": "node --test"
   },
   "engines": {

package/skills/notis-apps/SKILL.md

@@ -26,6 +26,7 @@ Use the Notis CLI for the app lifecycle:
 npx --package @notis_ai/cli@latest -- notis apps init
 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 screenshot
 npx --package @notis_ai/cli@latest -- notis apps verify
 npx --package @notis_ai/cli@latest -- notis apps create
 npx --package @notis_ai/cli@latest -- notis apps link
@@ -50,6 +51,8 @@ npx --package @notis_ai/cli@latest -- notis apps ...
 - Use `@notis/sdk` hooks instead of direct runtime access.
 - Do not rely on `window.__NOTIS_RUNTIME__` or portal-owned DOM hooks.
 - `npx --package @notis_ai/cli@latest -- notis apps deploy` updates an installed app. It does not publish to the public App Store.
+- **Local development first; deploy is user-gated.** Iterate with `apps dev` and hand off for the **user** to test in the desktop **Local development** sidebar group. Do not run `apps create` / `apps deploy` on your own — a clean build/verify is not permission to deploy. Deploy only when the user has tested the local build and explicitly asks. Finishing a build without deploying is the expected outcome.
+- **Installed app links are explicit.** A mounted dev session updates an installed app only when the checkout is linked by app id in `.notis/state.json` and the active dev-session registry mirrors that id. Name or slug matches may be suggestions, never update targets.
 - Public or team App Store publishing is a Portal review flow.
 - Use Phosphor icon names with the `phosphor:` prefix. Do not use emoji icons.
 - Prefer scaffolded shadcn components and portal theme tokens over custom visual systems.
@@ -70,21 +73,30 @@ npx --package @notis_ai/cli@latest -- notis apps init "My App"
 npx --package @notis_ai/cli@latest -- notis apps pull <app-id> ./my-app
 ```
 
-3. Install dependencies and develop:
+3. Install dependencies and develop. Keep `apps dev` running and **hand off to the user** — it is what surfaces the app in the desktop **Local development** sidebar group, and letting the user test there is the finish line for a build request:
 
 ```bash
 npm install
 npx --package @notis_ai/cli@latest -- notis apps dev
 ```
 
-4. Build and verify:
+The desktop lists a dev app only if its session is in the per-workspace registry it polls: `<workspace>/.context/app-dev-sessions.json`. A current CLI auto-resolves the nearest `.context` registry; on older CLIs (or when launched outside the workspace), pass `NOTIS_APP_DEV_SESSIONS_FILE="$CONDUCTOR_WORKSPACE_PATH/.context/app-dev-sessions.json"`. After starting, confirm your app's `devSlug` is in that file with a fresh `lastHeartbeatAt` — if it isn't, the session landed in the global `~/.notis` registry and the app won't appear in the sidebar.
+
+4. Build, capture listing screenshots, and verify (still local — this does not deploy):
 
 ```bash
 npx --package @notis_ai/cli@latest -- notis apps build
+npx --package @notis_ai/cli@latest -- notis apps screenshot
 npx --package @notis_ai/cli@latest -- notis apps verify
 ```
 
-5. Create or link the remote app, then deploy:
+`notis apps screenshot` renders each route in a headless harness and writes
+`metadata/screenshot-N.png` (2000x1250, 16:10). Apps are icon-led like Raycast:
+the app icon represents the app everywhere, so there is no cover image — only
+these screenshots. Re-run after changing routes or UI; it overwrites the set and
+drops stale files. Use `--routes home,history` to capture a subset.
+
+5. **Only after the user has tested the local build and explicitly asks to deploy**, create or link the remote app, then deploy (this installs or updates the app on the user's account, where it appears under **Workspace** rather than Local development). After first install, keep `.notis/state.json` linked to that installed app id so future dev-session actions become **Update** instead of another **Install**:
 
 ```bash
 npx --package @notis_ai/cli@latest -- notis apps create "My App" .
@@ -107,17 +119,24 @@ notis.config.ts
 vite.config.ts
 app/
 components/
-metadata/
+metadata/          # screenshot-N.png only — generated by `notis apps screenshot`
 .notis/output/
 ```
 
+`metadata/` holds listing screenshots (`screenshot-1.png`, `screenshot-2.png`,
+…). There is no `cover.png`: apps are icon-led like Raycast and the icon set in
+`notis.config.ts` represents the app in the Store. Generate screenshots with
+`notis apps screenshot` rather than authoring PNGs by hand.
+
 `notis.config.ts` owns:
 
-- app metadata: name, title, description, icon, categories, tagline
+- app metadata: name, title, description, icon, accent, categories, tagline
 - database slug references
 - route definitions
 - tool access
 
+**Icon & accent.** Set `icon` to a `phosphor:<name>` value (e.g. `phosphor:dice-five`) or `metadata/icon.png`. When `icon` is 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`; when unset a stable color is derived automatically from the app id. Both flow from `notis.config.ts` through deploy onto the app row and listing, and can also be changed later with the `update_app` tool (`{ "icon": "phosphor:...", "accent": "emerald" }`).
+
 Example:
 
 ```ts
@@ -128,6 +147,7 @@ export default defineNotisApp({
   title: 'My App',
   description: 'A focused Notis app.',
   icon: 'phosphor:squares-four',
+  accent: 'blue',
   databases: ['tasks'],
   routes: [
     {

package/skills/notis-apps/cli.md

@@ -155,6 +155,26 @@ Examples:
 - `npx --package @notis_ai/cli@latest -- notis apps verify --mode live`
 - `npx --package @notis_ai/cli@latest -- notis apps verify --no-browser  # start the harness, drive agent-browser yourself`
 
+### `npx --package @notis_ai/cli@latest -- notis apps screenshot [dir]`
+
+Capture listing screenshots of each route via the headless harness.
+
+When to use: Generate metadata/screenshot-N.png for the App Store listing. Apps are icon-led (like Raycast) — there is no cover image, only these screenshots. Run before notis apps verify / deploy / publish.
+
+Options:
+- `--routes <slugs>` — Comma-separated route slugs. Default: every route in manifest.
+- `--port <n>` — Loopback port. Default: auto-pick.
+- `--width <px>` — Viewport width. Default: 2000.
+- `--height <px>` — Viewport height. Default: 1250 (16:10).
+- `--output-dir <dir>` — Where to write screenshot-N.png. Default: metadata/.
+- `--mode <mode>` — stub | live. Default stub. Live renders against real data via the CLI JWT (requires a linked app), so screenshots show actual content instead of empty states.
+- `--skip-build` — Skip notis apps build; reuse existing .notis/output/.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps screenshot`
+- `npx --package @notis_ai/cli@latest -- notis apps screenshot --routes home,history`
+- `npx --package @notis_ai/cli@latest -- notis apps screenshot --mode live  # populated screenshots from real data`
+
 ### `npx --package @notis_ai/cli@latest -- notis apps link <app-id> [dir]`
 
 Link a local project to a remote Notis app.

package/src/cli.js

@@ -1,10 +1,29 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { COMMAND_SPECS, GROUP_SUMMARIES } from './command-specs/index.js';
 import { OutputManager } from './runtime/output.js';
 import { asCliError } from './runtime/errors.js';
 import { resolveRuntimeProfile, workspacePath } from './runtime/profiles.js';
 
-const CLI_VERSION = '0.2.0';
+// Read the version from package.json: the publish pipeline bumps the manifest
+// (scripts/release-utils.js applyVersion), so a hardcoded string here goes
+// stale on every release.
+function readCliVersion() {
+  try {
+    const manifestPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    const version = JSON.parse(readFileSync(manifestPath, 'utf-8')).version;
+    if (typeof version === 'string' && version.trim()) {
+      return version.trim();
+    }
+  } catch {
+    // Fall through to the placeholder below.
+  }
+  return '0.0.0';
+}
+
+const CLI_VERSION = readCliVersion();
 
 function buildHelpFooter(spec) {
   const lines = [

package/src/command-specs/apps.js

@@ -9,8 +9,8 @@
 
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { existsSync, readdirSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
 
 import { EXIT_CODES, usageError } from '../runtime/errors.js';
 import { formatTable } from '../runtime/output.js';
@@ -34,6 +34,7 @@ import {
 } from '../runtime/app-platform.js';
 import { startAppDevServer } from '../runtime/app-dev-server.js';
 import {
+  captureHarnessScreenshot,
   closeAgentBrowserSession,
   isAgentBrowserAvailable,
   runHarnessRoute,
@@ -236,6 +237,15 @@ function parsePort(value) {
   return port;
 }
 
+function parsePositiveInt(value) {
+  if (!value) return null;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw usageError('Expected a positive integer.');
+  }
+  return parsed;
+}
+
 function parseRouteSlugs(value) {
   if (!value) return null;
   const slugs = String(value)
@@ -277,6 +287,36 @@ function routeSelection(manifest, rawRouteSlugs) {
   return selected;
 }
 
+export function pruneStaleScreenshotFiles(outputDir, keepCount) {
+  for (const entry of readdirSync(outputDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const match = /^screenshot-(\d+)\.png$/i.exec(entry.name);
+    if (match && Number.parseInt(match[1], 10) > keepCount) {
+      rmSync(join(outputDir, entry.name), { force: true });
+    }
+  }
+}
+
+export function shouldPruneStaleScreenshotFiles(selectedRouteSlugs, failedCount) {
+  return failedCount === 0 && !selectedRouteSlugs;
+}
+
+export function screenshotIndexByRouteSlug(manifest) {
+  const routes = Array.isArray(manifest?.routes) ? manifest.routes : [];
+  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;
+}
+
 function declaredDatabaseSlugs(appConfig, manifest, route) {
   const slugs = new Set();
   for (const entry of appConfig?.databases || manifest?.databases || []) {
@@ -427,7 +467,19 @@ export async function ensureDevInstall({
   }
 
   const manifest = buildManifestForDev(appConfig);
-  const linkedState = readLinkedState(projectDir);
+  let linkedState = readLinkedState(projectDir);
+  if (linkedState?.app_id) {
+    const linkedApp = await assertDirectDeployAccess(ctx.runtime, linkedState.app_id, runTool);
+    if (!linkedState.dev_app_id && linkedApp?.manifest?.is_dev === true) {
+      const { app_id: legacyDevAppId, linked_at: _linkedAt, deployed_at: _deployedAt, version: _version, ...rest } = linkedState;
+      linkedState = {
+        ...rest,
+        dev_app_id: legacyDevAppId,
+        dev_linked_at: linkedState.dev_linked_at || linkedState.linked_at || new Date().toISOString(),
+      };
+      writeLinkedState(projectDir, linkedState);
+    }
+  }
   const ensureArguments = buildEnsureDevInstallArguments({ appConfig, manifest, linkedState });
   const ensureResult = await runTool({
     runtime: ctx.runtime,
@@ -440,6 +492,14 @@ export async function ensureDevInstall({
   if (!appId) {
     throw usageError('Dev installation tool did not return an app_id.');
   }
+  if (linkedState?.dev_app_id !== appId) {
+    const now = new Date().toISOString();
+    writeLinkedState(projectDir, {
+      ...(linkedState || {}),
+      dev_app_id: appId,
+      dev_linked_at: linkedState?.dev_linked_at || now,
+    });
+  }
   return {
     slug: ensureResult.payload.slug || devSlug,
     devSlug,
@@ -449,6 +509,7 @@ export async function ensureDevInstall({
     manifest,
     created: ensureResult.payload.created || false,
     linkedAppId: linkedState?.app_id || null,
+    targetAppId: linkedState?.app_id || null,
     databaseMaterialization: ensureResult.payload.database_materialization || { created: [], unresolved: [] },
   };
 }
@@ -468,16 +529,17 @@ function databaseMaterializationWarnings(apps) {
   return warnings;
 }
 
-async function assertDirectDeployAccess(runtime, appId) {
-  const result = await runToolCommand({
+async function assertDirectDeployAccess(runtime, appId, runTool = runToolCommand) {
+  const result = await runTool({
     runtime,
     toolName: LIST_APPS_TOOL,
   });
   const apps = result.payload.apps || [];
-  const hasAccess = apps.some((app) => (app.app_id || app.id) === appId);
-  if (!hasAccess) {
+  const app = apps.find((candidate) => (candidate.app_id || candidate.id) === appId) || null;
+  if (!app) {
     throw usageError(`Direct deploy requires access to app ${appId}.`);
   }
+  return app;
 }
 
 // ---------------------------------------------------------------------------
@@ -540,6 +602,7 @@ async function appsCreateHandler(ctx) {
       name: ctx.args.name,
       description: appConfig?.description || undefined,
       icon: appConfig?.icon || undefined,
+      accent: appConfig?.accent ?? undefined,
     },
     mutating: true,
     idempotencyKey,
@@ -669,6 +732,7 @@ async function appsDevHandler(ctx) {
       slug: app.devSlug,
       projectDir: app.projectDir,
       appId: app.appId,
+      targetAppId: app.targetAppId || null,
       userId: identity,
     })),
     port,
@@ -681,6 +745,7 @@ async function appsDevHandler(ctx) {
       userId: identity,
       apiBase,
       appId: app.appId,
+      targetAppId: app.targetAppId || undefined,
       devSlug: app.devSlug,
       bundleBaseUrl: app.bundleBaseUrl,
       projectDir: app.projectDir,
@@ -716,6 +781,7 @@ async function appsDevHandler(ctx) {
       apps: apps.map((app) => ({
         slug: app.devSlug,
         app_id: app.appId,
+        target_app_id: app.targetAppId,
         name: app.name,
         project_dir: app.projectDir,
         bundle_base_url: app.bundleBaseUrl,
@@ -999,6 +1065,149 @@ async function appsVerifyHandler(ctx) {
   }
 }
 
+async function appsScreenshotHandler(ctx) {
+  const projectDir = resolveProjectDir(ctx.args.dir || '.');
+  const problems = detectProjectProblems(projectDir);
+  if (problems.length) {
+    throw usageError(`Project has problems:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+  }
+
+  if (!isAgentBrowserAvailable()) {
+    throw usageError('agent-browser is not available on PATH. It ships with the Notis desktop app; open it once, then retry.');
+  }
+
+  const mode = ctx.options.mode || 'stub';
+  if (!['stub', 'live'].includes(mode)) {
+    throw usageError('--mode must be either "stub" or "live".');
+  }
+
+  let linkedState = null;
+  if (mode === 'live') {
+    if (!ctx.runtime.jwt) {
+      throw usageError('Live mode requires CLI auth. Open the Notis desktop app, sign in, and retry.');
+    }
+    linkedState = readLinkedState(projectDir);
+    if (!linkedState?.app_id) {
+      throw usageError('Live mode requires a linked app. Run `notis apps link <app-id> .` first.');
+    }
+  }
+
+  if (!ctx.options.skipBuild) {
+    await buildArtifact(projectDir);
+  }
+
+  const manifest = readManifest(projectDir);
+  const appConfig = await loadAppConfig(projectDir);
+  const selectedRouteSlugs = parseRouteSlugs(ctx.options.routes);
+  const routes = routeSelection(manifest, selectedRouteSlugs);
+  const screenshotSlots = screenshotIndexByRouteSlug(manifest);
+  if (!routes.length) {
+    throw usageError('No routes to screenshot.');
+  }
+
+  const width = parsePositiveInt(ctx.options.width) || 2000;
+  const height = parsePositiveInt(ctx.options.height) || 1250;
+  const outputDir = ctx.options.outputDir
+    ? resolveProjectDir(ctx.options.outputDir)
+    : join(projectDir, 'metadata');
+
+  const port = parsePort(ctx.options.port) || await getAvailablePort();
+  const appSlug = slugify(appConfig.name || manifest.app?.name || 'app') || 'app';
+  const baseUrl = `http://127.0.0.1:${port}/a/${appSlug}`;
+  const browserSessionName = `notis-screenshot-${process.pid}`;
+  let devServer = null;
+  let browserTouched = false;
+
+  try {
+    devServer = await startAppDevServer({
+      apps: [{ slug: appSlug, projectDir, appId: linkedState?.app_id || 'harness-app' }],
+      port,
+      watch: false,
+      harness: {
+        mode,
+        apiBase: ctx.runtime.apiBase,
+        jwt: mode === 'live' ? ctx.runtime.jwt : null,
+      },
+      log: () => {},
+      logError: (message) => process.stderr.write(`${message}\n`),
+    });
+    browserTouched = true;
+
+    mkdirSync(outputDir, { recursive: true });
+    const results = [];
+    let index = 0;
+    for (const route of routes) {
+      index += 1;
+      const slotIndex = screenshotSlots.get(route.slug) || index;
+      const fileName = `screenshot-${slotIndex}.png`;
+      const screenshotPath = join(outputDir, fileName);
+      const result = await captureHarnessScreenshot({
+        url: `${baseUrl}/harness?route=${encodeURIComponent(route.slug)}`,
+        sessionName: browserSessionName,
+        screenshotPath,
+        width,
+        height,
+        timeoutMs: Number.parseInt(ctx.globalOptions.timeoutMs || '', 10) || 15_000,
+      });
+      results.push({
+        route: route.slug,
+        path: route.path,
+        file: relative(projectDir, screenshotPath),
+        ok: result.ok,
+        errors: result.errors || [],
+        timed_out: Boolean(result.timed_out),
+        tool_error: result.tool_error,
+      });
+    }
+
+    const captured = results.filter((r) => r.ok);
+    const failed = results.filter((r) => !r.ok);
+    const warnings = [];
+
+    // Drop stale screenshots only after a full refresh. A selected-route
+    // capture intentionally leaves other listing screenshots untouched.
+    if (shouldPruneStaleScreenshotFiles(selectedRouteSlugs, failed.length)) {
+      pruneStaleScreenshotFiles(outputDir, routes.length);
+    }
+    if (failed.length) {
+      warnings.push(`${failed.length}/${results.length} routes failed to capture; see results.`);
+    }
+
+    ctx.output.emitSuccess({
+      ok: failed.length === 0,
+      command: ctx.spec.command_path.join(' '),
+      data: {
+        project_dir: projectDir,
+        output_dir: outputDir,
+        mode,
+        viewport: { width, height },
+        summary: { total: results.length, captured: captured.length, failed: failed.length },
+        results,
+      },
+      humanSummary: failed.length === 0
+        ? `Captured ${captured.length} screenshot(s) to ${relative(projectDir, outputDir) || 'metadata'}/.`
+        : `Captured ${captured.length}/${results.length} screenshots; ${failed.length} failed.`,
+      warnings,
+    });
+    return screenshotExitCode(failed.length);
+  } finally {
+    if (browserTouched) {
+      try {
+        await closeAgentBrowserSession(browserSessionName);
+      } catch {
+        // Ignore browser cleanup failures.
+      }
+    }
+    if (devServer) {
+      try {
+        await devServer.close();
+      } catch {
+        // Ignore server cleanup failures.
+      }
+    }
+  }
+}
+
 async function appsLinkHandler(ctx) {
   const projectDir = resolveProjectDir(ctx.args.dir || '.');
   const appId = ctx.args.appId;
@@ -1106,6 +1315,7 @@ async function appsDeployHandler(ctx) {
         files,
         source_files: sourceFiles,
         manifest,
+        ...appRowFieldsFromManifest(manifest),
         ...(baseVersion !== undefined ? { base_version: baseVersion } : {}),
       },
       mutating: true,
@@ -1345,6 +1555,38 @@ export const appsCommandSpecs = [
     backend_call: { type: 'local', name: 'verify_harness' },
     handler: appsVerifyHandler,
   },
+  {
+    command_path: ['apps', 'screenshot'],
+    summary: 'Capture listing screenshots of each route via the headless harness.',
+    when_to_use:
+      'Generate metadata/screenshot-N.png for the App Store listing. Apps are ' +
+      'icon-led (like Raycast) — there is no cover image, only these screenshots. ' +
+      'Run before notis apps verify / deploy / publish.',
+    args_schema: {
+      arguments: [
+        { token: '[dir]', key: 'dir', description: 'Project directory (default: current dir).' },
+      ],
+      options: [
+        { flags: '--routes <slugs>', description: 'Comma-separated route slugs. Default: every route in manifest.' },
+        { flags: '--port <n>', description: 'Loopback port. Default: auto-pick.' },
+        { flags: '--width <px>', description: 'Viewport width. Default: 2000.' },
+        { flags: '--height <px>', description: 'Viewport height. Default: 1250 (16:10).' },
+        { flags: '--output-dir <dir>', description: 'Where to write screenshot-N.png. Default: metadata/.' },
+        { flags: '--mode <mode>', description: 'stub | live. Default stub. Live renders against real data via the CLI JWT (requires a linked app), so screenshots show actual content instead of empty states.' },
+        { flags: '--skip-build', description: 'Skip notis apps build; reuse existing .notis/output/.' },
+      ],
+    },
+    examples: [
+      'notis apps screenshot',
+      'notis apps screenshot --routes home,history',
+      'notis apps screenshot --mode live  # populated screenshots from real data',
+    ],
+    mutates: true,
+    idempotent: true,
+    require_auth: false,
+    backend_call: { type: 'local', name: 'screenshot_routes' },
+    handler: appsScreenshotHandler,
+  },
   {
     command_path: ['apps', 'link'],
     summary: 'Link a local project to a remote Notis app.',

package/src/runtime/agent-browser.js

@@ -184,6 +184,95 @@ export async function runHarnessRoute({
   };
 }
 
+/**
+ * Open a harness route, wait for it to mount, then capture a PNG screenshot of
+ * the rendered app at a fixed viewport (default 2000x1250, the 16:10 the
+ * listing validator expects). Used by `notis apps screenshot`.
+ */
+export async function captureHarnessScreenshot({
+  url,
+  sessionName,
+  screenshotPath,
+  width = 2000,
+  height = 1250,
+  timeoutMs = 15_000,
+}) {
+  const opened = await runAgentBrowser(['--session', sessionName, 'open', url], {
+    timeoutMs: Math.min(Math.max(timeoutMs, 5000), 30_000),
+  });
+  if (opened.exitCode !== 0) {
+    return { ok: false, mounted: false, screenshotPath: null, tool_error: commandError('open', opened) };
+  }
+
+  // Fixed viewport so every screenshot is the same frame, regardless of the
+  // operator's screen. React re-layouts on the resize before we capture.
+  await runAgentBrowser(
+    ['--session', sessionName, 'set', 'viewport', String(width), String(height)],
+    { timeoutMs: 5000 },
+  );
+
+  const deadline = Date.now() + timeoutMs;
+  let lastErrors = [];
+  let lastReadError = null;
+  let mounted = false;
+  while (Date.now() < deadline) {
+    const read = await readHarness(sessionName, 5000);
+    if (read.ok) {
+      const harness = read.harness || {};
+      mounted = Boolean(harness.mounted);
+      lastErrors = Array.isArray(harness.errors) ? harness.errors : [];
+      if (mounted || lastErrors.length > 0) {
+        break;
+      }
+    } else {
+      lastReadError = read.toolError;
+    }
+    await delay(250);
+  }
+
+  if (lastErrors.length > 0) {
+    return { ok: false, mounted, screenshotPath: null, errors: lastErrors, tool_error: null };
+  }
+  if (!mounted) {
+    return {
+      ok: false,
+      mounted: false,
+      screenshotPath: null,
+      errors: [],
+      timed_out: true,
+      tool_error: lastReadError || {
+        phase: 'harness',
+        message: 'Timed out waiting for window.__harness.mounted.',
+      },
+    };
+  }
+
+  // Hide the harness debug banner so it never appears in the listing image.
+  await runAgentBrowser(
+    [
+      '--session',
+      sessionName,
+      'eval',
+      "(() => { const el = document.getElementById('harness-status'); if (el) el.style.display = 'none'; return true; })()",
+    ],
+    { timeoutMs: 5000 },
+  );
+
+  // Let the route settle (fonts, async data) before the capture.
+  await delay(500);
+
+  mkdirSync(dirname(screenshotPath), { recursive: true });
+  const shot = await runAgentBrowser(
+    ['--session', sessionName, 'screenshot', screenshotPath, '--screenshot-format', 'png'],
+    { timeoutMs: 15_000 },
+  );
+  if (shot.exitCode !== 0) {
+    return { ok: false, mounted: true, screenshotPath: null, errors: lastErrors, timed_out: false, tool_error: commandError('screenshot', shot) };
+  }
+
+  return { ok: true, mounted: true, screenshotPath, errors: lastErrors, timed_out: false, tool_error: null };
+}
+
 export async function closeAgentBrowserSession(sessionName) {
   const result = await runAgentBrowser(['--session', sessionName, 'close'], {
     timeoutMs: 5000,