@notis_ai/cli 0.2.5 → 0.2.6

package/src/command-specs/tools.js

@@ -342,43 +342,48 @@ async function toolsExecParallelHandler(ctx) {
 }
 
 async function toolsLinkHandler(ctx) {
-  const apiBase = ctx.runtime.apiBase.replace(/\/+$/, '');
-  let portalBase;
-  try {
-    const parsed = new URL(apiBase);
-    if (parsed.hostname.startsWith('api.')) {
-      parsed.hostname = parsed.hostname.replace(/^api\./, 'app.');
-      portalBase = parsed.origin;
-    } else if (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1') {
-      const apiPort = parseInt(parsed.port, 10) || 80;
-      parsed.port = String(apiPort === 3001 ? 3000 : apiPort);
-      portalBase = parsed.origin;
-    } else {
-      portalBase = apiBase;
-    }
-  } catch {
-    portalBase = apiBase.replace('api.', 'app.');
+  const credentials = ctx.options.credentials
+    ? await resolveJsonInput(ctx.options.credentials, 'credentials')
+    : undefined;
+  if (credentials !== undefined && (typeof credentials !== 'object' || credentials === null || Array.isArray(credentials))) {
+    throw usageError('credentials must be a JSON object');
+  }
+
+  const arguments_ = {
+    toolkit: ctx.args.toolkit,
+    ...(ctx.options.reconnect ? { reconnect: true } : {}),
+    ...(ctx.options.connectionId ? { reconnect_connection_id: ctx.options.connectionId } : {}),
+    ...(ctx.options.label ? { label: ctx.options.label } : {}),
+    ...(credentials ? { credentials } : {}),
+  };
+  const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
+  const result = await runToolCommand({
+    runtime: ctx.runtime,
+    toolName: 'LOCAL_NOTIS_AUTHENTIFY',
+    arguments_,
+    mutating: true,
+    idempotencyKey,
+  });
+  const payload = result.payload || {};
+  if (payload.status === 'error') {
+    throw usageError(payload.message || `Failed to connect ${ctx.args.toolkit}`, payload);
   }
-  const portalUrl = `${portalBase}/integrations?connect=${encodeURIComponent(ctx.args.toolkit)}`;
+  const authUrl = payload.redirect_url || payload.integrations_url || payload.url || null;
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: {
-      toolkit: ctx.args.toolkit,
-      auth_url: portalUrl,
+      ...payload,
+      auth_url: authUrl,
     },
-    humanSummary: `Open this URL to connect ${ctx.args.toolkit}`,
+    humanSummary: ctx.options.reconnect
+      ? `Reconnected ${ctx.args.toolkit}`
+      : `Started connection for ${ctx.args.toolkit}`,
     hints: [
       { command: 'notis tools toolkits', reason: 'Verify the toolkit is connected after setup' },
     ],
-    renderHuman: () =>
-      [
-        `Connect ${ctx.args.toolkit}:`,
-        `  ${portalUrl}`,
-        '',
-        'After connecting, verify with:',
-        '  notis tools toolkits',
-      ].join('\n'),
+    meta: { mutating: true, idempotency_key: idempotencyKey },
+    renderHuman: () => JSON.stringify({ ...payload, auth_url: authUrl }, null, 2),
   });
 }
 
@@ -481,19 +486,27 @@ export const toolsCommandSpecs = [
   },
   {
     command_path: ['tools', 'link'],
-    summary: 'Get the URL to connect an integration toolkit.',
-    when_to_use: 'Use this when a tool requires authentication with an external service.',
+    summary: 'Connect or reconnect an integration toolkit.',
+    when_to_use: 'Use this when a tool requires authentication or an active connection must be replaced.',
     args_schema: {
       arguments: [{ token: '<toolkit>', description: 'Toolkit name to connect (e.g. github, gmail, slack).' }],
-      options: [],
+      options: [
+        { flags: '--reconnect', description: 'Replace the existing account instead of adding another connection.' },
+        { flags: '--connection-id <id>', key: 'connectionId', description: 'Exact connection id to replace when multiple accounts exist.' },
+        { flags: '--label <label>', description: 'Account label for a new or replacement connection.' },
+        { flags: '--credentials <json>', description: 'Credential JSON object, @file path, or - for stdin. Prefer stdin so secrets do not enter shell history.' },
+      ],
     },
-    examples: ['notis tools link github', 'notis tools link gmail --json'],
-    output_schema: 'Returns the authentication URL for the specified toolkit.',
-    mutates: false,
-    idempotent: true,
-    require_auth: false,
+    examples: [
+      'notis tools link github',
+      'notis tools link dataforseo --reconnect --credentials - < credentials.json',
+    ],
+    output_schema: 'Returns the connection result and an authentication URL when provider authorization is still required.',
+    mutates: true,
+    idempotent: false,
+    require_auth: true,
     related_commands: ['notis tools toolkits', 'notis tools search <query>'],
-    backend_call: { type: 'local' },
+    backend_call: { type: 'tool', name: 'LOCAL_NOTIS_AUTHENTIFY' },
     handler: toolsLinkHandler,
   },
 ];

