@notis_ai/cli 0.2.0-beta.178.1 → 0.2.0-beta.1792022492092.1

package/src/runtime/space-verification.js

@@ -0,0 +1,89 @@
+/** Frozen offline fixtures rendered by the same read-only library as CLI/service. */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { appFilesDigest } from './app-platform.js';
+import { createSpaceFixtureBroker } from './space-fixture-broker.js';
+
+// Kept for the standalone legacy worker's lifecycle tests while that diagnostic
+// entrypoint is retired. The primary verifier below never starts that worker.
+export function spaceVerificationEnvironment(environment, { configPath }) {
+  const names = ['PATH', 'HOME', 'TMPDIR', 'TEMP', 'TMP', 'LANG', 'SystemRoot', 'WINDIR', 'DISPLAY', 'XDG_RUNTIME_DIR'];
+  return { ...Object.fromEntries(names.filter(name => typeof environment[name] === 'string').map(name => [name, environment[name]])),
+    AGENT_BROWSER_CONFIG: configPath, AGENT_BROWSER_NO_WEBMCP: '1' };
+}
+
+export async function loadSpaceVerificationRenderer() {
+  const candidates = [new URL('../../dist/view-renderer/', import.meta.url), new URL('../../../view-renderer/', import.meta.url)];
+  for (const root of candidates) {
+    const entry = new URL('src/index.js', root);
+    if (!existsSync(fileURLToPath(entry))) continue;
+    const digest = createHash('sha256');
+    for (const file of ['src/renderer.js', 'src/dom.js', 'src/pool.js', 'dist/host.js', 'dist/host.css', 'dist/theme.css']) {
+      digest.update(file); digest.update(readFileSync(new URL(file, root)));
+    }
+    return { ...(await import(entry.href)), rendererDigest: digest.digest('hex') };
+  }
+  throw new Error('The shared view renderer is missing. Rebuild or reinstall this CLI package.');
+}
+
+// One browser per verification, two widths concurrently; no worker creates an
+// unbounded browser fanout. Up to two invocations may run simultaneously.
+let active = 0;
+const waiting = [];
+async function acquire(signal) {
+  if (signal?.aborted) throw new Error('Verification cancelled.');
+  if (active < 2) { active++; return; }
+  if (waiting.length >= 8) throw new Error('The local verification queue is full.');
+  await new Promise((accept, reject) => {
+    const entry = { accept: () => { signal?.removeEventListener('abort', abort); accept(); } };
+    const abort = () => { const index = waiting.indexOf(entry); if(index >= 0) waiting.splice(index, 1); reject(new Error('Verification cancelled.')); };
+    waiting.push(entry); signal?.addEventListener('abort', abort, { once: true });
+  });
+}
+function releaseSlot() { const next = waiting.shift(); if (next) next.accept(); else active--; }
+
+/** Initial deployment checks the exact captured bytes at both product widths. */
+export async function verifySpaceRelease(release, { capabilities, timeoutMs = 45_000, signal, loadRenderer = loadSpaceVerificationRenderer,
+  authorizationMode = 'authorize_missing', unavailableActions = [] } = {}) {
+  const diagnostic = { schema: 'notis-space-render/v1', local_key: release.manifest.local_key,
+    source_digest: appFilesDigest(release.sourceFiles), artifact_digest: appFilesDigest(release.files),
+    mode: 'offline_fixtures', checked_at: new Date().toISOString(),
+    ...(authorizationMode === 'reuse_only' ? { authorization_mode: authorizationMode,
+      unavailable_actions: structuredClone(unavailableActions) } : {}) };
+  if (signal?.aborted) return { ...diagnostic, status: 'failed', errors: [{ phase: 'browser', message: 'Verification cancelled.' }] };
+  if (release.manifest.kind === 'container') return { ...diagnostic, status: 'not_applicable_container' };
+  let pool, held = false, rendererDigest;
+  const brokers = [390, 1440].map(width => ({ width, broker: null }));
+  try {
+    // Validate fixture authority before opening a browser or acquiring a slot.
+    for (const item of brokers) item.broker = createSpaceFixtureBroker({ release, capabilities, width: item.width,
+      authorizationMode, unavailableActions });
+    await acquire(signal); held = true;
+    const library = await loadRenderer(); rendererDigest = library.rendererDigest;
+    pool = library.createBrowserPool({ concurrency: 2, maxQueue: 2 });
+    const observations = await Promise.allSettled(brokers.map(async ({ width, broker }) => {
+      const result = await library.renderView({ broker, pool, outputs: ['markdown', 'screenshot'], width, timeoutMs, signal });
+      const blocked = result.blocked_calls || [];
+      return { width, mounted: true, status: blocked.length ? 'failed' : 'passed',
+        markdown_sha256: createHash('sha256').update(result.markdown).digest('hex'),
+        screenshot_sha256: createHash('sha256').update(Buffer.from(result.screenshot.data_base64, 'base64')).digest('hex'),
+        screenshot_width: result.screenshot.width, screenshot_height: result.screenshot.height,
+        rendered_at: result.rendered_at, blocked_calls: blocked };
+    }));
+    const renders = observations.map((value, index) => value.status === 'fulfilled' ? value.value : {
+      width: brokers[index].width, mounted: false, status: 'failed', error: value.reason?.code || 'render_failed',
+    });
+    const runtimeCalls = brokers.flatMap(({ width, broker }) => broker.calls.map(call => ({ width, ...call })));
+    const passed = renders.every(value => value.status === 'passed') && runtimeCalls.every(call => call.ok);
+    return { ...diagnostic, status: passed ? 'passed' : 'failed', mounted: renders.every(value => value.mounted),
+      fixture_digest: brokers[0].broker.fixtureDigest, renderer_digest: rendererDigest,
+      render_count: renders.length, browser_count: 1, renders, runtimeCalls,
+      errors: passed ? [] : [{ phase: 'renderer', message: 'At least one width or read-only fixture failed verification.' }] };
+  } catch (error) {
+    return { ...diagnostic, status: 'failed', ...(rendererDigest ? { renderer_digest: rendererDigest } : {}),
+      errors: [{ phase: 'harness', message: error.message }] };
+  } finally {
+    try { await pool?.close(); } finally { if (held) releaseSlot(); }
+  }
+}

