@notis_ai/cli 0.2.17 → 0.2.19

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

@@ -1,11 +1,18 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
 import type {
+  AgentTargets,
   LocalSkill,
   NotisSyncState,
   SkillSyncFailure,
   SyncPullResponse,
   SyncSettings,
+  SyncedSkill,
 } from "./types";
 import { normalizeAgentTargets } from "./types";
+import { assertNativePull, checkedNativeReference, isNativeSkill, nativeState } from './native-identity';
+import { bindNativeFolders, hasNativeFolderHistory, nativeLinkRows, nativeLocalReady, pendingLegacyUpgrade, previousNativeState, retainMissingNativeState } from './native-plan';
 import {
   downloadSkillBundle,
   fetchSyncSettings,
@@ -30,8 +37,9 @@ import {
   syncSymlinks,
   type DeletedAgentSymlink,
 } from "./symlink-manager";
-import { getPushCandidates } from "./sync-plan";
+import { getPushCandidates, selectCloudSkillsToApply } from "./sync-plan";
 import { writeCloudSkillWithBundleFallback } from "./write-cloud-skill";
+export { fetchSyncSettings } from './cloud-client';
 
 export interface RunSkillSyncResult {
   syncEnabled: boolean;
@@ -49,15 +57,22 @@ export interface RunSkillSyncResult {
   /** Skills the server rejected (e.g. an invalid SKILL.md description). The rest of
    * the batch still syncs; these are surfaced so the user knows what to fix. */
   failedPushes: SkillSyncFailure[];
+  failedLinks?: SkillSyncFailure[];
 }
 
 export interface RunSkillSyncOptions {
   /** Electron's scheduled invocation honors the account preference. A manual
    * CLI sync always runs, even when automatic Desktop refresh is disabled. */
   honorSyncEnabled?: boolean;
+  /** All account paths, scanner roots and agent links use this explicit home. */
+  syncHome?: string;
+  /** False when another account is the CLI default: sync this account's own
+   * folder only and leave the agent folders (Claude Code, Codex, Cursor) to the
+   * default's skills. Defaults to true. */
+  linkAgentFolders?: boolean;
 }
 
-const BASE_SKILL_NAMES = new Set(['notis-apps', 'notis-query', 'notis-cli']);
+const BASE_SKILL_NAMES = new Set(['notis-spaces', 'notis-query', 'notis-cli']);
 
 function withoutBaseSkills(pullResponse: SyncPullResponse): SyncPullResponse {
   return {
@@ -76,14 +91,21 @@ function withoutBaseSkillState(state: NotisSyncState): NotisSyncState {
 }
 
 export interface MaterializeCloudSkillsResult {
+  /** Cloud skills verified present in the final scoped disk scan. */
+  materializedSkillNames: string[];
   pulled: number;
   downloaded: number;
   deleted: number;
   removed: number;
   lastSyncedAt: string | null;
+  failedLinks?: SkillSyncFailure[];
 }
 
 export interface MaterializeCloudSkillsOptions {
+  /** Server-verified Notis identity, when Desktop's auth subject differs. */
+  canonicalUserId?: string;
+  /** Previously authenticated settings must agree with the pull before I/O. */
+  syncSettings?: SyncSettings;
   /** Re-link only these cloud skills without removing or adopting other links. */
   relinkSkillNames?: readonly string[];
 }
@@ -125,6 +147,74 @@ const DEFAULT_RUN_SKILL_SYNC_DEPS: RunSkillSyncDependencies = {
   removeForeignAccountSymlinks,
   updateAgentTargets,
 };
+
+// Another account is the CLI default and owns the agent folders: this account
+// syncs its own folder without linking, unlinking or adopting anything there.
+const MIRROR_ONLY_DEPS: Pick<
+  RunSkillSyncDependencies,
+  'removeForeignAccountSymlinks' | 'removeAllSymlinksForSkill' | 'syncSymlinks'
+> = {
+  removeForeignAccountSymlinks: async () => 0,
+  removeAllSymlinksForSkill: async () => 0,
+  syncSymlinks: async () => ({ linked: 0, removed: 0, skipped: 0, verifiedAgentLinks: {} }),
+};
+
+/**
+ * The account linking now owns the agent folders, so the links the other
+ * accounts on this computer last verified are gone. Forget them: otherwise that
+ * account's next linking sync would read each missing link as the user removing
+ * the skill and deactivate it.
+ */
+async function forgetOtherAccountsAgentLinks(
+  paths: ReturnType<typeof getSkillSyncPathsForUser>,
+): Promise<void> {
+  const usersDir = dirname(dirname(paths.syncStatePath));
+  let entries: import('node:fs').Dirent[];
+  try {
+    entries = await fs.readdir(usersDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const statePath = join(usersDir, entry.name, '.notis-sync.json');
+    if (statePath === paths.syncStatePath) continue;
+    let state: { skills?: Record<string, { verifiedAgentLinks?: unknown }> } | null = null;
+    try {
+      state = JSON.parse(await fs.readFile(statePath, 'utf8'));
+    } catch {
+      continue;
+    }
+    if (!state || typeof state !== 'object' || !state.skills || typeof state.skills !== 'object') continue;
+    let changed = false;
+    for (const skill of Object.values(state.skills)) {
+      if (skill && typeof skill === 'object' && 'verifiedAgentLinks' in skill) {
+        delete skill.verifiedAgentLinks;
+        changed = true;
+      }
+    }
+    if (!changed) continue;
+    const temporaryPath = `${statePath}.${process.pid}.${Date.now()}.tmp`;
+    await fs.writeFile(temporaryPath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+    await fs.rename(temporaryPath, statePath);
+  }
+}
+
+export function isolatedLinkOptions(paths: ReturnType<typeof getSkillSyncPathsForUser>) {
+  if (!paths.isolatedNamespace && !paths.homeDir) return undefined;
+  const root = paths.isolatedNamespace
+    ? join(paths.syncRoot, 'environments', paths.isolatedNamespace, 'agents') : paths.homeDir!;
+  return { agentSkillDirs: { notis: paths.skillsDir, claude_code: join(root, '.claude', 'skills'),
+    cursor: join(root, '.cursor', 'skills'), codex: join(root, '.codex', 'skills') },
+    legacyGlobalSkillsDir: join(root, '.agents', 'skills') };
+}
+
+function assertSyncEnvironment(pull: SyncPullResponse, settings: SyncSettings): void {
+  if ((pull.sync_namespace || null) !== (settings.sync_namespace || null)
+      || (settings.sync_scope !== undefined && pull.sync_scope !== settings.sync_scope)) {
+    throw new Error('Skill sync environment changed. Existing mirrors were retained.');
+  }
+}
 function toSkillMap(skills: LocalSkill[]): Map<string, LocalSkill> {
   return new Map(skills.map((skill) => [skill.name, skill]));
 }
@@ -144,7 +234,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,
@@ -156,46 +256,150 @@ function shouldWriteCloudSkill(
     return true;
   }
 
+  if (isNativeSkill(cloudSkill)) {
+    if (localSkill.nativeScope && localSkill.nativeScope !== cloudSkill.native_scope) return false;
+    if (nativeLocalReady(cloudSkill, localSkill)) return false;
+    const nativePrevious = previousNativeState(previousState, cloudSkill);
+    return (localSkill.nativeFilesCurrent === true && localSkill.folderHash === localSkill.nativeBaseFolderHash)
+      || (!localSkill.nativeReference && nativePrevious?.cloudId === cloudSkill.id
+          && nativePrevious.folderHash === localSkill.folderHash);
+  }
+
+  const previous = previousState.skills[skillName];
+  if (previous?.folderHash === localSkill.folderHash
+    && previous.cloudContentHash === cloudContentHash(cloudSkill)) return false;
+
+  // Without a stored content baseline (skills served through a signed source URL keep
+  // none, because that URL changes on every pull) the only other signal is
+  // `skill_folder_hash`, which the server does NOT always compute the way the local
+  // folder hash is computed. A bundle-entry hash can never equal the hash of the
+  // extracted directory, and comparing the two replaced the folder on every sync
+  // tick, deleting whatever a running skill had written inside it. Compare cloud against cloud instead: rewrite when the cloud
+  // revision we last applied has actually moved.
+  if (previous
+    && previous.cloudContentHash === undefined
+    && previous.cloudId === cloudSkill.id
+    && previous.appliedCloudFolderHash !== undefined
+    && previous.appliedCloudFolderHash === cloudHash
+    && previous.cloudUpdatedAt === cloudSkill.updated_at
+    && previous.folderHash === localSkill.folderHash) {
+    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)))
   );
 }
 
+type AppliedCloudRevisions = Record<string, string | undefined>;
+
+/**
+ * The cloud revision each folder's last successful write applied: this run's revision
+ * for the skills we just wrote, the previously recorded one otherwise. A failed write
+ * records nothing, so the next sync retries it.
+ */
+function collectAppliedCloudRevisions(
+  pullResponse: SyncPullResponse,
+  previousState: NotisSyncState,
+  writtenSkillNames: ReadonlySet<string>,
+): AppliedCloudRevisions {
+  const applied: AppliedCloudRevisions = {};
+  for (const skill of selectCloudSkillsToApply(pullResponse.skills)) {
+    applied[skill.name] = writtenSkillNames.has(skill.name)
+      ? skill.skill_folder_hash || ""
+      : previousState.skills[skill.name]?.appliedCloudFolderHash;
+  }
+  return applied;
+}
+
+/**
+ * The files each folder's last successful write put on disk: this run's list for the
+ * skills we just wrote, the previously recorded one otherwise. Missing means "no
+ * record", which keeps local files rather than deleting what cannot be attributed.
+ */
+function collectAppliedFiles(
+  pullResponse: SyncPullResponse,
+  previousState: NotisSyncState,
+  appliedFilesByName: Record<string, string[]>,
+): Record<string, string[] | undefined> {
+  const applied: Record<string, string[] | undefined> = {};
+  for (const skill of selectCloudSkillsToApply(pullResponse.skills)) {
+    applied[skill.name] = appliedFilesByName[skill.name]
+      ?? previousState.skills[skill.name]?.appliedFiles;
+  }
+  return applied;
+}
+
 function buildSyncState(
   pullResponse: SyncPullResponse,
   localSkills: LocalSkill[],
   lastSyncedAt: string | null,
+  verifiedAgentLinks: Record<string, Partial<AgentTargets>> = {},
+  failedContentNames: ReadonlySet<string> = new Set(),
+  appliedRevisions: AppliedCloudRevisions = {},
+  appliedFiles: Record<string, string[] | undefined> = {},
+  previousState: NotisSyncState = { version: 1, lastSyncedAt: null, skills: {} },
 ): NotisSyncState {
   const localSkillMap = toSkillMap(localSkills);
-  const skills = Object.fromEntries(
-    pullResponse.skills.map((skill) => {
+  // The same row selection the writer used, so the state describes the revision that
+  // is actually on disk rather than whichever duplicate row the server listed last.
+  const skills = Object.fromEntries<SyncedSkill>(
+    selectCloudSkillsToApply(pullResponse.skills).map((skill): [string, SyncedSkill] => {
       const localSkill = localSkillMap.get(skill.name);
+      const appliedCloudFolderHash = appliedRevisions[skill.name];
+      const appliedFileList = appliedFiles[skill.name];
+      if (pendingLegacyUpgrade(skill, localSkill, previousState)) {
+        // Keep the legacy baseline so the upgrade retries; never mark a usable folder unavailable.
+        const { nativeUnavailable: _unavailable, ...previous } = previousNativeState(previousState, skill)!;
+        return [skill.name, { ...previous, verifiedAgentLinks: verifiedAgentLinks[skill.name] ?? {} }];
+      }
+      if (isNativeSkill(skill) && !nativeLocalReady(skill, localSkill)) {
+        const previous = previousNativeState(previousState, skill);
+        return [skill.name, { ...(previous || {
+          cloudId: skill.id, folderHash: localSkill?.nativeBaseFolderHash || '',
+          agentTargets: normalizeAgentTargets(skill.agent_targets), syncedAt: lastSyncedAt || new Date().toISOString(),
+          ...(localSkill?.nativeReference ? { nativeReference: localSkill.nativeReference, nativeScope: localSkill.nativeScope } : {}),
+        }), nativeUnavailable: true, verifiedAgentLinks: {} }];
+      }
       return [
         skill.name,
         {
           cloudId: skill.id,
+          ...nativeState(skill),
           folderHash: localSkill?.folderHash || skill.skill_folder_hash || "",
           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) } : {}),
+          ...(appliedCloudFolderHash !== undefined ? { appliedCloudFolderHash } : {}),
+          ...(appliedFileList !== undefined ? { appliedFiles: appliedFileList } : {}),
           syncedAt: lastSyncedAt || new Date().toISOString(),
         },
       ];
     }),
   );
 
-  return {
+  for (const local of localSkills) {
+    if (!local.nativeReference || Object.values(skills).some(row => row.cloudId === local.cloudId)) continue;
+    skills[local.name] = { cloudId: local.cloudId!, nativeReference: local.nativeReference,
+      nativeScope: local.nativeScope, nativeUnavailable: true, verifiedAgentLinks: {},
+      folderHash: local.nativeBaseFolderHash || '', agentTargets: normalizeAgentTargets(),
+      syncedAt: lastSyncedAt || new Date().toISOString() };
+  }
+  return retainMissingNativeState(previousState, {
     version: 1,
     lastSyncedAt,
     skills,
-  };
+  });
 }
 
 function buildLocalSymlinkCandidates(
@@ -208,6 +412,10 @@ function buildLocalSymlinkCandidates(
   );
   const localOnlySkills = localSkills
     .filter((skill) => !cloudSkillNames.has(skill.name))
+    .filter(skill => !skill.nativeReference && !previousState.skills[skill.name]?.nativeReference
+      && !previousState.skills[skill.name]?.nativeUnavailable
+      && !hasNativeFolderHistory(previousState, skill.name)
+      && !/^native-[a-f0-9-]{36}$/.test(skill.name))
     .map((skill) => {
       const previous = previousState.skills[skill.name];
       return {
@@ -222,7 +430,7 @@ function buildLocalSymlinkCandidates(
       };
     });
 
-  return [...pullResponse.skills, ...localOnlySkills];
+  return [...nativeLinkRows(pullResponse, localSkills, previousState), ...localOnlySkills];
 }
 
 function isEmptySyncState(state: NotisSyncState): boolean {
@@ -268,6 +476,10 @@ async function writePulledSkillsToScopedMirror(
     RunSkillSyncDependencies,
     "downloadSkillBundle" | "writeCloudSkillToDisk"
   >,
+  failures: SkillSyncFailure[] = [],
+  writtenSkillNames: Set<string> = new Set(),
+  appliedFilesByName: Record<string, string[]> = {},
+  acknowledgedNative: ReadonlyMap<string, string> = new Map(),
 ): Promise<number> {
   const localSkillMap = toSkillMap(localSkills);
   const warnSkillSync = (message: string, error: unknown): void => {
@@ -275,20 +487,40 @@ async function writePulledSkillsToScopedMirror(
   };
 
   let downloaded = 0;
-  for (const cloudSkill of pullResponse.skills) {
-    if (!shouldWriteCloudSkill(cloudSkill, localSkillMap, previousState)) {
+  for (const cloudSkill of selectCloudSkillsToApply(pullResponse.skills)) {
+    const local = localSkillMap.get(cloudSkill.name);
+    const acknowledged = isNativeSkill(cloudSkill) && local && acknowledgedNative.get(cloudSkill.id) === local.folderHash;
+    // An unchanged pre-native folder has no applied-file record, so the files it shares
+    // with the incoming native Skill are the previous sync's output, not local edits.
+    const legacyBaseline = Boolean(local && pendingLegacyUpgrade(cloudSkill, local, previousState)
+      && previousNativeState(previousState, cloudSkill)?.folderHash === local.folderHash);
+    if (!acknowledged && !shouldWriteCloudSkill(cloudSkill, localSkillMap, previousState)) {
+      if (isNativeSkill(cloudSkill) && !nativeLocalReady(cloudSkill, local)) {
+        failures.push({ name: cloudSkill.name, error: 'Local native Skill changes were retained; resolve the version or identity conflict before using them.' });
+      }
       continue;
     }
 
-    if (
-      await writeCloudSkillWithBundleFallback(cloudSkill, {
-        downloadSkillBundle: deps.downloadSkillBundle,
-        writeCloudSkillToDisk: (skill, bundleBytes) =>
-          deps.writeCloudSkillToDisk(skill, bundleBytes, syncPaths),
-        onWarning: warnSkillSync,
-      })
-    ) {
+    const outcome = await writeCloudSkillWithBundleFallback(cloudSkill, {
+      downloadSkillBundle: deps.downloadSkillBundle,
+      writeCloudSkillToDisk: (skill, bundleBytes) =>
+        deps.writeCloudSkillToDisk(skill, bundleBytes, syncPaths, {
+          // What the last write put there. Everything else in the folder was
+          // produced locally and survives this one.
+          previouslyApplied: previousNativeState(previousState, skill)?.appliedFiles,
+          ...(isNativeSkill(skill) && local ? { expectedFolderHash: local.folderHash } : {}),
+          ...(legacyBaseline ? { legacyBaseline } : {}),
+        }),
+      onWarning: warnSkillSync,
+    });
+    if (outcome) {
       downloaded += 1;
+      writtenSkillNames.add(cloudSkill.name);
+      if (typeof outcome === "object" && Array.isArray(outcome.appliedFiles)) {
+        appliedFilesByName[cloudSkill.name] = outcome.appliedFiles;
+      }
+    } else {
+      failures.push({ name: cloudSkill.name, error: "Skill content could not be downloaded or written; sync will retry" });
     }
   }
 
@@ -298,6 +530,8 @@ async function writePulledSkillsToScopedMirror(
 function assertSkillsPullAuthorized(
   pullResponse: SyncPullResponse,
 ): void {
+  if (!Array.isArray(pullResponse.skills)) throw new Error('Skill inventory is unavailable; existing files were retained.');
+  assertNativePull(pullResponse);
   if (
     pullResponse.entitlement_access?.code === "entitlement_upgrade_required"
     && pullResponse.entitlement_access.entitlement === "skills"
@@ -340,42 +574,99 @@ export async function materializeCloudSkillsForLocalShell(
     );
   }
 
-  const syncPaths = getSkillSyncPathsForUser(authUserId);
-  const pullResponse = await deps.pullSkills(serverUrl, jwt);
+  let pullResponse = await deps.pullSkills(serverUrl, jwt);
   assertSkillsPullAuthorized(pullResponse);
+  if (options.syncSettings) assertSyncEnvironment(pullResponse, options.syncSettings);
+  const syncPaths = getSkillSyncPathsForUser(options.canonicalUserId?.trim() || authUserId, undefined, pullResponse.sync_namespace);
   const previousState = await deps.readSyncState(syncPaths);
 
   const localSkills = await deps.scanLocalSkills(syncPaths);
+  pullResponse = bindNativeFolders(pullResponse, localSkills, previousState);
+  const failedDownloads: SkillSyncFailure[] = [];
+  const writtenSkillNames = new Set<string>();
+  const appliedFilesByName: Record<string, string[]> = {};
   const downloaded = await writePulledSkillsToScopedMirror(
     pullResponse,
     localSkills,
     previousState,
     syncPaths,
     deps,
+    failedDownloads,
+    writtenSkillNames,
+    appliedFilesByName,
   );
   const finalLocalSkills = await deps.scanLocalSkills(syncPaths);
   const lastSyncedAt = pullResponse.last_synced_at || new Date().toISOString();
 
   const relinkSkillNames = new Set(options.relinkSkillNames || []);
+  const failures = [...failedDownloads];
+  const verifiedLinks: Record<string, Partial<AgentTargets>> = {};
+  for (const skill of pullResponse.skills) {
+    const previous = previousState.skills[skill.name];
+    if (skill.updated_at && previous?.cloudId === skill.id && previous.cloudUpdatedAt === skill.updated_at) {
+      verifiedLinks[skill.name] = { ...previous.verifiedAgentLinks };
+    }
+  }
   if (relinkSkillNames.size > 0) {
-    await deps.syncSymlinks(
-      pullResponse.skills.filter((skill) => relinkSkillNames.has(skill.name)),
+    const relinked = await deps.syncSymlinks(
+      nativeLinkRows(pullResponse, finalLocalSkills, previousState).filter((skill) => relinkSkillNames.has(skill.name)),
       syncPaths.skillsDir,
-      { removeUndesired: false },
+      { ...isolatedLinkOptions(syncPaths), removeUndesired: false },
     );
+    failures.push(...(relinked.failures ?? []).filter(
+      (failure) => !failedDownloads.some((download) => download.name === failure.name),
+    ));
+    for (const name of relinkSkillNames) {
+      verifiedLinks[name] = relinked.verifiedAgentLinks?.[name] ?? {};
+    }
   }
+  for (const failure of failedDownloads) delete verifiedLinks[failure.name];
 
-  await deps.writeSyncState(
-    buildSyncState(pullResponse, finalLocalSkills, lastSyncedAt),
-    syncPaths,
+  const materializedState = buildSyncState(
+    pullResponse, finalLocalSkills, lastSyncedAt, verifiedLinks,
+    new Set(failedDownloads.map(item => item.name)),
+    collectAppliedCloudRevisions(pullResponse, previousState, writtenSkillNames),
+    collectAppliedFiles(pullResponse, previousState, appliedFilesByName),
+    previousState,
   );
+  // Pull-only refresh is not an upload acknowledgement. Keep content baselines
+  // unless we actually wrote cloud content, and retain cloud-missing entries so
+  // the next two-way sync can delete them instead of uploading them as new.
+  for (const [name, entry] of Object.entries(materializedState.skills)) {
+    if (writtenSkillNames.has(name)) continue;
+    const previous = previousState.skills[name];
+    if (previous) {
+      entry.folderHash = previous.folderHash;
+      entry.cloudContentHash = previous.cloudContentHash;
+    } else {
+      delete materializedState.skills[name];
+    }
+  }
+  materializedState.skills = { ...previousState.skills, ...materializedState.skills };
+  let removed = 0;
+  for (const [name, previous] of Object.entries(previousState.skills)) {
+    if (!previous.nativeReference && !previous.nativeUnavailable) continue;
+    const current = pullResponse.skills.find(skill => skill.id === previous.cloudId);
+    const local = current && finalLocalSkills.find(row => row.name === current.name);
+    if (!current || (!nativeLocalReady(current, local) && !pendingLegacyUpgrade(current, local, previousState))) {
+      removed += await deps.removeAllSymlinksForSkill(name, syncPaths.skillsDir, isolatedLinkOptions(syncPaths));
+    }
+  }
+  await deps.writeSyncState(materializedState, syncPaths);
 
   return {
+    materializedSkillNames: pullResponse.skills
+      .filter((skill) => finalLocalSkills.some((local) => local.name === skill.name)
+        && (!isNativeSkill(skill) || (skill.status === 'active' && skill.agent_targets?.notis !== false
+          && nativeLocalReady(skill, finalLocalSkills.find(local => local.name === skill.name))))
+        && !failedDownloads.some((failure) => failure.name === skill.name))
+      .map((skill) => skill.name),
     pulled: pullResponse.skills.length,
     downloaded,
     deleted: 0,
-    removed: 0,
+    removed,
     lastSyncedAt,
+    ...(failures.length ? { failedLinks: failures } : {}),
   };
 }
 
@@ -397,6 +688,8 @@ async function deactivateDeletedAgentSkills(
     RunSkillSyncDependencies,
     "detectDeletedAgentSymlinks" | "updateAgentTargets" | "pullSkills"
   >,
+  failures: SkillSyncFailure[],
+  linkOptions?: ReturnType<typeof isolatedLinkOptions>,
 ): Promise<number> {
   // First sync (incl. legacy migration) has no reliable "we created this link" signal, so we
   // cannot tell a user deletion apart from a never-created link — skip detection entirely.
@@ -405,42 +698,18 @@ async function deactivateDeletedAgentSkills(
   }
 
   const deletions = await deps.detectDeletedAgentSymlinks(
-    pullResponse.skills,
+    pullResponse.skills.map(skill => {
+      const previous = isNativeSkill(skill) ? Object.entries(previousState.skills).find(([, row]) => row.cloudId === skill.id) : undefined;
+      return previous ? { ...skill, name: previous[0] } : skill;
+    }),
     previousState,
     skillsDir,
+    linkOptions,
   );
   if (deletions.length === 0) {
     return 0;
   }
 
-  // The agent-targets endpoint replaces the whole agent_targets column, so re-read the freshest
-  // values right before writing and merge onto them, only flipping the deleted agent. This avoids
-  // clobbering a concurrent portal/other-desktop change to a DIFFERENT agent with the stale
-  // snapshot from the top-of-sync pull. (A narrow read-modify-write window remains; the endpoint
-  // has no partial update.)
-  const latestSkillsById = new Map(pullResponse.skills.map((skill) => [skill.id, skill]));
-  let fresh: SyncPullResponse | null = null;
-  try {
-    fresh = await deps.pullSkills(serverUrl, jwt);
-  } catch (error) {
-    console.warn(
-      "[skill-sync] Could not re-pull latest agent targets before deactivation; " +
-        "using the top-of-sync snapshot.",
-      error,
-    );
-  }
-  if (fresh) {
-    // A transport failure may fall back to the already-authorized snapshot, but
-    // an explicit legacy denial must abort before any server or local mutation.
-    assertSkillsPullAuthorized(fresh);
-    for (const skill of fresh.skills) {
-      latestSkillsById.set(skill.id, skill);
-    }
-  }
-
-  // Group deletions by skill so multiple deleted agents for the SAME skill are flipped in one
-  // PATCH. Otherwise each PATCH, rebuilt from the same snapshot, would overwrite the previous one
-  // (deleting both claude_code and cursor for one skill would otherwise leave only the last off).
   const agentsBySkill = new Map<string, { skillName: string; agents: Set<DeletedAgentSymlink["agent"]> }>();
   for (const deletion of deletions) {
     const entry = agentsBySkill.get(deletion.skillId) ?? {
@@ -451,33 +720,47 @@ async function deactivateDeletedAgentSkills(
     agentsBySkill.set(deletion.skillId, entry);
   }
 
-  const inMemoryById = new Map(pullResponse.skills.map((skill) => [skill.id, skill]));
+  const fresh = withoutBaseSkills(await deps.pullSkills(serverUrl, jwt));
+  assertSkillsPullAuthorized(fresh);
+  assertSyncEnvironment(fresh, pullResponse);
+  Object.assign(pullResponse, fresh);
+  let needsRefresh = false;
   let deactivated = 0;
   for (const [skillId, { skillName, agents }] of agentsBySkill) {
-    const latest = latestSkillsById.get(skillId);
-    if (!latest) {
-      continue;
-    }
-    const nextTargets = { ...normalizeAgentTargets(latest.agent_targets) };
-    for (const agent of agents) {
-      nextTargets[agent] = false;
-    }
+    const skill = pullResponse.skills.find((item) => item.id === skillId);
+    const previous = previousState.skills[skillName];
+    if (!skill) continue;
+    const native = isNativeSkill(skill);
+    if (native) {
+      if (!skill.native_settings || previous?.nativeSettingsRevision !== skill.native_settings.revision) continue;
+    } else if (!skill.updated_at || previous?.cloudUpdatedAt !== skill.updated_at) continue;
+    const patch = Object.fromEntries([...agents].map((agent) => [agent, false]));
     try {
-      await deps.updateAgentTargets(serverUrl, jwt, skillId, nextTargets);
-      // Mutate the in-memory pull response so the symlink passes below see the link as undesired.
-      const inMemory = inMemoryById.get(skillId);
-      if (inMemory) {
-        inMemory.agent_targets = nextTargets;
+      const saved = await deps.updateAgentTargets(serverUrl, jwt, skillId, patch,
+        native ? undefined : skill.updated_at, native ? { reference: skill.native_reference!, settingsRevision: skill.native_settings!.revision } : undefined);
+      if (saved.success !== true || !saved.updated_at?.trim()
+        || (!native && saved.updated_at === skill.updated_at)
+        || !['notis', 'claude_code', 'cursor', 'codex'].every((agent) =>
+          typeof saved.agent_targets?.[agent as keyof AgentTargets] === 'boolean')
+        || ![...agents].every((agent) => saved.agent_targets[agent] === false)) {
+        throw new Error('Assignment update did not return a verified saved revision');
       }
+      skill.agent_targets = saved.agent_targets;
+      skill.updated_at = saved.updated_at;
+      if (native) needsRefresh = true;
       deactivated += agents.size;
     } catch (error) {
-      console.warn(
-        `[skill-sync] Failed to deactivate "${skillName}" for ${[...agents].join(", ")} ` +
-          `after local symlink deletion:`,
-        error,
-      );
+      needsRefresh = true;
+      failures.push({ name: skillName, error: 'Could not save the local agent removal; refreshed saved assignments' });
+      console.warn(`[skill-sync] Assignment changed or could not be saved for "${skillName}"; refreshing before reconciliation.`, error);
     }
   }
+  if (needsRefresh) {
+    const refreshed = withoutBaseSkills(await deps.pullSkills(serverUrl, jwt));
+    assertSkillsPullAuthorized(refreshed);
+    assertSyncEnvironment(refreshed, pullResponse);
+    Object.assign(pullResponse, refreshed);
+  }
   return deactivated;
 }
 
@@ -487,9 +770,11 @@ export async function runSkillSync(
   dependencies: Partial<RunSkillSyncDependencies> = {},
   options: RunSkillSyncOptions = {},
 ): Promise<RunSkillSyncResult> {
+  const linkAgentFolders = options.linkAgentFolders !== false;
   const deps = {
     ...DEFAULT_RUN_SKILL_SYNC_DEPS,
     ...dependencies,
+    ...(linkAgentFolders ? {} : MIRROR_ONLY_DEPS),
   };
   const syncSettings: SyncSettings = await deps.fetchSyncSettings(
     serverUrl,
@@ -506,11 +791,13 @@ export async function runSkillSync(
       "Cannot sync skills without a server-verified account identity.",
     );
   }
-  const syncPaths = getSkillSyncPathsForUser(syncUserId);
-  const foreignLinksRemoved = await deps.removeForeignAccountSymlinks(
-    syncPaths.skillsDir,
-  );
+  const syncPaths = getSkillSyncPathsForUser(syncUserId, undefined, syncSettings.sync_namespace, options.syncHome);
   if (options.honorSyncEnabled !== false && !syncSettings.sync_enabled) {
+    // Disabled sync intentionally performs no pull. Only the authenticated
+    // settings scope may remove foreign links; account mirrors stay untouched.
+    const foreignLinksRemoved = await deps.removeForeignAccountSymlinks(
+      syncPaths.skillsDir, isolatedLinkOptions(syncPaths),
+    );
     return {
       syncEnabled: false,
       pushed: 0,
@@ -528,6 +815,13 @@ export async function runSkillSync(
 
   let pullResponse = withoutBaseSkills(await deps.pullSkills(serverUrl, jwt));
   assertSkillsPullAuthorized(pullResponse);
+  assertSyncEnvironment(pullResponse, syncSettings);
+  const foreignLinksRemoved = await deps.removeForeignAccountSymlinks(
+    syncPaths.skillsDir, isolatedLinkOptions(syncPaths),
+  );
+  if (linkAgentFolders && !syncPaths.isolatedNamespace) {
+    await forgetOtherAccountsAgentLinks(syncPaths);
+  }
 
   const cloudCuratedSkillNames = new Set(
     pullResponse.skills
@@ -535,56 +829,68 @@ export async function runSkillSync(
       .map((skill) => skill.name),
   );
   const protectedSkillNames = new Set([...cloudCuratedSkillNames, ...BASE_SKILL_NAMES]);
+  const scopedState = withoutBaseSkillState(await deps.readSyncState(syncPaths));
+  const assignmentFailures: SkillSyncFailure[] = [];
+  // A mirror-only sync has no links by design, so none of them is missing.
+  const deactivated = linkAgentFolders && !syncPaths.isolatedNamespace
+    && syncSettings.agent_targets_conditional_updates === true
+    ? await deactivateDeletedAgentSkills(
+        serverUrl, jwt, pullResponse, scopedState, scopedState, syncPaths.skillsDir, deps, assignmentFailures, isolatedLinkOptions(syncPaths),
+      )
+    : 0;
+  assertSyncEnvironment(pullResponse, syncSettings);
   const authUserId = decodeJwtSubject(jwt);
   let previousAuthState: NotisSyncState | null = null;
-  if (authUserId && authUserId !== syncUserId) {
-    const previousAuthPaths = getSkillSyncPathsForUser(authUserId);
+  if (!syncPaths.isolatedNamespace && authUserId && authUserId !== syncUserId) {
+    const previousAuthPaths = getSkillSyncPathsForUser(authUserId, undefined, undefined, options.syncHome);
     previousAuthState = await deps.readSyncState(previousAuthPaths);
     await deps.gatherTopLevelLocalSkills(syncPaths, {
       sourceRoots: [{ label: "previous-auth-scope", root: previousAuthPaths.skillsDir }],
       protectedSkillNames,
     });
   }
-  await deps.gatherTopLevelLocalSkills(syncPaths, {
-    protectedSkillNames,
-  });
+  if (linkAgentFolders && !syncPaths.isolatedNamespace) {
+    // Skills found loose in the agent folders belong to the account linking them.
+    await deps.gatherTopLevelLocalSkills(syncPaths, { protectedSkillNames });
+  }
   const localSkills = (await deps.scanLocalSkills(syncPaths))
     .filter((skill) => !BASE_SKILL_NAMES.has(skill.name));
-  const scopedState = withoutBaseSkillState(await deps.readSyncState(syncPaths));
   const previousState = withoutBaseSkillState(applyLegacyFirstRunState(
     localSkills,
     scopedState,
-    isEmptySyncState(scopedState)
+    !syncPaths.isolatedNamespace && isEmptySyncState(scopedState)
       ? (!previousAuthState || isEmptySyncState(previousAuthState)
           ? await deps.readLegacySyncState(syncPaths)
           : previousAuthState)
       : null,
   ));
-  // Honor locally-deleted per-agent symlinks as deactivations before reconciling, otherwise the
-  // first syncSymlinks pass would recreate the link the user just deleted.
-  const deactivated = await deactivateDeletedAgentSkills(
-    serverUrl,
-    jwt,
-    pullResponse,
-    previousState,
-    scopedState,
-    syncPaths.skillsDir,
-    deps,
-  );
-  await deps.syncSymlinks(
+  pullResponse = bindNativeFolders(pullResponse, localSkills, previousState);
+  const gatheredSymlinkResult = await deps.syncSymlinks(
     buildLocalSymlinkCandidates(pullResponse, localSkills, previousState),
     syncPaths.skillsDir,
+    isolatedLinkOptions(syncPaths),
   );
   const pushCandidates = getPushCandidates(
     localSkills,
     previousState,
     cloudCuratedSkillNames,
     new Set(pullResponse.skills.map((skill) => skill.name)),
+    pullResponse.skills,
   );
 
   const failedPushes: SkillSyncFailure[] = [];
+  const acknowledgedNative = new Map<string, string>();
+  let writeLocalSkills = localSkills;
   if (pushCandidates.length > 0) {
     const pushResult = await deps.pushChangedSkills(serverUrl, jwt, pushCandidates);
+    for (const result of pushResult.skills || []) {
+      const saved = result as { id?: string; native_reference?: unknown };
+      const candidate = pushCandidates.find(local => local.nativeReference && local.cloudId === saved.id);
+      if (candidate && saved.native_reference) {
+        checkedNativeReference(saved.native_reference, candidate.cloudId);
+        acknowledgedNative.set(candidate.cloudId!, candidate.folderHash);
+      }
+    }
     if (Array.isArray(pushResult?.failed) && pushResult.failed.length > 0) {
       failedPushes.push(...pushResult.failed);
       console.warn(
@@ -594,6 +900,9 @@ export async function runSkillSync(
     }
     pullResponse = withoutBaseSkills(await deps.pullSkills(serverUrl, jwt));
     assertSkillsPullAuthorized(pullResponse);
+    assertSyncEnvironment(pullResponse, syncSettings);
+    writeLocalSkills = (await deps.scanLocalSkills(syncPaths)).filter(skill => !BASE_SKILL_NAMES.has(skill.name));
+    pullResponse = bindNativeFolders(pullResponse, writeLocalSkills, previousState);
   }
 
   // Delete phase: remove skills that were previously synced but are no longer in the cloud
@@ -601,18 +910,31 @@ export async function runSkillSync(
   let deleted = 0;
   for (const skillName of Object.keys(previousState.skills)) {
     if (!cloudSkillNames.has(skillName)) {
+      const previous = previousState.skills[skillName];
+      if (previous.nativeReference || previous.nativeUnavailable
+          || pullResponse.skills.some(skill => isNativeSkill(skill) && skill.id === previous.cloudId)) {
+        await deps.removeAllSymlinksForSkill(skillName, syncPaths.skillsDir, isolatedLinkOptions(syncPaths));
+        continue;
+      }
       await deps.deleteLocalSkill(skillName, syncPaths);
-      await deps.removeAllSymlinksForSkill(skillName, syncPaths.skillsDir);
+      await deps.removeAllSymlinksForSkill(skillName, syncPaths.skillsDir, isolatedLinkOptions(syncPaths));
       deleted += 1;
     }
   }
 
+  const failedDownloads: SkillSyncFailure[] = [];
+  const writtenSkillNames = new Set<string>();
+  const appliedFilesByName: Record<string, string[]> = {};
   const downloaded = await writePulledSkillsToScopedMirror(
     pullResponse,
-    localSkills,
+    writeLocalSkills,
     previousState,
     syncPaths,
     deps,
+    failedDownloads,
+    writtenSkillNames,
+    appliedFilesByName,
+    acknowledgedNative,
   );
 
   const finalLocalSkills = (await deps.scanLocalSkills(syncPaths))
@@ -620,11 +942,23 @@ export async function runSkillSync(
   const symlinkResult = await deps.syncSymlinks(
     buildLocalSymlinkCandidates(pullResponse, finalLocalSkills, previousState),
     syncPaths.skillsDir,
+    isolatedLinkOptions(syncPaths),
   );
+  const verifiedLinks = { ...(symlinkResult.verifiedAgentLinks ?? {}) };
+  for (const failure of failedDownloads) delete verifiedLinks[failure.name];
   const lastSyncedAt = pullResponse.last_synced_at || new Date().toISOString();
 
   await deps.writeSyncState(
-    buildSyncState(pullResponse, finalLocalSkills, lastSyncedAt),
+    buildSyncState(
+      pullResponse,
+      finalLocalSkills,
+      lastSyncedAt,
+      verifiedLinks,
+      new Set(failedDownloads.map(item => item.name)),
+      collectAppliedCloudRevisions(pullResponse, previousState, writtenSkillNames),
+      collectAppliedFiles(pullResponse, previousState, appliedFilesByName),
+      previousState,
+    ),
     syncPaths,
   );
 
@@ -635,9 +969,12 @@ export async function runSkillSync(
     downloaded,
     deleted,
     deactivated,
-    linked: symlinkResult.linked,
-    removed: foreignLinksRemoved + symlinkResult.removed,
+    linked: gatheredSymlinkResult.linked + symlinkResult.linked,
+    removed: foreignLinksRemoved + gatheredSymlinkResult.removed + symlinkResult.removed,
     skipped: symlinkResult.skipped,
+    failedLinks: [...assignmentFailures, ...failedDownloads, ...(symlinkResult.failures ?? []).filter(
+      (failure) => !failedDownloads.some((download) => download.name === failure.name),
+    )],
     lastSyncedAt,
     failedPushes,
   };