@notis_ai/cli 0.2.0-beta.157.1 → 0.2.0-beta.159.1

package/package.json

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

package/src/cli.js

@@ -10,6 +10,7 @@ import { reportCliCommand } from './runtime/telemetry.js';
 import { reconcileBaseSkillsBestEffort } from './runtime/base-skills.js';
 import { detectedAgentIds } from './runtime/agent-setup.js';
 import { withSkillSyncLock } from './runtime/sync-skills.js';
+import { maybeInstallSkillSyncService } from './runtime/skill-sync-service.js';
 import {
   CHANNEL_SWITCH_ENV,
   resolveChannelSwitch,
@@ -188,6 +189,9 @@ function attachSpec(program, parentMap, spec, specs, launchContext = {}) {
         ...launchContext,
       });
       process.exitCode = typeof exitCode === 'number' ? exitCode : 0;
+      if (process.exitCode === 0 && !['logout', 'agent-context', 'agent-capture'].includes(spec.command_path[0])) {
+        await maybeInstallSkillSyncService(runtime).catch(() => undefined);
+      }
       await reportCliCommand({
         spec,
         runtime,

package/src/command-specs/diagnostics.js

@@ -47,6 +47,8 @@ async function discoverSupabaseSqlTool(runtime) {
   const match = names.find((name) => (
     name.toUpperCase().includes('SUPABASE')
     && name.toUpperCase().includes('EXECUTE_SQL')
+    && name.toUpperCase().includes('NOTIS_APP')
+    && !name.toUpperCase().includes('WEBSITE')
   ));
   if (!match) {
     throw usageError('No connected Supabase execute-SQL capability was discovered. Run `notis tools link mcp_supabase_notis_app`.');
@@ -606,7 +608,42 @@ async function debugWorkerIdentityHandler(ctx) {
   });
 }
 
+export function buildProcessDiagnosticsSql(reference) {
+  if (typeof reference !== 'string' || !reference.trim() || reference.length > 256) {
+    throw usageError('An interaction id of 1–256 characters is required.');
+  }
+  return `BEGIN READ ONLY; SET LOCAL request.jwt.claim.role='service_role'; SELECT public.notis_process_diagnostics_v1(${sqlLiteral(reference)}) AS diagnostic; COMMIT;`;
+}
+
+async function debugProcessHandler(ctx) {
+  const execution = await executeReadOnlySql(ctx, buildProcessDiagnosticsSql(ctx.args.interactionId), 'process');
+  const raw = execution.rows[0]?.diagnostic;
+  const diagnostic = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  if (!diagnostic || diagnostic.definition_version !== 1 || diagnostic.status) {
+    throw usageError(`Process diagnostics unavailable: ${diagnostic?.status || 'invalid response'}.`);
+  }
+  if (diagnostic.interaction_id !== ctx.args.interactionId) throw usageError('Crossed diagnostic identity.');
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '), data: diagnostic, requestId: execution.requestId,
+    humanSummary: `${diagnostic.user_outcome}; ${diagnostic.handling}; ${diagnostic.reason_code || 'no incident'}.`,
+    meta: { mutating: false, sql_tool: execution.toolName },
+    renderHuman: () => JSON.stringify(diagnostic, null, 2),
+  });
+}
+
 export const diagnosticCommandSpecs = [
+  {
+    command_path: ['debug', 'process'],
+    summary: 'Read receipt-backed process diagnostics for one interaction.',
+    when_to_use: 'Correlate an interaction with Temporal runs, private failure references, delivery and settlement.',
+    args_schema: { arguments: [{ token: '<interaction-id>', key: 'interactionId', description: 'Exact interaction id.' }], options: [] },
+    examples: ['notis debug process interaction_123 --json'],
+    output_schema: 'Versioned, content-free logical outcome, handling, workflow/run and evidence references.',
+    mutates: false, idempotent: true,
+    related_commands: ['notis debug worker-identity', 'notis debug trace-cost <trace-or-interaction>'],
+    backend_call: { type: 'tool-discovery', name: 'Supabase execute SQL capability' },
+    handler: debugProcessHandler,
+  },
   {
     command_path: ['debug', 'user-context'],
     summary: 'Resolve a user’s effective redacted runtime and billing context.',

package/src/command-specs/skills.js

@@ -1,25 +1,43 @@
 import { getJwtSubject } from '../runtime/profiles.js';
 import { reconcileAllSkills } from '../runtime/sync-skills.js';
+import { ensureFreshOAuthCredential } from '../runtime/oauth.js';
+import { installSkillSyncService } from '../runtime/skill-sync-service.js';
 
 async function loadSkillSyncEngine() {
   return import('../../dist/skill-sync/index.js');
 }
 
-async function syncSkillsHandler(ctx) {
+export async function syncSkillsHandler(ctx, {
+  refresh = ensureFreshOAuthCredential, loadEngine = loadSkillSyncEngine,
+  reconcile = reconcileAllSkills, install = installSkillSyncService,
+} = {}) {
+  await refresh(ctx.runtime);
   const userId = ctx.runtime.oauthUserId || getJwtSubject(ctx.runtime.jwt);
-  const { runSkillSync } = await loadSkillSyncEngine();
-  const result = await reconcileAllSkills({
+  const { runSkillSync, fetchSyncSettings } = await loadEngine();
+  const settings = await fetchSyncSettings(ctx.runtime.apiBase, ctx.runtime.jwt);
+  const result = await reconcile({
     serverUrl: ctx.runtime.apiBase,
     jwt: ctx.runtime.jwt,
-    userId,
+    userId: settings.user_id || userId,
     honorSyncEnabled: Boolean(ctx.options.electronRepeat),
-    runAccountSync: runSkillSync,
+    runAccountSync: (serverUrl, jwt, dependencies, options) => runSkillSync(
+      serverUrl, jwt, { ...dependencies, fetchSyncSettings: async () => settings }, options,
+    ),
   });
+  if (settings.sync_enabled && !ctx.options.electronRepeat) {
+    try {
+      result.automaticSync = await install(ctx.runtime);
+    } catch (error) {
+      result.automaticSync = { status: 'error', message: error.message };
+    }
+  }
 
   const failures = [...(result.failedPushes || []), ...(result.failedLinks || [])];
   return ctx.output.emitSuccess({
     command: 'skills sync',
     data: result,
+    warnings: result.automaticSync?.status === 'error'
+      ? [`Skills synced, but automatic refresh could not start: ${result.automaticSync.message}`] : [],
     humanSummary: failures.length ? `Skill sync completed with ${failures.length} reported failures; inspect failedPushes and failedLinks.` : result.syncEnabled
       ? `Synced account skills and kept ${result.baseSkills.length} base skills current.`
       : `Automatic Desktop sync is off; kept ${result.baseSkills.length} base skills current.`,

package/src/runtime/profiles.js

@@ -228,8 +228,11 @@ function processIsAlive(pid) {
   try {
     process.kill(pid, 0);
     return true;
-  } catch {
-    return false;
+  } catch (error) {
+    // Sandboxed children may be allowed to observe the worktree lease but not
+    // signal its dev.sh supervisor. POSIX EPERM proves that the PID exists;
+    // ESRCH (and every other probe failure) does not.
+    return error?.code === 'EPERM';
   }
 }
 

package/src/runtime/skill-sync/cloud-client.ts

@@ -9,6 +9,7 @@ async function requestJson<T>(
   options: { method?: string; body?: JsonBody } = {},
 ): Promise<T> {
   const response = await fetch(url, {
+    signal: AbortSignal.timeout(90_000),
     method: options.method || 'POST',
     headers: {
       'Content-Type': 'application/json',
@@ -59,7 +60,7 @@ export async function pushChangedSkills(
 }
 
 export async function downloadSkillBundle(bundleUrl: string): Promise<Buffer> {
-  const response = await fetch(bundleUrl);
+  const response = await fetch(bundleUrl, { signal: AbortSignal.timeout(90_000) });
   if (!response.ok) {
     const text = await response.text();
     throw new Error(`GET ${bundleUrl} → ${response.status}: ${text}`);

package/src/runtime/skill-sync/index.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import type {
   AgentTargets,
   LocalSkill,
@@ -33,6 +34,7 @@ import {
 } from "./symlink-manager";
 import { getPushCandidates } from "./sync-plan";
 import { writeCloudSkillWithBundleFallback } from "./write-cloud-skill";
+export { fetchSyncSettings } from './cloud-client';
 
 export interface RunSkillSyncResult {
   syncEnabled: boolean;
@@ -147,7 +149,17 @@ function decodeJwtSubject(jwt: string): string | null {
   }
 }
 
-function shouldWriteCloudSkill(
+function cloudContentHash(skill: SyncPullResponse['skills'][number]): string {
+  return createHash('sha256').update(JSON.stringify({
+    md: skill.skill_md,
+    hash: skill.skill_folder_hash,
+    source: skill.skill_source_url,
+    files: skill.bundle_files?.slice().sort((a, b) => a.path.localeCompare(b.path)),
+    hydrationFailed: skill.bundle_hydration_failed === true,
+  })).digest('hex');
+}
+
+export function shouldWriteCloudSkill(
   cloudSkill: SyncPullResponse["skills"][number],
   localSkills: Map<string, LocalSkill>,
   previousState: NotisSyncState,
@@ -159,17 +171,20 @@ function shouldWriteCloudSkill(
     return true;
   }
 
+  const previous = previousState.skills[skillName];
+  if (previous?.folderHash === localSkill.folderHash
+    && previous.cloudContentHash === cloudContentHash(cloudSkill)) return false;
+
   if (cloudSkill.source === "curated") {
     return cloudHash ? cloudHash !== localSkill.folderHash : true;
   }
 
-  const previous = previousState.skills[skillName];
   const localChangedSinceLastSync =
     !previous || previous.folderHash !== localSkill.folderHash;
   return (
     !localChangedSinceLastSync &&
-    Boolean(cloudHash) &&
-    cloudHash !== localSkill.folderHash
+    ((Boolean(cloudHash) && cloudHash !== localSkill.folderHash)
+      || Boolean(previous?.cloudContentHash && previous.cloudContentHash !== cloudContentHash(cloudSkill)))
   );
 }
 
@@ -178,6 +193,7 @@ function buildSyncState(
   localSkills: LocalSkill[],
   lastSyncedAt: string | null,
   verifiedAgentLinks: Record<string, Partial<AgentTargets>> = {},
+  failedContentNames: ReadonlySet<string> = new Set(),
 ): NotisSyncState {
   const localSkillMap = toSkillMap(localSkills);
   const skills = Object.fromEntries(
@@ -191,6 +207,8 @@ function buildSyncState(
           agentTargets: normalizeAgentTargets(skill.agent_targets),
           verifiedAgentLinks: skill.status === "active" ? verifiedAgentLinks[skill.name] ?? {} : {},
           cloudUpdatedAt: skill.updated_at,
+          ...(!failedContentNames.has(skill.name) && !skill.skill_source_url
+            ? { cloudContentHash: cloudContentHash(skill) } : {}),
           syncedAt: lastSyncedAt || new Date().toISOString(),
         },
       ];
@@ -392,7 +410,7 @@ export async function materializeCloudSkillsForLocalShell(
   for (const failure of failedDownloads) delete verifiedLinks[failure.name];
 
   await deps.writeSyncState(
-    buildSyncState(pullResponse, finalLocalSkills, lastSyncedAt, verifiedLinks),
+    buildSyncState(pullResponse, finalLocalSkills, lastSyncedAt, verifiedLinks, new Set(failedDownloads.map(item => item.name))),
     syncPaths,
   );
 
@@ -629,7 +647,7 @@ export async function runSkillSync(
   const lastSyncedAt = pullResponse.last_synced_at || new Date().toISOString();
 
   await deps.writeSyncState(
-    buildSyncState(pullResponse, finalLocalSkills, lastSyncedAt, verifiedLinks),
+    buildSyncState(pullResponse, finalLocalSkills, lastSyncedAt, verifiedLinks, new Set(failedDownloads.map(item => item.name))),
     syncPaths,
   );
 

package/src/runtime/skill-sync/types.ts

@@ -12,6 +12,8 @@ export interface SyncedSkill {
   /** Actual readable managed links, never inferred from desired targets. */
   verifiedAgentLinks?: Partial<AgentTargets>;
   cloudUpdatedAt?: string;
+  /** Content accepted on disk; independent of server-specific folder hash formats. */
+  cloudContentHash?: string;
   syncedAt: string;
 }
 

package/src/runtime/skill-sync-service.js

@@ -0,0 +1,109 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isValidProfileName, loadConfig } from './profiles.js';
+import { withSkillSyncLock } from './sync-skills.js';
+
+export const SKILL_SYNC_SERVICE_LABEL = 'ai.notis.skills-sync';
+const bundlePath = fileURLToPath(new URL('../../dist/skill-sync-worker.mjs', import.meta.url));
+
+function atomicWrite(target, value, mode = 0o600) {
+  mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${process.pid}.tmp`;
+  writeFileSync(temporary, value, { mode });
+  renameSync(temporary, target);
+}
+
+function xml(value) {
+  return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+}
+
+export async function maybeInstallSkillSyncService(runtime, {
+  config = loadConfig(), install = installSkillSyncService,
+  fetchSettings, refresh,
+} = {}) {
+  if (process.platform !== 'darwin' || runtime.credentialKind !== 'oauth'
+    || config.current_profile !== runtime.profileName
+    || !['https://api.notis.ai', 'https://api-beta.notis.ai'].includes(runtime.apiBase)) return;
+  // Ordinary commands must not steal another explicitly bound account's job.
+  const plist = join(homedir(), 'Library', 'LaunchAgents', `${SKILL_SYNC_SERVICE_LABEL}.plist`);
+  if (existsSync(plist)) {
+    const saved = readFileSync(plist, 'utf8');
+    if (runtime.oauthUserId && [runtime.profileName, runtime.apiBase, runtime.oauthUserId]
+      .every(value => saved.includes(`<string>${xml(value)}</string>`))) return install(runtime);
+    return;
+  }
+  const refreshCredential = refresh || (await import('./oauth.js')).ensureFreshOAuthCredential;
+  await refreshCredential(runtime);
+  const getSettings = fetchSettings || (await import('../../dist/skill-sync/index.js')).fetchSyncSettings;
+  const settings = await getSettings(runtime.apiBase, runtime.jwt);
+  if (settings.sync_enabled && settings.user_id === runtime.oauthUserId) return install(runtime);
+}
+
+export async function installSkillSyncService(runtime, options = {}) {
+  if ((options.platform || process.platform) !== 'darwin') return { status: 'unsupported_platform' };
+  if (runtime.credentialKind !== 'oauth' || !runtime.oauthUserId
+    || !['https://api.notis.ai', 'https://api-beta.notis.ai'].includes(runtime.apiBase)) {
+    return { status: 'skipped_non_personal_profile' };
+  }
+  // Registration upgrades must not kill a worker holding the filesystem lock,
+  // nor race another CLI registering the same LaunchAgent.
+  return withSkillSyncLock(() => installSkillSyncServiceLocked(runtime, options),
+    options.home ? { home: options.home } : {});
+}
+
+async function installSkillSyncServiceLocked(runtime, {
+  home = homedir(), platform = process.platform, nodePath = process.execPath,
+  source = bundlePath, run = spawnSync, uid = process.getuid?.(),
+} = {}) {
+  // A single explicitly selected personal account owns global agent folders.
+  // Development and hosted credentials must never enroll a machine-wide job.
+  if (platform !== 'darwin') return { status: 'unsupported_platform' };
+  if (runtime.credentialKind !== 'oauth' || runtime.envCredentialOverride
+    || !isValidProfileName(runtime.profileName)
+    || !['https://api.notis.ai', 'https://api-beta.notis.ai'].includes(runtime.apiBase)) {
+    return { status: 'skipped_non_personal_profile' };
+  }
+  const root = join(home, '.notis', 'skills', 'service');
+  const bundle = readFileSync(source);
+  const digest = createHash('sha256').update(bundle).digest('hex');
+  const installedBundle = join(root, 'runtime', digest, 'worker.mjs');
+  if (!existsSync(installedBundle)
+    || !readFileSync(installedBundle).equals(bundle)) atomicWrite(installedBundle, bundle, 0o500);
+  const args = [nodePath, installedBundle, runtime.profileName, runtime.apiBase, runtime.oauthUserId];
+  if (!runtime.oauthUserId) return { status: 'skipped_missing_account' };
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>${SKILL_SYNC_SERVICE_LABEL}</string>
+<key>ProgramArguments</key><array>${args.map(value => `<string>${xml(value)}</string>`).join('')}</array>
+<key>WorkingDirectory</key><string>${xml(root)}</string>
+<key>StartInterval</key><integer>60</integer>
+<key>ProcessType</key><string>Background</string>
+</dict></plist>
+`;
+  const plistPath = join(home, 'Library', 'LaunchAgents', `${SKILL_SYNC_SERVICE_LABEL}.plist`);
+  const domain = `gui/${uid}`;
+  const target = `${domain}/${SKILL_SYNC_SERVICE_LABEL}`;
+  const unchanged = existsSync(plistPath) && readFileSync(plistPath, 'utf8') === plist;
+  const loaded = run('/bin/launchctl', ['print', target], { encoding: 'utf8', timeout: 5000 });
+  if (unchanged && loaded.status === 0) return { status: 'installed', intervalSeconds: 60, profile: runtime.profileName };
+  if (loaded.status === 0) {
+    const stopped = run('/bin/launchctl', ['bootout', target], { encoding: 'utf8', timeout: 5000 });
+    if (stopped.status !== 0) throw new Error('Could not update the existing automatic skill sync job');
+  }
+  atomicWrite(plistPath, plist);
+  let started;
+  // launchd may finish tearing down an old registration after bootout returns.
+  for (let attempt = 0; attempt < 10; attempt++) {
+    started = run('/bin/launchctl', ['bootstrap', domain, plistPath], { encoding: 'utf8', timeout: 5000 });
+    if (started.status === 0) break;
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  if (started?.status !== 0) throw new Error('Could not register automatic skill sync with macOS');
+  return { status: 'installed', intervalSeconds: 60, profile: runtime.profileName };
+}

package/src/skill-sync-worker-entry.js

@@ -0,0 +1,2 @@
+import { main } from './skill-sync-worker.js';
+await main();

package/src/skill-sync-worker.js

@@ -0,0 +1,50 @@
+import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { 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';
+
+export async function runAutomaticSkillSync({ profile, apiBase, userId }, {
+  resolveRuntime = resolveRuntimeProfile, refresh = ensureFreshOAuthCredential,
+  settings = fetchSyncSettings, sync = runSkillSync, lock = withSkillSyncLock,
+} = {}) {
+  const runtime = resolveRuntime({ profile }, { requireAuth: true });
+  if (runtime.credentialKind !== 'oauth' || runtime.apiBase !== apiBase
+    || runtime.oauthUserId !== userId) throw new Error('Automatic skill sync account changed; run notis skills sync to rebind');
+  await refresh(runtime);
+  const saved = await settings(runtime.apiBase, runtime.jwt);
+  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' };
+  const result = await lock(() => sync(runtime.apiBase, runtime.jwt, {
+    fetchSyncSettings: async () => saved,
+  }, { honorSyncEnabled: true }));
+  return { status: (result.failedLinks?.length || result.failedPushes?.length) ? 'partial' : 'synced', ...result };
+}
+
+export async function main(args = process.argv.slice(2)) {
+  const [profile, apiBase, userId] = args;
+  const root = join(homedir(), '.notis', 'skills', 'service');
+  const record = (value) => {
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const target = join(root, 'status.json');
+    const temporary = `${target}.${process.pid}.tmp`;
+    writeFileSync(temporary, JSON.stringify({ ...value, profile, at: new Date().toISOString() }, null, 2), { mode: 0o600 });
+    renameSync(temporary, target);
+  };
+  const deadline = setTimeout(() => {
+    record({ status: 'error', code: 'sync_timeout' });
+    process.exit(1);
+  }, 240_000);
+  try {
+    record(await runAutomaticSkillSync({ profile, apiBase, userId }));
+  } catch (error) {
+    // Persist only a classified error, never a bearer, signed URL or response body.
+    record({ status: 'error', code: error.code || 'sync_failed' });
+    process.exitCode = 1;
+  } finally {
+    clearTimeout(deadline);
+  }
+}

package/template/packages/sdk/src/components/MultiSelectActionBar.tsx

@@ -9,7 +9,8 @@ import React, {
   type ReactElement,
 } from 'react';
 import type { ResolvedCollectionAction } from '../interactions/actions';
-import { shortcutDisplay, useShortcuts, type ShortcutDefinition } from '../interactions/shortcuts';
+import { activateShortcutCollection, shortcutDisplay, useShortcuts, type ShortcutDefinition } from '../interactions/shortcuts';
+import { isInteractionElementVisible } from '../interactions/visibility';
 import type { ShortcutScope } from '../interactions/shortcuts';
 
 export type MultiSelectAction = ResolvedCollectionAction;
@@ -34,6 +35,9 @@ export interface MultiSelectActionBarProps {
   shortcutsEnabled?: boolean;
   /** Override the default collection shortcut scope. */
   shortcutScope?: ShortcutScope;
+  collectionOwnerId?: string;
+  isAvailable?: () => boolean;
+  onClearSelection?: () => void;
 }
 
 const containerBaseStyle: CSSProperties = {
@@ -114,7 +118,7 @@ const iconSlotStyle: CSSProperties = {
   display: 'inline-flex',
   alignItems: 'center',
   justifyContent: 'center',
-  opacity: 0.8,
+  color: 'inherit',
 };
 
 export function MultiSelectActionBar({
@@ -125,6 +129,9 @@ export function MultiSelectActionBar({
   style,
   shortcutsEnabled = true,
   shortcutScope = 'collection',
+  collectionOwnerId,
+  isAvailable,
+  onClearSelection,
 }: MultiSelectActionBarProps): ReactElement | null {
   const barRef = useRef<HTMLDivElement>(null);
   const visible = selectedCount > 0;
@@ -142,24 +149,35 @@ export function MultiSelectActionBar({
         }));
       }
     };
-    const update = () => report(true);
+    const update = () => report(isAvailable?.() !== false && isInteractionElementVisible(bar));
     update();
     const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(update);
     observer?.observe(bar);
+    const VisibilityObserver = bar.ownerDocument.defaultView?.MutationObserver;
+    const visibilityObserver = VisibilityObserver ? new VisibilityObserver(update) : null;
+    let element: Element | null = bar;
+    while (element) {
+      visibilityObserver?.observe(element, { attributes: true, attributeFilter: element === bar.ownerDocument.documentElement ? ['hidden', 'inert', 'aria-hidden', 'class'] : ['hidden', 'inert', 'aria-hidden', 'style', 'class'] });
+      const root: Node = element.getRootNode();
+      element = element.parentElement ?? ('host' in root ? (root as ShadowRoot).host : null);
+    }
     return () => {
       observer?.disconnect();
+      visibilityObserver?.disconnect();
       report(false);
     };
-  }, [visible]);
+  }, [isAvailable, visible]);
 
   const actionShortcuts = useMemo<ShortcutDefinition[]>(() => {
     return actions.flatMap((action): ShortcutDefinition[] => {
-        if (!action.shortcut || action.disabled || action.pending) return [];
+        if (!action.shortcut) return [];
         return [{
           id: `collection.action.${action.id}`,
           keys: action.shortcut,
           label: action.label,
-          onTrigger: () => action.onRun(),
+          allowRepeat: Boolean(action.disabled || action.pending),
+          // Keep advertised keys owned while disabled/pending; never fall through to another action.
+          onTrigger: () => { if (!action.disabled && !action.pending) action.onRun(); },
         }];
       });
   }, [actions]);
@@ -167,6 +185,8 @@ export function MultiSelectActionBar({
     enabled: shortcutsEnabled && selectedCount > 0,
     scope: shortcutScope,
     priority: 25,
+    collectionOwnerId,
+    isAvailable: () => isAvailable?.() !== false && isInteractionElementVisible(barRef.current),
   });
 
   if (selectedCount === 0) return null;
@@ -186,6 +206,14 @@ export function MultiSelectActionBar({
     <div
       ref={barRef}
       data-notis-bulk-actions
+      onFocusCapture={() => { if (collectionOwnerId) activateShortcutCollection(collectionOwnerId); }}
+      onMouseDownCapture={() => { if (collectionOwnerId) activateShortcutCollection(collectionOwnerId); }}
+      onKeyDown={(event) => {
+        if (event.key !== 'Escape' || !shortcutsEnabled || !onClearSelection || isAvailable?.() === false) return;
+        event.preventDefault();
+        event.stopPropagation();
+        onClearSelection();
+      }}
       role="toolbar"
       aria-label={`Bulk actions for ${selectedCount} selected ${countWord}`}
       className={className}
@@ -199,10 +227,11 @@ export function MultiSelectActionBar({
           [data-notis-bulk-divider] { display: none; }
           [data-notis-bulk-action-list] { width: 100%; }
           [data-notis-bulk-actions] button { min-height: 48px; font-size: 16px !important; }
+        }
+        @media (hover: none) and (pointer: coarse) {
           [data-notis-bulk-actions] kbd { display: none !important; }
           [data-notis-bulk-action-icon][data-has-shortcut] { display: inline-flex !important; }
         }
-        @media (hover: none) { [data-notis-bulk-actions] kbd { display: none !important; } }
       `}</style>
       <span data-notis-bulk-count style={countStyle}>{countLabel}</span>
       {actions.length > 0 ? <span data-notis-bulk-divider aria-hidden style={dividerStyle} /> : null}

package/template/packages/sdk/src/components/MultiSelectCheckbox.tsx

@@ -23,7 +23,9 @@ const baseStyle: CSSProperties = {
   width: '16px',
   height: '16px',
   borderRadius: '4px',
-  border: '1px solid hsl(var(--border))',
+  borderWidth: '1px',
+  borderStyle: 'solid',
+  borderColor: 'hsl(var(--border))',
   background: 'transparent',
   color: 'hsl(var(--primary-foreground))',
   cursor: 'pointer',