package/src/runtime/space-verify-browser-worker.js

@@ -0,0 +1,51 @@
+/** Runs in a credential-free child process, never in the authenticated CLI. */
+import { closeAgentBrowserSessionResult, isAgentBrowserAvailable, runHarnessRoute } from './agent-browser.js';
+
+let sessionName;
+let closing;
+let started = false;
+const controller = new AbortController();
+let exitCode = 0;
+const cleanup = () => closing ||= sessionName ? closeAgentBrowserSessionResult(sessionName) : Promise.resolve({ ok: true });
+for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => {
+  exitCode = signal === 'SIGINT' ? 130 : 143;
+  controller.abort();
+  if (!started) process.exit(exitCode);
+});
+process.on('disconnect', () => { exitCode = 1; controller.abort(); if (!started) process.exit(1); });
+
+process.once('message', async input => {
+  started = true;
+  let result;
+  try {
+    const url = new URL(input.url);
+    if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !url.port
+      || !/^notis-space-[a-f0-9-]+$/.test(input.sessionName)) throw new Error('Invalid offline verification session.');
+    sessionName = input.sessionName;
+    if (!isAgentBrowserAvailable()) throw new Error('Install agent-browser and its Chromium browser to verify a presentation.');
+    const observed = await runHarnessRoute({ url: url.href, sessionName, timeoutMs: input.timeoutMs,
+      designViewports: [], waitForRuntime: true, signal: controller.signal });
+    // Never retain raw eval/stdout or action inputs/results in a diagnostic receipt.
+    result = {
+      mounted: observed.mounted,
+      renderStarted: observed.renderStarted,
+      timed_out: Boolean(observed.timed_out),
+      errors: (observed.errors || []).map(error => ({ phase: String(error.phase).slice(0, 100), message: String(error.message).slice(0, 2000) })),
+      runtimeCalls: (observed.runtimeCalls || []).map(call => ({ actionId: call.actionId, ok: call.ok,
+        ...(call.error ? { error: String(call.error).slice(0, 2000) } : {}) })),
+      ...(observed.tool_error ? { tool_error: { phase: observed.tool_error.phase,
+        message: String(observed.tool_error.stderr || observed.tool_error.message
+          || 'The isolated verification browser could not complete this operation.').slice(0, 2000) } } : {}),
+    };
+  } catch (error) {
+    result = { mounted: false, errors: [{ phase: 'browser', message: error.message }], runtimeCalls: [] };
+  } finally {
+    if (process.connected) {
+      try { process.send({ phase: 'cleanup' }, () => {}); } catch { /* Cleanup still owns the browser after IPC loss. */ }
+    }
+    const closed = await cleanup();
+    result = { ...result, cleanup: closed, ...(!closed.ok ? { cleanup_failed: true } : {}) };
+  }
+  if (process.connected) process.send(result, () => process.exit(exitCode));
+  else process.exit(exitCode);
+});

package/src/runtime/space-view-manifest.js