package/src/runtime/agent-browser.js

@@ -1,7 +1,118 @@
 import { spawn, spawnSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 
+export const HIDE_HARNESS_STATUS_SCRIPT =
+  "(() => { const el = document.getElementById('harness-status'); if (el) el.style.opacity = '0'; return true; })()";
+
+/**
+ * Prepare the mounted harness page for a listing capture: remove the debug
+ * banner and the layout the harness adds around the app (top padding for the
+ * banner, 100vh min-height) so content height can be measured and framed
+ * without artificial whitespace.
+ */
+const PREPARE_CAPTURE_SCRIPT =
+  "(() => { const s = document.getElementById('harness-status'); if (s) s.style.display = 'none';" +
+  " const r = document.getElementById('root'); if (r) { r.style.paddingTop = '0'; r.style.minHeight = '0'; }" +
+  " document.body.style.minHeight = '0'; document.documentElement.style.minHeight = '0'; return true; })()";
+
+const FONTS_STATUS_SCRIPT =
+  "(() => (document.fonts ? document.fonts.status : 'loaded'))()";
+
+const CONTENT_HEIGHT_SCRIPT =
+  '(() => { const r = document.getElementById(\'root\');' +
+  ' if (!r) return Math.ceil(document.documentElement.scrollHeight);' +
+  ' return Math.ceil(Math.max(r.scrollHeight, r.getBoundingClientRect().height)); })()';
+
+// CSS viewport bounds for content-aware framing. Content shorter than the
+// minimum gets a little breathing room; content taller than the maximum is
+// cropped at the frame rather than shrunk into unreadably small text.
+const MIN_CSS_VIEWPORT_HEIGHT = 720;
+const MAX_CSS_VIEWPORT_HEIGHT = 1500;
+
+function pngDimensions(path) {
+  try {
+    const buffer = readFileSync(path);
+    if (buffer.length < 24 || buffer.readUInt32BE(12) !== 0x49484452) {
+      return null;
+    }
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pick a CSS viewport that frames `contentHeight` at the output aspect ratio,
+ * with a deviceScaleFactor that maps it back to exactly outputWidth x
+ * outputHeight physical pixels. Width snaps to a multiple of 8 so the height
+ * stays integral for the common 16:10 target.
+ */
+function fitCssViewport(contentHeight, outputWidth, outputHeight) {
+  const aspect = outputWidth / outputHeight;
+  const cssH = Math.min(
+    MAX_CSS_VIEWPORT_HEIGHT,
+    Math.max(MIN_CSS_VIEWPORT_HEIGHT, Math.round(contentHeight)),
+  );
+  const cssW = Math.round((cssH * aspect) / 8) * 8;
+  return {
+    width: cssW,
+    height: Math.round(cssW / aspect),
+    scale: outputWidth / cssW,
+  };
+}
+
+async function evalNumber(sessionName, script, fallback = null) {
+  const result = await runAgentBrowser(
+    ['--session', sessionName, '--json', 'eval', script],
+    { timeoutMs: 5000 },
+  );
+  if (result.exitCode !== 0) {
+    return fallback;
+  }
+  try {
+    const payload = parseAgentBrowserJson(result.stdout);
+    const raw = payload?.data?.result ?? payload?.result ?? payload?.data ?? null;
+    const value = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    return Number.isFinite(value) ? value : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+async function waitForFonts(sessionName, timeoutMs = 3000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const result = await runAgentBrowser(
+      ['--session', sessionName, '--json', 'eval', FONTS_STATUS_SCRIPT],
+      { timeoutMs: 5000 },
+    );
+    if (result.exitCode !== 0) {
+      return;
+    }
+    try {
+      const payload = parseAgentBrowserJson(result.stdout);
+      const raw = payload?.data?.result ?? payload?.result ?? payload?.data ?? null;
+      const status = typeof raw === 'string' && raw.startsWith('"') ? JSON.parse(raw) : raw;
+      if (status !== 'loading') {
+        return;
+      }
+    } catch {
+      return;
+    }
+    await delay(150);
+  }
+}
+
+async function setViewport(sessionName, width, height, scale = null) {
+  const args = ['--session', sessionName, 'set', 'viewport', String(width), String(height)];
+  if (scale != null) {
+    args.push(String(scale));
+  }
+  const result = await runAgentBrowser(args, { timeoutMs: 5000 });
+  return result.exitCode === 0;
+}
+
 function delay(ms) {
   return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
 }
@@ -186,13 +297,18 @@ 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`.
+ * the rendered app. Output is always exactly `width` x `height` physical
+ * pixels (default 2000x1250, the 16:10 the listing validator expects), but the
+ * CSS viewport is fitted to the rendered content height: short pages render
+ * larger (no dead whitespace below the app), tall pages get more room before
+ * cropping. The deviceScaleFactor maps the fitted CSS viewport back onto the
+ * fixed output frame. Used by `notis apps screenshot`.
  */
 export async function captureHarnessScreenshot({
   url,
   sessionName,
   screenshotPath,
+  focusSelector = null,
   width = 2000,
   height = 1250,
   timeoutMs = 15_000,
@@ -204,12 +320,20 @@ export async function captureHarnessScreenshot({
     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 },
+  // Initial fixed frame so mount/layout happen at a deterministic size; the
+  // scale keeps physical output at width x height from the very first paint.
+  const initial = fitCssViewport(900, width, height);
+  let scaledViewport = await setViewport(
+    sessionName,
+    initial.width,
+    initial.height,
+    initial.scale,
   );
+  if (!scaledViewport) {
+    // Older agent-browser without deviceScaleFactor support: fall back to a
+    // plain fixed viewport at output size.
+    await setViewport(sessionName, width, height);
+  }
 
   const deadline = Date.now() + timeoutMs;
   let lastErrors = [];
@@ -247,30 +371,89 @@ export async function captureHarnessScreenshot({
     };
   }
 
-  // Hide the harness debug banner so it never appears in the listing image.
+  // Strip harness chrome (debug banner, banner padding, 100vh min-height) so
+  // the frame contains only the app, then wait for webfonts before measuring.
   await runAgentBrowser(
-    [
-      '--session',
-      sessionName,
-      'eval',
-      "(() => { const el = document.getElementById('harness-status'); if (el) el.style.display = 'none'; return true; })()",
-    ],
+    ['--session', sessionName, 'eval', PREPARE_CAPTURE_SCRIPT],
     { timeoutMs: 5000 },
   );
+  await waitForFonts(sessionName);
+
+  // Fit the CSS viewport to the rendered content. Content height depends on
+  // viewport width, so refine once after the first resize reflows the page.
+  let framing = null;
+  if (scaledViewport) {
+    let contentHeight = await evalNumber(sessionName, CONTENT_HEIGHT_SCRIPT);
+    for (let pass = 0; contentHeight != null && pass < 2; pass += 1) {
+      const fitted = fitCssViewport(contentHeight, width, height);
+      if (framing && fitted.width === framing.width) {
+        break;
+      }
+      scaledViewport = await setViewport(sessionName, fitted.width, fitted.height, fitted.scale);
+      if (!scaledViewport) {
+        framing = null;
+        await setViewport(sessionName, width, height);
+        break;
+      }
+      framing = { ...fitted, content_height: contentHeight };
+      await delay(150);
+      const remeasured = await evalNumber(sessionName, CONTENT_HEIGHT_SCRIPT);
+      if (remeasured == null || Math.abs(remeasured - contentHeight) <= 32) {
+        framing.content_height = remeasured ?? contentHeight;
+        break;
+      }
+      contentHeight = remeasured;
+    }
+  }
 
-  // Let the route settle (fonts, async data) before the capture.
+  // Let the route settle (async data, resize transitions) 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 },
-  );
+  const screenshotArgs = ['--session', sessionName, 'screenshot'];
+  if (focusSelector) {
+    screenshotArgs.push(focusSelector);
+  }
+  screenshotArgs.push(screenshotPath, '--screenshot-format', 'png');
+  const shot = await runAgentBrowser(screenshotArgs, { 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 };
+  // The listing validator requires exact output dimensions. If the fitted
+  // capture came out wrong (e.g. the browser ignored the scale factor),
+  // recapture once at a plain fixed viewport.
+  const dimensions = pngDimensions(screenshotPath);
+  if (!focusSelector && framing && (!dimensions || dimensions.width !== width || dimensions.height !== height)) {
+    await setViewport(sessionName, width, height);
+    await delay(300);
+    const retry = await runAgentBrowser(
+      ['--session', sessionName, 'screenshot', screenshotPath, '--screenshot-format', 'png'],
+      { timeoutMs: 15_000 },
+    );
+    if (retry.exitCode !== 0) {
+      return { ok: false, mounted: true, screenshotPath: null, errors: lastErrors, timed_out: false, tool_error: commandError('screenshot', retry) };
+    }
+    framing = null;
+  }
+
+  if (focusSelector) {
+    framing = {
+      ...(framing || {}),
+      focus_selector: focusSelector,
+      source_dimensions: dimensions,
+    };
+  }
+
+  return {
+    ok: true,
+    mounted: true,
+    screenshotPath,
+    errors: lastErrors,
+    timed_out: false,
+    tool_error: null,
+    framing,
+  };
 }
 
 export async function closeAgentBrowserSession(sessionName) {

package/src/runtime/app-changelog.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const APP_CHANGELOG_FILE = 'CHANGELOG.md';
+export const CHANGELOG_MERGE_DATE = '{PR_MERGE_DATE}';
+
+const ENTRY_HEADING = /^##\s+\[([^\]]+)]\s+-\s+(\{PR_MERGE_DATE\}|\d{4}-\d{2}-\d{2})\s*$/;
+
+function validCalendarDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  const date = new Date(`${value}T00:00:00Z`);
+  return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}
+
+export function parseAppChangelog(markdown, { sourcePath = APP_CHANGELOG_FILE } = {}) {
+  const lines = String(markdown || '').replace(/\r\n?/g, '\n').split('\n');
+  const entries = [];
+  const errors = [];
+  let current = null;
+
+  function finishCurrent() {
+    if (!current) return;
+    entries.push({
+      title: current.title,
+      date: current.date,
+      body: current.body.join('\n').trim(),
+    });
+  }
+
+  for (const [index, line] of lines.entries()) {
+    // Only a level-2 heading (`## ...`, not `###`/`####`) can start a release
+    // entry; deeper sub-section headings are legitimate release-body content.
+    if (!/^##(?!#)/.test(line)) {
+      if (current) current.body.push(line);
+      continue;
+    }
+
+    const match = line.match(ENTRY_HEADING);
+    if (!match) {
+      errors.push(
+        `${sourcePath}:${index + 1} must use \`## [Release title] - YYYY-MM-DD\` or \`## [Release title] - {PR_MERGE_DATE}\`.`,
+      );
+      continue;
+    }
+
+    finishCurrent();
+    const title = match[1].trim();
+    const date = match[2];
+    if (!title) {
+      errors.push(`${sourcePath}:${index + 1} must include a release title inside square brackets.`);
+    }
+    if (date !== CHANGELOG_MERGE_DATE && !validCalendarDate(date)) {
+      errors.push(`${sourcePath}:${index + 1} contains an invalid calendar date.`);
+    }
+    current = { title, date, body: [] };
+  }
+  finishCurrent();
+
+  if (entries.length === 0 && errors.length === 0) {
+    errors.push(
+      `${sourcePath} must include at least one \`## [Release title] - YYYY-MM-DD\` entry.`,
+    );
+  }
+
+  return { source_path: sourcePath, entries, errors, exists: true };
+}
+
+export function readAppChangelog(projectDir) {
+  const path = join(projectDir, APP_CHANGELOG_FILE);
+  if (!existsSync(path)) {
+    return {
+      source_path: APP_CHANGELOG_FILE,
+      entries: [],
+      errors: [`${APP_CHANGELOG_FILE} is required for Store publication.`],
+      exists: false,
+    };
+  }
+  return parseAppChangelog(readFileSync(path, 'utf-8'));
+}

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

@@ -216,7 +216,7 @@ function findHarnessRoute(manifest, routeSlug) {
   return routes.find((route) => route?.slug === routeSlug) || null;
 }
 
-function buildHarnessDescriptor({ state, manifest, appConfig, route }) {
+function buildHarnessDescriptor({ state, manifest, appConfig, route, scenario = null }) {
   const databases = normalizeDatabaseDescriptors(
     Array.isArray(appConfig?.databases) && appConfig.databases.length
       ? appConfig.databases
@@ -246,14 +246,28 @@ function buildHarnessDescriptor({ state, manifest, appConfig, route }) {
       collection: route.collection || null,
     },
     databases,
-    context: { collectionItem: null },
+    context: { collectionItem: null, screenshotScenario: scenario },
     tools,
   };
 }
 
-function renderHarnessHtml({ state, manifest, appConfig, route, harnessOptions }) {
+function harnessFixtures(projectDir, scenario) {
+  const fixtureConfig = readJsonFile(join(projectDir, 'metadata', 'screenshot-fixtures.json')) || {};
+  const scenarios = fixtureConfig.scenarios && typeof fixtureConfig.scenarios === 'object'
+    ? fixtureConfig.scenarios
+    : {};
+  return {
+    tools: fixtureConfig.tools && typeof fixtureConfig.tools === 'object' ? fixtureConfig.tools : {},
+    requests: fixtureConfig.requests && typeof fixtureConfig.requests === 'object' ? fixtureConfig.requests : {},
+    scenario: scenario && scenarios[scenario] && typeof scenarios[scenario] === 'object'
+      ? scenarios[scenario]
+      : null,
+  };
+}
+
+function renderHarnessHtml({ state, manifest, appConfig, route, harnessOptions, scenario = null }) {
   const template = readFileSync(HARNESS_TEMPLATE_PATH, 'utf-8');
-  const descriptor = buildHarnessDescriptor({ state, manifest, appConfig, route });
+  const descriptor = buildHarnessDescriptor({ state, manifest, appConfig, route, scenario });
   const routeExport = route.export_name || route.exportName || exportNameFromPath(route.path || '/');
   const replacements = {
     '{{REACT_VERSION}}': resolveHarnessReactVersion(state.projectDir),
@@ -262,6 +276,7 @@ function renderHarnessHtml({ state, manifest, appConfig, route, harnessOptions }
     '{{MODE}}': scriptJson(harnessOptions.mode || 'stub'),
     '{{API_BASE}}': scriptJson(harnessOptions.apiBase || null),
     '{{JWT}}': scriptJson(harnessOptions.jwt || null),
+    '{{FIXTURES}}': scriptJson(harnessFixtures(state.projectDir, scenario)),
   };
   let html = template;
   for (const [token, value] of Object.entries(replacements)) {
@@ -370,6 +385,7 @@ export async function startAppDevServer({
     }
 
     const routeSlug = url.searchParams.get('route') || '';
+    const scenario = url.searchParams.get('scenario') || null;
     const route = findHarnessRoute(manifest, routeSlug);
     if (!route) {
       res.writeHead(404, {
@@ -386,6 +402,7 @@ export async function startAppDevServer({
       appConfig,
       route,
       harnessOptions: harness,
+      scenario,
     });
     res.writeHead(200, {
       ...headers,

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

@@ -7,6 +7,7 @@ import { CONFIG_DIR } from './profiles.js';
 export const DEFAULT_APP_DEV_SESSIONS_FILE = join(CONFIG_DIR, 'app-dev-sessions.json');
 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.
@@ -54,6 +55,12 @@ export function getAppDevSessionsFile(filePath) {
   return DEFAULT_APP_DEV_SESSIONS_FILE;
 }
 
+export function getAppDevSessionMountAcksFile(sessionsFilePath) {
+  const resolvedSessionsFile = getAppDevSessionsFile(sessionsFilePath);
+  const parsed = parsePath(resolvedSessionsFile);
+  return join(parsed.dir, `${parsed.name}-mount-acks${parsed.ext || '.json'}`);
+}
+
 function normalizeSessions(raw) {
   if (!raw || typeof raw !== 'object' || !Array.isArray(raw.sessions)) {
     return [];
@@ -149,5 +156,96 @@ export function linkAppDevSessionTarget({ appId, devSlug, targetAppId, lastHeart
 export function removeAppDevSession(sessionId, filePath) {
   const registry = readAppDevSessions(filePath);
   registry.sessions = registry.sessions.filter((session) => session.sessionId !== sessionId);
-  return writeAppDevSessions(registry, filePath);
+  const result = writeAppDevSessions(registry, filePath);
+  removeAppDevSessionMountAcknowledgements(sessionId, filePath);
+  return result;
+}
+
+function normalizeMountAcknowledgements(raw) {
+  if (!raw || typeof raw !== 'object' || !Array.isArray(raw.acknowledgements)) {
+    return [];
+  }
+  return raw.acknowledgements.filter((acknowledgement) =>
+    acknowledgement &&
+    typeof acknowledgement === 'object' &&
+    typeof acknowledgement.sessionId === 'string' &&
+    typeof acknowledgement.appId === 'string' &&
+    typeof acknowledgement.devSlug === 'string' &&
+    typeof acknowledgement.mountNonce === 'string' &&
+    typeof acknowledgement.acknowledgedAt === 'string' &&
+    acknowledgement.stage === 'listed',
+  );
+}
+
+export function readAppDevSessionMountAcknowledgements(sessionsFilePath) {
+  const filePath = getAppDevSessionMountAcksFile(sessionsFilePath);
+  if (!existsSync(filePath)) {
+    return { version: APP_DEV_SESSION_MOUNT_ACKS_VERSION, acknowledgements: [] };
+  }
+  try {
+    const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    return {
+      version: APP_DEV_SESSION_MOUNT_ACKS_VERSION,
+      acknowledgements: normalizeMountAcknowledgements(raw),
+    };
+  } catch {
+    return { version: APP_DEV_SESSION_MOUNT_ACKS_VERSION, acknowledgements: [] };
+  }
+}
+
+function writeAppDevSessionMountAcknowledgements(registry, sessionsFilePath) {
+  const filePath = getAppDevSessionMountAcksFile(sessionsFilePath);
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const normalized = {
+    version: APP_DEV_SESSION_MOUNT_ACKS_VERSION,
+    acknowledgements: normalizeMountAcknowledgements(registry),
+  };
+  const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(tempPath, JSON.stringify(normalized, null, 2), { mode: 0o600 });
+  renameSync(tempPath, filePath);
+  return normalized;
+}
+
+export function removeAppDevSessionMountAcknowledgements(sessionId, sessionsFilePath) {
+  const filePath = getAppDevSessionMountAcksFile(sessionsFilePath);
+  if (!existsSync(filePath)) {
+    return { version: APP_DEV_SESSION_MOUNT_ACKS_VERSION, acknowledgements: [] };
+  }
+  const registry = readAppDevSessionMountAcknowledgements(sessionsFilePath);
+  registry.acknowledgements = registry.acknowledgements.filter(
+    (acknowledgement) => acknowledgement.sessionId !== sessionId,
+  );
+  return writeAppDevSessionMountAcknowledgements(registry, sessionsFilePath);
+}
+
+function mountAcknowledgementKey(value) {
+  return `${value.sessionId}:${value.appId}:${value.devSlug}:${value.mountNonce}`;
+}
+
+export async function waitForAppDevSessionMountAcknowledgements(expectedSessions, options = {}) {
+  const expected = Array.isArray(expectedSessions) ? expectedSessions : [expectedSessions];
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? Math.max(0, options.timeoutMs) : 15_000;
+  const pollIntervalMs = Number.isFinite(options.pollIntervalMs)
+    ? Math.max(1, options.pollIntervalMs)
+    : 100;
+  const now = typeof options.now === 'function' ? options.now : Date.now;
+  const sleep = typeof options.sleep === 'function'
+    ? options.sleep
+    : (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs));
+  const startedAt = now();
+
+  while (true) {
+    const registry = readAppDevSessionMountAcknowledgements(options.sessionsFilePath);
+    const acknowledgedKeys = new Set(registry.acknowledgements.map(mountAcknowledgementKey));
+    const missing = expected.filter((session) => !acknowledgedKeys.has(mountAcknowledgementKey(session)));
+    if (missing.length === 0) {
+      return { mounted: true, missing: [], acknowledgements: registry.acknowledgements };
+    }
+
+    const elapsedMs = now() - startedAt;
+    if (elapsedMs >= timeoutMs) {
+      return { mounted: false, missing, acknowledgements: registry.acknowledgements };
+    }
+    await sleep(Math.min(pollIntervalMs, timeoutMs - elapsedMs));
+  }
 }