@@ -0,0 +1,254 @@
+/**
+ * What a view declares (V4): path, typed params, shows, memory, chrome and a Markdown override.
+ * Mirrors server/lib/space_view_manifest.py, which re-checks every release; property-level checks
+ * need the linked schemas and run on the server during `spaces verify` and deploy.
+ * Every presentation requires path, description and memory, including sources that omit
+ * specVersion. Containers remain non-executable; explicit specVersion 2 is unchanged.
+ */
+import { usageError } from './errors.js';
+import portalRouteRoots from '../../config/portal-route-roots.json' with { type: 'json' };
+const RESERVED_PATHS = new Set(portalRouteRoots);
+
+export const VIEW_SPEC_VERSION = 2;
+export const VIEW_DEFINITION_FIELDS = Object.freeze(['specVersion', 'path', 'params', 'shows', 'memory', 'chrome', 'markdown']);
+export const VIEW_PARAM_TYPES = Object.freeze(['record', 'enum', 'text', 'number', 'date', 'boolean']);
+const RESERVED_PARAMS = new Set(['record', 'assistantThread']);
+const PAGE_ONLY = ['params', 'shows', 'memory', 'chrome', 'markdown'];
+const NAME = /^[a-z][A-Za-z0-9_]{0,63}$/;
+// Credentials never ride in links, so no view param may look like one (the Portal drops these names).
+const CREDENTIAL_PARAM = /^(?:jwt|code|state|key)$|token|secret|password|credential|session|auth|api_?key/i;
+const WORD = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const ID_TAIL = /(?:^|-)(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+const PLACEHOLDER = /^\{([a-z][A-Za-z0-9_]{0,63})(?:\.([^{}.\s][^{}]{0,199}))?\}$/;
+const RECORD_KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const SERVICE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/;
+const FIELD_KEYS = ['property', 'property_id', 'column'];
+const OPS = new Set(['equals', 'not_equals', 'in', 'contains', 'not_contains', 'starts_with', 'ends_with', 'is_empty', 'is_not_empty',
+  'greater_than', 'less_than', 'greater_than_or_equal_to', 'less_than_or_equal_to', 'does_not_contain', 'before', 'after',
+  'on_or_before', 'on_or_after']);
+const CRON_BOUNDS = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 7]];
+const DEBOUNCE = [60, 86400];
+
+const plain = value => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const text = (value, limit) => typeof value === 'string' && value.trim().length >= 1 && value.trim().length <= limit && !CONTROL.test(value);
+const isoDate = value => typeof value === 'string' && DATE.test(value) && !Number.isNaN(Date.parse(`${value}T00:00:00Z`))
+  && new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) === value;
+
+export function validateViewPath(value) {
+  if (typeof value !== 'string' || value.length < 1 || value.length > 100) {
+    throw usageError('Declare path as the words of this view\'s links, such as "notes" or "seo/keywords".');
+  }
+  const segments = value.split('/');
+  if (segments.length > 4 || segments.some(segment => !WORD.test(segment) || ID_TAIL.test(segment))) {
+    throw usageError('A path is up to four lowercase words (a-z, 0-9, dashes) separated by "/", without ids.');
+  }
+  if (RESERVED_PATHS.has(segments[0])) throw usageError(`The path "${segments[0]}" belongs to the Portal. Choose another first word.`);
+  return value;
+}
+
+function validCron(value) {
+  const fields = typeof value === 'string' ? value.split(' ') : [];
+  if (fields.length !== 5) return false;
+  return fields.every((field, index) => {
+    const [low, high] = CRON_BOUNDS[index];
+    const inRange = number => /^\d+$/.test(number) && Number(number) >= low && Number(number) <= high;
+    if (index === 0) return inRange(field);
+    return field.split(',').every(part => {
+      const [base, step, extra] = part.split('/');
+      if (extra !== undefined || (step !== undefined && !(/^\d+$/.test(step) && Number(step) >= 1 && Number(step) <= high))) return false;
+      if (base === '*') return true;
+      const [start, end, more] = base.split('-');
+      if (more !== undefined || !inRange(start) || (end !== undefined && (!inRange(end) || Number(start) > Number(end)))) return false;
+      return true;
+    });
+  });
+}
+
+function validateMemory(memory) {
+  if (!plain(memory) || Object.keys(memory).sort().join(',') !== 'attachments,markdown,screenshot,snapshots') {
+    throw usageError('Declare memory as { markdown, attachments, screenshot, snapshots }; see the memory guide.');
+  }
+  if (['markdown', 'attachments', 'screenshot'].some(name => typeof memory[name] !== 'boolean')) {
+    throw usageError('memory.markdown, memory.attachments and memory.screenshot are true or false.');
+  }
+  if (!Array.isArray(memory.snapshots) || memory.snapshots.length > 3) {
+    throw usageError('memory.snapshots lists on_render, { scheduled } and { on_change }, each at most once ([] for none).');
+  }
+  const seen = new Set();
+  for (const strategy of memory.snapshots) {
+    let kind;
+    if (strategy === 'on_render') kind = 'on_render';
+    else if (plain(strategy) && Object.keys(strategy).join(',') === 'scheduled') {
+      kind = 'scheduled';
+      if (!validCron(strategy.scheduled)) throw usageError('A scheduled snapshot uses a five-field UTC cron with a fixed minute, such as "0 7 * * 1".');
+    } else if (plain(strategy) && Object.keys(strategy).join(',') === 'on_change') {
+      kind = 'on_change';
+      const debounce = strategy.on_change?.debounceSeconds;
+      if (!plain(strategy.on_change) || Object.keys(strategy.on_change).join(',') !== 'debounceSeconds' || !Number.isInteger(debounce)
+        || debounce < DEBOUNCE[0] || debounce > DEBOUNCE[1]) {
+        throw usageError(`An on_change snapshot waits debounceSeconds (${DEBOUNCE[0]} to ${DEBOUNCE[1]}) after the last change.`);
+      }
+    } else throw usageError('memory.snapshots lists on_render, { scheduled: "<cron>" } or { on_change: { debounceSeconds } }.');
+    if (seen.has(kind)) throw usageError('Declare each memory snapshot strategy at most once.');
+    seen.add(kind);
+  }
+}
+
+/** One typed param value, as the SDK and the server accept it. */
+export function viewParamValue(declaration, value) {
+  switch (declaration.type) {
+    case 'text': return typeof value === 'string' && value.length <= 500 && !CONTROL.test(value);
+    case 'enum': return typeof value === 'string' && (declaration.values || []).includes(value);
+    case 'number': return typeof value === 'number' && Number.isFinite(value);
+    case 'boolean': return typeof value === 'boolean';
+    case 'date': return isoDate(value);
+    case 'record': return typeof value === 'string' && RECORD_KEY.test(value);
+    default: return false;
+  }
+}
+
+function validateParam(name, declaration, resources) {
+  if (!NAME.test(name) || RESERVED_PARAMS.has(name) || CREDENTIAL_PARAM.test(name)) throw usageError(`Param names are camelCase words; "${name}" is not available.`);
+  const allowed = new Set(['type', 'description', 'required', 'default', 'values', 'database', 'main', 'slugProperty']);
+  if (!plain(declaration) || Object.keys(declaration).some(field => !allowed.has(field)) || !VIEW_PARAM_TYPES.includes(declaration.type)) {
+    throw usageError(`Declare param "${name}" as { type, description, ... } with type ${VIEW_PARAM_TYPES.join(', ')}.`);
+  }
+  if (!text(declaration.description, 500)) throw usageError(`Describe param "${name}": what it selects, for agents and people.`);
+  if ('required' in declaration && typeof declaration.required !== 'boolean') throw usageError(`Param "${name}": required is true or false.`);
+  if (declaration.type === 'enum') {
+    const values = declaration.values;
+    if (!Array.isArray(values) || values.length < 1 || values.length > 100 || new Set(values).size !== values.length
+      || values.some(value => !text(value, 100))) throw usageError(`Param "${name}": an enum lists its distinct values.`);
+  } else if ('values' in declaration) throw usageError(`Param "${name}": only enum params list values.`);
+  if (declaration.type === 'record') {
+    if (resources[declaration.database]?.kind !== 'database') {
+      throw usageError(`Param "${name}": a record param names a database this Space declares in resources.`);
+    }
+    if ('main' in declaration && typeof declaration.main !== 'boolean') throw usageError(`Param "${name}": main is true or false.`);
+    if ('slugProperty' in declaration && !text(declaration.slugProperty, 200)) throw usageError(`Param "${name}": slugProperty names a property of its database.`);
+    if ('default' in declaration) throw usageError(`Param "${name}": a record param has no default record.`);
+  } else if (['database', 'main', 'slugProperty'].some(field => field in declaration)) {
+    throw usageError(`Param "${name}": database, main and slugProperty belong to record params.`);
+  }
+  if ('default' in declaration) {
+    if (declaration.required === true) throw usageError(`Param "${name}": a required param has no default.`);
+    if (!viewParamValue(declaration, declaration.default)) throw usageError(`Param "${name}": its default must be a valid ${declaration.type} value.`);
+  }
+}
+
+function checkPlaceholder(value, params, collection, where) {
+  const match = typeof value === 'string' ? PLACEHOLDER.exec(value) : null;
+  if (!match) return;
+  const [, name, property] = match;
+  if (name === 'record') {
+    const records = Object.values(params).filter(declaration => declaration.type === 'record');
+    if (records.length === 1 || (!records.length && collection)) return;
+    throw usageError('Use {record} only in a view with exactly one record param (or a collection); otherwise name the param, such as {project}.');
+  }
+  if (!Object.hasOwn(params, name)) throw usageError(`${where}: "{${name}}" names no declared param.`);
+  if (property !== undefined && params[name].type !== 'record') throw usageError(`${where}: only record params have properties, such as {${name}}.`);
+}
+
+function walkFilter(node, visit, where, depth = 0, budget = { left: 200 }) {
+  budget.left -= 1;
+  if (depth > 12 || budget.left < 0) throw usageError(`${where}: the filter is too complex; use fewer conditions.`);
+  if (depth === 0 && plain(node) && !Object.keys(node).length) return;
+  if (!plain(node)) throw usageError(`${where}: a filter is an object.`);
+  for (const group of ['and', 'or']) {
+    if (!Object.hasOwn(node, group)) continue;
+    const children = node[group];
+    if (Object.keys(node).length !== 1 || !Array.isArray(children) || !children.length) throw usageError(`${where}: filter groups need at least one condition.`);
+    children.forEach(child => walkFilter(child, visit, where, depth + 1, budget));
+    return;
+  }
+  const field = node.field;
+  if (Object.keys(node).some(key => !['field', 'op', 'value'].includes(key)) || !('field' in node) || !('op' in node)
+    || !plain(field) || Object.keys(field).length !== 1 || !FIELD_KEYS.includes(Object.keys(field)[0])
+    || typeof Object.values(field)[0] !== 'string' || !OPS.has(node.op)) {
+    throw usageError(`${where}: each condition is { field: { property }, op, value } in the native filter language.`);
+  }
+  visit(node);
+}
+
+function validateShows(name, declaration, params, resources, collection) {
+  const where = `shows.${name}`;
+  if (!NAME.test(name)) throw usageError(`Shows names are camelCase words; "${name}" is not available.`);
+  if (plain(declaration) && 'about' in declaration) {
+    const services = declaration.services ?? [];
+    if (Object.keys(declaration).some(field => !['about', 'services'].includes(field)) || !text(declaration.about, 500)
+      || !Array.isArray(services) || services.length > 20 || services.some(service => typeof service !== 'string' || !SERVICE.test(service))) {
+      throw usageError(`${where}: describe what it shows as { about, services? }.`);
+    }
+    return;
+  }
+  if (!plain(declaration) || Object.keys(declaration).some(field => !['database', 'where', 'open'].includes(field)) || !('where' in declaration)) {
+    throw usageError(`${where}: declare { database, where, open? } for Notis data or { about, services? } otherwise.`);
+  }
+  if (resources[declaration.database]?.kind !== 'database') {
+    throw usageError(`${where}: "${declaration.database}" is not a database this Space declares and links.`);
+  }
+  if (declaration.open !== undefined && (params[declaration.open]?.type !== 'record' || params[declaration.open].database !== declaration.database)) {
+    throw usageError(`${where}: open names a record param over the same database.`);
+  }
+  walkFilter(declaration.where, condition => {
+    if (!('value' in condition)) return;
+    const values = condition.op === 'in' && Array.isArray(condition.value) ? condition.value : [condition.value];
+    values.forEach(value => checkPlaceholder(value, params, collection, where));
+  }, where);
+}
+
+/**
+ * Validates V4 declarations independently of the optional version marker, then returns
+ * their manifest form without inventing a version or page fields for containers.
+ */
+export function viewManifestFields(definition, { entry, resources }) {
+  const container = !entry;
+  const version = definition.specVersion;
+  if (version !== undefined && version !== VIEW_SPEC_VERSION) throw usageError(`specVersion is ${VIEW_SPEC_VERSION} for sources that declare the view manifest.`);
+  if (container && PAGE_ONLY.some(field => definition[field] !== undefined)) {
+    throw usageError('A container has no page: params, shows, memory, chrome and markdown belong to its views.');
+  }
+  if (!container || version === VIEW_SPEC_VERSION) {
+    const missing = ['path', 'description'].filter(field => !definition[field]);
+    if (!container && definition.memory === undefined) missing.push('memory');
+    if (missing.length) throw usageError(`This view needs ${missing.join(', ')} (specVersion 2).`);
+    if (!text(definition.description, 300)) throw usageError('Describe this view in one line (up to 300 characters).');
+  }
+  if (definition.path !== undefined) validateViewPath(definition.path);
+  const params = definition.params ?? {};
+  if (definition.params !== undefined) {
+    if (!plain(params) || Object.keys(params).length > 50) throw usageError('Declare params as { name: { type, description, ... } }.');
+    const mains = new Map();
+    for (const [name, declaration] of Object.entries(params)) {
+      validateParam(name, declaration, resources);
+      if (declaration.type !== 'record' || declaration.main !== true) continue;
+      if (mains.has(declaration.database)) {
+        throw usageError(`Params "${mains.get(declaration.database)}" and "${name}" both claim main for database "${declaration.database}"; a database has one main view.`);
+      }
+      mains.set(declaration.database, name);
+    }
+  }
+  if (definition.shows !== undefined) {
+    if (!plain(definition.shows) || Object.keys(definition.shows).length > 50) {
+      throw usageError('Declare shows as { name: { database, where, open? } } or { name: { about, services? } }.');
+    }
+    for (const [name, declaration] of Object.entries(definition.shows)) validateShows(name, declaration, params, resources, definition.collection);
+  }
+  if (definition.memory !== undefined) validateMemory(definition.memory);
+  if (definition.chrome !== undefined && !['portal', 'hidden'].includes(definition.chrome)) throw usageError("chrome is 'portal' (default) or 'hidden'.");
+  if (definition.markdown !== undefined && (typeof definition.markdown !== 'string' || !definition.markdown)) {
+    throw usageError('markdown names a source module whose default export renders this view as Markdown.');
+  }
+  return {
+    ...(version !== undefined ? { spec_version: version } : {}),
+    ...(definition.path !== undefined ? { path: definition.path } : {}),
+    ...(definition.params !== undefined ? { params } : {}),
+    ...(definition.shows !== undefined ? { shows: definition.shows } : {}),
+    ...(definition.memory !== undefined ? { memory: definition.memory } : {}),
+    ...(definition.chrome !== undefined ? { chrome: definition.chrome } : {}),
+    ...(definition.markdown !== undefined ? { markdown: { export_name: 'SpaceMarkdown' } } : {}),
+  };
+}

package/src/runtime/store-screenshot.js

@@ -38,15 +38,17 @@ export function resolveStoreScreenshotAccent(accent, seed = 'notis-app') {
   return ACCENT_NAMES[stableHash(seed) % ACCENT_NAMES.length];
 }
 
-export function storeScreenshotLayout(width = 2000, height = 1250) {
+export function storeScreenshotLayout(width = 2000, height = 1250, contentAspect = STORE_SCREENSHOT_ASPECT) {
+  const aspect = Number.isFinite(contentAspect) && contentAspect > 0
+    ? contentAspect : STORE_SCREENSHOT_ASPECT;
   const horizontalInset = Math.max(48, Math.round(width * 0.06));
   const verticalInset = Math.max(40, Math.round(height * 0.06));
   let cardWidth = width - horizontalInset * 2;
-  let cardHeight = Math.round(cardWidth / STORE_SCREENSHOT_ASPECT);
+  let cardHeight = Math.round(cardWidth / aspect);
   const maximumCardHeight = height - verticalInset * 2;
   if (cardHeight > maximumCardHeight) {
     cardHeight = maximumCardHeight;
-    cardWidth = Math.round(cardHeight * STORE_SCREENSHOT_ASPECT);
+    cardWidth = Math.round(cardHeight * aspect);
   }
   const cardLeft = Math.round((width - cardWidth) / 2);
   const cardTop = Math.round((height - cardHeight) / 2) - Math.round(height * 0.008);
@@ -80,7 +82,7 @@ function roundedRectSvg(width, height, radius, { fill = '#ffffff', stroke = null
 
 /**
  * Composite a truthful browser capture into the deterministic Store frame.
- * The source pixels are only resized/cropped; the app UI is never redrawn.
+ * Fit the complete source pixels; never crop controls or redraw the app UI.
  */
 export async function composeStoreScreenshot({
   inputPath,
@@ -94,13 +96,14 @@ export async function composeStoreScreenshot({
 }) {
   const sharp = await loadSharp();
   const resolvedTheme = theme === 'dark' ? 'dark' : 'light';
-  const layout = storeScreenshotLayout(width, height);
+  const source = await sharp(inputPath).metadata();
+  const layout = storeScreenshotLayout(width, height, source.width / source.height);
   const resolvedAccent = resolveStoreScreenshotAccent(accent, seed);
 
   const roundedCapture = await sharp(inputPath)
     .resize(layout.cardWidth, layout.cardHeight, {
-      fit: 'cover',
-      position: focused ? 'top' : 'centre',
+      fit: 'contain',
+      background: resolvedTheme === 'dark' ? '#09090b' : '#ffffff',
     })
     .composite([{
       input: roundedRectSvg(layout.cardWidth, layout.cardHeight, layout.radius),

package/src/runtime/sync-skills.d.ts

@@ -30,8 +30,10 @@ export function reconcileAllSkills<T extends object>(options: {
     serverUrl: string,
     jwt: string,
     dependencies: Record<string, never>,
-    options: { honorSyncEnabled: boolean },
+    options: { honorSyncEnabled: boolean; syncHome?: string; linkAgentFolders?: boolean },
   ) => Promise<T>;
   reconcileBase?: (options: { userId?: string | null; home?: string }) => BaseSkillReconcileResult;
   lockOptions?: Omit<SkillSyncLockOptions, 'home'>;
+  /** False syncs the account's own folder only; another account owns the agent folders. */
+  linkAgentFolders?: boolean;
 }): Promise<T & ReconcileAllSkillsResult>;

package/src/runtime/sync-skills.js

@@ -211,14 +211,22 @@ export async function reconcileAllSkills({
   runAccountSync,
   reconcileBase = reconcileBaseSkills,
   lockOptions = {},
+  linkAgentFolders = true,
 }) {
   return withSkillSyncLock(async () => {
-    const base = reconcileBase({ userId, ...(home ? { home } : {}) });
+    // Base skills are linked from the account that owns the agent folders.
+    const base = linkAgentFolders
+      ? reconcileBase({ userId, ...(home ? { home } : {}) })
+      : { skills: [], installed: 0, linked: 0, unchanged: 0, backups: [] };
     const account = await runAccountSync(
       serverUrl,
       jwt,
       {},
-      { honorSyncEnabled },
+      {
+        honorSyncEnabled,
+        ...(home ? { syncHome: home } : {}),
+        ...(linkAgentFolders ? {} : { linkAgentFolders: false }),
+      },
     );
     return {
       ...account,

package/src/runtime/transport.js

@@ -2,7 +2,6 @@ import { randomUUID } from 'node:crypto';
 import { createReadStream } from 'node:fs';
 import { dirname } from 'node:path';
 import { CliError, EXIT_CODES } from './errors.js';
-import { delegatedContextReason } from './delegated-context.js';
 import {
   credentialIsExpired,
   getJwtExpiration,
@@ -82,10 +81,15 @@ function createMultipartFileUpload(payload, bindingMetadata, fileBindings) {
   };
 }
 
-function normalizeBackendError(status, payload, runtime) {
+export function normalizeBackendError(status, payload, runtime) {
   const backendError = payload?.error;
+  // Space errors answer {error: <stable code>, message: <readable text>}: show
+  // the text (it can name the Space involved); the code stays in details.
+  const codedMessage = typeof backendError === 'string' && /^[a-z][a-z0-9_]*$/.test(backendError)
+    && typeof payload?.message === 'string' && payload.message ? payload.message : null;
   const message =
     backendError?.message ||
+    codedMessage ||
     backendError ||
     payload?.message ||
     payload?.error ||
@@ -258,6 +262,7 @@ export async function httpRequest({
   body,
   multipart = false,
   requireAuth = true,
+  spacesProtocol,
 }) {
   // Refresh before spending the credential rather than after a rejection: the
   // rotating refresh token is shared with every other `notis` process reading
@@ -293,6 +298,7 @@ export async function httpRequest({
     'X-Notis-CLI-Version': runtime.cliVersion,
     'X-Notis-Request-Id': requestId,
   };
+  if (spacesProtocol !== undefined) headers['X-Notis-Spaces-Protocol'] = String(spacesProtocol);
   if (!multipart) {
     headers['Content-Type'] = 'application/json';
   }
@@ -441,10 +447,6 @@ export async function callTool({
       cwd: process.cwd(),
       agent_mode: runtime.agentMode,
       cli_version: runtime.cliVersion,
-      // Reported so the server can refuse work-handing tools from a run Notis
-      // is itself driving. Advisory -- a determined agent can unset the markers
-      // -- so the server treats it as one layer, not the whole guard.
-      ...(delegatedContextReason() ? { delegated_context: true } : {}),
       ...(runtime.debugEntitlementOverride
         ? { debug_entitlement_override: runtime.debugEntitlementOverride }
         : {}),

package/src/runtime/view-render.js

@@ -0,0 +1,49 @@
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile, unlink } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { httpRequest } from './transport.js';
+import { CliError, EXIT_CODES, usageError } from './errors.js';
+
+async function rendererLibrary() {
+  const packaged = new URL('../../dist/view-renderer/src/index.js', import.meta.url);
+  if (existsSync(fileURLToPath(packaged))) return import(packaged.href);
+  const development = new URL('../../../view-renderer/src/index.js', import.meta.url);
+  if (existsSync(fileURLToPath(development))) return import(development.href);
+  throw usageError('The shared view renderer is missing. Rebuild or reinstall this CLI package.');
+}
+
+/** Root command registration supplies flags/output formatting; this adapter holds no browser JWT. */
+export async function renderViewWithCliRuntime({ runtime, url, outputs = ['markdown', 'screenshot'], width = 1440,
+  directory, signal, loadLibrary = rendererLibrary, request = httpRequest }) {
+  if (typeof url !== 'string' || !url.trim() || ![390, 1440].includes(width)) throw usageError('Choose a view link and width 390 or 1440.');
+  const ticket = (await request({ runtime, method: 'POST', path: '/portal_view_render/prepare', spacesProtocol: 1,
+    body: { url, outputs, width }, signal })).payload;
+  if (typeof ticket?.credential !== 'string') throw usageError('The short-lived render ticket is missing.');
+  const library = await loadLibrary();
+  const broker = library.createRemoteRenderBroker({ apiBase: runtime.apiBase, credential: ticket.credential });
+  let result;
+  try {
+    result = await library.renderView({ broker, outputs, width, signal });
+    await broker.complete(result, { signal });
+  }
+  catch (error) {
+    if (error instanceof library.ViewRenderError) throw new CliError({ code: error.code,
+      message: error.message, exitCode: EXIT_CODES.backend, retryable: error.status >= 500 || error.status === 429, cause: error });
+    throw error;
+  }
+  if (!directory) return { result, artifacts: null };
+  const root = resolve(directory), created = [], artifacts = {};
+  await mkdir(root, { recursive: true });
+  try {
+    for (const [kind, name, bytes] of [
+      ['markdown', 'view.md', result.markdown === undefined ? undefined : Buffer.from(result.markdown, 'utf8')],
+      ['screenshot', 'view.png', result.screenshot ? Buffer.from(result.screenshot.data_base64, 'base64') : undefined],
+    ]) {
+      if (bytes === undefined) continue;
+      const path = join(root, name);
+      await writeFile(path, bytes, { flag: 'wx', mode: 0o600 }); created.push(path); artifacts[kind] = path;
+    }
+  } catch (error) { await Promise.allSettled(created.map(path => unlink(path))); throw error; }
+  return { result, artifacts };
+}

package/src/skill-sync-worker.js

@@ -1,14 +1,23 @@
 import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { resolveRuntimeProfile } from './runtime/profiles.js';
+import { getCurrentProfileName, loadConfig, resolveRuntimeProfile } from './runtime/profiles.js';
 import { ensureFreshOAuthCredential } from './runtime/oauth.js';
 import { runSkillSync, fetchSyncSettings } from '../dist/skill-sync/index.js';
 import { withSkillSyncLock } from './runtime/sync-skills.js';
 
+function currentCliProfile() {
+  try {
+    return getCurrentProfileName(loadConfig());
+  } catch {
+    return null;
+  }
+}
+
 export async function runAutomaticSkillSync({ profile, apiBase, userId }, {
   resolveRuntime = resolveRuntimeProfile, refresh = ensureFreshOAuthCredential,
   settings = fetchSyncSettings, sync = runSkillSync, lock = withSkillSyncLock,
+  currentProfile = currentCliProfile,
 } = {}) {
   const runtime = resolveRuntime({ profile }, { requireAuth: true });
   if (runtime.credentialKind !== 'oauth' || runtime.apiBase !== apiBase
@@ -18,9 +27,12 @@ export async function runAutomaticSkillSync({ profile, apiBase, userId }, {
   if (saved.user_id !== userId) throw new Error('Automatic skill sync identity mismatch');
   // Do not gather, unlink foreign accounts or write anything when opted out.
   if (!saved.sync_enabled) return { status: 'disabled' };
+  // The service stays bound to its profile; after `notis profile use` moves the
+  // default away, it keeps that account's folder in sync without linking it.
+  const linkAgentFolders = (currentProfile() ?? profile) === profile;
   const result = await lock(() => sync(runtime.apiBase, runtime.jwt, {
     fetchSyncSettings: async () => saved,
-  }, { honorSyncEnabled: true }));
+  }, { honorSyncEnabled: true, ...(linkAgentFolders ? {} : { linkAgentFolders: false }) }));
   return { status: (result.failedLinks?.length || result.failedPushes?.length) ? 'partial' : 'synced', ...result };
 }